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

  Name:     mx_dbfview() - display DBF fields in resizeable window
  Usage:    <integer> = mx_dbfview(<r1>,<c1>,<r2>,<c2>,<titles>,<fields>,;
                                   [<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 <titles>- an array of titles to display above each
            field column. all elements must be of type string.
            array <fields> - an array of field expressions to display.
            All elements must evaluate to 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 record 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 the
            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.

            The array of titles are used to display a title above each
            column of field expressions. If the title is longer than the
            field expression to be displayed, then the length of the title
            is used to define the width of that column.

            The array of fields are strings of field names or expressions
            that evaluate to a displayable value. The value returned
            by the expression contained in each element of this array
            must evaluate to type string in order to be displayed
            properly. If you have numeric, date, or logical variables
            in the DBF, you must use the DTOC() STR() or IIF()
            functions to convert the field or expression to string
            type.

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

            This example uses a DBF with 5 fields, first name, last
            name, phone number, age, and entry date. The field array
            is loaded with the proper functions to convert all fields
            to string type. the age field is numeric, and the date field
            is a date type. the row/col coordinates are declared public
            and are sent to mx_dbfview() with the @ sign so that
            mx_dbfview() can load the ending window coordinates back
            into the coordinate variables for use the next time.

                 * declare the titles array
                 declare TITLES[5]

                 * load the titles array with the column descriptions
                 titles[1] = "First Name"
                 titles[2] = "Last Name"
                 titles[3] = "Phone Number"
                 titles[4] = "Age"
                 titles[6] = "Entry Date"

                 * load the fields array with the expressions to
                 * display in the columns of the window
                 declare FIELDS[5]
                 fields[1] = "fname"
                 fields[2] = "lname"
                 fields[3] = "phone"
                 fields[4] = "str(age)"
                 fields[5] = "dtoc(mdate)"

                 * declare the row/col variables
                 public trow, tcol, brow, bcol

                 trow = 10
                 tcol = 10
                 brow = 20
                 bcol = 70

                 * open the DBF and index
                 USE NAMES index LNAME

                 * display the DBF window
                 choice = ;
                 mx_dbfview(@trow,@tcol,@brow,@bcol,titles,fields,23)

                 * check return value
                 if (choice < 1)
                      return         && no selection made
                 endif

            At this point, the variable choice contains the record
            number of the users selection. Now you can enter a get,
            display the fields or do whatever processing you
            would normally do after the user makes a selection. If the
            user moved the window, trow/tcol etc. contain the new
            coordinates automatically because the @ sign was used.

  Example2: This next example loads the m_data() messages with values
            to display a title line, sets up a new shadow type, and
            makes the shadow color Cyan (BG).

                 * load the title
                 m_title("Use arrow keys to move highlight, "+;
                          "return selects")

                 m_data(16,3)   && load shadow to lower right
                 m_data(17,3)   && load shadow color for cyan

                 * display the window
                 choice = mx_dbfview(10,10,20,70,titles,fields,23)

  Example3: This next example causes mx_dbfview() to goto record
            50, and to place the highlight on row 4 of the window.

                 * load the record number into m_data()
                 m_data(31,50)

                 * load the highlight row number into m_data()
                 m_data(2,4)

                 * now set the restart flag to 1 so m_dbfview() uses
                 * the values put into m_data areas 31 and 2
                 m_data(29,1)

                 * display the DBF view window. m_dbfview() will
                 * goto the record in m_data(31), and will position
                 * the highlight on the row defined in m_data(2)

                 choice = mx_dbfview(10,10,20,70,titles,fields,23)

  Note:     Mx_dbfview() contains full mouse support if a mouse is
            present, but a mouse is not necessary to use mx_dbfview().
            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_dbfview().

                 UP ARROW       - goto previous record
                 DOWN ARROW     - goto next record
                 PGUP           - goto previous page
                 PGDN           - goto next page
                 HOME           - goto top row in window
                 END            - goto last row in window
                 CTRL/HOME      - goto first record
                 CTRL/END       - goto last record
                 LEFT ARROW     - pan to previous column
                 RIGHT ARROW    - pan to next column
                 ESC            - exit
                 RETURN         - selects highlighted record
                                  and returns the record #
                 ALPHA KEYS     - causes mx_dbfview() to
                                  seek the first record that
                                  matches the uppercase
                                  value of the key pressed.
                                  This option only works if
                                  an index file is used.
                 ALT/S          - search for data. You can
                                  do a seek on a string if
                                  an index is in use. Only
                                  string values can be
                                  seeked.
                 ALT/R          - cause the dbfview window
                                  to be refreshed. Use this
                                  to redraw the window.
                                  Popout to the set key to
                                  procedure, change the
                                  index order, and use
                                  nstuff() to stuff an inkey()
                                  value of 275 (ALT/R)
                                  into the buffer, forcing
                                  a refresh of the window.
                 ALT/G          - Enter a record number
                                  to goto.

            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 down
                 SCROLLOCK+LEFTARROW      - move window left
                 SCROLLOCK+RIGHTARROW     - move right

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

            TO                  - ACTION
            goto prev. record   - click left button on the up
                                  arrow
            goto next record    - 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 record   - click left mouse button
                                  on the top edge of window
            goto last record    - click left mouse button on
                                  bottom edge of window
            ESCape              - click left button on the
                                  triple bar in status line
            select a record     - move cursor onto the
                                  record and click on
                                  the left button
            to search for text  - click the mouse on the
                                  Record #: portion of the
                                  status line.
            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.

       Pressing an alphanumeric key causes mx_dbfview() to do a seek on the
       active index. If a match is found, the window is refreshed starting
       at the found record. You must have an index file in use, and the
       index expression must be string type. The same goes for the ALT/S
       search option. You can modify the source code if you need to seek
       on other types of expressions.

  Mouse Messages:

       The following Mouse Message Area messages are observed by
       mx_dbfview(). 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_dbfview() 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_dbfview() via m_data(30):

                 -8   - no DBF file in use
                  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(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(31) is 15  and
                   m_data(29) is 1 and m_data(2) is 3, then the DBF
                   will be displayed starting at record #15 as the first
                   row in the window and the highlight will be on
                   the third row in the window. Upon exit from
                   mx_dbfview(), m_data(2) returns the row number
                   that the highlight was last on inside the window.

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

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

       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 view window at all.

       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(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(22)- on entry, if this is set to 1 mx_dbfview()
                   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_dbfview()
                   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_dbfview()
                   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_dbfview()
                   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_dbfview()
                   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 DBF is
                   displayed starting at the record # defined in
                   m_data(31) and the highlight is moved to the row
                   defined in m_data(2).

       m_data(31)- on entry/exit, if m_data(29) is set to one before
                   executing mx_dbfview(). the value here is used as
                   the first record # to display. If this value was
                   15 and m_data(29) was 1, the window would start
                   displaying at record # 15. On exit, m_data(31)
                   contains the record number that was last displayed
                   on the first row of the window.

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

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

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