Scripting a Button

Create a new stack, name it 'Button Messages' and add a scrolling field and a button to the stack.

Name the field 'Text' and the button 'Red'.

Add some text to the field, in this example I used some Lorem Ipsum text but any text will be fine.

To open the Code Editor for the button:

1. Choose 'Edit Mode'
2. Select the button
3. Click the 'Code' button in the Toolbar

You can also open the Code Editor by right clicking the button and choosing 'Edit Script' from the menu.

There are a number of messages that are sent to buttons.

mouseEnter: sent when the mouse pointer enters an object
mouseMove: sent when the user moves the mouse within the object area
mouseDown: sent when the user presses the mouse button
mouseUp: sent when the user releases the mouse button

In this case we want something to happen on mouseUp, as an example we are going to change the text color of the field so we set the script to:

on mouseUp
    set the textColor of field "text" to red
end mouseUp

Then click the 'Apply' button(1), the traffic light indicator should turn green, showing that the script has compiled.

Note: A yellow indicator means the script has unsaved changes, a red indicator means there is an error on the script.

Switch to 'Run' mode(1) and click the 'Red' button (2). The text color of the field changes to red.

You can handle more than one message in a button script, open the Code Editor of the button again and add a mouseDown handler that changes the text color of the field to blue.

on mouseDown
    set the textColor of field "text" to blue
end mouseDown

Now when you switch to 'Run' mode and click the button the text turns blue when the button is pressed and red when the mouse is released.

In the lesson The LiveCode Message Path we mentioned that you can use the Message Path to group similar functionality and minimise repetitive coding.

What if we had 3 buttons that change the text color? We could add mouseUp handlers to each one but since they all do basically the same thing we can instead use the Message Path to handle the mouseUp message on the card instead.

Add 2 more buttons, 'Green' and 'Blue' to the stack and ensure that the scripts of all the buttons are empty. This is important because if a button has a mouseUp handler, even if it doesn't do anything, the message won't be passed up to the card.

Open the Script Editor for the card by choosing 'Card Script' from the Object menu. Alternatively you can right click on the card and select 'Edit Card Script' from the menu.

Add a mouseUp handler to the card script, within it we use the target function to check which button was pressed.

on mouseUp
    local tColor

    ## Use the target function to check which button was pressed
    ## The short name of the buttons are red, blue and green
    ## so we can use that to set the color
    put the short name of the target into tColor
    set the textColor of field "text" to tColor
end mouseUp

Another option is to create a custom handler and call this from the buttons, passing the color as a parameter.

You use custom commands and custom functions the same way as any other command or function. You can execute a custom command simply by typing the name of the command you want to send.

When a custom command is called a message with the same name as the command is sent. You respond to a custom command's message by writing a message handler with the name of the command. If you don't specify an object, the message is sent to the object whose script is being executed, and then passes up the message hierarchy as normal.

Like a built-in command, a custom command is an instruction to LiveCode to do something. You can include parameters with a custom command by passing them after the name.

Open the Code Editor for the card and add the following custom command

command colorText pColor
    set the textColor of field "text" to pColor
end colorText

This command takes a parameter, pColor, and sets the text color of the field to the value of that parameter.

Now open the script of button 'Red', change the mouseUp handler so it calls the custom command, passing the color as a parameter.

on mouseUp
    colorText "red"
end mouseUp

Repeat this for the other buttons, changing the parameter in each case.

An alternative option is to handle mouseUp on the card and call the custom command from the card script.

on mouseUp
    put the short name of the target into tColor
    colorText tColor
end mouseUp