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

  Name:     m_dbfview() - display DBF fields in a pick window
  Usage:    <integer> = m_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.

                 * 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)"

                 * open the DBF and index
                 USE NAMES index LNAME

                 * seek to the first "L" to start displaying L's
                 seek "L"

                 * display the DBF window
                 choice = m_dbfview(10,10,20,70,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.

  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")

                 * load the shadow type to lower right
                 m_data(16,3)

                 * load the shadow color (3 for cyan)
                 m_data(17,3)

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

  Example3: This next example causes m_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 = m_dbfview(10,10,20,70,titles,fields,23)

  Note:     M_dbfview() contains full mouse support if a mouse is
            present, but a mouse is not necessary to use m_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 m_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 number.
                 ALPHA KEYS     - causes m_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          - causes the dbfview
                                  window to be refreshed.
                                  Use this to redraw the
                                  window if you change the
                                  index order in a set key
                                  routine. Popout to the
                                  set key to procedure,
                                  change the index order,
                                  and use nstuff() to stuff
                                  an inkey() value of 275
                                  (ALT/R) to force a
                                  refresh of the window.

            If a mouse is present, the following mouse options are
            supported in m_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.

       Pressing an alphanumeric key causes m_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
       m_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 m_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
                   m_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_dbfview().
                   -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
                   m_dbfview(), 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_dbfview() will return
                   if the user clicks outside the m_dbfview() window.

       m_data(4) - on exit, this value returns 1 of the user clicked
                   outside the m_dbfview() 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(22)- on entry, if this is set to 1, m_dbfview()
                   automatically restores the screen upon exit.

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

  Warning:  m_dbfview() attempts to make sure that your window
            coordinates are valid, and large enough to display the control
            panel. If it is not, m_dbfview() will expand the window until
            the control panel fits. The minimum window height is 5 lines -
            the minimum window width is 26 columns.

  Hint:     m_dbfview() is a static window. If you want a window that
            moves you can use mx_dbfview(). If you wish to display static
            m_dbfview() windows and moveable mx_dbfview() windows,
            you are better off using mx_dbfview() and controlling it's
            movement with the m_data() messages rather than linking in
            both m_dbfview() and mx_dbfview(). The Clipper source
            code is on the source disk in the file c_m_dbfv.prg.