WinDom: Event Library

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

# Event Library
[Reference documentation]

Catch and handle GEM events. More...

## Data Structures
struct | EVNTvar
| Parametrization of mt_EvntWindom() calling. More...
struct | EVNTvar
| Parametrization of mt_EvntWindom() calling. More...
## Functions
int | mt_EvntWindom (APPvar *app, int __evnt)
| handle AES events.
int | mt_EvntWindomBuff (APPvar *app, int __evnt, short buff[8])
int | mt_EvntAdd (APPvar *app, WINDOW *win, int msg, func_evnt proc, int mode)
| add a function to a GEM event without data
int | mt_EvntAttach (APPvar *app, WINDOW *win, int msg, func_evnt proc)
| bind a function to a GEM event without data.
int | mt_EvntDataAdd (APPvar *app, WINDOW *win, int msg, func_evntdata proc, void *data, int mode)
| Add a callback function to event and its data to a window or to the application.
int | mt_EvntDataAttach (APPvar *app, WINDOW *win, int msg, func_evntdata proc, void *data)
| bind a function to a GEM event.
int | mt_EvntDelete (APPvar *app, WINDOW *win, int msg)
| Delete an event.
void * | mt_EvntFind (APPvar *app, WINDOW *win, int msg)
| find the first callback function bound to an event.
int | mt_EvntExec (APPvar *app, WINDOW *win, short buff[8])
| Execute all functions bound to an event.
void | mt_EvntClear (APPvar *app, WINDOW *win)
| removes all defined events of a window or of the application.
int | mt_EvntRemove (APPvar *app, WINDOW *win, int msg, void *proc)
| Remove one callback function bound to an event.
void | mt_EvntDisable (APPvar *app, WINDOW *win, int msg)
| Disable all callback functions bound to an event.
void | mt_EvntEnable (APPvar *app, WINDOW *win, int msg)
| Enable all callback functions bound to an event.
void | mt_EvntRedraw (APPvar *app, WINDOW *win)
| execute functions bound to WM_REDRAW event.
void | mt_EvntRedrawGrect (APPvar *app, WINDOW *win, GRECT *work)
| execute functions bound to WM_REDRAW event.

## Detailed Description

Catch and handle GEM events.

## Function Documentation

int mt_EvntAdd | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg,
|  | func_evnt | proc,
|  | int | mode
| ) |

| add a function to a GEM event without data This function is just a call to mt_EvntDataAdd() with parameter data set to NULL.

int mt_EvntAttach | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg,
|  | func_evnt | proc
| ) |

| bind a function to a GEM event without data. This function is just a call to mt_EvntDataAttach() with parameter data set to NULL.

void mt_EvntClear | ( | APPvar * | app,
|  | WINDOW * | win
| ) |

  | removes all defined events of a window or of the application. Parameters:
  | app | application descriptor,
  | win | window descriptor or NULL.
mt_EvntClear() removes all events defined to a window or to the application (if win is NULL). Actually, this function is called by mt_WindDelete() or mt_ApplExit() to release allocated memory. See also: mt_EvntDelete(), mt_EvntRemove().

int mt_EvntDataAdd | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg,
|  | func_evntdata | proc,
|  | void * | data,
|  | int | mode
| ) |

  | Add a callback function to event and its data to a window or to the application. Parameters:
  | app | application descriptor
  | win,msg,proc,data | see manual of mt_EvntDataAttach()
  | mode | way to add the callback function : EV_TOP : callback function is added in top position (will be called in first) EV_BOT : callback function is added in bottom position (will be called in last)
Returns: 0 or negative error code. This function is very similar to mt_EvntDataAttach(). The only difference is the callback function is added in a list of callback instead of remplacing previous callback function (or list of callback function) as mt_EvntDataAttach() acts. See also: mt_EvntAdd(), mt_EvntDataAttach().

int mt_EvntDataAttach | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg,
|  | func_evntdata | proc,
|  | void * | data
| ) |

  | bind a function to a GEM event. Parameters:
  | app | application descriptor,
  | win | window descriptor or NULL if event address the application not a window,
  | msg | event to bind, possible are : WM_XTIMER : timer event (MU_TIMER), WM_XBUTTON : button event (MU_BUTTON), WM_XKEYBD : keyboard event (MU_KEYBD), WM_XM1 : MU_M1 event, WM_XM2 : MU_M2 event, other value : any GEM event mesag (MU_MESAG), the value specifie the number mesag (e.g. WM_CLOSED).
  | proc | pointer to the callback function.
  | data | data to pass as argument of callback function.
Returns: 0 or a negative code error. mt_EvntDataAttach() links a GEM event to a function (such a function is called a callback function). A GEM event is a button event, keyboard event, a mesage event too. An event can be attached to a window or more, to the application or both window and application. If an event is previously defined, a new call of mt_EvntAttach() on this event removes the old event link. To cumulate several callbacks to a same event, use mt_EvntAdd(). Of course, that works only if mt_EvntWindom() is invoked (instead of evnt_multi()) to handle GEM event. A callback function has the following prototype :
     void function( WINDOW *win, short buf[8], void *data, APPvar *app);
where app is the application descriptor and win is the descriptor of the targeted window or NULL if the event addresses the application. data is the pointer provided by EvntDataAttach(), and buf[] contain the AES message catched that triggered the invoking of this callback function. Here some examples of binding :
        // Define a global button event:
        EvntDataAttach( NULL, WM_XBUTTON, AppButton);

        // Define the button event of a window:
        EvntDataAttach( win, WM_XBUTTON, WinButton);

        // Define the window destroy event:
        EvntDataAttach( win, WM_DESTROY, WinDestroy);

        // Define a global event message (the application shutdown):
        EvntDataAttach( NULL, AP_TERM, ApTerm);
See also: mt_EvntDataAdd(), mt_EvntAttach(), mt_EvntDelete(), EvntWindom(). Todo: A suggestion : mt_EvntAttach() appears to be useless. One could remove mt_EvntAttach() then rename mt_EvntDataAttach() in mt_EvntAttach(). Same remark addressing mt_EvntAdd() and mt_EvntDataAdd().

int mt_EvntDelete | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg
| ) |

  | Delete an event. Parameters:
  | app | application descriptor,
  | win | window descriptor or NULL (application targeted),
  | msg | event to delete,
Returns: 0 or negative error code. EvntDelete() removes all callback functions bound to an event. See also: EvntDataAttach()

void mt_EvntDisable | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg
| ) |

  | Disable all callback functions bound to an event. Parameters:
  | app | application descriptor,
  | win | window descriptor or NULL (if application is targeted)
  | msg | event to disable.
mt_EvntDisable() disables an event : callback functions bound to this event will not be executed (by mt_EvntExec() then by mt_EvntWindom()). This function is used to disabled temporally an event. See also: mt_EvntExec(), mt_EventEnable().

void mt_EvntEnable | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg
| ) |

  | Enable all callback functions bound to an event. Parameters:
  | app | application descriptor,
  | win | targeted window or NULL (if application is targeted)
  | msg | event to enable.
mt_EvntEnable() enables an event previously disabled by mt_EvntDisable(). See also: mt_EvntExec(), mt_EventDisable().

int mt_EvntExec | ( | APPvar * | app,
|  | WINDOW * | w,
|  | short | buff[8]
| ) |

  | Execute all functions bound to an event. Parameters:
  | app | application descriptor,
  | w | window descriptor or NULL (if application is targeted),
  | buff | event to execute,
Returns: TRUE if an event function is found and correctly executed. EvntExec() finds all event functions bound to the event msg and executes them if found. Important: WM_REDRAW cannot be executed by EvntExec() because it should be call several time on each rectangle of the AES redraw rectangle list. We have to used EvntRedraw for that. User is advised to execute an event mesag it is better to use mt_ApplWrite() instead of mt_EvntExec(). With mt_ApplWrite() we give the control to AES before to execute. With EvntExec(), events are executed directly. Some actions, as closing a window for example, can confuses AES if they are executed directly. And give the control to AES increases the multasking performance. Actually, mt_EvntExec() is used by mt_EvntWindom() to execute callback functions when an event occurs. See also: mt_EvntDisable(), mt_EvntEnable() Bug: With the use of the flag EVM_IN_USE, problems may appear if this function is re-entrant (f.e. if one of these find->proc callback function calls EvntExec(). Normally, this doesn't happen.

void* mt_EvntFind | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg
| ) |

  | find the first callback function bound to an event. Parameters:
  | app | application descriptor,
  | win | window descriptor or NULL (if application is addressed)
  | msg | event to find.
Returns: callback function address or NULL. mt_EvntFind() returns the address of the first callback function bound to an event. If the event is unbound, mt_EvntFind() returns NULL. Currently, it is not possible to have the list of function bound to a message. This function is just used to know if a message is defined.

void mt_EvntRedraw | ( | APPvar * | app,
|  | WINDOW * | win
| ) |

  | execute functions bound to WM_REDRAW event. Parameters:
  | app | application descriptor,
  | win | targeted window of NULL (if application is targeted)
WM_REDRAW is a special event. When this event occurs, functions bound to this message are executed several times: one time for each rectangle of the AES rectangle list. Off course, EvntWindow() handles that and it is transparent when we write a redraw event function. The consequence is a redraw function cannot be executed directly with EvntExec(). It is the goal of EvntRedraw(). See also: mt_EvntExec(), mt_snd_rdw(). Todo: mt_EvntRedraw() could be executed directly by mt_EvntExec().

void mt_EvntRedrawGrect | ( | APPvar * | app,
|  | WINDOW * | win,
|  | GRECT * | rdraw
| ) |

  | execute functions bound to WM_REDRAW event. Parameters:
  | app | application descriptor,
  | win | targeted window of NULL (if application is targeted)
  | rdraw | an area to redraw
This function is similar to mt_EvntRedraw(), except that you can specify the area to be redrawn (by using mt_EvntRedraw(), the whole work area is redrawn). See also: mt_EvntRedraw()

int mt_EvntRemove | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg,
|  | void * | proc
| ) |

  | Remove one callback function bound to an event. Parameters:
  | app | application descriptor,
  | win | window descriptor (or NULL),
  | msg | event to find,
  | proc | callback function to remove,
Returns: TRUE if the callback function is found and removed. mt_EvntRemove() removes one and only one callback function bound to an event. It is different to mt_EvntDelete() which removes all functions bound to an same event. Because a same function can be bound to different event, you should give an event (msg parameter) and, of course, the address of function to delete (proc parameter. See also: mt_EvntDelete(), mt_EvntClear().

int mt_EvntWindom | ( | APPvar * | app,
|  | int | evntflag
| ) |

  | handle AES events. Parameters:
  | app | application descriptor,
  | evntflag | bit field of event to handle : MU_MESAG : wait until a mesag arrives MU_TIMER : wait during a fixed time MU_BUTTON : wait for a mouse button event MU_KEYBD : wait for a keyboard event MU_M1, MU_M2 : wait for a motion mouse event
Returns: bit field of occured events. This function is the heart of WinDom. It replaces the AES evnt_multi() function (the EvntMulti() is already used by the Pure C AES bindings). EvntWindom() is a little bit complex: it calls the evnt_multi() function, it handles the color palette depending of the topped window or the desktop palette if no topped window, it calls the good event function depending the event occured (MU_MESAG, MU_BUTTON, ...), window menu window, window toolbar, keyboard shortcuts, specific WinDom features are handled. If needed, some AES4 special features (iconfications, bottom windows, untoppable and modal windows) are emulated, some new messages are eventually sent. As evnt_multi(), mt_EvntWindom() can be parametrized. The parametrization is performed by the variable app->evnt (see EVNTvar structure). Some events return additional informations. These informations are stored in the app->evnt variable too. See also: mt_EvntAttach(), mt_EvntAdd(), List of WinDom events, EVNTvar structure

int mt_EvntWindomBuff | ( | APPvar * | app,
|  | int | __evnt,
|  | short | buff[8]
| ) |