



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   13
    ________________________________________________________________________


    CHAPTER TWO: PADTALK SCRIPTS


    CONSTRUCTING SCRIPTS

    In HyperPAD, scripts are written using the Script Editor. In order to
    access an object's script, the pad's user level must be set to
    scripting. (See the section on user levels in the HyperPAD User's Guide
    for additional information.)


    To access an object's script:

    1.  Make sure the pad's user level is set to Scripting.

    2.  Select the object with the Selector tool.

    In order to access a button or field's script, you must use the Selector
    tool and select the object.

    3.  Open the object's Info dialog box from the Objects menu.

    Depending on the type of object you are working with, select Pad, Bkgnd,
    Page, Button, or Field Info from the Objects menu.

    4.  Select the <Script...> button from the dialog box.

    The Script Editor will be loaded along with the object's script.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   14
    ________________________________________________________________________


    THE SCRIPT EDITOR

    The Script Editor is an environment that allows you to edit an object's
    script and then compile it. It looks like this: 

 Ŀ
                                                                        
  **** The Printed Documentation has a picture or screen shot here **** 
                                                                        
 
    


    EXITING THE SCRIPT EDITOR:

    To exit the Script Editor and return to the previous screen, use one of
    the following methods:

    1.  Press ESC. If you have made any modifications, you will be asked if
    you want to save them.

    2.  Select Cancel from the File menu. Any changes you made will be lost.

    3.  Select Save and Return from the File menu. This saves any changes
    and then returns to the pad.


    LET'S START SCRIPTING:

    Let's create a very simple script linking a newly created button to the
    Home pad. (If you are going to do the procedures, you should create a
    new pad and a new button.)


    To create a new pad:

    1.  Set the user level to scripting. (See the section on user levels in
    the HyperPAD User's Guide.)



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   15
    ________________________________________________________________________


    2.  Select the New command from the File menu.

    3.  Type in the name of your pad and press ENTER.

    A blank page will be placed on-screen.


    To create a new button:

    1.  Set the user level to scripting.

    2.  Select the Select tool from the Tools menu.

    3.  Select the New Button command from the Objects menu.

    A new button will appear on-screen.


    To go to the button's script:

    1.  Select Button Info from the Objects menu (or just press ENTER).

    2.  Select the button (or press ALT+S).

    First, access the button's script. When the Script Editor loads, you'll
    see that HyperPAD has already written part of the script for you.
    Because almost all buttons created in HyperPAD respond to being
    selected, each button's script, by default, provides an empty select
    handler.

 Ŀ
                                                                        
  **** The Printed Documentation has a picture or screen shot here **** 
                                                                        
 
    

    First, examine the script HyperPAD has provided, line by line:

    handler select;

    A handler is a portion of an object's script that defines what happens
    when a certain message is received. Each handler statement, like the one



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   16
    ________________________________________________________________________


    above, names the message the handler responds to (in this case the
    select message) and must end with a semi-colon. The name determines
    which message triggers the execution of this handler.

    For more information on messages see Chapter Ten.

    begin
    end;

    The begin and end statements enclose the list of actions that make up
    this handler. When the select message is received by this button, the
    action statements listed between the begin and end statements will be
    executed.

    handler select;
    begin
      [statements executed when the button is selected]
    end;

    Each begin statement must have a corresponding end statement in order
    for the handler to be valid. A semi-colon must follow the end statement,
    signifying the end of the handler.

    The blank line that HyperPAD has left is for the author to complete. In
    between the begin and end statements, fill in the actions to be taken
    when this button is selected. In this case, we want the user to change
    to the next page. To complete the handler, add the following line:

    go to the next page;

    HyperPAD does not distinguish between upper and lower case letters - it
    recognizes go to the next page; and Go To The Next Page; as the same
    statement.

    Every PADtalk statement within a begin...end block must end with a semi-
    colon. You can incorporate numerous commands to execute by inserting
    them between the begin and end statements. The full handler should
    resemble the following:

    handler select;
    begin
      go to the next page;
    end;

    We have just created a script with one handler that responds to the
    select message. If the user selects this button (by pressing ENTER or
    with the mouse) the handler will execute, changing to the next page in
    the pad.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   17
    ________________________________________________________________________


    Scripts can contain many handlers allowing objects to respond to a
    variety of messages. For example, the following script responds to three
    messages:

    handler select;
    begin
      go to the next page;
    end;

    handler mouseUp;
    begin
      beep;
    end;

    handler mouseEnter;
    begin
      hide the menu bar;
    end;


    WRITING STATEMENTS IN PADTALK

    Each PADtalk statement ends with a semi-colon. A begin...end block, like
    in the Pascal languages, is really a single compound statement (that's
    why there is a semi-colon after the end).

    PADtalk is a flexible language. It sometimes provides more than one way
    to perform the same action. For example, the following statements access
    the next page:

    go to the next page;

    go to next page;

    go next page;

    go to page (currentPage() + 1);

    In many PADtalk statements, like the go statement shown above, you can
    use the word the. The use of this word is optional and has no purpose
    except to enhance readability of your scripts. (The exception is with
    the alternate syntax of function calls.)

    You can add comments to your scripts by enclosing them in curly
    brackets. Any text within brackets is ignored by the compiler. The
    following example shows a comment enclosed in brackets.

    { this is a comment }
    go to the next page;



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   18
    ________________________________________________________________________


    Brackets can enclose many lines, shown in the following example:

    { this is a comment that
      takes up two lines }
    go to the next page;

    You can also enclose comments within other comments. The following
    example comments out a few statements that have comments:

    {
    go to the next page;  { change pages }
    beep;                 { emit a sound }
    answer "Find What?";  { ask user question }
    }

    You can add a comment to the end of a line by using two consecutive
    hyphens (--). The text between the two hyphens and the end of the line
    is ignored by the compiler. For example:

     -- this is a comment
    go to the next page;   -- this is a comment too!

    PADtalk is a verbose language that understands over 400 different words.
    Before exploring it, become comfortable within the Script Editor.


    USING THE KEYBOARD

    Press this key:             To:
    ------------------------------------------------------------------------
    UP and DOWN                 Move up or down one line in a script

    LEFT and RIGHT              To move left or right on a line in a script

    HOME                        Go to the beginning of a line

    CTRL+HOME                   Go to the beginning of the script

    END                         Go to the end of the line

    CTRL+END                    Go to the end of the script

    CTRL+RIGHT or CTRL+LEFT     Move forward or backward one word

    BACKSPACE                   Delete the previous character

    DEL                         Delete the character under the cursor

    CTRL+Y or CTRL+D            Delete the current line

    CTRL+BACKSPACE              Delete the previous word



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   19
    ________________________________________________________________________


    Press this key:             To:
    ---------------------------------------------------------
    SHIFT+ARROWS                Select text

    ESC or CTRL+Q               Exit with a check to save changes

    CTRL+C or CTRL+INS          Copy selected text

    TAB                         Inserts space up to next tab stop

    PGUP or MINUS (keypad)      Move up one page

    PGDN or PLUS (keypad)       Move down one page

    CTRL+X or SHIFT+DEL         Cut text

    CTRL+V or SHIFT+INS         Paste text

    CTRL+DEL                    Delete to the end of the line

    CTRL+F                      Find a string

    CTRL+R                      Find and replace text

    CTRL+N                      Find next occurrence of the string

    F4                          Compile the script, checking for errors

    F10                         Open the menus


    EDITING A SCRIPT

    In the Script Editor, you can copy and move blocks of text within a
    script or even between scripts.

    Before you can using any of the editing features, you have to select the
    text you want to perform the operation on.


    To select text:

    1.  Place the cursor on the first character of the selection.

    2.  Hold down SHIFT and use the arrow keys to extend the selection.

    3.  When you've highlighted the entire selection, release the keys.

    To use the mouse, place the mouse pointer where you want to begin your
    selection. Hold down the left mouse button and drag the mouse until
    you've highlighted the selection. Then, release the mouse button. Once
    the text is selected, you can copy, cut, or delete it.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   20
    ________________________________________________________________________


    To copy text:

    1.  Select the text.

    2.  Select the Copy command from the Edit menu (ALT+E, C).


    To cut text:

    1.  Select the text.

    2.  Select the Cut command from the Edit menu (ALT+E, T).


    To paste text:

    1.  Position the cursor where you want to place the text.

    2.  Select the Paste command from the Edit menu (ALT+E, P).

    The contents of the clipboard will be inserted in the script.


    SEARCH AND REPLACE

    As you become more comfortable with PADtalk, your scripts will become
    longer and more complex. To reduce the amount of time and effort
    necessary to locate text, HyperPAD includes Search and Replace commands.


    To locate a string in a script:

    1.  Select the Find command from the Search menu (ALT+S, F).

    The Find dialog box will appear on screen.

    2.  Type in the string you want to locate and press ENTER.


    To locate the next instance of a string:

    1.  First complete the above procedure.

    2.  Select the Find Next command from the Search menu (ALT+S, N).

    To keep looking for that string, continue to select the Find Next
    command. CTRL+N is the shortcut for this command.

    Sometimes, you may need to replace a string in a script with another.
    Use the Replace command to locate the instance and replace it with what
    you've specified.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   21
    ________________________________________________________________________


    To search and replace within a script:

    1.  Select the Replace command from the Search menu.

    2.  Enter in the search and replace text, then select:

    Verify - Allows you to confirm each replacement.

    Replace - Replace the text and continue.

    Skip - Continue without replacing the text.

    Cancel - Stop the procedure.


    PRINTING SCRIPTS


    To print the scripts in your pads:

    1.  Select Printer Setup from the File menu and complete the dialog box
    so the options conform to your system. If your printer is not listed,
    select the Generic Printer, or another that your printer can emulate.

    2.  Select Page Setup from the File menu and make sure the settings are
    correct.

    3.  Select the Print command from the File menu.


    COMPILING SCRIPTS

    Before HyperPAD can use your scripts, they must first be compiled.
    HyperPAD compiles and saves your script when you exit the Script Editor.

    As it compiles, HyperPAD scans the script, checking for syntax errors.
    HyperPAD is only able to pass messages to handlers in scripts that have
    been successfully compiled without any errors.

    You can manually check for errors before exiting the Script Editor by
    selecting Compile from the Edit menu (or press F4). If there is an
    error, HyperPAD will assist you by positioning the cursor at the
    location of the error and displaying an error message.


    COMPILING WITH THE DEBUGGING SWITCH

    Runtime errors occur when something goes wrong in a script while
    browsing your pad. Normally, HyperPAD will take you to the offending
    script so that you can correct the problem. With larger scripts that
    contain many handlers, it may be difficult to locate the source of a
    runtime error.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   22
    ________________________________________________________________________


    To assist you in locating runtime errors, you can turn on the Debug
    option on the Edit menu. When you compile the script with the Debug
    option on, HyperPAD includes line number information with the compiled
    code. Then, following a runtime error, HyperPAD places the cursor
    directly on the line in which the error occurred. If you compile with
    the Debug option off and a runtime error occurs, HyperPAD simply places
    the cursor at the top of the offending script.


    THE COMPONENTS OF A SCRIPT

    A script consists of handlers, which you were introduced to above, and
    functions, which will be introduced in this section.


    HANDLERS

    As you have learned, a handler is a portion of a script that is invoked
    when a specific message is received by the object that contains it. Each
    handler names the message it responds to and includes some action(s) to
    be taken when that message is received.

    Here is a more complex handler. It receives two parameters from the
    statement that calls it.

    handler calcResult(i,j);
    begin
      put i * j / 100 into the message box;
    end;

    Sometimes, you may want a handler to receive a variable number of
    parameters. In this case, it is necessary to know how many parameters
    were passed to your handler and what each of them are. This is
    accomplished using the functions param, paramCount, and params. These
    functions return information about the number of parameters that were
    passed to your handler, the entire parameter list, and what each
    parameter is. The following function sums its parameters and returns the
    total to the calling statement.

    function addNums;
    begin
      put 0 into total;
      for i = 1 to the paramCount do
        add param(i) to total;
      return total;
    end;

    Notice that this example doesn't declare any parameter variables.
    Instead, it accesses the parameters using the param function.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   23
    ________________________________________________________________________


    DEFINING YOUR OWN FUNCTIONS

    In addition to handlers, scripts can contain your own functions. A
    function is a group of statements that returns a single value. Functions
    can be called from other handlers in the same script, or from scripts
    higher in the message hierarchy.

    For example, the following function asks a question in a dialog box
    using the answer command, then returns the result to the caller using
    the return statement.

    function okToContinue;
    begin
      answer "Is it safe";
      return it;
    end;

    The return statement defines the number or text value that the function
    will return to the calling statement. The return statement will not stop
    execution of the handler (only exit and pass stop the execution of a
    handler). If you specify more than one return statement, the last return
    statement executed will determine the returned value of the function.

    Calling your own functions is just like calling HyperPAD's built-in
    functions. The following statements call the function defined above:

    put okToContinue() into res;
    if okToContinue() is "Cancel" then beep;
    put "You selected" & okToContinue();

    The open and close parenthesis are used to distinguish a function call
    from a message name. The statement

    okToContinue;

    is a message name that gets sent to the current script, where as

    okToContinue()

    calls the user-defined function.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   24
    ________________________________________________________________________


    The following example function counts the number of Bs in a passed
    parameter.

    function countBs(str);
    begin
      put 0 into total;
      for i = 1 to the length(str) do
        if char i of str is "B" then add 1 to total;
      return total;
    end;

    To call this function:

    put 5 + countBs("Bobby and Billy when out.");


    OTHER DEFINITIONS

    The following definitions are intended to introduce you to other PADtalk
    components used when writing scripts.


    COMMANDS

    Commands are statements that tell HyperPAD what to do. Each command ends
    with a semi-colon. For example:

    go to page 1;

    put "wow" into page field 1;

    HyperPAD's built-in commands are discussed in Chapter Eleven.


    CONSTANTS

    A constant is any named value that can't be changed. Unlike a variable,
    you can not alter a constant, and unlike a literal, its value is not
    always identical to its name. The following tables summarize HyperPAD's
    constants and their corresponding values.



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   25
    ________________________________________________________________________


    MISCELLANEOUS CONSTANTS

    The miscellaneous constants are:


    Constant:             Description:
    ----------------------------------------------------
    empty                 Empty String ""

    false                 Boolean value false

    true                  Boolean value true

    pi                    The mathematical constant 3.14159

    up                    Returned by ctrlKey(), altKey(), and shiftKey()

    down                  Returned by ctrlKey(), altKey(), and shiftKey()


    CHARACTER CONSTANTS

    The character constants are:


    Constant:             Description:
    ----------------------------------------------------
    formfeed              ASCII 12

    linefeed              ASCII 10

    quote                 ASCII 34(")

    return                ASCII 13

    space                 ASCII 32(" ")

    tab                   ASCII 9



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   26
    ________________________________________________________________________


    PROPERTY CONSTANTS

    The property constants are:


    Constant:             Used with this property:
    ----------------------------------------------------
    centered              align

    checkBox              style

    even                  parity

    fat                   cursor

    layer                 tabbing

    left                  namePosition, align

    listBox               style

    none                  parity

    odd                   parity

    off                   cursor, printer, mouse

    on                    mouse, printer

    opaque                style

    position              tabbing

    right                 align

    scrolling             style

    thin                  cursor

    top                   nameposition

    transparent           style


    NUMERIC CONSTANTS

    The following constants can be used in place of any number to enhance
    readability of your scripts. The numeric constants are:

    zero          three        six          nine
    one           four         seven        ten
    two           five         eight



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   27
    ________________________________________________________________________


    LITERALS

    A literal is a number or text string enclosed in quotes. The following
    are literals:

    10
    17.39
    "hello"

    Special codes can be inserted into quoted text strings for characters
    that you can't easily type with the keyboard. Each code is started with
    the caret (^). The following table shows the supported codes and lists
    some examples:


    Code:       Value:
    ----------------------------------------------------
    ^^          ^

    ^"          "

    ^f          formfee (ASCII 12)

    ^n          linefeed (ASCII 10)

    ^t          tab (ASCII 9)

    ^r          carriage return (ASCII 13)

    ^d<n>       ASCII character n (where n is the 3 digit character number)

    ^x<n>       ASCII character n (where n is the hex character number)

    Examples:

    "The quick brown ^"fox^" jumped over the lazy dog"

    "^rThis is a new line"

    "square character ^d254 inserted here"

    "hex ^xf4 insert here"



     _______________________________________________________________________
                                         Chapter 2: PADtalk Scripts   28
    ________________________________________________________________________


    FUNCTIONS

    HyperPAD contains many built-in functions, each of which return a single
    value. Some functions require you to pass some parameters. The following
    are a few of HyperPAD's built-in functions:

    min(10,12)

    time()

    files("*.DOC")

    HyperPAD's functions are discussed in Chapter Thirteen.


    PROPERTIES

    Properties are values that control how objects look and behave. All
    objects of the same type have the same properties, but each object has
    its own values for these properties. Color, for example, is a property
    of buttons. All buttons have the color property and all buttons may be a
    different color. The following are properties:

    lockText

    insertPoint

    hilite

    Object properties are discussed in Chapter Twelve.


    CONTAINERS

    A container is a storage place for a value. The following are
    containers:

    fields

    variables

    the message box

    selectedText

    Containers are discussed in Chapter Four.
