# HyperTalk basics

## Set the user level to scripting

Before you can write your own scripts, you must set your user level to Scripting  (5).

Go to the Preferences card of your Home stack and set your user level there if you want it set to Scripting every time you start HyperCard.

## HyperTalk and scripts

HyperTalk® is HyperCard’s script language. You use it to write English-like statements that respond to events (such as when the user clicks a button or goes to a new card).

In HyperTalk, responding to an event is called **handling** the event. As a scripter, you write a specific handler for each event that you want your stack to handle. A collection of handlers is called a script.

The following graphic shows a handler for the mouseUp event. It’s part of the script of card button id 1.

## What are messages?

A message is simply an announcement that an event has occurred: The user has clicked the mouse, requested the answer to 4 * 3, added a new card to a stack, and so on.  

To understand messages, think of mailing a letter to a friend. You write a message and place it inside an envelope. Then you address the envelope and send it to your friend.

HyperCard does the same thing:  

1.  It determines the content of a     message (what just happened).  

2.  It decides where to send the     message.

### What’s the content of a message?

The message itself is just HyperCard’s name for the event that occurred. HyperCard acts as a translator: it “watches” the stack and translates events into message names.

To see HyperCard translate events into message names, move the pointer over the Example Button and click.

### Where does HyperCard send the message?

HyperCard determines what object the user has acted on and uses this as the “address” for the message. HyperCard then sends the message to one of its objects:

* a button
* a field
* a card
* a background
* a stack

Once HyperCard knows both the content of the message (the message name) and the destination of the message (where to send it), it sends the message to the object.

## Handling messages

As a scripter, you write message handlers to respond to messages. When an object receives a message, HyperCard searches the object’s script for a handler with the same name (a handler starts with the word on followed by the name of a message). If HyperCard finds a match, it runs any HyperTalk statements in the handler until it hits an end statement.

For example, if you want a button to respond to a mouseUp message, you would add a mouseUp message handler to its script.

```
on mouseUp
  play "boing"
end mouseUp
```

Click Related Topics for more information about opening a script window.

## The message-passing order

What happens if an object that receives a message *doesn’t*  handle it?

In this case, HyperCard passes the message to other objects and searches their scripts for a message handler that matches the current message. The order in which HyperCard passes a message to objects is called the _message-passing order_  or the _message-passing path_.

Initially, HyperCard sends messages to a specific button or field or to the current card. If a button or field doesn’t handle the message, it goes on to the current card. From the current card, the message goes to the following objects, in order:

* the current background
* the current stack
* the stack script of the Home stack
* HyperCard itself

To see the message-passing order in action, click each of the following buttons:

## Writing message handlers

When you write a handler for a message, you specify a sequence of statements for HyperCard to run. Each message handler has the following form, with the italicized words as placeholders:

```
on messageName
   statements
end messageName
```

When it runs the message handler, HyperCard sends each line of the handler as a message itself (so handlers can call other handlers).

**Important**: The message name does *not* have to be one of HyperCard’s built-in system messages or commands.

For example, if you wanted a new command called doubleBeep that would beep twice, you would write a handler for it as follows:

```
on doubleBeep
  beep
  beep
end doubleBeep
```

Of course, HyperCard doesn’t know about the doubleBeep command, so it will never be sent automatically in response to an event. But you can send doubleBeep from the Message box or use it as a statement in other handlers.

For example, the script of a card button might contain the following handler for the system message mouseUp:

```
on mouseUp
  doubleBeep
end mouseUp
```

If the script also contains the doubleBeep handler (or if the script of any object later in the message-passing path contains it), the mouseUp message will send the doubleBeep message, and doubleBeep will send two beep commands. Because beep is a built-in command, HyperCard beeps twice.

If HyperCard can’t find the doubleBeep message, it will complain (with a dialog box) that it “can’t understand” the message.

## Using parameter variables

A handler can receive values (called parameters) and use them as it runs. You represent each value with a **parameter variable**. A parameter variable always follows the handler name in a comma-separated list.

For example, when running the following mouseUp handler, HyperCard calls sayMessage with two values, "red" and "apple". It then binds these values to the parameter variables color and fruit in the sayMessage handler.

```
on mouseUp
  sayMessage "red", "apple"
end mouseUp

on sayMessage color, fruit
  put "I want a" && color && fruit
end sayMessage
```

You can use the variables color and fruit anywhere inside the handler. When HyperCard sees them, it uses the values currently bound to them. (The variables remain bound only while the handler runs.)

## Writing function handlers

When you write a handler for a function, you specify statements that compute and return a value to the handler that calls the function. Each function handler has the following form, where the italicized words are placeholders:

```
function functionName
   statements
end functionName
```

HyperCard has many built-in functions, but you can also write your own:

```
on mouseUp
  put square(5) into the Message box
end mouseUp

function square x
  return (x * x)
end square
```

The function square receives a number through its parameter variable, x.  It then returns the value of  x * x to the handler that called it (mouseUp) using the return keyword.

## The building blocks

HyperTalk scripts use a number of basic building blocks as sources of value.

Click one for more information about it.

basic sources of value
operator
expression
constant
local variable
global variable
it
button
field
message box
selection
chunk expression
property
function

## Referring to objects

You can refer to HyperCard objects and other elements from a script in any of several ways.

Click a term in the “Refer by” list for more information about that term.

Click Tips for a list of synonyms that you can use for referring to objects.

name
number
id
part
ordinal
position
me
target