Name
hw_PostEvent -- post a new event to queue (V5.2)
Synopsis
void hw_PostEvent(int type, APTR userdata);
Function
This function posts a new event to Hollywood's event queue. Prior to Hollywood 6.0 hw_PostEvent() could only be used with event types that had been registered using hw_RegisterEventHandler(). Starting with Hollywood 6.0 hw_PostEvent() supports several new event types. Here is a list:

HWEVT_QUIT:
If you post this event, Hollywood will quit. The user data parameter is unused for this event. Note that posting HWEVT_QUIT will shut down Hollywood as soon as it runs its event handler. To make Hollywood quit immediately, you can set the global quit flag using HWMCP_SETGLOBALQUIT. See hw_MasterControl for details. (V6.0)

HWEVT_CALLFUNCTION:
If you post this event, Hollywood will call the specified function the next time it enters a WaitEvent() or CheckEvent() cycle. You have to pass a pointer to a struct hwEvtCallFunction in the user data parameter. struct hwEvtCallFunction looks like this:

 
struct hwEvtCallFunction
{
    int (*Func)(lua_State *L, APTR userdata);
    APTR UserData;
};

The following members are part of struct hwEvtCallFunction:

Func:
This must be set to the function that you want Hollywood to call. Hollywood will pass a pointer to the lua_State and the user data you specify below to your function.

UserData:
Set this to the user data that Hollywood should pass to your function.

(V6.0)

HWEVT_WAKEUP:
This event can be used to wake up Hollywood from another thread. The user data parameter is unused for this event. (V6.0)

HWEVT_MOUSE:
This event can only be used from plugins that install a display adapter. HWEVT_MOUSE posts a mouse event to Hollywood's event queue. You have to pass a pointer to a struct hwEvtMouse in the user data parameter. struct hwEvtMouse looks like this:

 
struct hwEvtMouse
{
    APTR Handle;
    int X;
    int Y;
    int Button;
    int Down;
    ULONG Flags;
};

The following members are part of struct hwEvtMouse:

Handle:
This must be set to a display handle obtained from OpenDisplay().

X:
This must be set to the mouse cursor's current x position, relative to the upper-left corner of the display.

Y:
This must be set to the mouse cursor's current y position, relative to the upper-left corner of the display.

Button:
This must be set to one of the following predefined constants to define the mouse button that Down member of struct hwEvtMouse is referring to. The following button types are currently defined:

HWMBTYPE_NONE:
Structure member Down is unused.

HWMBTYPE_LEFT:
Structure member Down contains the current state of the left mouse button.

HWMBTYPE_RIGHT:
Structure member Down contains the current state of the right mouse button.

HWMBTYPE_MIDDLE:
Structure member Down contains the current state of the middle mouse button.

Down:
If Button does not equal HWBMTYPE_NONE, this member needs to be set to either True or False depending on whether the corresponding mouse button is currently down or up.

Flags:
Currently unused. Must be 0.

(V6.0)

HWEVT_MOUSEWHEEL:
This event can only be used from plugins that install a display adapter. HWEVT_MOUSEWHEEL posts a mouse wheel event to Hollywood's event queue. You have to pass a pointer to a struct hwEvtMouseWheel in the user data parameter. struct hwEvtMouseWheel looks like this:

 
struct hwEvtMouseWheel
{
    APTR Handle;
    int X;
    int Y;
    ULONG Flags;
};

The following members are part of struct hwEvtMouseWheel:

Handle:
This must be set to a display handle obtained from OpenDisplay().

X:
This must be set to the mouse wheel's x delta movement.

Y:
This must be set to the mouse wheel's y delta movement.

Flags:
Currently unused. Must be 0.

(V8.0)

HWEVT_KEYBOARD:
This event can only be used from plugins that install a display adapter. HWEVT_KEYBOARD posts a keyboard event to Hollywood's event queue. You have to pass a pointer to a struct hwEvtKeyboard in the user data parameter. struct hwEvtKeyboard looks like this:

 
struct hwEvtKeyboard
{
    APTR Handle;
    int ID;
    int Down;
    ULONG Qualifiers;
    ULONG Flags;
};

The following members are part of struct hwEvtKeyboard:

Handle:
This must be set to a display handle obtained from OpenDisplay().

ID:
This must be set to the identifier of the key this event is referring to. This can be either the 8-bit character code of a ISO 8859-1 key or one of the following special keys:

 
HWKEY_CURSOR_UP
HWKEY_CURSOR_DOWN
HWKEY_CURSOR_RIGHT
HWKEY_CURSOR_LEFT
HWKEY_HELP
HWKEY_F1
HWKEY_F2
HWKEY_F3
HWKEY_F4
HWKEY_F5
HWKEY_F6
HWKEY_F7
HWKEY_F8
HWKEY_F9
HWKEY_F10
HWKEY_F11
HWKEY_F12
HWKEY_F13
HWKEY_F14
HWKEY_F15
HWKEY_F16
HWKEY_BACKSPACE
HWKEY_TAB
HWKEY_ENTER
HWKEY_RETURN
HWKEY_ESC
HWKEY_SPACE
HWKEY_DEL
HWKEY_INSERT
HWKEY_HOME
HWKEY_END
HWKEY_PAGEUP
HWKEY_PAGEDOWN
HWKEY_PRINT
HWKEY_PAUSE

Down:
This must be set to either True or False indicating whether the specified key is currently pressed.

Qualifiers:
This must be set to a combination of qualifiers like shift and alt that are currently pressed. See GetQualifiers for a list of available qualifiers. Don't forget that the internal control bit HWKEY_QUAL_MASK must always be set.

Flags:
Currently unused. Must be 0.

Note that HWEVT_KEYBOARD can only be used for ISO 8859-1 characters and control keys. To post a Unicode key to Hollywood's event queue, use HWEVT_VANILLAKEY instead (see below for details). (V6.0)

HWEVT_RAWKEY:
This event can only be used from plugins that install a display adapter. HWEVT_RAWKEY posts a raw keyboard event to Hollywood's event queue. You have to pass a pointer to a struct hwEvtKeyboard in the user data parameter. struct hwEvtKeyboard looks like this:

 
struct hwEvtKeyboard
{
    APTR Handle;
    int ID;
    int Down;
    ULONG Qualifiers;
    ULONG Flags;
};

The following members are part of struct hwEvtKeyboard:

Handle:
This must be set to a display handle obtained from OpenDisplay().

ID:
This must be set to the identifier of the key this event is referring to. This can be one of the HWKEY_XXX keys listed above in HWEVT_KEYBOARD, the ASCII codes A-Z and 0-9 or one of the following special raw keys:

 
HWKEY_NP0
HWKEY_NP1
HWKEY_NP2
HWKEY_NP3
HWKEY_NP4
HWKEY_NP5
HWKEY_NP6
HWKEY_NP7
HWKEY_NP8
HWKEY_NP9
HWKEY_NPMUL
HWKEY_NPADD
HWKEY_NPSUB
HWKEY_NPDEC
HWKEY_NPDIV
HWKEY_LSHIFT
HWKEY_RSHIFT
HWKEY_LALT
HWKEY_RALT
HWKEY_LCOMMAND
HWKEY_RCOMMAND
HWKEY_LCONTROL
HWKEY_RCONTROL

Down:
This must be set to either True or False indicating whether the specified key is currently pressed.

Qualifiers:
This must be set to a combination of qualifiers like shift and alt that are currently pressed. See GetQualifiers for a list of available qualifiers. Don't forget that the internal control bit HWKEY_QUAL_MASK must always be set.

Flags:
Currently unused. Must be 0.

(V7.1)

HWEVT_VANILLAKEY:
This event can only be used from plugins that install a display adapter. HWEVT_VANILLAKEY posts a keyboard event to Hollywood's event queue. In contrast to HWEVT_KEYBOARD, HWEVT_VANILLAKEY must only be used to post printable characters (including the space character). It must not be used for control keys. These should be posted as HWEVT_KEYBOARD and HWEVT_RAWKEY events (see above for details). In contrast to HWEVT_KEYBOARD, HWEVT_VANILLAKEY supports the full Unicode character range. You have to pass a pointer to a struct hwEvtKeyboard in the user data parameter. struct hwEvtKeyboard looks like this:

 
struct hwEvtKeyboard
{
    APTR Handle;
    int ID;
    int Down;
    ULONG Qualifiers;
    ULONG Flags;
};

The following members are part of struct hwEvtKeyboard:

Handle:
This must be set to a display handle obtained from OpenDisplay().

ID:
This must be set to the Unicode character code of the key event you want to post.

Down:
This is ignored for HWEVT_VANILLAKEY.

Qualifiers:
This is ignored for HWEVT_VANILLAKEY.

Flags:
Currently unused. Must be 0.

(V7.0)

HWEVT_CLOSEDISPLAY:
This event can only be used from plugins that install a display adapter. HWEVT_CLOSEDISPLAY posts a close display event to Hollywood's event queue. This event is usually posted when the user presses the window's close widget. You have to pass a pointer to a struct hwEvtCloseDisplay in the user data parameter. struct hwEvtCloseDisplay looks like this:

 
struct hwEvtCloseDisplay
{
    APTR Handle;
    ULONG Flags;
};

The following members are part of struct hwEvtCloseDisplay:

Handle:
This must be set to a display handle obtained from OpenDisplay().

Flags:
Currently unused. Must be 0.

(V6.0)

HWEVT_SIZEDISPLAY:
This event can only be used from plugins that install a display adapter. HWEVT_SIZEDISPLAY posts a size display event to Hollywood's event queue. This event is usually posted when the user changes the size of the window. You have to pass a pointer to a struct hwEvtSizeDisplay in the user data parameter. struct hwEvtSizeDisplay looks like this:

 
struct hwEvtSizeDisplay
{
    APTR Handle;
    int Width;
    int Height;
    ULONG Flags;
};

The following members are part of struct hwEvtSizeDisplay:

Handle:
This must be set to a display handle obtained from OpenDisplay().

Width:
This must be set to the new display width in pixels.

Height:
This must be set to the new display height in pixels.

Flags:
Currently unused. Must be 0.

(V6.0)

HWEVT_MOVEDISPLAY:
This event can only be used from plugins that install a display adapter. HWEVT_MOVEDISPLAY posts a move display event to Hollywood's event queue. This event is usually posted when the user moves the window around. You have to pass a pointer to a struct hwEvtMoveDisplay in the user data parameter. struct hwEvtMoveDisplay looks like this:

 
struct hwEvtMoveDisplay
{
    APTR Handle;
    int X;
    int Y;
    ULONG Flags;
};

The following members are part of struct hwEvtMoveDisplay:

Handle:
This must be set to a display handle obtained from OpenDisplay().

X:
This must be set to the display's new x position in pixels. The position you specify here must be relative to the screen's upper-left corner.

Y:
This must be set to the display's new y position in pixels. The position you specify here must be relative to the screen's upper-left corner.

Flags:
Currently unused. Must be 0.

(V6.0)

HWEVT_SHOWHIDEDISPLAY:
This event can only be used from plugins that install a display adapter. HWEVT_SHOWHIDEDISPLAY posts a show/hide display event to Hollywood's event queue. This event is usually posted when the user minimizes the window or restores it from a minimized state. You have to pass a pointer to a struct hwEvtShowHideDisplay in the user data parameter. struct hwEvtShowHideDisplay looks like this:

 
struct hwEvtShowHideDisplay
{
    APTR Handle;
    int Show;
    ULONG Flags;
};

The following members are part of struct hwEvtShowHideDisplay:

Handle:
This must be set to a display handle obtained from OpenDisplay().

Show:
This must be set to False if the display has been minimized/hidden and True if it has been restored from a minimized/hidden state.

Flags:
Currently unused. Must be 0.

(V6.0)

HWEVT_FOCUSCHANGEDISPLAY:
This event can only be used from plugins that install a display adapter. HWEVT_FOCUSCHANGEDISPLAY posts a focus change display event to Hollywood's event queue. This event is usually posted when the window loses or gets the focus. You have to pass a pointer to a struct hwEvtFocusChangeDisplay in the user data parameter. struct hwEvtFocusChangeDisplay looks like this:

 
struct hwEvtFocusChangeDisplay
{
    APTR Handle;
    int Focus;
    ULONG Flags;
};

The following members are part of struct hwEvtFocusChangeDisplay:

Handle:
This must be set to a display handle obtained from OpenDisplay().

Focus:
This must be set to False if the display has lost the focus and True if it has received the focus.

Flags:
Currently unused. Must be 0.

(V6.0)

HWEVT_DROPFILE:
This event can only be used from plugins that install a display adapter. HWEVT_DROPFILE can be used to post an event to Hollywood's event queue which indicates that files have been dropped on a Hollywood display. You have to pass a pointer to a struct hwEvtDropFile in the user data parameter. struct hwEvtDropFile looks like this:

 
struct hwEvtDropFile
{
    APTR Handle;
    int MouseX;
    int MouseY;
    STRPTR DropFiles;
    ULONG Flags;
};

The following members are part of struct hwEvtDropFile:

Handle:
This must be set to a display handle obtained from OpenDisplay().

MouseX:
This must be set to the x-coordinate (relative to the window's upper-left corner) where the user dropped the file(s).

MouseY:
This must be set to the y-coordinate (relative to the window's upper-left corner) where the user dropped the file(s).

DropFiles:
This must be set to a list of filenames that have been dropped on the window. The individual filenames need to contain fully qualified paths and must be separated from one another by a single NULL terminator byte whereas the complete list is terminated by two NULL terminator bytes to signal the list end to Hollywood. Warning: You must use hw_TrackedAlloc() to allocate this list and you must not free it. Hollywood will take care of freeing it!

Flags:
Currently unused. Must be 0.

(V7.0)

HWEVT_MENUITEM:
This event can only be used from plugins that install a menu adapter. It must be sent to Hollywood's event queue whenever the user selects an item from the menu bar. You have to pass a pointer to a struct hwEvtMenuItem in the user data parameter. struct hwEvtMenuItem looks like this:

 
struct hwEvtMenuItem
{
    APTR Handle;
    APTR Item;
    ULONG Flags;
};

The following members are part of struct hwEvtMenuItem:

Handle:
This must be set to a display handle obtained from OpenDisplay().

Item:
This must be set to the struct hwMenuTreeInfo pointer of the menu item that has been selected.

Flags:
If the menu is a toggle or radio item, you must set the HWMENUFLAGS_SELECTED flag here whenever the item is selected. Otherwise set this to 0.

(V9.0)

HWEVT_USERMESSAGE:
This event can only be used from plugins that install an IPC adapter. See IPC adapter overview for details. It must be sent to Hollywood's event queue whenever your plugin receives an IPC message that has been sent using SendIPCMessage(). You have to pass a pointer to a struct hwEvtUserMessage in the user data parameter. struct hwEvtUserMessage looks like this:

 
struct hwEvtUserMessage
{
    APTR Data;
    int DataSize;
    ULONG Flags;
};

The following members are part of struct hwEvtUserMessage:

Data:
The raw message data. Note that this is not limited to text but can also contain binary data.

DataSize:
The size of the data in the Data member, in bytes.

Flags:
Currently unused. Must be 0.

(V9.0)

HWEVT_TRAYICON:
Display adapters supporting custom tray icons by setting the HWEXT_DISPLAYADAPTER_TRAYICON extension bit must post this event whenever the user clicks on the tray icon. The user data parameter is unused for this event. (V9.0)

Alternatively, you can also specify a custom event type that you have registered through hw_RegisterEventHandler() in parameter 1. In that case, the user data pointer you pass in parameter 2 is directly forwarded to your custom event's handler function. See hw_RegisterEventHandler for details.

Starting with Hollywood 6.0 this function has an extended version named hw_PostEventEx(). In contrast to hw_PostEvent(), the extended version will tell you whether the event was successfully posted. See hw_PostEventEx for details.

This function is thread-safe.

Designer compatibility
Unsupported

Inputs
type
type of event to post (see above)
userdata
event-dependent data (see above)

Show TOC