int id = hw_RegisterEventHandlerEx(STRPTR name, int type, APTR data);

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 the type of the event you would like to register. The following event types are currently recognized:

HWEVTHANDLER_STANDARD:

This registers a standard event. Standard events are the most basic event types available and they are also the ones that are registered by the hw_RegisterEventHandler() function. For standard events, the data parameter must be set to a pointer to a struct hwStandardEventHandler which looks like this:

struct hwStandardEventHandler { void (*EvtFunc)(lua_State *L, int type, APTR userdata); };

The following items are members of this structure:

EvtFunc:

This member must be set to a function pointer which will be called whenever Hollywood is about to run the callback that the user has installed for the event using InstallEventHandler(). The function you specify here 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 write 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().

HWEVTHANDLER_STANDARD is identical to the event handler registered by hw_RegisterEventHandler() so you might also use the latter to register standard events.

HWEVTHANDLER_CUSTOM:

This registers a custom event. Custom events differ from standard events in the way that your plugin is given more fine-tuned control about the way the events are handled. In contrast to standard events, Hollywood will call your plugin also after it has run a user callback for this event and it also supports event destructors. For custom events, the data parameter must be set to a pointer to a struct hwCustomEventHandler which looks like this:

struct hwCustomEventHandler { int (*PushData)(lua_State *L, int type, APTR udata); void (*PostCall)(lua_State *L, int type, APTR udata); void (*FreeEvent)(lua_State *L, int type, APTR udata); };

The following items are members of this structure:

PushData:

This member must be set to a function pointer which will be called whenever Hollywood is about to run the callback that the user has installed for the event using InstallEventHandler(). The function you specify here may then push additional values on the stack. Note that in comparison to events of type HWEVTHANDLER_STANDARD, Hollywood won't push any values on the stack for custom events. There will also be no table on the stack as it is the case with HWEVTHANDLER_STANDARD. Instead, your plugin is given complete control over what the stack should look like when Hollywood runs the user callback. For consistency reasons, however, it is advised that you push a table, set the Action field to the name of your event and then store all additional values inside that table. You should only deviate from this standard if you have very good reason to do so.

PostCall:

This member must be set to a function that should be called immediately after Hollywood has finished running the user callback registered for this event type.

FreeEvent:

This member must be set to a function that should act as a destructor for this event type. Hollywood will call this function whenever it has to free an event of your type.

Note that you must provide functions for all of the structure members above, even if they don't do anything. No structure member must be NULL. The user data that is passed to all the functions above as the third parameter is the same pointer that you provided in the call to hw_PostEvent() or hw_PostEventEx() when you posted the event.

name

name for the new event type (see above for limitations in the event name format)

type

desired event type (see above for supported types)

data

event type dependent data (see above for details)

id

identifier of the new event handler or 0 on error