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

  Name:     mx_choice() - emulate achoice() with mouse support
  Usage:    <integer> = mx_choice(<r1>,<c1>,<r2>,<c2>,<array>,[<attrib>])
  Params:   integer <r1> - the top row of the window
            integer <c1> - the left column of the window
            integer <r2> - the bottom row of the window
            integer <c2> - the right column of the window

            array <array>- the array to display. All elements must be of
            type string.

            integer <attrib> - the color to use for the window,
            optional. If <attrib> is left off, then Clipper's
            standard foreground color is used for the box, and the
            enhanced color is used for the highlight.

  Returns:  an integer equal to the element number that was highlighted
            at the time the user pressed return or clicked the mouse
            button. If ESCape was pressed or the mouse was clicked
            outside that window area when m_data(3) is set to 1, then a 0
            is returned. You can also check the status return value that is
            left in m_data(30) to see what event made the window return.

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

                 declare menuarray[3]
                 menuarray[1] = "Print a report by last name"
                 menuarray[2] = "Print a report to a file"
                 menuarray[3] = "Print a report to the screen"

                 choice = mx_choice(10,20,16,60,menuarray,23)

                 if choice = 0
                      return
                 elseif choice = 1
                      do byLASTNAME
                 elseif choice = 2
                      do toFILE
                 elseif choice = 3
                      do toSCREEN
                 endif

  Example2: This example sets the title to use, and starts the array display
            at element 20, and the highlight will be positioned at row 3 in
            the window. Assume that the array MYarray[] has 30
            elements:

                 declare MYarray[30]
                 * fill array with values here....

                 * setup the title
                 m_title("Select option, Press return.")

                 * setup the starting element number to 20
                 m_data(1,20)

                 * setup the starting highlighted row number to 3
                 m_data(2,3)

                 * turn the restart flag on so the function knows
                 * to use values defined in m_data(1), m_data(2)
                 m_data(29,1)

                 choice = mx_choice(10,10,20,65,MYarray)

                 * shut restart flag off
                 m_data(29,0)

                 do case.....

  Note:     Mx_choice() contains full mouse support if a mouse is
            present, but a mouse is not necessary to use mx_choice().
            You can eliminate mouse support by specifying mouse(.F.).
            See the mouse() function for a description. The following keys
            and functions are available in mx_choice().

                 UP ARROW       - goto previous line
                 DOWN ARROW     - goto next line
                 PGUP           - goto previous page
                 PGDN           - goto next page
                 HOME           - goto top line in window
                 END            - goto last line in window
                 CTRL/HOME      - goto first element in array
                 CTRL/END       - goto last element in array
                 LEFT ARROW     - goto previous line
                 RIGHT ARROW    - goto next line
                 ESC            - exit
                 RETURN         - selects highlighted line
                                  and returns the element #
                 ALPHA KEYS     - causes mx_choice() to
                                  search for the next
                                  element that matches the
                                  key pressed, if found, the
                                  highlight is moved to that
                                  element.

            To expand/shrink or move the window, use the following
            keys. Use the arrow keys on the numeric keypad only.

                 LEFT SHIFT+LEFT ARROW    - shrink right side
                                            of the window
                 LEFT SHIFT+RIGHT ARROW   - expand right side
                                            of the window
                 LEFT SHIFT+UP ARROW      - shrink bottom of
                                            the window
                 LEFT SHIFT+DOWN ARROW    - expand bottom
                                            of the window
                 SCROLLOCK+UPARROW        - move window up
                 SCROLLOCK+DOWNARROW      - move window
                                            down
                 SCROLLOCK+LEFTARROW      - move window left
                 SCROLLOCK+RIGHTARROW     - moves window
                                            right

            If a mouse is present, the following mouse options
            are supported in mx_choice()

            TO                  - ACTION
            goto previous line  - click left button on the up
                                  arrow
            goto next line      - click left button on the
                                  down arrow
            goto previous page  - click right button
                                  on the up arrow
            goto next page      - click right button on
                                  the down arrow
            goto first element  - click left mouse button
                                  on the top edge of window
            goto last element   - click left mouse button on
                                  bottom edge of window
            pan right           - click left mouse button
                                  on the right arrow
            pan left            - click left mouse button
                                  on the left arrow
            ESCape              - click left button on the
                                  triple bar in status line
            select an option    - move cursor onto the
                                  option and click on
                                  the left button
            expand right side   - press right mouse button
                                  while cursor is on
                                  right border of window
                                  and pull right
            shrink right side   - press right mouse button
                                  while mouse cursor is on
                                  the right border of the
                                  window and pull left
            expand the bottom   - press right mouse button
                                  while the cursor is on
                                  the bottom border of the
                                  window and pull down
            move the window     - press right mouse button
                                  while the cursor is in
                                  the center of the window
                                  and drag it to the new
                                  location.

       In addition, pressing an alphanumeric key cause mx_choice() to scan
       the highlight to the next element where the first character of that
       element matches the key pressed. This search is not case sensitive. If
       no more elements are found where the first character matches the key
       pressed, mx_choice() loops back to the beginning. You can also have
       mx_choice() find the element where the first character matches and
       automatically select that element by setting m_data(19,1). This is the
       return if keystroke matches flag, see m_data() for more information.

  Mouse Messages:

       The following Mouse Message Area messages are observed by
       mx_choice(). Each message has significance upon entry or exit as
       stated in each of the descriptions. You do not have to set these values
       in order for mx_choice() to work. See the m_data() function for more
       information on how to set or retrieve these values.

       m_data(30)- on exit, this message contains a number which
                   describes what happened inside the function. The
                   following return values can be returned by
                   mx_choice() via m_data(30):

                 -3   - array was empty (no elements to display)
                 -4   - window size too small, not enough rows
                 -5   - window size too small, not enough columns
                 -6   - window started outside the virtual window
                        coordinates defined by m_data() messages
                        8, 9, 10 or 11.
                  0   - user pressed ESCape to exit.
                 -2   - user clicked outside window area. This
                        value is reliable only if m_data(3) is
                        set to 1 before you execute mx_choice().
                 -1   - user pressed return, selection made.

       m_data(1) - on entry/exit, - on entry if m_data(29) (the auto
                   restart flag) is 1, then the number here is used as
                   the element number to display as the first row
                   inside the window. If m_data(1) is 15 and
                   m_data(29) is 1, then the array will be displayed
                   with element 15 as the first element in the
                   window. Upon exit from mx_choice(), m_data(1)
                   returns the element number that was being
                   displayed as the first line in the window at the
                   time of exit.

       m_data(2) - on entry/exit,- on entry if m_data(29) (the auto
                   restart flag) is 1, then the number here is used as
                   the row number to display as the highlighted row
                   inside the window. If m_data(1) is 15  and
                   m_data(29) is 1 and m_data(2) is 3, then the
                   array will be displayed with element 15 as the first
                   element in the window and the highlight will be on
                   the third row in the window. Upon exit from
                   mx_choice(), m_data(2) returns the row number
                   that the highlight was last on before exiting.

       m_data(3) - on entry, if this is set to 1 mx_choice() will return if
                   the user clicks outside the mx_choice() window.

       m_data(4) - on exit, this value returns 1 of the user clicked
                   outside the mx_choice() window area, or 0 if they
                   clicked within the window area.

       m_data(4) - on exit, this message is set to 1 if the user moved
                   the window to a new location, or resized it. If 0,
                   then the window is exactly as you defined it.

       m_data(8) - on entry, the user is not allowed to move the
                   window past the top row specified here. Also
                   known as the top virtual row. Use this to limit
                   where the window can be moved to.

       m_data(9) - on entry, the user is not allowed to move the
                   window past the left column specified here. Also
                   known as the left virtual column. Use this to limit
                   where the window can be moved to.

       m_data(10)- on entry, the user is not allowed to move the
                   window past the bottom row specified here. Also
                   known as the bottom virtual row. Use this to limit
                   where the window can be moved to.

       m_data(11)- on entry, the user is not allowed to move the
                   window past the right column specified here.
                   Also known as the left virtual column. Use this to
                   limit where the window can be moved to.

       m_data(12)- on entry, if this is set to 0 the user will not be
                   allowed to move the window.

       m_data(16)- on entry, the shadow type to use for the display
                   window based on the layout of the numeric keypad.
                   See the box() function for shadow descriptions

       m_data(17)- on entry, the color to use for the shadow. this is
                   the same shadow colors for the box() function.
                   See the box() function for shadow descriptions

       m_data(18)- on entry, if this is set to 0 the user will not be
                   allowed to expand the right side of the window.

       m_data(19)- on entry, if this message is set to 1, then
                   mx_choice() will return with a selection made if
                   an alphanumeric key is pressed that matches the
                   first letter of an array element. This is normally 0.

       m_data(20)- on entry, if this is set to 0 the user will not be
                   allowed to pull down/up the bottom of the window.

       m_data(21)- on entry, if this value is set to 0, the user will not be
                   allowed to scroll the inner contents of the window.
                   Normally set this to 1 (which is the default). setting
                   this to 0 also turns off the alphanumeric key search
                   option.

       m_data(22)- on entry, if this is set to 1, mx_choice()
                   automatically restores the screen upon exit.

       m_data(23)- on entry, if this is set to 0, the user is not allowed
                   to pan the inner contents of the view window.

       m_data(24)- on exit, upon exiting the function, mx_choice()
                   places the top row coordinate of the window
                   here so you can see where the window was moved
                   to.

       m_data(25)- on exit, upon exiting the function, mx_choice()
                   places the left column coordinate of the window
                   here so you can see where the window was moved
                   to.

       m_data(26)- on exit, upon exiting the function, mx_choice()
                   places the bottom row coordinate of the window
                   here so you can see where the window was moved
                   to.

       m_data(27)- on exit, upon exiting the function, mx_choice()
                   places the left column coordinate of the window
                   here so you can see where the window was moved
                   to.

       m_data(28)- on exit, if this value is 1, then the user moved or
                   resized the window. If it is 0, then the window is
                   exactly as you defined it.

       m_data(29)- on entry, if this message is set to 1, the array is
                   displayed starting at the element defined in
                   m_data(1) and the highlight is moved to the row
                   defined in m_data(2).

       m_frame() - on entry, the frame characters to use for the display
                   window. mx_choice() reads the characters returned
                   by m_frame() and uses them as the frame
                   characters for the window. Set the frame characters
                   for mx_choice() as follows: m_frame(<frame>).
                   See the box() function for more details on frame
                   characters.

       m_title() - on entry, the title to display in the title area of the
                   mx_choice window. The title area is the area to
                   the left of the control panel. mx_choice() uses the
                   text returned by m_title() as the title. Set the title
                   for use by mx_choice() as follows: m_title(<title>)

  Warning:  mx_choice() attempts to make sure that your window
            coordinates are valid, and large enough to display the control
            panel. If it is not, mx_choice() will exit with a return code
            in m_data(30). Make sure that you account for the control
            panel in your column coordinates. The minimum window
            height is 5 lines - the minimum window width is 7 columns.

  Note:     The Clipper source code to mx_choice() is available to you
            for modification on the source disk in the file
            c_mx_cho.prg.