



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   29
    ________________________________________________________________________


    CHAPTER THREE:  THE OBJECT HIERARCHY

    Each handler, whose components were discussed in the preceding chapter,
    depends on receiving a specific message in order to execute its
    statements. This section describes HyperPAD's message passing system,
    how messages are sent to objects and what happens when the messages are
    received by objects.

    The type and nature of the message and the current object at the time
    the message was generated determines which object  receives the message
    first. The receiving object may or may not have a handler for that
    message. If it does, then the handler for that message executes and the
    message stops its travel. If the object does not have a handler for that
    message, then the message is passed on to the next object in the
    hierarchy. This process continues until there is either a handler for
    that message or the message reaches HyperPAD.

    The types of messages and the path that the messages take during their
    travel through HyperPAD (the hierarchy) are discussed in this chapter.



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   30
    ________________________________________________________________________


    SENDING MESSAGES

    Within HyperPAD, script execution is initiated by messages sent to
    objects. Messages are HyperPAD's way of "telling" the objects what's
    taking place in the environment. Messages are sent:

        0  When an event occurs (like a key being pressed or mouse button
           being clicked).

        0  When the user executes a statement from the message box.

        0  When certain commands are executed from within a script, such as:
           beep.

        0  When the user selects a menu command.

        0  When the system is idle.


    WHERE DO MESSAGES GO?

    When an object receives a message, one of two actions is taken. If the
    object has a handler for that message, the handler is executed and the
    message travel is stopped.

    If the object doesn't have a handler for the message, then the message
    is sent to the next object in the object hierarchy. The message will
    continue along in this manner until it encounters a handler for itself,
    or reaches HyperPAD. The following diagram summarizes the path taken by
    a message through HyperPAD:



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   31
    ________________________________________________________________________


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



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   32
    ________________________________________________________________________


    The object with the focus receives the message first, which will usually
    be either a page, button, or field. For example, if a button is
    highlighted and the user selects it (by pressing ENTER) a
    select message is sent to the button. If the script doesn't have a
    select handler, the message is sent to the page, and on up the hierarchy
    until a handler is found or the message reaches HyperPAD.

    If the message reaches HyperPAD, one of three actions is taken.

    1.  The message will be ignored. This happens when there is no handler
    for a system message.

    2.  The message will be interpreted by HyperPAD. This happens, for
    example, with the quit message.

    3.  An error will be displayed indicating that HyperPAD didn't
    understand the message.


    TYPES OF MESSAGES

    The types of messages that are sent are discussed in this section.


    SYSTEM MESSAGES

    The most common messages passed through HyperPAD are system messages.
    These messages are sent to an object in response to a user-generated
    event. For example, if the pad user presses the left mouse button, the
    mouseDown message is sent to the object under the mouse pointer. Because
    system messages are generated by the pad user, the messages are
    initially sent to either the current page, button, or field. The object
    that first receives the message is called the target.

    There are two types of system messages:

    1.  Notification messages. These are messages that result from an action
    in the system and whose purpose is to notify a script that an action has
    occurred. Some examples are:

    openPage, mouseUp, newPad

    Creating handlers for these messages lets you specify actions to be
    performed after the user has completed an action in HyperPAD. For
    example, a mouseUp handler can be used to trigger some actions after the
    mouse button has been physically released.

    2.  Normal messages. These messages are sent before any actions have
    been taken and result in an action occurring when the message reaches
    HyperPAD. Normal messages are those that HyperPAD understands, such as
    doMenu, quit, help, beep, and deletePage. For example, if you select



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   33
    ________________________________________________________________________


    Delete Button on the Edit menu, then the deleteButton command is sent to
    that button. Only when this message is received by HyperPAD will the
    button be deleted.

    By creating handlers for these messages, you can control different
    aspects of HyperPAD. For example, the following handler intercepts the
    quit message asking if it is ok to quit. If the user selects Ok, the
    handler passes the message on (so that it will reach HyperPAD and you'll
    exit to DOS). If not, the message stops and HyperPAD doesn't quit.

    handler select;
    begin
      answer "Ok to quit?";
      if it is "Ok" then pass;
    end;


    MESSAGES FROM SCRIPTS

    Within your scripts, you can send messages. For example:

    handler select;
    begin
      CalculateResult;
    end;

    The message calculateResult will be sent to the script of the currently
    executing object. If there is a handler called calculateResult somewhere
    in the message path, it will then be executed.


    MESSAGE BOX MESSAGES

    The message box provides a way of executing statements immediately
    without having to type in a script. When you type in a command and press
    ENTER, one of the following will occur:

    1.  If you typed in a command, it will be executed (except the do
    command and any begin...end block).

    2.  If you typed in a message and parameters, the message will be sent
    to the current page. If there is a handler for the message, it will be
    executed. If there is no handler, and HyperPAD doesn't recognize the
    message, an error is displayed.

    3.  If a valid expression was entered, it is evaluated and the result is
    placed into the message box.



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   34
    ________________________________________________________________________


    MESSAGES THAT LOOK LIKE COMMANDS

    Some commands within scripts are implemented as messages. This may seem
    confusing. For example, you may, at first, be unable to determine if the
    following statement is a command or a message:

    beep;

    In fact, this is a command that sends a message called beep. When this
    message reaches HyperPAD, a sound is emitted from the system speaker.

    All of these special messages are noted in the Chapter Ten.


    RECEIVING AND SENDING MESSAGES

    As you learned above, the initial receiver of a message depends on the
    type and nature of the message as well as which object is currently
    selected when the message is generated.

    As senders and receivers of messages, all objects work the same. The
    type of object has no effect on the execution of the script. The
    following outlines the procedure taken when an object receives a
    message:

    First, the script is searched for a handler that corresponds to the
    message. If a match is located, that specific handler is executed. After
    a handler executes, the message stops its travel up the hierarchy unless
    it is passed with the pass command. If no matches are found, the message
    is passed to the next object up the hierarchy.



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   35
    ________________________________________________________________________


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


    THE EXIT COMMAND

    The exit command stops execution of a handler before the last statement
    of the handler has executed. In the following example, the statements
    following the exit statement will never be executed:

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

    The exit command terminates that message's travel through the hierarchy.
    If you want to stop the execution of all pending handlers, use the exit
    to hyperpad command. This command is similar to the user pressing
    CTRL+BREAK.



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   36
    ________________________________________________________________________


    The following example uses the exit to hyperpad command to stop the
    display of a sequence of screens. The checkContinue handler below does
    this by stopping all pending handlers, including the calling handler, at
    the user's request.

    handler checkContinue;
    begin
      answer "Is it ok to continue?";
      if it is "Cancel" then exit to hyperpad;
    end;

    handler select;
    begin
      go to the next page;
      checkContinue;
      go to the next page;
      checkContinue;
      go to pad "phone";
      checkContinue;
      go home;
    end;


    THE PASS COMMAND

    The pass command enables a handler to send the message to the next
    object in the hierarchy, as if the current handler hadn't received it.
    For example, consider the following scripts:

    Script:                 Description:
    ---------------------------------------------------------
    handler select;         This message will stop here, and
    begin                   will not go on to the next level in
      :                     the message path.
    end;

    handler select;         This script intercepts the message,
    begin                   performs some actions, and then
      :                     passes the message on to be handled
       pass;                by other objects higher in the
    end;                    hierarchy.



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   37
    ________________________________________________________________________


    The pass command stops execution of a handler. For example, in the
    following script, the beep statement never gets executed:

    handler select;
    begin
      pass;
      beep;
    end;

    Make sure you position the pass statement as the last statement in the
    script you want executed.


    ALTERING THE MESSAGE PATH

    Messages are normally passed by default up the hierarchy, never across
    to other objects on the same level. With the send command, however, you
    can redirect messages to objects outside the normal hierarchy, such as
    those objects on another page, or lower in the hierarchy.

    For example, the following handler redirects the mouseUp message to a
    button on another page:

    handler mouseUp;
    begin
      send "mouseUp" to button "Help" of page 2;
    end;



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   38
    ________________________________________________________________________


    If the receiving object does not contain a handler for that message, the
    message will proceed to travel up that object's hierarchy (not the
    hierarchy of the sending object).

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



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   39
    ________________________________________________________________________


    Messages sent from a script travel up the path of that sending object.
    This is important to remember in cases like the following:

    handler mouseUp;
    begin
      go to pad "B";
      calculateTotals;
    end;

    Even though the pad has been changed (to pad "B"), the message
    calculateTotals still travels the message path of the original pad.


    WHERE TO PUT YOUR HANDLERS

    Considering all of the stops a message makes on its journey along the
    message path, it may at first be difficult to decide where to put your
    handlers. For example, should you put a handler in the script of a
    button, a  page script, the corresponding background script, the pad
    script, or maybe in the Home pad script? To answer this question, you
    need to determine which objects need to use this handler. Then you will
    know exactly where to locate your handlers.

    Simply put, your handlers should be located in the script of the object
    lowest in the hierarchy and still be accessible to all the objects that
    need that handler.

    For example, if you have a single button that, when selected, takes you
    to the next page, you would create a handler in the script of the
    button.

    Suppose that you have 10 buttons on the page and you want the pad user
    to be able to click on any button and go to the next page. Instead of
    including this handler in the script of each of the ten buttons, you
    could put the handler into the script of the page. Thus, all buttons on
    the page would respond to the select message using the same handler.
    (Remember that if an object doesn't have a handler for a message, it is
    passed on to the next layer...in this case, the page.)

    In the next case, suppose that you have a handler called calcResult that
    you would like to access from several different pages which are all on
    the same background. Instead of including the handler in each page
    script that requires it, you could put the handler in the background
    script, making it accessible to every page that uses that background.

    Next, suppose that the calcResult handler is used in many different
    pages, buttons and fields throughout your entire pad, even from
    different backgrounds. In this case, you would want to put the handler
    in the pad script, making it accessible to each object in the pad.



    ________________________________________________________________________
                                    Chapter 3: The Object Hierarchy   40
    ________________________________________________________________________


    In the last case, suppose that the calcResult handler was used in many
    of your pads. Depending on how often it is used, you may want to copy it
    into each pad that uses it. Another approach is to put the handler in
    the pad script of the Home pad. This makes the handler accessible to all
    of your pads. You must be careful, however, to keep this script small
    and efficient because it is always loaded (thus requiring more memory).
