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.