Click above to get retro games delivered to your door ever month!

ACHOICE()


Syntax:     ACHOICE(<expN1>, <expN2>, <expN3>, <expN4>, <array1>
            [,<array2> [,<expC> [,<expN5> [,<expN6>]]]])

Purpose:    To execute a pop-up menu using an array of character strings
            as menu items.

Arguments:  <expN1...expN4> are the top, left, bottom and right
            window coordinates respectively.

            <array1> is an array of character strings to display as
            menu items.

            <array2> is a parallel array--one element for each item
            in <array1>--that specifies selectable menu items.  Elements
            can either be logical values or characters strings.  If the
            element is false (.F.), the corresponding menu item is not
            available.  If the element contains a character string, it
            is evaluated as a macro expression.  If the macro evaluation
            is false (.F.), the menu item is not available.  In
            addition, if false (.F.) is specified, all menu items are
            unavailable.

            <expC> is the name of a user-defined function that
            executes generally when an unrecognizable key is pressed.
            Specify the function name without parentheses or arguments.
            Note that the behavior of ACHOICE() is affected by the
            presence of this argument.  Refer to the discussion below
            for further information.

            <expN5> is the initial current item.  If not specified,
            the default is the first selectable item in <array1>.

            <expN6> is the initial relative window row beginning
            with position zero.  If not specified, the initial relative
            window row is the row containing the initial current item.

Returns:    A numeric value.

            ACHOICE() returns the index of the menu item in the array of
            choices.  If the selection is aborted, ACHOICE() returns
            zero.

Usage:      ACHOICE() has two modes depending on whether or not you
            specify the user-defined function argument (<expC>).  If you
            do not specify a user function, ACHOICE() displays the list
            of items within the given screen coordinates.  It then
            executes the following actions when you press the
            corresponding keys.

            Table: ACHOICE() Keys
            ---------------------------------------------------------------
                        User
            Key         Function Key   Action
            ---------------------------------------------------------------
            Uparrow        Yes         Up one item
            Dnarrow        Yes         Down one item
            Home           No          First item
            End            No          Last item
            Ctrl-Home      Yes         First item in window
            Ctrl-End       Yes         Last item in window
            PgUp           Yes         Up the number of elements defined
                                       for the menu window to the same
                                       relative row position
            PgDn           Yes         Down the number of elements
                                       defined for the menu window to
                                       the same relative row position
            Ctrl-PgUp      Yes         First item
            Ctrl-PgDn      Yes         Last item
            Return         No          Select item, returning position
            Esc            No          Abort selection, returning zero
            Leftarrow      No          Abort selection, returning zero
            Rightarrow     No          Abort selection, returning zero
            First letter   No          Next item with same first letter
            ---------------------------------------------------------------

            If the number of items in <array1> exceeds the number of
            rows in the menu window, the items scroll when you attempt
            to cursor beyond the top or bottom of the menu window.  Note
            that the highlight does not wrap when you reach the top or
            bottom of the list of items.  Pressing the first letter
            does, however, wrap the highlight within the set of items
            whose first letter matches the key you are pressing.

            User Function: If you specify a user function, the
            behavior of ACHOICE() changes to some degree.  Primarily,
            fewer keys are automatically executed by ACHOICE() and
            control passes to the user function when there is a key
            exception or there are no more keys to process and ACHOICE()
            goes to idle.  Keys that generate an exception include:
            Leftarrow, Rightarrow, Home, End, Return, Esc and letter
            keys.  Keys that ACHOICE() will execute are listed in the
            table above.

            When ACHOICE() executes the user function, it automatically
            passes the following three parameters: status message,
            current element in the array of items, and the relative
            position within the menu window.  The status message
            indicates the current state of ACHOICE() depending on the
            key pressed and action taken by ACHOICE() prior to executing
            the user function.  The status parameter has the following
            possible values:

            Table: ACHOICE() Status Messages
            ------------------------------------------------
             Mode       Description
            ------------------------------------------------
               0        Idle
               1        Cursor past top of list
               2        Cursor past end of list
               3        Keystroke exception
               4        No item selectable
            ------------------------------------------------

            After the user function has performed whatever operations
            are appropriate to the ACHOICE() state or LASTKEY(), RETURN
            a value requesting ACHOICE() to perform an operation from
            the set defined in the table below:


            Table: Requests to ACHOICE() from User Function
            ----------------------------------------------------------
            Value    Action
            ----------------------------------------------------------
               0     Abort selection, return zero
               1     Make selection, returning index of current item
               2     Continue selection process
               3     Go to the next item whose first
                     character matches the last key pressed
            ----------------------------------------------------------

            Refer the user function discussion under DBEDIT() for an
            explanation of how to structure the user function to process
            status messages and handle keys.

            Color: Menu items are displayed in standard color, the
            highlight is in enhanced color, and the unavailable items
            are displayed in the unselected color.  For example, the
            following color statement:

            SET COLOR TO W+/N,BG+/B,,,W/N

            displays a menu that is bright white on black, the highlight
            is bright cyan on blue, and the unavailable menu items are
            dim white on black.

            Nesting: You can call multiple copies of ACHOICE()
            within each copy of ACHOICE() allowing you to create nested
            or hierarchical menus.

Library:    EXTEND.LIB


----------------------------------- Example --------------------------------

   The following example demonstrates a call to ACHOICE() using a
   prototypical user function.  The user function illustrates a suitable
   general structure for most applications and uses of ACHOICE().

   PRIVATE pad[3]

   pad[1] = "One    "
   pad[2] = "Two    "
   pad[3] = "Three  "

   menuchoice = ACHOICE(10, 10, 12, 15, pad, "", "Afunc")

   RETURN


   FUNCTION Afunc

   PARAMETERS status, curr_elem, rel_row
   PRIVATE request, scr_row, scr_col

   * Define status messages.
   IDLE        = 0
   PAST_TOP    = 1
   PAST_END    = 2
   KEY_EXCEPT  = 3
   NO_ITEM     = 4

   * Define user function requests.
   ABORT_SEL   = 0
   MAKE_SEL    = 1
   CONT_SEL    = 2
   GOTO_ITEM   = 3

   * Save screen coordinates.
   scr_row = ROW()
   scr_col = COL()

   * Save latest keystroke.
   keystroke = LASTKEY()
   request = CONT_SEL

   DO CASE
   CASE status = NO_ITEM
      * Nothing selectable..abort.
      request = ABORT_SEL

   CASE status = KEY_EXCEPT
      * Keystroke exception..process it.
      request = Key_except()

   CASE status = PAST_TOP
      * Attempted to go past the top.
      TONE(100, 1)
      request = CONT_SEL

   CASE status = PAST_END
      * Attempted to go past the end.
      TONE(100, 1)
      request = CONT_SEL

   ENDCASE

   * Restore screen coordinate.
   @ scr_row, scr_col SAY ""

   RETURN request


   FUNCTION Key_except

   DO CASE
   CASE keystroke = 27
      * Esc..abort ACHOICE().
      RETURN ABORT_SEL

   CASE keystroke = 13 .OR. keystroke = 19 .OR. keystroke = 219
      * Quit with no abort..only Return causes selection.
      RETURN MAKE_SEL

   CASE keystroke = 1
      * Home key..top of list
      KEYBOARD CHR(31)        && Ctrl-PgUp
      RETURN CONT_SEL

   CASE keystroke = 6
      * End key..end of list.
      KEYBOARD CHR(30)        && Ctrl-PgDn
      RETURN CONT_SEL

   CASE IsData(keystroke)
      * Request character search.
      RETURN GOTO_ITEM

   ENDCASE


   FUNCTION IsData
   PARAMETER key

   * Determine if a key is data suitable for entry in place.
   RETURN (key >= 32 .AND. key < 249 .AND. key <> 219;
          .AND. CHR(key) <> ";")