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

  Name:     m_view() - view a text file in a window
  Usage:    [<string>] = m_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.

            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 if 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.

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

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

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

  Note:     M_view() contains full mouse support if a mouse is present
            but a mouse is not necessary to use m_view(). 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_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

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

            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 beg. of file   - click left mouse button
                                  on top edge of window
            goto end of file    - 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
            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

       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 m_view(). If you want to
       change the abort key, execute the function _xkeyval(<key>) before
       you execute m_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 stating not found.

       m_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.

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

  Mouse Messages:

       The following Mouse Message Area messages are observed by
       m_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 m_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 m_view()
                   via mouse message area 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.

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

       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(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_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(3) - on entry, if this is set to 1 m_view() will return if
                   the user clicks outside the file view window. set this
                   to 0 before you run view if you don't want the user
                   to be able to exit if they click outside the view
                   window

       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 m_view() when m_data(29) equals 1.

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

       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. m_view() uses
                   the text returned by m_title() as the title. Set the
                   title for use by m_view as follows: m_title(<title>)

  Warning:  m_view() attempts to make sure that your window
            coordinates are valid, and large enough to display the status
            line. If it is not, m_view() will expand the window until the
            status line fits. If it still can't fit the status line, the status line
            is truncated. Make sure that you account for the status line in
            your top and bottom row coordinates. The minimum window
            height is 5 lines - that will display 1 line of text from the file.
            The smaller the height of your window, the faster the file will
            scroll. A window of approx 12-13 lines high is optimal. Your
            window should also be wide enough to read several words in
            each line.

  Hint:     m_view() is a static window. If you want a window that moves
            you can use mx_view(). Note that these functions are full
            featured and therefore much larger than normal functions. If
            you wish to display static file view windows and moveable file
            view windows, you are better off using mx_view() and
            controlling it's movement with the m_data() messages rather
            than linking in both m_view() and mx_view().