Messages and events

Everything is a message

When the user does something, xTalk tells the object it happened to by sending it a message: a word such as mouseUp, keyDown or openCard. If the object's script has a handler with that name, the handler runs. If not, nothing visible happens, and the message moves on (the next lesson follows where it goes).

This is the heart of every xTalk program: you do not write a main loop that waits for clicks. You write small handlers, put each in the object it belongs to, and xTalk calls them at the right moment.

A button with a script

You have already written one handler: the button in Stacks, cards and controls. Here is the smallest one there is.

on mouseUp
   put "Hello from the button"
end mouseUp

Hello from the button

In Run mode, the click sends mouseUp to the button, and its handler runs. A script, or you in the Message Box, can send a message to an object just as a click would, and read an object's script, which is a property like any other:

send "mouseUp" to button "Hello"
put the number of lines of the script of button "Hello"

Hello from the button
3

Messages you will meet

Messages that carry a value

Some messages come with information, which arrives in the handler's parameters: mouseUp says which mouse button was used (1 is the main one), and keyDown which key was typed.

on mouseUp pWhich
   put "mouseUp with button" && pWhich
end mouseUp

mouseUp with button 1

Now give the field this script. In Run mode, click into the field and type: each key shows in the Message Box, and pass keyDown lets it on into the field. To try it without typing, send the field a keyDown from the Message Box:

on keyDown pKey
   put "typed" && pKey
   pass keyDown
end keyDown

send "keyDown x" to field "Typing"
send "keyDown 7" to field "Typing"

typed x
typed 7

One handler, many controls

A control with no handler for a message lets it go on to its card and then its stack (The message path follows it all the way). So a handler in the card's script hears the clicks of every button that does not handle them itself, and the target says which one it was:

ScriptThe script of this card, then in Run mode click button "Left" 3 times, then button "Right"Copy

on mouseUp
   if word 1 of the name of the target is "button" then
      set the label of the target to the label of the target + 1
   end if
   put the label of button "Left" && the label of button "Right"
end mouseUp

Message Box (what it shows after each click)

1 0
2 0
3 0
3 1

Your card as the OXT-Beyond engine draws it

My Stack

Click Left three times and Right once, and the Message Box counts along. The if leaves the card's own label alone when you click the card between the buttons.

Reacting to the pointer

Here is a script you could give any button: it lights up while the pointer is over it. Drag a Standard Button onto a card, name it Shiny, give it this script, and move the pointer over it in Run mode:

on mouseEnter
   set the backgroundColor of me to "gold"
end mouseEnter

on mouseLeave
   set the backgroundColor of me to empty
end mouseLeave

on mouseUp
   answer "You clicked" && the short name of me
end mouseUp

Setting a colour to empty gives the control back its normal look, inherited from its card and stack.

Messages when a card opens

Going to a card sends it openCard. It is the place for a card to get ready: fill its fields, start a timer, reset a game.

on openCard
   put "openCard: the card" && the short name of me && "is ready"
end openCard

Now go back and forth with View > Go Prev and View > Go Next, or in the Message Box:

go to card 1
go to card "Second"
go to card 1
go next

openCard: the card Second is ready
openCard: the card Second is ready

Two lines: only arriving at Second sends the message to its script. A handler in the stack's script (Object > Stack Script) would hear every card open, since a card with no openCard handler passes the message on to its stack.

Send and dispatch

send delivers a message as if xTalk had sent it. If no handler anywhere answers it, send stops with an error. On a card with a button B that has no script:

send "mouseUp" to button "B"

dispatch is the polite form: it delivers the message if someone handles it, and either way sets it to handled or unhandled, so your script can tell. Give the card a tidyUp handler of your own (a command: the lesson Commands explains them), and a button that dispatches it and a message nothing handles:

on tidyUp
   put "tidying up"
end tidyUp

on mouseUp
   dispatch "refresh" to me
   put it into tFirst
   dispatch "tidyUp" to me
   put tFirst && "then" && it
end mouseUp

unhandled then handled

Nothing answers refresh, and that is fine. tidyUp goes from the button on to the card, whose handler runs (its put is replaced in the Message Box by the last one).

Try it yourself

On a new card, drag a Field named Log and three Standard Buttons named Apple, Pear and Plum. Write one mouseUp handler, in the card's script, that adds the name of the button clicked as a new line of the field, and puts which line it is. Then click Pear, Plum and Apple.

Build it with the Tools palette and the Property Inspector

1. Drag three Standard Buttons in a row, about 120 points wide, and name them Apple, Pear and Plum.
2. Drag a Field below them, make it big, and name it Log.

Show a solution

ScriptThe script of this card, then in Run mode click button "Pear", then button "Plum", then button "Apple"Copy

on mouseUp
   if word 1 of the name of the target is not "button" then exit mouseUp
   if field "Log" is not empty then put return after field "Log"
   put the short name of the target after field "Log"
   put the short name of the target && "is line" && the number of lines of field "Log"
end mouseUp

Message Box (what it shows after each click)

Pear is line 1
Plum is line 2
Apple is line 3

Your card as the OXT-Beyond engine draws it

My Stack