Functions

Built-in Functions | Function Handlers

A function directs HyperTalk to perform a task that produces some value. Therefore, functions can appear as a term in an expression. For example, 3 / the average of "1, 2, 3" is a legal expression.

WyldCard provides a suite of built-in functions plus the ability to script new ones.

Built-in functions

When invoking a built-in WyldCard function, there are several equivalent syntax forms that can be used:

• Use the <function> for built-in functions that don't accept any arguments. For example, the mouseLoc or the screenRect (the preceding the is required for no-argument functions).
• Use [the] <function> { of | in } <argument> for built-in functions that accept a single argument. For example, the number of card buttons or sqrt of 25 (the is optional). WyldCard also allows this form to be used when invoking a function that accepts a list of arguments, provided the list is contained within quotes. For example, the max of "1,2,3" (HyperCard does not support this syntax).
• Use function(<arg1>, <arg2>, ...) for any kind of built-in functions. For example, sum(3,5,9) or mouseLoc() or sqrt(25).

You cannot invoke a function handler defined inside of a script using either of the first two forms. Only WyldCard-provided functions can be invoked as the <function> or <function> of ....

WyldCard includes the following built-in functions:

Function	Description
abs	Returns the absolute value of the given numerical argument.
atan	Returns the trigonometric arctangent of the given argument, represented in radians.
annuity	Given two arguments; an interest rate, and a number of periods, annuity returns the total value of an annuity that makes one payment per period at the given interest rate. Equivalent to (1 - (1 + rate) ^ -periods) / rate. For example, to calculate the monthly payment on a 30-year mortgage loan of a $100,000 at 3% interest, 100000 / annuity(.03 / 12, 30 * 12) yields approximately 421.60.
average	Returns the statistical mean of a list of numerical items. Example: the average of "1,2,3,4,5" (returns 3) or average (93, 26, 77) returns 65.33.
charToNum	Return the numerical codepoint associated with the given character. The actual mapping between characters and numbers will depend on the character encoding used by the system, but charToNum is always assured to be the inverse of numToChar
clickH	Returns the x-coordinate of the last location the user clicked the mouse.
clickChunk	Returns a HyperTalk expression referring to the chunk of text last clicked in a text field. For example, char 13 to 18 of background field 2
clickLine	Returns the line number of where the user last clicked in a text field.
clickLoc	Returns the coordinate of the last location the user clicked the mouse.
clickText	The last word that was clicked in a text field, or the empty string if no text has been clicked. For example, put "You clicked " & the clickText.
clickV	Returns the y-coordinate of the last location the user clicked the mouse.
commandKey	Returns the current state of the command key (and/or 'ctrl' key on PC hardware), either up or down. Also available as the cmdKey
compound	Given two arguments; an interest rate, and a number of periods, compound returns the value of one unit of principal invested at the given interest rate compounded over the given number of periods. Equivalent to (1 + rate) ^ periods. For example, to calculate how much a $1,000 initial investment will be worth assuming a 3% annual rate of return compounded annually and invested over 6 years, 1000 * compound(.03, 6) yields approximately 1194.05.
cos	Returns the trigonometric cosine of the given argument, represented in radians.
date	Returns the current date in a variety of formats. Use the date or the short date to yield a date in the format 07/04/16; use the long date or the English date for Sunday, July 4, 2016; use the abbrev date or the abbreviated date for Sun, Jul 4, 2016.
diskSpace	Returns the number of free bytes on the filesystem containing WyldCard, or any specified filesystem. For example, the diskSpace or the diskSpace of "/Volumes/Macintosh HD". Accepts the path of any disk, folder or file.
exp	Returns the value of e raised to the power of the given argument.
exp1	Returns the value of 1-e raised to the number of the given argument.
exp2	Returns the value of 2 raised to the given argument; for example the exp2 of 3 is equivalent to 2^3.
foundChunk	Returns a HyperTalk chunk identifying the currently highlighted search result text (the result of executing the find command). For example, chars 13 to 17 of background field id 8.
foundField	Returns a HyperTalk expression representing the field containing the highlighted search result text. For example, background field id 8.
foundLine	Returns a HyperTalk line chunk expression representing the line and field containing the highlighted search result. For example, line 4 of background field id 8.
foundText	Returns the highlighted search result, that is, the text string that is presently box-highlighted on the card.
length	Returns the number of characters in the value of the given expression. Example: the length of "Hello World!" yields 12.
ln	Returns the natural logarithm of the given argument.
ln1	Returns the natural logarithm of the given argument plus one.
log2	Returns the base-2 logarithm of the given argument.
max	Returns the maximum number passed to the function. For example: min(3,5,7.24,9) evaluates to 9.
menus	Returns a return-delimited list of menus appearing in the menu bar.
message	Returns the contents of the message box. For example: put the message box into aVar. Also available as message box or message window
min	Returns the minimum number passed to the function. For example: min(3,5,7.24,9) evaluates to 3.
mouse	Returns the current state of the left mouse button; either up or down
mouseClick	Returns whether the mouse was pressed at any point since the current handler began executing.
mouseH	Returns the x-coordinate of the mouseLoc; the number of pixels the mouse cursor is from the left border of the card.
mouseLoc	Returns the current location of the cursor (in coordinates relative the top-left corner of the card panel), for example: the mouseLoc returns 123,55
mouseV	Returns the y-coordinate of the mouseLoc; the number of pixels the mouse cursor is from the top border of the card.
number of	Returns the count of something within a given container. Several usages including: number of words in <container>, number of chars in <container>, number of lines in <container>, number of items in <container>, number of card { buttons / fields / parts}, number of background {buttons / fields / parts}, number of menuItems in menu <menuName>, number of menus, number of cards, number of marked cards, number of backgrounds, number of cards in background <background>.
numToChar	Returns the character value associated with the given character codepoint. The actual mapping between numbers and characters will depend on the character encoding used by the system, but numToChar is always assured to be the inverse of charToNum
offset	Accepts two values as arguments, text1 and text2. Returns 0 if text1 does not appear in text2, otherwise, returns the number of characters in text2 where text1 appears, counting from 1. For example, offset("world", "Hello world") yields 7.
optionKey	Returns the current state of the option key (and/or 'meta' key on Unix hardware), either up or down. For example, repeat while the optionKey is up
param	Returns the value of the given numbered parameter (or, more accurately, it returns the parameter's argument). Use 0 to retrieve the name of the handler or function. For example, in the context of the function myFunction("V1","V2"), the param of 1 would yield V1; the param of 0 would yield myFunction.
params	Returns a comma-separated list of arguments passed to the given handler or function. For example, in the context of myFunction(1,2,3), the params would yield 1, 2, 3.
paramCount	Returns the number of parameters passed to the current handler of function.
random	Returns a random integer between 0 and the given argument. Example: the random of 100 or random(10).
result	Accepts no arguments and provides the value returned from a function or message handler, or the error status reported by certain commands.
screenRect	The rectangle of the screen on which the card is displayed, for example put item 3 of the screenRect into screenWidth
seconds	Returns the number of seconds since midnight, January 1, 1970 UTC.
selectedChunk	Returns a chunk expression in the form char x to y of container describing the active text selection; returns empty if no selection exists.
selectedField	Returns a chunk expression identifying the part containing the active selection, for example the selectedField yields card field id 13
selectedLoc	Returns the location (in card-relative coordinates) of the text insertion caret last active in a focused text field.
selectedLine	Returns a chunk expression identifying the line or lines in a field containing the active selection. For example, the selectedLine yields line 2 to 7 of background field id 4
selectedText	Returns the currently selected text within whichever field is in focus, or the empty string if no selection exists. For example, answer the selectedText
shiftKey	Returns the current state of the shift key, either up or down. For example, wait until the shiftKey is down
sin	Returns the trigonometric sine of the given argument, represented in radians.
speech	Returns the text currently being spoken via the speak command, or done if nothing is being spoken.
sqrt	Returns the square root of the given argument or NaN of the argument is negative.
sound	Returns the name of the currently playing sound, or done if no sound is being played.
stacks	Returns a line delimited list of currently open stacks. HyperCard orders this list by z-order; WyldCard guarantees no ordering.
sum	Returns the sum of the arguments. For example, sum(1,3,8) yields 9.
tan	Returns the trigonometric tangent of the given argument, represented in radians.
target	Returns a HyperTalk expression referring to the part that first received the current message. For example, the target might yield card button id 13. Note that the target is a function, but target is a container.
themes	Returns a comma-separated list of available Java Swing look-and-feels installed on this system. The function does not exist in HyperCard.
ticks	Returns the number of ticks (1/60th second) since the JVM was started.
time	Returns the time of day in a variety of formats. Use the time, the abbrev time, the abbreviated time or the short time to yield a time in the format 11:15 AM; use the long time or the English time for 11:15:27 AM.
tool	Returns the name of the currently selected tool. Example: if the tool is "brush" then answer "Happy painting!"
trunc	Returns the integer portion of the given numerical argument; for example the trunc of 8.99 yields 8.
value	Evaluates the given factor as a HyperTalk expression and returns the result. Example: the value of ("3" & "*4") yields 12.
voices	Returns a list of installed voices. This function is unique to WyldCard and does not exist in HyperCard.
windows	Accepts no arguments and returns a return-delimited list containing the name of every window in alphabetical order (note that HyperCard returns this list in Z-order; WyldCard guarantees no ordering).

Function handlers

A function handler is a subroutine scripted by the user that performs some action and optionally returns a value. More accurately, all user-defined functions return a value, but those which do not explicitly call return implicitly return empty.

Note that user-defined function handlers may not...

• Be invoked using the [the] <function> of ... syntax (like you'd use with a built-in HyperTalk function)
• Have the same name as another function in the same script, or the same name as a HyperTalk keyword. HyperTalk does not support function overloading (two functions with the same name but having different parameters).
• Be nested inside of other functions or handlers

If a function handler is not defined in the same script in which it is invoked, the message passing order is used to locate the function handler. Thus, if a card button attempts to invoke myFunction() and the button's script does not define function myFunction then the card's script is searched, then the background's, then the stack's. However, unlike message handlers, invoking a function for which no function handler exists results in a syntax error.

The syntax for defining a function handler is:

function <functionName> [<arg1> [, <arg2>] ... [, <argN>]]]
  <statementList>
  [return <expression>]
end <functionName>

When calling a user-defined function, use the syntax <functionName>(<arg1>, <arg2>, ...). The number of arguments passed to the function must match the number declared in the handler.

Consider this recursive function for generating the Fibonacci sequence:

on mouseUp
  answer fibonacci(empty, 0, 1, 200)
end mouseUp

function fibonacci sequence, lastValue, thisValue, maxValue
  if sequence is empty then put "0" into sequence
  put thisValue + lastValue after the last item of sequence

  if thisValue + lastValue <= maxValue then
    return fibonacci(sequence, thisValue, thisValue + lastValue, maxValue)
  else
    return sequence
  end if

end fibonacci