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]
) 
 

Generated on Thu Jun 22 11:45:28 2006 for WinDom by  doxygen 1.4.6