



    ________________________________________________________________________
                                             Chapter 12: Properties   145
    ________________________________________________________________________


    CHAPTER TWELVE:  PROPERTIES


    INTRODUCTION

    This chapter describes how properties are used in the HyperPAD system.
    The first section describes the global properties. The next five
    sections describe the properties of pads, buttons, fields, pages and
    backgrounds. The final four sections describe the properties of the
    message box, tool box, status bar, and menu bar.


    WHAT ARE PROPERTIES

    A property is a characteristic of an object that defines its appearance
    and behavior. Objects of the same type (such as all buttons) have the
    same properties. Each button, however, can have different values
    associated with these properties. An example of a button property is
    fillColor, whose value is a number between 0 and 255.

    Objects are created with default values for their properties. You can
    alter a property value in one of two ways. Many property values are
    accessible using the object's Info dialog box on the Objects menu. The
    other way to modify an object's property value is with the PADtalk
    language, which gives you access (using the set command) to all object
    properties.



    ________________________________________________________________________
                                             Chapter 12: Properties   146
    ________________________________________________________________________


    PROPERTY LISTINGS


    GLOBAL PROPERTIES

    The global properties are:

    asciiChar          lockRecent          paintAttr
    autoSave           lockScreen          parity
    baud               markerAttr          printDevice
    currentDirectory   markerChar          printer
    cursor             maxDirtyPages       printerTranslation
    cursorLoc          modem               selectedText
    dataBits           mouse               stopBits
    fileSortMethod     mouseAttr           tabbing
    focus              mouseChar           userLevel
    lockMessages       numberFormat


    PAD PROPERTIES

    The pad properties are:

    cantDelete         cantModify          longName
    name               passwordOnly        script



    ________________________________________________________________________
                                             Chapter 12: Properties   147
    ________________________________________________________________________


    PAGE PROPERTIES

    The page properties are:

    cantDelete         id                  longID
    longName           name                script


    BACKGROUND PROPERTIES

    The background properties are:

    cantDelete         id                  longID
    longName           name                script


    BUTTON PROPERTIES

    The button properties are:

    acceleratorColor   hilite              name
    acceleratorKey     hiliteColor         rectangle
    align              hiliteIfFocus       script
    autoHilite         id                  shadow
    borderColor        layer               showName
    check              location            style
    color              lockText            visible



    ________________________________________________________________________
                                             Chapter 12: Properties   148
    ________________________________________________________________________


    FIELD PROPERTIES

    The field properties are:

    acceleratorColor   hiliteIfFocus       nameColor
    acceleratorKey     id                  namePosition
    align              insertPoint         rectangle
    autoHilite         layer               script
    borderColor        listbox             scrollable
    color              location            showName
    currentLine        lockText            startLine
    edgeType           longID              style
    fillColor          longName            value
    hilite             markedLines         visible
    hiliteColor        name                withEdge


    MESSAGE BOX PROPERTIES

    The message box properties are: 

    location           value               visible
    width


    TOOL BOX PROPERTIES

    The tool box properties are:

    location           visible


    MENU BAR PROPERTIES

    There is one menu bar property:

    visible


    STATUS BAR PROPERTIES

    There is one status bar property:

    visible



    ________________________________________________________________________
                                             Chapter 12: Properties   149
    ________________________________________________________________________


    GLOBAL PROPERTIES

    -----------------------------------
    ASCIICHAR

    Purpose: This property allows the user to set and get the value of the
    ASCII paint character. The range of available values is from 0 to 255.
    You can also set or get this property by selecting ASCII char from the
    Workspace menu.

    Examples:

    set the asciiChar to charToNum("A");

    set the asciiChar to 65;

    if the asciiChar is charToNum(the first char of it) then
      answer "they are the same";

    The following handler demonstrates a use of asciiChar:

    handler select;
    begin
      doMenu "Text";
      doMenu "ASCII char...";
      answer "you picked" && the asciiChar with "Ok";
    end;

    See Also: paintAttr

    -----------------------------------
    AUTOSAVE

    Purpose: By default, HyperPAD automatically saves your work every 30
    seconds. With autoSave, you can regulate (turn on or off) this feature.

    HyperPAD stores pages in a memory cache for quick access. If you modify
    a page in some way (i.e. type into a field or change the color of an
    object), the page is considered "dirty". The cache can't hold more than
    50 pages. If the cache fills up, the pages accessed least are removed
    from the cache.

    The maximum number of dirty (modified) pages allowed in the cache is
    determined by the maxDirtyPages property, which is 20 by default. When
    the number of dirty pages exceeds this number, they are saved to disk.
    The dirty pages will also be saved to disk if HyperPAD runs low on
    memory.



    ________________________________________________________________________
                                             Chapter 12: Properties   150
    ________________________________________________________________________


    If autoSave is true, then every 30 seconds HyperPAD saves as many dirty
    pages as it can in 1 second. The disk access occurs at idle time (at the
    end of all pending handlers). If autoSave is false, then the cache is
    emptied when one of two conditions is met: when the number of dirty
    pages exceeds maxDirtyPages, or when memory is low enough to require the
    space that the dirty pages are taking up.

    When to use it: Setting maxDirtyPages to 1 and autoSave to false is the
    safest environment for running HyperPAD. However, it accesses the disk
    constantly and is therefore slower.

    Examples:

    set the autoSave to true;

    set the autoSave to false;
    set the maxDirtyPages to 2;

    To set the autoSave to false every time you start HyperPAD, put the
    following handler in the pad script of your Home pad:

    handler startup;
    begin
      set the autoSave to false;
    end;

    Comments: The autoSave property is true by default.

    When autoSave is true:

    1.  You stand to lose less information if there's a power failure.

    2.  Disk access is kept to a periodic short burst.

    3.  Disk space is monitored closely, and you are notified when disk
    space is low.

    When autoSave is false:

    1.  Disk access is less frequent, but takes more time when it does
    occur.

    2.  Thrashing (continual disk accessing) can occur, depending on your
    application. For example, if there are 50 pages in the cache that need
    to be saved to disk, every time you switch to a new page, a page from
    the cache has to be saved, causing the disk to be accessed.

    3.  Since disk space is determined after each write, you may have
    information that needs to be saved to disk when there is insufficient
    disk space.

    See Also:  maxDirtyPages



    ________________________________________________________________________
                                             Chapter 12: Properties   151
    ________________________________________________________________________


    -----------------------------------
    BAUD

    Purpose: Sets the baud rate for use with the dial command. You can set
    the baud property to any baud supported by your modem (300, 1200, 2400,
    9600). The dial command will not work if you set baud to an unusable
    value. The default baud rate is 300.

    Examples:

    set the baud to 300;

    set the baud to item i of "300,1200,2400,9600";

    See Also: modem, stopBits, parity, and dataBits

    -----------------------------------
    CURRENTDIRECTORY

    Purpose: This property gets or sets the current DOS directory. You can
    set the directory to partial directory names as well. For example, if
    you want to set the directory to the parent:

    set the currentDirectory to "..";

    If you include a drive specifier, HyperPAD will also change the current
    drive. The following example changes to the S: drive and the directory
    called ACCOUNTS\JOHN:

    set the currentDirectory to "S:\ACCOUNTS\JOHN";

    Examples:

    put the currentDirectory into the msg;

    set the currentDirectory to "D:";

    set the currentDirectory to "C:\123";

    The following example runs MS-WORD from within a document directory and
    loads a document named MYDOC.DOC from the document directory.

    set the currentDirectory to "C:\DOCUMENT\PROJECT";
    run "C:\WORD5\WORD MYDOC";

    Abbreviations: curDir

    See Also: directory



    ________________________________________________________________________
                                             Chapter 12: Properties   152
    ________________________________________________________________________


    -----------------------------------
    CURSOR

    Purpose: Sets the hardware text cursor (the blinking cursor) shape to an
    underscore (thin), a full character block (fat), or invisible (off).

    When to use it: If you want to make the cursor change shape to indicate
    the cursor's entry into different portions of your application (such as
    entering buttons and fields).

    If you set the cursor shape to off (not visible) the cursor will be
    invisible until you change the shape to either thin or fat.

    Examples:

    set the cursor to thin;

    if the cursor is off then
      put "no one has the focus" into msg;

    See Also: cursorLoc, cursorX, cursorY

    -----------------------------------
    CURSORLOC

    Purpose: The cursorLoc property allows you to set or get the location of
    the hardware text cursor (the blinking cursor). The position is returned
    in the form "X,Y" where X is the horizontal position and Y is the
    vertical position with respect to the upper left corner of the screen.

    The range of values for the cursor location are:

    1 <= X <= screenWidth()    (usually 80)
    1 <= Y <= screenHeight()   (usually 25)

    Examples:

    put the cursorLoc into cl; -- puts X,Y into "cl"

    set the cursorLoc to 10,12 -- set it somewhere

    if the screenHeight is 43 then
      set the cursorLoc to 1,43

    See Also: cursor, cursorX, cursorY



    ________________________________________________________________________
                                             Chapter 12: Properties   153
    ________________________________________________________________________


    -----------------------------------
    DATABITS

    Purpose: Sets or gets the serial port property dataBits to
    either 7 or 8 for use with the dial command. The default value is 7.

    Examples:

    set the dataBits to 7;

    set the dataBits to 8;

    See Also: baud, stopBits, parity, modem

    -----------------------------------
    FILESORTMETHOD

    Purpose: The fileSortMethod property determines how a list
    of files is sorted when it is read from disk. It can have the following
    values:

    Method Value:     Sorted by:
    ---------------------------------------------
    1                 Name (ascending)

    2                 Extension (ascending)

    3                 Size (ascending)

    4                 Date/Time (ascending)

    5                 Name (descending)

    6                 Extension (descending)

    7                 Size (descending)

    8                 Date/Time (descending)

    The fileSortMethod property only affects the values of future calls to
    the files() and longFiles() functions.

    Examples:

    The following statements read in a directory list sorted by descending
    size:

    set the fileSortMethod to 7;
    put the longFiles into page field "List";



    ________________________________________________________________________
                                             Chapter 12: Properties   154
    ________________________________________________________________________


    -----------------------------------
    FOCUS

    Purpose: Use focus to change the focus to a particular button or field
    on the page or background. When a button or field has the focus, it is
    the current object and can be selected (button) or edited (field).

    You cannot set the focus to locked buttons or fields, or objects that
    are completely covered by other objects.

    When to use it: Use focus to highlight the button or field the user will
    most likely want to select.

    Examples:

    set the focus to page field 1;

    set the focus to button "initialize";

    The following handler (in a page script) sets the focus to the first
    empty field on a page:

    handler openPage;
    begin
      put 1 into i;
      while page field i is not empty AND
            i < the number of page fields do
        add 1 to i;
      set the focus to page field i;
    end;

    Comments: Changing the focus sends a closeButton/closeField message to
    the current object and an openButton/openField message to the object
    receiving the focus.

    -----------------------------------
    LOCKMESSAGES

    Purpose: Use lockMessages to prevent HyperPAD from sending automatic
    messages such as openPage, openButton, and openPad. The possible values
    for lockMessages are true and false.

    When to use it: You may want to set lockMessages to true for the
    following reasons:

    1.  To speed up execution of a script that cycles through many pages.
    Since fewer messages are being sent automatically by HyperPAD, the
    script will execute faster.



    ________________________________________________________________________
                                             Chapter 12: Properties   155
    ________________________________________________________________________


    2.  When you want to go to another page (i.e. to gather some data) and
    don't want to stay there, you can set lockMessages to true to avoid
    sending the automatic messages (like openPage) to that page.

    Examples:

    set the lockMessages to true;

    The following example script retrieves some data from a pad called
    "PIF.PAD". It sets the lockMessages property to true to avoid sending
    automatic messages to that pad.

    set the lockMessages to true;
    push this page;               -- remember where we are
    go to pad "Phone";
    get field "First Name";
    pop page;                     -- go back there

    Comments: The default value of lockMessages is false. It is reset to
    false when the next idle message is sent (at the end of all pending
    handlers).

    Another reason to set the lockMessages property to true is to avoid
    subtle recursion. Recursion occurs when a script either directly or
    indirectly executes itself. The following example demonstrates a
    recursion problem:

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

    The above closeField hander goes to another page. However, changing to
    another page sends closeField to the current field, thus executing the
    same script again (recursion). The following script corrects this:

    handler closeField;
    begin
      set lockMessages to true;
      go to the next page;
    end;

    In this case, setting lockMessages to true prevents the second
    closeField message (which is an automatic message) from being sent. (The
    closePage and openPage messages that are normally sent when the page is
    changed are not sent either.)

    See Also: lockRecent, lockScreen



    ________________________________________________________________________
                                             Chapter 12: Properties   156
    ________________________________________________________________________


    -----------------------------------
    LOCKRECENT

    Purpose: Setting lockRecent to true prevents HyperPAD from adding pages
    to the recent list. By default this property is false.

    When HyperPAD moves from page to page (including moving between pads),
    the order the pages are viewed is remembered in the recent list (the
    list of most recently accessed pages). When you press F5 (or select Back
    from the Go menu), HyperPAD accesses this list to take you back through
    the pages you've just viewed.

    When to use it: If you need to go to another page temporarily and don't
    want the user to cycle back to this page when pressing F5.

    Comments: The lockRecent property is reset to false when the next idle
    message is sent (at the end of all pending handlers).

    Examples:

    set the lockRecent to true;

    The following example goes to the Home pad and retrieves the user's name
    from the Preferences page, but doesn't allow the user to return there
    when F5 is pressed.

    set the lockRecent to true;
    push this page;
    go home;
    get page field "User Name" of page "Preferences";
    pop page;

    -----------------------------------
    LOCKSCREEN

    Purpose: Use lockScreen to freeze the screen, preventing HyperPAD from
    changing what is currently displayed. This is useful if you want to
    change to another page without seeing it.

    The value of lockScreen is either true or false, and is reset to false
    (the default) when the next idle message is sent (at the end of all
    pending handlers). If the value is true, the screen will be updated.

    When to use it: If you need to gather field contents from another pad,
    but don't want the user to actually view that pad, set the lockScreen to
    true.



    ________________________________________________________________________
                                             Chapter 12: Properties   157
    ________________________________________________________________________


    Examples:

    set the lockScreen to true;

    get the lockScreen;
    if it is true then beep;

    The following statements use lockScreen to hide the retrieval of the
    user name from the Preferences page of the Home pad:

    set the lockScreen to true;
    push this page;
    go home;
    get field "User Name" of page "Preferences";
    pop page;
    set the lockScreen to false;
    answer "Hello there" && it;

    Comments: Setting lockScreen to true increments an internal counter by
    1, setting it to false decrements this counter by 1.  When lockScreen is
    0, it is false. This is useful if you have a handler that is called from
    different places, sometimes when the screen is locked, and other times
    when it is not. As long as you set the lockScreen back to false, the
    value will be preserved, as in the following example:

              set the lockScreen to true;
                         :
                         :
              set the lockScreen to false;

    Note: The dialog boxes associated with the answer, ask, and fileOpen
    commands will be displayed regardless of the value of lockScreen.

    See also: lockMessages, lockRecent

    -----------------------------------
    MARKERATTR

    Purpose: Use markerAttr to determine the color of the marker character
    in all list box fields.

    By default, marked lines in list boxes are indicated by a right triangle
    character (ASCII 16) to the left of the line. Setting the markerAttr
    changes the color of these characters. You can select from a range of
    colors between 0 and 25.

    If the markerAttr is set to 0 (the default), then the marker characters
    are the same as the fillColor of the field they are in.

    If the markerChar is 0, then the markerAttr is used as the color of the
    entire line.



    ________________________________________________________________________
                                             Chapter 12: Properties   158
    ________________________________________________________________________


    Examples:

    set the markerAttr to yellow on red;

    set the marketAttr to 45;

    The following example makes the marked lines of a field reverse video by
    disabling the character that normally appears to the left of marked
    lines, and setting the color:

    set the markerChar to 0;
    set the markerAttr to black on grey;

    The next example sets the markings back to the default:

    set the markerChar to 16;        -- triangle
    set the markerAttr to 0;          -- use fillColor

    See Also: markerChar

    -----------------------------------
    MARKERCHAR

    Purpose: Use the markerChar to set and get the value of the character
    that is used to show marked lines within a list box field.

    When the user selects a line in a list box field, the markerChar appears
    to the left of the line in order to show that it is marked. You can
    change or remove the use of this character by modifying the markerChar.
    The default character is 16, a right arrow (ASCII 16).

    To change the markerChar, you must supply the ASCII code of the
    character you want. For example, if you wanted the lines to be marked
    with the letter A, you would type:

    set the markerChar to charToNum("A");

    When to use it: If you don't want a marker to be used, or you want to
    specify a different character.

    Examples:

    This example sets the marker characters to a yellow diamond:

    set the markerChar to 4;      -- diamond
    set the markerAttr to yellow;

    Comments: Changing the markerChar affects the display of all list box
    fields until you change the value or exit HyperPAD.

    See Also:  markerAttr



    ________________________________________________________________________
                                             Chapter 12: Properties   159
    ________________________________________________________________________


    -----------------------------------
    MAXDIRTYPAGES

    Purpose: HyperPAD stores pages in an area of memory called the cache.
    When pages are modified in any way, they are considered "dirty". The
    maximum number of modified pages in the cache is determined by this
    property. The default is 20. The range of values is between 1 and 50.
    When the number of modified pages exceeds the value of maxDirtyPages,
    the dirty pages are written to the pad file.

    When to use it: Setting maxDirtyPages to 1 causes HyperPAD to save each
    page as it is changed. This is the safest way to run HyperPAD, but also
    the slowest.

    Examples:

    set the maxDirtyPages to 1;

    See Also: autoSave

    -----------------------------------
    MODEM

    Purpose: The modem property establishes the serial port that the dial
    command will use to communicate with your modem.
    The modem property can be set to either "COM1" or "COM2". If you set the
    modem property to the wrong port, the dial command will give you an
    error.

    Examples:

    set the modem to "com1";
    dial "555-1212";

    The following example sets modem to the user's choice of a serial port:

    answer "Where is your modem connected?" with
       "COM1","COM2";
    if it is not empty then set the modem to it;

    The next example sets up each of the parameters to use with dial:

    set the modem to "com1";      -- default
    set the baud to 300;              -- default
    set the stopBits to 1;          -- default
    set the dataBits to 7;          -- default
    set the parity to "even";    -- default
    dial "555-1212";

    Comments: The default value is "COM1".

    See Also: baud, stopBits, parity, dataBits



    ________________________________________________________________________
                                             Chapter 12: Properties   160
    ________________________________________________________________________


    -----------------------------------
    MOUSE

    Purpose: The mouse property determines whether HyperPAD recognizes the
    presence of a mouse. By default, the mouse is recognized (and on) a
    mouse is connected to the system and the mouse driver is loaded.

    Setting this property to off causes HyperPAD to ignore the mouse, even
    if a mouse is present and operational. If you set the mouse property to
    off, you must reset it to on
    in order to use the mouse.

    If you attempt to set the mouse property to on and there isn't a mouse
    or the mouse software is not loaded, then the mouse property will remain
    off (HyperPAD will not return an error).

    The possible values are on or off.

    When to use it: If you want to force the user to use the keyboard in
    your pad, set the mouse to off.

    Examples:

    set the mouse to off;    -- turn mouse off, if present

    set the mouse to on;

    The next example determines if a mouse is present and available:

    set the mouse to on;
    if the mouse is not on then
      answer "You have no mouse";

    See also: mouseAttr, mouseChar, mouseLoc, mouseClick

    -----------------------------------
    MOUSEATTR

    Purpose: The mouseAttr property controls the attribute component of the
    mouse pointer.

    The mouse pointer in HyperPAD has two components, the mouseChar and the
    mouseAttr, that determine its appearance. When HyperPAD draws the mouse
    pointer, it performs the following steps:

    1.  If the mouseChar is not 0, then the character component of the mouse
    pointer is set to the mouseChar.

    2.  If the mouseAttr is not 0, then the attribute component of the mouse
    pointer is set to the mouseAttr.



    ________________________________________________________________________
                                             Chapter 12: Properties   161
    ________________________________________________________________________


    Examples:

    set the mouseAttr = black on grey;    -- default

    set the mouseAttr to 76;

    set the mouseAttr to the color of page button 1;

    The following example adjusts both the attribute and the character
    portion of the mouse pointer:

    if the graphicsCard is "Monochrome" then
      begin
        set the mouseAttr to 112;
        set the mouseChar to 4;
      end
    else
      begin
        set the mouseAttr to 32;
        set the mouseChar to chartonum("A");
      end;

    The following makes the mouse invisible:

    set the mouseChar to 0;
    set the mouseAttr to 0;

    Comments: The default mouseAttr is 112, which means that the mouse
    pointer is a reverse video block. The range of values is from 0 to 25.

    When displaying the attribute, HyperPAD examines the attribute that is
    already there at the location of the mouse pointer on the screen. If the
    background color is the same as the background color of the mouseAttr,
    then the foreground and background colors of the mouseAttr are swapped
    before the mouse pointer is displayed.

    See Also: mouse, mouseChar, mouseLoc



    ________________________________________________________________________
                                             Chapter 12: Properties   162
    ________________________________________________________________________


    -----------------------------------
    MOUSECHAR

    Purpose: With mouseChar, you can set the character component of the
    mouse pointer. The default mouseChar is 0, which means that the mouse
    pointer is represented only by an attribute (a rectangular block of
    color).

    To set the mouseChar, you need the ASCII value of the character you want
    to represent the mouse pointer. If you don't know the ASCII value, you
    can check it in the ASCII Char dialog box, or use charToNum() in your
    script.

    When to use it: Modify the mouseChar to create a visual cue that the
    mouse is on top of something. For example, you might change the pointer
    into a question mark whenever it enters your Help button.

    Examples:

    set the mouseChar to 4;  -- set mouse pointer to diamond

    -- set the mouse Char to the letter A
    set the mouseChar to chartonum("A");

    The following handlers (when placed in a page script) set the mouseChar
    to a diamond whenever the mouse pointer is inside a button or field.
    This gives the user a visual indication that the mouse can be pressed to
    initiate an action.

    handler mouseEnter;
    begin
      set the mouseChar to 4;  -- diamond
    end;

    handler mouseLeave;
    begin
      set the mouseChar to 0;  -- default is off
    end;

    -----------------------------------
    NUMBERFORMAT

    Purpose: The numberFormat property determines the precision in which
    mathematical calculations are displayed. Internally, HyperPAD keeps
    track of 19 digits of precision; however, when you put a number into the
    message box or a field, it is displayed using the current numberFormat.

    The numberFormat is made up of zeros, pound signs, and a decimal point.
    A zero to the left or right of the decimal point instructs HyperPAD to
    place a digit or, if there is no digit, a 0 in that position. A pound
    sign (#) to the right of the decimal point instructs HyperPAD to place a
    digit at that position only if the internal number has a digit there.



    ________________________________________________________________________
                                             Chapter 12: Properties   163
    ________________________________________________________________________


    The value of numberFormat has the following format:

    <zeros>.<zeros><pound signs>

    The following are legal number formats:

    "0000.000000"
    "0.000######"
    "00.#"
    "0.#########"

    The following are not legal:

    Number format:     Not legal because:
    -----------------------------------------------------------------------
    ##00.00            ##s to the left of the decimal place have no meaning

    00.##00            ##s cannot be followed by zeros

    The following table shows some sample numbers and how they would appear
    using some sample number formats:

    Number:              Number Format:        Looks Like:
    --------------------------------------------------------------------
    n3                   0.#####               3

    3.12                 0.#####               3.12

    3.66666666666667     0.#####               3.66667

    3                    00.00                 03.00

    3.1245               00.00                 03.12

    345.678              0.00##                345.68

    3                    0.00##                3.00

    3.123456789          0.00##                3.1235

    345.678              0.00##                345.678

    Examples:

    set the numberFormat to "0.00"; -- money format

    set the numberFormat to "0.00###";

    The next example increases the current precision by 2 digits:

    get the numberFormat;
    set the numberFormat to it & "##";



    ________________________________________________________________________
                                             Chapter 12: Properties   164
    ________________________________________________________________________


    The final example changes all background fields to use a new number
    format:

    ask "New Number Format" with the numberFormat;
    set the numberFormat to it;
    for i=1 to the number of fields do
      put (field i)*1 into field i;

    Comments: The default numberFormat is "0.######". HyperPAD resets when
    the next idle message is sent (at the end of all pending handlers).

    The numberFormat property will not affect the presentation of a number
    that is already displayed unless you first perform an arithmetic
    operation on it. If you don't want the value changed, simply multiply it
    by 1:

    set the numberFormat to "0.00";
    multiply field 1 by 1;

    -----------------------------------
    PAINTATTR

    Purpose: The paintAttr property is used to get or set the current value
    of the Paint Attribute. The valid range of values is from 0 to 255.

    You can also set this property using the Paint Attr command on the
    Workspace menu.

    Examples:

    set the paintAttr to 31;

    set the paintAttr to red on yellow;

    if the paintAttr is 78 then
      answer "you have changed the attribute";

    set the mouseAttr to the paintAttr;

    The following handler forces the user to change the current paint
    attribute:

    handler select;
    begin
      put the paintAttr into saved;
      repeat
        doMenu "paint"; -- paint tool
        doMenu "Paint Attr...";   -- get the box
      until the paintAttr is not saved;
    end;

    See Also: asciiChar



    ________________________________________________________________________
                                             Chapter 12: Properties   165
    ________________________________________________________________________


    -----------------------------------
    PARITY

    Purpose: This property sets the parity to either even, odd, or none for
    use with the dial command. The default is even.

    Examples:

    See the section on the MODEM property.

    See Also: baud, stopBits, modem, dataBits, parity

    -----------------------------------
    PRINTDEVICE

    Purpose: This property allows you to establish where HyperPAD will send
    printed output. You can specify either "LPT1", "LPT2", "COM1", "COM2" or
    any valid DOS filename. You can also set the print device manually
    through the Print Setup dialog box by changing the Print To setting.

    Examples:

    set the printDevice to "LPT1";

    if the printDevice is "LPT2" then
    answer "You don't have an LPT2 printer port";

    set the printDevice to "C:\HPAD\OUTPUT\STUFF.LST";

    The following example prints two fields, "first name" and "last name",
    from every page of a pad to a file called "OUTPUT.LST". The previous
    value of printDevice is saved and restored.

    put the printDevice into savedPrintDevice;
    set the printDevice to "OUTPUT.LST";
    set the printer to on;
    for i = 1 to the number of pages do
      print field "First Name" && field "Last Name";
    set the printer to off;
    set the printDevice to savedPrintDevice;

    Comments: LPT1 is the default printDevice.

    HyperPAD uses MS-DOS to perform its printing. Thus, any name that you
    specify must be a valid DOS filename.

    Once you set printDevice, it will remain unchanged until you change it
    again. The value is saved in your HPAD.INI file.

    Abbreviations: printDev

    See Also: print, printer, printerTranslation



    ________________________________________________________________________
                                             Chapter 12: Properties   166
    ________________________________________________________________________


    -----------------------------------
    PRINTER

    Purpose: You can use this property to turn the printer on and off. When
    printer is on, you can use the print command to send text out to the
    printer; if it's off, using the print command will cause a
    runtime error.

    Examples:

    set the printer to on;

    set the printer to off;

    The following example prints out all the background button scripts from
    the current pad:

    set the printer to on;  -- start the print job
    for i=1 to the number of pages do
      begin
        go to page i;
        for j = 1 to the number of bkgnd btns do
          print the script of bkgnd btn j;
      end;
    set the printer to off;  -- finished printing

    Comments: The printer property is automatically set to off when you exit
    HyperPAD, run a program using Run Program on the File menu or use the
    run command (from a script).

    See Also: print, printDevice, printerTranslation

    -----------------------------------
    PRINTERTRANSLATION

    Purpose: Setting this property modifies how HyperPAD translates
    characters that you send to your printer using the print command.

    When printerTranslation is true (the default), HyperPAD performs the
    following translations:

    Character:     carriage-return
    ASCII Value:        13
    Translates To:      13,10

    Notes:    Changes the internal print position to the next line

    Character :     formfeed
    ASCII Value:       12
    Translates To:     12

    Notes:    Resets the internal print position to 1,1



    ________________________________________________________________________
                                             Chapter 12: Properties   167
    ________________________________________________________________________


    When printerTranslation is false, no translation is performed. This
    enables you to send special escape sequences to your printer to control
    various printer options.

    Examples:

    set the printerTranslation to false;

    The following example sends an escape sequence to an IBM Proprinter to
    print in NLQ mode (near letter quality):

    set the printerTranslation to false;
    print numToChar(27) & H;

    Comments: HyperPAD resets printerTranslation to
    true (the default) when the next idle message is sent (at the end of all
    pending handlers).

    -----------------------------------
    SELECTEDTEXT

    Purpose: Use selectedText to determine what text is currently
    highlighted in a field or the message box.

    When the user highlights text in a field (using SHIFT+Arrow keys or by
    dragging the mouse), HyperPAD copies the highlighted text to the
    selectedText. The text will remain in the selectedText until you
    highlight something else, exit HyperPAD, or run another program.

    Setting the selectedText does not highlight the text on the screen. This
    is accomplished using the hilite command.

    Example:

    put the selectedText into the message box;

    set the selectedText to empty;

    The following handler finds the selectedText:

    handler select;
    begin
      if the selectedText is not empty then
        find the selectedText;
    end;

    See Also: hilite



    ________________________________________________________________________
                                             Chapter 12: Properties   168
    ________________________________________________________________________


    -----------------------------------
    STOPBITS

    Purpose: Sets the stopBits for use with the dial command. The possible
    values are 1 or 2. This value is used to initialize the serial port
    before using the dial command.

    Examples:

    set the stopBits to 2;

    set the stopBits to 1;

    See Also: modem, baud, parity, dataBits,dial

    -----------------------------------
    TABBING

    Purpose: Use the tabbing property to control the behavior of the TAB key
    when moving from object to object on the page.

    When you press the TAB key, the focus is taken away from the current
    button or field and given to the next button or field. The next object
    that receives the focus is determined by the tabbing property, which can
    be set to either position or layer.

    If tabbing is set to layer, then the next object to receive the focus
    depends on the order which the objects sit on the page. Each button and
    field is on its own transparent layer, these layers are stacked on top
    of one another. Pressing TAB moves the focus to the object in the next
    layer higher (i.e. from page button 1 to page button 2).

    If tabbing is set to position (the default), then the next object is
    determined by the object's position relative to the current one on the
    page. HyperPAD looks for objects to the right and then down on the page.
    If there aren't any, then the object closest to the upper left corner of
    the screen receives the focus.

    When to use it: Use this property to make the movement between the
    buttons and fields in your pads as logical as possible.

    Examples:

    set the tabbing to position;

    handler openPage;
    begin
      set the tabbing to layer;
    end;



    ________________________________________________________________________
                                             Chapter 12: Properties   169
    ________________________________________________________________________


    -----------------------------------
    USERLEVEL

    Purpose: Use the userLevel property to limit access to your pad. You can
    modify this property with the Protect command on the File menu.

    Within HyperPAD, the commands you can access from the menus are
    determined by the userLevel. You can set the user level to one of five
    values. The higher the value, the more power HyperPAD gives the user.

    The numbers 1 through 5 correspond to the userLevel in the following
    way:

    Number:    User Level:
    --------------------------------------
    1          Browsing

    2          Typing

    3          Painting

    4          Authoring

    5          Scripting

    As you change userLevel, the menus change to reflect the new
    capabilities HyperPAD gives you (or takes away!).

    The userLevel property can be set by the pad's user using the Protect
    dialog box on the File menu. The userLevel is saved with the pad, so
    that the next time you use the pad, it has the same user level.

    If you attempt to change the userLevel of a pad that currently has a
    password, then you will be asked for the password. The userLevel will
    remain unchanged if you give the wrong password or select <Cancel> from
    the Password dialog box.

    When to use it: If you want to limit the pad user's ability to alter the
    pad, or if you want to allow some changes but not others, you'll need to
    change the userLevel.

    Examples:

    set the userLevel to 5;

    set the userLevel to 1;



    ________________________________________________________________________
                                             Chapter 12: Properties   170
    ________________________________________________________________________


    The following handler sets the userLevel on entry to a pad. It sets a
    higher level if the user knows a certain password:

    handler openPad;
    begin
      ask "What is the password?";
      if it is "FANCY" then set the userLevel to 5
      else set the userLevel to 2;
    end;

    See Also: passwordOnly



    ________________________________________________________________________
                                             Chapter 12: Properties   171
    ________________________________________________________________________


    PAD PROPERTIES

    The following section describes the properties of a pad. You can change
    a pad property using the set command, as in the following example:

    set the cantDelete of pad to true;

    -----------------------------------
    CANTDELETE

    Purpose: Setting this property to true prevents a pad from being
    deleted. When cantDelete is false, the pad can be deleted using Delete
    Pad command on the File menu.

    Changing this value changes the value of the Can't delete option in the
    Protect dialog box.

    When to use it: Set cantDelete to true when you want to protect your
    pads from being accidentally deleted from within HyperPAD.

    Examples:

    set the cantDelete of pad to false;

    if the userLevel <= 2 then
      set the cantDelete of pad to true;

    Comments: This property does not prevent you from deleting the pad using
    the DOS Delete command (it doesn't modify the DOS file attributes).

    See Also:  cantModify

    -----------------------------------
    CANTMODIFY

    Purpose: The cantModify property allows you to determine whether the
    pad's user can make modifications to a pad.
    When the value of cantModify is false, you can change the information in
    a pad within the constraints of the current user level.

    When cantModify is true, the pad cannot be changed. Thus, you are
    prevented from typing into fields, painting, modifying an object's
    position and properties, and modifying an object's script. Pads of this
    type (with cantModify set to true) are read-only and cannot be
    physically modified by HyperPAD. Furthermore, more than one user on a
    network can browse read-only pads at the same time.

    Changing the value of this property changes the value of the Read only
    option in the Protect dialog box.



    ________________________________________________________________________
                                             Chapter 12: Properties   172
    ________________________________________________________________________


    When to use it: If you want to allow a pad to be shared on a network, or
    if you want to further restrict the pad user from modifying it.

    Examples:

    set the cantModify of pad to true;

    The following handler in a pad script changes the userLevel to scripting
    if there are no other users accessing the pad on a network; otherwise,
    the pad is opened in read-only mode:

    hander openPad;
    begin
      if the cantModify of pad is true then
        being
          set the cantModify of pad to false;
          if the cantModify of pad is false then
            set the userLevel to 5;
        end;
    end;

    Comments: Scripts can still modify the contents of fields and the
    properties of buttons. However, these changes will not be saved to disk.

    See Also: cantDelete, passwordOnly

    -----------------------------------
    LONGNAME

    Purpose: Use this property to determine the full DOS pathname of the
    current pad, including a drive letter, like the following example:

    C:\HPAD\HOME.PAD

    Note:  You cannot modify the longName of a pad; in order to change the
    path of a pad you must copy it through DOS or the DOS pad.

    Examples:

    put the longName of pad into pname;

    get the longName of pad;
    if the first character of it is in "AB" then
      answer "You are on a removable disk.";

    See Also: name



    ________________________________________________________________________
                                             Chapter 12: Properties   173
    ________________________________________________________________________


    -----------------------------------
    NAME

    Purpose: Use the name property to get or set the name of a pad. The
    value of name will be the DOS name of the pad without the extension. If
    you set the name of a pad, you will change the actual DOS name.

    Examples:

    if the name of pad is "HOME" then
      answer "You are home now!";

    The following example changes the name to one that the user specifies:

    ask "New name for pad:" with the name of pad;
    if it is empty then exit;
    if "." is not in it then put ".PAD" after it;
    set the name of pad to it;
    if the name of the pad is not it then
      answer "Unable to change the name" with "Ok";

    See Also: longName

    -----------------------------------
    PASSWORDONLY

    Purpose: This property determines whether a pad is accessible by
    password only.

    You can require that the user enter the correct password in order to
    access the pad for the first time in a HyperPAD session. Setting this
    property modifies the By Password Only option in the Protect dialog box.

    If you attempt to set passwordOnly to true and no password has been
    chosen, you will be prompted to enter one. If you cancel the Password
    dialog box, the property will not be changed.

    When passwordOnly is true, you must type in the password when you open
    the pad for the first time (you only have to give the password once per
    HyperPAD session). If you change the user level after accessing the pad,
    you must enter the password again.

    When to use it: When you want to protect your pad from being browsed by
    other users.

    Examples:

    set the passwordOnly of pad to true;

    set the passwordOnly of pad to (the userLevel >= 4);

    See Also: cantModify, cantDelete, userLevel



    ________________________________________________________________________
                                             Chapter 12: Properties   174
    ________________________________________________________________________


    -----------------------------------
    SCRIPT

    Purpose: Use the script property to get or replace the current script of
    the pad. The value of script is a text string composed of lines
    separated by carriage returns.

    Setting this property replaces the current pad script with a new one.
    The new script must be compiled and checked for errors. Any handlers
    within the new script that contain errors will not be compiled.
    Getting the script allows you to view it or paste it into another
    script.

    When to use it: When you want to alter a script without using the Script
    Editor.

    Examples:

    put the script of pad into stext;

    set the script of pad to stext;

    set the script of pad to empty;

    The next example creates an openPad handler by appending text together
    (using the & operator) and attaching the new openPad handler to the end
    of the pad script. The new handler beeps when the pad is opened.

    set the script of pad to the script of the pad &
      return & return &
      "handler openPad;" & return &
      "begin" & return &
      "  beep;" & return &
      "end;" & return;

    The next example changes the script of page button 2 to a new script
    that causes the button to go to page 4 when selected.

    handler select;
    begin
      set the script of page button 2 to
      "handler select;" & return &
      "begin" & return &
      "  go to page 4;" & return &
      "end;";
    end;

    See Also: edit script



    ________________________________________________________________________
                                             Chapter 12: Properties   175
    ________________________________________________________________________


    FIELD PROPERTIES

    -----------------------------------
    ACCELERATORCOLOR

    Purpose: The acceleratorColor property determines the color of a given
    accelerator key when the ALT key is pressed. Any field in your pad can
    be assigned an accelerator key, which allows you to set the focus to
    that field quickly. An acceleratorKey must be set for a field and the
    showName property must be true for acceleratorColor to have an effect.

    You cannot set the accelerator key or color of a field using the Field
    Info dialog box like you can with buttons. The only way to do this is
    through the message box or a script.

    The range of values is from 0 to 25. The default is 7.

    Examples:

    set the acceleratorColor of page field 3 to red on blue;

    Abbreviations: accelColor

    See Also: acceleratorKey, showName

    -----------------------------------
    ACCELERATORKEY

    Purpose: The acceleratorKey property defines the character within the
    field's name that the user can press to quickly go to that field. The
    acceleratorKey is highlighted when the user holds down ALT. For example,
    if a field's acceleratorKey is "A", the key combination ALT+A will set
    the focus to that field.

    If the acceleratorKey can't be found within the field's name, then it
    will not be highlighted when ALT is pressed. However, the field can
    still be accessed with the ALT key combination.

    Accelerator keys can be any letter or number (A..Z, 0..9).

    Example:

    set the accelKey of field "First Name" to "E";

    Comments: Make sure you select a unique key code for the accelerator
    key. If it isn't, then the field or button lowest in the hierarchy will
    get the focus first. Further, be careful not to create accelerator keys
    that conflict with the menu accelerators.
    Abbreviations: accelKey

    See Also: acceleratorColor, showName



    ________________________________________________________________________
                                             Chapter 12: Properties   176
    ________________________________________________________________________


    -----------------------------------
    ALIGN

    Purpose: Use the align property to set or get the text
    justification of a field. By default, text in fields is left aligned.

    You can set align to left, right, or centered.

    Examples:

    set the align of page field 1 to right;

    The next example randomly aligns text in all the fields of a page:

    put "left,right,centered" into settings;
    for i = 1 to the number of page fields do
      begin
        set the align of page field i to
          item (random(3)) of settings;
    end;

    -----------------------------------
    AUTOHILITE

    Purpose: Use  this property to determine whether a field is highlighted
    when it receives the focus. The value  can be true or false.

    Example:

    set the autoHilite of field "Address" to true;

    -----------------------------------
    BORDERCOLOR

    Purpose: The borderColor property sets or gets the color of a field's
    border. The borderColor property will have no effect if withEdge is
    false or the style is transparent.

    The range of colors is from 0 to 255; the default is 7 (grey on black).

    This property can also be modified through the Field Info property box.

    Examples:

    set the borderColor of page field 1 to 7; -- the default

    if the style of field "Notes" is not transparent then
      set the borderColor of field 1 to yellow on red;

    See Also: color, fillColor, nameColor, hiliteColor



    ________________________________________________________________________
                                             Chapter 12: Properties   177
    ________________________________________________________________________


    -----------------------------------
    COLOR

    Purpose: The color property allows you to determine or change the
    fillColor and borderColor of a field.

    When used with the set command, this property modifies both the
    fillColor and the borderColor properties of a field. When used with the
    get or put commands, the value of this property is the fillColor of the
    field.

    The valid colors are in the range 0 to 255; the default is 7 (grey on
    black).

    Examples:

    set the color of field 1 to 31;

    set the color of page field "Notes" to blue on white;

    Comments: This property can also be modified through the Field Info
    dialog box.

    See Also: fillColor, borderColor, nameColor, hiliteColor

    -----------------------------------
    CURRENTLINE

    Purpose: Use currentLine to retrieve the line number of the current
    insert point within a field.

    The currentLine property returns the line number as it appears on the
    screen (not the line number as determined by carriage returns).

    This value cannot be changed. You can change the insertion location
    within the text using the insertPoint property.

    Examples:

    put the currentLine of field 1 into cline;

    get the currentLine of field "Notes" of page 2;

    The following makes the current line the first line displayed:

    set startLine of field 1 to the currentLine of field 1;

    See Also: insertPoint



    ________________________________________________________________________
                                             Chapter 12: Properties   178
    ________________________________________________________________________


    -----------------------------------
    EDGETYPE

    Purpose: The edgeType property determines the current edge type of a
    field. You can choose different characters to define the borders of a
    field. The valid edge types are 1 to 15. The default is 1, which is a
    single width line. The edgeType will only have an effect if the value of
    withEdge is true.

    Appendix 3 shows the available edge types and their corresponding
    values.

    This property can also be modified through the Field Info dialog box.

    Examples:

    set the edgeType of page field "Zip Code" to 7;

    put the edgeType of field 1 into the message box;

    The next two handlers in a field script change the border to a double
    line when the field is opened for editing and the changes the border
    back to a single line when the field is closed. This provides an
    additional visual cue for the user that the field is open for editing:

    handler openField;
    begin
      set the edgeType of me to 2;
    end;

    handler closeField;
    begin
      set the edgeType of me to 1;
    end;

    See Also: withEdge, borderColor



    ________________________________________________________________________
                                             Chapter 12: Properties   179
    ________________________________________________________________________


    -----------------------------------
    FILLCOLOR

    Purpose: Use the fillColor property to set or get the color of the
    interior portion of a field. If the field is style is transparent,
    fillColor will have no effect.

    The valid range of colors is from 0 to 255; the default is 7 (grey on
    black).

    This property can also be modified through the Field Info dialog box.

    Examples:

    set the fillColor of field 1 to red;

    set the fillColor of field 2 to 31;

    See Also: color, borderColor, nameColor, hiliteColor

    -----------------------------------
    HILITE

    Purpose: Use the hilite property to determine or change the current
    hilite status of a field.

    This property can be true or false; the default is false. If the value
    of the hiliteIfFocus property is true, the field will be highlighted
    automatically when the user tabs to it. Thus, the hilite property would
    be true. The color of the highlight is determined by the hiliteColor.

    Examples:

    set the hilite of page field 1 to true;

    set the hilite of page field 1 to the hilite of page button 1;

    Sometimes it is useful to highlight a field automatically when the mouse
    is moved into its rectangle. These two handlers in the field's script
    will do this:

    handler mouseEnter;
    begin
      set the hilite of me to true;
    end;

    handler mouseLeave;
    begin
      set the hilite of me to false;
    end;

    See Also: hiliteIfFocus, autoHilite



    ________________________________________________________________________
                                             Chapter 12: Properties   180
    ________________________________________________________________________


    -----------------------------------
    HILITECOLOR

    Purpose: Use the hiliteColor property to determine or change the color
    of the field when it has the focus. This property will only affect
    fields with hiliteIfFocus set to true. If hiliteIfFocus is false, the
    field will not be highlighted when it receives the focus.

    The range of valid colors is from 0 to 255; the default is 112 (black on
    grey).

    This property can also be modified through the Field Info dialog box.

    Examples:

    set the hiliteColor of field "help msg" to yellow;

    set the hiliteColor of page field 1 to
      the hiliteColor of page field 1 of the next page;

    See Also: color, nameColor, fillColor, borderColor

    -----------------------------------
    HILITEIFFOCUS

    Purpose: Use the hiliteIfFocus property to determine or change whether a
    field is automatically highlighted when it has the focus.

    When hiliteIfFocus is true, the field is automatically highlighted when
    it gets the focus. The user is then required to use F2 to edit the
    field. If hiliteIfFocus is false (the default), when the field receives
    the focus, the cursor is immediately placed within the text ready for
    typing.

    This property can also be modified through the Field Info dialog box.

    Examples:

    set the hiliteIfFocus of page field 1 to true;

    set the hiliteIfFocus of field "Notes" to false;

    See Also: hilite, autoHilite

    -----------------------------------
    ID

    Purpose: Use this property to determine how the button is identified.
    Each button ID is unique for that page and cannot be altered.

    Using the button ID is the only way to guarantee that you are
    referencing a unique button.



    ________________________________________________________________________
                                             Chapter 12: Properties   181
    ________________________________________________________________________


    The returned value of ID is a number.

    You can see the field's ID number in the Field Info dialog box.

    Examples:

    put the id of page field 1 into fid;

    if the id of me > 20 then set the visible of me to true;

    The following statements in a field script pass the field ID to a
    handler in the page called setProps. In this way, the setProps handler
    can uniquely identify this field.

    handler openField;
    begin
      get the id of me;
      send "SetProps" it to me;
    end;

    handler setProps(fid);
    begin
      hide field id fid;
    end;

    See Also: ID, name, longName

    -----------------------------------
    INSERTPOINT

    Purpose: Use the insertPoint property to determine the position of the
    cursor within a text field. Each character in the field counts as a
    valid position for the text cursor, including carriage returns and
    spaces.

    The value of the insertPoint will be between 1 and the number of
    characters in the field:

    1 <= insertPoint <= the number of chars in the field

    Examples:

    set the insertPoint of field "Last Name" to 6;

    The following moves the insert point to the first occurrence of the word
    "that":

    set the insertPoint of page field "Comment" to
      offset("that",page field "Comment");



    ________________________________________________________________________
                                             Chapter 12: Properties   182
    ________________________________________________________________________


    -----------------------------------
    LAYER

    Purpose: Use the layer property to determine the layer of a field in
    relation to the other fields on the page or background.
    Fields are superimposed on their background or page according to their
    layer. The fields closest to the page are lower in value and are
    possibly overlapped by fields on a higher layer.

    Examples:

    put the layer of page field 1 into msg;

    The following example uses the field's layer to create an index into a
    container of values for that field. If the wrong value is entered into
    the field, an error is displayed.

    handler closeField;
    begin
      get the layer of me;
      if item it of "10,56,78,34" is not the value of me then
        answer "Field" && it && has the wrong value;
    end;

    See Also: ID

    -----------------------------------
    LOCATION

    Purpose: The location property determines the X (column) and Y (row)
    coordinates of the upper left corner of a field and returns two numbers
    in "X,Y" format; for example:

    "10,12"

    The location can be changed using the Selector tool, or by setting the
    rectangle property.

    Examples:

    put the location of page field 3 into page field 4;

    Abbreviations: loc

    See Also: rectangle



    ________________________________________________________________________
                                             Chapter 12: Properties   183
    ________________________________________________________________________


    -----------------------------------
    LOCKTEXT

    Purpose: Use the lockText property to prevent or allow editing within a
    field. When you create a field, lockText is initially false; this allows
    you to enter and edit the field.

    Locked text fields are completely inaccessible to the keyboard user. You
    can't enter text into them or edit them. A locked text field acts like a
    button when the mouse is clicked on it (the field receives mouseDown,
    mouseStillDown, and mouseUp).

    You can modify the lockText property using the Field Info dialog box.

    When to use it: When you want to protect the text in your fields from
    inadvertent editing, or you want a field to act like a button, set
    lockText to true. This is useful for creating fields that contain
    messages or visual information for the user.

    Examples:

    set the lockText of page field "Salaries" to true;

    The next example goes to a page that contains the word "hello" in
    background field 1. It is important to lock the field first to prevent
    HyperPAD from setting the focus to that field.

    set the lockText of field 1 to true;
    find "hello" in field 1;
    set the lockText of field 1 to false;

    -----------------------------------
    LONGID

    Purpose: The longID property returns the full field ID, including the
    field's ID number, the page or background name the field is on, and the
    full DOS path of the pad it's in.

    You can not alter a longID. The format of the longID for a page field
    is:

    field id 1 of page id 1 of pad "C:\HPAD2\HOME.PAD"
    or for a background field:

    bkgnd field id 1 of bkgnd page id 1 of pad "C:\HOME.PAD"

    Examples:

    put the longID of page field "phone";

    See Also: ID, name, longName



    ________________________________________________________________________
                                             Chapter 12: Properties   184
    ________________________________________________________________________


    -----------------------------------
    LONGNAME

    Purpose: The longName property returns the complete name of any field in
    a pad. The long name of a page field contains information such as the
    full DOS path and has the following format:

    field id 12 of page 45 of pad "C:\HPAD\HOME.PAD"

    For background fields, the word bkgnd is used:

    bkgnd field id 12 of bkgnd 3 of pad "C:\HPAD\HOME.PAD"

    You can't change the longName of a field.

    Examples:

    put the longName of field 1 into msg;

    The next example prints out the script of field 1 the
    longName of the field as the heading:

    print (the longName of field 1) & return & return;
    print (the script of field 1) & return & return;

    See Also: name, namePosition, nameColor, showName

    -----------------------------------
    MARKEDLINES

    Purpose: Use this property to get a list of the line numbers of the
    lines currently marked in a list box field. The value of markedLines is
    an item delimited list of line numbers, like the following:

    "10,11,12,18,19"

    The above example means that lines 10 though 12, 18 and 19 are all
    marked.

    If there aren't any marked lines in the field, then the value is empty.

    Examples:

    if the markedLines of field "list" is empty then
      answer "There are no marked lines!";



    ________________________________________________________________________
                                             Chapter 12: Properties   185
    ________________________________________________________________________


    The following example copies all of the marked lines from page field 1
    into page field 2:

    put the markedLines of page field 1 into mlist;
    put the number of items of mlist into n;
    for i = 1 to n do
      put line (item i of mlist) of page field 1
        after the last line of page field 2;
    end;

    Comments: You cannot set the markedLines property of a field. By
    adjusting the field's content, however, you can mark lines.
    HyperPAD marks lines by inserting the ASCII character 1 as the first
    character on a line. For example, to mark the first line of field 1:

    put numToChar(1) before char 1 of line 1 of field 1;

    When you retrieve the markedLines, HyperPAD returns an item delimited
    list of the line numbers containing character 1 as the first character.
    Whenever you change a field's content, all of the marks are removed from
    the text. Thus, the following two statements result in only one line
    (the second line) being marked:

    put numToChar(1) before char 1 of line 1 of field 1;

    put numToChar(1) before char 1 of line 2 of field 1;

    To avoid this, you must first copy the field into a local variable, mark
    the lines you want, then copy the local variable back into the field:

    put field 1 into temp;
    put numToChar(1) before char 1 of line 1 of temp;
    put numToChar(1) before char 1 of line 2 of temp;
    put temp into field 1;

    See Also: mark, unmark



    ________________________________________________________________________
                                             Chapter 12: Properties   186
    ________________________________________________________________________


    -----------------------------------
    NAME

    Purpose: Use the name property to determine the name of any
    field in the current pad. The returned value is the same as the name in
    the Field Info dialog box.

    Examples:

    set the name of page field 1 of page 2 to "Last Name";

    if the name of page field i is "Last Name" then
      print page field i;

    put the name of page field 2 into fname;
    put the id of page field fname into msg;

    See Also: namePosition, longName, nameColor, showName, ID,
    longID.

    -----------------------------------
    NAMECOLOR

    Purpose: The nameColor property modifies the color of the displayed name
    of a field.

    When showName is true, the name appears either to the left or on top of
    the field using the attribute determined by nameColor.

    The colors you select must be in the range from 0 to 255 (or use the
    color constants). Changing this property modifies the Name Color option
    in the Field Info dialog box.

    Examples:

    set the nameColor of page field 1 to white on green;

    set the nameColor of field "Last Name" to 31;

    set the nameColor of field 2 to the fillColor of field 2;

    See Also: showName, namePosition



    ________________________________________________________________________
                                             Chapter 12: Properties   187
    ________________________________________________________________________


    -----------------------------------
    NAMEPOSITION

    Purpose: Use the namePosition property to determine the
    location of the field's name, which can be either on top or to the left
    of the field. In order for this property to have an effect, the name
    must be shown (the showName property must be
    true).

    When namePosition is left (the default), the name of the field appears
    on the left side of the field, decreasing the field's editing area by
    the width of the name. When set to top, the name appears on top of the
    field, decreasing the editing area by 1 line.

    A colon always follows the displayed field name.

    Changing this property changes the Name position option in the Field
    Info dialog box.

    Examples:

    set the namePosition of page field 1 to left;

    set the namePosition of field "Last Name" to top;

    Abbreviations: namePos

    See Also: showName, nameColor

    -----------------------------------
    RECTANGLE

    Purpose: The rectangle property determines the position of
    the rectangular region occupied by a field. The value of rectangle is a
    text string consisting of four numbers separated by commas, and may be
    summarized:

    upper left x, upper left y, lower right x, lower right y

    You can also change a field's rectangle property using the Selector
    tool. (See the User's Guide for more information on the Selector tool.)

    To set a field's rectangle, you must supply all four numbers, separated
    by commas (not a container having a text string of numbers). For
    example, the following statements will not work because the variable "r"
    contains a string of numbers:

    put the rectangle of page field 1 into r;
    set the rectangle of page field 1 to r;



    ________________________________________________________________________
                                             Chapter 12: Properties   188
    ________________________________________________________________________


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

    The following will work:

    put the rectangle of page field 1 into r;
    set the rectangle of page field 1 to
      item 1 of r, item 2 of r, item 3 of r, item 4 of r;

    The default rectangle for a field is 29,9,55,15.

    Examples:

    set the rectangle of page field 1 to 10,10,70,20;

    Abbreviations: rect

    See Also: location

    -----------------------------------
    SCRIPT

    Purpose: The script property allows you to retrieve or
    replace the script of any field in a pad. Setting this property replaces
    the script of a field with a new one. The new script must be compiled
    and checked for errors. Any handlers within the script that contain
    errors will not be compiled.

    The value of script is a text string composed of lines separated by
    carriage returns.

    The script can also be changed through the Field Info dialog box.

    When to use it: When you want to copy a script from one field to
    another, or assign a new script to a field, or print a script.

    Examples:

    To display the script of field 1:

    put the script of page field 1 into page field 1;



    ________________________________________________________________________
                                             Chapter 12: Properties   189
    ________________________________________________________________________


    To change a script:

    set the script of field "Last Name" to stext;

    To recompile a script of field:

    set the script of pg fld 1 to the script of pg fld 1;

    To print the script of field "First Name":

    print the script of field "First Name";

    -----------------------------------
    SCROLLABLE

    Purpose: The scrollable property determines if you can view
    text outside the physical confines of a field. With HyperPAD, you can
    place more text into a field than can be viewed at once. With a
    scrollable field, you can allow the user to move down through the field
    to view the text that doesn't fit inside the field.

    The default is true.

    Changing the property changes the Scrollable option in the Field Info
    dialog box.

    When to use it: To include more information in a field without
    increasing its size, set scrollable to true.

    Examples:

    set the scrollable of page field 1 to true;

    set the scrollable of field "Last Name" to false;

    The following handler (in a pad or background script) sets the
    scrollable property to false for all new fields:

    handler newField;
    begin
      set the scrollable of the target to false;
    end;



    ________________________________________________________________________
                                             Chapter 12: Properties   190
    ________________________________________________________________________


    -----------------------------------
    SHOWNAME

    Purpose: The showName property determines whether the
    field's name is shown. When true, the name of the field is displayed
    either to the left or top of the field, depending on the value of
    namePosition. By default showName is false, meaning that the field's
    name isn't shown.

    This property can be modified using the Field Info dialog box.

    Examples:

    set the showName of page field 1 to true;

    set the showName of the target to false;

    The following handler creates a dBase style field. It sets all of the
    relevant properties, including showName, and receives the name as a
    parameter.

    handler DBASEField(fieldName);
    begin
      set the showName of field fieldName to true;
      set the withEdge of field fieldName to false;
      set the hiliteIfFocus of field fieldName to true;
      set the scrollable of field fieldName to false;
      set the lockText of field fieldName to false;
      set the style of field fieldName to opaque;
      set the align of field fieldName to left;
      set the namePosition of field fieldName to left;
    end;
    To call this handler:

    DBASEField "Last Name";

    See Also: showName, namePosition, nameColor, name, longName

    -----------------------------------
    STARTLINE

    Purpose: The startLine property allows you to determine which is the
    first line displayed in a scrollable field. The value of startLine is
    not determined by carriage returns, but by the actual lines of text in
    the field.

    When to use it: By changing the value of startLine, you can simulate
    scrolling through a field. (Note: the field must be scrollable.).

    Examples:

    set the startLine of page field 1 to 1;



    ________________________________________________________________________
                                             Chapter 12: Properties   191
    ________________________________________________________________________


    To synchronize two fields so that they both start at the same line:

    set the startLine of page field 1 to
      the startLine of page field 2;

    The following example scrolls all the fields on a page down by one line:

    for i = 1 to the number of page fields do
    begin
      set the startLine of page field i to
      (the startLine of page field i) +1;
    end;

    -----------------------------------
    STYLE

    Purpose: Use the style property to determine or change the style of a
    particular field. There are four different styles for fields.
    Each style changes the way a field looks and works.

    The fields styles are:
    opaque    transparent    scrolling    listBox

    List box fields require some special mention because they receive some
    additional messages that other style fields do not receive. The
    differences are summarized as follows:

    1.  Lines in list box fields do not word wrap; all lines are broken only
    by carriage returns.

    2.  The UP and DOWN arrow keys move a highlight bar through the choices
    in the field.

    3.  Pressing SPACE marks and unmarks the highlighted line. This actions
    sends the mark and unmark messages to the field.

    4.  Pressing ENTER or double clicking the mouse on a choice sends a
    select message to the field.

    5.  You can get the currently marked line numbers using the markedLines
    property.

    You can also change a field's style using the Field Info dialog box.

    Examples:

    set the style of page field 1 to listBox;

    if the style of field "Last Name" is scrolling then
      set the style of field "Last Name" to opaque;



    ________________________________________________________________________
                                             Chapter 12: Properties   192
    ________________________________________________________________________


    The following function returns the contents of all the list box fields
    on a page:

    function getListBoxes;
    begin
      get empty;
      for i = 1 to the number of page fields do
        begin
          if the style of page field i is listBox then
            put it after the last line of it;
        end;
      return it;
    end;

    -----------------------------------
    VALUE

    Purpose: The value property determines the content of a field.

    Example:
    The following handler copies a field's content into the message box when
    it receives the focus:

    handler openField;
    begin
      put the value of me into the msg box;
    end;

    -----------------------------------
    VISIBLE

    Purpose: The visible property determines whether a field is visible or
    hidden. When a field is hidden, it cannot be edited or given the focus.
    Further, hidden fields cannot be edited using the Selector tool unless
    the visible property is set to true.

    When a field is created, the visible is true (the default).

    This property can also be changed using the hide and show commands. You
    are unable to modify this property using the Field Info dialog box (you
    must use the message box or a script).

    When to use it: If you have information in a field that you want the
    user to view only after a specific action is taken (such as selecting a
    button) you can use visible to hide and then show the field.



    ________________________________________________________________________
                                             Chapter 12: Properties   193
    ________________________________________________________________________


    Examples:

    set the visible of page field "Notes" to false;

    set the visible of page field "help" to the check   of button id 2;

    put the visible of field id 4;

    show page field 1;  -- sets visible to true
    hide page field 1;  -- sets visible to false

    The following button handler displays a help field when selected:

    handler select;
    begin
      show page field "help";
      wait 10000;              -- wait 10 seconds
      hide page field "help";
    end;

    -----------------------------------
    WITHEDGE

    Purpose: Use the withEdge property to determine whether a field has a
    border. When true (the default), the field is displayed with the
    edgeType as the border.

    You can modify this property using the Field Info dialog box.

    Examples:

    set the withEdge of page field 1 to true;

    put the withEdge of field "Last Name" into the message box.

    See Also: edgeType, borderColor



    ________________________________________________________________________
                                             Chapter 12: Properties   194
    ________________________________________________________________________


    BUTTON PROPERTIES

    The following section describes the properties that are used by buttons.
    Some of the properties used by buttons are also used by fields.

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

    -----------------------------------
    ACCELERATORCOLOR

    Purpose: The acceleratorColor property determines the color of the
    selected acceleratorKey (a selected character in the button's name) when
    the user presses ALT in Browse mode. Any button in your pad can be
    assigned an accelerator key, which allows for quick selection of the
    button. An acceleratorKey must be selected and showName must be true for
    acceleratorColor to have an effect.

    The range of values is from 0 to 255; The default is 7 (grey on black).

    You can modify the acceleratorColor using the Button Info dialog box.

    Examples:

    set the acceleratorColor of page button 3 to red on blue;

    Abbreviations: accelColor

    See Also: acceleratorKey, showName



    ________________________________________________________________________
                                             Chapter 12: Properties   195
    ________________________________________________________________________


    -----------------------------------
    ACCELERATORKEY

    Purpose: The acceleratorKey property defines the character in the
    button's name that the user can press to speed button selection.
    This property allows users to select buttons by holding down ALT and a
    specified character in the button's name.

    The acceleratorColor must be different from the fillColor and showName
    must be true for this property to work.

    When you press the accelerator key combination for a button, the button
    becomes highlighted and a select message is sent to that button.
    Any letter or number (A..Z,0..9) can be used an accelerator key. The
    default is empty.

    If the accelerator letter isn't within the button's name, then you will
    not see it when you press ALT. However, you can still press the ALT key
    combination to select that button.

    Examples:

    set the accelKey of page button 1 to "A";

    set the acceleratorKey of button "Home" to "H";

    Comments: Make sure you select a unique key code for the accelerator
    key. If you don't, then the button with the lowest layer gets the focus
    first. Also, be careful because button accelerator keys have priority
    over menu accelerators (such as ALT+F for File menu).

    Abbreviations: accelKey

    See Also:  acceleratorColor, showName, select

    -----------------------------------
    ALIGN

    Purpose: This property controls the positioning of the button's name
    within the button. The possible values are:

    left
    right
    centered
    The default is centered.

    Examples:

    set the align of page button 4 to right;



    ________________________________________________________________________
                                             Chapter 12: Properties   196
    ________________________________________________________________________


    -----------------------------------
    AUTOHILITE

    Purpose: The autoHilite property determines if a button is automatically
    highlighted when it receives the focus. The color of the highlighted
    button is determined by the value of hiliteColor.

    The default value of autoHilite is true.
    Buttons that have the focus will be highlighted only if hiliteIfFocus is
    true. If hiliteIfFocus is false, then the button will only be
    highlighted while the mouse is pressed and the mouse pointer is within
    the rectangle of that button.

    When a button is highlighted, the hilite property for that button is set
    to true.

    Examples:

    set the autoHilite of button 1 to true;

    set the autoHilite of button "Home" to false;

    To make sure a button gets highlighted when it has the focus:

    set the autoHilite of button 1 to true;
    set the hiliteIfFocus of button 1 to true;

    See Also: hiliteIfFocus, hiliteColor, hilite

    -----------------------------------
    BORDERCOLOR

    Purpose: Use the borderColor property to determine the color of the
    characters that form the button's border. The borderColor property will
    have no effect unless withEdge is true and the style is not transparent.

    The range of colors is from 0 to 255; the default is 7 (grey on black).

    You can modify this property using the Button Info dialog box.

    Examples:

    set the borderColor of page button 1 to 7;

    if the style of button "Notes" is not transparent then
      set the borderColor of button 1 to yellow on red;

    See Also: withEdge, acceleratorColor, fillColor, color, hiliteColor



    ________________________________________________________________________
                                             Chapter 12: Properties   197
    ________________________________________________________________________


    -----------------------------------
    CHECK

    Purpose: The check property determines whether a button is checked. This
    will only have an effect on checkBox styled buttons.

    If the check is true, then the check box button will have an X between
    the brackets:

    [X] Include Last Name

    If it false, then there will be a blank space between the brackets:

    [ ] Include Last Name

    The value of check gets modified when HyperPAD receives the select
    message initially sent to a check box styled button. For example, the
    following script in your checkBox button prevents its value (the check)
    from being toggled, because it prevents the select message from being
    sent to HyperPAD.

    handler select;
    begin
    end;

    Intercepting the select message enables you to create option button
    groups in your pads (an option button group is where one button in the
    group is checked while the other are not). Suppose you have 3 buttons,
    of which only one can be checked at a time. The button names are "Blue",
    "Red", and "Green". The script of button "Green" would be:

    handler select;
    begin
      set the check of button "Red" to false;
      set the check of button "Blue" to false;
      set the check of me to true;
    end;

    The script of button "Red" would be:

    handler select;
    begin
      set the check of button "Blue" to false;
      set the check of button "Green" to false;
      set the check of me to true;
    end;



    ________________________________________________________________________
                                             Chapter 12: Properties   198
    ________________________________________________________________________


    and the script of button "Blue" would be:

    handler select;
    begin
      set the check of button "Green" to false;
      set the check of button "Red" to false;
      set the check of me to true;
    end;

    Examples:

    set the check of page button 1 to true;

    set the check of me to false;

    set the check of the target to the salesTax > 10;

    The following handler in the script of a check box button locks and
    unlocks a field depending on whether the button is checked.

    handler select;
    begin
      get the check of me;
      set the lockText of page field "Custom Size" to it;
      pass;
    end;

    Comments: You can still modify the checkBox property for buttons that do
    not have a checkBox style (you just won't see the X).

    -----------------------------------
    COLOR

    Purpose: Use the color property to modify the
    fillColor and the borderColor of a button.

    Setting the color of a button sets both the fillColor and the
    borderColor of the button. Getting the color of a button, however,
    returns only the fillColor of the button.

    Examples:

    set the color of page button 1 to 31;

    set the color of button "Home" to white on red

    See Also: fillColor, borderColor, hiliteColor, acceleratorColor



    ________________________________________________________________________
                                             Chapter 12: Properties   199
    ________________________________________________________________________


    -----------------------------------
    EDGETYPE

    Purpose: Use the edgeType property to determine the type of border a
    button uses.

    The valid edge types are 1 to 15. The default is 1, which is a single
    width line. This property will only have an effect if the value of
    withEdge is true.

    Appendix 3 shows the available edge types and their corresponding
    values.

    Examples:

    put the edgeType of button 4 into the message box;

    The next two handlers in a button script change the border to a double
    line when the button has the focus, and sets the border back to a single
    width line when the focus changes to another object.

    handler openButton;
    begin
      set the edgeType of me to 2;
    end;

    handler closeButton;
    begin
      set the edgeType of me to 1;
    end;

    See Also: withEdge, borderColor

    -----------------------------------
    FILLCOLOR

    Purpose: The fillColor property determines the color of the interior
    portion of a button, including the button name.

    You color will have no effect if the button style is transparent.

    The valid range of colors is from 0 to 255; the default is 7 (grey on
    black).

    Examples:

    set the fillColor of button 1 to red;

    set the fillColor of button 2 to the borderColor of button 2;

    See Also: acceleratorColor, borderColor, color, hiliteColor



    ________________________________________________________________________
                                             Chapter 12: Properties   200
    ________________________________________________________________________


    -----------------------------------
    HILITE

    Purpose: Use the hilite property to determine whether a button is
    highlighted. When true, the button appears using the current color value
    of the hiliteColor property.

    Buttons that have the focus will only be highlighted if the autoHilite
    property is true. If false, then the button will only be highlighted
    when a mouse button is pressed while the mouse pointer is within the
    rectangle of the button.

    Examples:

    set the hilite of page button "Quit" to true;

    if the hilite of page button "Home" is true then
      answer "You are highlighting Home";

    See Also: autoHilite, hiliteColor

    -----------------------------------
    HILITECOLOR

    Purpose: The hiliteColor property determines the color of a button when
    it has the focus. The autoHilite property has to be true for the button
    to be able to be highlighted.

    A button can be highlighted (using the hiliteColor) under the following
    two conditions:

    1.  If the button has the focus and hiliteIfFocus is set to true.

    2.  While the mouse button is held down and the pointer is inside the
    button's rectangle.

    The range of valid colors is from 0 to 255; the default is 112 (black on
    grey).

    You can modify this property using the Button Info dialog box.

    Examples:

    set the hiliteColor of button "hello" to yellow;

    set the hiliteColor of page button 1 to
      the hiliteColor of page button 2;



    ________________________________________________________________________
                                             Chapter 12: Properties   201
    ________________________________________________________________________


    -----------------------------------
    HILITEIFFOCUS

    Purpose: Use the hiliteIfFocus property to determine whether your button
    is highlighted when it has the focus.

    When true, a button with the focus will be highlighted using the
    hiliteColor. If false, the button will not be highlighted when it has
    the focus.

    You can modify this property using the Button Info dialog box.

    Examples:

    set the hiliteIfFocus of page button 1 to true;

    -----------------------------------
    ID

    Purpose: Use the ID property to determine the unique number that
    HyperPAD assigned to this button when it was created. The only way to
    uniquely reference a specific button is with the ID.

    You can't change a button's ID.

    You can see a button's ID using the Button Info dialog box.

    Examples:

    put the id of page button 1 into fid;

    if the id of me > 20 then set the visible of me to true;

    See Also: longID

    -----------------------------------
    LAYER

    Purpose: The layer property returns the layer number of the button with
    respect to all the buttons on the page.

    You cannot change this property through a script. You must use the
    Selector tool to select a button, then use the Send Farther and Move
    Closer commands on the Object menu.

    When to use it: It is sometimes convenient to organize your button's
    layering so that the layer of a button can be used as an index into
    data.



    ________________________________________________________________________
                                             Chapter 12: Properties   202
    ________________________________________________________________________


    Examples:

    put the layer of button 1 into page field 2;

    handler select;
    begin
      -- get the line number corresponding to the layer
      get line (the layer of me) of page field "index";
      go to page it;
    end;

    -----------------------------------
    LOCATION

    Purpose: The location property determines the X (column) and Y (row)
    coordinates from the upper left corner of a button, returning two
    numbers in the "X,Y" format, like:

    10,12

    You can also change a button's location using the Selector tool, or by
    modifying the value of the rectangle property.

    Examples:

    set the location of page button 1 to 10,10;
    if the location of button "Home" is "3,4"
      then go to the next page

    Abbreviations: loc

    See Also: rectangle

    -----------------------------------
    LOCKTEXT

    Purpose: The lockText property locks a button so that it cannot be
    selected with the mouse or keyboard. Locked buttons receive no messages.

    When to use it: You can use a transparent button with the lockText
    property set to true to cover up other objects that you don't want
    selected.

    You can't modify this property using the Button Info dialog box. You
    must use either the message box or a script.

    Examples:

    set the lockText of button 1 to true;

    if the lockText of page button "Cover Up" then
      answer "Can't select that right now";



    ________________________________________________________________________
                                             Chapter 12: Properties   203
    ________________________________________________________________________


    -----------------------------------
    LONGID

    Purpose: Use longID to get a button's full identification information
    including its ID number, the name of the page or background the button
    is on, and the full DOS path of the pad it's in.

    The name is returned information is in the following format:

    button id 4 of page 4 of pad "C:\HPAD\HOME.PAD"

    You cannot change the longID of a button.

    Examples:

    put the longID of page button "exit" into the msg;

    if word 5 of the longID of the target is "page" then
      answer "This is a page button";

    See Also: ID, name, longName, layer

    -----------------------------------
    LONGNAME

    Purpose: The longName property allows you to access the long name of any
    button in a pad. The long name of a page button has the following
    format:

    button id 12 of page 45 of pad "C:\HPAD\HOME.PAD"

    For background buttons, the word bkgnd is used:

    bkgnd button id 12 of bkgnd 3 of pad "C:\HPAD\HOME.PAD"

    You cannot alter the longName of a button.

    Examples:

    put the longName of button 1 into msg;

    The next example prints out the script of button 1 with a heading
    containing its longName:

    print (the longName of button 1) & return & return;
    print (the script of button 1) & return & return;

    See Also: name, ID, longID, layer



    ________________________________________________________________________
                                             Chapter 12: Properties   204
    ________________________________________________________________________


    -----------------------------------
    NAME

    Purpose: Use the name property to determine the name of any button in
    the current pad.

    The value of the name property is the same as the name in the Button
    Info dialog box. The button's name can be referred to in a script or in
    the message box.

    You can modify this property using the Button Info dialog box.

    When to use it: By naming objects, you give yourself an easy to remember
    reference for each object in HyperPAD scripts.

    Examples:

    set the name of page button 1 of page 2 to "Last Name";
    These statements use the name property to refer to the object:

    get the name of the target;
    set the color of button it to red;
    set the align of button it to left;

    Comments: The button name cannot begin or end with a space character
    (use character 255 if you need to create space to the left of a button
    name).

    See Also: longName, align

    -----------------------------------
    RECTANGLE

    Purpose: The rectangle property determines the rectangular region
    occupied by a button. The value of rectangle is a text string of four
    numbers separated by commas, as in the following:

    upper left x, upper left y, lower right x, lower right y
    For example:

    "10,10,70,21"

    To set the rectangle of a button, you must supply all four numbers,
    separated by commas, not a text string of numbers. For example, the
    following statement will NOT work because the variable "r" contains a
    string of four numbers:

    put the rectangle of page button 1 into r;
    set the rectangle of page button 4 to r;



    ________________________________________________________________________
                                             Chapter 12: Properties   205
    ________________________________________________________________________


    The following will work:

    put the rectangle of page button 1 into r;
    set the rectangle of page button 6 to
      item 1 or r, item 2 of r, item 3 of r, item 4 of r;

    You can also set the rectangle of a button using the Selector tool.

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

    Examples:

    set the rectangle of page button 1 to 10,10,70,20;

    set the rect of page button "Home" to 10,10,20,20;
    if item 3 of the rect of button 1 > 10 then
      go to the next page;

    Abbreviations: rect

    See Also: loc



    ________________________________________________________________________
                                             Chapter 12: Properties   206
    ________________________________________________________________________


    -----------------------------------
    SCRIPT

    Purpose: The script property retrieves or replaces the
    script of any button in a pad. The value of script is a text string
    composed of lines separated by carriage returns.
    Setting this property replaces the script of a button with a new one.
    The new script must be compiled and checked for errors. Any handlers
    within the script that contain errors will not be compiled.

    You can also view and modify the script through the Button Info dialog
    box, by selecting the Script button.

    Examples:

    put the script of page button 1 into page field 1;

    set the script of button "Last Name" to stext;

    To recompile a button's script:

    set the script of pg btn 1 to the script of pg btn 1;

    -----------------------------------
    SHADOW

    Purpose: Use the shadow property to determine whether a button has a
    shadow, giving it a three-dimensional appearance. The possible values
    are true and false; the default is false.

    This property can also be modified through the button's property box.

    Note:  Some monochrome and LCD systems will be unable to display a
    shadow correctly.

    Examples:

    set the shadow of me to false;

    set the shadow of page btn 1 to true;

    The shadow takes on the background color of the area on the screen
    behind the button. The shadow is drawn as follows:



    ________________________________________________________________________
                                             Chapter 12: Properties   207
    ________________________________________________________________________


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


    -----------------------------------
    SHOWNAME

    Purpose: Use the showName property to determine whether the button's
    name is shown. When showName is true (the default), the name of the
    button is displayed using the current value of the align property.

    You can modify this property using the Button Info dialog box.

    When to use it: In most cases, the name of the button will be necessary
    for the user to know what is being selected.

    Examples:

    set the showName of page button 1 to true;

    See Also: align, name

    -----------------------------------
    STYLE

    Purpose: The style property allows you to determine the style of a
    button to. The possible values are: opaque, transparent, and checkBox.

    You can also modify this property using the Button Info dialog box.

    Examples:

    set the style of page button 1 to checkBox;

    if the style of page button "wow" is opaque then
      set the focus to page field 2;

    See Also: check



    ________________________________________________________________________
                                             Chapter 12: Properties   208
    ________________________________________________________________________


    -----------------------------------
    VISIBLE

    Purpose: Use the visible property to determine whether a
    button is shown or hidden. When a button is hidden, it is invisible and
    cannot be edited using the Selector tool unless the visible property is
    set to true.

    When a button is created, it is visible (the default). This property can
    be changed using hide or show. You can't change this property using the
    Button Info dialog box.

    When to use it: If you want to make a button appear or disappear,
    depending upon the user's action, you would modify this property.

    Example:

    set the visible of page button "Word" to false;

    set the visible of page button "help" to
      not the visible of the message box;

    See Also: lockText

    -----------------------------------
    WITHEDGE

    Purpose: Use the withEdge property to determine whether a button has
    characters defining its borders. When withEdge is true (the default), a
    button is displayed with a border. (The border type is the value of the
    edgeType property.)

    Examples:

    set the withEdge of page button 1 to true;

    See Also: edgeType, borderColor



    ________________________________________________________________________
                                             Chapter 12: Properties   209
    ________________________________________________________________________


    PAGE PROPERTIES

    -----------------------------------
    CANTDELETE

    Purpose: Setting cantDelete to true prevents a page from being deleted.
    When false, the page can be deleted using Delete Page on the Edit menu.

    This property can also be modified through the Page Info dialog box.

    When to use it: Set cantDelete to true when you want to protect pages
    from being accidentally deleted.

    Examples:

    set the cantDelete of page 2 to false;

    if the userLevel <= 2 then
      set the cantDelete of page 3 to true;

    See Also: userLevel, delete

    -----------------------------------
    ID

    Purpose: Use this property to retrieve the identifier that HyperPAD gave
    a page when it was created. The ID is the most reliable way to refer to
    a  page.

    You can see, but not modify, the page ID using the Page Info dialog box.

    Examples:

    put the id of page 1 into pg;

    if the id of me > 20 then go to page 1;

    See Also: longID

    -----------------------------------
    LONGID

    Purpose: Use the longID property to get a page's complete name,
    including the ID number and the full DOS path of the pad, as in the
    following example:

    page id 2 of pad "C:\HPAD.HOME.PAD"

    You cannot modify a page's longID.

    See Also: ID



    ________________________________________________________________________
                                             Chapter 12: Properties   210
    ________________________________________________________________________


    -----------------------------------
    LONGNAME

    Purpose: Use the longName property to determine a page's complete name,
    including the page ID and full DOS pathname of the current pad, in the
    following format:

    page id 2 of pad "C:\HPAD\HOME.PAD"

    Examples:

    put the longID of this page into the message box;

    The following example prints the current page with the longName as the
    heading.

    print the longName of this page;
    print this page;

    See Also: name

    -----------------------------------
    NAME

    Purpose: Use the name property to get or set the name of a page. This is
    the same name that appears in the Page Name option in the Page Info
    dialog box.

    Examples:

    if the name of page is "HOME" then
      answer "You are home now!";

    The following handler sets the name of the page when the page is
    created. This handler belongs in a background or pad script.

    handler newPage;
    begin
      set the name of the target to "page at" && time();
    end;

    See Also: longName, ID, longID



    ________________________________________________________________________
                                             Chapter 12: Properties   211
    ________________________________________________________________________


    -----------------------------------
    SCRIPT

    Purpose: Use the script property to retrieve or replace the current
    script of the page. By using the set command, this property will replace
    the current page script with a new one. The new script will be
    immediately compiled and checked for errors. Any handlers within the
    script that contain errors will not be compiled.

    The value of the script is a text string composed of lines separated by
    carriage returns.

    You can get to a page's script using the Page Info dialog box.

    Examples:

    put the script of page 3 into stext;

    set the script of page 6 to stext;

    The next example appends an openPage handler to the current script of
    the page. The new handler beeps when the page is opened.

    set the script of page 1 to the script of the page &
      return & return &
      "handler openPage;" & return &
      "begin" & return &
      "beep;" & return &
      "end;" & return;



    ________________________________________________________________________
                                             Chapter 12: Properties   212
    ________________________________________________________________________


    BACKGROUND PROPERTIES

    -----------------------------------
    CANTDELETE

    Purpose: Setting cantDelete to true prevents a background from being
    deleted. When false, the background can be deleted by deleting all of
    the pages that use that background.

    You can modify this property using the Background Info dialog box.

    When to use it: Set cantDelete to true when you want to protect
    backgrounds from being accidentally deleted.

    Examples:

    set the cantDelete of page 2 to false;

    if the userLevel <= 2 then
      set the cantDelete of page 3 to true;

    See Also: userLevel, delete

    -----------------------------------
    ID

    Purpose: The ID property gets the number which uniquely identifies a
    background. Using the ID number is the only sure way to uniquely
    reference a background.

    You can't change a background's ID.

    When to use it: Use the ID number in a script to refer to a background.

    Examples:

    put the id of bkgnd 8 into fid;

    go to background id 19;

    -----------------------------------
    LONGID

    Purpose: The longID property gets the background's full name, including
    its ID number and the full DOS path of the pad it's in, as in the
    following:

    bkgnd id 4 of "C:\HPAD\INDEX.PAD"

    You can't change the longID of a background.

    See Also: ID, name, longName



    ________________________________________________________________________
                                             Chapter 12: Properties   213
    ________________________________________________________________________


    -----------------------------------
    LONGNAME

    Purpose: The longName property retrieves the background's ID number and
    the full DOS path of the pad it's in, using the following format:

    bkgnd id 5 of pad "C:\HPAD\PHONE.PAD"

    You can't change the longName of a background.

    Examples:

    get the longName of bkgnd 5;

    put the longName of bkgnd 1 into the msg;

    See Also: name, ID, longID

    -----------------------------------
    NAME

    Purpose: Use the name property to get or set the name of a background.

    When to use it: It is often easier to refer to a background by name in a
    script then to use its object or ID number.

    You can modify a background's name using the Background Info dialog box.

    Examples:

    if the name of this bkgnd is "wild" then
      go to page 5;

    put the name of this background into page field 1;

    set the name of background id 4 to "template";

    See Also: longName, ID, longID



    ________________________________________________________________________
                                             Chapter 12: Properties   214
    ________________________________________________________________________


    -----------------------------------
    SCRIPT

    Purpose: The script property gets or replaces the current background
    script. Setting this property replaces the current background script
    with a new one. The new script will be compiled immediately and checked
    for errors. Any handlers within the script that contain errors will not
    be compiled.

    The value of the script is a text string composed of lines separated by
    carriage returns.

    You can also access the Background's script through the background
    property box.

    Examples:

    put the script of bkgnd 1 into junk;

    set the script of bkgnd 5 to ex;



    ________________________________________________________________________
                                             Chapter 12: Properties   215
    ________________________________________________________________________


    MESSAGE BOX PROPERTIES

    -----------------------------------
    LOCATION

    Purpose: Use the location property to determine the X (horizontal) and Y
    (vertical) coordinates of the upper left corner of the message box. The
    message box's position on-screen can be changed or accessed using the
    location property.

    If you get the location of the message box, it returns two numbers in
    "X,Y" format, such as

    12,14

    When you set the location of the message box, you must supply two
    parameters, like the following example:

    set the location of msg to 12,14;

    You can also modify the message box's position using the mouse.

    Examples:

    set the location of the message box to 32,1;

    Abbreviations: loc

    -----------------------------------
    VISIBLE

    Purpose: With the visible property, you determine whether
    the message box is shown or hidden. When the message box is hidden, it
    is invisible and cannot be accessed (although you can still put text
    into it). By default, the message box is not visible.

    This property can also be changed using the hide and show commands.

    Example:

    set the visible of msg to false;

    The following statements are equivalent:

    set the visible of the message box to true;
    show the message box;

    See Also: show, hide



    ________________________________________________________________________
                                             Chapter 12: Properties   216
    ________________________________________________________________________


    -----------------------------------
    WIDTH

    Purpose: Use the width property to adjust the size of the
    message box. The cannot set the width larger than the screen width.

    When to use it: When you want to shrink the message box so it doesn't
    obstruct your view of other elements on the page or background.

    Examples:

    To make the message box 40 characters wide:

    set the width of the msg to 40;



    ________________________________________________________________________
                                             Chapter 12: Properties   217
    ________________________________________________________________________


    TOOL BOX PROPERTIES

    -----------------------------------
    LOCATION

    Purpose: The location property determines the X (horizontal)
    and Y (vertical) coordinates of the upper left corner of the tool box,
    returning two numbers in "X,Y" format, like:

    18,4

    You can also move the tool box around the screen with the mouse.

    Examples:

    set the location of the tool box to 10,5;

    put the location of the tool box into msg;

    Abbreviations: loc

    -----------------------------------
    VISIBLE

    PURPOSE: USE the visible property to hide or show the tool box.

    When the tool box is hidden, it cannot be used by the pad user. By
    default, the tool box is not displayed (the visible is false).

    This property can be changed using the hide or show commands.

    You can also toggle the visibility of the tool box by selecting Tool Box
    from the Workspace menu.

    Example:

    set the visible of the tool box to false;

    See Also: hide, show



    ________________________________________________________________________
                                             Chapter 12: Properties   218
    ________________________________________________________________________


    MENU BAR AND STATUS BAR PROPERTIES

    -----------------------------------
    VISIBLE

    Purpose: Use the visible property to turn the menu bar or
    status bar on or off.

    You can also modify this property using the hide and
    show commands, or by accessing the Menu Bar and Status Bar
    commands from the Workspace menu. ALT+SPACE also lets you toggle the
    menu bar on and off.

    The status bar can't be displayed without the menu bar.

    When to use it: If your pad includes its own menu bar, or if you don't
    want your users to access the menu commands, set the visible
    of the menu bar to off. If you want your pad users to be able to read
    messages you place on the bottom line on the screen, turn the status bar
    off.

    Example:

    set the visible of the menu bar to false;

    set the visible of the status bar to true;

    if the visible of the menu bar then
      set the visible of the status bar to true;

    See Also: show, hide
