Command-handler-calls

<commandName> [<parameter1>[, <parameter2>[, <parameter3> [...]]]]

send <commandName> [<parameter1>[, <parameter2>[, <parameter3> [...]]]] to <object> [in <time>]

Specifying in <time> with time being a number in 60ths of a second, will schedule the message to be sent that many 60ths of a secon in the future, not right now.

Expressions

Math operators

+, -, * for integer and double types, and /, <, <=, >, >=, =, ^ operators.

Concatenation Operators

& and && string concatenation operators.

Brackets

(<expression>) a bracketed expression to expressly override operator precedence.

Function-handler-calls

<functionName>([<parameter1>[, <parameter2>[, <parameter3> [...]]]])

Sends the message <functionName> to the current object, from where it bubbles up the message path.

<functionName>([<parameter1>[, <parameter2>[, <parameter3> [...]]]]) via <object>

Sends the message <functionName> to the object <object>, from where it will bubble up the message path..

Chunks

{character|line|word|item|byte} <startIndex> to <endIndex> of <value> and put <expression> into {character|line|word|item|byte} <startIndex> to <endIndex> of <container> for generating/modifying substrings

Property Expressions

[the] <propertyName> of <object> query/modify a property stored under the supplied name in an object.

Dictionary Entry Expressions

entry <key> of <dictionary> query/modify a value stored under the supplied key name in a dictionary.

User Properties

define property <propertyName> of <object> creates a property on the given object, that you can use to store any valid SuperTalk data type.

undefine property <propertyName> of <object> deletes a property previously created using define property.

Self-References

  • me indicating the object the currently running script belongs to.
  • [the] target indicating the object the current message was sent to.

Comments

Single-line comments with --. Multi-line comments begin with (* and end with *).

Return

return [<expression>] command for returning a value from a handler. For a command handler, the value given here is stored in the local variable the result of the calling handler.

You can also merely write return without a value to return no value (the return value of the handler will have the “unset” value). return without an expression is equivalent to exit <handlerName>.

Output

output <expression> command for printing to the console. For compatibility with HyperCard, put <expression> is supported as a synonym for this command.

Assignment

put <expression> into <container>
set <container> to <expression>

for assigning to variables, named parameters and properties, and declaring variables.

Loops

repeat while <condition>\n...\nend repeat

Conditionals

if <condition> [\n] then [\n] <commands> [\n] [else [\n] <commands>] [\n] [end if] conditional statements.

Passing a Message up the Path

pass <currentHandlerName>

Early Returns

exit <currentHandlerName> Return from a handler without returning a value. exit to top Abort script execution of the entire call stack, returning control to the host application. For compatibility, exit to HyperCard and exit to SuperCard are also supported.

Dictionaries

"key:value" & newline & "key2:value2" ...
<key>: <value>, <key2>: <value2> ...

You can declare a dictionary as a string or as native syntax. In its string representation, a newline must be prefixed with a ¬ and an ¬ needs to be replaced with ¬¬. Like everything in Hammer, dictionary keys are not case-sensitive.

put <key> of <dictionary> into ...
put ... into <key> of <dictionary>

Retrieve the value of the dictionary entry under the given key, or assign a value to the given key in the dictionary (possibly replacing an existing value).

Global Variables

global <variableName> [, <variableName2> ...]

Declare a global variable and make it available to the current command or function handler.

Object descriptors

You can refer to objects in any currently open project, and to projects anywhere accessible to the current user using object descriptors. Generally, object descriptors have three forms:

  • <type> <name> - An object of the given type, referenced by its name. Like card "Contents".
  • <type> <number> - An object of the given type, referenced by its position in the project, like window 1 or icon 37.
  • <type> id <id> - An object of the given type, referenced by its unique identification number, or ID number. The ID of an object does not change over its lifetime. While you can change an object’s name or number, the ID stays the same until an object is permanently deleted.

Available types right now are project, icon, window, background, card, button, field, graphic.

Referencing objects relative to their parents

Objects exist in a hierarchy. A SuperCard file is called a project, which you can reference by using its file path on disk, like project "/Users/karen/Documents/My Project.xstk". If a project is already open, or is in a location that SuperCard already knows, you can also just use the file name to refer to it, and you can often even leave out its filename suffix (like project "My Project").

A project may contain multiple stacks of filing cards. Each stack is presented in its own window (appropriately called window), which can contain multiple cards (i.e. pages). Each card can contain zero or more other things, like UI elements (pushbuttons, popup menus, text fields) and graphics (vector rectangles and circles, or a fixed-resolution pixel image).

Each object must be unique among its peers (there can only be one project at any given file path, and there can only be one button with ID number 15 on a particular card), but apart from that, unique IDs and file names can occur multiple times in different places. To avoid ambiguity, you can tell SuperCard which object you want exactly using the of operator. So if you wanted to be very precise, you could say:

button "OK" of card "Delete confirmation" of window "Confirmation dialog" of project "/Second HD/DialogProject.xstk"

You could also only partially specify such a nested object descriptor, in which case SuperCard will use the current card (or its containing stack or project) to make a best-effort attempt at finding an object with the given name (possibly inside another object, if you specified one). Like:

button "Quit" of card "Startup Error"

Backgrounds

Apart from cards, SuperCard windows also contain backgrounds. A background, like a card, can contain buttons and fields and graphics. Every card has a background, but multiple cards may share the same background. Any objects you place on a background will be drawn behind (“underneath”) the objects of a card. This allows you to create common elements that are shared by all cards that belong to a background, like a common background color, a common title text field etc.

You can set up some objects (like text fields) so their contents are different on different cards. This is usually limited to one specific property of that object type, which you do not get to choose. For example, background checkbox controls can have different values for their highlight property on different cards. Background text fields can have different text (“contents”) in them on different cards. This allows you to use a window as a simple database, with the background definining the fields, and each card being a record in the database.

Strings

Strings are just quoted with the double-quote character.

"foo"

There are no escape sequences. Instead, you can concatenate string constants with symbolic constants.

"Hello" && quote & "World" & quote

Numbers

Numbers can be integers or floating point numbers

123
265.7

You can also specify a unit after a number. Current supported units are

1.5 hours
2 seconds
1 tick

Units have singular and plural forms, though SuperCard does not enforce their correct usage, so 1 ticks is valid syntax.