%------------------------------------------------------------------------

\Class{vTextEditor}
\Indextt{vTextEditor}\index{Text Editor}

A complete text editing canvas pane.

\subsection* {Synopsis}

\begin{description}
	\item [Header:] \code{<v/vtexted.h>}
	\item [Class name:] vTextEditor
 	\item [Hierarchy:] vCanvasPane \rta vTextCanvasPane \rta vTextEditor
\end{description}

\subsection* {Description}

This class is a completely functional line oriented text editor.
It can edit any file with lines less than 300 characters wide that
use a linefeed, carriage return, or combination of those to mark
the end of each line.

While you need to create your own class derived from \code{vTextEditor},
your class can be very minimal, often only needing to provide some
service methods for the parent \code{vCmdWindow}, such as a method
to open, read, save, and close a file. Other than actually working
with the real text source and providing that source to \code{vTextEditor},
you can get a fully functional text editor with no additional work.

However, \code{vTextEditor} has been designed to allow you to extend
and add functionality to the editor if you need to. The \code{vTextEditor}
also sends messages that will allow you to place various status
messages on a status bar if you wish. The hard stuff is done for you.
You don't need to worry about mouse movements, scroll bars or scroll
messages, updating the screen, handling keystrokes, or anything else
associated with actual editing. The \code{vTextEditor} class takes
care of all those details, and provides a standard editing interface.

The following steps are required to use \code{vTextEditor}. First,
you create an instance of your derived class from your \code{vCmdWindow}
class, something like this:

\footnotesize
\begin{verbatim}
   ...

   // The Text Editor Canvas
    vedCanvas = new vedTextEditor(this);
    AddPane(vedCanvas);
   ...

   // Show Window

    ShowWindow();
    vedCanvas->ShowVScroll(1);  // Show Vert Scroll for vTextEditor

    ...
\end{verbatim}
\normalfont\normalsize

Your derived \code{vTextEditor} class should provide the methods
needed for opening and reading the text file you want to edit.
(Actually, you can edit any text source you wish.) \code{VTextEditor}
doesn't actually read or write any text itself. It maintains an
internal line buffer. (The default version of the internal buffer
is essentially limited by the amount of memory your system can
provide. The buffer methods can be overridden to provide totally
unlimited file size, if you wish.) The idea is to have your
application control where the text comes from, and then
add it a line at a time to the \code{vTextEditor} buffer.
You retrieve the text a line at a time when you want to save
the edited text. Thus, your if your code is working with
disk files, it can read the text a line at a time, and let
\code{vTextEditor} worry about the buffering.

The following code shows how to add the contents of a text file
to the \code{vTextEditor} buffer, and display it in the canvas
for the first time. Calls to \code{vTextEditor} methods are
marked with **.

\footnotesize
\begin{verbatim}
//===================>>> vedTextEditor::ReadFile <<<====================
  int vedTextEditor::ReadFile(char* name)
  {
    const int maxBuff = 300;    // Line length
    char buff[maxBuff];

    if (!name || !*name)
        return 0;
    ifstream inFile(name);      // Open the file

    if (!inFile)
        return 0;               // file not there

    resetBuff();                // ** Tell vTextEditor to init buffer

    while (inFile.getline(buff,maxBuff))  // read file
      {
        if (!addLine(buff))     // ** Add the line to the buffer
          {
            ERROR_MESSAGE("File too big -- only paritally read.");
            break;
          }
      }
    inFile.close();             // Close the file
    displayBuff();              // ** Now, display the buffer
    return 1;
  }
\end{verbatim}
\normalfont\normalsize

Essentially, you first call \code{resetBuff} to initialize the
buffer, then add a line at a time with calls to \code{addLine},
and finally display the text by calling \code{displayBuff}.

When your are editing (e.g., the user enters a Close command),
you retrieve the text from the \code{vTextEditor} buffer
with calls to \code{getLine}.

Then, to use the editor, you pass keystrokes from the
\code{KeyIn} method of your \code{vCmdWindow} to the \code{EditKeyIn}
method of the \code{vTextEditor}. \code{EditKeyIn} interprets
the conventional meanings of the arrow keys, etc., and lets
you edit the text in the buffer. You will also probably implement
other commands, such as Find, by using the \code{EditCommand}
method.

\code{VTextEditor} also calls several methods to notify of
text state changes, such as current line, insert or overtype,
etc. You can receive these messages by overriding the default
methods, and display appropriate information on a status bar.

\subsection* {Constructor} %------------------------------------

\Meth{vTextEditor(vBaseWindow* parent)}
\Indextt{vTextEditor()}

The \code{vTextEditor} constructor requires that you specify
the parent \code{vCmdWindow}. Since you usually create the text editor object
in your \code{vCmdWindow} object, this is easy. You will probably need
to cast the \code{this} to a \code{vBaseWindow*}.

\subsection* {Utility Methods} %------------------------

\Meth{resetBuff()}
\Indextt{resetBuff}

Before you load new text into the buffer, you must first
call this method. It initializes the internal state of
the text buffer.

\Meth{virtual int addLine(char* line)}
\Indextt{addLine}

This method is called repeatedly to add lines to the
text buffer. The default method is limited by the amount
of memory avaiable on the system, and this method
return 0 when it runs out of memory.

Note that the entire text buffer package can be overridden
if you need to provide unlimited file size handling. You
should examine the source code for \code{vTextEditor} to
determine the specifications of the methods you'd need
to override.

\Meth{virtual void displayBuff()}
\Indextt{displayBuff}

After you have added the complete file, call \code{displayBuff}
to display the text in the window.

\Meth{virtual int getLine(char* line, int maxChars, long
lineNum)}
\Meth{virtual int getFirstLine(char* line, int maxChars)}
\Indextt{getFirstLine}
\Meth{virtual int getNextLine(char* line, int maxChars)}
\Indextt{getNextLine}

These are used to retrieve the edited text from the buffer.
You can use \code{getFirstLine} with \code{getNextLine} for
easy sequential retrieval, or \code{getLine} for specific
lines. These methods return -1 when all lines have been
recovered.

\Meth{virtual int EditCommand(int id, long val)}
\Indextt{EditCommand}

\Meth{virtual int EditKeyIn(vKey key, unsigned int shift)}
\Indextt{EditKeyIn}

\subsection* {Methods to Override} %------------------------


\subsection* {See Also} %---------------------------------------

vTextCanvasPane