Name
InstallEventHandler -- install/remove an event handler (V2.0)
Synopsis
InstallEventHandler(table[, userdata])
Function
You can use this function to install your own event handlers for standard events. You have to pass a table to this function, that tells Hollywood which event handlers you want to install or remove. To install a new handler you need to initialize the corresponding table field with your own function. If you want to remove an event handler, set the corresponding table field to 0.

The following table fields are recognized by this function:

OnKeyDown:
The function you specify here will be called each time the user presses a control key, a numerical key, or an English alphabetical key. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnKeyDown.
Key:
Will be set to the key which has been pressed.
ID:
Will be set to the identifier of the display that has received this key stroke.

Note that officially, OnKeyDown only supports control keys, numerical keys and English alphabet keys. To listen to non-English keys, use the VanillaKey event handler instead. VanillaKey supports the complete Unicode range of keys. Note that OnKeyDown supports certain non-English keys on some platforms but this is unofficial behaviour and you shouldn't rely on it. If you need to listen to modifier keys like shift, alt, control, etc. use the OnRawKeyDown event handler instead (see below).

OnKeyUp:
The function you specify here will be called each time the user releases a control key, a numerical key, or an English alphabetical key. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnKeyUp.
Key:
Will be set to the key which has been released.
ID:
Will be set to the identifier of the display that has received this key release.

Note that officially, OnKeyUp only supports control keys, numerical keys and English alphabet keys. To listen to non-English keys, use the VanillaKey event handler instead. VanillaKey supports the complete Unicode range of keys. Note that OnKeyUp supports certain non-English keys on some platforms but this is unofficial behaviour and you shouldn't rely on it. If you need to listen to modifier keys like shift, alt, control, etc. use the OnRawKeyUp event handler instead (see below).

OnRawKeyDown:
This event handler can be used to listen to raw key events. The difference between raw key events and normal key events is that raw key events always deliver the raw key without applying any potential modifier keys like shift, alt, control, etc. that might be down as well. For example, when pressing the shift key and the "1" key on an English keyboard, OnKeyDown will report that the "!" key has been pressed whereas OnRawKeyDown will report two key events: It will first report that the shift key has been pressed and then it will report that the "1" key has been pressed. In contrast to OnKeyDown, OnRawKeyDown will never combine the shift and the "1" key into the "!" key. Instead, you will get the raw key events. Also, OnKeyDown will never be triggered if a modifier key like shift, alt, control, etc. has been pressed on its own. OnRawKeyDown, however, will also be triggered when the user presses a modifier key. Thus, OnRawKeyDown is very useful for listening to modifier keys or combinations of character keys and modifier keys, e.g. you can use this event handler to find out if the right alt key and a character key are both down. The function you pass to this event handler will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnRawKeyDown.
Key:
Will be set to the key which has been pressed. See Raw keys for a list of raw keys supported by Hollywood.
Modifiers:
Will be set to a combination of modifier keys that are currently down. The following modifier key flags may be set:
#MODLSHIFT
Left shift key
#MODRSHIFT
Right shift key
#MODLALT
Left alt key
#MODRALT
Right alt key
#MODLCOMMAND
Left command key
#MODRCOMMAND
Right command key
#MODLCONTROL
Left control key
#MODRCONTROL
Right control key
ID:
Will be set to the identifier of the display that has received this key stroke.

(V7.1)

OnRawKeyUp:
This event handler will be triggered whenever a raw key has been released. Please see the description of OnRawKeyDown above to find out more about the difference between normal key events and raw key events. The function you pass to this event handler will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnRawKeyUp.
Key:
Will be set to the key which has been released. See Raw keys for a list of raw keys supported by Hollywood.
Modifiers:
Will be set to a combination of modifier keys that are currently down. See above in OnRawKeyDown for a list of modifier key flags.
ID:
Will be set to the identifier of the display that has received this key release.

(V7.1)

VanillaKey:
The function you specify here will be called each time the user presses a key or a key combination that results in character that has a graphical representation, including the SPACE character. VanillaKey supports the whole Unicode range of characters and it can also handle characters that are generated by multiple key presses, e.g. diacritical characters. This is the event handler to use if your application should be able to handle non-English characters as well. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to VanillaKey.
Key:
Will be set to the key which has been pressed.
ID:
Will be set to the identifier of the display that has received this key stroke.

Note that VanillaKey only reports key down and key repeat events. It cannot report key up events because this isn't possible for characters generated by multiple key strokes. Additionally, it will only report printable characters (including the SPACE character). If you need to listen to control keys like ESC, backspace, cursor keys, etc., use the OnKeyDown and OnKeyUp event handlers. (V7.0)

OnMouseMove:
The function you specify here will be called each time the user moves the mouse. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnMouseMove.
X,Y:
Will be set to the current mouse pointer position. If they are negative, the mouse pointer is outside the display's boundaries.
ID:
Will be set to the identifier of the display that received this mouse event.

OnMouseDown:
The function you specify here will be called each time the user presses the left mouse button. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnMouseDown.
ID:
Will be set to the identifier of the display that received this mouse event.

(V3.1)

OnMouseUp:
The function you specify here will be called each time the user releases the left mouse button. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnMouseUp.
ID:
Will be set to the identifier of the display that received this mouse event.

(V3.1)

OnRightMouseDown
The function you specify here will be called each time the user presses the right mouse button. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnRightMouseDown.
ID:
Will be set to the identifier of the display that received this mouse event.

(V3.1)

OnRightMouseUp:
The function you specify here will be called each time the user releases the right mouse button. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnRightMouseUp.
ID:
Will be set to the identifier of the display that received this mouse event.

(V3.1)

OnWheelDown:
The function you specify here will be called each time the user moves the mouse wheel in downward direction. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnWheelDown.
ID:
Will be set to the identifier of the display that received this mouse event.

(V4.0)

OnWheelUp:
The function you specify here will be called each time the user moves the mouse wheel in upward direction. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnWheelUp.
ID:
Will be set to the identifier of the display that received this mouse event.

(V4.0)

OnMusicEnd:
The function you specify here will be called each time a music object has finished playing. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnMusicEnd.
ID:
Identifier of the music object that has stopped.

Please note that this event is only triggered when the music has finished playing. It is not triggered when you call StopMusic().

OnSampleLoop:
The function you specify here will be called each time a sample is started. If the sample is only played once, the function will only get called once. If the sample is playing in loop mode, the function you specify will be called each time Hollywood repeats the sample. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnSampleLoop.
ID:
Identifier of the sample that was just started or repeated.
Time:
The time in milliseconds that the sample has been playing now.
Starts:
The number of times this sample was started. This field starts at 1 and will be increased each time Hollywood loops your sample.

Attention! Use this event handler with care. If you have a short sample that is looped infinitely, your callback function will get called again and again which will kill your script's performance. This event handler allows you to achieve exact timing with sample playback.

OnSampleEnd:
The function you specify here will be called each time a sample has finished playing. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnSampleEnd.
ID:
Identifier of the sample that has stopped.
Time:
The time in milliseconds that the sample was playing.
Starts:
The number of times this sample was started. This field starts at 1 and will be increased each time Hollywood loops your sample.

Please note that this event is only triggered when the sample has finished playing. It is not triggered when you call StopSample().

OnARexx:
The function you specify here will be called each time a new ARexx message arrives at the Rexx port created with CreateRexxPort(). The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnARexx.
Command:
A string with the command that shall be executed.
Args:
A pre-parsed string which contains all the arguments for this command delimited by NULL ("\0") characters. You can use the SplitStr() function to extract the individual arguments.
ArgC:
The number of arguments in the Args string.
RawArgs:
The unparsed string containing all the arguments.

Please note that Hollywood might not always separate the arguments in the way you want to have them. In that case, you can use the RawArgs field to access the arguments in their original format just as Hollywood has received them. The Args and ArgC fields are included just for your convenience but some advanced users might sometimes prefer to use RawArgs instead.

See CreateRexxPort for an example of this event handler. (V2.5)

SizeWindow:
The function you specify here will be called each time the user resizes the window. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to SizeWindow.
Width:
New width of the window
Height:
New height of the window
ID:
Will be set to the identifier of the display that has been sized.

MoveWindow:
The function you specify here will be called each time the user moves the window. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to MoveWindow.
X,Y:
New position of the window on the host screen.
ID:
Will be set to the identifier of the display that has been moved.

CloseWindow:
This function will be called everytime the user presses the close box of the window. You can use this to pop up a requester which asks the user if he really wants to quit. Message fields:

Action:
Initialized to CloseWindow.
ID:
Will be set to the identifier of the display whose close box has been clicked.

ActiveWindow:
The function you specify here will be called each time the Hollywood window becomes active. Message fields:

Action:
Initialized to ActiveWindow.
ID:
Will be set to the identifier of the display that has been activated.

InactiveWindow:
This function will be called everytime the Hollywood window becomes inactive. Message fields:

Action:
Initialized to InactiveWindow.
ID:
Will be set to the identifier of the display that has lost the focus.

ShowWindow:
The function you specify here will be called each time the user brings the hidden Hollywood window back to the screen. Message fields:

Action:
Initialized to ShowWindow.
ID:
Will be set to the identifier of the display that has returned from minimized mode.

(V3.0)

HideWindow:
This function will be called every time the Hollywood window is hidden by the user. Message fields:

Action:
Initialized to HideWindow.
ID:
Will be set to the identifier of the display that has been minimized.

(V3.0)

ModeSwitch:
This function is called every time the user switches the current display mode by pressing the COMMAND+RETURN (LALT+RETURN on Windows) hotkey. Message fields:

Action:
Initialized to ModeSwitch.
Mode:
Display mode that Hollywood switched into (can be #DISPMODE_WINDOWED or #DISPMODE_FULLSCREEN)
ID:
Display which handled the pressed hotkey.
Width:
Display width. (V6.0)
Height:
Display height. (V6.0)

(V4.5)

OnDropFile:
This function is called every time the user drops one or multiple icons onto a display. The following fields will be available to your function:

Action:
Initialized to OnDropFile.
ID:
Identifier of the display over which the files were dropped.
NumDropFiles:
The number of files the user dropped over your display. This is usually 1.
DropFiles:
A table containing the list of files that were dropped of the display. This table will have exactly NumDropFiles entries.
X,Y:
Contains the position relative to the top left corner of the receiving display over which the files have been dropped.

(V4.5)

ClipboardChange:
This function is called every time the contents of the clipboard changes. This is useful to enable/disable paste functionality in your script. Message fields:

Action:
Initialized to ClipboardChange.
ID:
Display which received this event.

(V4.5)

OnMidMouseDown:
The function you specify here will be called each time the user presses the middle mouse button. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnMidMouseDown.
ID:
Will be set to the identifier of the display that received this mouse event.

(V4.5)

OnMidMouseUp:
The function you specify here will be called each time the user releases the middle mouse button. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnMidMouseUp.
ID:
Will be set to the identifier of the display that received this mouse event.

(V4.5)

OnConnect:
The function you specify here will be called each time a new client connects to a server created using the CreateServer() call. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnConnect.
ClientID:
Identifier of the client that has connected itself to the server.
ServerID:
Identifier of the server that the client has connected to.

The ClientID is important and you should store it somewhere because you will need it to communicate with the client. You can also use this id to find out the IP address and port number of the client using the commands GetConnectionIP() and GetConnectionPort(). You can also send data to the client by using SendData(). (V5.0)

OnDisconnect:
The function you specify here will be called each time a client disconnects from a server created using the CreateServer() call. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnDisconnect.
ID:
Identifier of the client that has disconnected from the server. You need to call CloseConnection() on this ID to remove the client from your server.

When you get this event, do not forget to call CloseConnection() on the client ID to fully disconnect the client from your server. This is very important. (V5.0)

OnReceiveData:
The function you specify here will be called each time new data is received by an existing connection. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnReceiveData.
ID:
Identifier of the connection that has new data.

When you receive this message it means that there is new data available in the connection specified by ID, and that you should call ReceiveData() now to read this data from the network buffer. (V5.0)

OnReceiveUDPData:
The function you specify here will be called each time new data is received by an existing UDP connection. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnReceiveUDPData.
ID:
Identifier of the connection that has new data.

When you receive this message it means that there is new data available in the connection specified by ID, and that you should call ReceiveUDPData() now to read this data from the network buffer. (V5.0)

OnVideoEnd:
The function you specify here will be called each time a video has finished playing. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnVideoEnd.
ID:
Identifier of the video that has stopped.

Please note that this event is only triggered when the video has finished playing. It is not triggered when you call StopVideo(). (V5.0)

FillMusicBuffer:
The function you specify here will be called each time the sound server needs more audio data when a dynamic music created using CreateMusic() is playing. Your callback will then have to call FillMusicBuffer() to feed more audio data to the device. The function you specify here will receive a message as parameter 1 with the following fields:

Action:
Initialized to FillMusicBuffer.
ID:
Identifier of the music object that has caused this event.
Samples:
Contains the number of PCM frames Hollywood is requesting from your callback. Your callback must provide this amount of PCM frames to Hollywood so that it can forward this audio data to the system's audio device. See FillMusicBuffer for details.
Count:
Contains a global count of how many PCM frames have been sent to the audio device already. Useful for keeping track of how many seconds the music has already been playing.

(V5.0)

OrientationChange:
The function you specify here will be called each time the user changes the orientation of his mobile device. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OrientationChange.
ID:
Identifier of the display.
Orientation:
Constant specifying the new orientation of the device. This will be one of the following constants:

 
#ORIENTATION_PORTRAIT
#ORIENTATION_LANDSCAPE
#ORIENTATION_PORTRAITREV
#ORIENTATION_LANDSCAPEREV

Please note that this event handler is only supported in the mobile version of Hollywood. (V5.0)

ShowKeyboard:
The function you specify here will be called each time the software keyboard becomes visible on mobile devices. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to ShowKeyboard.
ID:
Identifier of the display.

Please note that this event handler is only supported in the mobile version of Hollywood. (V5.0)

HideKeyboard:
The function you specify here will be called each time the software keyboard becomes invisible on mobile devices. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to HideKeyboard.
ID:
Identifier of the display.

Please note that this event handler is only supported in the mobile version of Hollywood. (V5.0)

OnUserMessage:
The function you specify here will be called each time a new user message arrives at the message port created with CreatePort(). The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnUserMessage.
Command:
A string with the command that shall be executed.
Args:
A pre-parsed string which contains all the arguments for this command delimited by NULL ("\0") characters. You can use the SplitStr() function to extract the individual arguments.
ArgC:
The number of arguments in the Args string.
RawArgs:
The unparsed string containing all the arguments.

Please note that Hollywood might not always separate the arguments in the way you want to have them. In that case, you can use the RawArgs field to access the arguments in their original format just as Hollywood has received them. The Args and ArgC fields are included just for your convenience but some advanced users might sometimes prefer to use RawArgs instead.

See CreatePort for an example of this event handler. (V5.0)

Hotkey:
The function you specify here will be called each time the user presses the key combination specified in the -cxkey argument. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to Hotkey.
ID:
Identifier of the display.

Please note that this event handler is only supported in the AmigaOS compatible versions of Hollywood. (V5.2)

TrayIcon:
If you have called the SetTrayIcon() function to install an icon into the system tray, the function you specify here will be called each time the user clicks on that icon. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to TrayIcon.
ID:
Identifier of the display.

Please note that this event handler is only supported in the Microsoft Windows version of Hollywood. (V5.2)

OnTouch:
The function you specify here will be called each time the touch screen detects a user interaction such as putting a new finger on the touch screen, lifting a finger, or moving it. This event is only required if you need fine-tuned control over all touch events, e.g. for supporting multi-touch events or gestures. If you only need simple control over the touch screen, it is easier to use the OnMouseDown, OnMouseUp, and OnMouseMove event handlers. Hollywood will always map the primary finger on the touch screen to the left mouse button.

The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnTouch.
ID:
Will be set to the identifier of the display that received this mouse event.
Type:
This is set to a string describing the type of the touch event. This will be set to either Down, Up, or Move.
Finger:
The finger number this event refers to.
X:
The current X coordinate of the finger on the touch screen.
Y:
The current Y coordinate of the finger on the touch screen.
Pressure:
Contains the current pressure of the finger. This generally ranges from 0 (no pressure at all) to 1 (normal pressure). Values greater than 1 are also possible, dependingt on the calibration of the touch screen.
DownTime:
Contains the time when the finger was put down on the touch screen.
EventTime:
Contains the time when the event was generated.
Size:
Contains the scaled value of the approximate size for the current finger.
TouchMajor:
Contains the current length of the major axis of an ellipse describing the touch area for the current finger.
TouchMinor:
Contains the current length of the minor axis of an ellipse describing the touch area for the current finger.
ToolMajor:
Contains the current length of the major axis of an ellipse describing the tool area for the current finger.
ToolMinor:
Contains the current length of the minor axis of an ellipse describing the tool area for the current finger.
Orientation:
Contains the current orientation of the touch and tool areas in radians running clockwise from vertical for the current finger. The range is from -PI/2 radians (finger is fully left) to PI/2 radians (finger is fully right).

Please note that this event handler is only supported in the mobile version of Hollywood. (V5.3)

OnApplicationMessage:
The function you specify here will be called each time a new message sent through AmigaOS 4's application.library messaging system arrives. If you want to be able to receive application.library messages, you need to have set the RegisterApplication tag in @OPTIONS to True first. The function you specify here will be passed a table as parameter 1 with the following fields initialized:

Action:
Initialized to OnApplicationMessage.

Sender:
The name of the application that has sent this message.

Message:
The actual message.

Please note that this event handler is only available on AmigaOS 4. (V6.0)

OnDockyClick:
If you have set RegisterApplication to True in the @OPTIONS preprocessor command, the function you specify here will be called every time the user clicks on your application's icon in AmiDock. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnDockyClick.
ID:
Identifier of the display.

Please note that this event handler is only supported in the AmigaOS 4 version of Hollywood. (V6.0)

OnMenuSelect:
The function you specify here will be called each time the user selects a menu item. The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnMenuSelect.

ID:
Identifier of the display that the menu strip has been attached to.

Item:
The identifier of the menu item that has been selected. See MENU for details.

Selected:
If the menu item that has been selected is a toggle menu item (i.e. a menu item that can have two different states), this field will contain the current toggle state. See MENU for details.

(V6.0)

RunFinished:
The function you specify here will be called whenever a program executed asynchronously using the Run() command has terminated. The function will receive a message as parameter 1 with the following fields initialized:

Action:
Initialized to RunFinished.

Program:
This is set to a string that contains the name of the program that was launched using Run().

Args:
This is set to a string that contains the arguments that were passed to the program launched using Run().

RunUserData:
If custom user data is specified in the call to Run(), it will be passed on to your callback in this message field. If you don't pass any custom user data, this field won't be initialized at all.

(V6.1)

DirectoryChanged:
If you are currently monitoring directories using the MonitorDirectory() function, the function you specify here will be called whenever a change inside a monitored directory occurs. The function will receive a message as parameter 1 with the following fields initialized:

Action:
Initialized to DirectoryChanged.

ID:
Identifier of the directory object in which the change occurred.

Directory:
This will be set to a string that contains a fully-qualified path of the directory in which the change occurred.

MonitorUserData:
If custom user data was specified in the call to MonitorDirectory(), it will be passed to your callback in this message field. If you don't pass any custom user data, this field won't be initialized at all.

(V8.0)

OnAccelerometer:
The function you specify here will be called each time the device's sensor reports new accelerometer values. Note that this will typically happen all the time so if you listen to this event, you will get lots of events that can impact the performance of your script.

The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnAccelerometer.
ID:
Will be set to the identifier of the display that received this event.
X:
X accelerometer value from sensor.
Y:
Y accelerometer value from sensor.
Z:
Z accelerometer value from sensor.

Please note that this event handler is only supported in the Android version of Hollywood. To learn how to interpret the X, Y, and Z values provided by this event handler, please consult the Android documentation of SensorEvent. (V8.0)

OnGyroscope:
The function you specify here will be called each time the device's sensor reports new gyroscope values. Note that this will typically happen all the time so if you listen to this event, you will get lots of events that can impact the performance of your script.

The function will receive a message as parameter 1 with the following fields:

Action:
Initialized to OnGyroscope.
ID:
Will be set to the identifier of the display that received this event.
X:
X gyroscope value from sensor.
Y:
Y gyroscope value from sensor.
Z:
Z gyroscope value from sensor.

Please note that this event handler is only supported in the Android version of Hollywood. To learn how to interpret the X, Y, and Z values provided by this event handler, please consult the Android documentation of SensorEvent. (V8.0)

If you want to remove an event handler, simply set the corresponding field in the table to 0 instead of passing a function.

Starting with Hollywood 3.1 there is an optional argument called userdata. The value you specify here is passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the userdata argument you can easily pass data to your callback function. You can specify a value of any type in userdata. Numbers, strings, tables, and even functions can be passed as user data.

Starting with Hollywood 7.0 all event messages will contain an additional field named Timestamp. This field contains the time stamp when the event was generated. This time stamp is passed in seconds as a fractional number. It is relative to the time Hollywood was started. See GetTimestamp for details.

Please note that the event handler functions are only executed while the script is in a WaitEvent() loop. You have to use WaitEvent() for them!

Inputs
table
table which contains information about which handlers to install or remove
userdata
optional: user specific data that will be passed to the callback function (V3.1)
Example
Function p_HandlerFunc(msg)
  Switch(msg.action)
  Case "ActiveWindow":
    DebugPrint("Window has become active again!")
  Case "InactiveWindow":
    DebugPrint("Window has become inactive!")
  Case "MoveWindow":
    DebugPrint("User has moved the window to", msg.x, msg.y)
  Case "OnKeyDown":
    If msg.key = "ESC" Then End
  EndSwitch
EndFunction

InstallEventHandler({ActiveWindow = p_HandlerFunc,
   InactiveWindow = p_HandlerFunc,
   MoveWindow = p_HandlerFunc,
   OnKeyDown = p_HandlerFunc})

Repeat
  WaitEvent
Forever
The code above installs four event handlers for ActiveWindow, InactiveWindow, MoveWindow and OnKeyDown. If the user presses escape, the program will quit. If you want to remove e.g. the event handler MoveWindow, just call InstallEventHandler() again with the parameter MoveWindow=0.

Show TOC