I decided to adapt the window text editor from my books about Turbo C and QuickC. The code works properly, is mine and yours to use, and is reasonably small. It is modified here to use the more concise window functions from this column and to be extensible in that it is easy to add commands without modifying the source code of the editor itself. It also now has the potential for recursive calls to the editor. Although there are no immediate plans for a multiple-window editor or for one that can be called recursively, the editor should not preclude those features. Therefore, the code will allow an application to preserve the editor's current environment and reinvoke the editor for a different environment (window, buffer, and so forth).

To use the window text editor in a program, you must provide a window and a buffer with, perhaps, some text already in it. The buffer's size is a function of the width of the widest allowable text line and the maximum number of lines of text. You tell the editor these two dimensions when you execute it. The editor assumes that the window is wide enough to hold the lines and that the buffer is deep enough for a text file with the maximum number of lines. This approach, which uses trailing spaces to fill out each line, uses more buffer memory than one that uses newlines in the text, but the code for managing the cursor and blocks of text is less complex. The buffer is essentially an xy rectangle of y rows by x columns.

Because the fixed rectangular buffer must fit horizontally inside the window, the editor does not provide for horizontal scrolling. This means that lines cannot extend beyond the right margin of the window. It also means that a text file cannot have variable margins. These are features that we trade off to get an efficient editor within an application, and their loss does not compromise our requirements for a message composition tool.

The editor does not record or otherwise use the tab character (\ t) in a text buffer. When you type the Tab key the editor inserts the appropriate number of spaces to put the cursor at the next tab stop. Tab stops are specified as fixed intervals of character positions. The width of the interval can be configured when you compile the editor code.

The editor allows you to mark text blocks for move, copy, delete, and paragraph operations. These blocks are online boundaries rather than at character positions. This choice, too, was made in the interest of efficient code.

Customizing the window editor consists of changing some default values and providing your own command keys instead of the ones that are published. If you make such changes, when the menu shell and help windows are added later you will need to change the text that tells you what these commands are. For now, however, you only need to redefine the configured command values found in editor.h. The editor commands are single key stroke values that are delivered by the function getkey in window.c (September DDJ). The configurable commands have mnemonic global names such as END_LINE and DELETE_WORD. Change their values by defining different values for them. Note that this approach uses single keystrokes as editor commands. If you want to make this editor emulate the WordStar double stroke sequences like the Borland and QuickC editors do, you must write a getkey substitution that knows about them. There is a precedent for doing this--lots of people are comfortable with the WordStar command set--but the editor as published here does not support double stroke sequences.

Three other configuration items are found in editor.h. These are the width of the tab stops, whether the editor comes up in insert or overwrite mode, and whether the editor comes up with automatic paragraph reforming enabled.

To change the editor's window colors, change the TEXTFG, TEXTBG, BLOCKFG, and BLOCKBG global values in window.h from the September "C Programming" column. Text colors are the normal colors for the text editor window and should be specified as the window's colors when you establish the window that the editor will use. Block colors are set by the editor when a block is marked. The editor resets the window to the text colors for nonblocked displays. Color configuration was discussed in September.

Of course, one other level of customization is available to you. You have the source code to this editor, and you can make it do anything you want within the limits of your abilities with the C language.

No one will use this editor to replace Word, WordPerfect, XyWrite, or WordStar; nor will you toss out Brief, vi, Vedit, EMACS, or the Norton Editor. Nonetheless, the editor needs a sufficient set of word processing features to make it useable for entering messages. From my experience with word processors and on-line services comes a set of features that I believe to be the minimum, and these are built into the editor. Realizing, however, that the need for more features will no doubt come later, I wrote the code so that extensions--those new, undiscovered features--could be easily tacked on. More about that later; first the minimum features.

Text Entry--You can type words into the buffer. Word wrap occurs when the word being typed reaches the right margin or when an inserted character pushes the rightmost word to the margin. When you type, the insert or overstrike mode is effective. Paragraphs can be automatically reformatted as you type or not as determined by a programmed toggle.

Cursor Movement-You can move the cursor around by characters words pages, tabs, to the right or left of the line, to the top or bottom of the window, or to the beginning or end of the text. If you type the Enter key, the cursor moves to the next line, first column. If this is done in insert mode, the line is split.

Editing--You can delete characters (left or right), words, lines, or blocks. You can mark a block of lines and then move, copy, delete, or form a paragraph from the block. You can unmark a marked block.

Paragraphs--A paragraph begins with an indented line. The indent is the number of spaces in the tab interval. Automatic paragraph reforming occurs from the cursor position up to the next paragraph or blank line. The paragraph command does likewise when no block has been marked.

These are the basic text editing features of a buffer of text that is edited through a window by our text editor. The file management aspects of the editor project come next month when we see how to read and write text files into and from the buffer. We will also add the text searching algorithms and a menu shell. Nothing about this program pushes the technology. We have added a tool to our collection, one that will enable free-format text to be entered and changed in a window by the users of our programs.

Most of the code in editor.c explains itself about as well as C code can explain itself without extensive comments. At least I think so. It works for me and I hope it does for you too. My commenting practices follow a convention that identifies the purpose of each function in a comment at the beginning of the function. Variables that are not obvious get comments that describe their purpose. Where code gets downright abstruse, I will insert comments as it goes along, but mostly I prefer to let the code describe itself. This habit and preference comes from years of reading the code of others where their extensive and verbose comments predate the code by generations of modifications. I have been lulled into believing beautifully crafted comments and have thus been subliminally conditioned to assume things that are not true. This loses time. Later, when my confusion reaches an intolerable level, I resort to reading the code, only to find that it disagrees with the comments. No matter whether the comments are statements of intent never realized or accurate descriptions of code no longer in place; the comments say one thing and the code does another.

As a matter of conviction and to preserve the remnants of my sanity, I now refuse to read comments that are written as pseudocode unless I am sure the program has never been modified. Even then I am reluctant. Those comments are rarely (if ever) maintained as the code is being developed or later when it is changed. Perhaps your experiences are different; perhaps the rigidly enforced standards and procedures of your employer keep this crotchet out of your shop; and perhaps you believe that. I do not.

C language code is not always its own best documentation. It is, however, the most reliable statement of what is going on in the program. My practice serves me well because I tend to remember what those cryptic variable names mean, and I prefer small functions with simple purposes. If the function works, its purpose is understood, and it is small, then it can be thought of as a black box, can be read, and can be trusted. Not that I always practice what I preach; text_editor is a big function, although it is mostly a lot of small cases to a key stroke switch.

By the way--I don't much care to read code that has been commented out either. A faraway, out-of-sight #if DEBUG statement or an as yet unterminated /* start-of-comment token can have you reading reams of code that does not exist.

On the other hand, my pal Bill Chaney says that anyone who fails to provide ample comments in an assembly language program should be required for penance to spend a year maintaining COBOL/CICS screen driver programs for the Puerto Rican income tax system.