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

  Name:     m_choice() - emulate achoice() with mouse support
  Usage:    <integer> = m_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 = m_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
            35 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 = m_choice(10,10,20,65,MYarray)

                 * shut restart flag off
                 m_data(29,0)

                 do case.....

  Note:     M_choice() contains full mouse support if a mouse is
            present, but a mouse is not necessary to use m_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 m_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 row and
                                  returns it's element number
                 ALPHA KEYS     - causes m_choice() to
                                  search for the next
                                  element that matches
                                  the key pressed, if
                                  found, the highlight is
                                  moved to that element.

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

            TO                  - ACTION
            goto previous line  - click the left button on
                                  the up arrow
            goto next line      - click the left button on
                                  the down arrow
            goto previous page  - click the right button
                                  on the up arrow
            goto next page      - click the right button
                                  on the down arrow
            goto first element  - click the left button
                                  on the top edge of
                                  window
            goto last element   - click the left mouse
                                  button on bottom edge
                                  of the window
            ESCape              - click left button on the
                                  triple bar in status line
            select a line       - move cursor onto the
                                  line of text and click on
                                  the left button

       In addition, pressing an alphanumeric key cause m_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, m_choice() loops back to the beginning. You can also
       have m_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
       m_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 m_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
                   m_choice() via m_data(30):

                 -3   - array was empty (no elements to display)
                  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 m_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 m_choice(), m_data(1)
                   returns the element number that was being
                   displayed as the first line in the window.

       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
                   m_choice(), m_data(2) returns the row number
                   that the highlight was last on

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

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

       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(19)- on entry, if this message is set to 1, then
                   m_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(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, m_choice()
                   automatically restores the screen upon exit.

       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. m_choice() reads the characters
                   returned by m_frame() and uses them as the
                   frame characters for the window. Set the frame
                   characters for m_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
                   m_choice window. The title area is the area to
                   the left of the control panel. m_choice() uses the
                   text returned by m_title() as the title. Set the title
                   for use by m_choice() as follows:
                   m_title(<title>)

  Warning:  m_choice() attempts to make sure that your window
            coordinates are valid, and large enough to display the
            control panel. If it is not, m_choice() will expand the
            window until the control panel fits. 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.

  Hint:     m_choice() is a static window. If you want a window that
            moves you can use mx_choice(). Note that these functions
            are full featured and therefore much larger than normal
            functions. If you wish to display static m_choice() windows
            and moveable mx_choice() windows, you are better off
            using mx_choice() and controlling it's movement with the
            m_data() messages rather than linking in both m_choice()
            and mx_choice(). The Clipper source code to m_choice() is
            available to you for modification on the source disk in the
            file c_m_choi.prg.