© Copyright 2000 Handwave Inc. All Rights Reserved.

Action Pad User Manual

1. Overview

Action Pad extends the built-in Memo Pad application with the ability to evaluate expressions contained in memo text. Highlight a portion of a menu containing an expression, tap the "Show" button and see the answer inserted into the memo. Action Pad includes all of the standard Memo Pad functionality, so you already are familiar with most of its features.

Action Pad uses the arithmetic operators +, -, * and /, with parentheses to control evaluation order. You will find that entering simple expressions will generally produce the results you expect.  Try entering the text 3 + 4, highlight it and tap the Show button.  If you see 7, congratulations, you've learned how to create live memos.  For complex expressions and creating your own functions, see the HandScript Language specification.

Action Pad also adds a menu item for "cloning" memos and a Function Finder dialog for organizing HandScript source code. Action Pad includes pre-built scripts for saving and restoring memo categories and function libraries.

2. Included Materials

The following files are included with Action Pad:

File NameFile Purpose
Action Pad.prcThe Action Pad application.
Functions-APAD.pdbSource code to the functions supplied with Action Pad.
Scenarios-APAD.pdbSample memos with useful example expressions.
MathLib.prcThe C library of mathematical functions. These are needed to use the Action Pad "math" library.
ActionPadManual.htmlThe file you are reading.
ActionPadLanguage.htmlA description of the HandScript language.
ActionPadLicense.htmlThe Action Pad license agreement.
readme.htmlRead this first

If you have an earlier version of Action Pad, delete it before installing this version.  HotSynch the 2 .prc files and the 2 .prb files to your organizer.

3. Action Pad Support for the Palm Keyboard

The Palm keyboard has built-in support for "tapping" buttons and selecting text in text fields, but it does not support selecting items in lists or tables.  If you have the Palm keyboard, Action Pad enables you to browse the lists of memos and functions using keyboard keys and without using the stylus.

3.1 Navigating the Memo List with the Keyboard

The Fn+Scrollup and Fn+Scrolldown keys scroll the list of memos up and down, respectively.  The Up-arrow and Down-arrow keys cause the top list entry to be highlighted when no entries are highlighted, and move the highlight to the next entry up or down respectively, when an entry is already highlighted.  The enter key selects the currently highlighted memo.

3.2 Navigating the Function Lists with the Keyboard

The Function Finder form has two lists: the list of function libraries on the left and the list of functions in the selected (highlighted) library on the right.  You move the highlight in the library list up and down using the Fn+scroll keys. You move the highlight in the function list up and down with the Up-arrow and Down-arrow keys.  You select the currently highlighted function with the enter key.

4. Action Pad for Non-Programmers

4.1 Show Button

The Memo Pad memo edit form is extended with a "Show" button.  Highlight text to evaluate and tap the Show button.  The results of the evaluation are displayed highlighted immediately following the evaluated text.

There is a series of examples of evaluations in a database named "Scenarios-APAD".  HotSync this database to your organizer, then enter the following text in some memo:
    memo.restore("Scenarios-APAD")
Highlight this text and tap the Show button.  This will load a series of memos into your memo database under the Scenarios category.  Now you can experiment with a diverse set of pre-built examples.  Load each of these memos, then for each example highlight the example text and tap the Show button.

Error Reporting

There are two kinds of errors that are reported: syntax errors and evaluation errors.  A syntax error means the form of the text is invalid, such as mismatched parentheses [e.g., "(2.3*4" ].  An evaluation error means that an incorrect value was encountered during evaluation, such as divide by zero.  For syntax errors, a dialog describing the error pops up.  When the error dialog is dismissed, the insertion point is set in the memo at the point of the syntax error, so you can correct it.  For evaluation errors, a dialog describing the error pops up.  This dialog includes the function call stack (the list of functions that have been called but have not yet returned), helping to pinpoint the source of the error.

4.2 Cloning Memos

The Memo Pad edit form Record menu has an additional item: "Clone Memo".  Selecting this menu item results in the creation of an identical copy of the current memo.  This is useful for creating a series of memos that have similar calculations.  An original memo can be cloned, and the clone modified to have some operands and operations different than the original. 

5. Action Pad for Programmers

5.1 Action Pad Functions

The HandScript language doesn't define any built-in functions.  Without any functions, HandScript is sufficiently complete to compute useful results within memos. Functions allow you to extend the language any way you choose.

There is a set of functions included in source form with Action Pad in database Functions-APAD.pdb.  These support basic math operations, and source code and memo copying to and from databases.

Math Functions

The math support provides basic trig support and other functions implemented in the MathLib shared library.  For a list of functions, pop up the function finder (see below) and select the "math" library.

MathLib is a free shared library (implemented in C) that can be used by any Palm OS 2.0+ program that needs IEEE 754 double precision math functions.  It's distributed under the terms of the GNU Library General Public License, and is freely available with full source code and documentation at the MathLib Information web page.  It's not a part of the Action Pad program, and you're not paying anything for its use; a copy is simply included with Action Pad for your convenience.

Source Code Mangement

The source code management support implements save and restore operations on the functions database.  The save operation copies source code for one or more libraries from the functions database to another database.  The restore operation is the inverse of save.  It copies a database of source code to the functions database (Functions-APAD.pdb).  Note that if a function with the same name appears in both databases, restore replaces the one in the Functions-APAD database.

Memo Management

The memo management support similarly implements save and restore operations on the memo database.  The save operation copies all memos in named category from the memo database to another database.  The restore operation copies all memos in a saved database back to the memo database and assigns them to the category name in which they were saved.

Action Pad Libraries

A library is defined to be all functions that have the same characters preceding the dot (".") character in the function name.  Therefore, for example, math.sin and math.cos belong to the same library.  The currently included Action Pad function libraries are:

Library NamePurpose
dbdatabase metadata functions
mathelementary math functions
memomemo save/restore functions
scriptfunction library sav/restore functions
stringelementary string support
_Categoryselected Palm OS category functions
_Dmselected Palm OS data manager functions
_Memselected Palm OS memory manager functions
_Strselected Palm OS string manager functions
_Sysselected Palm OS system manager functions
_Timselected Palm OS time manager functions

For a list of functions in each library, use the function finder and select a library name to see which functions the library contains.

Naming Convention

A naming convention is used to distinguish higher-level functions that a user might directly invoke (with the action button from a memo), and lower level functions that are not likely to be directly user invoked.  Lower level functions have their names prefixed with an underscore in two ways.  If all functions in a library are low-level, the library name begins with underscore (e.g., the _Dm. library).  If only a subset of functions in a library are low-level, the low-level functions have an underscore after the period separating library and function name (e.g., memo._open(dbname)).  This convention causes high-level functions to sort above low-level ones in the Function Finder browser.

Palm OS trap calls are all considered low-level, so their library names all begin with underscore. A further convention is that Palm OS calls use the subsystem name as HandScript library name.  For example, memory manager call MemHandleLock(handle) becomes _Mem.HandleLock(handle), organizing it into the "_Mem" library.

5.2 Function Finder

The function finder dialog presents all functions contained in the Functions-APAD database organized into libraries.  Tap the button labeled "f(x)" to popup the function finder.  There are two lists: libraries on the left, and functions within the selected library on the right.  There are four buttons at the bottom: OK, New, Call and View which do the following:

ButtonAction
OKReturns to the form previously viewed.
NewEnters the function editor with a prototype function definition for the selected library.
CallIf the previous form was the edit form, inserts a call into the edit form replacing the current selection.
ViewEnters the function editor displaying the selected function.

5.3 Function Editor

The function editor is entered from the function finder form upon tapping the New or View buttons.  The function editor displays a single function at a time.

Action Pad maintains two memo databases: MemoDB defined by the standard Memo Pad, which contains one memo per record, and Functions-APAD which contains function source code, one function per record.  MemoDB has creator ID "memo", which is the creator ID of the built-in Memo Pad.  Functions-APAD has creator ID "APAD, the creator ID of Action Pad.

The function editor behaves like the memo editor with the following two exceptions: Note that it is not required to syntax check functions in the function editor.  But if there is an attempt to evaluate a function that contains syntax errors, this error will be reported at runtime.  Therefore, to detect errors sooner, tap the syntax check button before exiting the function editor. 
© Copyright 2000 Handwave Inc. All Rights Reserved.