Copyright: Copyright Premia Corp. 1994.  All rights reserved.


Table of Contents

Basic Concepts

The Menu Bar

The Tool Ribbon and Tool Box

API Library

Key Commands

Using Codewright


Using Codewright

Auto-indent

Brace Matching

Browser

Tags Support

Color Guide

Editing Modes

Mouse Commands

Regular Expressions

SideBar

Template Macros

Tool Ribbon and Tool Box

Version Control Setup

Word Wrap


Basic Concepts

Current

Buffer

Bookmarks

Projects

Saved Positions

Selections

Scrap

Keymaps

Windows

Workspaces


Current

When something is said to be current, it is the focal point of attention.  For example, you perform edits in the current buffer, at the current cursor position, in the current window.  Current usually implies that there could be more than one of something and that the focal point can therefore change.


Buffer

A buffer is a temporary storage area.  Buffers are closely related to files, and most buffers are representations of files in memory.  The terms file and buffer are therefore sometimes used interchangeably.  Buffers are sometimes used by Codewright for Undo/Redo data or for transferring information in much the same way as the Windows Clipboard is used.

Buffers can operate independently from windows.  Windows are used to see into buffers.  More than one window may be assigned to a single buffer and a window may be used to view several different buffers consecutively.  There is an option, however, that limits one buffer to a window and opens a new window for each buffer.  With this option selected, buffers and windows act as a unit.  This option is on the System Options dialog.


Bookmarks

There are several kinds of marks that Codewright uses, and all of them are used to record buffer line and column positions.  The primary types of marks are bookmarks, saved positions, and selections.

You use bookmarks to facilitate movement from one position to another, within and between buffers.  There are both local and global bookmarks.  Local bookmarks are known only within the buffer in which they were defined.  Global bookmarks, on the other hand, are recognized from any buffer.


Saved Positions

Saved positions are essentially bookmarks that are kept in a last-in/first-out (LIFO) stack.  The most recently saved position is on the top, ready to be used.  When it is, the next most recently saved position becomes available for use.


Selections

Selections are marked blocks or regions of text.  These, too, are kept in a LIFO stack.  The most recent selection, or current selection, is seen as a highlighted block of text.  As one selection is used and disposed of, the previous selection, if any, becomes highlighted.

A selection is defined by two marks.  When the beginning mark has been placed, the selection is defined by that mark and the cursor position.  If the ending mark is also placed, the selection is said to be "closed".  It is no longer tied to the cursor position.  A closed selection may also be reopened, at which time the end of the selection moves to the cursor position.  We believe Codewright to be unique among programmer's editors in its ability to define multiple, closeable selections.  Command sets designed to emulate other editors therefore will usually not exploit this feature.

In addition to having a beginning and an end, a selection also has a top and bottom.  The top is always whichever end is closer to the top of the buffer, and the bottom of the selection is always the end closer to the bottom of the buffer.  However, the top is not always the beginning and the bottom is not always the end of the selection.  This is because you can begin marking a selection at the bottom of the text you wish to mark, and end marking it at the top.


Scrap

The Scrap buffer is one of the buffers Codewright uses for transferring information.  It is used as the staging area for local cut and paste operations within or between edit buffers much as the Windows Clipboard is used for cut and paste operations between applications.  Codewright's scrap buffer, however, knows the difference between text that was copied from a column selection and text copied from a line or stream selection.  It is therefore more suited for use within Codewright than the Windows Clipboard.

Codewright also supports the Windows Clipboard for transferring data between programs.  However, we cannot recommend the Clipboard for use within the Codewright's local operations because it lacks the versatility required by a programmer's editor.  Support for the Clipboard is provided primarily for transferring data between Codewright and another application.  You can select which staging area you will use from the Edit menu.


Keymaps

The action of each key, except those defined by Microsoft Windows, is the result of a function being assigned to a key.  These assignments are stored in a keymap.  You may have more than one set of key assignments for different purposes.  Hence, you may have more than one keymap.  For example, you might have one keymap for editing and another for drawing lines.


Windows

A window, in Codewright terminology, is a rectangular viewing area.  Windows are used to view the contents of buffers.  When windows are mentioned here, this is usually a reference to buffer viewing areas, rather than the Microsoft Windows operating environment.  When referring to Microsoft Windows, the word Windows will always be capitalized to distinguish the reference from edit windows.


Projects

A project, at a minimum, is a list of files that you find it useful to group together logically.  Creating a project facilitates operating on these file as a group, whether you are using version control, creating a "Tags" database, or even if you are just loading files.  The files within the project may be further divided into Workspaces, which may contain project and non-project files.

A project may also store the options you have selected.  If you wish, your project files may contain as much information as your Codewright configuration file.


Workspaces

You can think of each workspace almost as a separate instance of Codewright.  That is, when you change workspaces you have the ability to pick up where you left off with a group of files.  It doesn't matter if you worked on that group of files a half hour before or three months ago.  It is as if an instance of Codewright were frozen in time containing these files.

A workspace differs from a project in that it does not store the system-wide options normally stored in a configuration file.  Only the more transient options and settings are saved as part of the workspace.  In a sense, the workspace is like a state file that you can swap on the fly.  As such, it retains information about the currently open windows and buffers.  Other state information such as search options, response histories, bookmarks and so on are stored as part of the project.


Menu Bar

File Menu

Edit Menu

Search Menu

Project Menu

Buffer Menu

Window Menu

Key Menu

Utility Menu

Options Menu

Help Menu


File Menu

New...	Create a new file to edit.  Prompts for name

Open...	Open a file for editing or viewing.

Close	Close the file and delete the buffer.

Save	Save the changed file.

Save As...	Save the buffer in a different file.

Save All	Save all modified buffers.

Reload	Reload the original file into the buffer.

Filters...	View/change file filters.

Change Dir...	Change the current directory.

Difference...	Compute the difference between files/buffers.

Merge...	Merge two sets of changes made to a file.

Print...	Print buffer contents or highlighted selection.

Print Setup...	Select or configure a printer.

Exit...	Terminate the editing session.


File New Dialog

The File New dialog box creates a new file when you give it a filename specification.  Use the Browse button to locate a desired directory and to see what filenames are already in use.

If the file already exists, or if you already have a buffer by that name, you are notified of the error and no new file is created.

•	Create window  You also have the option to open a new window for the new file.  If you don't check the box, the new file is assigned to an existing window, the current window.  If there are no windows open, one will be created regardless of whether or not you checked the box.


File Open Dialog

The File Open dialog box allows you to select one or more files that you wish to edit.  You can select files matching a wildcard pattern, select files individually, in ranges, or select the files that you don't want to open and open the rest.

File Name

When you type a filename into the File Name box, you can load it by pressing either the OK or Open buttons.  If you type in a wildcard pattern, pressing OK will show the files that match that pattern in the File Name list box.  If, instead, you want to load all of the files matching that pattern, press the Open button.

You might begin by entering a wildcard pattern in the File Name box -- *.c, for example.  You could then open all of the files matching that pattern by pressing the Open button.

File Name List Box

You could, instead, press [Enter] or select the OK button.  This would display a list of files matching the wildcard pattern, rather than opening the files.  Then, you could select from among the files listed in the same manner you would select files in the Windows File Manager:  click on a file to select just that file; Ctrl-click to add a file to those already selected; Shift-click to select all files between and including the file previously selected through the one on which you click.

Invert Button

If you wanted to open all of the files except the first, third and fifth, you would click and Ctrl-click on those filenames, just as you would if you wanted to open those files, and then select the Invert button.  As a result, the files you previously selected would become unselected and visa versa.

Directories

The Directories box shows the directory structure as a series of folders, the current one in an open position.  You may use this directory tree to change directories and browse their contents.  Just point and click on the desired directory and the files matching the pattern in the File Name box are displayed.

Drives

The directories box does not allow you to change drives.  A separate Drives box is supplied for this purpose.  All valid drives and their volume labels, if any, are listed in the Drives box.

List Files of Type

The List Files of Type box contains a list of predefined extensions or groups of extensions that may be selected for display in the File Name box.  You may make additions to this list through the File Filters dialog.

Check Boxes

There are three check boxes in the File Open dialog box.  They are the Read-Only, New Window and Keep Dir check boxes.

•	Read-Only  This check box allows you to make the file or files you load uneditable.  This can prove useful when you want to remind yourself not to edit a file, perhaps for reasons of version control.

•	New Window  This check box allows you to specify whether a window is created for each file that you select.  This box receives its initial value from the  "One buffer per window" option found on the System Options dialog.

When the box is not checked, a single window is created, if none already exists.  Otherwise, no new windows are created.  The first file opened is then displayed in the current window.  Any other files opened are placed in buffers, but no window is created or attached to those buffers.  They may be viewed by issuing the next buffer command ([Alt][N] for BRIEF [Ctrl][N]  for CUA).

When the box is checked, and you are loading multiple files, the number of windows opened depends on whether you are opening them by specifying a wildcard pattern or whether you are selecting them in the list box.  When selected in the list box, a window is opened for each buffer.  When selected with a wildcard pattern, one window is opened for that group of files, and the first is displayed.

To open a window for each file in a wildcard pattern, specify the pattern, display the matching files (press [Enter] ), click on the Invert button to select them all, and then press the OK button.

•	Change Dir  This check box allows you to pick up where you left off the next time you use the File Open dialog.  It will remember the last directory you looked at and display the same files next time.  If you are wandering off of the main directory in which your files for the current project are stored, this may not be desirable.


File Save As Dialog

The Save As dialog is the same as the File Open dialog, except that it only lets you operate on a single file -- the current buffer.  You can list files, but they are all grayed-out.  They sometimes serve as a useful reminder of what files are already on disk.  The grayed-out names can also save you some typing.  If you click on a name, that name will appear in the File Name box for modification or overwriting.

In adition to having the usual "Change Dir" check box, this dialog has two additional check boxes described here:

•	Keep old file  When this box is checked, the buffer will be written to the selected  filename but the buffer continues with its old name.  When this box is not checked, saving the file under a different name will have the effect of changing the buffer's name.

•	Create dir  This box may be useful if you type in the name of the file, including some or all of its path.  When this box is checked, Codewright will not complain if you specify a path that does not currently exist.  It will just create the path as necessary.  The results may be undesireable if you make any typos in entering the path, however.  When this box is not checked, the path to the file must exist or Codewright will give you an error message.

When an explicit filename is displayed in the File Name box, you may press [Enter] or select OK to save the current buffer under that name.


File Filters Dialog

The Filters dialog allows you to define wildcard patterns for use in dialog boxes where the "List Files of Type" box appears.  These dialogs include the File Open, File Save As, and other dialogs with browsing capabilities.

Adding Filters

You can add filters to the list by typing in a new description and pattern, and then selecting the Add button.  The filter is added to the list at the position of the highlight.

By convention, the description contains the wildcard pattern within parentheses, but this is not required, since the description is for reference purposes only. The pattern is any DOS wildcard pattern or patterns that match the files you indicate by the description.  If you include more than one wildcard pattern in the Pattern, separate the specifications with semicolons.

Removing Filters

You remove filters from the list simply by highlighting the unwanted filter and selecting the Remove button.

Rearranging the List

You can rearrange the entries in this list by removing and re-adding entries.  The first step is to highlight and select the entry you want to move.  You can do this by double clicking on the entry.  The entry then appears in the Description and Pattern edit boxes.  Next, press Remove.  Though the pattern and description are deleted from the list they remain in the edit boxes.  Now, relocate the highlight to the position where you want to insert the filter and press the Add button.  The filter has been moved within the list.  Repeat this process as necessary until the list is arranged as you desire.

Saving Changes

The changes you make do not take effect until you select the OK button.  If you wish to abandon the changes you have made, select Cancel instead of OK.


Change Dir Dialog

The Change Directory Dialog looks and works like the Directory portion of the File Open dialog.  It allows you to set a new working directory for Codewright.  If you have elected not to check the Keep Dir check box in the File Open dialog, you may occasionally wish to change directories using this mechanism.


Differencing
File Differencing

The Difference Dialog helps you discover the differences between two similar files or buffers.  You can compare an unsaved buffer to the version of file on disk, or you can compare the changes you made to a file to those made by a another person.  You view the differences side by side.

Codewright  does a line by line analysis of a reference file or buffer and a target file or buffer.  It then places the result in special side-by-side windows to facilitate comparison.  The windows share a common scroll bar that allows you to scroll both windows at once.

Lines that are the same in both files will have normal coloring in the new buffer, but each line will be prefixed by a single space.  Lines that have been added to the target will be prefixed by plus sign ( + ), and lines that have been deleted from the target will be prefixed by a minus sign ( - ).  Lines which have moved (not just been shifted by other additions and deletions) are shown as deleted at their original location and added at their new destination.  In addition to being visual cues, these line prefixes form a basis for searching for differences.  Just press the next and previous difference buttons to move sequentially through the differences detected.

Each of these three types of lines, added, deleted and common, is displayed using a different foreground/background color combination.  This makes it easier to see where groups of lines have been added or deleted.  You may control the colors given to these lines by accessing the Colors dialog on the Window menu.

Reference File

This is the file or buffer that serves as the basis for comparison.  Usually it is the older of the two being compared.  If you are comparing the current buffer to the same file on disk, just click on the Original File button and its name will be inserted into this field.

Target File

This is the file or buffer to which the Reference is compared.  It is usually the newer of the two being compared.  If you want to compare the current buffer to the Reference File, simply press the Current Buffer button and Codewright  inserts the filename into this field.

File/Buffer Buttons

These radio buttons allow you to tell Codewright  if the name you entered is a file or is already loaded as a buffer.

Browse

Selecting the Browse button allows you to select a file or buffer from a dialog box rather than typing in the name.  Setting the File/Buffer buttons before selecting Browse determines whether you will be presented with a list of buffers or permitted to select a file on disk.

Output Mode

The output mode group allows you to select what way you wish to review the results of the differencing operation.

•	Side-By-Side Comparison  View the comparison in side-by-side windows that share a common scroll bar in the center.  This facilitates synchronized scrolling of the two files.  The window also has two edit buttons that allow you to call up either of the compared files for editing.

•	Interleaved Output  The output is co-mingled in one buffer.

•	Compressed View  When you select Interleaved output, you can also select whether to see just the differences or the text common to both, too.  Viewing just the differences requires that you select the compressed output option.  This option utilizes Codewright's Selective Display mode.  You can therefore open and close sections containing the common text and view the entire buffer uncompressed just by pressing [Esc].


File Merge Dialog

The File Merge Dialog allows you to specify three files for comparison, and the name of the file that is to contain the merged changes.

Base File

The first filename you must enter is the name of the Base File.  This is the file from which the two revisions were derived.  Usually this is the oldest of the three files.  You may type in the name of the file, or select the Browse button to locate the desired file on disk or select from the buffer list.  You may place the name of the file, from which the current buffer was read, into this field by pressing the Original File button.  The File and Buffer radio buttons allow you to specify whether Codewright should look for this file on disk, or whether it has already been loaded into a buffer.

Revision 1 and Revision 2

These files are both revisions of the of the Base File.  It does not matter which revision you specify as Revision 1 and which you specify as Revision 2; the outcome of the merge is not materially affected.  You may, however, wish to establish a convention for your own use that Revision 1 is "mine" and revision 2 is "theirs", or that Revision 1 is older than Revision 2.

In each case, you may choose to type in the name of the file or select the browse button to locate the desired file on disk or select from the buffer list.  You may elect to use the current buffer for one of these revisions by selecting the Current Buffer button in the appropriate group.  The File and Buffer radio buttons allow you to specify whether Codewright should look for these files on disk, or whether they have already been loaded into a buffer.

Output File

In this box, you specify the name of the file to contain the output from the Merge.  You may type in the name of the file or select the Browse button to locate a file on disk.  This merge file is always written to disk, rather than just being placed into a buffer as the Differencing function does.

In addition, this group allows you to set two other options.  There are check boxes that indicate whether Codewright should overwrite a like-named file when creating the output file, and whether the output file should be loaded for viewing and editing at the end of the operation.

If you do not check the Overwrite File option, and a like-named file exists, Codewright will prompt you for permission to overwrite the file.  If you don't give this permission, Codewright aborts the merge.

Removing Changes with Merge

Merge Output


Removing Changes with Merge

Merge can also be useful when your development has been a linear progression, rather than simultaneous revisions (branching).  For example, you may find that a bug was introduced at some point in the past, and want to undo those changes without abandoning the changes that you have made since.  You could of course do this manually, but Merge is faster and easier.

Usually, the Base File is the oldest of the three files used in the Merge comparison.  It need not be the oldest, however.  For the purposes of removing changes, the Base File is a revision in the middle that looks backward at the changes that must be removed and looks forward to the changes that must be retained.

When selecting the Base File, select the first revision following the changes you want to remove.  Next select the most recent revision of your file as Revision One.  For Revision Two, choose the revision just before the change you want to remove was introduced.

This may at once appear to be magic, but it is not.  Compared to the Base File, the Merge function will see one set of changes that removes the bug, and another that adds other changes.  Since the Base File and the Revision One file both contain the bug, the un-bugged revision will look like a change made to a single revision.  As such, the bug fix will quite likely be automatically incorporated into the resulting file.


Merge Output

The Merge function will alert you if it found any conflicts in the two sets of changes it is merging.  If no conflicts were reported, editing the file is probably not necessary.  Chances are, you will want to look it over in any case.  When you do have one or more conflicts, you will need to know how to find them so that you can resolve the conflict.

Merge uses a series of ten dashes to separate the conflict area from the rest of the file.  This enables you to look for conflicts in your file using the regular expression "^----------".  This pattern will match ten dashes at the beginning of a line.  Each line containing a message from the Merge function will begin in this manner.  You will need to delete these lines after resolving the conflict.

The first message from Merge identifies the conflict by number, names the Base File, and indicates that the Base File was read from disk (file).  The next message introduces the section of the Revision 1 file that conflicts with Revision 2.  It also gives the filename and indicates the origin of the file (File or Buffer).  The line or lines between this message and the next message from Merge are taken from the Revision 1 file.

After the lines from Revision 1 there is a message from the Merge function introducing the corresponding section from Revision 2.  Again Merge indicates the filename and origin.  Between this message and the "End Conflict" message are the lines that you need to compare with those from the Revision 1 file to see how to resolve the conflict.

On occasion, you may find that the section of conflicting line from one revision or the other contains zero lines.  This is an indication that the lines were deleted in one revision and changed in the other.  The revision from which the lines were deleted will be represented by an empty conflict section.

Once you have resolved the conflict and deleted the message lines you are ready to search for any further conflicts.


The Print Dialog
Print Dialog

The Print Dialog lets you define the appearance of a buffer or buffers to the printer, and then submit the job for printing.

Title Format

The Title Format group provides a key to the title format controls available.  You use these macro-like keywords to refer to, in a generalized way, the page number (%p), current date (%d), current time (%t), and name of the file you are printing (%f).  Place these keywords at the location within the header or footer string where you want the corresponding information to appear.

Header/Footer

The header and footer groups permit you to define header and footer text for each page that you print.  You may elect to place a portion of your header or footer at the left, right and center of the page.  The semicolon character is used to separate these three portions of the header or footer.  The first portion is left-justified, the portion following the first semicolon is centered, and the portion following the second semicolon is right-justified.  See the format diagram below:

<left-justified portion>;<centered portion>;<right-justified portion>

Any portion of this format may be empty.  Thus, if you wish to left-justify the filename but right justify the date, your format would look like this:

%f;;%d

To center the page number, your format would look like this:

;%p

Margins

The Margins group allows you to set the distance from the text to the edge of the page in each direction.  The distance is measured in inches.

ChromaCoding Rendering

The ChromaCoding group allows you to control how your ChromaCoded text will be rendered on the printer.  You can select one of the attribute fonts, and whatever ChromaCoding you have enabled (either Language Dependent or Changed Lines) will be printed using that font attribute.  If you choose to check the Reverse attributes box, the ChromaCoded text will be given the "normal" attributes while the normal text will receive the attributes you select here.

Two Up

This check box enables printing two pages at a time, side by side.  When printing this way, best results are obtained if you also select Landscape mode.  You may also wish to  select a smaller font than you normally use.

Selection Only

When this box is checked, printing is limited to the selected portion of the buffer.  If you have not defined a selection, this option will be unavailable.

Framed Border

When this box is checked, a box at the margins of the page is drawn.  When Two Up is selected, two boxes are drawn; one around each page.

Line Number Increment

By default, Codewright  prints the sequence number of the lines being printed at the beginning of every fifth line.  You may set this to any interval you like.  A setting of zero disables the printing of line numbers.

Header/Footer at Margins

When this box is checked, the printable area is diminished in order to place the header and footer within the specified margins.  It is useful on some printers and with some printer drivers that are overly optimistic about the printable area of the page.  This can result in headers and footers that are partially or completely truncated.  Selecting this checkbox fixes that problem.

Save Settings Button

Pressing the Save Settings button updates your configuration file with the print settings currently defined in the dialog.  Print options are not automatically saved between sessions.

Font Selection Button

Pressing the Font button brings up the Printer Font dialog box.  This dialog is the same as the one provided for setting the font for a window, except that it is only used for printing.  Variable pitched fonts as well as monospaced fonts are therefore permitted.

Buffers Button

The Buffers button allows you to select which of the currently loaded buffers to print.  By default, Codewright  prints only the current buffer.  Pressing this button displays the names of the loaded buffers in an extended list box.  An individual buffer may be selected (click), a range of buffers may be selected (Shift-click), or a series of individual buffers may be selected (Ctrl-click).  For additional information on extended list boxes, see Extended Selection Listboxes


Print Setup Dialog

This is the standard Windows dialog for setting up your printer.  It has provisions for using the default printer or selecting a special printer.  You can also select the paper source and image orientation.


The Exit Dialog
Exit Dialog

This dialog appears when you select Exit from the File menu without saving all changed buffers to their output files.  The buffers containing changes that have not been saved are listed for you.

This dialog also appears when you

•	double click on the Visual C++ System menu,

•	select Exit from the File menu,

•	press [Alt][F4].

It does not appear if Visual C++ mode is active, or when the exit commands specific to the BRIEF emulation are used.

Save None, Save All

If it was your intent not to save these changes, just select the Save None button.  To save all of the changes, simply press the Save All button.

Save Selected

To save one buffer, while abandoning the changes in others, select that buffer name from the list.  Press [Ctrl] and click on the names of any other buffers you wish to save.  When you have selected all of the buffers you wish to save, press the Save Selected button.

Invert

If you have many buffers you wish to save and just one or two you want to abandon,  you may find the Invert button to be useful.  Select the file or files in the manner just described that you don't wish to save.  Pressing the Invert button will make those files the only ones not selected.  You may then proceed to save all of the other modified buffers by pressing Save Selected.

Cancel

The Cancel button will return you to your Codewright  editing session, thereby aborting the requested Exit.


Edit Menu

Undo	Undo changes made.

Redo	Redo 'undone' changes.

Clipboard	Select the clipboard for cut/paste, when checked.

Scrap	Select the scrap buffer for cut/paste, when checked.

Cut	Cut out selected text to clipboard/scrap.

Copy	Copy the selected text to clipboard/scrap.

Append	Append selected text to clipboard/scrap.

Paste	Insert clipboard/scrap contents in buffer.

Erase	Clear clipboard/scrap.

Word wrap	Enable/disable automatic word wrapping.

Block Processing	Block Selection Operations

Spell Check...	Check spelling of current buffer

Insert File...	Insert a file into the buffer.

Insert Literal...	Insert arbitrary character codes.

Options...	Set clipboard/scrap options.


Block Processing

There are a number of operations available in Codewright that are intended to work on a limited portion of an edit buffer.  This may be a block of code, a comment or a column in a table.  Normally, you describe this block to Codewright by enclosing it in a selection.  Often a column block is the most effective type of selection.  It adds to your control by telling Codewright more specifically the extents of the text.

Upper

Lower

Slide-in

Slide-out

Prompted Slide-in

Prompted Slide-out

Selection Justify

Enumerate

Column Formatting

Comment Boxes


Upper

The Upper item converts the text in the selection to upper case.  If there is no selection, the current line is converted to upper case.


Lower

The Lower item converts the text in the selection to lower case.  If there is no selection, the current line is converted to lower case.


Slide in

The Slide-in item indents the selected lines to the next indent level or tab stop.


Slide out

The Slide-out item unindents the selected lines to the preceding indent level or tab stop.


Prompted Slide in

The Prompted Slide-in item indents the current selection by a string.  The user is prompted to enter the string.  Handy for commenting out a block.


Prompted Slide out

The Prompted Slide-out item unindents the selection by removing a specified string from each line.  The user is prompted to enter the string.  If a line does not contain this string, it is left unaltered.  Handy for removing a comment block.


Selection Justify

There are several forms of text justification available in Codewright as block operations.  They are not just for word processing style uses, but rather for use on data tables and long series of #defines you want to neaten up.  Just make a column block, indicating where you want the data to align, and justify the text to the left or right boundary of the block, or center it between the boundaries.  Line blocks are also acceptable for this purpose.


Enumerate

This operation puts a number at the beginning of the line for each line in the selection.  In the case of a column selection, the number is inserted at the first column within the selection.

If the first line or line segment begins with a number, numbering continues upward from that number.  Otherwise, numbering will begin with zero.  If the first and second line begin with a number, the difference is treated as the desired increment.  For example, if the first line begins with 10 subsequent lines are numbered 11, 12, 13, and so on.  If the second line begins with 12, however, the third line is numbered 14, the next is numbered 16, and so on.  Other options, such as Hexadecimal numbering, may be specified by editing the menu definition with the menu editor.  See the description of MarkNumSel in the Codewright Programmer's Reference Manual or README.TXT.


Column Formatting

The Column Format operation assumes that the data in the selection is in need of alignment into columns.  Columns are perceived as separated by whitespace.  The operation is increases whitespace to allow for the widest element in each column plus a one space separator.  Using a Column selection allows you to limit the extent of the columnization.

Use this for tables and variable declaration blocks.


Comment Boxes

The Comment and Comment Box menu items draw a user-defined border around selected text.  The border may be a comment block or any decorative characters you care to use.  The strings used for these borders are defined in the Comment Settings Dialog on the Options menu.

The Comment item adds a purely functional left and right border, which may serve as the beginning and end of a comment.  The default for this item is to add /* to the beginning of each line or line segment in the selection, and to add */ at the end of each.

The Comment Box item does the same, but adds a decorative top and bottom line.  This type of comment is usually used for an eye-catching multi-line comment at the beginning of a function or file.  It is designed to be used primarily with line selections, but you may also find it useful for column or stream selections.

This feature makes it convenient to write the text of a comment employing word wrap, and then to add the comment characters later.

The left side of the border is placed at the beginning of the line, or, in the case of a column selection, in the first column of the selection.  The right side of the border is placed at the first tab stop to the right of the longest line in the selection.


Spell Check Dialog

The Spell Check dialog allows you to check the spelling of a word, the words in a selection, or an entire buffer. The Spell check icon will appears on the Tool Ribbon and the item Spell Check will appear on the Edit menu.

Suggest Alternate Spellings

The Suggest Alternate Spellings check box determines, when the spell checker finds a word that is not in the dictionary, whether it lists similarly spelled words that are in the dictionary.  This has the effect of slowing down the checking process, so you may want to omit this option when you know you will be checking a lot of words that are not in the dictionary.

Restrict to Selection

This check box is only available when you have selected a block of text.  When a selection has been defined, a check in this box indicates that only words in the selection are to be checked.

Restrict to Comments/Strings

This option is only available when you have a file loaded that has one of the following extensions:  .C, .H, .CPP, .HPP, .HXX, .CXX, .PAS, .INC, .ASM, .PRG, .SC.  These represent the file types for which Codewright  understands comment structures and string constants.  It is then able to differentiate between comments, strings and other code.  When this box is checked, the spell checker operates only on the words in comments and strings.

Apply Corrections Globally

This check box allows you to specify how the corrections you make are applied.  If you wish all occurrences of a misspelling to be corrected in the same way, select this check box.  For example, you may want the spelling "teh" always to be corrected to "the".  If you wish to check each misspelling yourself to supply individual corrections, leave this box unchecked.

Check Buffer Button

The Check Buffer button initiates a spell check on the current buffer, using the selected options.

Check Word Button

The Check Word button checks the spelling of the word at or by the cursor.

Next Button

The Next button initiates a spell check on the current buffer beginning at the cursor position and continuing through the subsequent text.  This button is useful when you momentarily exit the spell checker to make manual corrections and then want to pick up the spell check from where you left off.

See also the Spell Correction Dialog


Spell Correction Dialog

The Spell Correction dialog box displays the word that the spell checker did not find in the dictionary in its caption.  It then allows you to add the word to the dictionary or correct the spelling of the word.

Replace with

The Replace with edit box displays the spelling that will replace the misspelling when the Correct button is pressed.  If you have elected to have the spell checker suggest possible correct spellings, the spelling selected in the list box below appears here.  You may manually enter a spelling into this box or edit the word displayed.

Add to User Dictionary

When the spelling in the caption is correct and you wish to have the spell checker recognize the word in the future, press this button.  The spell check then continues.  The word will be saved to a special user dictionary at the end of the session.

Correct button

This button replaces the word displayed in the caption with the word in the Replace with edit box.  The spell check then continues.

Ignore button

When you neither want to correct the spelling of the word in the caption, nor want to add the word to the dictionary, press this button.  This is useful when the word is not expected to be repeated elsewhere.  The spell check then continues.

Exit button

This button discontinues the spell check session.  It may be continued later by selecting the Next button on the Spell Check dialog.


The Insert File Dialog
Insert File Dialog

The Insert File dialog box is essentially the same as the File Open dialog, except that you may only select a single file at a time.  The selected file is inserted into the current buffer at the cursor position.


The Insert Literal Dialog
Insert Literal Dialog

The Insert Literal dialog box provides a method of entering characters into the buffer that would otherwise trigger a command.  You enter a value for the character in the character code box.  The representation for that value is displayed in the box immediately to the left, based on the current window font.

Radio Buttons

You may select from among three different modes of entry:  by the decimal equivalent of the character, the hexadecimal equivalent, or by entering the value itself (ASCII).  This selection is made by choosing one of the three radio buttons labeled Decimal, Hex and ASCII respectively.


The Edit Options Dialog
Edit Options Dialog

The Edit Options dialog allows you to select between the Windows Clipboard and Codewright's Scrap buffer as the staging area for cut and paste operations.  It also lets you set options for each.

Cut/Paste Area

This is where you select between using the Windows Clipboard or Codewright's own scrap buffer system.

Multiple Scrap Buffers

You may set the number of scrap buffers defined for use within Codewright.  The default is one.  Sometimes it is desirable to have more than one scrap buffer.  You can then avoid overwriting the contents of one scrap buffer and have another scrap buffer available for normal scrap operations.  Each scrap buffer is numbered, beginning with 0.  To change scrap buffers, change the number in the Current Scrap Buffer box.

Clipboard Options for Column Selections

Codewright exchanges data with other programs in the CF_TEXT format.  This is the format for text most widely understood by other programs.  These options let you determine what separation and termination strings Codewright will use when exchanging data from a column selection with other Windows programs.  This does not affect Codewright's use of the Clipboard when exchanging data between Codewright edit buffers.

Separator and Termination Strings

A column selection consists of a portion of one or more lines.  Usually a column selection spans more than one line, otherwise, a normal (stream) selection would be sufficient.  The separation string is a string that is added to the selection, between the portion of one line and the portion of the next, when it is placed in the Clipboard.  Similarly, the termination string is a string added to the end of the last portion of a line when it is placed in the Clipboard.

The effect of the separation and termination strings you select depends primarily on the application you are exchanging data with.  If the separation string is \r\n (carriage return + line feed) and enabled, each portion of a column selection will probably be inserted as a separate line.  If this feature is disabled or the string is empty, the entire column selection will probably be inserted on a single line or portion of a line.

By allowing you to define individual separation and termination strings, Codewright permits you to make an exception in the treatment of the last line.


Search Menu

Search...	Search for strings.

Search Again	Repeat last search.

Replace...	Replace one string with another.

Replace again	Repeat last replacement.

Multiple Buffers...	Multiple Buffer Search and Replace.

Multiple Files...	Multiple File Search and Replace.

Project Files...	Project Files Search and Replace

Options...	Set the search parameters.

Find next error	Locate next error reported by compiler.

Show error file	Display the compiler error file.

File Find...	Search disk for files matching a pattern.

File Grep...	Search files for matching text.


The Search Dialog
Search Dialog

The Search Dialog box and the Replace Dialog box are the same, except that the Replacement String and  Replace Options group have been added to the latter.


The Replace Dialog
Replace Dialog

The Replace Dialog provides a field for specifying the search string.  Previous entries may be recalled by selecting the down arrow to the right of each of these boxes.  These are followed by several groups of radio buttons and check boxes.  You may set the default values for these options through the Search Options dialog.

Search Direction

You may elect to search forward from the cursor position or backward.

Search Options

This group of check boxes allows you to turn various search attributes on or off.  These include:

•	Ignore case.  When this box is checked, uppercase characters or lower case characters will be matched.  When it is not checked, the case of the characters in the specified search string is significant.

•	Regular expression.  When checked, this box indicates that the search pattern is a regular expression.  Some of the characters in regular expressions are given a different meaning than they would have in an ordinary string search.  This allows for more powerful searches.  See regular expressions.

•	Maximal match  A check in this check box indicates that regular expressions should match the largest possible unit.  If this box is not checked, regular expressions will match the smallest possible unit, which in some cases may be 0 characters.  For example, if the regular expression specifies matching 2 or more A's in a row (AA+), and the search encounters 5 in a row (AAAAA), what does it match?  If maximal match is on, it matches five.  If it is not, the search matches the first two.

•	Wrap at beginning/end  A check in this check box indicates that you want to search the entire buffer.  When the buffer extremity is reached (the beginning or end of the buffer, depending upon the direction of search), the search is continued from the other buffer extreme.  The search concludes at the point at which the search began.

•	Restrict to selection.  This check box allows you to indicate whether you want the search to be restricted to the selection or marked block of text.  If the box is not checked, the scope of the search is global.  This option will be disabled if no selection is defined.

•	Select matching string.  This check box specifies whether the text that matches the search will be highlighted in a selection at the end of the search.  The selection may be momentary, or may be retained so that you can operate on it (copy, cut, or replace).

•	Retain selection.  When the "Select matching string" box is checked, this check box indicates whether the selection that encompasses matching text is momentary or whether it is retained so that you may operate on it.

Replacement Options

This group of options is specific to the replacement operation.

•	Prompted replacement.  When this radio button is selected, you will be prompted each time text matching the search pattern is found.  You may elect at that time to make or skip the replacement, or to cancel the search.  The search continues until no more matches are found in the defined scope of the search, or you select cancel.

•	Single replacement.  When you select this radio button, the first occurrence of matching text is replaced without prompting.

•	Global replacement.  Selecting this radio button causes all occurrences of matching text within the scope of the search to be replaced without further prompting.

Save Settings

This check box is provided to save you from having to make a trip to the Search Options dialog whenever you want to make a change to the search settings.  It does not write the settings to the configuration file, however.  It makes the current settings the default for the session.  These settings are saved in the state file, if you are employing one.

See Also SrchSetFlags


Multiple Buffers Dialog

The Multi-buffer Search and Replace Dialog allows you to define a search or replace operation that is not confined to a single buffer.

Search and Replacement Edit Boxes

The Search String and Replacement String edit boxes allow you to enter the pattern you want to match and the replacement string, just as you would in a single buffer search.  You may only enter a replacement string when the Search and Replace action has been selected.  Both of these edit boxes maintain a history of previous responses, which you may select by pressing the down arrow to the right of the edit box.

Repeat Last

The Repeat Last button provides a shortcut when you are using the same search strings and settings.  You may have, for example, changed only the buffers to which the operation is to apply.  These strings and settings are saved separately from those used in single buffer operations, so don't worry that you may have lost the correct settings by performing an intervening single buffer search or replace operation.

Buffer List

When the dialog first presents itself, the operation applies to all buffers.  If you wish to limit the search or replace to specific buffers, select the Buffer List button.  Codewright  then displays a list of the buffers currently defined, and allows you to select the file to which the operation applies.

Selecting Files from the List

Clicking on a filename selects it for the search operation.  You may select additional files by holding down the [Ctrl] button and clicking on those filenames.  The Clear button allows you to start your selection process over again.  If the list of buffers you don't want to search is shorter than the list of buffers you do want to search, select the buffers you want to leave out and then press the Invert button.  All of the buffers that were previously selected become unselected, while the unselected buffers become selected.

Action

The Action group lets you select between a search operation, and a search and replace operation.  If Search only is selected, you will not be able to enter a replacement string.

Search Options

This group of check boxes allows you to turn various search attributes on or off.  These include:

•	Case insensitive.  When this box is checked, uppercase characters or lower case characters will be matched.  When it is not checked, the case of the characters in the specified search string is significant.

•	Regular expression.  When checked, this box indicates that the search pattern is a regular expression.  Some of the characters in regular expressions are given a different meaning than they would have in an ordinary string search.  This allows for more powerful searches.

•	Maximal match  A check in this check box indicates that regular expressions should match the largest possible unit.  If this box is not checked, regular expressions will match the smallest possible unit, which in some cases may be 0 characters.  For example, if the regular expression specifies matching 2 or more A's in a row (AA+), and the search encounters 5 in a row (AAAAA), what does it match?  If maximal match is on, it matches five.  If it is not, the search matches the first two.

•	Selected buffers Only.  This option is only available when you have selected one or more buffers from the list.  You may select from the list after pressing the Buffer List button.  When this check box is selected, the operation will only apply to the indicated buffers.  When it is not selected, the operation applies to all buffers.

Replacement Options

This group of radio buttons applies only when you are performing a replace operation.  These include:

•	Prompted Replacement.  When this option is selected, you will be prompted each time text matching the search pattern is found.  You may elect at that time to make or skip the replacement, or to cancel the search.  The search continues until no more matches are found in the defined scope of the search, or you select cancel.

•	Single replacement.  When you select this radio button, the first occurrence of matching text in each buffer is replaced without prompting.

•	Global replacement.  Selecting this radio button causes all occurrences of matching text within the scope of the search to be replaced without further prompting.


Multiple Files Dialog

Use this feature with discretion.  Any mistakes you make may not be immediately apparent, since you are not viewing the files.  Backup files are created, if generally enabled, but there is no other undo available if the file is altered on disk.  Note that if you do a Prompted replacement with this dialog, the file will be loaded into a buffer.  The result is more like doing a multi-buffer search and replace rather than a file-based operation.  Buffers loaded for the purpose of prompting are deleted after the operation is complete.

Previously Loaded Buffers

If you choose to search a file that already has a corresponding edit buffer, the buffer will be searched rather than the file.

Search and Replacement Edit Boxes

The Search String and Replacement String edit boxes allow you to enter the pattern you want to match and the replacement string, just as you would in a single buffer search.  You may only enter a replacement string when the Search and Replace action has been selected.  Both of these edit boxes maintain a history of previous responses, which you may select by pressing the down arrow to the right of the edit box.

Repeat Last

The Repeat Last button provides a shortcut when you are using the same search strings and settings.  You may have, for example, changed only the files to which the operation is to apply.  These strings and settings are saved separately from those used in single buffer operations, so don't worry that you may have lost the correct settings by performing an intervening single buffer search or replace operation.

Action

The Action group lets you select between a search operation, and a search and replace operation.  If Search only is selected, you will not be able to enter a replacement string.

Search Options

This group of check boxes allows you to turn various search attributes on or off.  These include:

•	Ignore case.  When this box is checked, uppercase characters or lower case characters will be matched.  When it is not checked, the case of the characters in the specified search string is significant.

•	Regular expression.  When checked, this box indicates that the search pattern is a regular expression.  Some of the characters in regular expressions are given a different meaning than they would have in an ordinary string search.  This allows for more powerful searches.  See regular expressions

•	Maximal match  A check in this check box indicates that regular expressions should match the largest possible unit.  If this box is not checked, regular expressions will match the smallest possible unit, which in some cases may be 0 characters.  For example, if the regular expression specifies matching 2 or more A's in a row (AA+), and the search encounters 5 in a row (AAAAA), what does it match?  If maximal match is on, it matches five.  If it is not, the search matches the first two.

Replacement Options

This group of radio buttons applies only when you are performing a replace operation.  These include:

•	Prompted Replacement.  When this option is selected, you will be prompted each time text matching the search pattern is found.  You may elect at that time to make or skip the replacement, or to cancel the search.  The search continues until no more matches are found in the defined scope of the search, or you select cancel.

•	Single replacement.  When you select this radio button, the first occurrence of matching text in each file is replaced without prompting.

•	Global replacement.  Selecting this radio button causes all occurrences of matching text within the scope of the search to be replaced without further prompting.

Save Settings

This checkbox allows you to retain the settings you have selected for the current search for subsequent searches.

File Name

This is where the files that you want to search are listed.  If you use the File Name listbox, the names will automatically be listed here for you.

File Name List Box

You may select from among the files listed in this box in the same manner you would select files in the Windows File Manager.  Click on a file to select just that file.  Ctrl-click to add a file to those already selected.  Shift-click to select all files between and including the file previously selected through the one on which you click.

Invert Button

If you wanted to select all of the files except the first, third and fifth, you would click and Ctrl-click on those filenames, just as you would if you wanted to open those files, and then select the Invert button.  As a result, the files you previously selected would become unselected and visa versa.

Directories

The Directories box shows the directory structure as a series of folders, the current one in an open position.  You may use this directory tree to change directories and browse their contents.  Just point and click on the desired directory and the files matching the pattern in the File Name box are displayed.  You may only operate on the files in one directory at a time.

Drives

The directories box does not allow you to change drives.  A separate Drives box is supplied for this purpose.  All valid drives and their volume labels, if any, are listed in the Drives box.

List Files of Type

The List Files of Type box contains a list of predefined extensions or groups of extensions that may be selected for display in the File Name box.


The Project Files Dialog
Project Files Dialog

The Project Files dialog allows you to search for and replace text in the files that are members of the current project.  You may search all or any subset of the member files.

Search and Replacement Edit Boxes

The Search String and Replacement String edit boxes allow you to enter the pattern you want to match and the replacement string, just as you would in a single buffer search.  You may only enter a replacement string when the Search and Replace action has been selected.  Both of these edit boxes maintain a history of previous responses, which you may select by pressing the down arrow to the right of the edit box.

Repeat Last

The Repeat Last button provides a shortcut when you are using the same search strings and settings.  You may have, for example, changed only the buffers to which the operation is to apply.  These strings and settings are saved separately from those used in single buffer operations, so don't worry that you may have lost the correct settings by performing an intervening single buffer search or replace operation.

Project List

When the dialog first presents itself, the operation applies to all members of the current project.  If you wish to limit the search or replace to specific members, select the Project List button.  Codewright  then displays a list of the members currently defined, and allows you to select the files to which the operation applies.

Selecting Files from the List

Clicking on a filename selects it for the search operation.  You may select additional files by holding down the [Ctrl] button and clicking on those filenames.  The Clear button allows you to start your selection process over again.  If the list of buffers you don't want to search is shorter than the list of files you do want to search, select the buffers you want to leave out and then press the Invert button.  All of the files that were previously selected become unselected, while the unselected buffers become selected.

Action

The Action group lets you select between a search operation, and a search and replace operation.  If Search only is selected, you will not be able to enter a replacement string.

Search Options

This group of check boxes allows you to turn various search attributes on or off.  These include:

•	Case insensitive.  When this box is checked, uppercase characters or lower case characters will be matched.  When it is not checked, the case of the characters in the specified search string is significant.

•	Regular expression.  When checked, this box indicates that the search pattern is a regular expression.  Some of the characters in regular expressions are given a different meaning than they would have in an ordinary string search.  This allows for more powerful searches.

•	Maximal match  A check in this check box indicates that regular expressions should match the largest possible unit.  If this box is not checked, regular expressions will match the smallest possible unit, which in some cases may be 0 characters.  For example, if the regular expression specifies matching 2 or more A's in a row (AA+), and the search encounters 5 in a row (AAAAA), what does it match?  If maximal match is on, it matches five.  If it is not, the search matches the first two.

•	Selected buffers Only.  This option is only available when you have selected one or more buffers from the list.  You may select from the list after pressing the Buffer List button.  When this check box is selected, the operation will only apply to the indicated buffers.  When it is not selected, the operation applies to all buffers.

Replacement Options

This group of radio buttons applies only when you are performing a replace operation.  These include:

•	Prompted Replacement.  When this option is selected, you will be prompted each time text matching the search pattern is found.  You may elect at that time to make or skip the replacement, or to cancel the search.  The search continues until no more matches are found in the defined scope of the search, or you select cancel.

•	Single replacement.  When you select this radio button, the first occurrence of matching text in each buffer is replaced without prompting.

•	Global replacement.  Selecting this radio button causes all occurrences of matching text within the scope of the search to be replaced without further prompting.


The File Find Dialog
File Find Dialog

The File Find dialog allows you to search the disk for files whose names match a specified pattern.  At the end of the search, any files that were found to match the pattern are displayed in a message box at the bottom of the Codewright  window.  To load any of the files listed in the message box, select that filename from the list and press [Enter].

Pattern

The pattern may be a literal filename or may contain the standard DOS wildcard characters ? and *.  If you specify a path element, the search is limited to that directory.  Otherwise, the entire drive is searched.

Output file

You may specify the name of the file in which the names of matching files are stored.  The default name is CWFFIND.___.  You may specify another name if the default causes a conflict, or if you wish to save the output from the previous or current operation.


File Grep
File Grep Dialog

File Grep allows you to search through files on disk for a text string matching a specified pattern. Its dialog is located at the bottom of the Search menu. At the end of the search, the names of any files that were found to contain matching text are displayed in a message box at the bottom of the Codewright window.  The line numbers and the line containing the matching text are also displayed.  To move to any of the matches listed in the message box, select the matching line from the list and press [Enter].

Pattern

The pattern to be matched may be a literal string or a regular expression.  It is only treated as a regular expression, however, when Regular expression is selected in the option group.

Scope

The scope of the search determines what files will be searched for matching text.  The scope pattern may contain the standard wildcard characters ? and *.  If the pattern does not contain a path element, Codewright searches the current directory.  If you affix a path to the pattern only that directory will be searched.

Output file

You may specify the name of the file in which the file and line numbers of matches are stored.  The default name is CWFGREP.___.  You may specify another name if the default causes a conflict, or if you wish to save the output from the previous or current operation.

Regular expression

When the regular expression box is checked, special meaning is given to certain characters to enable more powerful searches.  Select this option even if you are only using the escape sequences used in regular expressions, such as \t and \n.

Subdirectories

When this box is checked, the subdirectories under the current or specified directory are also searched using the specified filename pattern.

Ignore case

When checked, the case of characters specified in the Pattern box and in the files searched is not considered significant.  Lower case characters are allowed to match upper case characters and vice versa.

Buffers only

This check box indicates that buffers are to be searched rather than files.


Search Options Dialog

The Search Options Dialog is largely the same as the Replace Dialog box, except that the search and replacement strings have been omitted.  Use this dialog to set which of the search and replace options are on or off  by default.

Search Direction

You may elect to search forward from the cursor position or backward.

Default Prompt

This group of radio buttons allows you to select the source of the search string that initially appears in the search string edit box.  The choices are:

•	Current word  Use the word at the cursor as the default search string.

•	Selection  Use the contents of the selection as the default search string.

•	History  Use the history mechanism to allow selecting from search strings previously used.

Search Options

This group of check boxes allows you to turn various search attributes on or off.  These include:

•	Case insensitive.  When this box is checked, uppercase characters or lower case characters will be matched.  When it is not checked, the case of the characters in the specified search string is significant.

•	Regular expression.  When checked, this box indicates that the search pattern is a regular expression.  Some of the characters in regular expressions are given a different meaning than they would have in an ordinary string search.  This allows for more powerful searches.  See regular expressions

•	Wrap at beginning/end  A check in this check box indicates that you want to search the entire buffer.  When the buffer extremity is reached (the beginning or end of the buffer, depending upon the direction of search), the search is continued from the other buffer extreme.  The search concludes at the point at which the search began.

•	Restrict to selection.  This check box allows you to indicate whether you want the search to be restricted to the selection or marked block of text.  If the box is not checked, the scope of the search is global.  This option will be disabled if no selection is defined.

•	Maximal matching  This check box determines whether the search will match the largest unit of text or the smallest that fits the specified pattern.  For example, if the line contained the text "param1, param2," and the pattern was ".*," maximal matching would match the whole line, while non-maximal would match just  "param1,".

Replacement Options

This group of options is specific to the replacement operation.

•	Prompted replacement.  When this radio button is selected, you will be prompted each time text matching the search pattern is found.  You may elect at that time to make or skip the replacement, or to cancel the search.  The search continues until no more matches are found in the defined scope of the search, or you select cancel.

•	Single replacement.  When you select this radio button, the first occurrence of matching text is replaced without prompting.

•	Global replacement.  Selecting this radio button causes all occurrences of matching text within the scope of the search to be replaced without further prompting.

See Also SrchSetFlags


Project Menu

New...	Create a new project.

Edit...	Change an existing project.

Open...	Open an existing project.

Close	Close the current project.

Load files...	Load one or more files from the project.

Directories...	Project files and directories setup.

Configure...	Configure build, execute, debug command lines.

Compiler Setup...	Configure compiler for each file type.

Browse	Enable/Disable Browser window

Build Tags	Generate the Tags database

Load Workspace...	Load workspace defined in the project.

Save Workspace...	Save a workspace for the project.

Options...	Set configuration options.


New Project Dialog

Creating a Codewright project is as simple as selecting New from the Project menu and entering a name for your new project.  The name is the filename and path in which the project information will be stored.  In selecting a name, keep in mind that Codewright does not assume any extension for the project filename.  If you want an extension, you must specify one.  We recommend that you use the filename extension .PJT for your projects.

After creating the project, you are given the opportunity to specify the names of files that are members of the project.  See The Project Edit Dialog.  You should also select Options from the Project menu to define how much configuration information will be saved along with the filenames in the project file.


Project Edit Dialog

You specify the members of a project by selecting Edit from the Project menu.  Locate the files you want to add by navigating your file system as you would when using the File Open dialog.  You may select a series of files and then add them by pressing the Add button, or you can double click on each filename to add it to the project.  A file may be a member of more than one project, so specify any files you want to group together logically and which you might want to operate on as a group.

Files that are included in the project are listed in the box at the bottom of the dialog as you add them.  You may delete files from the project by selecting them in this box and then pressing the Delete button.

This dialog contains extended selection listboxes.  For more information on the use of extended selection listboxes, see "Extended Selection Listboxes".


Project Open Dialog

You can select a project by choosing Open from the Project menu.  You can navigate your directory structure as you would when using the File Open dialog and select the name of a project file you wish to load.

Recently selected projects will be listed at the bottom of the Project menu, numbered from one to nine.  You may select from this list to reload any of the projects listed.


Project Load File Dialog
Project Load Files Dialog

One of the best things about organizing your work into projects is the convenience it provides in selecting files for loading.  Just choose Load Files from the Project menu and you will be presented with a list of files in the current project.  You can select one or more files from this list for loading and editing.  If you find that some members of the project aren't listed, select Edit from the project menu to add them.  If you wish to load files that are not part of the project, select Open from the File menu.

The rules for using extended selection listboxes apply to the Load Files dialog.  If you need to review these rules, see "Extended Selection Listboxes".


Project Directories Dialog

The Directories entry on the Project menu provides information about and lets you set directories used in the current project.

Informational Directories and Filenames

The Project Directories dialog begins with several filenames and paths that are presented for informational purposes only.  You cannot change these entries.  They are described in the table below:

Entry	Description

Filename	The file in which Project information is stored.  This will be your configuration file if you have not defined or selected a project.

Initialization	The file in which configuration information is stored.  This is normally CWRIGHT.INI

State	The file in which the state of Codewright and the files you were editing is stored between Codewright sessions.  This is usually CWRIGHT.PST.

Extension	The file in which Extension-specific settings are stored.  This will be your configuration file unless you have defined a project or if you have specified a separate file for this information.  If a project is in use, this information will be stored in the project file unless you specify otherwise.

Working Directory

The working directory entry is the directory from which commands are launched.  This includes extension specific compile commands, debug and other commands listed in this dialog box.

•	Note:	This working directory does not apply to Check-in and Check-out commands.  For these version control commands, the current directory is the directory where the workfile is located.

Browser Database Directory

This is the location and filename in which the Microsoft Browser database (.BSC file) or compiled tags database (.PTG file) for the project is located.  This is used by the Browser and Build Tags entries on the Utility menu.

Tags Database Directory

This is the location and filename in which Tags data for the project is located.  This is especially useful if you are not using a Microsoft compiler.  This is used by the Browser and Build Tags entries on the Utility menu, and also TagFind and the various Tag... hypertext-style functions.

Browse Buttons

The browse buttons next to each of the three directories described above allow you to locate the desired directory on disk by graphically traversing the directory structure of your drives.


Project Configuration
Project Configuration Dialog

Project configuration consists of setting up project-wide utility settings.  This is where you define all commands, except for compiler commands. Compiler commands are File-type specific.  This is also where you define how compiler output (the error file) is processed.  You receive this dialog when you choose Configure from the Project menu.

Error Filename

Error Parsers

Project Command Lines

Capture Output from Commands

Command Window Display and Execution


Error Filename

The Error filename is the name of the file in which the error parser will look for error output.  You don't need to specify a name for this file, but if you have files in many directories for the same project, it is best to name a file, and its path, explicitly.  If you don't specify a name, the parser will look for a file based on the name of the buffer.

It will first substitute .ERR for whatever extension the buffer has been assigned.  That is, if the buffer is named FOO.C, the parser will look for FOO.ERR.  If it doesn't find such a file, it will try using the buffer's extension as a basename.  In other words, if the buffer is FOO.C, it will look for C.ERR.

If this method of arriving at an error file name does not suit you, you should specify a name of your own choosing.  You may use the macros shown in the Command Lines key to refer to portions of the filename generically (e.g., %b.ERR).


Error Parsers

An Error parser is a function that can take error messages from a compiler, assembler, or linker and extract the name of the file, the line number and the message from it.  The parser functions are named to indicate which utility they go with.

You can name up to three parsers to be used sequentially on your error file.  The output of a "Make" or rebuild might contain output from a compiler, linker and assembler.  If so, you may require three error parsers to process the errors from each.

Don't be too concerned if your compiler isn't listed, however.  While you can't just make up a function name, one of the functions listed will probably work.  For example, there is no parser specifically for Turbo Pascal.  You might think you could use the Borland/Turbo C parser, but no.  It is the Default parser that works on Turbo Pascal.  The Default error output format is as close to a standard as there is, so when in doubt, try the Default parser (_DefaultErrorInfo).

If you find that none of the listed parsers will do the job, there may be a parser on the "Best of BBS" disk that is designed for your compiler or utility.  The "Best of BBS" disk is disk 3 of the distribution diskettes.  On it you will find a file ERRPARSE.ZIP.  Instructions and a DLL are enclosed in this archive.


Project Command Lines

After you have made these selections, you are ready to specify or edit the command lines listed for the various Utilities menu selections.  They are: Make, Rebuild, Debug and Execute, plus two alternate commands.

There are sample commands that are initially displayed in these fields.  These commands are not useful as supplied, but rather await your edits.  You can replace parameters such as <makefile> with a specific filename, or with a symbolic value.

There are several symbolic labels or macros that can be used in the various command lines.  You use these macros in the command line in place of the filename, or portions of the filename, since the filenames are various and unknown at this time.  The actual value used when the command is issued will then depend on the name of the current buffer.  These macros and their meanings are listed in a table at the beginning of the Command Lines group.


Capture Output from Commands

Each command line listed has a corresponding "Capture Output" check box.  When this box is checked, output is automatically redirected to the Error filename you specified.  If the utility referenced in the command line has some other provision for capturing output, you may want to disable automatic output capture.

In most cases, you will want to see the output of the command on the screen as well as capturing it in a file.  Codewright provides you with two methods of doing this: VDOS and FTEE. Once VDOS in enabled, Capture Output support is automatic.  If you choose to use FTEE instead, you will find the information in this section useful.

The FTEE utility (or FTEE32 for Windows NT), is supplied along with Codewright.  Just place the FTEE command at the beginning of the command line.  If your Codewright directory is not on the path, ensure the file FTEE.EXE is in a directory that is.

FTEE is similar to the several TEE programs you will find in the public domain and on many Unix systems.  Like a plumbing or electrical "Tee" connector, these programs allow you to direct output to two places at once.  The difference between FTEE and these TEE programs is that FTEE allows the command to execute normally whenever you do not redirect output to a file.  Other TEE programs typically quit with an error message under these circumstances.

Before using FTEE, make sure that your application does not do any redirection on its own.  Nothing useful can result from both your program and FTEE trying to redirect the same output.

If you are calling a Windows executable, such as Borland's BCW, do not try to capture output in this manner.  The program will be treated as a DOS application, if you do.


Command Window Display and Execution

The groups labeled Window Display and Execution permit you to specify some aspects of the execution of the command lines you have entered.  The Window Display group lets you specify what state the execution window will be given.  The Execution group lets you specify whether the task will run in the foreground or as a background task.

If you elect to execute a process in the background, a message appears on the status line an a beep sounds to indicate that the background task has been completed.

In the Windows version of Codewright, you can modify the behavior of foreground and background tasks by changing the PIF files, COMFGNML.PIF (foreground) and COMBGNML.PIF (background).  You can find these files in the Codewright home directory.


Save Workspace Dialog

You may at any time save a workspace by selecting Save Workspace from the Project menu, but this is usually only necessary when creating a new workspace.  Codewright automatically updates the active workspace whenever you:

•	close or change projects,

•	exit Codewright,

•	and optionally when you change workspaces.

At any time while working on a project, you can select Save Workspace from the Project menu and create a new workspace.  Just give your workspace a name -- a descriptive name, rather than just a file name.  A workspace name may contain any printable characters (including spaces) except apostrophe ( ' ), backslash ( \ ), quote ( " ), and square brackets ( [ ] ).

Creating a Workspace

Suppose that you have a number of files open, and want to create a new workspace that doesn't include any of the files currently open.  Select Load Workspace from the Project menu.  You will see listed there a workspace that is always available, called <none>.  You can select that workspace to wipe the slate clean.  If the "Delete buffers and windows" option is set to "All", your buffers and windows are all closed so that you can start afresh.   Of course, if any of the buffers contain changes that have not been saved to disk you will be given an opportunity to do so.

Now that you have your clean slate, open the files that you want to have open in your workspace.  Anytime you are ready, you can save your workspace under whatever descriptive name you wish.


Load Workspace Dialog

Once you have created more than one workspace, you will find it easy to switch between them.  When you select Load Workspace from the Project menu to do this, you will notice a couple of options are available.   These options relate to what happens to the workspace you are leaving.

Update Current Workspace

When the Update Current Workspace box is checked, the workspace you are leaving is automatically updated before the new workspace is loaded.

Close Windows/Delete Buffers

You may choose to close all windows and buffers after leaving one workspace and before the next is loaded.  In this event, no buffers or windows are carried over from one workspace to the next.  You may elect to just close the files that are members of the workspace.  This means that any files you opened during the session, such as a special header file, will carry over to the next workspace.  You may even choose to have all files carry over into the next workspace.  If you do this, we recommend that you either delete the carry-over buffers before saving the workspace, or save the workspace under a new name.  Otherwise, workspaces will become less distinct, and therefore less useful, entities.

Keep in mind that the saving of windows and buffers in the workspace you are leaving is unaffected by which of these options you select.


Project Options Dialog

The amount of configuration information kept in the project file versus the configuration file is configurable.  This is what you are setting when you select options in the Options dialog on the Project menu.  The more information that goes into the Project file, the less information goes into the Configuration file, as you change settings.

Configuration Component Checkboxes

The check boxes indicate which categories of settings you wish to transport with the project file.  Just changing the status of these checkboxes, however, does not move information from one file to another.  Moving settings information between files, however, may be accomplished through this dialog.

Update configuration files

This checkbox lets you immediately update the project file and configuration file to reflect the changes you made in the Component checkboxes.  It is usually not necessary to change the contents of these files immediately.  It will be updated automatically when next you modify your settings through Codewrights other dialogs.  You may wish to use this setting, however, after reading in new configuration settings using the Read Configuration File Data button.

Read Configuration File Data

See also Configuration Categories Detail


Read Configuration Data Dialog

This dialog allows you to read configuration settings from any file.  Using this dialog in combination with the Update Configuration Files checkbox in the Project Options dialog lets you readily transport configuration information from one file to another.

Configuration Components

The series of checkboxes in this dialog let you limit what settings are read from the file.  Only the settings in the categories checked will be read.

Browse

The browse button allows you to locate any file on disk which may contain configuration information or settings.  This includes project files and .INI files.


Build Tags

The build tags entry on the Project menu allows you to generate both the Tags hypertext database, and the Premia compiled tags database.  This function only operates if you have a project open.  Codewright then runs the WTags executable supplied on the files that are members of the current project.

Before issuing this command, you must have defined the name to be given to the standard Tags database in the Project Directories dialog.  If you wish to generate the compiled database for use with the Browser, you must also have defined a name for the Browser database in the same dialog.  Use the extension .PTG for this filename rather than .BSC, which should be reserved for Microsoft Browser database files.


Buffer Menu

Next	Change to the next buffer in the list.

Previous	Change to the previous buffer in the list.

Create	Create a new buffer.

Delete	Delete the current buffer.

Clear	Clear the current buffer.  This cannot be undone.

Delete All	Delete all buffers.

File Type Properties	View/Change file type specific properties.

Properties...	View/Change buffer properties.

Mark...	Location marking submenu.

Select...	Choose a buffer from a list.

The Buffer menu lists operations that are commonly performed on buffers.

If you have selected the "One buffer per window" mode of operation, switching buffers also switches windows.  Otherwise, the selected buffer will be assigned to the current window.

If the "One buffer per window" mode is off, as you open and work on a buffer, the filename is added to the bottom of the Buffer menu.  The name with the check mark beside it in the left hand column is the current buffer.  You may make another buffer current merely by selecting it from this menu list.  There is a similar list of windows on the Window menu that you may use to change buffer and window as a unit, if One buffer per window is on.

Note:	Buffer operations such as Create and Delete are influenced by the state of the "One buffer per window" option.  This option causes windows and buffers to be treated as a unit for these operations.  It is set through the Options System Dialog.


Buffer Select Dialog

The Select Dialog lists the currently defined buffers and allows you to select from or modify the list.

Modified/Read-only Designations

As indicated by the interpretation key at the bottom of the dialog, buffer names in the list that are preceded by an R are Read-Only buffers.  Edit actions are disabled in these buffers.  Buffer names preceded by an M contain modifications that have not been written to disk.

Making a Buffer Current

To make a buffer current, select the buffer name from the list and press [Enter] or just double click on the name.

Save Button

If you find a buffer on the list that you want to save to disk, just select that buffer and press the Save  button.  You will note that the buffer is no longer designated as modified.

Delete Button

You may find that there are one or more buffers on the list that are no longer needed.  To dispose of these buffers, select them one at a time and press the Delete button.

Settings Button

To view or modify the buffer's settings, including Read-Only status, select the buffer name and then press the Settings button.


Buffer Properties
Buffer Properties Dialog

You can update any buffers, current, non-current or model buffer from this dialog.

Source/Destination

These groups let you determine which buffer's properties are viewed and which buffers receive the settings after you modify them.  In the Source group, you can elect to view the Current Buffer Properties, the Model Buffer Properties, or use the Select Buffer button to view the settings for any currently defined buffer.

Similarly, the destination group allows you to assign the viewed settings to the Current Buffer, the Model Buffer, All User Buffers (does not include the Model Buffer), or a selected, arbitrary list of buffers.  The Selected Buffers button allows you to define an arbitrary list of buffers.  This is an extended selection listbox.

•	Filename  This is the name of the file from which the buffer was read.  This entry can't be edited.  It is often referred to as the original filename.

•	Buffer name  This is an arbitrary name you can give a buffer.  Usually this is done on buffers created for a special purpose, and which have no input file.

•	Output name  The name of the file to which the buffer will be written.  When this is blank, the Filename serves as an output name.

•	Backup spec. A formatting string that describes how the name of the backup file is derived from the output name.

Current Position

You can change the Current Position in the buffer by changing the value of the line and column variables in the Current Position group.

User Flags

 The User Flags is a double word value that is made available for the user to define and modify, much as Codewright uses Buffer SysFlags.  There is no predefined meaning or use for this variable.

Tab Stops

In the Tab Stops group, the Maximum Column setting defines the column number after which tab stops are no longer calculated.  This setting in no way limits the length of the line.  It does, however, speed up some operations if Codewright doesn't have to do tab expansion all the way to the end of a line of indefinite length.  This is particularly true of binary files.

The Tab columns string describes where tab stops will occur.  Tab stops are placed at the columns specified in this string.  For evenly spaced tab stops, you need not specify more than two column numbers.  Codewright calculates the interval between the last two column numbers and repeats that interval between tab stops all the way out to the Maximum Column.  The column count begins with 1, not 0.

Buffer SysFlags

The buffer's System Flags, or Buffer SysFlags that appear in the Properties dialog are listed below:

Name	Description
Read-Only	Specifies whether edits are permitted on the buffer.
Overtype	Determines if the buffer is in overtype or insert mode.
Use Tabs	Specifies whether tab characters or spaces are used to fill to the next tab stop, when requested.
Make backups	Tells whether a backup copy of the file should be generated when saving.
Record undo info	Dictates whether a record of edits is kept so that they may be undone.
Unix EOL	Indicates whether inserted newlines are <cr><lf> or just <lf>.
Ctrl-Z EOF
Input	Dictates whether reading a file terminates when Ctrl-Z is reached.
Output	Tells whether a Ctrl-Z character should be appended to a file when it is written to disk.
Display mode
Normal	The default mode of operation, whenever compact and hex modes are not selected.
Compact	Indicates if the buffer is in Compact viewing mode.  Portions of the buffer may be hidden while normal editing continues on others.
Hex ASCII/Binary	Indicates if the buffer is in Hexadecimal viewing mode.  Bytes are shown in hex and ASCII representations.  The cursor may be placed in either the ASCII or Binary portion of the display.
Status group
System	Identifies the buffer as a system buffer.  Usually, this means the buffer is not an edit buffer.  You cannot change this setting.
Modified	Specifies that the buffer contains changes that have not yet been written to the output file.  Changes may have been auto-saved, however.  You cannot change this setting from the Buffer Properties dialog.
Auto-Indent group*
Use virtual space	Positions the cursor at the indented position on new lines, but does not fill until the line is edited.
Use spaces	Immediately fills the indent with spaces, even if the line receives no further edits.
Use tabs	Immediately fills the indent optimally (spaces and tabs as necessary), even if the line receives no further edits.
Use tab mode	Immediately fills the indent with spaces, or spaces and tabs, depending on whether tab usage is enabled for the buffer.
Duplicate	Immediately fills the indent by duplicating exactly the whitespace present on the preceding line.
None	Disable the auto-indent feature.
Seek Indentation	If the previous line contains no printing characters, search backwards for a line that does, and use that lines indent level.  Use in conjunction with one of the settings above.
Virtual Lines group
Enable	Indicates if the cursor may travel beyond the end of the buffer.  The maximum number of virtual lines may also be set.  That setting also appears in the Virtual Lines group.
* For a more detailed description of the Auto-indent feature, see Auto-indent.


File Type Properties Dialog
File-Type Properties Dialog

When you select File-type Properties from the Buffer menu, you are looking at the central jumping-off point for controlling Codewright's file type specific features.

Associating Extensions with a Language

File Type

Adding Extensions

System Flags

Edit Options

ChromaCoding

Backup Specification

Tabs

Word Delimiters

Output File

Extension Filename Button

See also:

Compiler Setup

Template Setup

Brace-style Setup


Associating Extensions with a Language

Before you start your extension-specific configuration, you should consider if you will need to add or extend language features to file types that Codewright doesn't know about.  By default, Codewright knows that files with the extension .C are C language source files.  Similarly, it knows about .ASM, .PAS, .CPP, and, if the right DLL is loaded, .SC, .PRG, .BAS and .COB.  But what about .A86 or .CAS or even .INC?

It doesn't do any good to turn on language support for a type of file if Codewright doesn't know what language that type of file contains.  Use the command ExtAlias in your .INI file to tell Codewright which language the file type  represents.  If you know anything about Windows-style .INI files, you can probably wing it.  As an example of how this is done, the command below tells Codewright that a .CAS file is the same as a .C file:

[Editor]

ExtAlias=".CAS", ".C"

A line containing the ExtAlias command has been added to the [Editor] section of Codewright's CWRIGHT.INI file.  You can repeat this command for as many file types and languages as you desire.

To learn more about Codewright's CWRIGHT.INI file, consult the "Introduction to Configuration and State" section in chapter 3 of the Codewright User's Guide.


File Type

(File Type Properties Dialog on the Buffer menu)

There is a column of filename extensions listed at the left of the dialog. This indicates where the properties you are currently viewing come from and to which extension you are going to apply them. If listed, the extension of the file associated with the current edit buffer is selected initially, but you may change this to any desired extension.  Clicking on various extensions lets you quickly review the properties for those extensions.

Note:	There is a special extension reserved for default settings.  This extension is .*.  Select this extension when you want to define commands and settings for files that have no settings defined specifically for their extension.

You may select more than one extension at a time.  This may save you some time if you want to setup several extensions the same way.  Use the rules for extended selection listboxes to select more than one extension (click on first file, Ctrl-click on other files, Shift-click for range).


Adding Extensions

(File Type Properties Dialog on the Buffer menu)

If you do not see the filename extension of interest listed in the file-type box, do not be alarmed.  This does not imply that there is no support for that extension.  The extensions for languages that are supported in separate DLLs are not listed, since the support may not be available.

Select the edit box titled New and type in the extension or extensions you want to add.  If you are adding more than one extension, separate each of them with a space.  A leading dot ( . ) is optional.  You can immediately begin making appropriate settings for that extension by pressing the Accept button.  (Reminder:  don't press [Enter] or the dialog will go away).


System Flags

(File Type Properties Dialog on the Buffer menu)

The first group of settings is labeled System Flags.  This dialog shares these settings with the Model and Current Buffer Properties dialogs.  To set defaults for the destination extension, select the desired settings here.

Name	Description
Read-Only	Specifies whether edits are permitted on the buffer.
Overtype	Determines if the buffer is in overtype or insert mode.
Use Tabs	Specifies whether tab characters or spaces are used to fill to the next tab stop, when requested.
Make backups	Tells whether a backup copy of the file should be generated when saving.
Record undo info	Dictates whether a record of edits is kept so that they may be undone.
Unix EOL	Indicates whether inserted newlines are <cr><lf> or just <lf>.
Ctrl-Z EOF
Input	Dictates whether reading a file terminates when Ctrl-Z is reached.
Output	Tells whether a Ctrl-Z character should be appended to a file when it is written to disk.
Auto-Indent group
Use virtual space	Positions the cursor at the indented position on new lines, but does not fill until the line is edited.
Use spaces	Immediately fills the indent with spaces, even if the line receives no further edits.
Use tabs	Immediately fills the indent optimally (spaces and tabs as necessary), even if the line receives no further edits.
Use tab mode	Immediately fills the indent with spaces, or spaces and tabs, depending on whether tab usage is enabled for the buffer.
Duplicate	Immediately fills the indent by duplicating exactly the whitespace present on the preceding line.
None	Disable the auto-indent feature.
Seek indentation	Search backward for line containing printable characters and duplicate its level of indentation.  Used in conjunction with one of the other settings.


Edit Options

(File Type Properties Dialog on the Buffer menu)

The edit options let you turn on some enhancements to the normal editing features.  Smart indenting and Template expansion are language-specific.  There must be built-in support for the language you are using for you to use these features.

Smart Indenting

The Language indentation feature, also called Smart indenting, automatically  indents when you press [Enter] after typing certain words.  For example, if  in a .C file you press enter after typing a curly brace, the next line will automatically be indented.  Other words will cause smart indenting when they appear at the beginning of the terminated line.  To continue with our .C file example, such words as "while" and "switch" at the beginning of the line will cause the next line to be indented.

Smart indenting may be thought of as an extension of the auto-indent feature that recognizes the block constructs of the programming language and indents accordingly.  You may, however, use smart indenting with auto-indent turned off.  Most of the time you will want to have auto-indent on when using smart indenting which will ensure the most consistent appearance of your code.

Smart indenting will recognize the comment constructs of a language.  True to its name, it will be smart enough not to automatically indent lines that you are typing into a comment.  The languages for which smart indenting is supported include C, C++, Pascal, dBASE, Visual Basic and Paradox.  The source code for this feature is provided if you wish to modify or add to the support.

Template expansion

There are some aspects of writing source code that are both repetitious and quite predictable.  Such tasks are prime candidates for automation.  The language templates feature provides you with a "fill in the blanks" form for many of the language's more common control structures.  This takes some of the drudgery out of code writing, as well as speeding it along.

When this feature is enabled, typing certain words or abbreviations will cause a template to be inserted into the buffer.  When you press the space bar after typing one of these words, Codewright inserts the associated template and positions the cursor at the first "blank" that must be filled in.

To use Pascal as an example, pressing the space bar after typing the word "FOR" (using any combination of character case), will cause a FOR Loop template to be inserted into the buffer.  The cursor is then positioned following the word "FOR", ready for you to type in the name of the variable that controls the loop.

Language Templates are provided for the following languages:  C, C++, Pascal, dBASE, COBOL, Paradox and Visual Basic.  Remember, you do not have to type the entire word to activate these templates.  In most cases, the first two characters will do.  In some cases the first letter of each word will trigger the template, as in the case of "else if" where "ei" triggers template insertion.

Don't worry about typing these words into comments.  Codewright will not insert a template when you are typing within comments.  Templates and the macros that are used in them are discussed further in "Template Macros".

Word Wrap

This options allows you to set whether the word wrap feature is initially on or off for this type of file.  When this is on, text will wrap when it reaches your right margin mark.  If you have not defined a right margin mark, it wraps when text reaches the edge of the screen.  You may wish to have this on for  .TXT files and off for most other types of files.

Brace Expansion

This feature is a special key assignment for C and C++ language support.  It operates very much like the Brace template in Template Expansion, except that the template is inserted whenever you type the left brace ( { ) key.  Template Expansion isnt activated until you press the space bar.

This may be an unnatural sequence for many styles of programming, and this feature therefore provides an alternative.  It may also be useful for users who do not want full template expansion, but who want the benefits of automatic brace handling.

Whether you use Brace Expansion in conjunction with Template Expansion or instead of it, this feature uses the style of brace placement specified in the Brace-style Setup dialog.  When you type a brace, it is automatically positioned, the closing brace is inserted in the correct position and the cursor is placed between them.


ChromaCoding

(File Type Properties Dialog on the Buffer menu)

One of the features provided to assist in the task of programming is ChromaCoding.  The ChromaCoding group are features that apply color coding to text as you type. You may select Changed lines ChromaCoding, Language Dependent ChromaCoding, or both.

Language Dependent

The Language Dependent ChromaCoding gives color to various elements of your programming language's syntax.  While this support varies somewhat from one language to another, the following elements are generally supported:

•	comments

•	keywords (reserved words)

•	strings

•	numbers

There is additional support for C/C++ to color the following:

•	preprocessor commands

•	braces

You may select a different color for each element.  You control the colors used by this feature through the Window Colors dialog.  You can select a color that will make the comments stand out from the code, or to make them fade into the background.  This feature is supported for  C, C++, Pascal, Assembly language, xBase, Visual Basic, COBOL, and Paradox.  Support can readily be added for other languages.

Changed Lines

Changed Lines ChromaCoding facilitates locating portions of a file that have been modified.  When you enable Changed Lines ChromaCoding but not Language Dependent ChromaCoding, you will see the color of an entire line change whenever you first edit that line. When you enable both Changed Lines and Language Dependent ChromaCoding only the left margin of the window shows which lines have changed or been added.  This avoids interference with Language Dependent ChromaCoding.

Reset on Write

The Reset on Write option applied to Changed Lines ChromaCoding. When Reset on Write is enabled Changed Line markings in the left margin are cleared when you save the file.  If it is disabled Changed Line markings accumulate throughout the edit session. Selecting another radio button from this group will reset the colors, however.

You can set the colors used by ChromaCoding, through the Window Colors dialog.  There are two color settings used by this feature.  One is used on newly inserted lines, and the other is used on existing lines that have been changed (including lines that are first inserted and then changed).  This feature is supported for all languages and, of course, ordinary text files.


Backup Specification

(File Type Properties Dialog on the Buffer menu)

The Backup specification is a formatting string that describes how the name of the backup file is derived from the name of the output file.  This is usually set on a global basis rather than for a specific extension.  It is set globally in the System Options dialog, which you will find on the Options menu.


Tabs

(File Type Properties Dialog on the Buffer menu)

The Tabs field allows you to set tab stops specific to the selected extension.  When this field is empty, tab stop settings will be those defined for the buffer, usually a setting inherited from the Model Buffer.  It is best to set the Model Buffer tab stops to reflect your normal preferences, rather than setting tab stops for each extension.  This field is useful for specifying the exceptional case, where your normal tab stop preferences do not apply to files with a certain extension.


Word Delimiters

(File Type Properties Dialog on the Buffer menu)

The Word Delimiters field allows you to define what a "word" is for files of the selected extension.  Word delimiters are the characters that separate one word from another.  Due to the variation of characters allowed in identifiers from one programming language to another, it may be useful to vary this definition with the file type.

This definition is used in the NextWord and PrevWord functions that move the cursor position in units of a word.  In addition, other functions based on these functions are affected by this definition.  Whitespace characters are always implicit in the definition of a word.  List punctuation and other delimiters in this field.

Note:	These delimiters are used as a regular expression's class.  As such, certain characters must be "escaped".  That is, they must be preceded by a backslash.  The characters that must be escaped are: ] " - ^ \  They will look like this when escaped: \] \" \- \^ \\  See "Regular Expressions".


Output File

(File Type Properties Dialog on the Buffer menu)

The name of the file in which File-type Properties are stored is displayed next to the label "Output File".  If the indicated file is not desirable, press the Extension Filename button to change it.


Extension Filename Button
Extension Filename Dialog

The Extension Filename button allows you to define where the options set through this dialog will be stored.  They can be stored in your configuration file, your project file, or in a file that you name.

If you name a file to use, you can follow the convention by giving it a .EXT extension.  This file never contains compiler and template definitions (unless edited by hand), but is limited to flags and other extension initialization information.

If there is no current project, the information will default to being stored in your configuration file.  If you are using a project, the project file is often the best place to keep this information.  It is particularly useful to store the compiler setup information in the project file.


Mark Submenu

Mark...	Place a bookmark.

Goto Mark...	Move to a bookmark.

Goto Line...	Move to a specified line.

Save Position	Save current position on a stack.

Restore Position	Restore position from a stack.


The Mark Dialog
Mark Dialog

The Mark Dialog allows you to define a bookmark at the current buffer location.  To define a bookmark, you select a number for the bookmark, from one to nine, reusing older bookmarks as you see fit.

Local/Global

Bookmarks may be local or global, as defined by the radio buttons that are so named.  Bookmarks are global by default.  The advantage of global bookmarks is that you may jump directly to them from any buffer.  Local bookmarks are only useful for intra-buffer jumps.

Mark Number

You may select an arbitrary number for you bookmark by using the Mark box, directly below the other bookmarks.

OK/Cancel

The bookmark is defined at the cursor position in the current buffer when you select the OK button.  To avoid creating a bookmark you must press [Esc] or select the cancel button.


The Goto Mark Dialog
Goto Mark Dialog

This dialog is almost identical to the Mark Dialog, except that when you select a mark from the list, the cursor is moved to that position, instead of defining a mark.  In addition, there is a "Swap" button that allows you to exchange the position of the selected bookmark with the cursor position.  What was the cursor position becomes the location of the bookmark, while what was the location of the bookmark becomes the current position.


The Goto Line Dialog
Goto Line Dialog

The Goto Line Dialog requests the line number of the line to which you wish to move.  You may elect to go to the line currently assigned that number, or to the line which was assigned that number when the file was last saved.  If lines have been inserted or deleted since the last save, the moving to the original line #258 may not take you to the current line #258. You may choose between these two destinations by selecting either the Current or Original radio button.


Compiler Setup

When you select the Compiler Setup from the Project menu, you will receive the Compiler Setup dialog that allows you to define compiler commands for the selected file extension.

Compiler File Type

Compiler Name

Compile Command Lines

Response File Contents

Capture Output

Window Display and Execution


Compiler File Type

There is a column of filename extensions listed at the left of the dialog. This indicates where the settings you are currently viewing come from and to which extension you are going to apply them. If listed, the extension of the file associated with the current edit buffer is selected initially, but you may change this to any desired extension.  Clicking on various extensions lets you quickly review the settings for those extensions.

Note:	There is a special extension reserved for default settings.  This extension is .*.  Select this extension when you want to define commands and settings for files that have no settings defined specifically for their extension.

You may select more than one extension at a time.  This may save you some time if you want to setup several extensions the same way.  Use the rules for extended selection listboxes to select more than one extension (click on first file, Ctrl-click on other files, Shift-click for range).


Compiler Name

The default compiler for the extension you selected is displayed in the Compiler Name box.  If the box is empty, or the wrong compiler is displayed, select the down arrow to the right of the box to display the list of other compiler names.  If the compiler you seek is not listed, type in a descriptive string for it.


Compile Command Lines

After you have made these selections, you are ready to specify or edit the command lines for the Compile and Debug Compile operations.  These are both command lines for your compiler: one intended for use while you are debugging your application and the other for use when producing a production version.

There are several symbolic labels or macros that can be used in the command lines.  These macros allow you to refer to the filename, or portions of the filename within the command without knowing what the filename is in advance.  The actual value used when the command is issued will then depend on the name of the current buffer.  These macros and their meanings are listed in a table at the beginning of the Compile Command Lines group.  The %Q macro is further described in Response File Contents.


Response File Contents

The %Q macro and the Response File Contents edit box work together to automate response files and avoid command line length limits.  The Response File Contents edit box only comes into play if you have used the %Q macro on one or both of your compile command lines.  Note that this macro is case sensitive.  An uppercase Q must be used.

When the %Q macro is used in a compile command, the name of a temporary file is substituted at that position in the command line.  Before execution of the command, the contents of the Response File edit box are written to that temporary file.  An example follows:

cl /c @%Q

An alternate syntax for the %Q macro allows this macro to be the only thing on the command line.  If the character following the %Q is a dot, the three characters following the dot are used as the temporary filenames extension.  For example:

%Q.bat

This syntax will cause the temporary file to be a batch file that can be executed alone.


Capture Output

Each command line has a corresponding "Capture Output" check box.  When this box is checked, output is automatically redirected to the Error file.  The Error file is specified in the Configuration dialog on the Project menu.  If the compiler you are using has some other provision for capturing output, you may want to disable automatic output capture.

In most cases, you will want to see the output of the command on the screen as well as capturing it in a file.  Codewright provides you with two methods of doing this: VDOS and FTEE. Once VDOS in enabled, Capture Output support is automatic.  If you choose to use FTEE instead, just place the FTEE command at the beginning of the command line.  If your Codewright directory is not on the path, ensure the file FTEE.EXE is in a directory that is.

FTEE is similar to the several TEE programs you will find in the public domain and on many Unix systems.  Like a plumbing or electrical "Tee" connector, these programs allow you to direct output to two places at once.  The difference between FTEE and other TEE programs is that it allows the command to execute normally whenever you do not redirect output to a file.  Other TEE programs typically quit with an error message under these circumstances.


Window Display and Execution

The groups labeled Window Display and Execution permit you to specify some aspects of the execution of the command lines you have entered.  Commands executed through VDOS are unaffected by these settings.  The Window Display group lets you specify what state the execution window will be given.  The Execution group lets you specify whether the task will run in the foreground or as a background task.

You can modify the behavior of foreground and background tasks by changing the PIF files COMFGNML.PIF (foreground) and COMBGNML.PIF (background).  The Windows NT version of Codewright does not use these files, however.  Windows users can find these files in the Codewright home directory.


Template Setup
Template Setup Dialog

When you press the Template Setup button, you receive a dialog that allows you to examine and redefine language templates associated with the selected extension.  If Codewright cannot find templates for the selected extension, you will receive an error when you press this button.  In this case, check to see that any support DLLs for your language have been loaded (PRG.DLL, SC.DLL, BAS.DLL...).  If that is not the problem, you may be using an extension that is not recognized by Codewright.  Use ExtAlias to identify the extension to Codewright.  See "Associating Extensions with a Language".

Abbreviations and Keyword Abbreviations

Editing Definitions

See also:

Language Construct Templates


Abbreviations and Keyword Abbreviations

Down the left side of this dialog is a list in alphabetical order of all the abbreviations that trigger template expansion for the current file type.  These are your trigger words or keywords.  To see the definition associated with any of these abbreviations, select it from the list.


Editing Definitions

When you select an abbreviation from the list, you will see the template definition in the Keyword Abbreviations box and the string it inserts in the Template box.  In addition to the abbreviation you selected, you will see any other keywords that trigger this template in the Keyword Abbreviations box.  They are separated by vertical bars, the "or" operator for template keywords.  You may edit the contents of this box, or the contents of the Template edit box.

Keep in mind that the template edit box is not a sophisticated editor and does not support the Codewright keymap you are used to.  It is a convenience that lets you avoid editing the configuration file directly.

The special characters and macros that are available for use in Codewright templates are described in the "Template Macros".


Brace_style Setup
Brace-style Setup

The Indentation Setup button is a C/C++ specific setup.  It allows you to select the location of braces in language templates.  This button will be disabled when you select other extensions.


Playback Strings

The Playback Strings Dialog provides a convenient way to record, identify, and reuse a series of recorded keystrokes.  This dialog allows you to record and playback nine different keystroke recordings.  Each recording may be given a description, to assist you in remembering what it does. You can also use it to see and manipulate which keystrokes are currently associated with the Playback menu entry and its shortcut key ([F8], or [Ctrl][X][e] in Epsilon).

Playback String

The Playback string in the bottom group of the dialog is the keystring that is played back when you select Playback from the Key menu, or use the shortcut key, usually [F8], for that feature.  If the keystroke recording is short, the entire keystring is displayed in this group, next to the Keystring: label.  Longer keystrings will appear truncated to fit the dialog box, though there is virtually no limit to the length of a keystroke recording.

The buttons marked Copy To Storage and Copy From Storage allow you to swap in and out other keystroke recordings, which may then also be played back using [F8].  The Copy To Storage button copies the keystring associated with the Playback key to the selected storage location, numbered 1 through 9.  The Copy From Storage button copies the keystring from the selected storage location for use with the Playback key, when next it is used.

Keystring Storage

There are nine entries in the keystring storage area.  Each entry consists of a radio button, a status indicator, and a place for a description.  The radio button indicates which of the nine recordings you are working with or operating on.  The status indicator is the letter "U" for unused, until a recording is stored in that location.  A letter "R" in this position indicates that a recording is stored there.

The contents of the currently selected recording is displayed directly below the nine storage entries.  On longer recordings, only the first portion of the keystring is displayed.  Directly below the keystring is the description edit box, for entering or modifying the description of the currently selected recording.

Using Playback Strings


Using Playback Strings

You begin using playback strings by making one or more keystroke recordings.  To begin a recording you can press [F7] ([Ctrl][X][(] in the Epsilon emulation), select Record from the Key menu, or if you are already in the Playback strings dialog just click on the record button.  Next, start typing the keystrokes you want to record.

When your recording is complete, you have similar choices for turning recording off:  You can press [F7] again ([Ctrl][X][)] in the Epsilon emulation), select Record from the Key menu (which should have a check mark next to it this time, indicating a recording in progress), or reactivate the dialog and select the Stop button.  Regardless of which of the nine storage areas is selected, your recording appears in the Playback String area at the bottom of the dialog.

The Play button is for playing a keystroke directly from its storage location.  It therefore remains disabled until there is a playback string at the currently selected location.  To do this, you copy the current recording to one of the nine storage areas by selecting the desired location's radio button and then pressing the Copy To Storage button.

You may enter a description of the playback string now or at a later time.  Until you enter a description, the contents of the playback string is used as a description.

The Copy From Storage key allows you to select an existing recording at any of the nine storage locations and copy it to the current playback string, where it can be used more conveniently.  It is then available by pressing  [F8] or by selecting Playback from the Key menu.

Limitations and Alternatives

Unfortunately, you cannot record keystrokes entered into Windows dialog boxes.  A partial solution for this is to use command line prompting instead of dialog boxes whenever possible (see the System Options dialog on the Options menu).  A more complete solution is to use the Windows Recorder accessory to do your keystroke recording.  For most purposes, the record and playback capability provided by Codewright  will be sufficient.


Window Menu

Next	Change to the next window in the list.

Previous	Change to the previous window in the list.

Create	Create a new window and make it current.

Close	Close the current window.

Properties...	View/change current window properties.

Colors...	Choose window colors.

Font...	Choose window font.

Select...	Select a window from the list.

Output	Display output window.

Close All	Close all windows.

Tile	Arrange windows in tiled configuration.

Tile vertically	Arrange windows in vert. tiled configuration.

Cascade	Arrange windows in cascaded configuration.

Arrange Icons	Reposition window icons.

The Window menu lists operations that are commonly performed on windows.  As you open more windows, the window titles are added to the bottom of the Window menu.  The name with the check mark beside it in the left hand column is the current window.  You may make another window current merely by selecting it from this menu list.


Window Source and Destinations

Several dialogs related to window settings allow you to view settings for any window and apply then to any group of windows.  This is what the Source and Destination groups in theses dialogs are for.  The dialogs employing this scheme include:

•	Window Settings (current or model)

•	Window Colors

•	Window Font

The Source and Destination groups let you determine which windows settings are viewed and which buffers receive the settings after you modify them.  In the Source group, you can elect to view the Current Window settings, the Model Window settings, or use the Select Window button to view the settings for any currently defined window.

Similarly, the destination group allows you to assign the viewed settings to the Current Window, the Model Window, All User Windows (does not include the Model Window), or a selected, arbitrary list of windows.  The Selected Windows button allows you to define an arbitrary list of windows.  This is an extended selection listbox.

•


Window Properties
Window Properties Dialog

Scope

Several dialogs related to Window Properties allow you to view settings for any window and apply them to any group of windows.  This is what the Source and Destination groups in theses dialogs are for.  The dialogs employing this scheme include:

•	Window Properties

•	Window Colors

•	Window Font

The Source and Destination groups let you determine which windows settings are viewed and which windows receive the settings after you modify them.  In the Source group, you can elect to view the Window Properties for the Current or Model Window, or use the Select Window button to view the settings for any currently defined window.

Similarly, the destination group allows you to assign the viewed settings to the Current Window, the Model Window, All User Windows (does not include the Model Window), or a selected, arbitrary list of windows.  The Selected Windows button allows you to define an arbitrary list of windows.  This is an extended selection listbox.

Static Information

This dialog contains several items that cannot be changed from the Settings dialog.  The Attached Buffer is the name of the buffer to which the window is attached.  The Buffer Keymap and the Window Keymap are also identified here.  There usually is no Buffer Keymap or Window Keymap defined.  It is useful, however, to be aware of this possibility, since the Window Keymap would replace the System keymap, and the Buffer Keymap overlays whichever other keymap is in effect.

System Flags

The System Flags group lists the status of the Windows SysFlags in a series of check boxes.  These flags are described in the table below:

Window SysFlags

Name	Status when checked
Line Numbers	Line numbers are displayed in the window.
Horizontal Scroll Bar	The window has a horizontal scroll bar.
Vertical Scroll Bar	The window has a vertical scroll bar.
Short Title	Only the filename is used in the window's caption (no path).
Maximized	The window is Zoomed.
Minimized	The window is an Icon.
System Window

This tells if the window is identified for system use.  You cannot modify this setting.

Visibles

The Visibles group lets you specify characters to use as visual representations of otherwise invisible aspects of a buffer.  These numbers are specified by their numeric value, either in decimal or hexadecimal notation.  These Visibles are described in the table following:

Character	Purpose
End Of Line	A visual representation of the end of the buffer line.
Virtual Spaces	A visual representation of space beyond the end of the line and also tab expansion.
Tabs	A visual representation of tab characters.
Spaces	A visual representation of space characters.
Virtual Lines	Represents lines beyond the end of the buffer.
End Of File	Represents the end of the buffer or file.
User Flags

The User Flags is a double word value that is made available for the user to define and modify, much as Codewright uses Window SysFlags.  There is no predefined meaning or use for this variable.

Horizontal Scroll Increment

The Horizontal scroll increment sets how many columns Codewright will scroll at a time when it needs to scroll horizontally.  Scrolling in larger increments can reduce the frequency of scrolling, and thereby avoid one of the slower aspects of working under Windows.

Left Margin Space

This value determines the distance between the left edge of a buffer and the window border.  This margin may be used for making line selections.  Clicking with the mouse in this space selects the line to the right.  You can tell that the mouse is in the left margin when the left pointing arrow or I-beam cursor changes to a right pointing arrow.  Clicking in the left margin and dragging the mouse up or down selects a series of lines -- even if the mouse happens to stray from the margin.

This measurement is either in pixels or percentage of a character cell.

Right Margin Mark

The right margin mark is a vertical line that is displayed at a buffer column you specify.  When word wrap is enabled, Codewright uses this mark to know when to wrap text to the next line.  Even if you are not using word wrap, you may want to set this mark as a reminder of where 80 columns is.  This can be helpful in meeting company guidelines for line length.  Setting this value to zero turns off the right margin mark.

Font Information

The Settings dialog shows what font is in use in the current window, and its height and width.  These settings may be modified through the Font dialog.


The Colors Dialog
Colors Dialog

You can use this dialog to set the colors used in the current window as well as the default colors for windows.

Scope

The Colors dialog begins with settings that determine the scope of the changes made when you exit this dialog.  The settings you are viewing are those for the current window.  When you are through modifying the settings, however, you may apply the new settings to the current window, the model window, all user-defined windows, or any combination of these.

Assigning a Color

First, you select the screen element for which you wish to set a color.  For example, the Text item sets the foreground and background colors used to display buffer text; the Selection item sets the colors used for the currently selected block of text.

After selecting the item you want to color, click on one of the sixteen colors in the row of foreground colors and one in the row of background colors.  The box below these two rows containing the phrase "Sample Text" shows you what this combination looks like.  Keep selecting combinations till you come up with one you like.  Select other screen elements whose colors you wish to change and repeat the process.  When you are done changing colors, press or click OK.

Advanced users may want to redefine one or all of the sixteen choices displayed here.  The method for doing this is described in the Color Guide.


The Font Dialog
Font Dialog

This dialog lets you choose which font to use in the current window.  You will note that only fixed width fonts are listed in the Font selection box.  You may select a proportional font when printing, but not for purposes of displaying text.

In addition to selecting a font, you can select a style for that font.  Most fonts will offer normal, bold italic and bold italic renditions of the font.

After selecting the desired font style, you will see the available sizes listed in the Size box.  You may type in sizes that are not listed, and the closest available size will be used.  In the case of  TrueType fonts, few or no font sizes may be listed.  TrueType fonts are scaled to whatever  size you specify.

You may notice that the fonts available vary depending on what other programs have been run, or are running.  For example, many word processors add fonts while they are running, and Windows itself creates a smaller version of the terminal font whenever DOS is running in a window.

Note:	For those who like lots of lines on the screen, the smaller the font height, the more lines you will have.  If you don't have scaleable fonts, try selecting  the Terminal font, size 8, and then change the height setting to six.  This will result in just under one hundred lines when maximized in 1024x768 display mode.


Select Window Dialog

This dialog lets you select a window from the list of user-defined windows.  To do this, double-click on the desired window name or select it from the list and press enter or OK.

Settings Button

You may also use this dialog to access the Window Properties dialog to change the settings of any window listed.  Select the window whose settings you wish to view from the list and press the Settings button.


Key Menu

Select Keymap

Bindings...	View/change key assignments.

Record	Record a keystroke sequence.

Playback	Playback a recorded keystroke sequence.

Playback Strings...	Manage record/playback strings.


Select Keymap Dialog

This dialog lets you select from any of the standard Codewright keymaps, or to specify one of your own design.  These keymaps are listed below:

CUA

The Common User Access keymap uses a Windows-style command set.  The basic commands in this keymap are essentially the same as those used in Notepad and Word for Windows.

Brief

This keymap emultates the Brief editor of DOS programming fame.  Because of its reliance on the [Alt] key, this keymap is not particularly well suited for use in Windows.

Epsilon

The Epsilon keymap provides an emulation of the Epsilon DOS editor from Lugaru.  There are notable similarities to EMACS in this keymap.

vi

This keymap provides an emulation of the vi editor found on Unix systems.

Other

If you have another Codewright keymap that you wrote yourself or downloaded from our bulletin board, select the last radio button.  Then type the name of the DLL, less the .DLL extension into the edit box.


Key Bindings Dialog

The Key Bindings dialog is a multi-purpose dialog for

•	querying what keystroke invokes a certain function (key query),

•	querying what function is assigned to a certain keystroke (function query),

•	making assignments to the current keymap (key assignment).

Note:	This dialog box is not intended for designing a new keymap.  Creating a new keymap or making a large number of changes to an existing one is best done through DLL source code.  This dialog saves key assignments to your configuration file.  A large configuration file can increase the startup time of Codewright.


Key Query

The Key Query begins with the name of the Codewright function for which you want to discover the keystroke.

Locate the Function combo box at the bottom center of the dialog box.  Selecting the down arrow to the right of the box will allow you to view a long, alphabetical listing of functions.  Find the function that you want the assignment for on the list, and select it.  Then select the Binding button immediately to the right of the Functions box.

After a short pause, a string containing the keystroke assigned to that function will appear in the combo box directly above the Functions box, the Key Sequence box.  If the function is assigned to more than one keystroke, other keystrokes may be viewed by selecting the down arrow button to the right of the keystroke string box.  If the Key Sequence box remains empty, there is no keystroke assigned to the function.

If you do not get the result you expected, keep in mind that the function you chose may be called indirectly by some other keystroke.  For example, the function BufUndo is not normally assigned to a key.  The function Undo calls BufUndo and then prints the informative message "undone".  This is the function that is usually assigned to a key.

The string in the Key Sequence box is a representation of the keystroke required to invoke the function in question.


Function Query

To make a function query, you begin by entering a keystring into the Key Sequence combo box.

There are three ways the keystring can be entered into the Key box:

•	by selecting the Key box and typing in the keystring.

•	by recording keystrokes you type from the keyboard or

•	by recording keystrokes typed with the mouse on the on-screen keyboard.

The first method is the only method that requires an understanding of the format used in keystrings to represent keystrokes in strings.  As simple to use as keystrings are, the other methods of entering keystrings are even easier for most users to employ.  This first method is the only way available to make assignments to mouse keys and mouse key combinations, however.

The second method is as simple as pressing the Record button in the lower left of the dialog and typing the keystroke that you want to investigate.  As you type, you will see the corresponding keystring appear in the Key Sequence box.  If you make a mistake, don't press backspace -- that keystroke will be recorded, too.  Instead, press the New button just above the Record button.

The third method begins, like the second, with pressing on the Record button.  You then click on the "keys" of the on-screen keyboard, instead of your actual keyboard.  When you click on the [Ctrl], [Alt] or [Shift] key, Codewright waits for you to press another key, and then enters a keystroke in the Key box just as if the two keys were pressed at the same time.

Whichever method you use to get the keystring into the Key Sequence box, once it is there, you select the Binding button to obtain your results.  Make sure that you use the Binding button directly to the right of the Key Sequence box.  The other Binding button will clear your keystroke.  After selecting the correct binding button, the function assigned to this keystroke, if any, will appear in the Functions combo box, directly below the Key Sequence box.


Key Assignment

To assign a function to a keystroke, you also need to place a keystring in the Key Sequence box.  To do this, you can use any of the three methods used in the function query.  Instead of selecting the Binding button, you then select the Functions combo box.  Locate the function you want to assign to the keystroke on the function list and select it.  If the function requires any parameters, enter them in the box at this time, following the function name.  Separate the parameters from each other and from the function name with either spaces or commas.

You are now ready to indicate that this is the assignment you want by pressing the Next button.  You may then return to step 1 to make further assignments, or save the results.

Saving the Results

When you are ready, you may select one of the action buttons across the bottom of the dialog box to install the assignment or assignments you just made.  You can make the assignment temporarily -- just for the current session -- by selecting Update keymap.  You might prefer to save the assignment in the configuration file for continued use.  In the latter case, the [KmapAssign] section of  your configuration file will be updated.

Finding Functions

How do you find the functions to assign to keys if you don't know their names?  If there is a command that does what you want, it is easiest to use the Function Query feature of the Key Bindings dialog to discover what function is assigned to the keystroke command.  You can then assign it to another key, if you wish.

Another place you can look is in the "Function Summary by Category" chapter of the Codewright Programmer's Reference.  The names of the functions in the Codewright API are listed in that chapter, grouped by topic.  Pick out a likely sounding function name and then look it up.


Utility Menu

API Command...	Execute an API command.

Make	Run make utility.

Rebuild	Run rebuild utility.

Compile	Run compiler/assembler.

Compile(debug)	Run compiler/assembler using debugging options

Debug	Run debugger.

Execute	Run a command

Alternate 1	Run alternate 1 command line

Alternate 2	Run alternate 2 command line

Check-in...	Put a workfile into an archive.

Check-out...	Get a workfile from an archive.

Filter...	Process text through a filter.

Shell...	Run a command shell.

Shell Command...	Invoke a Windows/DOS application.

Menu Editor...	View/change menu structure.

Ribbon Editor...	View/change button bar configuration.

History Editor...	View/change internal history lists.

Most of the items on the Utility menu are not very useful until a command line has been defined for that item.  Among these are the Make, Compile, Compile(debug), Alternate 1, Alternate 2, Debugger, Execute and Check-in/Check-out.  The compiler commands are File-type specific and may be accessed through the Buffer Menu.  The Check-in/Check-out commands, have their own setup.  The rest of the commands are set through the Project Configuration dialog.


API Command Dialog

The API Command Dialog lets you execute commands from the Codewright API and supporting functions.  In addition, you can execute any user defined commands that have been properly exported.  It lists commands previously issued when you select the down arrow to the right of the edit box.  If no arrow appears at that location, there are no previous commands available.  This dialog is identical to the Command Key prompt when pop-up prompting (as opposed to status line prompting) is enabled.

See also:  Command Key


History Lists Editor

The History Editor dialog allows you to view the various history lists maintained by Codewright, and to delete unwanted entries.  History lists are responses to prompts and edit box entries that are saved so that you can recall and reuse later.  Each list or section of history is given a name with which responses are associated.

Section List Box

The Section list box shows the names of the various history lists maintained by Codewright.  The first step in using this dialog is to select a section name from the Section list box.  The contents of that list is then displayed in the Item list box.

Item List Box

The Item list box show the entries in the selected history section.  If the selected section is PROJECTS, for example, the item list box contains the names of recently opened projects.  This is the same list that appears at the bottom of the Projects menu.  Similarly, FILELIST contains the list of filenames that appear at the bottom of the File menu (when enabled), and SEARCH is a list of search strings used.

Remove Button

The only editing action currently allowed is to delete an entry from its section.  To do this, just select the entry you want to delete, and press the Remove button.  Note that removing a filename from a history list does not delete or otherwise change the files status on disk.


Check in Dialog
Check-in Dialog

This dialog box allows you to store a new revision of a file or files in an archive.  You select the files you wish to operate on from a list box in the same manner you select files from the File Open dialog.  There are a series of other controls that determine what files are displayed in the file selection list box.  If the file to be checked in is contained in a buffer, the buffer should be written to disk before the check-in is initiated.

Project

If you have one or more Version Control Projects defined, the Project combo box will appear.  These projects are limited to purposes of version control, and are not generally as useful as Codewright (Development) Projects.  If you have defined a Codewright Project, that project is assumed to be your version control project, and this combo box will not apear.  The project combo box allows you to select a version control project from a list of those defined.  You view this list by selecting the down arrow at the right of the box.  Version control projects may be defined in your configuration file.

Version control projects are created by placing the ProjectAddFile command in your configuration file (CWRIGHT.INI).  To disable version control projects so that you can obtain full use of your Codewright Project, locate the lines in your CWRIGHT.INI file containing the ProjectAddFile command and place a semicolon at the beginning of these lines.  See also Defining Version Control Projects.

Writable files only

This check box allows you to limit the files listed by excluding files that are Read-Only.  Some version control systems give a Read-Only attribute to files that were checked out for "browse only".  Since it is unlikely that such files would be Read-Only if they had been changed, Read-Only files do not normally need to be checked-in.

Project files only

This check box limits the list of files to those associated with the project selected in the Project combo box.

Change Dir

The Change Directory button enables you to change the working directory.  This allows the check-in to operate on the files in that directory.

Working Files and Version Archives

While the Working Files listbox is always displayed, the Version Archives listbox is not initially displayed, since it is usually not required.  You may display both listboxes by pressing the Archives button.

These listboxes display the files from the project or working directory on which you may choose to operate.  You can select a single file by clicking on it, select additional files with Control-Click, and a range of files with Shift-Click.  The Clear button removes any selection, so that you can start over.  The Invert button reverses the selections -- those that are selected become unselected; those that are not selected become selected.  If you want to select all of the files, just press Invert at the outset.

Comment String

The Comment String box is a multi-line edit control.  The contents of this box are only used if the Check-in command contains the Response File macro ( %Q ).  You can use this edit box to supply descriptions of the changes in a revision, or, when creating a new archive, to describe the role of the file in the project.  The description is used for each file you select for check-in.  If %Q is in the Check-in command, but the edit box is empty, you will be prompted for a descriptive string for each file being checked in.

To determine if your check-in command contains the %Q macro, press the Setup button.  For more information about the %Q response file macro, see Version Control Setup.


Check out Dialog
Check-out Dialog

This dialog box allows you to retrieve a revision of a file or files from an archive.  You select the files you wish to operate on from a list box in the same manner you select files from the File Open dialog.

Project

If you have one or more Version Control Projects defined, the Project combo box will appear.  These projects are limited to purposes of version control, and are not generally as useful as Codewright (Development) Projects.  If you have defined a Codewright Project, that project is assumed to be your version control project, and this combo box will not apear.  The project combo box allows you to select a version control project from a list of those defined.  You view this list by selecting the down arrow at the right of the box.  Version control projects may be defined in your configuration file.

Version control projects are created by placing the ProjectAddFile command in your configuration file (CWRIGHT.INI).  To disable version control projects so that you can obtain full use of your Codewright Project, locate the lines in your CWRIGHT.INI file containing the ProjectAddFile command and place a semicolon at the beginning of these lines.  See also Defining Version Control Projects.

Check-out With Lock

There are two different commands that can be issued for Check-out.  This check box selects between the two.  This is primarily useful with version control systems that support locking.  Locking is a method of signaling that one individual is modifying the file and preventing others from accidentally modifying the same file.  The two Check-out commands are defined through the Setup dialog.

Edit Working File

Checking this box indicates that you want to edit the file after checking it out of your version control system.  When this box is checked, the file or files will be loaded into Codewright for editing.

Change Dir

The Change Directory button enables you to change the working directory.  This allows the check-in to operate on the files in that directory.

Working Files and Version Archives

These list boxes display the files from the project or working directory on which you may choose to operate.  Many version control systems may be configured to delete the working file after a new revision has been checked-in.  In this case, the file will not appear in the directory listing.  If you have defined the file as part of a project, you can select that project from the Project list, and then select the file from the Working File list.  If the file is not part of a defined project or in a directory listing, just type the name into the Working Files edit box.

When selecting files that are in the directory listing, select a single file by clicking on it, select additional files with Control-Click, and a range of files with Shift-Click.  The Clear button removes any selection, so that you can start over.  The Invert button reverses the selections -- those that are selected become unselected; those that are not selected become selected.  If you want to select all of the files, just press Invert at the outset.


Version Control Setup

The Version Control Setup dialog is where you define the three commands for use in the Check-in/Check-out dialog boxes.  Each of these three commands has a default value, that may make version control setup unnecessary for some users.  These default values are detailed in the description of each command, below.

Command Component Key

The first portion of this dialog is the Command Component Key.  This is a listing of macros available for use in the three commands you define in this dialog box.  These macros are expanded just before the command is executed.  The expansion is a portion of the Workfile name or the project name, if any.  Here is a list of the command component macros and their expansion:

Component	Description

%%	Percent sign   Since component macros begin with a percent sign, you must use two percent signs to represent a literal % in your command.

%b	Basename  The complete workfile name, less the extension.

%d	Directory  The directory component of the workfile.  This component has no filename and no drive component.  It also has no trailing backslash.

%e	Extension  The extension of the workfile.  This component begins with a dot ( . ) unless the extension is null.

%n	Project name  The name of the project, if one has been defined and selected.  Otherwise, this macro expands to a null string.

%p	Path  The path component of the workfile.  This component has no filename and no drive component.  It has a trailing backslash.

%r	Root  The filename of the workfile, less the extension.

%v	Volume  The drive component of the workfile, a letter and a colon.

%x	Project Path  The path component of the project file currently in use (usually indicates the project directory).

%y	Project Root  The base filename of the project file currently in use.

%Q	Response File.  The name of a temporary response file containing the text from the Comment String (check-in) or Additional Options (check-out) edit box.  This macro is case sensitive.  You must use an upper case Q.  See the default check-in command for an example of its use.

Though not given in the key that appears in this dialog, you may also refer to components of the archive name.  To do this, you use the same component macro, except that you specify the associated letter in upper case.  For example, you may reference the extension of the archive using the %E macro, rather than %e, which refers to the workfile's extension.

Note that no use is made of the archive name, even if one is selected from the Version Archives list box.  The Version Archives list box serves only a reference, showing what workfile is associated with which archive, when a project has been defined.  If you find some use for the archive name, you may modify the CheckIn and CheckOut functions in the supplied source code to make use of it.  You will find these functions in the file VCS.C in Codewright's CWSTART directory.

Check in

Check out

Check out with Lock


Check In

The Check-in command is the command line needed to check in a file to your version control system or archive.  If possible, this command should work whether an archive currently exists for the workfile or if one must be created.  If more than one file is selected or check-in, this command is executed once for each of the files to be stored.

If the check-in command is empty the following command will be used:

put %b%e

The initial check-in command defined in your CWRIGHT.INI file is as follows:

put -t@%Q -m@%Q %b%e

The additional flags and %Q macro enables you to supply a description of the changes or of the archive itself, when creating a new archive, to the check-in command.  This is done through prompting, or through the Comment String edit box in the check-in dialog.  The text is placed in a temporary response file.  The command could also look like this:

put @%Q

Use this form if you want to supply all parameters to the command, including filenames, from within the temporary response file the %Q macro creates.

Here are a pair of alternate commands for the RCS and TLIB version control systems, respectively:

ci %b%e

tlib u %b%e


Check Out

The Check-out command is the command line to execute when you are checking out a revision from a version control system or other archive.  If your version control system offers revision locking, this command should not lock the revision.  This is the command to be used when you are browsing or compiling the file, rather than planning to change it.

If you don't define a command for check-out, the following command will be used:

get %b%e

If you wish to be prompted for additional options, or to supply them through the Additional Options edit box in the Check-out dialog, use a command like the one below:

get @%Q %b%e

Here are a pair of alternate commands for the RCS and TLIB version control systems, respectively:

co %b%e

tlib e %b%e


Check Out with Lock

The Check-out With Locking command is the command line to execute when checking out a revision for the purpose of changing it.  If your version control system does not offer revision locking, you may either make this command the same as the Check-out command or leave it blank.

If you don't define a command for Check-out with locking, the following command will be used:

get -l %b%e

If you wish to be prompted for additional options, or to supply them through the Additional Options edit box in the Check-out dialog, use a command like the one below:

get -l @%Q %b%e

Here are a pair of alternate commands for the RCS and TLIB version control systems, respectively:

co -l %b%e

tlib e %b%e

Note that the TLIB example does not lock the revision.

See also Defining Version Control Projects


Filter Dialog

The Filter dialog lets you perform an external operation on the current buffer or the selected portion of  it.  For example, you may order a group of lines numerically or alphabetically by filtering that part of the buffer through the DOS Sort command.  The selected portion of the buffer is replaced by the output from the external command.  If no selection is defined within the buffer, the entire buffer is processed through the filter.

The command used as a filter, in this manner, must take its input from the standard input device, and send its output to the standard output device.  The browse button permits locating the desired filter on disk.


Shell Command Dialog

The Shell Command dialog differs from invoking a command shell in that it just executes the one command and then immediately returns.  Another way in which it differs is that you can invoke another Windows application in this method.


Menu Editor Dialog

The Menu Editor dialog allows you to change, delete and add menus and menu items interactively.  It is located on the Utility menu.  (At least, before you use the Menu Editor that is where it is.)

Menus

Menus are the top-most selections on the Menu bar.  They contain items and submenus.  You begin your modification of the menu by selecting a menu from the list on the left.

•	Up/Down  These buttons allow you to change the position of the menu relative to other menus.  Up and down refer to the position in the listbox.  Up moves the selected menu to the left on the menu bar, while Down moves the menu to the right.

•	Delete  The Delete button deletes the selected menu.  You could delete all menus, if you wish.  You would then find that you are unable to add them back interactively, once you leave this dialog.  (You couldn't get the dialog back.)  If the worst happens, you can restore the original menu by editing Codewright's configuration file, CWRIGHT.INI.  Locate the [Menu] section of the file and rename the section, or delete all lines under that section heading.

•	Add or Change Menu Dialog

Menu Items and Submenus

Menu items and Submenus are the entries listed on a menu.  After selecting a menu, the items on that menu will appear in the list box on the right.  Any submenus on the menu will also be listed in order, preceded by a + sign.  You may then select a menu item or submenu from the list on which to operate.

•	Up/Down  These buttons allow you to change the position of the item or submenu on the menu.  You may also move separator lines with these buttons.

•	Add Popup  This button brings up a dialog similar to the Add Menu dialog.  Enter a name for the submenu, an ID number, a help message, and any functions to initialize the submenu.

•	Delete  The Delete button deletes the selected item.  You could delete all items in a menu, if you wish.  You can also delete separators with this button.

•	Add Separator  The Add Separator button allows you to add a separator line at the selected position within the menu.

•	Add List  There are five lists which may be added to the bottom of a menu:  recent files, scrap buffers, edit buffers, recent projects, and windows.  If you are using One-buffer-per-window mode, the list of edit buffers is not available.  (See System Options dialog)  Each of these lists may only appear on one menu.  Therefore, you must first delete a list from a menu before you can add it to another.  This button is disabled if there are no unassigned lists.

Operating on Submenus

To view or operate on a submenu, you must double click with the mouse on the submenu (marked with a plus) in the list on the right.  The submenu then moves to the list on the left and is marked with a minus sign.  You may then operate on it as you would a menu, adding items, moving and deleting items as you desire.

Whenever you are through operating on a submenu, you may move it back to the list on the right by double clicking on the name again.  The minus sign will change back to a plus when it arrives in the list on the right.

This system allows you to have any level of nesting of submenus that you like.  Just keep adding them on the right and moving them over to the left.


Add or Change Menu Dialog

The Add Menu dialog lets you add a menu to Codewright's menu bar.  You must provide:

•	a name for the menu to appear on the menu bar

•	a unique ID number of your own choosing

•	a helpful message to display when the menu is selected,

•	optionally, one or more functions to initialize the menu (disables or check marks menu items as necessary).

The Change Menu Attributes dialog is like the Add Menu dialog, except that the attributes for the selected menu are displayed for editing.  You cannot change the ID of a menu.

This dialog is also used for adding Pop-up menus (submenus).


Add or Change Menu Item Dialog

The Add Item dialog lets you add an item to one of Codewright's menus.  You must provide:

•	a name for the item to appear on the menu (Menu item text),

•	a unique ID number (ID),

•	a helpful message to display when the menu is selected (Help string),

•	and a function to execute when that item is selected (Handler function).

If there is a short-cut keystroke that performs the same function, you may enter that keystroke for display on the menu (Key string).

The operation of this button depend on whether you have selected a submenu or a normal menu item.  If you have selected a normal menu item, the Change Item Attributes dialog is like the Add Item dialog, except that the attributes for the selected item are displayed for editing.  If you have selected a submenu, the dialog is like the Add Popup dialog.


Ribbon Assignments Dialog

The Ribbon Editor selection on the utility menu allows you to change the buttons on the Tool Ribbon and SideBar, and change the functions they perform.  This is a lot like changing key assignments.

Selected Button Group

The Selected Button group allows you to select one of the currently defined buttons and see the settings associated with it.  You select a button by scrolling through the graphical list box.  As you do this, you will see the ribbon ID and button type assigned to this button.  You cannot change the associations in this group.

Change Button

Use the Change button when you want to change the appearance of the button.  In this dialog, you can scroll through the buttons available and select another button.  As supplied, the buttons are all bitmaps, but you may change the button type to use an icon or to contain text.

You may select the source of your list of buttons from either the Codewright main executable, or any DLL loaded into Codewright.  You do this through the Library combo box.

Additional Libraries

You may create and use additional libraries of resources to use on the Tool Ribbon and SideBar.  The  CWBUTTON.DLL is supplied for this purpose.  If it is not in the list of libraries for you to choose from, you can add it by placing a line in the [Editor] section of your configuration file, CWRIGHT.INI:

[Editor]

LibPreload=CWBUTTON.DLL

You can also either add to and recompile CWBUTTON.DLL, or copy it and create your own DLL.  The C source code is provided.

New Button Dialog


New Button Dialog

If you want to add another button to the ribbon,  select the New button.  You may select whether the new button displays a bitmap, icon, or text to indicate its purpose.  In addition, you may specify if the button is placed on the Tool Ribbon (Top) or SideBar (Side).  You may choose a library from which to select a resource, as when you are changing the button.

When you return to the Ribbon Assignments dialog, you will see that Codewright has selected a location for the new button, as well as an ID number.  You are then ready to make an assignment to your new button.

Add or Change Ribbon Assignments Dialog


Add or Change Ribbon Assignments Dialog

There are 5 things you can change or assign to a new button:

•	position

•	size

•	button text

•	function to execute (binding)

•	helpful message (descriptive text)

Of these, size and button text are only meaningful if you have selected a text button.  Other types of buttons use the size of the resource, and have no text placed on them.

Position

The position is the X and Y coordinates relative to the upper left corner of the Codewright client area, which includes the Tool Ribbon and SideBar.

Size

Use the width and height fields to specify the size of a text button.  Make sure that it is large enough to contain the intended text.

Button Text

The button text is the label that goes directly on a text button.  This field is not used for bitmap and icon buttons.

Function Binding

This field contains the function call to be executed when the button is pressed.  This function call must conform to the rules of LibFunctionExec, or calling it through the API Command Key.

Descriptive Text

This is the string that is displayed on the status line when the mouse cursor passes over the button.  It is used to describe the action of the button.

Accept Button

Press the Accept button when you have made the desired assignments to the selected button.


Options Menu

System Options...	View/change system settings.

System Colors...	View/change default colors.

System Font...	View/change default font.

Auto-save Options...	View/change auto-save parameters.

State File Options...	View/change state file options.

Show Button Bar	Display button bar.

Show Tool Box	Display button toolbox.

Show Side Bar	Control Side Bar appearance

Comment Settings...	View/change border strings

Save Settings...	Save default settings.

File List Sorting	View/change the sorting mode for file lists


System Options Dialog

The System Options Dialog lets you change the Global SysFlags and other system-wide variables that affect the operation of Codewright.

Global Backup Spec.

The global backup specification dictates how the name of a backup file is derived from the original filename.  This is the most common method of specifying the name of the backup file, though backup specifications may be set for each buffer.  The backup specification can indicate the directory in which backups are made, the extension used, or the backup specification may used to transform the filename into another name.

The default backup specification, "%b.bak" dictates that the backup file be made in the same directory as the original file, but bearing the extension .BAK.  The backup specification is only used when backups are enabled.  The subject of backup files and backup specifications is discussed in the "Backup Files and Directories" section of General Operations chapter of the Codewright User's Guide.

Main Window

System Flag Options

Advanced System Flags

Coloring

Key Repeat

User Flags


Main Window

The Main Window group lets you set the condition of Codewright's program window.

•	Maximize main window  When this button is selected, the Codewright program window takes up the entire screen.

•	Normal main window  When this button is selected, the Codewright program window is set to its normal size and position.

•	Minimize main window  When this button is selected, the Codewright program window is reduced to an icon.


System Flag Options

The system flags or Global SysFlags control a variety of system-wide Codewright features.

•	Use Windows Clipboard  When this box is checked, Codewright uses the Windows Clipboard as a staging area for cuts, copies and pastes.  This is useful when doing cuts and pastes between programs.  When this box is not checked, Codewright uses one of its private Scrap buffers for cuts, copies and pastes.  This gives Codewright greater flexibility and security.

•	Retain directory changes (Change dir)  When this box is checked, the File Open, and most other dialogs that allow browsing for a file, will remember the last directory selected, by default.  This means that the "Change dir" check box in these dialogs will be initially checked.  When this box is not checked, the default action for these dialogs is to return to the current directory each time they are called.  This means that "Change dir" check box  is not initially checked.

•	Auto Update .INI file  When this box is checked, the changes you make to option settings are automatically written to the configuration file.  When it is not checked, option changes are only in effect for the current session, unless you explicitly save the settings with the Save Settings dialog.

•	Use Command line prompt  When this box is checked, most prompting that comes from Codewright will be done on Codewright's status line.  When this box is not checked, this prompting is done through pop-up windows.

•	Use I-beam text cursor  This option allows you to select between an arrow or an I-beam cursor, when the mouse is over the text area of a window.  In the CUA mode, the I-beam cursor is the default, while the arrow cursor is the default in the BRIEF emulation.

•	Show Button Bar  This check box turns off and on the display of the button bar or ribbon in Codewright's main window.

•	Show Toolbox  This check box turns off and on the display of Codewright's floating Toolbox.

•	Show File List  When this box is checked, Codewright maintains a list of up to 9 recently viewed files at the end of the File menu.  The most recently loaded file appears at the top of the list.  These files may be reloaded by selecting the filename from the list.

•	Show Side Bar  This check box enables the display of Codewright's Side Bar for push-button access to additional tools.


Advanced System Flags

The advanced system options are displayed when the Advanced button is pressed.  They are as follows:

•	One buffer per window (New window)  When this box is checked, buffers and their windows are treated as a unit, much like other CUA-style editors.  A new window is created each time you load a buffer or buffers.  In addition, deleting either a buffer or a window will close the corresponding window or buffer, respectively.  The exception to this is when you delete a window and there is another window viewing the same buffer. In that case, only the window is closed.

When this box is not checked, loading a new buffer will cause it to be assigned to the current window, displacing the buffer previously assigned to that window.  In this instance, the only time a new window is created automatically is if there is no window defined.

The New Window check box on the File Open dialog and similar dialogs receive their initial value from this flag.  Subsequently, the two operate independently, however.

•	Hide cursor while typing When this box is checked, Codewright will hide the mouse cursor when you begin to enter text into a buffer.  The cursor will not reappear until you move the mouse again.  In this way, the mouse cursor will not interfere with reading the text.  When the box is not checked, the mouse cursor remains visible during typing.

•	Allow alt-key combinations  When this box is checked, you can make key assignments that employ the [Alt] key, but you will be unable to use such key combinations to access the menu items.  You will instead have to click on the menus with the mouse or first press and release the [Alt] key, and then type the menu letter.  When this box is not checked, the [Alt] key is reserved as a system key, and may not be used in key assignments.

•	Allow undo past save  This check box allows you to select between an undo stack that is reinitialized whenever you save the buffer, or one that is maintained continuously for the duration of the edit session.  Since the save itself cannot be undone, many users prefer not to be able to accidentally undo past that point.  Other users want the fullest undo capability available.

•	Create window using mouse  When this box is checked, you may use the mouse to create new windows.  You do this by pointing to any part of Codewright's client area that is not currently occupied by a window and clicking left and dragging to any other part of the client area.

•	Typing replaces selection  Whether you are using the CUA keymap or not, you may have typing replace the selection by checking this box.  This means that typing or pasting deletes the contents of the selection rather than being added at the cursor position.

•	Leave mouse selections open  This checkbox determines whether selections made with the mouse are left open or closed.  An open selection has one end tied to the cursor position and expands or contracts as the cursor moves.  Both ends of a closed selection are defined, allowing the cursor to move independent of the selection.  If you think you will want to scroll a selection off-screen, use closed selections.

•	Suppress reload prompt  If another process alters a file that you have loaded into Codewright, it will prompt you, asking if you wish to reload the file.  If you wish to always reload the file without being prompted, check this box.

•	Create directories as needed  It is possible to specify a directory in a file specification that does not exist.  When Codewright attempts to write the file, it cannot do so without creating the directories involved.  If these occasions are normally typos, you won't want Codewright to create the directories.  If you really mean what you say, checking this box will cause Codewright to create directories as necessary.

•	Allow button moves  You may allow buttons to be relocated within the SideBar and Tool Ribbon by checking this box.  You may then press [Ctrl][Shift] and drag the button using the left mouse button.

•	Auto-save button moves  Checking this box indicates that you don't want to be prompted for saving the new location each time you move a button with the mouse.  When checked, the new location is automatically saved.

•	Suppress button descriptions  When this check box is checked, the descriptive message that normally appears on the status line when the mouse passes over a button on the Tool Ribbon or Tool Box does not appear.

•	Save file on loss of focus  You may wish to have files saved whenever you switch away from Codewright to another application.  If so, check this box.  This adds an extra level of security when you are testing programs that might deprive you of the opportunity to save later.

•	Allow non-DOS filenames  When this box is checked, Codewright does no checking to ensure that filenames comply with Dos's 8 character root and 3 character extension requirement.


Coloring

These settings affect the performance of Codewright's Language ChromaCoding.

•	Delayed  This check box determines whether a newly loaded file will be colored and then displayed (not delayed), or displayed and then colored (delayed).  If you are working on long files, you will probably want to have them displayed and then colored.  If you find seeing the file being colored distracting, you will not want to check this box.

•	Frequency  This value sets the number of times that the ChromaCoding update function is called before it does a complete update.  This allows you to control how quickly or how intrusively colors are updated.  The initial default for the update delay is 20 calls.  To make ChromaCoding update faster, lower this number.  To be interrupted by updates less often, increase this number.

•	Comment search limit  One of the most time consuming aspects of Language ChromaCoding is determining whether or not you are typing in a comment.  The Comment search limit determines how far forward or back Codewright will look before assuming that the current position is not in a comment, if no comment is found.  The smaller the value, the faster Codewright willl color.  The default value is 200 lines.  Set this to the length of the longest comment you would normally encounter.


Key Repeat

The key repeat group allows you to adjust the Codewright's own "typematic" delay and repeat rate.  The delay represents the interval between when a key is pressed and when the key begins repeating.  The repeat rate is also an interval, so the lower the number, the more key repeats will occur each second.  Higher numbers slow the repeat rate.


User Flags

The user flags or Global User SysFlags are provided to store information not native to Codewright.  Codewright does not modify this value or use it in any way.  User written programs may use it for whatever purpose you see fit.  It can readily be checked and modified here for convenience.


System Colors Dialog

This dialog appears and operates the same as the colors dialog under the Window menu, except that it operates on global objects instead of the current window.  For this reason the selections available in the "Screen Element" box are different and less numerous.  The elements you may color include:

Object Name	Description

Command Line	The color used on the status line, the bottom line of Codewright's program window.

Error messages	The color given to error messages.

Messages	The color given to informative messages.

Warning messages	The color given to warning messages.


System Font Dialog

This dialog allows you to select the Windows stock font that is used on the Codewright status line, also called the command line.  Variable pitch fonts will generally allow longer messages to be displayed on the status line.  OEM fonts may vary from installation to installation.  Try the different fonts to determine which is best for you.


Auto save Options Dialog
Auto-save Options Dialog

The Auto-save Dialog gives you control over all aspects of the auto-save feature.  This feature periodically saves changes to disk to avoid the substantial loss of data that could otherwise result from a power outage or other minor catastrophe.  Normally these saves are performed using a filename other than the original.  This allows you to determine when you are ready to overwrite the original file.  You can have the auto-save feature make saves on the basis of elapsed time, or on the basis of keyboard inactivity, or both.

Auto-save Directory

Enter here the name of the directory, if you want auto-save files created in a central location.  If you don't name a directory for auto-save files, they will be created in the same directory as the original file.

The filename used will be the same as that used on the original file, except that the third character of the extension will be a tilde (~).  If the extension is less than two characters, it will be filled with underscores ( _ ).  For example the file FOO.C would be auto-saved under the name FOO.C_~.  On the other hand, a file whose name already has three characters, such as FOO.PAS, is auto-saved under the name FOO.PA~.  In this case the S was replaced with a tilde.  Finally, a file with no extension, such as README, would be saved with the extension .__~  (e.g. README.__~).

Idle time

This entry sets the interval of inactivity that will trigger an auto save.  Inactivity means no key has been pressed and no button has been pushed.  Enter here the number of seconds of inactivity you want to allow.  A value of  zero has the effect of turning this kind of auto-save off.

Force time

This entry sets the absolute time interval that is allowed to pass without saving to disk.  This type of auto-save is performed without regard to keyboard or other activity.  Enter the number of minutes you want to allow before auto-save interrupts editing to save the file.  A value of  zero has the effect of turning this kind of auto-save off.

Auto-save enable

None of the entries in this dialog box mean anything unless auto-save has been enabled.  A check mark in this box enables the auto-save feature.

Overwrite auto-save files

If Auto-save detects a file of the same name as it wants to use, it checks to see if it is a file that it created during the current session.  If it is not, Codewright prompts you before overwriting.  The file may not be an auto-save file at all, or it may be an auto-save file from a session that terminated abnormally.  In these cases, you may wish to retain the file.  On the downside, if you are not present to respond to the prompt, the file will not be auto-saved.  This checkbox allows you to specify that the file be overwritten regardless of its origin without prompting.


State File Options Dialog

Save state information between sessions

This checkbox enables saving information about Codewright's state at exit, so that state can be restored when Codewright is invoked again.  If this box is not checked, the other settings in this dialog are ineffective.

Save Window State

You may choose to restore only the window that was current when Codewright exited, or you may choose to restore every edit window that was defined at that time.  If you are using "One buffer per window" mode, selecting All Windows will cause all buffers to be restored also.  One buffer per window mode is the CUA default, and is set through the System Options dialog.

Save Buffer State

You may also choose to restore only the buffer that was current when Codewright exited, or to restore all edit buffers open at the time of exit.  If you are using "One buffer per window" mode, and have elected to restore all window, all buffers will be restored anyway.  This is primarily useful in Brief emulation.

Save Marks

Codewright supports a number of kinds of marks, and you may elect to save these between sessions by category.  The categories available are:

•	Local Bookmarks  These bookmarks mark locations in a buffer and are not known outside of the current buffer.

•	Global Bookmarks  These bookmarks allso mark locations in the buffer, but are known globally and may be used for jumping between buffers.

•	Position Marks  These marks are saved as a stack to enable returning to locations in the reverse order they are saved.  These are global in scope.

•	Selections  These are the stream, column or line blocks local to each buffer.


Comment Settings
Comment Settings Dialog

The Comment Settings dialog allows you to set the parameters for the Comment and Comment Box menu items.  You will find these menu items in the Block Processing submenu on the Edit menu.  These items draw a user-defined border around selected text.  The border may be a comment block or any decorative characters you care to use.

The left side of the border is placed at the beginning of the line, or, in the case of a column selection, in the first column of the selection.  The right side of the border is placed at the first tab stop to the right of the longest line in the selection.

There are two types of comments or borders available, though you can define the characters used for each.  One is a purely functional left and right border, which may serve as the beginning and end of a comment.  This type is referred to as a Comment border and corresponds to the Comment menu item.

The other type of comment or border adds a decorative top and bottom line.  This type of comment is called a Comment With Border and corresponds to the Comment Box menu item.  It is usually used for an eye-catching multi-line comment.  It is designed to be used primarily with line selections, but you may also find it useful for column or stream selections.

This feature makes it convenient to write the text of a comment employing word wrap, and then to add the comment characters later.

Comment With Border

The Comment With Border group contains the settings used by the CommentWithBorder function.

Drawing Elements

The Drawing Elements for the Comment With Border are a series of edit boxes that are arranged much as they will appear in the buffer.  Each of the drawing elements is typically one or two characters, but it may be more if desired.

The top left and bottom right are usually used for the multi-line begin and end comment characters.  The top and bottom fill string is repeated to fill the space between the left and right drawing elements on the top and bottom.  The side strings are used on each line of the selection between the top and bottom.

Insert Top Border

The Insert Top Border for Mid-line Selection checkbox controls the way the top line is handled if the selection begins at some place other than the beginning of a line.  This includes column and stream selections.  When this box is checked, a new line is inserted at the beginning of the selection and the top left, right, and fill strings are used to draw a border on the new line.  If the box is not checked, the top line of the border is omitted under these circumstances.

Comment Without Border

The Comment Without Border group contains the settings used by the Comment function.

Drawing Elements

The Drawing Elements in the Comment Without Border group contains edit boxes for strings that are placed at the beginning and end of each line or line segment in the selection.

On Exit Dialog

The On Exiting Dialog group controls what happens when you close the dialog.  If there is a selection defined, you may elect to apply a comment to it or a comment with top and bottom borders.  If there is no selection or you do not wish to apply a comment to it, select Save Settings Only.  This setting is not saved between sessions.


Save Settings Dialog

If you always make changes to options and settings by using the supplied dialog boxes, you should have little need for this dialog.  The supplied dialogs automatically update the CWRIGHT.INI file to save the changes you make for the next session, unless you have modified the System Options to prevent this.

If, on the other hand, you make changes to settings through the Command Key or have disabled "Update .INI" in your System Options, you will need to save options manually.  This dialog provides you will a means of doing this.

Save All

The Save All option saves every setting it is reasonable to save, without regard to whether or not that setting was already the default value.  Sometimes it is useful to select this option, just to see what is written to the .INI file as a result.  You can then fiddle with the settings by editing the .INI file.  Keep in mind, however, that a long configuration file can make Codewright take longer to load.

Note that if you "Save all" with no buffers or windows open, there will be no useful window and buffer settings to save.  These settings will be reinitialized.

Save Individual Components

If you know specifically what setting you or a program you ran modified, just select the appropriate check box or check boxes from this group.  Note that search options are saved in the state file (CWRIGHT.PST).


File Sort Options Dialog
File List Sorting Options Dialog

This dialog lets you control how lists of filenames are presented in various Codewright dialogs.

Display Mode

This group of radio buttons gives you a choice of displaying the filenames as fully qualified paths, or with the path element split off from the filename and enclosed in square brackets.  The latter method ensures that the filename will be visible in the list box, whereas the standard method may allow the filename to be pushed out of view to the right by a long path.

Sort By

This group lets you select how the list of filenames is sorted when it is presented.

•	No Sort  This option lists the files just as they are read from the file or directory.

•	Entire Filename  This is the typical method sorting used by most programs.  The complete filename, including drive and directories, are sorted lexically.

•	Filename Root  This method sorts by the root name of the file only.  Using this method FOO.C and FOO.H will be grouped together, even if they are in different directories.

•	Filename Extension  This method sorts by the file's extension only.  All .C files will be listed together, regardless of directory or root name.

Dialog boxes affected by these settings include all of the extended selection listboxes, except for those based on the File Open common dialog.


Help Menu

Index	Help index.

Commands	Key command contents.

Functions	Codewright API contents

Using Help	How to use Help.

Search for Help on...	Search help index file for keyword

Configure Index File...	Configure help index file


Find Help Dialog
Search for Help on Dialog

The Search for Help On... item on the Help menu enables you to look up a keyword in any file on your help file list.  To set up a help file list, use the Configure Index File... item on this menu.

Help Keyword

This is where you enter the keyword to look for.  When you start typing, Codewright automatically presents a list of all the help files that contain the word you are typing.  The list appears in the listbox at the bottom of the dialog.

Exact Match

Check this box if you want to type in the exact keyword to find.  If this box is not checked, then all keywords that begin with the letters that you type are considered matches.

Browse

If this box is checked, the dialog will remain after you have closed the WinHelp window.  Then you will be able find help for another topic easily.  If this box is not checked, the dialog will disappear when WinHelp exits, so that you can go back to your work.

Found in these Help FilesSelect One:

As you type into the Help Keyword field, keywords appear in this listbox that match whatever is in that field at the moment.  The more you type, the more exact the match.  The keyword appears on the left column.  A brief description of the help file appears on the right.


Help Editor Dialog
Configure Index File Dialog

The Configure Index File item on the Help menu enables you to add help files to the list of help files known to Codewright.

This dialog contains three displays: the help file index, the keyword list, and the help search path.  The help file index, or Helpfiles list, shows all the help files that Codewright knows about.  If the Show Keywords checkbox is checked, then that display will show all the keywords defined in the selected help file.  The third display shows the path that Codewright uses to find the help files.

How the Help System Works

Codewright uses index (.IDX) files to match keywords to help files.  The index files follow Microsofts help file index format.  Usually, only one IDX file, CWRIGHT.IDX, is used.  You can use the Add button to add more help files to CWRIGHT.IDX or to any additional .IDX files you may use.

Configuring the Help Index

The buttons near the Helpfiles list give you control over the files that Codewright uses to provide online help.

•	Edit...  This button brings up a dialog that allows you to modify the help file name and its description.  The description appears in the Search For Help On... dialog when you invoke online help.  The file name here is the name that Codewright will use to find the help file.

•	Add...  Add a helpfile to the list.  This button presents a dialog which lets you select a Windows Help File to add to the help file index.

•	Remove.  Remove a helpfile from the list.  The selected helpfile is deleted from the list without further prompting.

•	Export...  Convert a help file to Help Information File (.HIF) format.  Codewright uses Help Index Files (.IDX) to look up keywords in help files.  Each .IDX file can contain a master index for many help files.  This button extracts the keyword list for the selected help file, and saves this list in HIF format.  It brings up a dialog which lets you specify a destination for the converted file.  Since the HIF file is plain text, you can add entries to it using any text editor.

•	Move Up.  This button moves the currently selected help file one place closer to the top of the list.  Files are searched in the order listed, so its best to place most frequently used files at the top.

•	Move Down.  This button moves the currently selected help file one place closer to the bottom of the list.  Help files not frequently used should be placed at the bottom.

Setting Up the Help Search Path

When you ask for online help, Codewright looks in its IDX file for the keyword under the cursor.  The IDX file entry tells Codewright which help file lists that keyword.  Codewright then looks for the help file on the path specified in the Help Search Path display.  This path is a list of directories that contain help files.  The directories may be separated with commas or spaces.

Loading an Alternative IDX File

You can keep more than one IDX file on your system.  Use the Load button to get a dialog that will let you browse for an IDX file to load.

Save and Close

When you press the Save button, all the changes that you have made in this dialog will be saved to the current IDX file.  The Close button will exit the dialog.  If you have not saved your settings, they will be discarded without prompting.


Model Buffer
Model Buffer is a pseudo buffer from which all buffers inherit their attributes at the time they are created.


Model Window
Model Window is a pseudo window from which all windows inherit their attributes at the time they are created.


Configuration Categories Detail

There are a series of checkboxes common to the Options dialog on the Project menu and the Save Settings dialog on the Options menu.  The following list will help you relate those checkboxes to the contents of your configuration file or project file:

Checkbox Option	Related Configuration Function

Buffer Defaults	SysSetDefault=DEFAULT_BUFFER

Window Defaults	SysSetDefault=DEFAULT_WINDOW

Default Window Font	_FontDefault

Default Window Colors	SysSetDefault=DEFAULT_COLOR

System Colors	ColorCommandLine
ColorError
ColorMessage
ColorWarning

System Options	BufSetGlobalBackupSpec
ExtCommentSearchLimit
ExtDelayedColoring
KeyDelay
KeyRepeat

Auto-save Options	Autosave
AutosaveDir

Compiler Settings	BrowseSetFile
CompilerAddBuild
CompilerAssign
CompilerNewExt
TagSetFile
CompilerAdd

Language Options	ExtColors
ExtColorsAssoc
ExtIndentEnable
ExtIndentEnableAssoc

Version Control Setup	CheckInSetCmd
CheckOutSetCmd

Filename Filters	FilterAdd
FilterDeleteList

Clipboard/Scrap Options	ClipboardEnableSepStr
ClipboardEnableTermStr
ClipboardSetSepStr
ClipboardSetTermStr
ScrapSetCount

State File Options	StateSetMarkLevel


Defining Version Control Projects

Version control projects are defined in the configuration file using the ProjectAddFile function.  You will find this most useful if you are not using a project file for development.  If you are using a Project file, it may be unnecessary to create a version control project definition, since your project files can be assumed to be your version control project members.  If you place a ProjectAddFile definition in your configuration file, however, that will take precedence over your Project file, if you are using one.

Place any version control project definitions in the Version Control section of your Codewright configuration file, CWRIGHT.INI.  We will use the project FOOBAR to demonstrate how a project is defined.  What follows in the pertinent part of the configuration file, used to define the FOOBAR project:

[VersionControl]

ProjectAddFile='foobar','foobar.rc','foobar.rcv'

ProjectAddFile='foobar','foobar.c','foobar.c_v'

ProjectAddFile='foobar','foobarin.c','foobarin.c_v'

Each of these lines under the Version Control heading adds a single file to a project definition.  Following the equal sign, in each instance, are three string parameters.  The first parameter is the name of the project.  This string is stored in a case sensitive manner; the foobar project is not the same as the FooBar project.

The second parameter is the name of the workfile or source code file.  The third parameter is the archive name associated with the specified workfile.  If you wish, you may specify an empty string for the archive name, or omit the parameter completely.

If you have twenty or more files in a version control project, you may find this method of defining a project to be too tedious.  In this case, you may find one of the alternate syntaxes for the ProjectAddFile command to be useful.  The two most simple and useful alternate syntaxes allow obtaining the names of archives and workfiles from a file, or through a wildcard specification.

Obtaining Names from a File

You may already have the names of the workfiles in your version control project listed in a file.  You may be using such files as response files or command files that you supply to certain utilities, including version control systems.  Let us imagine that you have a file containing the names FOOBAR.RC, FOOBAR.C, and FOOBARIN.C.  The file itself is named FOOBAR.  The names must be listed one filename per line.  In this case, you could define the same three files used in the earlier example as part of the foobar version control project with the following syntax:

ProjectAddFile='foobar','@foobar'

Note that the command only has two parameters following the equal sign.  The first parameter, as before, is the name of the version control project.  The second, however, is the name of the file containing the filenames of the members of this project.  The filename is preceded by an at sign ( @ ) to signal that the members are listed in the filename that follows.  The first character in the second parameter must be @.

Specifying Members with Wildcards

The wildcard method of specifying members is similar to the file method.  For this alternate syntax, the second parameter to the ProjectAddFile command is a wildcard specification.  The wildcard may specify a path, if desired.  If no path is named, the current directory will be assumed.  Files matching the wildcard specification at the time the Check-in or Check-out dialog is invoked will be considered members of the project.  Likewise, changing the directory from the dialog will change the members of the project.  Here is an example using this syntax:

ProjectAddFile='foobar','c:\src\foobar*.*'

For further examples of these and other syntaxes, see ProjectAddFile.


Auto_indent
Auto-indent

The auto-indent feature anticipates that when you enter a new line, you will want it to be indented to the same level as the line you typed above it.  When you are indenting blocks to add readability to your code, this saves you from continually having to indent new lines yourself.

You will find the auto-indent settings in the Buffer Settings dialogs.  This may be en extension-specific setting.

Selecting a Mode

To satisfy all tastes, Codewright's auto-indent feature comes in five flavors.  The difference between these flavors or modes is in how they fill the indented part of the line.  There is also the Seek Indent option which potentially influences the operation of auto-indent regardless of mode.

When Seek Indent is off, Codewright looks only as far as the preceding line to determine the amount of indent.  If the preceding line is empty, the cursor is placed in column one of the new line.  When Seek Indent is on, auto-indent does not stop at the preceding line if it is empty.  Instead, it seeks backwards until it finds a line that is not empty and copies the whitespace from that line.

Here is a listing of the modes available

Mode Name	Description

Virtual	Positions the cursor at the indented position on new lines, but does not fill until the line is edited.

Spaces only fill	Immediately fills the indent with spaces, even if the line receives no further edits.

Tabs/spaces fill	Immediately fills the indent optimally, even if the line receives no further edits.

Tab usage fill	Immediately fills the indent with spaces, or spaces and tabs, depending on whether tab usage is enabled for the buffer.

Duplicate fill	Immediately fills the indent by duplicating exactly the whitespace present on the preceding line.

There is another factor that modifies auto-indent behavior:

The Trim Whitespace on Enter option removes trailing whitespace from the current line when [Enter]  is pressed.  This has the benefit of cleaning up unnecessary whitespace and thereby reducing file size.  However, if Seek Indent is not on, this can have the affect of causing the cursor to return to column 1 when you press [Enter] twice in a row.

To set Trim Whitespace on Enter when using any of the standard keymaps, follow the steps below:

1.	Ensure that Template Expansion is turned off for the current extension.  You will find this setting in the Utility Options dialog.

2.	Using the Key Bindings dialog, query the function assigned to the Enter key.  You should find that the function call ends with a 0 for its parameter.

3.	Change the 0 parameter to a 1.  For Example, if the assignment was "CUA_enter 0" change it to "CUA_enter 1".

4.	Press the Save to file button, and then the quit button.

This feature may be set one way in one buffer and another way in another buffer.  If you to create a default setting, set it in the Model Buffer.  If you want to create different settings for different file types, make the setting in the File Type Properties dialog. All subsequent buffers will have auto-indent enabled.  If you just want to set it for a single buffer, you will find that setting in the Buffer Properties dialog.


C Language Support

Brace MatchingPre-processed View


Brace Matching

Brace matching is a function specific to certain programming languages, primarily C and C++.  Brace matching support in Codewright comes in several forms:

•	Brace Function check the current buffer to see that braces are balanced.  This form is useful for checking syntax.

•	Brace Highlighting highlight the text between a set of braces.  This form is useful in visualizing the scope of the block defined by the braces and indenting blocks.

•	Brace Locating locate the matching brace and move to it, either momentarily or permanently.


Brace Function

There is a function supplied with Codewright that processes the current buffer, looking for unmatched curly braces.  By default, the function will ignore any curly braces it finds in C language comments within the file.  You can specify that all braces within the file are to be matched.

You invoke the Brace function through the API Command Key. This means pressing [F9] in the CUA keymap and [F10] in the BRIEF-compatible keymap.  If you are using another keymap, you may have to select API Command from the Utility menu.

Supposing that you wanted to match all curly braces within a file, you would respond to the Command: prompt in the following manner:

Command: Brace TRUE

If you wished to ignore braces in comments, you just omit the TRUE parameter, or supply FALSE as a parameter instead.

If the function finds an unmatched curly brace, the cursor is positioned on that curly brace.


Brace Highlighting

There are two functions that help you examine or operate on the text between matching curly braces and parentheses.  Both of these functions are available on the Codewright Toolbox and SideBar, but may be readily assigned to keys or other buttons.

The first function is BraceMatchNext, which looks for the next left brace or parenthesis, locates its mate, and then highlights the text between them.  On subsequent calls, this function will find pairs nested within the highlighted set, or a pair following the highlighted set.

The second function is BraceMatch, which operates similarly to BraceMatchNext, except that it searches for a match to the brace at the cursor position.  If the curly brace at the cursor is a left brace or parenthesis, the function searches forward for its mate.  If it is a right curly brace or parenthesis, the function instead searches backward for the mate.   If neither a left nor a right parenthesis or brace is at the cursor position, the function searches forward for the next matching set.

Note:	Since BraceMatch looks at the current cursor position, it is not effective for highlighting a series of blocks in sequence.  On subsequent calls to this function, BraceMatch "finds" the pair that is already highlighted.

If you omit the parameter to this function, it will look for braces only.  Passing a non-zero parameter to either of these two functions will cause it to look for matching parentheses in addition to curly braces.


Brace Locating

The function BraceFind is provided to allow you to locate the brace, parenthesis, or square bracket that is the mate for the one at the cursor position.   It does not create a highlight, but just positions the cursor at the corresponding object.  This function is also available on Codewright's SideBar.

The function also has a "kissing" mode that can be activated by giving the function a TRUE or 1 value as a parameter.  In this mode, the cursor moves to the corresponding object, but only momentarily.  After a brief pause, the cursor returns to its original position.  This provides a method of reassuring yourself that you are closing the block or clause you thought you were.


Pre-processed View

This feature is for C users that find their source files cluttered with #ifdefs.  Now you can see your source code exactly as the compiler will see it, while you are editing it.  Thanks to Selective mode, the whole file is still there, but you don't have to look at the parts that don't apply.  Just create your "defines" in the [Definitions] section of the configuration file, or interactively.  Then use the function Preprocess through the Command Key and soon you'll be seeing just what you need to see.  You can read more about the Preprocess function in the Codewright Programmer's Reference.

Freedom to #ifdef

Creating Definitions


Freedom to #ifdef

If you put more than a couple of #ifdefs and related pre-processor commands into a file, you will probably note that the readability of the file has diminished.  It can sometimes get difficult, if not impossible, to tell what is "going on" in the file.  Don't get us wrong; #ifdefs are very important and useful.  If you aren't making extensive use of these preprocessor commands, maybe you should be.  Now you can use them without any concern for their down side.

If you write applications that are to run on more than one platform, or if you write custom software for more than one company, #ifdefs help you avoid redundant maintenance.  If you maintain separate versions of a file for each of several platforms or customers, you will need to change each version whenever you need to improve the code that is common to all of them.  You can instead maintain different versions in a single file using #ifdefs.  Then, if you have to change the code they share in common, you change it only once.

Previously, you may have been reluctant to use a lot of pre-processor conditionals because of how confused the source code begins to appear.  Whatever time you saved on redundant maintenance could be lost just trying to figure out confusing source code.  Codewright allows you to get the full benefit from the use of pre-processor conditionals by letting you see clearly the code for just what you are working on.


Creating Definitions

You use the functions EvalStrAdd and EvalStrDel to define and undefine the symbols you use in your #ifdefs.  You can place these calls in your configuration file (CWRIGHT.INI), or execute them through the Command Key.  Many times you will want to do a combination of both.

When placing these calls in your configuration file, put them under the heading [Definitions].  As an example of how such a call might appear, a definition of the symbol "MSWINDOWS" is shown below:

[Definitions]

EvalStrAdd=MSWINDOWS, 0, FALSE

The meaning of the three parameters to the right of the equal sign are as follows:

•	MSWINDOWS is the label being created.

•	The value assigned to MSWINDOWS is 0.  The value assigned to the symbol or label is immaterial, so long as you are using only the #ifdef and #ifndef constructs to evaluate this label.

•	FALSE specifies that if the symbol already exists, do not change the value.  We don't care what the value is, so why change it?

If later we want to undefine this symbol through the Command Key, here is how we can do it:

Command: EvalStrDel=MSWINDOWS


Browser Support

The Codewright Browser supports two kinds or browser databases:

•	Microsoft format .BSC databases  These are the databases generated by Microsoft C/C++ 7.0 and later.  (If you need support for an earlier format, contact Premia.)

•	Premia Compiled Tags databases  These are the databases produced by the WTAGS utility shipped with Codewright.  They are given the extension .PTG by convention.

Browser Window

Selecting a Database

Traversing the Tree

Jump to Code

String Search

Query Button

Quick Search

Called By or Calls To

Search After Go To

Filter Toggle Buttons


Browser Window

The Browser is one of the windows available for viewing in the tabbed Output Window.  It appears when you select Browse from the Project menu or when you select the Browse tab on the Output Window.  The Browser is actually two windows side by side with its own tool ribbon at the top.  Tree window appears on the left and the Inspect window appears on the right.

Press [F1] to receive help, press [Esc] at any time to exit the Browser window and return to the current edit window.  To close the Browser window, select Browser again from the Project menu.


Selecting a Database

The first step in using the Browser is to select a database.  If you have previously defined a valid .BSC or .PTG file for the current project, that database is loaded when you select Browse.  You define the database for the project in the Project Directories dialog.  If you have not defined a database, or if you later want to change databases, you may select a database by choosing the File Open button on the Browser ribbon.

Microsoft project makefiles can contain instructions that cause these databases to be created automatically with the BSCMAKE utility as part of a Build or Make.  Therefore, you may find that no action is required from you to create and maintain this database.


Traversing the Tree

Once you have loaded the database, a tree structure will be displayed in the Tree window.  You may traverse this tree from the keyboard by using the arrow keys to move from node to node, and by pressing the [Enter] key to expand or collapse a node.  Using the mouse, you may double-click on a node to expand or collapse it, or click on the expand/collapse button on the browser ribbon.

As you traverse the tree, you will note that information about the selected node appears in the Inspect window to the right.  This window will list information such as where the item is defined and where it is referenced, if this information is in the database.  You may move between the Tree window and the inspect window by either pressing the [Tab] key or clicking in the intended window.

Label Bitmaps

At the beginning of each line of the tree is a bitmapped label identifying to what the information in that branch relates.  A key to these labels is given below:

Bitmap	Description
Database	Root information coming from the database.
Class	Information pertaining to a class.
Funct	Information pertaining to a function.
Macro	A preprocessor macro definition.
Module	Information pertaining to a file or module.
Struct	Information pertaining to a structure.
Type	A type definition.
Var	Information pertaining to a variable.
The first file in the tree list will often be labeled <unknown>.  These are functions and other objects that are referenced, but whose source was not compiled along with the project.  The most common examples of this are the use of functions in the Microsoft Foundation Classes, or other libraries.


Jump to Code

After traversing the tree, you will usually want to go to the corresponding source.  There are two Go to buttons on the Browser Ribbon that allow you to do this.  If you wish to go to the source code represented by the selected tree node (usually a point of definition), you can press the Go To button on the left of the Browser Ribbon.  If you have selected a reference, a calling or called function in the Inspect window, you may wish to press the Go To From Inspect key to go to that reference or function.  Simply pressing the [G] key will always take you to whatever is selected in the Tree window.


String Search

The String Search feature of the browser works like a grep or filter of information in the database.  Use it to filter out extraneous information.  It is one of the most useful features of the browser.

To use the String Search feature, enter a string into the combo box on the browser ribbon.  Unlike some other browsers, the string you enter will not be treated in a case sensitive manner, and a trailing wildcard will be assumed.  That is to say, if you enter "dump", it will match strings like "Dump" and "dumpFile".

Each matching identifier is displayed as a node on the tree.  All other nodes disappear.  You can then traverse this "filtered" tree.


Query Button

The first button to the right of the Search String combo box on the browser ribbon is the Query button. You can initiate a query by pressing the Query button, or by pressing the [Q] key.  Depending on the context, one of six query dialogs will then appear.

Each query dialog has a set of action buttons and filter check boxes.  The filter check boxes apply only to the action buttons that are enclosed in the same group box.  Therefore, the check boxes apply only to the Used By and Uses buttons.  The other action buttons operate independently of the filters.

With all the filters enabled (all the check boxes checked), you may find that you have too much information to sift through to find what you are after.  It is probably best to check the minimum number of boxes that fill your needs.

The six Query Dialogs are as follows:

Button	Purpose
General	General inquiries about the terminals (leaves) on the tree.
Class	OOP class inquiries.
Function	Inquiries about functions.
Friend Class (Fclass)	OOP friend class inquiries.
Database	Inquiries from the root of the database.
Module	Inquiries related to a module.


Quick Search

The Quick Search button on the Browser Ribbon is for use when you are in a normal edit window and want to look up the word at cursor in the browser database.  This step saving device acts the same as if you had typed the word into the String Search combo box and pressed [Enter].


Called By or Calls To

When you have selected a function in the Tree window, you may view either a list of functions that call it, or a list of functions it calls by pressing one of these buttons.


Search After Go To

The Search After Go To button is a toggle that determines what action is taken after jumping to the related source code (Go To).  When this button is depressed, the Browser executes a forward search for the item selected in the Browser window from which it jumped.  This is especially useful if you have modified the source code since the last time the database was generated.  The Browser may still be able to take you directly to the item of interest.


Filter Toggle Buttons

The Filter Toggle buttons allow you to focus in on specific categories of objects by turning filters on and off.  Each of the lettered buttons at the right of the browser ribbon has an on and off position.  When depressed, the button is on, and object associated with that button will show up in the tree.  When the button is out, it is in its off position.  Related objects will not show up in the tree. You can reverse the condition of any of these buttons by clicking on it with the mouse or by pressing the corresponding letter on your keyboard (i.e., [F][T][M][V][G] ).

Below is a list of the buttons and their related objects:

Letter	Filter Objects
F	Function references and definitions.
T	Type references and definitions
M	Preprocessor macro references and definitions.
V	Variable references and definitions.
C	OOP Class references and definitions.
After changing the filter toggle settings, you will find that the new settings do not take effect until you have performed some action, such as opening a branch of the tree.  To see the effect of the filter change on a branch you are already viewing, collapse and re-expand the branch.


Tags Support

Codewright has support for CTags and other Tags generating programs whose databases conform to the standard Tags format.  The file TAGS.C in Codewright's CWSTART subdirectory contains the functions that support this capability, and also defines the standard Tags file format.

In addition, Codewright comes with a built-in Tags database generation capability.  This program produces both a standard Tags database and a compiled database The resulting compiled database may be used with Codewright's Browser in a similar fashion to a browser database.  You can search the database and traverse its contents via a graphical tree.

A standard Tags database adds browse-like capabilities to an editor that knows how to read and use the database.  If you see the name of a function on the screen and need to know what that function does, the supporting functions allow you to jump directly to the file and line at which the function is defined.  You may later return to your original location by changing back to the original buffer.

Codewright is known to be compatible with the PCTags program from Moderne Software and GNU Tags, both of which are available for download from our bulletin board system.

See also:

Tags Setup

Using the Tags Database


Tags Setup

To get Codewright to generate and use a Tags database automatically requires that you follow a few simple steps:

•	Create a project whose members are the files you want to scan for your Tags database.  Begin by selecting New or Open from the Project menu.

•	Define what files will hold your Tags data -- your standard Tags database and your compiled database for use with the Browser.  These are the last two entries on the Directories dialog on the Project menu.  Enter a filename in the Browser database field that employs the .PTG extension rather than .BSC to avoid having the file overwritten by a browser database generator.

•	Select Build Tags from the Project menu.

•	Use the Browser or TagFind function.


Using the Tags Database

To use the standard Tags database, you need to have the function TagFind assigned to a key.  The TagFind function looks at the word at the cursor and tries to find a match for it in the database.  You can assign this function to a key, if it is not already assigned, through the Key Bindings dialog on the  menu.

To use the compiled tags database with the Browser, load the .PTG file with the Browser File Open dialog.  You will then be able to traverse a tree of your tags database, search the database, and be able to do queries for functions and other objects except for friend classes.  You will only be able to query definitions, however.  References are not stored in the Tags database.


Help Indexer

The Codewright Help is a series of utilities and dialogs that extend your control of online help.  With them, you can create and modify a central index of where help topics can be found.  Codewright can then use the index to locate all kinds of help information for you -- even helpfiles that came with the libraries you are using and in-house helpfiles just recently created.

Use as many different helpfiles as you want.  There is virtually no practical limit to how many topics can be stored in the index.

The index stores the topic name, and the name of the helpfile in which the topic is defined.  It does not store the path to the helpfile, however.  Instead, it relies on a Help Path, similar to the DOS PATH for executables, except that it is an .INI file entry rather than an environment variable.  This system has the advantage of allowing you to move files and change directories without the need to reindex.  At most, you just have to change the Help Path.

Microsofts Visual C++ Workbench uses a similar index to access topics  in its own help files.  They, however, provide no way for the user to extend or modify the index.  We have chosen a format compatible with Microsofts  so that you can use Codewright and its utilities to extend the Visual C++ index.  Users of the Codewright Fusion for Visual C++ product will be relying on that index.

Search for Help On Dialog

Configure Help Index File DialogHelpScan Utility

Help Information Files


HelpScan Utility

You will find the HelpScan utility in your Codewright home directory, where you normally find the Codewright executables.  It is a DOS utility that just reads the topics out of a helpfile you name, and prints them to the screen.  You can redirect this output to a file, and presto!  You have a Help Information File (HIF) to use in a Codewright Help Index.  These files are by convention given the extension .HIF.  You supply a description for the helpfile on the command line, along with the name of the file to be scanned.  For a complete listing of the parameters taken by the HelpScan utility, type HELPSCAN at a DOS or NT command prompt.


Help Information Files

A Help Information File is a file which contains the information needed to add a help file to the help index.  The file contains the help file name, the description for the file, and the keywords the help file recognizes.    It is usually not very useful to add keywords to the index that contain special characters or more than one word.  While such keywords are valid, you will not be able to access these topics by placing the cursor on a word an invoking topic help ([Ctrl][F1]).

The format of a help information file is as follows:

<Help File Name>

<Help File Description>

<Keyword 0>

.

.

.

<Keyword n>

The <Help File Name> is the name of the helpfile from which the topics were scanned.  The Description, <Help File Description> is an identifying phrase like Microsoft Foundation Classes or Borland OWL Help.  This description is displayed in the Codewright Help dialogs next to topics and helpfile names.  The maximum length for the description is 64 characters.  Keywords follow the description, one per line, representing the topics available in the helpfile.


Extended Selection Listboxes

Codewright makes use of extended selection listboxes in a number of its dialogs that are available from the Menu Bar.  If you have not previously encountered this type of object, you will find this short introduction to them useful.

In Windows, a listbox is a box which shows a list of items, such as filenames.  A selection listbox is one that permits the user to make a selection from the list.  An extended selection listbox is a listbox that allows you to select more than one item from the list.

The commands for selecting more than one item from the list are the same as those used by the Windows File Manager to select more than one file.   You select a single item, or the first of several items, by highlighting it or clicking on it.  Other individual items may be added to the selection by pressing [Ctrl] while clicking on the item.

In addition, you may select a range of items by pressing [Shift] and clicking on an item at one end of the range.  All of the items between and including the previously selected item and the item you click on will be in the extended selection.  Any other items you may have selected that are outside the range will no longer be selected.

The Codewright dialog boxes that use extended selection listboxes include:

•	Buffer Properties, Select Buffers

•	Compiler Setup

•	File Open

•	File Print

•	File-Type Properties

•	Project Edit

•	Search Multiple Buffers

•	Search Multiple Files

•	Utility Check-in

•	Utility Check-out

•	Window Color, Select Window

•	Window Font, Select Window

•	Window Properties, Select Windows

The Buffer menu lists operations that are commonly performed on buffers.


Tool Ribbon and Tool Box

The Tool Ribbon, also called the "Button Bar", and Tool Box offers quick access to a number of menu operations, as well a few that aren't on the menu.  This describes the action associated with each of the buttons used in the default configuration.  The display of the Button Bar and Tool Box are each controlled through the Options menu.  When a check precedes the name of either of these items on the menu, that item is displayed.  Selecting the item on the menu toggles the display on or off.

Tool Ribbon

Tool Box


Tool Ribbon

New File

The New File button immediately creates a new file buffer named <untitled>.  You may begin editing immediately, but you must rename the buffer when saving.  You cannot receive any extension-specific support such as ChromaCoding or Template expansion until you give the buffer a proper name.

File Open

The File Open button invokes the same dialog you get when you select Open from the File menu.

File Save

The File Save button saves the current buffer to its output file.  If a selection is defined, you will be prompted for a filename in which to save the contents of the selection.

File Print

The File Print button invokes the same dialog you get by selecting Print from the File menu.

Cut

The Cut button deletes the currently defined selection to the clipboard or current scrap area.  If there is no selection defined, the current line is cut.

Copy

The Copy button copies the currently defined selection to the clipboard or current scrap area.  If there is no selection defined, the current line is copied.

Paste

The Paste button inserts the contents of the clipboard or current scrap area at the current cursor location.

Undo

The Undo button reverses the effects of the most recent edit action.

Redo

The Redo button reverses the effects of the immediately preceding Undo.

Search again

The Search Again button invokes a search using the most recently used pattern and parameters without further prompting.

Quick Search

The Quick Search button immediately searches forward for the word found at the cursor.

Next Error

The Next Error button begins or continues a review of errors found in a compiler output file.

Compile

The Compile button performs the same action as selecting Compile from the Utility menu.  It executes a command line associated with the current buffer's extension and compiler designation.

Make

The Make button performs the same action as selecting Make from the Utility menu.  It executes a command line associated with the current project.

Execute

The Execute button performs the same action as selecting Execute from the Utility menu.  It invokes a command line defined for the current project.

Put

The Put button executes the command defined for Check-in on the Utility menu to archive the current buffer.  The current buffer is saved to disk before the Check-in command is executed.

After the operation is completed, Codewright checks to see if the file is still there and, if so, checks the read/write status of the file.  If the file is gone, the buffer is automatically closed.  If the file is Read-Only, the status of the buffer is changed to match.

Get

The Get button executes the command defined for the Check-out w/Lock operation on the Utility menu to replace the current buffer and file with one that has been previously archived.

Note:	Use this button with caution.  Any unsaved edits will be lost, and the existing file will be overwritten without further prompting.

Context Help

The Context Help button uses the word at the cursor and searches for that topic in the Codewright and other known help libraries.


Tool Box

File Find

The File Find button brings up the File Find dialog found on the Search menu.

File Find Next

The File Find Next button loads the next file in the list of files that matched a previous File Find operation.

Check-in

The Check-in button executes the command defined for check-in on the Utility menu to archive the current buffer.  The current buffer is saved to disk before the check-in command is executed.

After the operation is completed, Codewright checks to see if the file is still there and, if so, checks the read/write status of the file.  If the file is gone, the buffer is automatically closed.  If the file is Read-Only, the status of the buffer is changed to match.

Check-out w/Lock

The Check-out w/Lock button executes the command defined for this operation on the Utility menu to replace the current buffer and file with one that has been previously archived.

Note:	Use this button with caution.  Any unsaved edits will be lost, and the existing file will be overwritten without further prompting.

The checked-out version of the file is loaded into the current buffer.

File Grep

The File Grep button brings up the same dialog that is available on the Search menu.

File Grep Next

The File Grep Next button displays the next location in the list of places where a previous File Grep operation found matching text.

File Difference

The File Difference button brings up the same dialog that is available on the File menu.  This dialog is described fully in "File Differencing".

File Merge

The File Merge button brings up the same dialog that is available on the File menu.  This dialog is described fully in "File Merge".

Upper Case

The Upper Case button converts the text in the selection to upper case.  If there is no selection, the current line is converted to upper case.

Lower Case

The Lower Case button converts the text in the selection to lower case.  If there is no selection, the current line is converted to lower case.

Pair Match

The Pair Match button uses the BraceMatch function, described in "C Language Support", to show where sets of parentheses and curly braces are.  The function looks at the left or right parenthesis or curly brace at the cursor position and searches in the appropriate direction for its mate.  When found, it highlights a block encompassing the scope of the pair.

Pair Highlight

The Pair Highlight button can be used to sequentially highlight pairs and nested pairs of parentheses and curly braces.  It uses the BraceMatchNext function to search forward for the next left parenthesis or curly brace.  It then finds that item's mate and highlights the text in between.


SideBar

The Codewright SideBar has two modes (other than off!):  Button mode and Open File mode. You set the mode by selecting the Side Bar item from the Options menu.

Button Mode

Open File Mode


Button Mode

Brace Match

The Brace Match button uses the BraceMatch function to show where sets of parentheses and curly braces are.  The function looks at the left or right parenthesis or curly brace at the cursor position and searches in the appropriate direction for its mate.  When found, it highlights a block encompassing the scope of the pair.

Brace Next

The Brace Next button can be used to sequentially highlight pairs and nested pairs of parentheses and curly braces.  It uses the BraceMatchNext function to search forward for the next left parenthesis or curly brace.  It then finds that item's mate and highlights the text in between.

Brace Locate

The Brace Locate button looks for a brace, parenthesis, or square bracket at the cursor position and then moves the cursor to its mate.

Brace Kiss

The Brace Locate button looks for a brace, parenthesis, or square bracket at the cursor position and then moves the cursor momentarily to its mate.  After a short pause the cursor returns to its original position.

To Upper

The To Upper button converts the text in the selection to upper case.  If there is no selection, the current line is converted to upper case.

To Lower

The To Lower button converts the text in the selection to lower case.  If there is no selection, the current line is converted to lower case.

Slide-in

The Slide-in button indents the selected lines to the next indent level or tab stop.

Slide-out

The Slide-out button unindents the selected lines to the preceding indent level or tab stop.

Slide-in Prompt

The Slide-in Prompt button indents the current selection by a string.  The user is prompted to enter the string.  Handy for commenting out a block.

Slide-out Prompt

The Slide-out Prompt button unindents the selection by removing a specified string from each line.  The user is prompted to enter the string.  If a line does not contain this string, it is left unaltered.  Handy for removing a comment block.

Ribbon Editor

The Ribbon Editor button is the same as selecting the Ribbon Editor entry on the Utility menu.

Menu Editor

The Menu Editor button is the same as selecting the Menu Editor entry on the Utility menu.

Next Buffer

The Next Buffer button makes the next buffer in the list current.

Previous Buffer

The Previous Buffer button makes the previous buffer in the list current.

Entab

The Entab button converts spaces to tabs, where possible, in the current buffer.

Detab

The Detab button converts tabs to spaces in the current buffer.

Spell Check

The Spell Check button is the same as selecting Spell Check from the Edit menu.

Wrap Paragraph

The Wrap Paragraph button causes Codewright to adjust the current paragraph to make it conform to margins.  It does not turn the Word wrap feature on or off.  Use it whenever you wish to wrap a single paragraph.

Selective Display

The Selective Display button puts the current buffer into Selective Display or compact mode.  If you have not defined which lines you wish to selectively view, all lines will disappear.  Run Routines, Grep, Ungrep, or Preprocess before pressing this button.  To return to standard (ASCII) mode, press [Esc].

Hex Mode

The Hex Mode button puts the current buffer into Hex mode.  To return to standard (ASCII) mode, press [Esc].

Module Header

The Module Header button inserts the contents of the file FILE.TPL at the cursor position.  This file contains a module header form for C and C++, which may be edited by the user.

Function Header

The Function Header button inserts the contents of the file FUNC.TPL at the cursor position.  This file contains a function header form for C and C++,  which may be edited by the user.

File Find

The File Find button brings up the File Find dialog found on the Search menu.

File Grep

The File Grep button brings up the same dialog that is available on the Search menu.


Open File Mode

The Open File mode of the SideBar is like having a permanent File Open dialog built into Codewright's main window.  You can use your file filters to list files of a selected type.  You can change drives, navigate the directory structure and see the files in each directory.

Most importantly, loading files with the Open File SideBar is even easier than with the File Open dialog.  Just double-click with the left mouse button on any file you want to open, or select the file and press [Enter].  The file is instantly loaded, and the Open File SideBar is still there, ready to help you load the next file.

Note:	You can change the font used by the Open File SideBar to any of the stock Windows fonts.  This is done with the CWFOpenSetFont function, either interactively, or in your CWRIGHT.INI file.  Values of 10 through 16 are the Windows stock fonts.  Contact tech support for further details, if necessary.


Mouse Commands

Inclusive or Exclusive Selection

Closed Selections

Column Marking

Line Selections

Word Selections

Status Line Actions

Text Drag and Drop

Mouse Copy and Move

Creating Windows with a Mouse

Drag and Drop File Loading

Expand or Collapse

Dragging Ribbon Buttons

Making Mouse Assignments


Inclusive or Exclusive Selection

In all three standard keymaps, you can select text by clicking with the left mouse button and dragging the mouse across the area you want to select.  In the CUA and BRIEF keymaps, the block you define is exclusive, while if you are using the vi keymap, the block is inclusive. That is, in vi the block includes the character at the cursor, but the others do not.


Closed Selections

You may elect to have selections that you make with the mouse be either closed or open when you release the mouse button.  This is one of the System Options that you can set.  Your keymap dictates the initial setting for this option.

A closed selection means you will not change the selection size or shape when you move the cursor.  Selections made with key commands usually are not closed.  In this case, one end of the selection is defined by the cursor position, and it therefore moves with the cursor.  Your keymap may have a command to toggle a mouse selection or other selection open or closed.  You can do this with the [Ctrl][A] command in the BRIEF-compatible keymap, and [Ctrl][ . ] in the CUA keymap, for example.  If you re-open a closed selection after moving the cursor away from the selection, the end of the selection moves to the cursor position, wherever it happens to be.

The distinction between closed and open selections is not meaningful in the CUA keymap unless you have turned on persistent selections.  Otherwise, CUA removes the selection, whether closed or open, whenever you execute an cursor motion command.


Column Marking

Making a column selection with the mouse is just as easy.  Just click and drag with the right mouse button instead of the left.  Column blocks are always inclusive, regardless of which keymap you are using.


Line Selections

There is an adjustable margin between the left edge of the buffer and the window border.  You can use this area for making line selections.  Clicking with the mouse in this space selects the line to the right.  Clicking and dragging selects a series of lines -- even if the mouse happens to stray from the margin.


Word Selections

As with many Windows editors, double clicking on a word makes a selection encompassing that word.  If you continue to hold down the cursor on the second click and drag it around, you can select in units of words.  You may be familiar with this method of selection from one of several word processors.


Status Line Actions

There are a number of functions that you can perform just by clicking with the right mouse button on hotspots on the status line.  These actions are listed below:

Action	Description
Insert/Overtype Toggle	Toggle between insert and overtype mode by clicking-right on the Ins or Ovr designation on the status line.
Read-only/Read-write Toggle	Toggle between Read-only and Read/write status by clicking-right in the box to the left of the line number.  The box may be blank or have a RO designation in it.  This toggles both file and buffer status.
Go to line	Clicking-right in the Line number box brings up the Go to Line dialog.
Next Message	Clicking with the right mouse button in the message box at the left of the status line will cause the program to process the next Build error message.
A related command is the right mouse click on the Ribbon Search combo box. This is on the Tool Ribbon instead of the status line.  A right click here brings up the Search Options dialog.  This allows you to check or change the settings in preparation for using the Ribbon Search or other search mechanism.


Text Drag and Drop

After you have selected a block, you can move or copy the block by dragging the block to its new location.  To move the block, place the mouse cursor in the selection's highlighted area and press the left mouse button.  The cursor will change shape to indicate that a drag and drop operation has commenced.  Continuing to press the mouse button, move the mouse cursor to the intended destination.

The caret (text cursor) follows the mouse cursor, indicating where the destination would be at any given moment.  When the caret is at the intended destination, release the mouse button and the selected text moves there.  You perform a copy operation in the same manner as a move, except that the [Ctrl] key must be pressed when you initiate the operation.

To cancel a drag and drop operation after it has been commenced, move the mouse cursor back over the selection and release the mouse button.  A selection cannot be copied or moved into itself. The operation is then cancelled and the selection removed.

Text drag and drop is not effective for copying or moving text from one window to another.  Use mouse copy and move commands for those operations.

Disabling Drag and Drop


Disabling Drag and Drop

If you are unaccustomed to text drag and drop, you may find it annoying and want to turn it off.  You can do this by editing the key bindings.  Just follow the steps listed below:

1.	From the Options menu, select Keymap Bindings.

2.	In the Key Sequence edit box, enter <mouse_left_down> (less the quotes) and press the binding button immediately to the right of that edit box.  The binding should appear in the Functions edit box below.

3.	Move the cursor into the Functions edit box, and press the End key.  You will see a 0 and a 1 at the end of the key binding.

4.	Change the 1 to a 0.

5.	Press the Save to File button and then the Quit button.

The drag and drop editing feature should now be disabled.


Mouse Copy and Move

In addition to Text Drag and Drop, Codewright supports another method of copying and moving text with the mouse.  You just select the text you want to copy or move, point the mouse at the place you want it to go, and issue the proper mouse command.  The command for moving the selected text is [Ctrl][Rt Click].  The copy command is [Ctrl][Shift][Rt Click].

Sometimes, when you are moving or copying text, the source and destination of the text are too far apart to be viewed in the same window at the same time.  You can still use the mouse move and copy commands, if you find this method more convenient than using either one of Codewright's Scrap buffers or the Windows Clipboard.  This is done by either opening up another window, or scrolling between source and destination.

You might have several sections of text that you want to copy or move, all from the same source location to a single destination.  In this case, viewing the source in one window and the destination in another is the best approach.

If you have just one copy or move operation in mind, you can select the desired text and then scroll to the destination.  The selection will scroll off the screen, but so long as you are using closed selections for mouse operations, it won't change.  A "closed selection" refers to Codewright's ability to separate the selection from the cursor position.  You can select whether selections made with the mouse are open or closed in the System Options dialog.  For more information on selections, see the "Selections" section of the "General Operations" chapter of the Codewright User's Guide.


Creating Windows with a Mouse

It is very easy to create windows of an arbitrary size and position when you are working with a mouse.  This is the quickest way to open up a second window onto your current buffer, so that you can view two different sections of the buffer at the same time.

You do this by pointing to any part of Codewright's client area that is not currently occupied by a window and clicking with the left button and dragging the mouse cursor to any other part of the client area.  Whatever buffer was current previous to creating the window is also made visible in the new window.  This means you will have at least two windows in which to view the current buffer.

If you don't like this use of the left mouse button you can turn it off through the System Options dialog.


Drag and Drop File Loading

The Drag and Drop feature allows you to load files into applications from the Windows File Manager.  This is done by selecting one or more files listed in the File Manager, and then dragging them with the mouse to a minimized application.  When the mouse button is released, the application is restored, and the file or files are loaded or processed.

If you choose to use Codewright regularly in this manner, you may want to add Codewright to the Load= statement in your WIN.INI file.  You can then perform other duties when you first start Windows, such as reading your mail.  When you are ready to work with Codewright you can then use the File Manager to drag and drop the appropriate file onto the Codewright icon.

If you already have files loaded in Codewright, the files you drag and drop onto Codewright will be added to those already being edited.  Whether or not a window is created for each of  the files dropped onto Codewright depends on your settings of the System Options.  If windows are not created, the window that was current will contain the first file of those dropped.


Expand or Collapse

When you are using selective display mode, you can use a mouse for expanding and collapsing sections of text as you might the sections of an outline.  The mouse command used for this is a double click with the right mouse button.  See the description of "Editing Modes" for more information about this use of the mouse.


Dragging Ribbon Buttons

If enabled via your System Options dialog, you can use the mouse to reposition buttons on the Tool Ribbon and SideBar.  The keystroke for doing this is [Ctrl][Shift].  Check the Advanced settings of the System Options dialog on the Options menu to see if this option is enabled.  There is also an option there for automatically updating your configuration file with the new location.


Making Mouse Assignments

You can also make your own assignments to mouse buttons and combinations through the Key Bindings dialog.


Tabbed Output Window

There are a number of windows in Codewright that are not normal edit windows.  They contain such things as output from a compiler or OS command, and require special treatment.  Codewright has a special output window for these purposes.

The Codewright output window may be opened explicitly, by selecting the Output item from the Window menu.  There may be little to view in the output window, however, until you use one of the features that relies on it.  If you use one of these features, the output window will open automatically when needed.

Initially, the window uses the bottom portion of the Codewright client area, and effectively reduces it.  This is convenient when you dont want edit windows overlapping the output window.  You can view the output window and the file you are editing at the same time.

Tear-off Window

The Codewright output window also has another mode, however, in which it operates independently of the Codewright program window.  Note the two small controls in the lower left of the output window.  These have little carats or arrows in them, and are similar to the controls in the upper right of  almost all Windows programs and child windows.

In the upper right these controls would allow you to select between a minimized, maximized and normal (restored) window.  They have similar meaning for the Codewright output window.  To the Codewright output window, however, maximized means the window is functioning independent of the Codewright program window.  When in this mode, you will note that the window also displays the max./min. controls in the upper right, giving you further control over the size and state of the output window.

Normal or restored is the mode in which the output window fits itself to the bottom of Codewrights client window. It will do this automatically even if the Codewright window has changed size while the output window was external.

Select View via Tabs

In a sense, the Codewright output window is several windows of which you can view any one at a time.  At the bottom of the Codewright output window, you will note a series of tabs similar in appearance to those you might see on file folders or dividers.  These allow you to select between compiler output, File Grep, or other output just by clicking on the desired tab.  Predefined tabs include:  Build, File Find, File Grep, Browse, Difference, and VDOS Shell (when loaded).

The File Find, File Grep, Browse and Difference tabs are used in conjunction with the menu items of the same name.  See the description of VDOS for further information about the Build and Shell tabs.


VDOS

VDOS is a command shell that runs in a Codewright edit window.  Its output is automatically captured in a buffer.  This facilitates cut and paste, re-executing commands and more.  It is also faster than starting a DOS session.

When VDOS is activated, it will intercept output from Compile, Make, Rebuild and other project commands, and put it in the Build buffer. Checking the No shell box next to any of these commands will disable the use of VDOS for that command.

You can also directly interact with VDOS through the Shell buffer. You can do most anything you might do in a DOS box using the Shell buffer, but there are a few special keystrokes that are also available:

•	Highlight part of a line and press [Enter] to execute it as a command.

•	Highlight part of a line and press [Ctrl][Enter] to copy the text to the command line at the end of the buffer for editing or use in a command.

•	Press [Shift][Ins] or [Ctrl][C] to copy the current selection to the clipboard.

You may view either the Build or Shell buffer by selecting the appropriate tab on Codewrights tabbed output window.

VDOS has been tested for compatibility in a number of configurations.  It appears to be compatible with Windows for Workgroups V3.11, even with 32 bit disk and file access turned on.  There are a few systems that are not completely compatible with VDOS, however, and it is not initially activated for that reason.

Even when activated, VDOS is not automatically used for Version Control commands.  Although this speeds up the commands considerably, prompting by the version control software may not be visible through VDOS.  To try out VDOS with your version control package, put the following command in the [Editor] section of you CWRIGHT.INI file:

[Editor]

VCSuseVDOS=TRUE

See also:

Activating VDOS


Activating VDOS

To activate VDOS, follow the three steps below:

1.	Load the DLL -- In your CWRIGHT.INI file, find the line in the [LibPreload] section that refers to CWDOSBOX.DLL.  Remove the comment character ( ; ) from the beginning of the line.

2.	Load the VXD device driver --  If you try to use VDOS without installing the VXD, it will offer to modify your SYSTEM.INI file for you.  If you would like to do this yourself, just add a line like the one below to the [386Enh] section of your SYSTEM.INI file:

device=c:\cwright\cwvdos.386

If you installed Codewright into a different directory, be sure to substitute the name of that directory for the one shown above.  After adding this line, you will need to restart Windows for the change to take effect.

3.	Remove references to other redirectors from your command lines.  Programs such as FTEE are not compatible with VDOS.


Editing Modes

Codewright has three different modes in which it can operate.  No, we are not talking about overtype and insert modes here.  The three modes are Standard, Selective  and Hex.

Standard mode is the mode Codewright has in common with most any other editor.  In this mode, the text in a file is displayed, organized into lines and columns.  Almost every value for a byte has some representation that is shown in the window, if it's in the file.

Selective Mode

Hex Mode


Selective Mode

Selective mode differs from standard mode, in that not all of the lines in the file are necessarily shown.  Selective mode is somewhat similar to the outlining mode supported by many word processors, but you have more control over what is shown and what is not.  Using Selective mode can greatly facilitate getting about in a buffer, and even help you to see the "bigger picture".

Selective mode is referred to in certain API function names and in some other places as "Compact" mode.  Some users were confused by that terminology, and we are moving toward the more descriptive phrase, Selective mode.  These are both terms referring to the same thing.

In Selective mode, you might choose to display only the first line of each subroutine.  You might hide all of the lines that are just comments, or elect to show only the comments.  You could have Codewright display just the lines containing a certain function or variable name.  The lines you choose not to display are still there; they just have been elided, or skipped over.

Entering Selective Mode

You can enter Selective mode just by pressing [Ctrl][Shift][C] in the CUA or the BRIEF keymap, or [F3] in the vi emulation.  This is not very useful, however until you have defined some lines as visible and others as invisible.  More likely, you will want to execute one of the following functions through the Command Key to begin using Selective mode:

•	Routines  selects lines in the current buffer that contain C language function definitions.

•	Grep  select lines for display that contain text matching a regular expressions pattern.

•	Ungrep  hides lines that contain text matching a regular expressions pattern.

•	Preprocess  selects lines for display based on C language #defines and other preprocessor directives.

You use these functions to make visible only the lines in the buffer that interest you.  You can then quickly move to the area of the buffer you want to edit, and press [Esc] when you want to restore the invisible lines.  This returns you to Codewright's Standard mode.  When you want to see just the lines you have selected again, there's no need to run Grep or Routines or other function again to select lines.  Just press [Ctrl][Shift][C] in the CUA or the BRIEF keymap, or [F3] in the vi emulation.

In Selective mode, lines are preceded with a small button or icon.  When this button contains a plus sign, it indicates that there is text hidden following that line.  You may view the hidden text by double-clicking on the plus sign or pressing [Shift][Enter] on that line.  The plus sign then turns to a minus sign, to indicate that the section has been expanded to show the "invisible" lines.  Double-click on the minus sign or press [Shift][Enter] again, and the section collapses again.  You can also double click with the right mouse button to expand and collapse hidden text.

Editing in Selective Mode

Selective is not just a viewing mode.  You still have all of your editing capabilities.  You can still mark text with column, line and stream selections; you can do search and replace.  The search and replace operations will only "find" text that is visible.  Selections, however operate on the invisible text as well as the visible.  This calls for a little caution, but keep in mind that you can undo any inadvertent deletions.  Also, text drag and drop is disabled when in Selective mode.


Hex Mode

Hex mode allows you to view and edit a file in hexadecimal values.  You may edit the file by entering values for each byte, or by typing the ASCII equivalent.  Enter Hex mode by pressing [Ctrl][Shift][H] in the CUA or the BRIEF keymap, [F4] in the vi keymap:

Hex mode displays the buffer offset at the left, 16 bytes of hex values in the middle, and their ASCII equivalent to the right.  The 16 hex values are divided into four groups of four.  Each value has two digits: a high nibble and a low nibble.

When you enter the Hex mode, the [Tab] key is redefined.  It may then be used to switch from the Hex values to their ASCII equivalent, and back again.  To return to Standard mode from Hex mode press the [Esc] key.

Note:	If you were in insert mode when you entered Hex editing, you will continue to insert when typing.  If the file or portion of a file you are editing is length-sensitive, you will probably want to toggle to overtype mode.
Most Hex mode editors cannot change the length of a file, and therefore are always in overtype mode.  Codewright can insert characters while in hex mode, and it will be in insert mode if you were in insert mode before entering Hex mode.  At first, it may be difficult to tell what is happening when you insert characters.  Since this can be disconcerting, a short explanation is in order:

When entering text in the ASCII portion of the Hex mode display, insertions appear as they do when you are in normal text mode, except that the text is in a rather narrow column.  When in the Binary portion of the Hex display, each byte is displayed as two hexadecimal numbers, the high nibble on the left and the low nibble on the right.  When you type numbers (0 to F) in these positions, it changes or inserts the character whose numerical equivalent you have typed.

You cannot insert a nibble; you must insert an entire byte.  Therefore, when you type at the high nibble position, both nibbles of the byte are inserted.  The low nibble is initially zero.  The cursor is then positioned over the low nibble.  The next number you type replaces the value of the low nibble.  So, as you type, you will alternately see two nibbles inserted, and one nibble overtyped.  This is normal.


Command Key

The Command Key is a keystroke that calls the LibFunctionExec function.  It provides an interface to Codewright's API while you are running Codewright.

If you find you want to do something in Codewright for which there is neither a key command nor a menu entry, you can probably do it using the Command Key.  If you are using the CUA and vi command set, the Command Key is [F9].  If you are using the BRIEF-compatible command set, the Command Key is [F10], which in BRIEF provides access to the BRIEF interpreter.  In keymaps where there is no such assignment, you can still execute an API Command by selecting API Command from the Utility menu.

When you press the Command Key, a prompt appears on the status line or in a pop-up dialog box, depending on which is enabled:

Command:

You then respond by entering a Codewright API function call, much as you would enter it in Codewright's C source code.  Pressing [Enter]  sends the command off for processing.

Command Completion and History

Using the API

Source Code versus Command Key

Displaying Return Values

Examples of Usage


Command Completion and History

The API Command key and API Command menu selection remember responses you have previously made at the prompt.  Whether the prompt appears in a pop-up dialog or on the status line, you can access this history using the up and down arrow keys.

The up arrow allows you to circulate backward through the list of previous responses, beginning with the most recent.  The down arrow key lets you circulate forward through the list, beginning with the oldest response.

In addition to the command history, you can also use the command completion feature.  This feature is only available when status line prompting is in effect, rather than the pop-up dialog.  You can control which type of prompting is used through the System Options dialog found on the Options menu.

Command completion allows you to enter as much of a command (function name) you can recall and then press the [Tab] key.  In return, you receive a list of commands that begin the same way as your partial command.  You can then select the desired command from that list and it is placed on the prompt line for you.  If you want a complete list of the commands available just press the tab key without entering anything at the prompt.


Using the API

To make much use of the Command Key, you will need to know something about the Codewright API -- at a minimum, you need to know the name of a function you want to execute.  The Codewright Programmer's Reference is the place to learn more about the Codewright API and specific functions, whether you want information about a topic or just want to browse the library of functions.

For many users this is the first step toward truly customizing and extending Codewright.  Once users see how quickly they become comfortable with Codewright's API, they want more.  Soon they start delving into the supplied DLL source code and, before they know it, they've altered the world.  Well, their Codewright world, at least.

If you are trying to avoid learning any more about Codewright's API than you have to, make sure you have checked the various Options dialogs and menu entries to see if what you are trying to do can be done through the menu.  On the other hand, those who are more comfortable issuing commands than making selections from a menu (a la SPF, or even BRIEF), will probably find themselves using the Command Key regularly.


Source Code versus Command Key

Here are the differences between Codewright API function calls issued in source code and through the Command Key:

•	Parameters may be only numeric values and strings.  Parameters may not be variables or nested function calls, when issued through the Command Key. The only exception to this is that the various identifiers/labels listed in the Codewright Programmer's Reference may be substituted for numeric values.  Expressions that employ only bit-wise AND, OR and complement (&, | and !) may also be used.

•	Some API functions cannot be issued through the Command Key.  In particular, functions that return allocated strings and functions that have a variable number of parameters may not be issued through the Command Key.  In addition, functions that require a pointer or handle (other than a pointer to a string) as a parameter cannot be issued.  These functions may only be used in source code.  The description of each affected function clearly notes this limitation.

•	User written functions are available only when registered.  The function LibExport must be used to register a user function, its parameters and return value before it may be called from the Command Key.

•	Parameters may be omitted.  If you omit parameters from a function call issued through the Command Key, Codewright will either fill in default values or the call will fail.  In source code, you have no option but to supply parameters, if you want it to compile.

•	The format permitted and required varies from that of source code.  The requirements on quoting string constants are stringent so that other requirements may be more lax.  Spaces can be used to separate function parameters in place of commas, and spaces, equal signs, or parentheses may be used to separate a function name from its parameters.


Displaying Return Values

It isn't very useful to use one of the Query functions via the Command Key to query Codewright about one thing or another unless you can see a response.  Since virtually all Codewright Query functions respond by returning a value, you'll need to tell Codewright to show you what value a function returns.  You can do this by beginning your command with a question mark.  Here is an example of how such a command might look, just before sending the command off for processing:

Command: ?BufQModifiedCount

When the return type is a numeric value, Codewright displays that number on the status line in both decimal and hexadecimal notation.  If the return type is a pointer to a string, Codewright displays the contents of that string.


Examples of Usage

BufSetHexBinary

BufSetHexBinary()

bufsethexbinary

All three of these examples do the same thing.  They put Codewright in the Hex Editing mode, with the cursor located in the "binary" portion of the display.

MovNextChar( 2 )

Movnextchar 2

Both of these examples advance the cursor position by two characters.

BufEdit( "c:\projecta\debug.c" )

bufEdit "c:\projecta\debug.c"

Either of these commands opens a buffer for C:\PROJECTA\DEBUG.C.

kmapAssign( "<ctrl-a>", "BufSetHexAscii" )

Assigns the function BufSetHexAscii to the keystroke Ctrl-A.

MarkBeginSel( SELECTION_INCLUSIVE )

Begins an inclusive selection, using one of the labels listed in the Codewright Programmer's Reference.


Word Wrap

Codewright offers a simple form of word wrap.  Those who like to use their text editor for writing reports and notes, and also for those who like to use word wrap when entering comments in their code, will welcome this feature.  You toggle this feature on and off by selecting the Word Wrap item on the Edit menu.  When word wrap is enabled this item will be preceded by a check mark.

Word wrap works off of left and right margins.  The right margin is set by either the right margin mark, if you have set it.  You will find the right margin mark on the Window Properties Dialog.  If it has not been set, Codewright uses the right window edge as its margin marker.  (You may also set the right margin with the function WrapSetRightMargin.

The left margin does not have a setting.  Codewright merely looks at the amount of indentation you have created and maintains that same indentation for the entire paragraph.  You may indent the next paragraph using the same, a greater, or a lesser degree of indentation.  Just indent the first line to the desired column and start typing.

Word wrap uses auto-indent to maintain the left margin, so the way the left margin is filled will depend on what setting you have selected for auto indent.  See also Auto-indent.

Paragraph Reformat

Codewright's word wrap feature does not attempt to constantly update the entire paragraph, but rather just the line you are editing.  This means that if you begin typing in the middle of an existing paragraph or change the margins the paragraph will not automatically be reformatted.  You can perform this operation whenever you desire using the WrapParagraph function.

The WrapParagraph function is available through the Tool Ribbon or may be executed through the API Command key.  You may also assign it to a key through the Key Bindings dialog.  For more information about this function refer to the function description in the Codewright Programmer's Reference Manual.


Regular Expressions

Regular Expressions are a powerful notation for describing string matching patterns that has gained wide acceptance.  Codewright  optionally makes available Unix-style Regular Expressions for use in searching.  They have now gained wide acceptance outside the Unix realm.  The relatively small investment of time required to gain a useful knowledge of Regular Expressions can pay you back many times over.

As you begin using Regular Expressions, keep an eye out for new uses.  This will help your use and understanding of Regular Expressions to grow, as well as save you time.

A Regular Expression can be as simple as a single literal character.  Such simple expressions are usually a subexpression of a more complex  regular expression.  In reading the descriptions that follow, an "expression" may mean a single character, a group or class of characters.

Special Characters

Escape Sequences

Matching a Character

Character Classes

Iteration Qualifiers

Beginning and End of Line

Alternation and Grouping

Reference Groups and Replacement Strings

Placing the Cursor

Regex Examples


Special Characters

Regular Expressions give special meaning to certain characters.  Some are operators and some show grouping.  There is also a method of representing non-printing characters, such as a tab, within Regular Expressions.  All other characters just represent themselves, as they would in an ordinary string search.

The characters to which Regular Expressions give special meaning are called metacharacters.  These characters and their meaning are shown below:

Character	Meaning

.	Matches any single character, except a newline

*	Matches any number of occurrences (even zero) of the expression that precedes it.

+	Matches one or more occurrences of the preceding expression.

?	Matches zero or one occurrence of the preceding expression.

[ and ]	Defines the beginning and end of a character class.

( and )	Defines the beginning and end of a group of expressions.  Groups expressions into a larger units, dictates precedence.  Each group is also a Reference Group which may be pasted into a replacement string.

|	Alternation.  Allows matching the expression on the left or on the right of the operator.

$	Matches the end of a line.

^	Two meanings:  Matches the beginning of a line.  Complement operator when the first character in a character class.

\	Used for escaping metacharacters and non-printing characters.

\c	The position in the pattern at which the cursor is placed at the end of a successful search.


Escape Sequences

There are times that you want to use a metacharacter as itself -- without the special meaning that Regular Expressions gives it.  For example, you may wish to match a dollar sign, rather than look for the end of a line.  To match a dollar sign you must escape or quote it.  This is done by preceding the character with a backslash.  This is true of all the metacharacters.  To match a dollar sign, for example, you use \$ in your Regular Expression, rather than just $.

Below is a list of other escape sequences supported by Codewright's Regular Expressions:

Escape	Meaning

\n	Newline (<CR><LF> or <LF>, depending on how it is defined for the buffer)

\t	Tab

\b	Ctrl-H (backspace)

\r	Carriage return

\f	form feed

\nnn	Octal value between 0 and 0377.

\xnn	Hexadecimal digit between 0x00 and 0xFF

\m	The literal character m.

Note:	When using escape sequences in C language source code, each backslash must also be escaped with another backslash.  The resulting pattern specification is often unaesthetic.


Matching a Character

The basic unit of a regular expression is matching a single character.  You can match a single character in one of three ways:

•	Literally,

•	Ambiguously, or

•	with a Character Class.

You may match a character literally by using the character itself or the appropriate escape sequence.  If matching a character literally is too limiting, you may match ambiguously, by using the dot ( . ) metacharacter.  If a literal character is too narrow a match and the dot is too broad a match, a character class can be used for anything in between.


Character Classes

A character class is a series of characters enclosed in square brackets.  It specifies a set of characters, any one of which may match.  For example, the character class

[AEIOUYaeiouy]

matches any vowel, whether upper or lower case.

Metacharacters may be used in character classes without escaping.  The only exception would be the opening and closing square brackets in which a character class is enclosed; they must still be escaped.

Ranges of characters may also be specified within a character class.  This is done by placing a dash between the character that begins the range and the character that ends the range.  The following character class

[0-9]

will match any character between 0 and 9.

How do you match a dash, then?  If it is not in the character range you specified, just place it at the beginning or end of the character class where it is not between two characters of the class.

The caret ( ^ ) has a special meaning when it appears as the first character of a character class.  It complements the class.  When it appears at any other position within the character class, it just adds the up-caret to that class.  You may use it as a shorthand method of saying "match any characters except for the following: rather than specifying a large character class.  For example,

[^$.|(){}*+?^]

matches anything except the eleven characters following the up-caret.


Iteration Qualifiers

Iteration qualifiers are metacharacters that are not regular expressions by themselves.  Instead, they state how many iterations of the preceding expression there must be or can be, in order to match.  These metacharacters are:  *, + and ?.  As stated in the table, the * matches any number of occurrences, the + matches one or more, and the ? matches zero or one.  Without these qualifiers, a regular expression will match exactly one occurrence in the text.

Let us consider some specific examples of how these qualifiers might be used in the task of matching whitespace:

\t*

The example above will match any number of consecutive tabs, including none.  By itself, it is not very useful to match none of something.  As part of a larger regular expression, it could be quite useful.  For our purposes here, the following might be preferable:

\t+

This example matches one or more consecutive tabs.  The tab is represented as \t, and the plus sign says "one or more of the previous."  To match whitespace, we need to match spaces too.  We don't know what order the spaces and tabs will come in, and we don't know how many there will be.  These are signs that we need a character class.

[ \t]+

The example above uses a character class containing a space and a tab.  The + sign following it means that this Regular Expression will match any combination of spaces and tabs, so long as there is at least one space or tab.

If you wanted to match the whitespace within a function call, where you knew there might be one space or tab, or there might be none, your expression could look like this:

\([ \t]?

This example searches for a left parenthesis followed by zero or one spaces or tabs.  Since the left parenthesis is a metacharacter it is necessary to escape or quote it with a preceding backslash.  The \t we have used before to represent a tab character.  The question mark says "zero or one of the preceding."


Beginning and End of Line

You may use the metacharacters ^ and $ to qualify your Regular Expression further.  We have already seen how the ^ may be used to complement a character class, but it has another quite different use outside of a character class.  These metacharacters specify that, in order to match your Regular Expression, the text must appear at the beginning or end of a line, respectively.  Unlike the iteration qualifiers, however, these metacharacters can stand alone as Regular Expressions.  That is, you can search for just the end of the line or just the beginning of the line.

^PUBLIC

\)$

^\)$

The first of the examples above matches the word "PUBLIC" when it occurs at the beginning of a line.  The second example matches a right parenthesis, a character which must be escaped, when it is found at the end of a line.  The third example matches a right parenthesis when it is the only thing on the line.


Alternation and Grouping

Alternation and grouping go hand in hand.  Alternation often relies on grouping and is the primary need for grouping.

Alternation uses the metacharacter | to denote that a match has been found if the text matches either of two Regular Expressions.  This operator may be repeated to indicate that the text may match any one of several expressions.

Because of the typical order of precedence, the alternation applies to the entire expression, if not limited by grouping.  Grouping occurs when you place parentheses around one or more expressions that are part of a larger expression.

Here are some examples of how these two features work together:

PUBLIC|PRIVATE

PUBLIC (void|DWORD)

^PUBLIC[ \t]+(void|int|long|DWORD)

The first of these examples matches either the word "PUBLIC" or "PRIVATE".  The second matches the word "PUBLIC", when followed by a single space, and then followed by either the word "void" or "DWORD".  Note the use of grouping in this example.  The third example is a bit more complex.  It matches, at the beginning of a line, the word "PUBLIC", followed by one or more spaces or tabs, followed by any one of the following words:  "void", "int", "long" or "DWORD".  This begins to show the power of regular expressions.


Reference Groups and Replacement Strings

In addition to showing association and precedence, grouping allows the use of Reference Groups.  A reference group is one or more expressions that have been placed between parentheses and then pasted into a replacement string by referencing its number.

Codewright  assigns a reference number, from 1 to 9, to the text matching each group defined.  Reference numbers are assigned from left to right.  You may paste the associated text into a replacement string by using this number, preceded by a backslash.

The following example demonstrates how reference groups may be used:

Search pattern:

GotoXY\((.*),(.*)\)

Replacement String:

move_cursor(\2,\1)

Note that in replacement strings you do not need to escape metacharacters, such as the left parenthesis, with a backslash.  There are a few escape sequences that are meaningful in a replacement string, such as those used by reference groups, but such sequences are not themselves regular expressions.

An operation using reference groups could be used to reverse the parameter order used by one function when converting to a similar function.

There is an implicit reference group that you can use in replacement strings to   represent the matching text in its entirety.  You reference this group in the replacement string with an & at the desired location.  This means that you must use \& to specify an ampersand in a replacement string, when regular expressions are enabled.


Placing the Cursor

When you search for a piece of text, it is usually because you are going to do something with it or to it.  After a successful search operation, Codewright  positions the cursor at the beginning of the matching text -- at least, that is the default action.  What if you want to edit the other end of the matching text, or perhaps the middle?

When using Codewrights regular expressions, you have a special escape sequence available that allows you to indicate where in the matching text the cursor should be positioned.  You should note that this is available only for search operations.  It is not for use in replacement text.

The escape sequence that specifies cursor position is \c.  An example of its use follows:

singletons\[\c.*\]

This example places the cursor at the beginning of whatever text is contained between the left and right square brackets.  The square brackets are metacharacters and are therefore escaped.  This cursor positioning facilitates editing the contents of the square brackets.


Regex Examples

The following examples are intended to inspire your own uses of regular expressions:

Pattern	Description

[A-Za-z_][A-Za-z0-9_]*	C language identifier

-?([0-9]+\.?[0-9]*|\.[0-9]+)	Floating point (real) number

([ \t]|^)[^ \t]+	Beginning of word (simple whitespace)

[^ \t]+\c([ \t]|$)	End of word (simple whitespace)

([^A-Za-z0-9]|^)[A-Za-z0-9]+	Beginning of word (Non-alphanumeric)

[A-Za-z0-9]+\c([^A-Za-z0-9]|$)	End of word (Non-alphanumeric)

/\*.*\*/	Single-line comment (C language)

/\*.*\n([ \t]*\*.*\n)*.*\*/	Multi-line comment (C language)


Color Guide

The methods of setting colors in Codewright use a common scheme, intended to simplify selection of foreground and background colors.  The scheme is similar to the one used by DOS, in that it has 16 predefined color settings available that you can use as either foreground or background colors.  You can, however, change the RGB color settings for each of the colors in the table.

This color scheme is also used by the following functions:

ColorCommandLine	AttrFindColor

ColorError	AttrQColor

ColorLineNumbers	AttrSelColor

ColorMessage	AttrSetColor

ColorSelection	AttrSetPaletteEntry

ColorText

ColorWarning

As described in the Codewright Programmer's Reference, they each take a parameter that has a foreground/background combination encoded into a byte.  Each nibble of the byte contains a value corresponding to one of 16 predefined colors.  The most significant nibble describes the background color and the least significant nibble describes the foreground.

The table  shows the default red, green and blue values used for each of the predefined colors.  The function AttrSetPaletteEntry, described in the Codewright Programmer's Reference, allows you to change these mappings:

Color	Number	Red	Green	Blue

Black	0	0	0	0

Blue	1	0	0	128

BlueGreen	2	0	128	128

Green	3	0	128	0

Red	4	128	0	0

Purple	5	128	0	128

Brown	6	128	128	0

Gray	7	128	128	128

DarkGray	8	64	64	64

LightBlue	9	0	0	255

LtBlueGreen	10  (A)	0	255	255

LightGreen	11  (B)	0	255	0

LightRed	12  (C)	255	0	0

LightGray	13  (D)	192	192	192

Yellow	14  (E)	255	255	0

White	15  (F)	255	255	255


Language Construct Templates

Templates allow you to take a fill-in-the-blanks approach to your work.  A significant amount of programming is rather repetitive work:  loops, ifs, and other language constructs.  Other parts of programming may be largely boiler-plate:  the comments describing modules and functions.  Templates reduce the amount of typing you need to do by inserting the repetitive text and letting you fill in the form.  In the case of module and function descriptions, they can even fill in much of the form for you.  Templates provide the added benefit of reducing the chance for errors.  If the template inserts the closing brace for you, braces are less likely to get out of balance.

Codewright has many templates predefined for you, and all you have to do to use them is turn on template expansion.  You will find the setting in the File-Type Properties, on the Buffer submenu of the Options menu.

Of course, coding styles differ from person to person and company to company.  For this reason, templates are fully redefinable.  Press the Template Setup button in that same File-Type Properties to view, edit and add to existing definitions.

Setting up Brace Styles

Modifying Template Primitives

Template Macros

Predefined Templates

Adding and Changing Template Definitions

Using Macros in Templates


Setting-up Brace Styles

One of the ways in which C and C++ coding styles most commonly differ is in the placement of curly braces.  If templates are going to be inserting braces for you, the program will need to know what your coding style is regarding braces.  In anticipation of this, the Brace Style Setup dialog lets you select between three commonly used brace styles.  You get to this dialog by pressing the Brace Style Setup button on the File-Type Properties.  If none of the settings are exactly what you want, see Modifying Template Primitives.


Modifying Template Primitives

Templates replace a trigger word with some usually larger amount of text, such as a fill-in-the-blanks form.  Templates may also contain macros that insert text into the templates.  By changing the definition of a macro, you can thereby change all of the templates that use it.  This is the way Codewright  changes the style of indentation used on braces.

You can edit the definitions of these macros, just as you would edit the definition of any template.  You will find them listed in the Template Setup dialog, which is accessible from the File-Type Properties.


Template Macros

Templates are useful in taking the drudgery out of repetitive tasks.  The constructs used in programming lend themselves to a fill-in-the-blanks style of template.  Codewright  supports this type of template that is automatically triggered when you type a designated abbreviation.

Codewrights templates have a macro capability, however, that makes them the most powerful in the industry.  You may be leaving great potential untapped if you just use templates for language constructs.


Predefined Templates

Before you add or change a template, you need to know what templates are already defined, and what their definitions are.  Since templates are associated with a specific programming language, Codewright  associates them with file types used in that programming language.

You can therefore view the templates defined for a particular file type by selecting Template Setup from the File Type Properties dialog.  You will find this dialog on the Settings submenu on the Buffer menu.  Here, you can view the abbreviations that trigger template expansion, and the string values associated with them.


Adding and Changing Template Definitions

Two methods are provided for adding your own constructs, or changing existing ones.  The first of these methods is through the Template Setup dialog.  The second method is to directly edit your configuration file.

If you choose to do this by directly editing your configuration file (CWVC.INI), you can do this by adding a call to ExtAssignTemplate.  Put it under the [Editor] heading.

There are three string parameters used by ExtAssignTemplate.  The first tells what file extension to associate the template with (e.g., .C, .SC,...).  The second specifies a word or abbreviation that is to trigger the template expansion, for example "if", "else", and so on.  The third string is the template itself.

There are special characters defined for use in language templates, that give Codewright  useful instructions.  For example, most templates will take up more than one line in the buffer. There is a need, therefore, to specify in the template string the locations of new lines.  In most templates, you will also want to specify a location where the cursor is to be placed after the template is inserted.  Here is a table of the special characters available, and their meanings:

Character	Purpose

\n	New Line.  Simulates pressing enter at this point.

&	Specifies cursor position after template insertion.

@	Issues a backspace.

\c	Insert 'c' literally, (e.g., \&, \@, \\)

\t	Insert a tab.

Here are some sample template strings, to give you an idea of how these special characters are used to construct templates:

"if (&)\n{\n}"

"do \n{\n\t&\n}\n while( );"

"for (&; ; )\n{\n}"

Finally, here is how the complete ExtAssignTemplate line might look in your configuration file:

ExtAssignTemplate=".pas","proc","Procedure &();\nBegin\nEnd;"

This example adds a template for use when editing files with the extension .PAS.  When the word "proc" is typed, followed by a space, a template for a Pascal Procedure is inserted in the buffer.  The cursor is positioned at the point where the name of the procedure would be entered.


Using Macros in Templates

You may have noticed the use of certain % macros in some of the existing templates used for language constructs.  These macros can have a great many uses.  For example, they enable Codewright  to place braces differently, depending on the indentation style desired.  You can even find uses for these Template macros independent of triggering abbreviations and specific programming languages.  You may wish to assign a template to a key or button.  To do this, you need to use a function that interprets these macros directly.  That function is ExtExpandTemplate.

You will find an example use of ExtExpandTemplate on the sidebar.  There are two buttons that use this function to insert a header.  One button inserts a module header, and the other inserts a function header.  The function call is quite simple:

ExtExpandTemplate %ffunct.tpl$

This command uses the %f Template macro to insert the file FUNCT.TPL, which contains the function header.  The trailing $ is used to delimit the filename string.  Template macros can, of course, be a lot more complex.  The file that this macro inserts can also contain Template macros.  The file FUNCT.TPL is also simple, and it contains just one Template macro.  A table containing a complete list of the % macros available follows:

Macro form	Description

%colNum	Moves the cursor to column Num of the current line.

%date	Inserts a U.S. formatted date string at the current cursor position. (mm/dd/yy)

%db	Deletes to the beginning of the line.

%dcNum	Deletes Num characters at cursor.

%de	Deletes to the end of the line.

%dlNum	Delete Num line, beginning with the current.

%dw	Delete the word at the cursor.

%eEnVar$	Insert the string value associated with environment variable EnVar.

%fFilename$	Insert the named file at the cursor.  Any template macros within the file are also processed.

%home	Move the cursor to the beginning of the line.

%lineNum	Move the cursor to the line named by Num.

%mdNum	Move down Num lines.

%meof	Move the cursor to the end of the file.

%meol	Move the cursor to the end of the line.

%mlNum	Move the cursor left by Num columns.

%mrNum	Move the cursor right by Num columns.

%muNum	Move up Num lines.

%Num	When Num is 0 to 9, it refers to a user-definable string that may be defined differently for each extension.  Any macros contained in these strings are also expanded.  Typically, these assignments are made in your configuration file or CWVC.EXT.  The macros 0 through 3 are used for custom indentation in predefined language templates.  See ExtSetTemplateMacro.

Higher numbered macros (10 through 31) are not extension specific, but are otherwise similarly definable.  They are reserved for the use of individual users.

%open	Open a new line following the current.  Similar to going  to the end of the line and pressing [Enter].

%qPrompt$	Query for string to insert, using the string Prompt to prompt the user.

%repCNum	Insert Num repetitions of character C.

%restore	Restore a saved position.

%save	Save a position for later restoration.

%time	Insert a formatted time string.  (hh:mm:ss)

%tof	Move cursor to the top (first line) of the file.  Requires %home to assure positioning at the first character of the file.

%xFuncCall$	Execute the Codewright  API function call in FuncCall.  This may be any function that could be assigned to a key or otherwise executed through LibFunctionExec.


Key Commands

CUA Key Commands

BRIEF Key Commands

VI Key Commands

Epsilon Key Commands


CUA Key Commands

Buffer/File

Cursor Motion/Scrolling

Editing

Scrap/Clipboard

Search/Replace

Selections/Marks

System

Window


BufferFile Commands
Buffer/File Commands

Change output name	[Ctrl][Shift][O]

Close buffer	[Ctrl][-]

Display filename	[Ctrl][F]

Next buffer	[Ctrl][N]

Open file	[Ctrl][F12]

Open file	[Ctrl][E]

Previous buffer	[Ctrl][P]

Read file into buffer	[Ctrl][Shift][F]

Save file	[Shift][F12]

Save file	[Ctrl][W]

Tabs usage on/off	[Ctrl][Shift][Tab]

Write selection to file	[Ctrl][W]


Cursor MotionScrolling Commands
Cursor Motion/Scrolling Commands

beginning of line	[Home]

bottom of file	[Ctrl][End]

Cursor left	[Left]

Cursor right	[Right]

end of line	[End]

Go to line (prompt)	[Ctrl][Shift][L]

Go to mark (prompt)	[Ctrl][Shift][B]

Line down	[Down]

Line up	[Up]

Make bottom of win.	[Ctrl][A]

Make top of window	[Ctrl][T]

Make middle of win.	[Ctrl][M]

Page down	[PgDn]

Page up	[PgUp]

Scroll down one line	[Ctrl][Down]

Scroll up one line	[Ctrl][Up]

top of file	[Ctrl][Home]

Word left	[Ctrl][Left]

Word right	[Ctrl][Right]


Editing Commands

Delete character	[Del]

Delete character  left	[Backsp]

Delete line	[Ctrl][D]

Delete to end of line	[Ctrl][Del]

Delete next word	[Shift][Backsp]

Delete previous word	[Ctrl][Backsp]

Indent block	[Tab]

Insert line	[Ctrl][Enter]

Insert next literally	[Ctrl][Q]

Redo	[Alt][Ins]

Redo	[Ctrl][Y]

Undo	[Alt][Backsp]

Undo	[Ctrl][U]

Undo	[Gray *]

Unindent block	[Shift][Tab]


ScrapClipboard Commands
Scrap/Clipboard Commands

Copy to 	[Ctrl][Ins]

Copy to 	[Ctrl][C]

Copy to 	[Gray +]

Cut to 	[Shift][Del]

Cut to 	[Ctrl][X]

Cut to 	[Gray -]

Paste from 	[Shift][Ins]

Paste from	[Ctrl][V]

Paste from	[Gray /]

Toggle clipb./scrap	[Ctrl][/]


SearchReplace Commands
Search/Replace Commands

Incremental search	[Ctrl][Shift][I]

Brace kiss	[Ctrl][Shift][K]

Match brace or paren	[Ctrl][ { ]

Quick search	[Ctrl][Shift][Q]

Replace	[Ctrl][R]

Replace again	[Ctrl][Shift][R]

Search	[Ctrl][S]

Search again	[F3]

Search again	[Ctrl][Shift][S]


SelectionsMarks Commands
Selections/Marks Commands

Begin sel., inclusive	[Ctrl][I]

Begin sel., exclusive	[Ctrl][Z]

Begin selec., column	[Ctrl][B]

Begin selection, line	[Ctrl][L]

Extend selection left	[Shift][Left]

Extend selection right	[Shift][Right]

Extend selection up	[Shift][Up]

Extend sel. down	[Shift][Down]

Extend sel. word left	[Ctrl][Shift][Left]

Extend sel. word right	[Ctrl][Shift][Right]

Extend sel. begin line	[Shift][Home]

Extend sel. end  line	[Shift][End]

Extend sel. beg. buffer	[Ctrl][Shift][Home]

Extend sel. end buffer	[Ctrl][Shift][End]

Close/open Selection	[Ctrl][ . ]

Go to mark (prompt)	[Ctrl][Shift][B]

Lower case selec.	[Ctrl][Shift][D]

Upper case selec.	[Ctrl][Shift][U]

Set mark	[Ctrl]n

Slide-in prompt	[Ctrl][>]

Slide-out prompt	[Ctrl][<]


System Commands

API interface	[F9]

Auto indent on/off	[Ctrl][Shift][A]

Compact Mode	[Ctrl][Shift][C]

Compile buffer	[Ctrl][F10]

Expand/Col. hidden	[Shift][Enter]

Next error	[Ctrl][Shift][Down]

Previous error	[Ctrl][Shift][Up]

Help	[F1]

Hex Mode	[Ctrl][Shift][H]

Insert mode on/off	[Ins]

Load recording file	[Ctrl][F7]

Make current	[Ctrl][F9]

Playback keystrokes	[F8]

Play stored keystrokes	[Ctrl][Shift]n

Print version	[Ctrl][Shift][V]

Quit	[Alt][F4]

Record keys toggle	[F7]

Routines	[Ctrl][Shift][G]

Text Mode	[Ctrl][Shift][T]

Wrap paragraph	[Ctrl][Shift][W]

Write recording file	[Ctrl][F8]


Window Commands

Close win. & buffer	[Ctrl][F4]

Close window only	[Ctrl][Shift][-]

Iconify window	[Ctrl][Shift][F4]

Next window	[Ctrl][Shift][N]

Next wind. & buffer	[Ctrl][F6]

Previous window	[Ctrl][Shift][P]

Toggle visible whspc.	[Ctrl][Shift][X]

Zoom window	[Alt][F2]


BRIEF Key Commands

Buffer/File

Cursor Motion/Scrolling

Editing

Scrap/Clipboard

Search/Replace

Selections/Marks

System

Window


BufferFile BRIEF Commands
Buffer/File Commands

Change output name	[Alt][O]

Close buffer	[Ctrl][-]

Display filename	[Alt][F]

List of buffers	[Alt][B]

Next buffer	[Alt][N]

Open file	[Alt][E]

Previous buffer	[Alt][-]

Print buffer	[Alt][P]

Read file into buffer	[Alt][R]

Save file	[Alt][W]

Write selection to file	[Alt][W]


Cursor MotionScrolling BRIEF Commands
Cursor Motion/Scrolling Commands

Beginning of line	[Home]

Bottom of file	[Ctrl][PgDn]

Bottom of file	[End][End][End]

Bottom of window	[Ctrl][End]

Bottom of window	[End][End]

Column left	[Left]

Column right	[Right]

End of line	[End]

Go to line (prompt)	[Alt][G]

Go to mark  (prompt)	[Alt][J]

Left window edge	[Shift][Home]

Line down	[Down]

Line up	[Up]

Make bottom of win.	[Ctrl][B]

Make top of window	[Ctrl][T]

Make center of win.	[Ctrl][C]

Page down	[PgDn]

Page up	[PgUp]

Right wind. edge	[Shift][End]

Scroll down 1 line	[Ctrl][D]

Scroll up 1 line	[Ctrl][U]

Top of file	[Home][Home][Home]

Top of file	[Ctrl][PgUp]

Top of window	[Ctrl][Home]

Top of window	[Home][Home]

Word left	[Ctrl][Left]

Word right	[Ctrl][Right]


Editing BRIEF Commands
Editing Commands

Delete character	[Del]

Delete character to left	[Backsp]

Delete line	[Alt][D]

Delete to end of line	[Alt][K]

Delete next word	[Alt][Backsp]

Delete previous word	[Ctrl][Backsp]

Indent block by tab	[Tab]

Indent block by space	[Space]

Insert line	[Ctrl][Enter]

Insert next literally	[Alt][Q]

Redo	[Alt][Y]

Undo	[Alt][U]

Undo	[Gray *]

Unindent block by tab	[Shift][Tab]


ScrapClipboard BRIEF Commands
Scrap/Clipboard Commands

Copy to 	[Ctrl][Ins]

Cut to 	[Shift][Del]

Copy to 	[Gray +]

Cut to 	[Gray -]

Paste from 	[Ins]

Toggle clipb./scrap	[Ctrl][/]


SearchReplace BRIEF Commands
Search/Replace Commands

Brace kiss	[Ctrl][Shift][K]

Ignore case on/off	[Ctrl][F5]

Quick search	[Ctrl][Shift][Q]

Multi-buf search again	[Ctrl][Shift][M]

Reg. expr. on/off	[Ctrl][F6]

Replace	[Alt][T]

Replace	[F6]

Replace again	[Shift][F6]

Search	[F5]

Search	[Alt][S]

Search again	[Shift][F5]


SelectionsMarks BRIEF Commands
Selections/Marks Commands

Begin selec., inclusive	[Alt][M]

Begin selec., exclusive	[Alt][A]

Begin selec., column	[Alt][C]

Begin selection, line	[Alt][L]

Close/open Selection	[Ctrl][A]

Go to mark (prompt)	[Alt][J]

Set mark	[Alt]n

Slide-in prompt	[Ctrl][>]

Slide-out prompt	[Ctrl][<]


System BRIEF Commands
System Commands

API interface	[F10]

Backups on/off	[Ctrl][W]

Compact Mode	[Ctrl][Shift][C]

Compile buffer	[Alt][F10]

Display routines	[Ctrl][G]

Expand/Col. hidden	[Shift][Enter]

Next error	[Ctrl][N]

Previous error	[Ctrl][P]

Help	[Alt][H]

Hex Mode	[Ctrl][Shift][H]

Insert mode on/off	[Alt][I]

Load DLL	[F9]

Load recording file	[Alt][F7]

Playback keystrokes	[F8]

Print buffer	[Alt][P]

Print version	[Alt][V]

Quit w/prompt	[Alt][X]

Quit w/write	[Ctrl][X]

Record keys toggle	[F7]

Repeat key action	[Ctrl][R]

Shell	[Alt][Z]

Text Mode	[Esc]

Unload DLL	[Shift][F9]

Write recording file	[Alt][F8]


Window BRIEF Commands
Window Commands

Adjust window size	[F2]

Borders on/off	[Alt][F1]

Create tiled edge	[F3]

Delete tiled edge	[F4]

Next window	[F1]

Select  win. at left	[Shift][Left]

Select win. at right	[Shift][Right]

Select win. above	[Shift][Up]

Select win. below	[Shift][Down]

Zoom window	[Alt][F2]


VI Command Set

VI Modes

VI Command Summary

Codewright Extensions for vi

EX Command Words supported


VI Modes

Command	Initial (Normal) mode.  Other modes normally return to command mode upon completion.  [Esc] is used to cancel a partial command.
Input	Enter this mode by setting any of the following options: a A i I o 0 c C s S R. You may then enter arbitrary text.  This mode is normally terminated by pressing [Esc].
Last line	Reading input for : / ? or 1; terminated by typing a [Enter].


VI Command Summary

Examples

Bookmarks

Count Arguments

Cursor Motion

Editing

File Operations

Miscellaneous Operations

Scrolling

Searching

Operators

Undo, Redo, Retrieve

Yank and Put


vi Examples
Examples

/text[Enter]	search for text

:cmd[Enter]	ex or ed command

:q![Enter]	quit, discarding changes

^U ^D	scroll up or down

3dd	delete 3 lines

cwnew[Esc]	change word to new

dd	delete a line

dw	delete a word

easX	plurals word (end of word; append s; escape from input state)

h i k I	same as arrow keys, respectively

itext[Esc]	insert text

[Lt][Dn][Up][Rt]	arrow keys move the cursor

u	undo previous change

x	delete a character

ZZ	exit vi, saving changes


Count Arguments

Numbers may prefix some commands, They are interpreted in one of these ways.

line/col number	z  G  I

scroll amount	^D  ^U

repeat effect	most of the rest


File Operations

:!cmd[Enter]	run cmd, then  return

:e #[Enter]	edit alternate file

:e + name[Enter]	edit, starting at end

:e +n[Enter]	edit  starting  at line n

:e name[Enter]	edit file name

:e! #[Enter]	edit alternate file, discard changes

:e![Enter]	reload, discard changes

:n args[Enter]	specify new arglist

:n[Enter]	edit next file in arglist

:q![Enter]	quit, discard changes

:q[Enter]	quit

:sh[Enter]	run shell, then  return

:ta tag[Enter]	position cursor to  tag

:w name[Enter]	write file name

:w! name[Enter]	overwrite file name

:w![Enter]	forced write, if permission originally not valid

:w[Enter]	write back changes

^G	show current file and line

ZZ	if file modified, write and exit; otherwise, exit

In general, any command word (such as substitute or global) may be typed, preceded by a colon and followed by a carriage return.


Cursor Motion

! or [Left]	backward

$	end of line

(	back a sentence

(	beginning of sentence

)	end of sentence

)	to next sentence

+	next line, at first non-white

-	previous line, at first non-white

[[	previous section/function

]]	next section/function

^	first non white-space character

^B	backward screen

^D	scroll down half screen

^F	forward screen

^H	same as backspace

^U	scroll up half screen

{	back a paragraph

{	beginning of paragraph

}	end of paragraph

}	to next paragraph

0	beginning of line

B	back a blank-delimited word

b	back a word

E	end of a blank-delimited word

e	end of word

[Enter]	return, same as +

H	top line on screen

h or [Right]	forward

L	last line on screen

M	middle line on screen

n	repeat last or ? command

N	reverse last or ? command

n|	move to column n

nG	go to the beginning of the specified line (end default), where n is a line number

space	same as space bar

W	forward a blank-delimited word

w	forward a word

[Dn] or j	next line, same column

[Up] or k	previous line, same column


Searching

,	repeat inverse of last f F t or T

%	find matching ( ) { or }

/pat	next line matching par

/pat/+n	n-th line after pat

/pat/z-[Enter]	move pat line to bottom of window

;	repeat last f F t or T

?pat	previous line matching pat

?pat?-n	n-th line before pat

a	append after cursor

A	append at end of line

fx	find next x

Fx	find previous x

i	insert before cursor

I	insert before first non-blank

Rtext[Esc]	replace characters

rx	replace single char with x

Tx	move to character following previous x

tx	move to character prior to next x


Scrolling

^E	scroll window down 1 line

^L	clear and redraw window

^R	clear and redraw window if -L is - key

^Y	scroll window up 1 line

z-[Enter]	redraw screen with current line at bottom of window

z.[Enter]	redraw screen with current line at center of window

z[Enter]	redraw screen with current line at top of window

zn.[Enter]	use n-line window


Bookmarks

mx	mark current position with the ASCII lower-case letter x

`x	move cursor to mark x

'x	move cursor to first non-white space in line marked by x


Editing (Insert Mode)

^H	erase last character (backspace)

^W	erase last word

erase	your erase character, same as ^H (backspace)

\	quotes your erase and kill characters

[Esc]	ends insertion, back to command mode

[Del]	interrupt, terminates insert mode

^D	backtab one character; reset left margin of autoindent

^^D	caret (^) followed by control-d (^D); backtab to beginning of line; do not reset left margin of autoindent

O^D	backtab to beginning of line; reset left margin of autoindent

^V	quote non-printable character

o	open line below

O	open above


Operators

Operators are followed by a cursor motion, and affect all text between the cursor's starting and ending position.  For example, since w move's over one word, dw deletes the word that would be moved over.  Double the operator, e.g., dd to affect whole lines.

!	fitter through command

<	left shift

>	right shift

c	change

d	delete

y	yank lines to buffer


Miscellaneous Operations

C	change rest of line (c$)

D	delete rest of line (d$)

J	join lines

s	substitute chars (cl)

S	substitute lines (cc)

x	delete characters (dl)

X	delete characters before cursor (dh)

Y	yank lines (yy)


Yank and Put

Put inserts the text most recently deleted or yanked; however, if a buffer is named (using lower-case letters), the text in that buffer is put instead.

"xd	delete into buffer x

"xp	put from buffer x

"xy	yank to buffer x

3yl	yank 3 characters

3yy	yank 3 lines

p	put back text after cursor

P	put back text before cursor


Undo, Redo, Retrieve

"dp	retrieve dth last delete

.	repeat  last  change

U	restore current line

u	undo last change


Codewright Extensions for vi

[F1]	Context sensitive help

[F2]	ASCII Editing mode

[F3]	Selective Display mode

[F4]	Hex Edit mode

[F9]	API Command Key


EX Command Words Supported

!

&

<

=

>

append

cc

cd

change

chdir

copy

delete

edit

errlist

ex

file

global

insert

join

k

list

make

mark

move

next

number

previous

print

put

quit

read

rewind

set

shell

substitute

tag

to

undo

version

vglobal

visual

wq

write

xit

yank


Epsilon Key Commands

Buffer/File

Cursor Motion/Scrolling

Editing

Scrap/Clipboard

Search/Replace

Selections/Marks

System

Window


Epsilon Buffer/File

Bufed	[Ctrl][X], [Ctrl][B]

Copy to file	[Ctrl][F7]

Kill buffer	[Ctrl][X],[K]

Next buffer	[F12]

Next buffer	[Ctrl][X],[>]

Previous buffer	[F1]

Previous buffer	[Ctrl][X],[<]

Save all buffers	[Ctrl][X],[S]

Save file	[Ctrl][X], [Ctrl][S]

Select buffer	[Ctrl][X],[B]

Visit file	[Ctrl][X], [Ctrl][V]

Write file	[Ctrl][X], [Ctrl][W]


Epsilon Cursor Motion/Scrolling

Backward character	[Left]

Backward character	[Ctrl][B]

Backward kill level	[Alt][Del]

Backward level	[Ctrl][Alt][B]

Backward paragraph	[Alt][[]

Backward paragraph	[Alt][Up]

Backward sentence	[Alt][A]

Backward sentence	[Ctrl][Up]

Backward word	[Alt][B]

Backward word	[Ctrl][Left]

Beginning of line	[Alt][Left]

Beginning of line	[Ctrl][A]

Beginning of window	[Home]

Beginning of window	[Alt][,]

Center window	[Ctrl][L]

Down line	[Down]

Down line	[Ctrl][N]

End of line	[Alt][Right]

End of line	[Ctrl][E]

End of window	[End]

End of window	[Alt][.]

Forward character	[Right]

Forward character	[Ctrl][F]

Forward level	[Ctrl][Alt][F]

Forward paragraph	[Alt][]]

Forward paragraph	[Alt][Down]

Forward sentence	[Alt][E]

Forward sentence	[Ctrl][Down]

Forward word	[Alt][F]

Forward word	[Ctrl][Right]

Go to beginning	[Ctrl][Home]

Go to end	[Ctrl][End]

Goto beginning	[Alt][<]

Goto end	[Alt][>]

Goto line	[Ctrl][X],[G]

Next page	[PgDn]

Next page	[Ctrl][V]

Next position	[Ctrl][X], [Ctrl][N]

Previous page	[Alt][V]

Previous page	[PgUp]

Previous position	[Ctrl][X], [Ctrl][P]

Scroll down	[Alt][Z]

Scroll left	[Alt][{]

Scroll right	[Alt][}]

Scroll up	[Ctrl][Z]

To indentation	[Alt][M]

Up line	[Up]

Up line	[Ctrl][P]


Epsilon Editing

Backward delete character	[Ctrl][H]

Backward delete character	[Ctrl][?]

Backward kill word	[Ctrl][Alt][H]

Capitalize word	[Alt][C]

Center line	[Alt][S]

Delete blank lines	[Ctrl][X], [Ctrl][O]

Delete character	[Ctrl][D]

Delete character	[Del]

Delete horizontal space	[Alt][\]

Enter key	[Ctrl][M]

Fill paragraph	[Alt][P]

Indent for comment	[Alt][;]

Indent previous	[Ctrl][Ι]

Indent region	[Ctrl][Alt][\]

Indent rigidly	[Ctrl][X],[Alt][I]

Indent under	[Ctrl][Alt][I]

Insert ascii	[Alt][#]

Insert file	[Ctrl][X],[I]

Kill level	[Ctrl][Alt][K]

Kill line	[Ctrl][K]

Kill Region	[Ctrl][W]

Kill sentence	[Alt][K]

Kill word	[Alt][D]

Lowercase word	[Alt][L]

Maybe break line	[Ctrl][J]

Open line	[Ctrl][O]

Overwrite mode	[Ins]

Quoted insert	[Ctrl][Q]

Redo	[Ctrl][X],[R]

Redo	[F10]

Redo changes	[Ctrl][F10]

Redo changes	[Ctrl][X],[Ctrl][R]

Transpose characters	[Ctrl][T]

Transpose lines	[Ctrl][X], [Ctrl][T]

Transpose words	[Alt][T]

Undo	[Ctrl][X],[U]

Undo	[F9]

Undo changes	[Ctrl][F9]

Undo changes	[Ctrl][X], [Ctrl][U]

Uppercase word	[Alt][U]


Epsilon Scrap/Clipboard

Append next kill	[Ctrl][Alt][W]

Copy region	[Alt][W]

Copy to scratch	[Ctrl][X],[X]

Insert scratch	[Ctrl][X],[Y]

Yank	[Ctrl][Y]

Yank pop	[Alt][Y]


Epsilon Search/Replace

Find delimiter	[Alt][)]

Incremental search	[Ctrl][S]

Query replace	[Alt][%]

Query replace	[Alt][R]

Regex replace	[Alt][*]

Regex replace	[Alt][Gray -]

Regex search	[Ctrl][Alt][S]

Replace string	[Alt][&]

Reverse incremental search	[Ctrl][R]

Reverse regex search	[Ctrl][Alt][R]

Select tag file	[Ctrl][X],[Alt][,]

tag files	[Ctrl][X],[Alt][.]


Epsilon Selections/Marks

Exchange point and mark	[Ctrl][X], [Ctrl][X]

Highlight region	[Ctrl][X], [Ctrl][H]

Jump to last bookmark	[Alt][J]

Mark paragraph	[Alt][H]

Rectangle mode	[Ctrl][X],[#]

Set bookmark	[Alt][/]

Set mark	[Ctrl][@]

Set mark	[Alt] n

Set named bookmark	[Ctrl][X],[/]

Tabify region	[Ctrl][X], [Ctrl][Alt][I]

Untabify region	[Ctrl][X],[Alt][I]

Write region	[Ctrl][X],[W]


Epsilon System

Abort	[Ctrl[G]]

Alt prefix	[Ctrl][[]

Alt prefix	[Ctrl][X], [Ctrl][[]

Argument	[Ctrl][U]

Argument	[Alt][-]

Argument	[Alt][Gray -]

Bind to key	[F4]

cd	[F7]

Change modified	[Alt][~]

Compare windows	[Ctrl][F2]

Count lines	[Ctrl][X],[L]

Ctrl prefix	[Ctrl][^]

Ctrl prefix	[Ctrl][Alt][^]

Ctrl prefix	[Ctrl][X], [Ctrl][Alt][^]

Ctrl prefix	[Ctrl][X], [Ctrl][^]

Dired	[Ctrl][X],[D]

End kbd macro	[Ctrl][X],[)]

Exit	[Ctrl][X], [Ctrl][C]

Exit level	[Ctrl][X], [Ctrl][Z]

Find file	[Ctrl][X], [Ctrl][F]

Goto tag	[Ctrl][X],[.]

Grep	[Alt][F7]

Help	[Ctrl][_]

Help	[F1]

Last kbd macro	[Ctrl][F4]

Last kbd macro	[Ctrl][X],[E]

Load bytes	[F3]

Make	[Ctrl][X],[M]

Name kbd macro	[Ctrl][X],[Alt][N]

Named command	[Alt][X]

Named command	[F2]

Pluck tag	[Ctrl][X],[,]

Push	[Ctrl][X], [Ctrl][E]

Set comment column	[Ctrl][X],[;]

Set fill column	[Ctrl][X],[F]

Set variable	[F8]

Show bindings	[F5]

Show menu	[Alt][F2]

Show variable	[Ctrl][F8]

Start kbd macro	[Ctrl][X],[(]

Start process	[Ctrl][X],[Ctrl][M]

Stop process	[Ctrl][C]

What is	[F6]

Write state	[Ctrl][F3]


Epsilon Window

Enlarge window	[Ctrl][X],[^]

Enlarge window	[Ctrl][PgUp]

Enlarge window	[Ctrl][X],[^]

Enlarge window horizontally	[Alt][PgUp]

Enlarge window horizontally	[Ctrl][X],[@]

Enlarge window interactively	[Ctrl][X],[Gray +]

Enlarge window interactively	[Ctrl][X],[+]

Kill window	[Ctrl][X],[Ctrl][D]

Kill window	[Ctrl][X],[0]

Move to window	[Ctrl][X],[Down]

Move to window	[Ctrl][X],[Left]

Move to window	[Ctrl][X],[Right]

Move to window	[Ctrl][X],[Up]

Next window	[Ctrl][X],[N]

Next window	[Ctrl][X],[O]

Next window	[Alt][End]

One window	[Ctrl][X],[1]

Previous window	[Ctrl][X],[P]

Previous window	[Alt][Home]

Shrink window	[Ctrl][PgDn]

Shrink window horizontally	[Alt][PgDn]

Shrink window interactively	[Ctrl][X],[Gray -]

Shrink window interactively	[Ctrl][X],[-]

Split window	[Ctrl][X],[2]

Split window vertically	[Ctrl][X],[5]

Zoom window	[Ctrl][X],[Z]