int id = hw_RegisterEventHandler(STRPTR name, void (*evtfunc) (lua_State *L, int type, APTR userdata));
InstallEventHandler()
. Whenever you want this
event handler to trigger, you have to post an event to Hollywood's event
queue using the hw_PostEvent() or hw_PostEventEx()
function.
You have to specify a name for the new event type. This name must follow the
conventions for Hollywood variables because the user will need to use this
name when installing a handler for this event type using Hollywood's InstallEventHandler()
function. Thus, the name you specify here must not clash with any existing
event handler names and it must not use any spaces or special characters.
It has to start with a letter from the English alphabet.
In parameter 2, you need to pass a function pointer to hw_RegisterEventHandler()
.
This function will be called whenever Hollywood is about to run the callback
that the user has installed for the event using InstallEventHandler()
. Your
function may then push additional values on the stack. When evtfunc
is called,
Hollywood will have already pushed a table to the stack and it will have set the
Action
field of that table to the name of your event for consistency with
inbuilt Hollywood events. All other values that your event handler may want
to provide to the user's event callback should also be stored in that table. Note
that you must implement this function even if you do not want to push any additional values on the stack.
evtfunc
must not be NULL
. The user data that is passed to evtfunc
as the third
parameter is the same pointer that you provided in the call to hw_PostEvent()
or hw_PostEventEx().
This function is also available as an extended version. See hw_RegisterEventHandlerEx for details.