1  .TH MiniLibX 3 "September 19, 2002"
  2  .SH NAME
  3  MiniLibX - Handle events
  4  .SH SYNOPSYS
  5  
  6  .nf
  7  .I int
  8  .fi
  9  .B mlx_loop
 10  (
 11  .I void *mlx_ptr
 12  );
 13  
 14  .nf
 15  .I int
 16  .fi
 17  .B mlx_key_hook
 18  (
 19  .I void *win_ptr, int (*funct_ptr)(), void *param
 20  );
 21  
 22  .nf
 23  .I int
 24  .fi
 25  .B mlx_mouse_hook
 26  (
 27  .I void *win_ptr, int (*funct_ptr)(), void *param
 28  );
 29  
 30  .nf
 31  .I int
 32  .fi
 33  .B mlx_expose_hook
 34  (
 35  .I void *win_ptr, int (*funct_ptr)(), void *param
 36  );
 37  
 38  .nf
 39  .I int
 40  .fi
 41  .B mlx_loop_hook
 42  (
 43  .I void *mlx_ptr, int (*funct_ptr)(), void *param
 44  );
 45  
 46  .SH EVENTS
 47  
 48  The graphical system is bi-directionnal. On one hand, the program sends orders to
 49  the screen to display pixels, images, and so on. On the other hand,
 50  it can get information from the keyboard and mouse associated to
 51  the screen. To do so, the program receives "events" from the keyboard or the
 52  mouse.
 53  
 54  .SH DESCRIPTION
 55  
 56  To receive events, you must use
 57  .B mlx_loop
 58  (). This function never returns. It is an infinite loop that waits for
 59  an event, and then calls a user-defined function associated with this event.
 60  A single parameter is needed, the connection identifier
 61  .I mlx_ptr
 62  (see the
 63  .B mlx manual).
 64  
 65  You can assign different functions to the three following events:
 66  .br
 67  - A key is pressed
 68  .br
 69  - The mouse button is pressed
 70  .br
 71  - A part of the window should be re-drawn
 72  (this is called an "expose" event, and it is your program's job to handle it in the
 73  Unix/Linux X11 environment, but at the opposite it never happens on MacOS).
 74  .br
 75  
 76  Each window can define a different function for the same event.
 77  
 78  The three functions
 79  .B mlx_key_hook
 80  (),
 81  .B mlx_mouse_hook
 82  () and
 83  .B mlx_expose_hook
 84  () work exactly the same way.
 85  .I funct_ptr
 86  is a pointer to the function you want to be called
 87  when an event occurs. This assignment is specific to the window defined by the
 88  .I win_ptr
 89  identifier. The
 90  .I param
 91  adress will be passed to the function everytime it is called, and should be
 92  used to store the parameters it might need.
 93  
 94  The syntax for the
 95  .B mlx_loop_hook
 96  () function is identical to the previous ones, but the given function will be
 97  called when no event occurs.
 98  
 99  When it catches an event, the MiniLibX calls the corresponding function
100  with fixed parameters:
101  .nf
102  
103    expose_hook(void *param);
104    key_hook(int keycode, void *param);
105    mouse_hook(int button, int x, int y, void *param);
106    loop_hook(void *param);
107  
108  .fi
109  These function names are arbitrary. They here are used to distinguish
110  parameters according to the event. These functions are NOT part of the
111  MiniLibX.
112  
113  .I param
114  is the address specified in the mlx_*_hook calls. This address is never
115  used nor modified by the MiniLibX. On key and mouse events, additional
116  information is passed:
117  .I keycode
118  tells you which key is pressed (with X11, look for the include file "keysymdef.h",
119  with MacOS, just try :) ),
120  (
121  .I x
122  ,
123  .I y
124  ) are the coordinates of the mouse click in the window, and
125  .I button
126  tells you which mouse button was pressed.
127  
128  .SH GOING FURTHER WITH EVENTS
129  The MiniLibX provides a much generic access to other available events. The
130  .I mlx.h
131  include define
132  .B mlx_hook()
133  in the same manner mlx_*_hook functions work. The event and mask values
134  will be taken from the X11 include file "X.h". Some MacOS events are mapped
135  to these values, when it makes sense, and the mask is not used in MacOS.
136  
137  See source code of the MiniLibX to find out how it will
138  call your own function for a specific event.
139  
140  .SH SEE ALSO
141  mlx(3), mlx_new_window(3), mlx_pixel_put(3), mlx_new_image(3)
142  
143  .SH AUTHOR
144  Copyright ol@ - 2002-2019 - Olivier Crouzet