Scripting a Button
A LiveCode application is driven by user actions, when the user interacts with your application, by clicking a button or typing in a field, LiveCode sends a message.
You decide what messages you want your program to respond to and add scripts which handle those messages.
This lesson shows you how to respond to some of the messages that are sent to buttons.
Create the Stack
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 Text to the Field
Add some text to the field, in this example I used some Lorem Ipsum text but any text will be fine.
Open the Code Editor for the Button
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.
Scripting the Button
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.
Try the Button
Switch to 'Run' mode(1) and click the 'Red' button (2). The text color of the field changes to red.
Adding a mouseDown Handler
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.
Using the Message Path
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.
Handling the mouseUp Message on 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
Using a Custom Handler
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.
The colorText Custom Command
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.
Calling the Custom Handler from the Card Script
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
Not changing red for me - compiles fine. Am I missing some earlier stage? Just trying the coding for buttons but can some good folks help - come form a VB background but seeking redemption.