SuperCard Programming/Basics/Handlers & Functions

Handlers
Handlers in SuperCard are subroutines.

They begin with the "on" keyword, followed by the handler name. They end with the "end" keyword, also followed by the handler name.

Example: on calculateInterest -- other lines of code would be here end calculateInterest

Arguments
Handlers can take one or more arguments or parameters passed to them. These arguments should be included in the handler definition following the handler name and should be separated by commas.

Single Argument
Here's an example where a handler called "calculateInterest" takes a single argument "baseAmt" and multiplies it by an already defined global variable "gInterestRate" and stores it in an already defined global variable "gInterestAmt".

Example: on calculateInterest baseAmt global gInterestRate global gInterestAmt

put (baseAmt * gInterestRate) into gInterestAmt end calculateInterest

To call this handler in your code, you would do something like this:

Using a fixed, literal number: calculateInterest 5599

Or, like this, using a variable: calculateInterest preInterestAmt

Multiple Arguments
Here's an example where a handler called "calculateInterest" that takes two arguments, "baseAmt" & "interestRate", multiplies them and then stores the result in an already defined global variable "gInterestAmt".

Example: on calculateInterest baseAmt, interestRate global gInterestAmt

put (baseAmt * interestRate) into gInterestAmt end calculateInterest

To call this handler in your code, you would do something like this:

Using fixed, literal numbers: calculateInterest 5599,0.07

Or, like this, using variables: calculateInterest preInterestAmt,anInterestRate

Functions
Functions are also subroutines like handlers, however functions should return a value using the "return" keyword just before the "end [function_name]" line that terminates the function. SuperTalk doesn't enforce this. It will let you declare functions that do not return values, just as it will let you return values in handlers. However, it is good form to not return values from handlers and to use a function rather than a handler when you need to return a value. Following this convention will help you write code that is easier to follow, debug, and maintain.

Calling functions is slightly different than calling handlers. Calling a function generally requires that the function name be followed by a set of opening and closing parentheses, even if no arguments are being passed.

Here's an example of a function that takes no arguments: function piTimesTwo put pi * 2 into theResult

return theResult end piTimesTwo

To call this function you would do something like this: put piTimesTwo into doublePi

Or, you could use it without storing its results like this: if someOtherVariable > piTimesTwo then -- lines of code for a true result would go here else -- actions for the false result would go here end if

Notice that even though the "piTimesTwo" function takes no arguments, when it is called, its name is followed by a set of empty parentheses.

Arguments
Just like a handler, a function can take one or more arguments.

Single Argument
Building on the example above, here's a function to calculate interest that takes only one argument, multiplies it by an already defined global variable, but instead of storing the result in another global variable, it returns it:

function calculateInterest baseAmt global gInterestRate

put (baseAmt * gInterestRate) into theResult

return theResult end calculateInterest

You could call this function with a literal number like this: set tInterestAmt to calculateInterest(5995)

But, more realistically, you would probably pass it an amount stored in a variable: set tInterestAmt to calculateInterest(somePreInterestAmt)

Multiple Arguments
And, finally, here's a more realistic (although probably overly simplistic) example of a function that takes two arguments, multiplies them, and then returns the result. The advantage being, that you don't need a globally defined variable for the interest rate. The reason this is overly simplistic is that you would not need to define a function just to multiply two numbers and store the result, however, I'm sure you can envision creating functions that do much more than just multiply two numbers before they return a result.

Example: function calculateInterest baseAmt,interestRate put baseAmt * interestRate into theResult

return theResult end calculateInterest

Note: It is not actually necessary to place (baseAmt * interestRate) into a new variable called "theResult". The preceding function could have looked like this: function calculateInterest baseAmt,interestRate return (baseAmt * interestRate) end calculateInterest

To call the function using two values already stored in variables, you would do something like this: put calculateInterest(someAmt,someInterestRate) into someInterestAmt

Summary
Both handlers and functions allow you to define subroutines within your SuperTalk scripts.

Both handlers and functions can take:
 * no arguments
 * one argument
 * multiple arguments

Handlers begin with the "on" keyword followed by the handler name.

Functions begin with the "function" keyword followed by the function name.

Both handlers and functions are terminated with the "end" keyword followed by the handler/function name.

When calling a handler that takes one or more arguments, the argument(s) are placed after the handler name without any enclosing parentheses.

When calling a function with no arguments, it is best to follow the function name with an empty set of parentheses. And when calling a function with one or more arguments, the argument(s) must be enclosed in parentheses.

You should use functions to create subroutines that return a value using the "return" keyword followed by a variable name or a calculation.

You should use handlers to create subroutines that do no return a value.