[id] = MakeButton(id, #LAYERBUTTON, layerid, t[, userdata])
[id] = MakeButton(id, #SIMPLEBUTTON, x, y, width, height, t[, userdata])

[id] = MakeButton(id, #LAYERBUTTON, layerid, exactcoll, noautohide, t
                      [, userdata]) (V2.5)

#SIMPLEBUTTON:

Creates a standard button. Note that this button is invisible. You need to use graphics in your BGPic to show the user where your button is. The type #SIMPLEBUTTON requires you pass the position and dimensions for the button in argument 3 to 6. The seventh argument is a table argument allowing you to specify the callback functions to be invoked when the button receives an event (see below).

#LAYERBUTTON:

This type is new in Hollywood 2.5. It will create a dynamic button which will always share the position and size of the layer specified by layerid. Note that layer buttons are closely tied to their layer. Thus, when the layer is deleted, the button will also be deleted. Layer buttons also support some additional options in the table argument accepted by MakeButton() (see below for details).

The t argument must be a table which specifies the functions that shall be called when a specific event occurs. It can also be used to configure some advanced button options. The table can contain the following fields:

OnMouseOver:

The function specified here will be called when the user moves the mouse over the button's area.

OnMouseOut:

The function specified here will be called when the mouse pointer leaves the area occupied by this button.

OnMouseDown:

The function specified here will be called when the user presses the left mouse button while the pointer is over the button's area.

OnMouseUp:

The function specified here will be called when the user releases the left mouse button while the pointer is over the button's area. This event will only be triggered if the user also pressed the left mouse button while the pointer was over the button's area.

OnRightMouseDown:

Same as OnMouseDown but with the right mouse button.

OnRightMouseUp:

Same as OnMouseUp but with the right mouse button.

OnMidMouseDown:

Same as OnMouseDown but with the middle mouse button. (V4.5)

OnMidMouseUp:

Same as OnMouseUp but with the middle mouse button. (V4.5)

PixelExact:

This is only supported for #LAYERBUTTON. It specifies whether or not your button should use pixel-exact or rectangular collision detection. If you pass True here, events will only be triggered on a pixel-exact collision. This can be useful for irregularly shaped buttons. Defaults to False.

NoAutoHide:

This is only supported for #LAYERBUTTON. It specifies whether or not the button shall automatically be hidden when the layer is hidden. If you specify True here, the button will not automatically disappear when you hide the layer it is attached to. If NoAutoHide is False, the button will disappear as soon as you hide the layer. Defaults to False.

ZOrder:

This is only supported for #LAYERBUTTON. It specifies whether or not the layer z-order should be respected when handling events of overlapping layer buttons. Historically, overlapping layer button events were handled in the order of their creation, i.e. if a layer button was created before another layer button and both layers overlapped, the layer button created earlier would receive the events even if it was below the other layer button. By setting the ZOrder tag to True, you can force Hollywood to handle events of overlapping layer buttons in their stacking order, i.e. layers on top of other layers will receive their events first. For compatibility reasons, this tag defaults to False. (V9.0)

If you just want to listen to mouse clicks on a button, it is enough to provide a callback function for the OnMouseUp event type. OnMouseDown is only required, if you want to highlight the button in some way while the user clicks on it.

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.

The callback functions you specify in the event table will be called by Hollywood with one parameter. This parameter is a message table that contains some information about the event. The following fields are provided:

Action:

Contains the name of the event triggered, e.g. OnMouseUp, OnMouseOver or OnMouseOut. This field is a string.

ID:

Contains the identifier of the button that triggered this event. This field is a number.

X, Y, Width, Height:

These fields contain the dimensions of the button that triggered this event.

MouseDown:

This field will be set to True if the left mouse button is currently pressed. Useful in connection with the OnMouseOver event, so that you can display a differently highlighted version of the button if the user moves the pointer of the button while the left mouse button is pressed.

RightMouseDown:

Same as MouseDown but relating to the right mouse button.

MidMouseDown:

Same as MouseDown but relating to the middle mouse button. (V4.5)

Layer:

The identifier of the layer this button is bound to. This is only set for buttons of type #LAYERBUTTON. (V4.5)

LayerName:

The name of the layer this button is bound to. This is only set for buttons of type #LAYERBUTTON. (V4.5)

UserData:

Contains the value that you have passed in the userdata argument when you created the button.

Timestamp:

Contains a time stamp that indicates when the event occurred. See GetTimestamp for details. (V7.0)

The advantage of this message is that you can use one and the same function for all your buttons and all events. Just check the fields Action and ID to find out which button caused the event.

Please note: Buttons are always attached to BGPics. So if you call MakeButton() when BGPic 1 is displayed, the button will be attached to BGPic 1. If you display BGPic 2 then, the buttons will go away. Once you switch back to BGPic 1, its buttons will also be re-activated.

Also note that you can only create rectangularly shaped buttons with #SIMPLEBUTTON. If you want to have irregularly shaped buttons, create a layer that has a transparency setting (masked or alpha channelled transparency) and then use #LAYERBUTTON to attach a button to this layer.

id

identifier for the new button or Nil for auto id selection

type

type of the new button

x

x position of the new button

y

y position of the new button

width

width of the new button

height

height of the new button

t

table that contains callback functions that Hollywood shall call if a specific event occurs and additional arguments (see above)

userdata

optional: user specific data that will be passed to the callback function (V3.1)

id

optional: identifier of the button; will only be returned when you pass Nil as argument 1 (see above)

Function p_MyFunc(msg)
  Switch msg.action
  Case "OnMouseUp":
    DebugPrint("User left-clicked button", msg.id)
  Case "OnMouseOver":
    DebugPrint("User moved mouse over button", msg.id)
  Case "OnRightMouseUp":
    DebugPrint("User right-clicked button", msg.id)
  EndSwitch
EndFunction

; draw the buttons
Box(0, 0, 100, 100, #RED)
Box(200, 200, 100, 100, #BLUE)

; install them
evtmatch = {OnMouseUp = p_MyFunc, OnMouseOver = p_MyFunc,
            OnRightMouseUp = p_MyFunc}
MakeButton(1, #SIMPLEBUTTON, 0, 0, 100, 100, evtmatch)
MakeButton(2, #SIMPLEBUTTON, 200, 200, 100, 100, evtmatch)

Repeat
  WaitEvent
Forever