Name
MakeButton -- create a new button (V2.0)
Synopsis
[id] = MakeButton(id, type, ...)
[id] = MakeButton(id, #SIMPLEBUTTON, x, y, width, height, evttable
                  [, userdata])
[id] = MakeButton(id, #LAYERBUTTON, layerid, exactcoll, noautohide,
                  evttable[, userdata]) (V2.5)
Function
This function creates a new button with specified dimensions and attaches it to the BGPic that is currently displayed. The button will be given the identifier specified by id, or, if you pass Nil as id, MakeButton() will automatically choose a vacant identifier for you. The argument type specifies the type of the button. Currently possible types are:

#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 an event table (see below).

#LAYERBUTTON:
This type is new in Hollywood 2.5. It creates a dynamic button which will always be at the position where the layer with the specified layerid is. The button will use the dimensions of the specified layer. The exactcoll argument specifies whether your button shall use pixel- exact or rectangular collision detection. If you pass True here, events will only be triggered on a pixel-exact collision. This allows you to create irregularly shaped buttons. The noautohide argument 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. The evttable argument is an event table (see below). Please note that layer buttons depend on the layer they are attached to. If you delete this layer, the button will also be deleted.

The evttable argument must be a table which defines the functions that shall be called when a specific event occurs. 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)

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)

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.

Inputs
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
evttable
table that contains callback functions that Hollywood shall call if a specific event occurs
userdata
optional: user specific data that will be passed to the callback function (V3.1)
Results
id
optional: identifier of the button; will only be returned when you pass Nil as argument 1 (see above)
Example
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

Show TOC