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

  Name:     mx_view() - view a text file in a resizeable window
  Usage:    [<string>] = mx_view(<r1>,<c1>,<r2>,<c2>,<fname>,[<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

            string <fname> - the name of the file to display, or
            integer <fname> - the file handle to use. Assuming
            that you opened the file previously with fopen()
            If you specify a file handle, then lines of text
            are displayed starting at the current file pointer
            position unless the restart flag (m_data(29)) is set to 1 before
            running mx_view().

            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:  a null if error or the user ESCaped out. If the user presses
            return, the line of text that is highlighted is returned. If the
            user clicks the left button on a line of text in the window, then
            that line of text is returned. This value can be ignored, or can
            be used to select items out of a text file. A return code can
            be checked via m_data(30), see m_data(). Also note that if
            you declare your row/col variables to be public, and then use
            the @ sign if front of the variables when you pass them to
            mx_view(), the public variables will contain the new row/col
            coordinates if the user moves or resizes the window. This lets
            you keep track of where they moved it to very easily. You can
            also get the new locations of the window through MMA
            function m_data(24/25/26/27).

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

                 @ 10,0 say "Enter file to view: " get fname
                 read

                 mstring = mx_view(10,3,23,77,fname,23)
                 if (mstring <> "")
                      ? "Line picked: "+mstring
                 endif

            * or to always have the row/col coordinates even if they
            * move the view window:

                 public trow, tcol, brow, bcol
                 trow = 10
                 tcol = 3
                 brow = 23
                 bcol = 77

                 mx_view(@trow,@tcol,@brow,@bcol,"textfile",23)

            * using the @ sign lets mx_view() stuff the new row/col
            * coordinates into the variables you passed so that the new
            * coordinates can be used for the next time.

  Example2: This example sets the title to use, and sets the shadow type
            to 3, with a shadow color of 2

                 * setup the title
                 m_title("Use up/down arrow to scroll...")

                 * setup the shadow color to 2
                 m_data(17,2)

                 * setup the shadow type of 3
                 m_data(16,3)

                 * display the file
                 mx_view(10,10,20,70,"report.txt",23)

  Note:     Mx_view() contains full mouse support if a mouse is present,
            but a mouse is not necessary to use mx_view(). You can get
            rid of mouse support with the mouse() function. The
            following keys and functions are available in mx_view()

                 UP ARROW       - goto previous line
                 DOWN ARROW     - goto next line
                 PGUP           - goto previous page
                 PGDN           - goto next page
                 HOME           - goto beginning of file
                 END            - goto end of file
                 LEFT ARROW     - pan file left
                 RIGHT ARROW    - pan file right
                 ALT/S          - search for text in the file
                 ALT/A          - search for same text again
                 ESC            - exit
                 RETURN         - selects highlighted line
                                  of text and returns

            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_view()

            TO                  - ACTION
            goto previous line  - click on the up arrow
            goto next line      - click 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 beg. of file   - click left mouse button
                                  on the top edge of window
            goto end of file    - click left mouse button
                                  bottom edge of the
                                  window
            pan right           - click left mouse button
                                  on the right arrow
            pan left            - click left mouse button
                                  on the left arrow
            search for text     - click left button on the
                                  filename portion of the
                                  status line
            ESCape              - click left button on the
                                  triple bar in status line
            select line of text - move cursor onto the
                                  line of text 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 to new location.

  Mouse Messages:

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

                 -7   - file not found, the file specified by
                        the <fname> parameter was not found
                  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_view().
                 -1   - user pressed return, selection made.
                 -6   - the starting window coordinates were
                        beyond the range defined in the
                        m_data(8/9/10/11) coordinates. These
                        coordinates specify the maximum and
                        minimum row/col locations that the
                        window must stay within. In this case,
                        mx_view() exited prematurely without
                        displaying the file.

       m_data(2) - on exit/entry, this message contains the last active
                   row number that was highlighted inside the view
                   window. Or it is used to re-position the highlight on
                   entry to mx_view() when m_data(29) equals 1.

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

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

       m_data(16)- on entry, the shadow type to use for the view
                   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 message 22 is set to 1, mx_view()
                   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_view()
                   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_view()
                   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_view()
                   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_view()
                   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 file pointer
                   is moved to the offset specified in message area 31
                   and the highlight is moved to the row number that
                   is specified in message area 2.

       m_data(31)- on exit, The last file pointer position. On
                   entry, if the restart flag (m_data(29)) is set
                   to 1, the file pointer is moved to the location
                   specified here before the file is displayed.

       m_frame() - on entry, the frame characters to use for the view
                   window. mx_view() reads the characters returned
                   by m_frame() and uses them as the frame
                   characters for the view window. Set the frame
                   for mx_view() as follows: m_frame(<frame>)

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

            In addition, when the user is searching for text, the ESCape
            key aborts the search unless you specify otherwise with the
            _xkey() or _xkeyval() functions. To not let the user abort a text
            search, execute the function _xkey(.F.) before you execute
            mx_view(). If You want to change the abort key, execute the
            function _xkeyval(<key>) before you execute mx_view(). See
            the flocate() function for more details on the _xkey() and
            _xkeyval() functions. When the text is found, the highlight
            is placed on the line that contains the text. If you want to
            search for the next occurrence of the text, press ALT/A. If no
            text is found that matches, then a message is displayed. If the
            window width is less than the width of the control panel + the
            file name status area, then you will not be able to search for
            text.

            mx_view() also adheres to the newline character that is
            defined by the _newline() function. the default newline
            character is a chr(13)+chr(10) combination. This can be
            changed by the _newline() function to be any ascii character
            you like. See the _newline function for more details.

            mx_view() can be called recursively via SET KEY TO to
            display several files on the screen at once. However, only the
            most recent mx_view() can be active unless you modify the
            source code. The source code to mx_view() is in the file
            c_mx_view.prg on the source disk.

  Warning:  mx_view() checks to make sure that the window size you want
            to display is large enough to hold the control panel and at
            least one line of text. It is the programmers responsibility to
            make sure that the height of the window is at least 5 lines
            high, and the width is at least 11 characters wide. If the size of
            the window cannot display the control panel or at least one
            line of text from the file, then mx_view() will try to expand the
            window to hold the control panel. If it still can't display
            the text and the status line, it may exit prematurely with an
            error value in m_data(29).

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