Codewright Manual

i

Codewright

Programmer�s Editor

8VHU©V�*XLGH

Part No. 000-3936

ii

Copyright © 1992-1996 Premia Corporation. All rights reserved.

The following copyright message is required due to the inclusion of CTL3D.DLL withour product:Portions © Microsoft Corporation, 1985-1995. All rights reserved.

Publication History

October, 1991 First ReleaseFebruary, 1992 Updated for 1.1June, 1992 Updated for 2.0August 1993 Updated for 3.0August 1994 Updated for 3.1November 1995 Reformatted and updated for 4.0January 1997 Updated for 5.0

TrademarksPremia is a registered trademark of Premia Corporation.Codewright is a trademark of Premia Corporation.Borland C++ and Brief are registered trademarks of Borland International.Microsoft is a registered trademark of Microsoft Corporation.Windows and Visual C++ are trademarks of Microsoft Corporation.Epsilon is a trademark of Lugaru, Inc.Other product names are the trademarks of their respective holders.

Premia Corporation1075 NW Murray Blvd., Suite 268Portland, Oregon 97229Phone: (503) 641-6000Fax: (503) 641-6001BBS: (503) 646-1374CompuServe: 70673,2627Email: [email protected] or [email protected] Wide Web: http://www.premia.com

iii

Table of Contents

INTRODUCTION...................................IX

What Makes Codewright Different? ...... ixBasic Strategy ..................................... xUser Compiled DLLs .......................... x

Key Editor Features................................ xiAbout the Manuals ................................ xiiUsing this Manual ................................. xiiTypographical Conventions .................xiii

EDITOR HIGHLIGHTS.......................... 1

API Assistance ........................................ 1Using the API Assistant ...................... 1Modifying the Database ...................... 2Automation Tools................................ 2

Browsing, Tags, and Outline Symbols .... 3Which Type of Browsing Should IUse? .................................................... 3Browser Support ................................. 4Tags Support ....................................... 9Outline Symbols................................ 10

Button links ........................................... 12How it works ..................................... 12What you see..................................... 12Defining buttons................................ 12View Links ........................................ 13

Mouse Commands................................. 14Inclusive or Exclusive Selection ....... 14Closed Selections .............................. 14Column Marking ............................... 15Line Selections.................................. 15Word Selections ................................ 15Status Line Actions ........................... 15Text Drag and Drop .......................... 16Mouse Copy and Move ..................... 17Creating Windows with a Mouse ...... 17Drag and Drop File Loading ............. 18Expand / Collapse ............................. 18Popup Menu...................................... 18Making Mouse Assignments ............. 19

Selective Display...................................19Using Selective Display.....................19

Spell Checker ........................................19Spell Check Dialog............................20Spell Correction Dialog.....................21

Template Macros...................................22Predefined Templates ........................23Adding and Changing TemplateDefinitions.........................................23Using Macros in Templates...............24

User-definable Popup Menu..................27Definition Sections ............................28Item Definition Lines.........................28Item Hot Keys ...................................28Separator Lines..................................29Supporting Functions.........................29

SEARCH AND REPLACE.....................31

Search and Replace Dialog....................31Search Settings ......................................32Replacement Options.............................33Multiple Sources Search Dialog ............34Advanced Multi-source Search Options 34Edit Search List .....................................37Incremental Searching ...........................38

ISearch Function................................38Quick Search .........................................39Toolbar Search ......................................39

DOCKABLE TOOLBARS ANDWINDOWS ..............................................41

What Does Dockable Mean?.................41Enabling and Disabling Toolbars ..........41Docking and Moving Toolbars andWindows................................................42Customizing Toolbars and Buttons .......42Project Window.....................................43

File View Window ............................44Outline Window ................................45Bookmarks Window..........................47

iv

Table of Contents

Open File Window ............................ 48Tabbed Output Window........................ 48

Select View via Tabs......................... 49Associated Dialogs............................ 50

VDOS.................................................... 50

LANGUAGE FEATURES...................... 53

Document Settings ................................ 53Document Language Dialog.................. 53

Associating File Types with aLanguage........................................... 53

Other File Type Specific Settings ......... 54Editing the Extensions File................ 54

Function Definitions Outline................. 55C Language Support.............................. 55

Brace Matching ................................. 55Pre-processed View........................... 57

KEY COMMANDS ................................ 59

CUA Key Commands............................ 59In the Beginning................................ 60Advanced Stages ............................... 60

Codewright CUA Variant...................... 60Persistent Selections.............................. 61Disabling Virtual Space ........................ 61CUA Commands by Category............... 63CUA Commands by Key....................... 65Making CUA Key Assignments ............ 67CUA Keymap Functions ....................... 67BRIEF Key Commands......................... 74

BRIEF-compatible Commands byCategory............................................ 75BRIEF Compatible Commands by Key78Brief Keymap Functions ................... 80

VI Key Commands................................ 84Vi Modes........................................... 84VI Command Summary..................... 84Codewright Extensions...................... 89EX Command Words Supported....... 89

Epsilon Key Commands........................ 90Epsilon Keymap Functions ............... 99

VERSION CONTROL SETUP............114

Which Interface Do I Use?..................114Command Line Interface .....................115

Unlisted Providers ...........................115Check In Command.........................115Check Out Command ......................116Check Out with Lock Command .....116Lock Command ...............................117Unlock Command............................117Log Command.................................117Manager Command .........................117

SCC Provider Interface .......................118VCS Maintenance Dialog....................118

PROJECTS AND WORKSPACES .....119

What is a Project?................................119What is a Workspace? .........................119Creating a Project ................................120Adding and Deleting Project Members120Project Setup Checklist .......................121Using Projects .....................................121

Selecting or Changing Projects........122Loading Files for Editing.................122Project Window...............................122Creating a Workspace .....................123Workspace Saving...........................123Changing Workspaces .....................124Searching Project Files....................125Selecting files for Check-in or Check-out....................................................125

Project Files.........................................125Configuration and State Hierarchy ......125

REGULAR EXPRESSIONS ................127

Special Characters ...............................127Escape Sequences................................128Matching a Character ..........................129Character Classes ................................129Escaping Characters in a Class............130Iteration Qualifiers ..............................130

v

Table of Contents

Beginning and End of Line ................. 131Alternation and Grouping.................... 132Reference Groups and ReplacementStrings ................................................. 133Placing the Cursor ............................... 133Examples............................................. 135

GENERAL OPERATION.................... 136

Backup Files and Directories .............. 136Backup Formatting Strings.............. 137Transformation Patterns .................. 138Illustrative Examples....................... 139

Command Key..................................... 139Command Completion .................... 140Using the API.................................. 141Source Code versus Command Key 141Displaying Return Values ............... 142Examples of Usage.......................... 142Expression Evaluator ...................... 143

Line Drawing ...................................... 144Menu Editor ........................................ 146

Menus.............................................. 146Menu Items and Submenus ............. 147Operating on Submenus .................. 148

Prompt Histories ................................. 148

CONFIGURATION AND STATE ...... 150

Introduction to Configuration and State151Configuration File ........................... 151State File ......................................... 151Other Files Containing ConfigurationData................................................. 152Example File ................................... 152Example Interpretation.................... 153

Processing At Startup.......................... 154Order of Processing......................... 155

User Defined Sections......................... 156Relating Checkboxes to Functions ...... 158State File ............................................. 159

Contents of the State File ................ 159

COMMAND LINE PARAMETERS ...161

Filenames.............................................161Flags ....................................................161Command Files....................................166

APPENDIX A -- COLOR GUIDE .......167

Palette Settings ....................................168

APPENDIX B -- TECHNICALSUPPORT ..............................................169

Web Page ............................................169Internet Mail ........................................169CompuServe ........................................169Fax.......................................................170Phone Support .....................................170Maintenance Policy .............................170

APPENDIX C -- UPDATING SOURCEWITH MERGE .....................................171

Steps to Merging .................................171Identify Merge Candidates ..............172Make the Source Files Available.....172Install AutoMerge............................173Define AutoMerge Directories ........173Execute the AutoMerge Function....174Resolve Conflicts.............................174

APPENDIX D -- TAGSWNN UTILITY176

Usage...................................................176TAGSWnn Command Line Options....176

APPENDIX E -- SPECIFICATIONS ..183

Line Length Limit............................183Lines per Buffer Limit .....................183Buffers Limit ...................................183Windows Limit ................................183File Size...........................................183Number of Files...............................183Clipboard/Scrap Buffer Size............183Search String Length .......................183

vi

Table of Contents

FUNCTION REFERENCE.................. 187

Function Description Format............... 187AssignMouseKeys............................... 189AttrSetPaletteEntry ............................. 189Autosave.............................................. 189AutosaveDir ........................................ 190BackTab.............................................. 190BlockCopy .......................................... 190BlockCut ............................................. 191Brace ................................................... 191BraceMatch ......................................... 191BraceMatchNext ................................. 192BufBackspace...................................... 192BufDelChar ......................................... 193BufDelLine.......................................... 194BufDelSelection .................................. 194BufDelToEOL..................................... 194BufEditFile.......................................... 195BufInsertChar...................................... 196BufInsertEOL...................................... 196BufInsertFile ....................................... 196BufInsertScrap .................................... 197BufInsertStr......................................... 198BufSetAutoIndentMode ...................... 198BufSetBackupSpec.............................. 199BufSetGlobalBackupSpec................... 200BufSetTabStr....................................... 201BufSetTabUsage ................................. 202BufWrite ............................................. 203BufWriteFile ....................................... 203BufWriteSelection............................... 204CenterLine........................................... 204CheckIn ............................................... 204CheckInBuffer..................................... 206CheckInSetCmd .................................. 206CheckOut ............................................ 207CheckOutBuffer .................................. 208CheckOutSetCmd................................ 209ClipboardEnableSepStr....................... 210ClipboardSetSepStr............................. 211

ColorCommandLine ............................211Color....................................................212ColorError ...........................................213ColorMessage......................................214ColorWarning......................................214ColorWarning......................................215ConfigFileRead ...................................215CWHelp...............................................216DefaultKeymap....................................217DeleteNextWord..................................217DeletePrevWord..................................218DisplayFileName.................................218Dlg.......................................................218DlgMenuPopup ...................................220DlgMenuExec......................................221EditNextBuffer ....................................221EditPrevBuffer ....................................221EdVersion............................................222ErrKmapAssign ...................................222EvalStrAdd..........................................223EvalStrDel ...........................................223ExecApp..............................................224ExecCommand ....................................224ExecUserCmnd....................................225ExecuteMacro......................................226ExtAddKeyword..................................226ExtAlias...............................................227ExtAssignTemplate .............................228ExtColors.............................................229ExtColorsAssoc ...................................229ExtCommentSearchLimit ....................230ExtDelayedColoring ............................231ExtExpandTemplate ............................231ExtIndentEnable ..................................233ExtIndentEnableAssoc ........................233ExtKmapAssign...................................234ExtReadKeywordFile ..........................235ExtReadTemplateFile ..........................235ExtSetDelimiters..................................236ExtSetStyle ..........................................237ExtSetTemplateMacro.........................238

vii

Table of Contents

ExtSetUpdateDelay ............................. 238ExtSetWrap......................................... 239FFind................................................... 240FFindFile............................................. 240FFindNext ........................................... 241FFindPattern........................................ 241FFindShow.......................................... 241FGrepFile ............................................ 242FGrepFlags.......................................... 242FGrepNext........................................... 243FGrepPattern ....................................... 243FGrepScope......................................... 244FGrepShow ......................................... 244FileTabs .............................................. 244FilterAdd............................................. 245FilterDeleteList ................................... 246FontSelectMsg .................................... 246GotoLine ............................................. 246InsertMode .......................................... 247ISearch ................................................ 247KeyPlayback ....................................... 247KeyRecord .......................................... 248KmapAssign........................................ 248LibAutoLoad....................................... 249LibFunctionReplace ............................ 250LibPreLoad ......................................... 251LibUnLoad.......................................... 252Lower .................................................. 252MarkGoto............................................ 252MarkRestorePos.................................. 253MarkSavePos ...................................... 253MarkSet............................................... 253MenuCmnd.......................................... 254MenuCommand................................... 255MouseLeftDClick................................ 255MouseLeftDown.................................. 255MouseRightDown ............................... 256MovDown ........................................... 257MovEndWin........................................ 257MovEOF ............................................. 257MovEOL ............................................. 258

MovHome............................................258MovLeft...............................................258MovNextChar......................................259MovPageDown....................................259MovPageUp.........................................260MovPrevChar ......................................260MovRight ............................................261MovTopBuf.........................................261MovTopWin........................................261MovUp ................................................262MsgLevel.............................................262MsgMessage........................................263MsgPauseOnError ...............................264NextWord............................................264OutputFile............................................264OutputWindow ....................................265Paste ....................................................265PrevWord ............................................266Print .....................................................266PrintFlags ............................................266PrintFooter...........................................267PrintHeader .........................................268PrintLineInc.........................................268PrintLineInc.........................................269PrintMargin... ......................................269PrintSelection ......................................270QDefaultKeymap.................................270Redo ....................................................271Repeat..................................................271ResizeWindow.....................................271ScrapNext ............................................271ScrapPrev ............................................271ScrapSetCount .....................................272SelectWord..........................................272SetLineDrawBindings .........................272SetLineDrawStyle................................273SlideIn .................................................274SlideOut...............................................274Space ...................................................275SrchFind ..............................................275SrchQFlags ..........................................276

viii

Table of Contents

SrchSetFlags........................................ 276SrchTranslate ...................................... 277StateSetMarkLevel.............................. 278SysBeep............................................... 279SysCaretHeight ................................... 279SysCaretWidth .................................... 280SysExit ................................................ 280SysQFlags ........................................... 281SysSetCwd .......................................... 282SysSetDefault ...................................... 282SysSetFlags ......................................... 283SysSwapBlocks ................................... 284Tab ...................................................... 285Tabs..................................................... 285TagFind............................................... 286TagIgnoreCase .................................... 286TagPrompt........................................... 287TagSetFile ........................................... 287ToBottom............................................ 288ToTop ................................................. 288Undo.................................................... 288Upper .................................................. 289Visibles ............................................... 289WinScrollHInc .................................... 289WinSetCreationPos ............................. 290WinVisible... ....................................... 291WinVisibleMarginColumn.................. 292WrapEnable......................................... 292WrapParagraph ................................... 293WrapSetRightMargin .......................... 293WriteBuffer ......................................... 294ZoomWindow ..................................... 294

CHANGING AND EXTENDINGCODEWRIGHT.................................... 295

System Overview ................................ 295Core Services ...................................... 296

CWSTART DLL............................. 296CWDIALOG DLL .......................... 299CWHELP DLL ............................... 299

Keyboard Command Sets.................... 299

Supplemental Language Support .........300Auxiliary Services ...............................301Sample DLL ........................................302Dissecting a Codewright DLL .............302

The _init Function ...........................302Exporting Functions ........................303

Making Changes and Additions...........303Changing Existing Functions...........303Adding Your Own Functions...........304

Creating New Keymap Command Sets304Keymap _init Function ....................304Keymap Function ............................305Flag Initialization ............................305Basic Assignments...........................305Keymap Specific Assignments ........306Menu Accelerators ..........................306

Recompiling a DLL.............................306Using and Modifying the Makefiles 306Compile and Link Options ..............307Link Libraries ..................................307

Using Your Own DLL.........................309Installing Your DLL ........................309

INDEX....................................................311

ix

Introduction

Codewright is, in large part, an editor. It is the first professional quality, extensible,programmer's editor written from the ground up for Windows. Codewright is also your"Central Command". From it you issue commands to your generals in the field: yourcompiler, version control system, operating system, and more. Codewright blendspowerful productivity tools and Windows resources with a command shell. The result iseminently usable.

What Makes Codewright Different?

Here are some of the things that make Codewright different from other editors:

• Codewright is not a port of a program from DOS, Unix, or any other operatingsystem.

• Codewright is the innovator. Here are just a few of the innovations Codewrightbrought to programmer’s editors under Windows:

Syntax Highlighting (ChromaCode), DLL extensibility, Merge and Difference,elided text (Selective Display), Help Manager, IDE integration, API Assistance,Button Links, HTML viewer, and MVB file support.

• Codewright is from Premia Corp. This ensures you of the best satisfactionguarantee and the best support available.

• Codewright for Windows – Just Windows. Porting to other platforms wherethere is little demand for a Windows editor slows development, and degradesperformance. By doing just one platform well we avoid having to charge you forill-advised marketing forays.

What Makes Codewright Different?

x

Basic Strategy

Most professional programmer's editors use the same basic strategy. They provide theprogrammer with the following:

• An editor engine to perform basic tasks.

• An extension language in which higher level functions are written.

• An interpreter built into the editor to interpret functions written in the extensionlanguage and to accept user commands.

• An extension language "compiler" to turn extension language source code intosomething the interpreter can use.

• An extension language debugger to debug the extension language source code.

Codewright needs just one of these five components: an editor engine to perform basictasks. Yet it provides the same capabilities and more. To be properly designed forWindows, Codewright had to avoid the weaknesses of Windows while taking advantageof its strengths. That meant using a different basic strategy.

User Compiled DLLs

Many editors tout their "C like" extension language. Some say their extension languagedebugger is a lot like the one you are using now. They don't want you to worry about howhard it will be to learn to write extensions to their editors. You are most familiar with thetools you use for your regular software development, so they imitate those tools as muchas possible. We say, better yet, use your regular compiler and debugger. We'll supply thesource code, and make it easy for you to change the editor.

Well, not all the source code. Just the source code you need to recompile many of theDynamic Link Libraries (DLLs). Write your extensions in C, use your compiler andlinker to rebuild the DLL, and use your debugger if your extensions don't work asexpected. For those who use a Windows compatible language other than C, just createyour own DLL that can be loaded and used by Codewright. For most users, nothing couldbe more natural.

This architecture does not preclude a macro language. In fact, it allows for the possibilityof many.

Key Editor Features

xi

Key Editor Features• Unlimited Undo and Redo of commands.

• Line length and file size virtually unlimited.

• Optional auto-save at scheduled intervals or during idle periods.

• Interactively definable Toolbars for quick mouse access to common commands.

• Complete support of regular expressions in searching and replacement, includingsearches across multiple lines and replacement groups.

• Configurable and Extensible through configuration file and DLLs.

• Hex mode for editing binary files, including inserting and deleting bytes.

• ChromaCode™ use of color to signal changed lines or highlight language syntax.

• Flexible multiple-window, multiple file interface. Edit as many files in as manywindows as your resources allow.

• Selective Display mode for selecting which lines to make visible or invisible.Allows selecting lines to be viewed with grep-like commands, or bypreprocessing #ifdefs -- you name it.

• CUA, Brief, Epsilon, or vi style key commands.

• Multi-document or file-based search and replace.

• Completely remappable keyboard -- Create your own command set.

• Special integration with Compiler Environments including Borland’s C++ IDE,Microsoft’s VC++ Workbench, Borland’s Delphi, and Watcom.

• Uses features of Windows , including Common Dialogs for familiar operation,Drag and Drop for convenient file loading, E-mail integration, and TabbedDialogs (property sheets) to simplify dealing with settings and options.

• Button Links let you reference and view external documents, such as diagramsand word processor files, or organize notes into a To Do list. These itemsappear as graphical buttons within the text file.

• Extensive per-window, per-file and per-file type configurability.

• Side-by-side Differencing, Difference Editing, and Merging of files.

• Allows unlimited local and global bookmarks.

About the Manuals

xii

• Powerful Templates for language constructs, personalized function headers andmore. Any API function that can be executed interactively can be executedwithin a template.

• API Assistant helps you accurately complete function calls by showing you thetypes and options for each parameter defined for the function. It then assemblesthe proper call for insertion into your text.

• Multiple scrap buffers allow copying more than one item for later use withoutoverwriting previous items.

• Spell checker that lets you check the spelling of just source code comments andstrings, if you like. Spell check the whole buffer, or just the selection.

• Offers several types of browsing, including Tags, Microsoft .BSC files, andOutline Symbols.

In short, you'll find Codewright to be the most powerful editing environment available onany platform.

About the Manuals

Two manuals are supplied with Codewright Professional: this User’s Guide and a smallerGetting Started guide. Use the Getting Started guide to install and begin usingCodewright Professional, and later use this manual to learn how to take full advantage ofthis unique product.

Using this Manual

Due to the advantages of hypertext links and pop-ups over flipping pages, we have putsome things in online help and other things in the manuals. While there is some overlap,we expect that you will rely on the online help for details of using the dialogs andCodewright’s own API. This manual contains more general reference and “how to”information.

This manual is divided into two parts. The first part provides reference on many of thethings you can do with Codewright Professional. The second part describes functions thatyou may use to make key assignments or to use in Codewright Professional’s initialization(.INI) file. It also contains an introduction to extending Codewright through your ownDLLs.

Typographical Conventions

xiii


Becoming familiar with a few typographical conventions used in this manual willaccelerate your understanding of the information presented. Several different typefacesare used to signal specific purposes.

Courier Courier typeface is used to indicate something you might see on themonitor, such as a prompt, something you are asked to type, or thecontents of a file. When a combination of a prompt and user input isshown, the response portion will appear in bold, as shown below:

Command: just_do_it

Times Bold The Times Bold typeface is used for keywords and function names.

Times Italic Times Italic is used for names of parameters that you supply. It is alsooccasionally used for emphasis.

)6 Keystrokes are usually described using pictures of the keys which must

be pressed. The example to the left depicts the control and shift keysand the right mouse button, all being pressed at the same time.


xiv

Editor Highlights

Codewright contains many fine features. Some of these, such as search and replace,version control, and projects, merit chapters unto themselves. Other equally importantfeatures require less description, and are described in this chapter.

API Assistance

You will find on the help menu the item “API Assistance on...” This item will provide youwith help in completing a call to a subroutine or function, if such help is available.Currently, help is provided on the Windows API, Standard C Library functions, MicrosoftFoundation Classes, and the Codewright API.

Using the API Assistant

You begin using the API Assistant by selecting API Assistance On from the help menu.If there is a word near the cursor when you do this, Codewright will attempt to locateassistance for that word. If no word is nearby, you are prompted for a subroutine orfunction name to look up. If more than one occurrence of the word is found, you areprompted to select from those found.

You are then presented with a form to fill out. There is an edit box or set of checkboxesfor each parameter used by the subroutine or function. The parameter type is listed byeach edit box or set of buttons. This makes it simple to ensure that all necessaryparameters are supplied, and are of the correct type. If you need additional information,press the Help button and you will see the Windows API Help entry, or other helpfileentry, for that subroutine or function.

When the form is completed, press OK and the information you have provided isassembled into a complete function call, including commas and parentheses, and isinserted into the document. Using the API Assistant, it is hard to go far wrong, and youspend less time doing it.

API Assistance

2

Using the Checkboxes

The use of checkboxes in the API Assistant is usually associated with a numericparameter, such as an integer. The values you check, as represented by the predefinedlabels, are ORed together in the resulting function call. If you are not familiar with thelabels you require, press the Help button and locate the descriptions in the related helpfile.

Modifying the Database

One of the sample “tools” placed at the end of the Tools menu is the API DatabaseEditor. This lets you modify and make minor additions to any of the API Assistant’sdatabases. More serious modifications may best be done with the automation toolsdescribed below.

The database editor provides the primary method by which you may present a parameteras a series of choices, rather than a simple edit box. This assists the user in rememberingor selecting a reasonable value for the parameter, and tends to validate the choice.

The databases supplied as of this writing are described in the table below:

Filename DescriptionWINAPI.TDB Contains information about Windows API function callsCWAPI.TDB Contains information about Codewright API function callsMFC.TDB Contains information about Microsoft Foundation ClassesC.TDB Contains information about Standard C library functions

Automation Tools

A tool has been provided to take data, in one of several formats, and make entries in anAPI Assistant database. This enables you to automate the creation and update of an APIAssistant database for an API or library for which support is not provided.

You will need to create a method for getting the data into the proper format. This mightbe done using an AWK script on source files or DDE queries to InfoView. After doingthis, the automation tool will do the work of actually creating or updating the database,based on this information.

Browsing, Tags, and Outline Symbols

3

A description of the automation tools and how to use them is contained in the fileAUTOTOOL.TXT. You will find it in the directory containing the Codewrightexecutables.


Programmers have a need to investigate the code they edit. Whether you are working onsomeone else's C++ code with a long line of inheritance, or working on C code you wrotelast week, you can spend a lot of time investigating. Browsers and Tags programs havelong been available to assist with this aspect of programming. Codewright offers theseand another form of on-the-fly browsing we call Outlining that will reduce the time youspend being a detective.

Which Type of Browsing Should I Use?

The Codewright Browser uses Microsoft .BSC files that are produced when you compile.It uses a graphical tree to demonstrate relationships and simplify locating the file or otherinformation you need. If you are compiling with Microsoft tools this method gives youthe most information about your code. However, you must be able to compile the code,and the information is only as up to date as your most recent build.

The Codewright Tags support provides only limited information about your code –primarily the location of function definitions. You can access this information in twoways: you can use the same graphical interface as the browser, or a hypertext-stylelookup of the word at the cursor. This information, too, relies on you updating thedatabase regularly.

The Codewright Outline/Symbols feature may render the other two nearly obsolete. It hasits own graphical tree interface in the Outline Window tab of the Project Window. It usesthe Symbols Window, a tab on the Output Window, and background parsing to let youview the most up to date information about your project. In addition, users with aknowledge of regular expressions can readily add to the parsers provided.


4

Browser Support

The Codewright Browser supports two kinds or browser databases:

• Microsoft format .BSC databases These are the databases generated by MicrosoftC/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 theTAGSWnn utility shipped with Codewright. The nn in the name is replaced by 16 or32 depending on which version of Codewright you are running, 16 bit or 32 bitrespectively. The Tags databases are given the extension .PTG by convention.TAGSWnn is described in Appendix D of this manual.

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 Browsetab on the Output Window. The Browser is actually two windows side by side with itsown tool ribbon at the top. The Tree window appears on the left and the Inspect windowappears on the right.

Press � to receive help, press ; at any time to leave the Browser window and return

to the current edit window. To close the Browser window, select Browser again from theProject menu.


5

Selecting a Database

The first step in using the Browser is to select a database. If you have previously defineda valid .BSC or .PTG file for the current project, that database is loaded when you selectBrowse. You define the database for the project in the Project Properties dialog, on theDirectories tab. If you have not defined a database, or if you later want to changedatabases, you may select a database by choosing the File Open button on the Browserribbon.

Microsoft project makefiles can contain instructions that cause these databases to becreated 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 nodeto node, and by pressing the ( 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 inthe Inspect window to the right. This window will list information such as where the itemis defined and where it is referenced, if this information is in the database. You maymove between the Tree window and the inspect window by either pressing the 7 key or

clicking in the intended window.

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

Bitmap DescriptionRoot information coming from the database.Information pertaining to a file or module.Information pertaining to a class.Information pertaining to a function.A preprocessor macro definition.A type definition.Information pertaining to a variable.


6

The first file in the tree list will often be labeled <unknown>. These are functions andother objects that are referenced, but whose source was not compiled along with theproject. The most common examples of this are the use of functions in the MicrosoftFoundation Classes, or other libraries.

Browser Ribbon

Here is how the Browser Ribbon appears:

Refer to this diagram as you read the descriptions below.

Jump to Code

After traversing the tree, you will usually want to go to the corresponding source. Thereare two Go to buttons on the Browser Ribbon that allow you to do this. If you wish to goto 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 haveselected a reference, a calling or called function in the Inspect window, you may wish topress the key (Go to from Inspect) to go to that reference or function. Simplypressing the J 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 thedatabase. Use it to filter out extraneous information. It is one of the most useful featuresof 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 sensitivemanner, and a trailing wildcard will be assumed. That is to say, if you enter "dump", itwill match strings like "Dump" and "dumpFile".


7

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 theQuery button. You can initiate a query by pressing the button, or by pressing the Tkey. Depending on the context, one of six query dialogs will then appear. An exampledialog is shown below:

Each query dialog has a set of action buttons and filter check boxes. The filter checkboxes apply only to the action buttons that are enclosed in the same group box.Therefore, in the example above, the check boxes apply only to the Used By and Usesbuttons. 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 toomuch information to sift through to find what you are after. It is probably best to checkthe minimum number of boxes that fill your needs.

The six Query Dialogs are as follows:

Button PurposeGeneral 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.


8

Quick Search

The Quick Search button on the Browser Ribbon is for use when you are in a normal editwindow and want to look up the word at cursor in the browser database. This step savingdevice acts the same as if you had typed the word into the String Search combo box andpressed (.

Called By / Calls To

When you have selected a function in the Tree window, you may view either a list offunctions 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 afterjumping to the related source code (Go To). When this button is depressed, the Browserexecutes a forward search for the item selected in the Browser window from which itjumped. This is especially useful if you have modified the source code since the last timethe database was generated. The Browser may still be able to take you directly to the itemof interest.

Filter Toggle Buttons

The Filter Toggle buttons allow you to focus in on specific categories of objects byturning filters on and off. Each of the lettered buttons at the right of the browser ribbonhas an on and off position. When depressed, the button is on, and object associated withthat 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 thesebuttons by clicking on it with the mouse or by pressing the corresponding letter on yourkeyboard (i.e., IWPYF ).

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

Letter Filter ObjectsF Function references and definitions.T Type references and definitionsM Preprocessor macro references and definitions.V Variable references and definitions.C OOP Class references and definitions.


9

After changing the filter toggle settings, you will find that the new settings do not takeeffect until you have performed some action, such as opening a branch of the tree. To seethe effect of the filter change on a branch you are already viewing, collapse and re-expandthe branch.

Tags Support

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

In addition, Codewright comes with a built-in Tags database generation capability. Thisprogram produces both a standard Tags database and a compiled database The resultingcompiled database may be used with Codewright's Browser in a similar fashion to abrowser database. You can search the database and traverse its contents via a graphicaltree.

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

Codewright is known to be compatible with the PCTags program from Moderne Softwareand GNU Tags, the former of which is available for download from our bulletin boardsystem; the latter is supplied with Codewright.

Tags Setup

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

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

• Define what files will hold your Tags data -- your standard Tags database andyour compiled database for use with the Browser. These are the last two entrieson the Directories tab of the Project Properties dialog. Enter a filename in theBrowser database field that employs the .PTG extension rather than .BSC toavoid having the file overwritten by a browser database generator.


10

• 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 akey. The TagFind function looks at the word at the cursor and tries to find a match for itin the database. You can assign this function along with TagNext and TagPrev tokeystrokes, if they are not already assigned. You do this through the Keyboard dialog onthe Tools menu.

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

Outline Symbols

The Outline Window is a hierarchical view of symbols in Project files and any other filesthat are currently loaded. The references to symbols (usually function names, variablenames and the like) are kept in a database that is generated in the background as youwork. It does not rely on a database generated by compiling, and therefore works on codethat has never been compiled.

Parsers are provided for use with a variety of file types to generate the symbol databases.You can add parsers for use with the output window without compiling. An advancedknowledge of regular expressions, and some development effort is required, however.


11

Supported File Types

Parsers are available for the following file types:

File Type Parsers.BAS Declare, Function, Sub.C Function, Define.COB Section, Division.CPP Function, Define, Class.H Function, Define, Class.HTML Function.INI Section.JAVA Function, Class.PAS Function, Procedure.PRG Function

These parsers are also available to any file types that have been mapped to the ones above(e.g., .HTM is mapped to .HTML).

Using the Outline Window

The Outline Window uses the Symbols tab in the Output Window and an edit window tolet you investigate the code you are working with. In the window you will see a treestructure with a root for each of the files you currently have open. When you open eachroot, you will see a list of symbols found in that file, grouped by parser type.

Symbol Window

Clicking on a filename or root opens that file for editing. A single click on a listedsymbol shows references to that symbol in the Symbol Window tab of the OutputWindow. If there is just one reference in the symbols database, the source code at thatlocation is shown in the Symbol window. If there is more than one reference, a summaryof each reference is listed in the Symbol window. You can then select a reference ofinterest, and view that location in the source code by double clicking on that entry in thelist.

When you single click on a symbol listed in the Outline window, as described above, theview in your current edit window is not modified. This allows you to browse symbolreferences without losing your place. If you double-click on a symbol listed under one ofthe loaded files, your view in the current edit window moves to that location, in additionto listing references in the Symbol window.

Button links

12

Button links

Button links are special action buttons that Codewright lets you embed in your text files.You may use them to view bitmapped images, bring up a related document orspreadsheet, run a macro or just to make notes. To any other editor, it is still just astraight text file, and because the buttons are placed in comments, source code filescompile as they normally would.

How it works

You select the type of link and the text that will appear in the button. Codewright usesthis information to create an index entry for that text, and places it into the text file with aspecial 3 character prefix and suffix. Comment prefixes and suffixes are used as youindicate. The index entry refers to an entry in a database that indicates what the buttonlink does.

What you see

When you have turned on the View Links option in the Document Properties, you will notsee the 3 character prefix or suffix. Instead, you will see a 3D-style button containing thetext you specified, and a notation indicating what type of link it represents. Click on thebutton and the associated action is performed.

Defining buttons

When you select Insert Link from the Edit menu, you are presented with a dialog thatallows you to define a button link. You enter your button’s text (which must be unique),select the link type, and enter the appropriate text to be associated with the button. Thenature of the associated text depends on which link type you select.

Using buttons you can perform three different categories of actions:

Access to the Codewright API

The Template and Macro type links allow you access to the Codewright API.

• Templates -- Templates allow you to insert text, prompt, move the cursor, or executea series of actions. For templates, the associated text is the contents of a template toexecute, such as supplied to the ExtExpandTemplate function.

Button links

13

• Macros -- Macros allow you to execute any API command that is availableinteractively. The text associated with a Macro link is the function call. It is limitedto a single function.

Running external programs

The Document and Application link types allow you to run external programs.

• Document – The document link allows you to run the program associated with a filetype, to view or modify that document. The document might be a bitmapped diagramor a word processor file. In this case, the text associated with the button is just thefilename of the document.

• Application – The application link lets you define any arbitrary command line to beexecuted when the button is pressed.

Pop-up notes

Pop-up note links come in two flavors: standard notes and “to do” notes. These twotypes of notes are essentially the same. Providing two link types for notes, however, givesthe buttons a different appearance and allows you to sort “to do” notes separately fromother notes, when viewing the list of defined links.

View Links

The View Links dialog lets you see what links are currently defined in the database, letsyou edit their definitions, delete them, or go to the location in the file where the link isdefined. The tree shows the six different types of links available, and allows you to viewthe links of each type.

There is a folder on the tree representing each of the six types of links. When the folderappears disabled, this indicates that there are no links of that type defined. After youopen a branch of the tree to view the list of links of that type, you may select a specificlink. Once selected, you may edit the definition of that link by pressing the Edit button,go to the location where that link is defined by pressing Go To, or you may delete the linkfrom the database.

Mouse Commands

14

Note: Deleting a link from the database does not delete the button part of the link fromthe text file. This is something that currently must be done manually. If you do not dothis, your files and database will become out of sync.

Mouse Commands

You can probably guess most of the things that you can do with a mouse in Codewright:click on menus, select text and so on. There may be a few things that you wouldn't guessyou could do with a mouse, and other things that you might suspect you could do but donot know how to do. It is those things that we will be covering in this section.

Inclusive or Exclusive Selection

In all three standard keymaps, you can select text by clicking with the left mouse buttonand dragging the mouse across the area you want to select. In the CUA and BRIEFkeymaps, the block you define is exclusive, while if you are using the vi keymap, theblock is inclusive. That is, in vi the block includes the character at the cursor, but theothers do not.

Closed Selections

You may elect to have selections that you make with the mouse be either closed or openwhen 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 movethe cursor. Selections made with key commands usually are not closed. In this case, oneend of the selection is defined by the cursor position, and it therefore moves with thecursor. Your keymap may have a command to toggle a mouse selection or other selectionopen or closed. You can do this with the )D command in the BRIEF-compatible

keymap, and )� 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 thecursor position, wherever it happens to be.

The distinction between closed and open selections is not meaningful in the CUA keymapunless you have turned on persistent selections. Otherwise, CUA removes the selection,whether closed or open, whenever you execute an cursor motion command.

Mouse Commands

15

Column Marking

Making a column selection with the mouse is just as easy. Just click and drag with theright mouse button instead of the left. Column blocks are always inclusive, regardless ofwhich 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 spaceselects the line to the right. Clicking and dragging selects a series of lines -- even if themouse happens to stray from the margin.

Word Selections

As with many Windows editors, double clicking on a word makes a selectionencompassing that word. If you continue to hold down the cursor on the second click anddrag it around, you can select in units of words. You may be familiar with this method ofselection from one of several word processors.

Status Line Actions

There are a number of functions that you can perform just by clicking with the rightmouse button on hotspots on the status line. These actions are listed below:

Action DescriptionInsert/Overtype Toggle Toggle between insert and overtype mode by

clicking-right on the “Ins” or “Ovr” designation onthe status line.

Read-only/Read-write Toggle Toggle between Read-only and Read/write status byclicking-right in the box to the left of the linenumber. The box may be blank or have a “RO”designation in it. This toggles both file and bufferstatus.

Go to line Clicking-right in the Line number box brings up theGo to Line dialog.

Next Message Clicking with the right mouse button in the messagebox at the left of the status line will cause theprogram to process the next Build error message.

Mouse Commands

16

A related command is the right mouse click on the Ribbon Search combo box. This is onthe Standard Toolbar instead of the status line. A right click here brings up the SearchOptions dialog. This allows you to check or change the settings in preparation for usingthe 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 toits new location. To move the block, place the mouse cursor in the selection's highlightedarea and press the left mouse button. The cursor will change shape to indicate that a dragand drop operation has commenced. Continuing to press the mouse button, move themouse cursor to the intended destination.

The caret (text cursor) follows the mouse cursor, indicating where the destination wouldbe at any given moment. When the caret is at the intended destination, release the mousebutton and the selected text moves there. You perform a copy operation in the samemanner as a move, except that the ) key must be pressed when you initiate the

operation.

To cancel a drag and drop operation after it has been commenced, move the mouse cursorback over the selection and release the mouse button. A selection cannot be copied ormoved 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 toanother. Use mouse copy and move commands, described below, for those operations.

Disabling Drag and Drop

If you are unaccustomed to text drag and drop, you may find it annoying and want to turnit off. You can do this by editing the key bindings. Just follow the steps listed below:

1. From the Tools menu, select Keyboard.

2. Click on the Mouse tab at the top of the dialog. There you will see a series of buttonsfor each of the mouse buttons in three different columns. Press the Down buttonunder the heading Left and press the binding button immediately to the right of theKey Sequence 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 0and a 1 at the end of the key binding.

Mouse Commands

17

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 andmoving text with the mouse. You just select the text you want to copy or move, point themouse at the place you want it to go, and issue the proper mouse command. Thecommand for moving the selected text is ) . The copy command is )6 .

Sometimes, when you are moving or copying text, the source and destination of the textare too far apart to be viewed in the same window at the same time. You can still use themouse move and copy commands, if you find this method more convenient than usingeither one of Codewright's Scrap buffers or the Windows Clipboard. This is done byeither 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 samesource location to a single destination. In this case, viewing the source in one windowand 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 andthen scroll to the destination. The selection will scroll off the screen, but so long as youare 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 canselect whether selections made with the mouse are open or closed in the Environmentdialog on the Tools menu. Select the System tab.

Creating Windows with a Mouse

It is very easy to create windows of an arbitrary size and position when you are workingwith a mouse. This is the quickest way to open up a second window onto your currentbuffer, 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 currentlyoccupied by a window and clicking with the left button and dragging the mouse cursor toany other part of the client area. Whatever buffer was current previous to creating the

Mouse Commands

18

window is also made visible in the new window. This means you will have at least twowindows 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 theEnvironment dialog on the Tools menu. You will find it on the System tab..

Drag and Drop File Loading

The Drag and Drop feature allows you to load files into applications from the WindowsFile Manager. This is done by selecting one or more files listed in the File Manager, andthen dragging them with the mouse to a minimized application. When the mouse buttonis 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 addCodewright to the Load= statement in your WIN.INI file. You can then perform otherduties when you first start Windows, such as reading your mail. When you are ready towork with Codewright you can then use the File Manager to drag and drop theappropriate file onto the Codewright icon.

If you already have files loaded in Codewright, the files you drag and drop ontoCodewright will be added to those already being edited. Whether or not a window iscreated for each of the files dropped onto Codewright depends on your settings of theSystem Options. If windows are not created, the window that was current will contain thefirst file of those dropped.

Expand / Collapse

When you are using selective display mode, you can use a mouse for expanding andcollapsing sections of text as you might the sections of an outline. The mouse commandused for this is a double click with the right mouse button. See the description of"Selective Display" later in this chapter for more information about this use of the mouse.

Popup Menu

Whenever you click with the right mouse button, you get a popup menu in any of the fourstandard keymaps. (Not press and hold, but rather a quick press and release.) This popupmenu is context sensitive, presenting different items depending on whether you areclicking in a regular edit window, or in the output window; whether you have a selectiondefined or none defined. The Popup menu is described more fully later in this chapter.

Spell Checker

19

Making Mouse Assignments

You can also make your own assignments to mouse buttons and combinations through theKeyboard dialog on the Tools menu.

Selective Display

Selective Display mode lets you focus by hiding text that is not of current interest. Thetext is still there, but you don’t see it until you want to. There are several ways to selectwhat text to make visible. You can specify a pattern and hide lines that contain text thatdoesn’t match that pattern. In this case, the resulting view of the file looks something like“grep” output. You can similarly specify a pattern and hide lines containing matchingtext. There are also some other more complex operations predefined for your use. Youwill find all of these capabilities in the Selective Display dialog on the Text menu.

Using Selective Display

Just press ; when you want to restore the invisible lines. When you want to see just

the lines you have selected again, there's no need to re-enter the dialog and run thecommand again. Instead, just press &%F in the CUA or the BRIEF keymap, or �in the vi emulation.

In Selective mode, lines are preceded with a small button or icon. When this buttoncontains a plus sign, it indicates that there is text hidden following that line. You mayview the hidden text by double-clicking on the plus sign or pressing %( on that

line. The plus sign then turns to a minus sign, to indicate that the section has beenexpanded to show the "invisible" lines. Double-click on the minus sign or press%( again, and the section collapses again. You can also double click with the right

mouse button to expand and collapse hidden text.

Spell Checker

Codewright Professional's spell checker has a 100,000 word dictionary and some "code-smarts" that make it useful for a variety of purposes. It will help you keep reports, codecomments, and the messages your program displays looking professional.

Spell Checker

20

The Spell Check item appears on the Edit menu. The Spell check button will appear onthe Toolbox when it is enabled.

The spell checker relies on several dictionary files:

DICT.D Main dictionary data file.DICT.I Main dictionary index file.DICT.S Small word dictionary containing one and two character words.DICT.APP Application dictionary.DICT.U User dictionary.

All of these files, except for DICT.U, are placed in your Codewright Professional homedirectory during installation. The file DICT.U is created when you first specify that a newword is to be added to the dictionary.

Spell Check Dialog

The Spell Check dialog allows you to check the spelling of a word, the words in aselection, or an entire document.

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

Spell Checker

21

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

Restrict to Comments/StringsThis option is normally only available when you have a file loaded that has one of thefollowing extensions: .C, .H, .CPP, .HPP, .HXX, .CXX, .PAS, .INC, .ASM, .PRG, .SC.These represent the file types for which Codewright Professional understands commentstructures and string constants. It is then able to differentiate between comments, stringsand other code. When this box is checked, the spell checker operates only on the wordsin comments and strings.

Restrict to StringsThe option is the same as the one above, except that the spell checker limits itself tostrings only.

Check Document ButtonThe Check Document button initiates a spell check on the current document, using theselected options.

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

Next ButtonThe Next button initiates a spell check on the current document beginning at the cursorposition and continuing through the subsequent text. This button is useful when youmomentarily exit the spell checker to make manual corrections and then want to pick upthe spell check from where you left off.

Spell Correction Dialog

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

Replace withThe Replace with edit box displays the spelling that will replace the misspelling when youpress the “Correct” button. If you have elected to have the spell checker suggest possiblecorrect spellings, the spelling selected in the list box below appears here. You maymanually enter a spelling into this box or edit the word displayed.

Template Macros

22

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

Correct buttonThis button replaces the word displayed in the caption with the word in the Replace withedit box. The spell check then continues.

Correct All buttonThis button replaces the word displayed in the caption with the word in the Replace withedit box. The spell check then continues. If Codewright encounters the same misspellingagain, it will correct the spelling in the same way without further prompting.

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

Ignore All buttonWhen you neither want to correct the spelling of the word in the caption, nor want to addthe word to the dictionary, press this button. The spell check then continues. IfCodewright encounters the same misspelling again, it will ignore it.

Quit buttonThis button discontinues the spell check session. It may be continued later by selectingthe Next button on the Spell Check dialog.

Template Macros

Templates are useful in taking the drudgery out of repetitive tasks. The constructs used inprogramming lend themselves to a fill-in-the-blanks style of template. CodewrightProfessional supports this type of templates that are automatically triggered when youtype a designated abbreviation.

Codewright Professional's templates have a macro capability, however, that makes themthe most powerful in the industry. You may be leaving great potential untapped if youjust use templates for language constructs.

Template Macros

23

This section of the manual reviews how to create the type of template used for languageconstructs. It goes on to describe the advanced features provided by template macros.

Predefined Templates

Before you add or change a template, you need to know what templates are alreadydefined, and what there definitions are. Since templates are associated with a specificprogramming language, Codewright Professional associates them with file types used inthat programming language.

You can therefore view the templates defined for a particular file type by selectingTemplate tab of the Language dialog on the Document menu. Here, you can view theabbreviations 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 mentioned above. Thesecond method is to directly edit your configuration file.

If you choose to do this by directly editing your configuration file (CWRIGHT.INI), youcan 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 fileextension to associate the template with (e.g., .C, .SC...). The second specifies a word orabbreviation 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 CodewrightProfessional useful instructions. For example, most templates will take up more than oneline in the document. There is a need, therefore, to specify in the template string thelocations of new lines. In most templates, you will also want to specify a location wherethe cursor is to be placed after the template is inserted. Here is a table of the specialcharacters 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., \&, \@, \\ )

Template Macros

24

\t Insert a tab.

Here are some sample template strings, to give you an idea of how these specialcharacters 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 yourconfiguration file:

ExtAssignTemplate=".pas","proc","Procedure &();\nBegin\nEnd;"

This example adds a template for use when editing files with the extension .PAS. Whenthe word "proc" is typed, followed by a space, a template for a Pascal Procedure isinserted in the document. The cursor is positioned at the point where the name of theprocedure would be entered.

The ExtAssignTemplate function is described in the “Function Reference” part of thismanual.

Using Macros in Templates

You may have noticed the use of certain % macros in some of the existing templates usedfor language constructs. These macros can have a great many uses. For example, theyenable Codewright Professional to place braces differently, depending on the indentationstyle desired. You can even find uses for these Template macros independent oftriggering abbreviations and specific programming languages. You may wish to assign atemplate to a key or button. To do this, you need to use a function that interprets thesemacros directly. That function is ExtExpandTemplate.

You will find an example use of ExtExpandTemplate on the Toolbox. There are twobuttons that use this function to insert a header. One button inserts a module header, andthe 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, whichcontains 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

Template Macros

25

can also contain Template macros. The file FUNCT.TPL is also simple, and it containsjust one Template macro. To demonstrate the use of Template macros, we will add a fewmacros to this file. This is the contents of the file FUNCT.TPL:

/* ** %qEnter function name:$ * * PARAMETERS: * * DESCRIPTION: * * RETURNS: */

The second line contains the %q query macro, which requests the name of the function.

Here is the modified version of the same file:

/%rep*60 ** %qEnter function name:$ * * PARAMETERS: & * * DESCRIPTION: * * RETURNS: * * CREATED: %date %time * * BY: %eUSERNAME$ */

These are the macros that were added:

%rep This macro repeats the * character 60 times.& This specifies where the cursor should be placed at the end of the insertion.%date This inserts the current date.%time This inserts the current time.%e This inserts the value associated with the specified environment variable,

USERNAME. Again, the $ character is used to delimit the string.

Below is an example expansion of this template file:

/*********************************************************** ** MyFunc

Template Macros

26

* * PARAMETERS: * * DESCRIPTION: * * RETURNS: * * CREATED: 08/16/95 11:45:50 * * BY: milow *

These are just a few of the things you can do with template macros. A table containing acomplete list of the % macros available follows:

Macro form Description%col Num 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 lines, 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.

%line Num 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 different for each

extension. Any macros contained in these strings are also expanded. These

definitions are normally stored in your configuration file or CWRIGHT.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.

User-definable Popup Menu

27

%open Open a new line following the current. Similar to going to the end of the line andpressing ( .

%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 Professional API function call in FuncCall. This may be any

function that could be assigned to a key or otherwise executed through

LibFunctionExec.


The user-definable popup menu is a menu that is defined in a text file. You can changethe way the menu works by editing that file. The changes are effective immediately.There is no need to recompile anything or to restart Codewright -- just save the file andyour changes are effective.

The file that contains the popup menus is named CWRIGHT.MNU. Codewright looksfor this file in its home directory, usually along with the Codewright executables. Youwill find it there, too, when you want to modify it. A portion of CWRIGHT.MNU isshown below:

;----------------- Popup Menu sections -----------------

[Utilities]Quick Search ; SearchQuick-Check in ; CheckInBufferCheck out ; CheckOutBuffer 1-Match brace ; BraceMatch 1Match next brace ; BraceMatchNext 1-EnTab ; EnTabDeTab ; DeTab-Selective text ; BufSetCompactHexidecimal ; BufSetHexAscii-File comment ; ExtExpandTemplate %ffile.tpl$Function comment ; ExtExpandTemplate %ffunct.tpl$

Menu DefinitionSection

Pseudo-comment

Function toexecute


28

[pvcs]; This is a commentCheck &In... ; MenuCommand 0x1708Check &Out... ; MenuCommand 0x1709- This is a menu separator&Lock file ; DlgMenuExec [Lock]&Unlock file ; DlgMenuExec [Unlock]&Newest Rev ; DlgMenuExec [ReportRev]

Definition Sections

The popup menu definition file contains sections just like a Windows .INI file does. Eachsection begins with a section heading, a word or label enclosed in square brackets. Thelines that follow the section heading describe the menu items that will appear on thepopup menu, and what happens when you select each item from the menu. These arecalled item definition lines.

Item Definition Lines

There are two parts to each item definition line:

• the part that appears on the menu (menu item) and

• the part that tells Codewright what to do when the item is selected (functioncall).

The two parts of the definition line are separated by a semicolon. This may appear to be acomment, but it is not. We therefore call this a pseudo-comment. For a line to be acomment, the semicolon must be the first character on the line. The rest of the line is thenignored.

The part of the line in the pseudo-comment is the function call that Codewright willexecute when you select the menu item to the right of the semicolon. This function callmust be something that you could call through the Codewright function LibFunctionExec,or the API Command prompt. No variables, no nested function calls.

Item Hot Keys

You may use an ampersand ( & ) in the menu item portion of the definition line to definea hot key for the menu item. This follows Windows conventions for menu constructs:

Real Comment

Menu Separator


29

The letter following the ampersand appear underlined, and pressing that letter on thekeyboard selects the menu item.

Separator Lines

Any line in a definition section that begins with a dash indicates that Codewright shouldplace a separator line on the popup menu at that position. A line the full width of themenu will appear on the menu even if there is only a single dash on the line. Codewrightwill ignore the remainder of any line that begins with a dash.

Supporting Functions

There are two functions that support the operation of popup menus. They are as follows:

• DlgMenuPopup -- Use this function to assign a popup menu to a key or mouseclick.

• DlgMenuExec -- Use this function to execute other sections within theCWRIGHT.MNU file.

These functions are further described in the Function Reference portion of this manual.


30

31

Search and Replace

Codewright offers a relatively large number of methods of performing search and replaceoperations. Each has its own advantages under differing circumstances. Some work on asingle file when loaded into a document. Others work directly on the files on disk. Someare meant to be quick and simple while others are designed for power. To help youreview your alternatives, the description of these methods are collected together in thischapter.

The methods of search and replace discussed in this chapter are listed below:

• Search and Replace dialog• Incremental Search• Toolbar Search• Quick Search• Multi-source Search and Replace

In addition, the Search Options dialog influences the various methods of search andreplace described here.

Search and Replace Dialog

Search Settings

32

Search and Replacement Edit BoxesThe Search String and Replacement String edit boxes allow you to enter the pattern youwant to match and the replacement string. You may only enter a replacement string whenthe Replace radio button in the Action group has been selected. Both of these edit boxesmaintain a history of previous responses, which you may select by pressing the downarrow to the right of the edit box.

Save SettingsThis check box is provided to save you from having to make a trip to the Search Optionsdialog whenever you want to make a change to the search settings. Settings are notimmediately written to disk, however. Checking the box makes the current settings thedefault for the session. These settings are saved in the state file on exit, if you areemploying one.

Search Settings

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

Search OptionsThis group of check boxes allows you to turn various search attributes on or off. Theseinclude:

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

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

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

Replacement Options

33

• Whole word When the whole word box is checked, the pattern you are searchingwill not match strings that are only partial words. That is, the pattern must bepreceded and followed by one of the following:

Beginning of file or end of fileBeginning of line or end of lineSpaces or tabs

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

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

• Select matching string. This check box specifies whether the text that matchesthe search will be highlighted in a selection at the end of the search. Theselection 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 checkbox indicates whether the selection that encompasses matching text ismomentary or whether it is retained so that you may operate on it.

Replacement Options

The Range group of options is specific to the replacement operation.

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

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

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

Multiple Sources Search Dialog

34

Multiple Sources Search Dialog

The Multiple Sources Search and Replace Dialog allows you to define a search or replaceoperation that is not confined to a single document. You may elect to search through allloaded documents, through files that are members of the current project, or any arbitraryset of files.

Search and Replacement Edit BoxesThe Search String and Replacement String edit boxes allow you to enter the pattern youwant to match and the replacement string, just as you would in a single document search.Both of these edit boxes maintain a history of previous responses, which you may selectby pressing the down arrow to the right of the edit box.You may only enter a replacement string when the Search and Replace action has beenselected. If you elect only to search a series of files, rather than selecting the Replaceaction, you are selecting to perform a File Grep. A list of matches in the files specifiedwill appear in the File Grep tab of the Output Window. The line numbers and the linecontaining the matching text are also displayed. To move to any of the matches listed inthe message box, double click on it with the mouse, or select the matching line from thelist and press (.

Advanced Multi-source Search Options

You receive these options when you press the Advanced button on the Search andReplace dialog, or when you select Multi-source Search from the menu.


35

Current DirectoryThe Search and Replace dialog shows the directory that is current as you initiate thesearch.

• Browse Button If you are not in the desired directory, press the Browse buttonto select a new working directory for Codewright.

• Retain Directory After changing the directory, you may want that directory toremain in effect after you finish searching and return to editing. If this is so,check the Retain Dir box. If you just want the directory in effect for the search,ensure that this box is not checked.

Multiple Source Mode Selection

• Project This option lets you search through files that are members of thecurrent project.

• Documents only This option lets you limit the search to the list of currentlyloaded documents.

• Files and folders This option lets you search an arbitrary group of files in anyseries of folders. Enter a name for your search set in the edit box associated withthis radio button, or select from the list of previously created search sets.

File PatternYou may use the File Pattern edit box for quick, ad hoc searches that you are not apt torepeat. It lets you specify a file type or series of file types to search without associating itwith a search set name. While not as powerful as the Search list, it is simpler to use.Enter one or more wildcard patterns into this box. Separate multiple patterns with asemicolon.

The File Pattern supplements the selected items on the Search list, if any. You may add itto the Search list by pressing the Add button.

Note: The File Pattern, when specified, does not override the list of files in the Searchlist. If both are defined, the files in both the File Pattern and any selectedmembers of the Search list are searched.

Search ListThe initial contents of this box depends on which mode of search you have selected. Ifyou have selected Project mode, the box will list the files in the current project. If youhave selected Documents only mode, the listbox shows the list of documents currentlyopen. When you select Files and Folders, the list reflects the search set shown in the


36

Files/Folders combo box. It is usually a series of wildcard patterns. To edit the list, pressthe Edit button.

When you first select your desired mode, you will see that the entire contents of thelistbox is selected. If you wish to further limit the search or replace to a subset of the list,deselect the files you want to exclude.

Selecting Files from the ListClicking on a filename or wildcard pattern selects it for the search operation. You mayselect or deselect additional files or patterns by holding down the & button and clicking

on those members of the list. The Clear button allows you to start your selection processover again. If the list of documents you don't want to search is shorter than the list ofdocuments you do want to search, select the documents you want to leave out and thenpress the Invert button. All of the documents that were previously selected becomeunselected, while the unselected documents become selected.

Search SubdirectoriesCheck this box if you want the search to encompass the files in subdirectories of the pathsearched.

Edit Modified FilesIf you are performing a replace operation, you may wish to review the changes made, orat least to know which files were changed. Selecting this option lets you do this.Modified files are loaded for viewing and possible editing. This is a convenience whenyou plan to check the modified files into version control.

ThreadedChecking this box lets the search or replace operation proceed as a separate process. Youcan then proceed with other tasks as the search continues. In the case of a search only(File Grep) operation, the output window will be updated as matches are found. Withoutthreading, the matches would only be listed after the operation is completed.

Send Listing to Output WindowThis checkbox and group controls whether and what information is sent to Codewright’stabbed output window. It’s primary purpose is to let you see the results of Search only(File Grep) operations, but it can also be useful as a summary of replacement operations.

• List Filenames Only By default, the output listing contains the file and linenumbers of matches, along with the line of text in which the match was found.For a terse summary containing only the filenames in which matches were found,check this box.

Edit Search List

37

• Append to Listing To add to the information in the output window fromprevious searches, check this box. Otherwise, the contents of the output windowwill be reinitialized.

• List to File You may specify that the information about the matches found bestored in a file, and the name or that file. The default name is CWFGREP.___,which is created in your TEMP directory. You may specify another name if thedefault causes a conflict, or if you wish to save the output from the previous orcurrent operation, rather than allowing it to be overwritten. You may alsoredisplay the results of a previous search by specifying the name of the file inwhich you saved the results.

Edit Search List

File PatternEnter the file specification that you wish to add to the definition of the current Search Setin this edit box. Standard wildcard characters ? and * are allowed. Your pattern may beanything from *.c to k:\src\cw????.??v . You can enter several patterns at onceby separating them with semicolons. When you do so, each pattern is given a separateline in the list of patterns for the Search Set. Use the Add button to add the file pattern tothe Patterns list.

Patterns ListThis listbox contains source patterns already defined for this Search Set. The Search Setis the union of these patterns, rather than the intersection. Files are only searched once,even if they match several of the Search Set’s source patterns. Therefore, if the SearchSet contains the pattern *.* , other patterns are superfluous unless they contain a pathelement. Source patterns that do not contain a path element will apply to the currentdirectory.

Drive and Directory ListsThe drive listbox and the directory tree list box allow you to select the path you want toapply to the source set. This is only meaningful if the Include Directory checkbox ischecked when the Source Pattern is added to the Patterns list.

Include DirectoryWhen this box is checked, the drive and directory selected in the adjacent listboxes areautomatically added to the pattern specified in the File Pattern edit box as you press theAdd button.

Incremental Searching

38

List Editing ButtonsYou may Add, or Delete members of the Source Patterns list. The Invert and Clearbuttons assist you in selecting patterns on the list that you wish to delete. Invert reversesthe selection; those items that were selected become deselected and visa versa. The Clearbutton deselects all the patterns on the list so that you can start selecting from scratch.

Incremental Searching

Incremental searches can save time and typing. This is because Codewright searches forthe string as you are typing it in, rather than waiting for you to type in the whole word andpress (. Many times the search function finds the string you are looking for without

you having to type it all in. This results in a little savings of time and effort for you.

ISearch Function

The ISearch function performs the incremental type of search for you. It may already bebound to a key in your keymap, but if not you can easily add such a binding with theKeyboard dialog on the Tools menu. You can check the listings for your keymap in the"Key Commands" chapter of this manual.

You begin the search by invoking ISearch; press &%L in the CUA keymap, for

example. ISearch prompts you for the search string, and you begin typing. Keep in mindthat ISearch always searches in a case-sensitive fashion. The case of the characters youtype must agree with the case of the characters in the document, in order to match.

When you type the first character, ISearch moves to the next occurrence of that characterand highlights it. ISearch performs a search after each character you type, looking forthe sequence of characters you have typed thus far. If it doesn't find a match, it issues abeep, and the character you just typed is removed from the search string.

If you find you have mistyped, just backspace over the incorrect character or characters.As you remove characters from the search string, the cursor backs up to the position thatfirst matched the characters that remain. Delete the entire search string and you will findyourself at the position where the search began.

You cancel ISearch by pressing ;. At that time, the string you typed into ISearch is

added to the search response history to make searching for that string again moreconvenient. You may also use the Quick Search feature to search for the word that isnow at the cursor position.

Toolbar Search

39

Quick Search

The Quick Search facility is a function you can use to do an immediate search for theword at the cursor. In the default configuration, you will find this function assigned to the

button on the Tool Ribbon, and assigned to the &%T key combination in the

CUA keymap. Other assignments may be made, or readily changed.

Toolbar Search

"Toolbar Search" refers to the search capability built into the Tool Ribbon in the form ofa drop-down listbox control. This provides the most immediate, convenient way toperform simple searches.

To use the Toolbar Search, click in the Toolbar Search edit box and type in the string youwish to search for. This may be a regular expression pattern, if you have regularexpressions turned on. Toolbar Search honors all of the settings in the Search Optionsdialog. As soon as you press (, the search commences.

If Codewright finds a match, Toolbar Search will retain the focus. This gives you theopportunity to search again just by pressing ( again. Pressing anything else will

cause Toolbar Search to lose the focus, and you are then able to edit at the position wherethe match was found.

Toolbar Search maintains its own response history, to allow you to recall strings orpatterns you previously typed. These are available when you select the down arrow to theright of the edit box and the history list drops down.

40

41

Dockable Toolbars and Windows

Codewright supports a number of standard toolbars, as well as allowing for user-definedtoolbars. Any of these toolbars can be modified through a simple drag and drop interface.Select Toolbars from the Tools menu to select which are visible and which are not, or tomake any other modifications to your toolbars.

In addition to toolbars, dockable windows, such as the Output Window and the ProjectWindow are listed here. That is because they use the same docking system and can bemade visible or invisible – just like a toolbar – though they do not contain the same buttonsystem.

What Does Dockable Mean?

A dockable window or toolbar can either be attached to one of the edges of Codewright’sclient area, or it can be “free-floating”. When the window or toolbar is docked, it reducesthe client area, and does not overlay other objects. When free-floating, the window ortoolbar may be placed anywhere on the screen and may be resized to most any shape. Itwill, in all likelihood, partially obscure other objects, however.

Enabling and Disabling Toolbars

Once any dockable toolbar or window is enabled (visible), a shortcut is available forsetting the visibility status of any toolbar or dockable window. Click with the right mousebutton on any non-button part of the toolbar or window’s frame, and a list of currentlydefined toolbars and dockable windows will pop up. The ones preceded by checkmarksare the ones that are currently visible. You may change the status of any of those listed byselecting it from the list.

If no toolbars or dockable windows are currently visible, select Toolbars from the Toolsmenu, select the desired toolbar from the list and put a check in the Visible checkbox.Press the OK button and the toolbar will become visible.

Docking and Moving Toolbars and Windows

42

Docking and Moving Toolbars and Windows

You can dock or undock a toolbar or dockable window by double clicking on any non-button portion of its frame. If it was docked, it will become free-floating. If it was free-floating, it will become docked. The exception is when the toolbar or window has neverbeen docked before, and has no default docking location. In this case it won’t knowwhere to dock, and you will need to dock it manually.

You can manually dock and undock these objects by dragging them with the mouse.When you drag a free-floating toolbox or window to the edge of Codewright’s client area,you will notice a change in the mouse cursor. A small square with a plus sign in it willappear at the base of the arrow. This is to tell you that if you drop the object, it will dock.The outline of the object you are dragging will indicate what orientation it will take whendropped.

Dockable windows have a title bar, but dragging them by the title bar disables automaticdocking. This is so you can reposition free floating windows without accidental docking.Drag a dockable window by some other part of if its frame or part of its interior (otherthan a control) and it will automatically dock when over the edge of the client area.

To undock a toolbar or window, point the mouse at any non-button portion of the frame,press the left mouse button and drag the mouse. You will see an outline of the toolbar orwindow appear. Continue to drag the object away from the edge of the Codewright clientarea, and then drop it where ever you want it. You can then resize and reposition the free-floating toolbar or window at will. If you have multiple toolbars docked along a singleedge of the client area, you can use this drag and drop technique to change the order ofthe toolboxes.

Customizing Toolbars and Buttons

When you select Toolbars from the Tools menu, you receive a dialog with three separatetabs. Use the Select Buttons tab and Bindings tab to customize your toolbars.

Select Buttons

When you select the tab marked Select Buttons, Codewright enters a special mode. Thetoolbars are temporarily inoperative, but you can drag and drop buttons from the dialog toany toolbar, or even drag buttons from one toolbar to another. You may rearrange

Project Window

43

buttons by dragging and dropping within the toolbar. To remove a button, just drag it offthe toolbar and drop it away from any toolbar.

If you drag from one toolbar to another, the function bound to that button moves with it.If you drag from the dialog, the button receives the default binding for that button. Usethe Binding tab to view or modify these assignments.

Default bindings for each button are kept in a resource description file. For example, thedefault buttons you see in the dialog and their bindings are kept in a file namedCWBUTTON.BTN. It is formatted rather like an .INI file, and it tells Codewright aboutthe resources in the DLL file.

Bindings

The Bindings tab lets you change what each button does. You begin using it by selectinga toolbar from the listbox. You can then cycle through the buttons on that toolbar untilyou get to the one you want to change. The three edit boxes below the toolbar listboxcontain the bindings for each the button. The Text button only applies to buttonscontaining ordinary text – not bitmapped images. The Function Binding field contains thefunction call to be executed when the button is pressed. This function call must conformto the rules of LibFunctionExec, or calling it through the API Command Key. The ToolTip field contains the message that pops up when the mouse cursor pauses over thebutton.

Project Window

The Project window is one of the dockable windows provided with Codewright. Like theOutput Window, it contains several tabs that let you view different information about yourproject files and even other files. These tab are:

• File View Window

• Outline Window

• Bookmarks Window

• Open Window

Project Window

44

File View Window

The File View Window lists the files in the current project in hierarchical form, and letsyou operate on files or groups of files.

Getting Started with the File View Window

Select Properties from the Project Menu, and use the Files tab to add files to your projectdefinition. If you have more than a few files in your project, you will probably find ituseful to define some filters for your project, using the Filters tab. This allows the files tobe listed hierarchically in the File View Window, rather than just appearing as one longlist.

For example, let us say that a C language project consists of some .C files, some .H files,a .DEF file, a .RC file, and a .MAK file. You could divide these into three groups bydefining three filters:

Description File Spec.Source files *.cInclude files *.hOther files *.*

Set up this way, you would see three headings in the Project window, Source files,Include files and Other files. The *.c files would be listed under the Source Files heading,the *.h files would be listed under the Include Files heading and the rest of the files wouldbe listed under Other Files.

Because of the order in which the filters are defined, the Other Files category only liststhe .DEF, .RC and .MAK file. Files are listed only once. If there is any overlap in thefile specs of two filters, the intersection will appear in whichever filter category is listedfirst.

File Icons

Each file listed in the Project window is preceded by an icon. These icons tell yousomething about the files. An icon that looks like a page with the corner turned overrepresents a normal read/write file. If the file is read only, the icon appear in light gray or“disabled” colors. If the file is not present at the specified location, the icon is followedby an exclamation point.

Project Window

45

Operating on the files

You may select any number files listed in the Project Window, using the rules for multipleselection listbox – click on a single file, shift click a range of files, or add to the currentlyselected file with control click. After you have selected the desired files, just press (to load them for editing. For a list of other operations available, click with the rightmouse button on one of the selected files.

Set up this way, you would see three headings in the File View Window, Source files,Include files and Other files. The *.c files would be listed under the Source Files heading,the *.h files would be listed under the Include Files heading and the rest of the files wouldbe listed under Other Files.

Because of the order in which the filters are defined, the Other Files category only liststhe .DEF, .RC and .MAK file. Files are listed only once. If there is any overlap in thefile specs of two filters, the intersection will appear in whichever filter category is listedfirst.

Outline Window

The Outline Window is a hierarchical view of symbols in Project files and any other filesthat are currently loaded. The references to symbols (usually function names, variablenames and the like) are kept in a database that is generated in the background as youwork. It does not rely on a database generated by compiling, and therefore works on codethat has never been compiled. For many users, this will replace the normal uses of aBrowser.

Parsers are provided for use with a variety of file types to generate the symbol databases.You can add parsers for use with the output window without compiling. An advancedknowledge of regular expressions, and some development effort is required, however.See the Symbols tab of the Document Language dialog for further information.

Using the Outline Window

The Outline Window uses the Symbols tab in the Output Window and an edit window tolet you investigate the code you are working with. In the window you will see a treestructure with a root for each of the files you currently have open. When you open eachroot, you will see a list of symbols found in that file, grouped by parser type.

Project Window

46

Symbol Window

Clicking on a filename or root opens that file for editing. A single click on a listedsymbol shows references to that symbol in the Symbol Window tab of the OutputWindow. If there is just one reference in the symbols database, the source code at thatlocation is shown in the Symbol window. If there is more than one reference, a summaryof each reference is listed in the Symbol window. You can then select a reference ofinterest, and view that location in the source code by double clicking on that entry in thelist.

When you single click on a symbol listed in the Outline window, as described above, theview in your current edit window is not modified. This allows you to browse symbolreferences without losing your place. If you double-click on a symbol listed under one ofthe loaded files, your view in the current edit window moves to that location, in additionto listing references in the Symbol Window.

Auto-Expand/Collapse

When this checkbox, at the bottom of the Outline Window, is checked, changing from onedocument to another will close one list of symbols and open another for the newly currentdocument. This saves a step when you want to view or jump to a symbol location. Whenthe box is not checked, you control when the symbol lists open and close.

Supported File Types

Parsers are available for the following file types:

File Type Parsers.BAS Declare, Function, Sub.C Function, Define.COB Section, Division.CPP Function, Define, Class.H Function, Define, Class.HTML Function.INI Section.JAVA Function, Class.PAS Function, Procedure.PRG Function

Project Window

47

These parsers are also available to any file types that have been mapped to the ones above(e.g., .HTM is mapped to .HTML).

Bookmarks Window

The Bookmark Window gives you a view of local and global bookmarks defined in yourdocuments. Clicking on a bookmark moves you to the bookmark’s document andlocation. Although the bookmark database may contain bookmarks for files that are notloaded, only bookmarks found in loaded documents are listed. The contents of thebookmarks database, and other bookmark options are found on the Bookmarks Tab of theDocument Preferences dialog.

Global Bookmarks

Global bookmarks are listed under that heading, regardless of in which document they arefound. The entry for the global bookmark shows:

• the bookmark number,

• its name, if one was given, and

• the name of the document in which it is found.

Local Bookmarks

Local bookmarks are listed under the name of the document in which they are found. Theentry shows:

• the bookmark number,

• its name, if one was given.

Double clicking on the document heading makes that document current.

Auto-Expand/Collapse

When this checkbox, at the bottom of the Bookmark Window, is checked, changing fromone document to another will close one list of symbols and open another for the newlycurrent document. This saves a step when you want to view a list of bookmarks. Whenthe box is not checked, you control when the bookmark lists open and close.

Tabbed Output Window

48

Open File Window

The Open File Window is like a persistent File Open Dialog and a file manager in one. Ita list of icons representing valid drives from which to choose, a directory tree, a place tospecify a file filter to limit the files displayed, and a box where matching files are listed.Just double click on any of the files listed and Codewright loads it for viewing or editing.

But opening files is just the beginning. There are a total of 17 other operations that youcan perform, as represented by a series of icons appearing on the window frame. Thereare tool tips, small popup messages, that describe each of these. Two of these icons areuser definable commands, and you can select which icons are displayed, as well asdefining the user commands in the Configuration dialog. The icon that invokes theConfiguration dialog is the last in the series of icons.

The user commands must be Codewright API function calls, rather than DOS commandsor the like. You may, however, execute DOS commands by specifying the API functionExecUserCmnd.

Example:

ExecUserCmnd “Dir”

In the Configuration dialog, you will also note that you can elect to view hidden files, filetimestamps, file sizes and file attributes. The timestamps, file sizes and file attributesonly become visible as tooltips, when you pause the mouse cursor over a file in the listbox.


There are a number of windows in Codewright that are not normal edit windows. Theycontain such things as output from a compiler or OS command, and require specialtreatment. Codewright has a special output window for these purposes. This sectionpresents some of its special features.


49

The Codewright output window may be opened explicitly, by selecting the Output itemfrom the Window menu. There may be little to view in the output window, however, untilyou use one of the features that relies on it. If you use one of these features, the outputwindow will open automatically when needed.

Initially, the window uses the bottom portion of the Codewright client area, andeffectively reduces it. This is its “docked” mode. It is convenient when you don’t wantedit windows overlapping the Output Window. You can view the output window and thefile you are editing at the same time.

Select View via Tabs

In a sense, the Codewright output window is several windows of which you can view anyone at a time. At the bottom of the Codewright output window, you will note a series oftabs similar in appearance to those you might see on file folders or dividers. These allowyou to select between compiler output, File Find, or other output just by clicking on thedesired tab. Predefined tabs include:

• Build,

• File Find,

• Search,

• Browse,

• Difference,

• VDOS Shell, and

• Symbols.

VDOS

50

Associated Dialogs

You can invoke the associated dialog for several of these output windows by using themouse to right-click on the tab. The tabs that you can click on and their associateddialogs are listed below:

Tab DialogFind File FindSearch File GrepDifference File DifferenceSymbol Symbol Menu

The Search dialog also can perform File Greps and sends output to the Search Tabwindow. See also Browser Support. See the description of VDOS for further informationabout the Build and Shell tabs.

VDOS

VDOS is a command shell that runs in a Codewright edit window. This facilitates cut andpaste, re-executing commands and more.

When VDOS is activated, it will intercept output from Compile, Make, Rebuild and otherproject commands, and put it in the Build buffer. Checking the “No shell” box next to anyof 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 mostthings you might do in a DOS box using the Shell buffer, but there are a few specialkeystrokes that are also available:

• Highlight part of a line and press ( to execute it as a command.

• Highlight part of a line and press )( to copy the text to the command line

at the end of the buffer for editing or use in a command.

• Press 68 or )F to copy the current selection to the clipboard.

VDOS has been tested for compatibility in a number of configurations. It appears to becompatible with Windows for Workgroups V3.11, even with 32 bit disk and file accessturned on.

VDOS

51

You may view either the Build or Shell buffer by selecting the appropriate tab onCodewright’s tabbed output window. When you first select the Shell tab on the outputwindow, Codewright will automatically activate VDOS.

• If you are running Windows 3.x, the first time you use VDOS, it will offer tomodify your SYSTEM.INI file for you to add a reference to the VxD in requiresunder 3.x. If you would like to do this yourself, just add a line like the onebelow 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 thename of that directory for the one shown above. After adding this line, you willneed to restart Windows for the change to take effect.

• Remove references to other redirectors from your command lines when you useVDOS. Programs such as FTEE are not compatible with VDOS.

52

53

Language Features

Codewright Professional's Language features are settings and support that vary with theextension of the file that you are working on. For example, you may want Word Wrap todefault to "on" in files with the extension .TXT, but not in files with the .ASM extension.

Many features can be turned on or off for any type of file you may be using. There aresome features, however, that will only work for languages for which there is built-insupport. Language templates and ChromaCoding, for example, require built-in support.You can create built-in support for additional languages, but this is not something you cando on the fly.

Document Settings

Since extensions apply to files, and files are loaded as documents, you will find that mostextension specific features are document settings. In Codewright Professional there aretwo dialogs for document settings, both on the Document menu: the DocumentPreferences dialog and the Document Language dialog. Since you will find some of thesame settings in both of these dialogs, you should note that the difference between theoverlapping settings is largely a matter of scope.

You control the settings for the current document, the default settings, and all user defineddocuments by selecting the Document Preferences dialog. Use the Document Languagedialog to create settings that effect all documents of a certain file type, as indicated by itsfilename extension.

Document Language Dialog

When you select the Language dialog from the Document menu, you are looking at thecentral jumping-off point for controlling Codewright Professional's Language features.

Associating File Types with a Language

Before you start your Language configuration, you should consider if you will need to addor extend language features to file types that Codewright Professional doesn't know about.

Other File Type Specific Settings

54

By default, it 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?

The first thing to do in the Document Languages dialog is to make sure that all of the filetypes you expect to be working with are listed in the list box on the left of the dialog.You do this by pressing the New Type button, and then entering the file extension orextensions in the edit box presented. Next, make sure that Codewright knows whatprogramming language they are associated with by mapping the new file types to onesthat Codewright is familiar with. Use the Map Type To button to perform this task. Onceyou have done this, the settings in your new file types will mirror those of the type theyhave been mapped to.

Other File Type Specific Settings

Almost any setting can be made specific to a certain file type. If you don’t see the settingin the Language dialog, you can often place a function call directly in the Extensions file.

Your extensions file may be your configuration file, your project file, or another file ofyour choosing. If you don't know which it is, it is probably your configuration file, but tobe sure, check the Store tab on the Document Language dialog.

Editing the Extensions File

As an example, we will imagine that we wish to make the right margin mark extensionspecific. This is the visual indicator of where a specific column is on the screen. It isgenerally used as a marker for Word Wrap, when Word Wrap is turned on, but it is alsouseful if you have to follow a coding standard. It reminds you not to make lines too long.

Language settings are stored under headings that incorporate the extension to which thesettings apply. The heading we are looking for in our example is [Extension.txt], which isfollowed by settings that apply to files with the extension .TXT. If you made othersettings through the Language Settings dialog for files with the extension .TXT, thosesettings will also be listed under this heading. If the heading does not already exist, justcreate it. Here is how the section might look when we are through:

[Extension.txt]WinVisibleMarginColumn=70

C Language Support

55

This sets the right margin mark at column 70, for files that have the extension .TXT. Thisleaves a little margin for our friends who are stuck in 80 column mode.

What can you make file type specific? Most things. Just follow this guideline: if youcan't set it as a document or window default, don't try and make it extension specific. Inthat case, it is probably global, and turning on for one extension will turn it on for all. Forexample, don't try setting the color of warning messages differently for .C files. It willchange the color for all warning messages.

Function Definitions Outline

One handy language specific feature is the ability to collapse the body of your functionsor subroutines so that you are just looking at a list of function definitions. It is similar tousing an outliner in a word processor to look at headings. Then, when you have located afunction of interest, you can view the full text of the function at will.

This works for a number of different languages. You can access this feature through theSelective Display dialog on the Text menu.

C Language Support

This section contains description of some functions and features that are specifically for Cand similar or related languages. These things are not language sensitive, however, sincethey operate the same way regardless of the extension of the file on which you are usingthem.

Brace Matching

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

• check the current buffer to see that braces are balanced. This form is useful forchecking syntax.

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

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

C Language Support

56

These services are performed by functions assigned to keys or buttons. You may wish tocustomize these assignments or make new assignments. Key assignments may be madethrough the Keyboard dialog on the Tools menu. Button assignments may be madethrough the Toolbars dialog also on the Tools menu.

Brace FunctionThere is a function supplied with Codewright that processes the current buffer, lookingfor unmatched curly braces. By default, the function will ignore any curly braces it findsin C language comments within the file. You can specify that all braces within the file areto be matched.

You invoke the Brace function through the API Command Key. By now, you know thatthis means pressing � in the CUA keymap and� in the BRIEF-compatible keymap. Ifyou are using another keymap, you may have to select API Command from the Toolsmenu.

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

Command: Brace TRUE

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

The function shows its progress by displaying the number of the line it is processing onthe status line. If the function finds an unmatched curly brace, the cursor is positioned onthat curly brace.

Brace HighlightingThere are two functions that help you examine or operate on the text between matchingcurly braces and parentheses. Both of these functions are available on the CodewrightEdit toolbar, 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, thisfunction will find pairs nested within the highlighted set, or a pair following thehighlighted 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 atthe cursor is a left brace or parenthesis, the function searches forward for its mate. If it isa right curly brace or parenthesis, the function instead searches backward for the mate. If

C Language Support

57

neither a left nor a right parenthesis or brace is at the cursor position, the functionsearches forward for the next matching set.

Note: Since BraceMatch looks at the current cursor position, it is not effective forhighlighting 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-zeroparameter to either of these two functions will cause it to look for matching parentheses inaddition to curly braces.

Brace LocatingThe function BraceFind is provided to allow you to locate the brace, parenthesis, orsquare bracket that is the mate for the one at the cursor position. It does not create ahighlight, but just positions the cursor at the corresponding object. This function is alsoavailable on Codewright's Edit toolbar.

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

Pre-processed View

This feature is for C users that find their source files cluttered with #ifdef s. Now youcan see your source code exactly as the compiler will see it, while you are editing it.Thanks to Selective Display Mode, the whole file is still there, but you don't have to lookat the parts that don't apply. Just create your "defines" in the [Definitions] section of theconfiguration file, or interactively. Then use the Preprocess function in the SelectiveDisplay dialog and soon you'll be seeing just what you need to see. You’ll find this dialogon the Text menu.

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

C Language Support

58

If you write applications that are to run on more than one platform, or if you write customsoftware 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, youwill need to change each version whenever you need to improve the code that is commonto 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 itonly once.

Previously, you may have been reluctant to use a lot of pre-processor conditionalsbecause of how confused the source code begins to appear. Whatever time you saved onredundant 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 conditionalsby letting you see clearly the code for just what you are working on.

Creating DefinitionsYou use the functions EvalStrAdd and EvalStrDel to define and undefine the symbolsyou 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 willwant 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

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 orlabel is immaterial, so long as you are using only the #ifdef and #ifndefconstructs to evaluate this label.

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

Command: EvalStrDel=MSWINDOWS

Key Commands

The Codewright editor is several editors in one. In its "standard" mode, Codewright is a CommonUser Access (CUA) compliant editor. If you have ever used a Windows editor before, such asNotePad or SysEdit, you will find that you can guess many of the basic commands. This commandset offers a number of short-cut keystrokes to allow you to bypass the menus in most cases.

Codewright offers alternate command sets that may be more to the liking of users whose roots areembedded in DOS, Unix and other non-Windows platforms. These alternate command sets imitatethe commands used in the BRIEF editor so popular in the DOS development world, Epsilon, anEMACS-style editor, and vi, the standard editor under Unix. We have supplemented thesecommand sets with a number of CUA commands. It should take very little urging to get those whoused a similar command set under DOS to give this alternate command set a try.

Note: You may occasionally find that you have inadvertently placed Codewright inmenu mode by pressing and releasing the + key. This commonly happens when

you start to issue a command, but fail to carry through. You can tell this hashappened when most keys that you type result only in a chirp, and a menu itemappears highlighted. Pressing and releasing the + key again will toggle you out of

this mode.

This behavior is typical of Windows programs, but is made more of a hazard in theBRIEF-compatible keymap, due to its numerous commands that employ the + key.

CUA Key Commands

The CUA keymap has many more assignments in it than are covered by the Common User Accessstandard. In devising these additional keystrokes, we have relied heavily on mnemonics, that is,keys that easily form an association in your memory with the action they perform. This makes thecommands easier to learn and remember. If you are familiar with CUA commands, you may doubtthat CUA commands would be easy to associate, and some commands are not. (It's hard toassociate anything with +�, you just have to memorize it.) You will find, however, that most

commands of this variety have a more memorable equivalent. For example, to search again youhave your choice of � or )6V ()I is find).

Two stages of mnemonics are needed for the two stages of learning: Beginner and Advanced.

Codewright CUA Variant

60

In the BeginningWhen you are first using a keymap or command set, you need to remember the most commonkeystrokes that you will use, perhaps, hundreds of times a day. Memory aids at this stage canhasten learning.

The keystrokes that you use most often should require pressing no more than two keys. Since the+ key is defined in CUA as a System key, very few commands can use that key. The common

two key commands are therefore primarily the ) key combined with a letter key.

Advanced StagesIt is not long, though, before you perform these common commands quite automatically, and thereis no need for memory aids. At this second stage, mnemonics are needed for those once-in-a-whilecommands. You don't want to stop what you are doing to look up a command you use once everycouple of days. If all the best mnemonics are used up by the stage 1 commands, only the morearbitrary assignments remain for the less common commands.

The less frequently used commands often require that you press more than two keys. They attemptto maintain an easily remembered association at the expense of pressing another key. For thisreason, many of the less common commands are the keys )6 combined with a letter key.

Codewright CUA Variant

The CW CUA keymap is almost identical to the CUA Key Commands with the followingexceptions:

Search )V

Make line middle )P

Make bottom of window )D

Display Filename )I

Begin exclusive selection )]

Undo

Copy to

Cut to

Paste from

Persistent Selections

61

The Codewright (CW) CUA keymap was designed at a time when Microsoft Word for Windowsused 6� to save a file. While the CUA keymap demonstrates our desire to keep up with the

current interpretation of the standard, we have retained the CW CUA keymap out of respect forthose whose fingers have come to rely on these keystrokes. We expect further divergence in thefuture.

Persistent Selections

The CUA convention is to have non-persistent selections. That is, selections disappear wheneveryou execute a motion command, such as pressing one of the arrow keys. Programmers often findthis behavior unfamiliar and limiting. A number of the key assignments in the CUA keymap areineffective when in this mode, such as toggling a selection open or closed.

To assure flexibility, we have added the ability to disable this behavior of CUA. Selections willthen not disappear when you move the cursor. You can open and close selections to extend themas you wish. If you wish to have your selections persist, place the following command in yourconfiguration file (CWRIGHT.INI):

[Editor]

CUA_sel_persist=TRUE

To try out persistent selections, you can execute this same command from the API Command key.

Disabling Virtual Space

Another CUA convention is not to allow the cursor to go into virtual space. For example, whenyou press and hold down the right arrow key in NotePad, the cursor moves from one character tothe next. When it reaches the end of a line, it moves on to the first character of the next line. Ifyou click the mouse somewhere to the right of the end of a line, the cursor snaps to the end of theline, rather than where the mouse is pointing. This is not the default behavior for Codewright.

Codewright's default action, when you continually press the right arrow, is to move from onecolumn to the next, out past the end of the line, as far as you might like to go. When you click withthe mouse, the cursor goes right where you are pointing, even if it is beyond the end of a line.

Those who prefer to have Codewright work as closely to CUA conventions as possible may disablecursor travel into virtual space by adding the following line to their configuration file,CWRIGHT.INI:

Disabling Virtual Space

62

[Editor]

CUA_enable_virtual=FALSE

For more information about configuration files, consult the "Configuration and State" chapter ofthis manual.

CUA Commands by Category

63


Document/File

Change output name tuRClose document t�New document tQOpen file tOpen file tHPrint tSRead file into

documenttuI

Save file tVSave selection/file tZ

Cursor Motion/Scrolling

Beginning of line

Bottom of file tCursor left rCursor right qEnd of line

Go to line (prompt) tuOGo to mark (prompt) tuELine down oLine up pMake top of window tWMake middle of win. tRPage down

Page up

Scroll down one line toScroll up one line tptop of file tWord left trWord right tqDelete character

Editing

Delete character left

Delete line tGDelete to end of line tDelete next word uDelete previous word tIndent block vInsert line t.Insert next literally tTRedo sRedo t\Slide-in prompt t!Slide-out prompt t�Undo t]Undo tXUnindent block uv

Scrap/Clipboard

Copy to tCopy to tFCut to uCut to *[Paste from uPaste from tYToggle clipb./scrap t�

Search/Replace

Incremental search tuLKiss matching brace tuNMatch brace or paren t^Multibuf search again tuP


64

Search/Replace (cont.)

Quick word search tuTReplace again tuUFind tIFind again d

Selections/Marks

Begin sel., inclusive tLBegin sel., exclusive tPBegin selec., column tEBegin selection, line tOClose/open Selection t�Create comment tuHExtend selection left urExtend selection right uqExtend selection up upExtend sel. down uoExtend sel. word left turExtend sel. word right tuqExtend sel. begin lineuExtend sel. end line uExtend sel. beg.

documenttu

Extend sel. end

documenttu

Format columns tuMGo to mark (prompt) tuESet mark t [0..9]Lower case selec. tuGUpper case selec. tuXSelect all tDSlide-in prompt t!Slide-out prompt t�

System

API Assistant sbAPI interface jAuto indent on/off tuDBuild current tjCompact Mode tuFCompile document tkError list tupHelp bHex Mode tuKInsert mode on/off

Load recording file thNext error tuoPlay stored keys tu[0..9]Playback keystrokes iPrint version tuYQuit seRecord keys toggle hRoutines tuJText Mode tuWWrap paragraph tuZWrite recording file ti

Window

Close win. &

documentte

Close window only tu�Iconify window tueNext window tuQNext wind. &

documenttg

Previous window tuSToggle visible whsp. tu[Zoom window sc

CUA Commands by Key

65

CUA Commands by Keys ......Undo

sb ........API Assistant

sc ........Zoom window

se ........Quit

s ........Redo

...........Delete character left

t�........Close document

t�........Close/open Selection

t�........Toggle clipb./scrap

t^........Match brace or paren.

tD........Begin column sel.

t ......Delete previous word

tF........Copy to clip/scrap

tG ........Delete line

t ........Delete to end of line

to ........Scroll down one line

tH........Open file

t ........Go to bottom of file

tx ......Insert line

tI ........Find

te ........Close wind. &document

tg ........Next wind. &document

th ........Load recording file

ti ........Write recording file

tj ........Build current

tk ........Compile document

tH........Open file

t ........Go to bottom of file

tx ......Insert line

tI ........Find

te ........Close wind. &document

tg ........Next wind. &document

th ........Load recording file

ti ........Write recording file

tj ........Build current

tk ........Compile document

t ................Open file

t ........Go to top of file

tL ........Begin selec., inclusive

t ........Copy to

tO ........Begin selection, line

tr ........Word left

tP ........Begin selec., exclusive

tQ ........New file

tS ........Print

tT ........Insert next literally

tU ........Replace

tq ........Word right

tV ........Save

tur...Extend sel. word left

tuq...Extend sel. word right

tuo...Next error

tu ...Extend sel. beginningdocument

tu ...Extend sel. end ofdocument

tu�...Close window only

CUA Commands by Key

66

tu[0..9].Play stored keys

tuD .. Auto indent on/off

tuE .. Go to mark (prompt)

tuF .. Compact Mode

tuG .. Lower case sel.

tuH .. Create comment

tuI .. Read file into doc

tue .. Iconify window

tuJ .. Routines

tuK .. Hex Mode

tuL .. Incremental search

tuM .. Format columns

tuN .. Kiss matching brace

tuO .. Go to line (prompt)

tuP .. Multi-document searchagain

tuQ .. Next window

tuR .. Change output name

tuS .. Previous window

tuT .. Quick search for word

tuU .. Replace again

tuV .. Search again

tuW .. Text Mode

tup .. Show errors

tuX .. Upper case sel.

tuY .. Print version

tuZ .. Wrap paragraph

tu[ .. Toggle visible whsp.

tW........Make line top of win.

tX........Undo

tY........Paste from clip/scrp

tp ........Scroll up one line

tZ........Write selection/file

t[ ........Cut to clip/scrp

t\ ........Redo

t] ........Begin excl. sel.

t! ........Slide-in prompt

t� ........Slide-out prompt

t[0..9]........Set mark

.............Delete character

o .............Line down

..............Go to end of line

b .............Help

d .............Search again

h .............Record keys toggle

i .............Playback keystrokes

j .............API interface

.............Beginning of line

.............Insert mode on/off

r .............Cursor left

.............Page down

.............Page up

q .............Cursor right

u .......Delete next word

u ........Cut to

u ........Extend sel. beginning line

u ........Extend sel. end of line

u ........Save file

u ........Paste from

ur ........Character left

uq ........Character right

uv ......Backtab/unindent

v............Tab/indent

p .............Line up

t! ........Slide-in prompt

t� ........Slide-out prompt

Making CUA Key Assignments

67

Making CUA Key Assignments

If you have occasion to add or modify key assignments in the CUA keymap you will notice thattwo functions seem to be assigned to many of the keystrokes. This section of the manual describeswhat you are seeing to better enable you to make key assignments of your own.

There are three pass-through functions that are used to give the CUA keymap consistency. Thesefunctions are CUA_motion, CUA_deletion and CUA_selection. You will note that the keyassignments that look like they have two functions assigned to them usually begin with one of thesefunctions. The second function is actually a parameter of the first function call. It is called by thepass-through function.

The CUA_selection FunctionCUA Keystrokes that extend the current selection or create a new selection use the CUA_selectionfunction. The functions that are in turn called by the CUA_selection function are, for the mostpart, ordinary motion commands. The pass-through function manages the creation and opening orclosing of the selection.

The CUA_deletion FunctionThe CUA_deletion function manages the process of replacing a selection with what is typed orinserted. This behavior is part of the CUA standard. The function deletes the contents of aselection, if there is one, and then calls the inserting function to allow the insertion to take place.

The CUA_motion FunctionAs part of the CUA standard, a selection is removed, if an ordinary motion command is typed.Keystrokes that operate in this way pass the motion command through the CUA_motion functionto allow it to remove a selection, if necessary.

There is also a pass-through function for CUA mouse commands, named CUA_mouse. Thisfunction manages the creation of mouse selections in a way that maintains compatibility with theother pass-through function that use selections.

CUA Keymap Functions

This section describes the major functions defined and used in the CUA keymap. You will findthis listing useful when you want to change or add key assignments.


68

The functions are listed here in much the same fashion that they would be used in key assignments.The same form may be used when executing these commands through the API Command Key.Parameters are enclosed in angle brackets, < and >. You must replace the angle brackets and theircontents with your value.

Parameter names that are enclosed in single quotes are strings. You may need to enclose yourstring in single quotes, too -- especially if the string contains whitespace. Numeric parameternames are preceded by a type.

CUA_attach

Toggle whether the cursor is tied to the selection or moves independently.

CUA_auto_indent

Toggles auto indent off or on.

CUA_backspace

If a selection is defined, the selection is deleted. Otherwise, the preceding character isdeleted.

CUA_back_tab

Move to the preceding tabstop, or, if a selection is defined, unindent the selection to thepreceding tabstop.

CUA_copy

Copies the current selection, if any, to the scrap buffer.

CUA_cut

Cuts the current selection to the clipboard or scrap buffer.

CUA_delete

Deletes the current selection, if defined, otherwise deletes the character at the cursor.

CUA_delete_curr_buffer

Delete the current document, prompting for save if modified.


69

CUA_delete_curr_window

Delete the current window, but not the document, unless "one document per window" ison.

CUA_deletion <'func'>

Delete the current selection, if any, and then execute the named function.

CUA_drop_bookmark <int num>

Place a numbered global bookmark at the current position.

CUA_edit_file

Load a file for editing.

CUA_edit_next_window

Selects the next window in the window list and displays its name.

CUA_edit_prev_window

Selects the previous window in the window list and displays its name.

CUA_end_of_buffer

Go to the last character of the last line of the document

CUA_end_of_window

Synonym for MovEndWin.

CUA_esc

Changes the display mode to normal, otherwise it removes the current selection, if any.

CUA_exit

Exit with query to save modified documents.


70

CUA_goto_bookmark <int num>

Prompt for a bookmark number 1-10 and then go there.

CUA_left_side

Go to the first column visible at the left of the screen.

CUA_make_window_icon

Minimize the current window.

CUA_mark <int mark_type>

Starts a selection of the specified type. If selection already exists, it is removed if the oldand new selection are the same type. The type of the existing selection is changed, ifthey are not the same.

CUA_motion <'func'>

Removes an existing selection before calling the named function.

CUA_mouse <'func'>

Identifies the operation as a mouse operation before executing the named function.

CUA_mouse_selextend <int seltype>

Extends an existing selection to the current mouse position.

CUA_next_winbuf

Selects the next window, unless there is only one, in which case it selects the nextdocument.

CUA_open_line

Inserts a new line at the end of the current line.

CUA_playback

Plays back the current keystroke recording.


71

CUA_QPersistSel

Reports whether persistent selections are on or off.

CUA_quote

Inserts the next key literally, rather than processing it as a command.

CUA_read_file

Inserts a file at the cursor position, after prompting for the name.

CUA_remember

Toggles recording of keystrokes.

CUA_right_side

Moves to the last visible column at the right of the window.

CUA_search_again

Repeat the last search operation using the same parameters.

CUA_search_back

Set the direction of search to backward.

CUA_search_fwd

Set the direction of search to forward.

CUA_selection <'func'>

Used to exec functions that extend an existing selection, this function reopens theexisting selection.

CUA_self_insert <int ch>

Inserts a specified character, or the key just pressed if none is specified.


72

CUA_sel_persist <BOOL persist_on>

Sets persistent selections feature to the state of the parameter.

CUA_shiftpage <int direction>

Pages the text in the window horizontally. Left if the parameter is a negative number,right if it is positive.

CUA_tab

Inserts a tab character or equivalent spaces, or indents a block, if defined.

CUA_tab_use

Toggles the use of tab characters or equivalent spaces on or off.

CUA_toggle_clipscrap

Toggle between using the Windows clipboard or a scrap buffer.

CUA_top_of_buffer

Move to the first character of the first line in the document.

CUA_top_of_window

Move to the last character of the last line in the document.

CUA_translate

Perform a search and replace operation.

CUA_translate_again

Repeat a search and replace operation using the previous settings.

CUA_translate_back

Perform a replace operation in a backward direction.


73

CUA_translate_fwd

Perform a replace operation in a forward direction.

CUA_write_and_exit

Save all modified documents to disk and exit the program.

PlaybackRecStr <int StrNum>

Playback one of the numbered keystroke recording strings used by the Playback Stringsdialog.

Advanced Stages

74

BRIEF Key Commands

BRIEF key commands are not CUA compliant. This means that they conflict with theway Windows commands normally work. For example, the BRIEF commands makeextensive use of + key combinations. CUA rules reserve most of these for standard

commands, such as accessing menus. For instance, +I is usually reserved for

bringing down the File menu. In BRIEF, this is used for displaying the output file's nameon the status line.

For this reason, when using the BRIEF command set, you must press and release the +key to access the menu. To access the File menu, for example, you press and release the+ key and then press I. Similarly, to access other menus, you press and release +and then press the underlined letter in the menu's name.

BRIEF-compatible Commands by Category

75


Note: Gray keys indicate keys located on the keypad.

Buffer/File

Change output name sRClose buffer t�Display filename s)List of buffers sENext buffer sQOpen file sHPrevious buffer s�Print buffer sSRead file into buffer sUSave file sZWrite selection to file sZ


Beginning of line

Bottom of file tBottom of file

Bottom of window tBottom of window

Column left rColumn right qEnd of line

Go to line (prompt) sJGo to mark (prompt) sMLeft window edge uLine down oLine up p

Cursor Motion/Scrolling (cont.)

Make bottom of win. tEMake top of window tWMake center of win. tFPage down

Page up

Right wind. edge uScroll down 1 line tGScroll up 1 line tXTop of file

Top of file tTop of window tTop of window

Word left trWord right tq

Editing

Delete character

Delete character to left

Delete line sGDelete to end of line sNDelete next word sDelete previous word tIndent block by tab vIndent block by space

Insert line txInsert next literally sTRedo s\


76

Editing (cont.)

Slide-in Prompt t!Slide-out Prompt t�Undo sXUndo

Unindent block by tab uv

Scrap/Clipboard

Copy to tCut to uCopy to

Cut to

Paste from

Toggle clipb./scrap t�

Search/Replace

Ignore case on/off tfKiss matching brace tuNQuick search for word tuTMultiBuf Search again tuPReg. expr. on/off tgReplace sWReplace gReplace again ugSearch fSearch sVSearch again uf

Selections/Marks

Begin selec., inclusive sPBegin selec., exclusive sDBegin selec., column sFBegin selection, line sOClose/open Selection tDGo to mark (prompt) sMSet mark sn

System

API interface kBackups on/off tZCompile buffer skDisplay routines tJExpand/Collapse uxNext error tQShow errors tSHelp sKInsert mode on/off sLLoad DLL jLoad recording file shPlayback keystrokes iPrint buffer sSPrint version sYQuit w/prompt s[Quit w/write t[Record keys toggle hRepeat key action tUShell s]Text Mode


77

System (Cont.)

Unload DLL ujWrite recording file si

Window

Borders on/off sbCreate tiled edge dDelete tiled edge eResize window cSelect win. at left uSelect win. at right uSelect win. above uNext window bSelect win. below uZoom window sc

BRIEF Compatible Commands by Key

78

BRIEF Compatible Commands by Keys� ............... Previous buffer

sD ............... Mark exclusive block

sE ............... Buffer list

s .......... Delete word at right

sF ............... Mark column block

sG ............... Delete line

sH ............... Load new buffer

sI ............... Show output filename

sb ............... Window borders togglesk ............... Compile current buffer.sc ............... Zoom in/out on windowsf ............... Search backward

sg ............... Replace backwards

sh ............... Save keystroke file

si ............... Load keystroke file

sJ ............... Go to line no.

sK ............... Help index

sL ............... Insert mode toggle

sM ............... Go to bookmark

sN ............... Delete to end of line

sO ............... Mark block of lines

sP ............... Mark inclusive block

sQ ............... Next buffer

sR ............... Change output filename

sS ............... Print buffer

sT ............... Insert key literally

sU ............... Read block from file

sV ............... Search forward

sW ............... Replace forwards

sX ............... Undo last edit

sY ............... Show program version

sZ ............... Write block to file

sZ ............... Write buffer to file

s[ ............... Quit with query save

s\ ............... Redo last Undo

s] ............... OS Shell

sn.................. Set bookmark

................. Delete character left

t! ............... Slide-in Prompt

t� ............... Slide-out Prompt

t� ............... Delete current buffer

tD ............... Toggle block attach

tE ............... Scroll to wind. bottom

t .......... Delete word at left

tF ............... Scroll to window center

tG ............... Scroll down a line

t .............. Bottom line of window

tx............. Open new line

tf ............... Ignore case toggle

tg ............... Regular expr. toggle

tJ ............... Display routines

t ............. Top line of window

tr ............... Previous word

BRIEF Compatible Commands by Key

79

tQ ............... Next error position

tS ............... Show errors

t .......... End of buffer

t .......... Top of buffer

tU ............... Repeat key action

tq ............... Next word

tuF ........ Compact mode

tuK ........ Hex mode

tuN ........ Kiss matching brace

tuP ........ MultiBuf Search again

tuT ........ Quick search for word

tW ............... Scroll to window top

tX ............... Scroll up a line

tZ ............... Backup file toggle

t[ ............... Write buffers and exit

................... Delete block

................... Delete char. at cursor

o ...................... Line down

.................... End of line

.............. End of window

........ End of buffer

x.................... Insert new line

b ................Next window

k ................API interface

c ................Resize window

d ................Create tiled edge

e ................Delete tiled edge

f ................Search forward

g ................Translate forward

h ................Record keys toggle

i ................Play recorded keys

j ................Preload DLL

...............Beginning of line

..........Top of window

....... Top of buffer..............Insert scrap...............Copy block to scrap...............Cut block to scrap...............Undo

r ................Column left............Page down............Page up

q ................Column right

u ..........Right edge of window

ux .........Expand/Collapse

uf ...........Search again

ug ............... Replace again

uj ............... Unload DLL

u ............. Left edge of window

u ............. Select adjacent win.




uv............. Outdent block by tab

................. Indent block by space

v.................... Indent block by tab

p ...................... Line up

Brief Keymap Functions

80


This section describes the major functions defined and used in the Brief keymap. Youwill find this listing useful when you want to change or add key assignments.

The functions are listed here in much the same fashion that they would be used in keyassignments. The same form may be used when executing these commands through theAPI Command Key. Parameters are enclosed in angle brackets, < and >. You mustreplace the angle brackets and their contents with your value.

Parameter names that are enclosed in single quotes are strings. You may need to encloseyour string in single quotes, too -- especially if the string contains whitespace. Numericparameter names are preceded by a type.

BR_adjacent_window <int direction>Select a new current window with the arrow keys

BR_attachToggles the current selection between being attached to the cursor or unattached.

BR_backspaceBrief-style backspace. Won't backspace beyond the beginning of the line.

BR_beginning_of_lineSynonym for MovHome().

BR_bordersToggles window borders on an off.

BR_copyCopies the selection to scrap. If no selection, copies current line.

BR_create_edgeSplit the current window, creating a new window in the indicated direction.

BR_cutCuts the selection to scrap. If no selection, cuts current line.

BR_deleteDeletes the current selection. If no selection, deletes character at the cursor.


81

BR_delete_curr_bufferDeletes the current buffer unless it is the last one.

BR_delete_edgeDelete adjacent window and expand current window to occupy its space.

BR_delete_macroDelete a macro by unloading its DLL.

BR_del_to_BOLDelete from the cursor position to the beginning of the line.

BR_drop_bookmark <int num>Place a numbered global bookmark.

BR_edit_fileLoad a file.

BR_end_keyBrief's overworked End key. End (End of line), End-End (End of Screen), End-End-End (End of file).

BR_end_of_bufferGo to the last character of the last line.

BR_end_of_lineSynonym for MovEOL()

BR_end_of_windowMove to the last character on the last line visible on the screen.

BR_escReturn to normal display mode. Otherwise, insert and escape character.

BR_exitBrief's standard exit. Prompts [ynw] if any buffers contain unsaved changes.

BR_goto_bookmark <long num>Move to a numbered global bookmark.

BR_home_keyBrief's overworked Home key. Home (beginning of line), Home-Home(beginning of screen), Home-Home-Home (beginning of file)


82

BR_left_sideMove to the first visible column at left of screen

BR_load_macroLoad a DLL.

BR_mark <int mark_type>Drop an anchor, using Brief's selection types.

BR_open_lineOpen a new line at the end of the current one.

BR_playbackPlayback the keystroke recording.

BR_printInvoke the print dialog.

BR_quoteInsert the next character literally, without interpreting it.

BR_read_fileRead a file from disk into the buffer at the current position.

BR_rememberToggle recording of keystrokes.

BR_right_sideMove the cursor to the last column visible at the right of the screen.

BR_search_againRepeat the last search operation using the same parameters.

BR_search_backSet the direction of search to be backward.

BR_search_caseToggles case sensitivity on and off in searching

BR_search_fwdSet the direction of search to be forward.


83

BR_set_backupToggles backups on or off for all existing buffers.

BR_set_mode <int mode>Select between display modes: 1 = Normal ASCII, 2 = Compact, 3 = Hex (ifalready in hex, toggles between hex and ASCII columns.)

BR_tabInserts a tab character or equivalent spaces, or moves to the next tab stop whenin overtype mode.

BR_toggle_clipscrapToggle the use of the Windows clipboard or the current scrap buffer.

BR_toggle_reToggles on or off the use of regular expressions in a search pattern.

BR_top_of_bufferMoves to the first character of the first line in the buffer.

BR_top_of_windowMove to the first character of the first line in the window.

BR_translatePerform a replace operation after prompting for parameters.

BR_translate_againRepeat the last replace operation using same parameters.

BR_translate_backPerform a replace operation in a backward direction.

BR_translate_fwdPerform a replace operation in a forward direction.

BR_write_and_exitWrite all modified buffers to disk and exit the program.

Vi Modes

84

VI Key Commands

In the commands listed below, ( stands for carriage return and ; stands for theescape key.

Vi Modes

Command Initial (Normal) mode. Other modes normally return to command mode uponcompletion. ; (escape) 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 bypressing ;.

Last line Reading input for : / ? or !; terminated by typing a (.

VI Command Summary

Examples/text(................................................search for text

:cmd(...............................................ex or ed command

:q!( ..................................................quit, discarding changes

Û ^D ....................................................scroll up or down3dd.........................................................delete 3 linescwnew;..............................................change word to new

dd...........................................................delete a linedw..........................................................delete a wordeas;....................................................plurals word (end of word; append s; escape from input

state)h i k l .....................................................same as arrow keys, respectivelyitext;..................................................insert text

4<=5 ...............................................arrow keys move the cursor

u.............................................................undo previous changex.............................................................delete a characterZZ..........................................................exit vi, saving changes

VI Command Summary

85

Count Arguments

Numbers may prefix some commands, They are interpreted in one of these ways.

line/col number......................................z G Iscroll amount.........................................^D Ûrepeat effect ...........................................most of the rest

File Operations:!cmd( .............................................run cmd, then return

:e #(.................................................edit alternate file

:e + name( ......................................edit, starting at end

:e +n( ..............................................edit starting at line n

:e name( ..........................................edit file name

:e! #( ...............................................edit alternate file, discard changes

:e!( ..................................................reload, discard changes

:n args( ...........................................specify new arglist

:n( ...................................................edit next file in arglist

:q!( ..................................................quit, discard changes

:q( ...................................................quit

:sh(..................................................run shell, then return

:ta tag( ............................................position cursor to tag

:w name( .........................................write file name

:w! name(........................................overwrite file name

:w!( .................................................forced write, if permission originally not valid

:w(...................................................write back changes

^G..........................................................show current file and lineZZ..........................................................if file modified, write and exit; otherwise, exit

In general, any command word (such as substitute or global) may be typed, preceded bya colon and followed by a carriage return.

Cursor Motionh or 4 ...................................................backward

$.............................................................end of line( .............................................................back a sentence( .............................................................beginning of sentence) .............................................................end of sentence) .............................................................to next sentence+ ............................................................next line, at first non-white

VI Command Summary

86

- .............................................................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Û..........................................................scroll up half screen{.............................................................back a paragraph{.............................................................beginning of paragraph}.............................................................end of paragraph}.............................................................to next paragraph0.............................................................beginning of lineB............................................................back a blank-delimited wordb.............................................................back a wordE ............................................................end of a blank-delimited worde.............................................................end of word( ......................................................return, same as +

H............................................................top line on screenl or 5 ....................................................forward

L ............................................................last line on screenM ...........................................................middle line on screenn.............................................................repeat last or ? commandN............................................................reverse last or ? commandn|............................................................move to column nnG..........................................................go to the beginning of the specified line (end default),where n is a line numberspace......................................................same as space barW...........................................................forward a blank-delimited wordw............................................................forward a word< or j ....................................................next line, same column

= 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-( ............................................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 pata.............................................................append after cursor

VI Command Summary

87

A............................................................append at end of linefx............................................................find next xFx...........................................................find previous xi .............................................................insert before cursorI .............................................................insert before first non-blankRtext; ...............................................replace characters

rx............................................................replace single char with xTx ..........................................................move to character following previous xtx............................................................move to character prior to next x

ScrollingÊ ..........................................................scroll window down 1 line^L ..........................................................clear and redraw window^R ..........................................................clear and redraw window if -L is - key^Y..........................................................scroll window up 1 linez-( ...................................................redraw screen with current line at bottom of window

z.(....................................................redraw screen with current line at center of window

z(.....................................................redraw screen with current line at top of window

zn.(..................................................use n-line window

Bookmarksmx..........................................................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 worderase.......................................................your erase character, same as ^H (backspace)\ .............................................................quotes your erase and kill characters; .......................................................ends insertion, back to command mode

.......................................................interrupt, terminates insert mode

^D..........................................................backtab one character; reset left margin of autoindent^^D........................................................caret (^) followed by control-d (^D); backtab to beginningof line; do not reset left margin of autoindentO^D.......................................................backtab to beginning of line; reset left margin ofautoindent^V..........................................................quote non-printable charactero.............................................................open line belowO............................................................open above

VI Command Summary

88

Operators

Operators are followed by a cursor motion, and affect all text between the cursor'sstarting and ending position. For example, since w move's over one word, dw deletes theword that would be moved over. Double the operator, e.g., dd to affect whole lines.

! .............................................................fitter through command< ............................................................left shift> ............................................................right shiftc.............................................................changed.............................................................deletey.............................................................yank lines to buffer

Miscellaneous OperationsC............................................................change rest of line (c$)D............................................................delete rest of line (d$)J .............................................................join liness .............................................................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 (usinglower-case letters), the text in that buffer is put instead.

"xd .........................................................delete into buffer x"xp .........................................................put from buffer x"xy .........................................................yank to buffer x3yl .........................................................yank 3 characters3yy.........................................................yank 3 linesp.............................................................put back text after cursorP ............................................................put back text before cursor

Undo, Redo, Retrieve"dp.........................................................retrieve dth last delete...............................................................repeat last changeU............................................................restore current lineu.............................................................undo last change

EX Command Words Supported

89

Codewright Extensions

� Context sensitive help

# ASCII Editing mode

� Selective Display mode

� Hex Edit mode

� API Command Key

EX Command Words Supported!&<=>appendcccdchangechdircopydeleteediterrlistexfileglobalinsertjoin

klistmakemarkmovenextnumberpreviousprintputquitreadrewindsetshellsubstitutetagtoundoversionvglobalvisualwqwritexityank

Epsilon Keymap Functions

90

Epsilon Key Commands

Epsilon Emulation Commands by CategoryNote: Gray keys indicate keys located on the keypad.

Buffer/File

Bufed t[,tECopy to file thKill buffer t[,NNext buffer

Next buffer t[,!Previous bufferPrevious buffer t[,�Save all buffers t[,VSave file t[,tVSelect buffer t[,EVisit file t[,tYWrite file t[,tZ


Backward character rBackward character tEBackward kill level sBackward level tsEBackward paragraph s>Backward paragraph sp


Backward sentence sDBackward sentence tpBackward word sEBackward word trBeginning of line srBeginning of line tDBeginning of windowBeginning of window s�Center window tODown line oDown line tQEnd of line sqEnd of line tHEnd of windowEnd of window s�Forward character qForward character tIForward level tsIForward paragraph s@Forward paragraph so


91


Forward sentence sHForward sentence toForward word sIForward word tqGo to beginning tGo to end tGoto beginning s�Goto end s!Goto line t[,JNext page

Next page tYNext position t[,tQPrevious page sYPrevious pagePrevious position t[,tSScroll down s]Scroll left s^Scroll right s`Scroll up t]To indentation sPUp line pUp line tS

Editing

Backward deletecharacter

tK

Backward deletecharacter

t"

Backward kill word tsKCapitalize word sFCenter line sVDelete blank lines t[,tRDelete character tGDelete characterDelete horizontalspace

s?

Enter key tPFill paragraph sTIndent for comment s�Indent previous tLIndent region ts?Indent rigidly t[,tLIndent under tsLInsert ascii s�Insert file t[,LKill level tsNKill line tNKill Region tZKill sentence sNKill word sG


92

Editing (cont.)

Lowercase word sOMaybe break line tMOpen line tROverwrite modeQuoted insert tTRedo t[,URedo kRedo changes tkRedo changes t[,tUTranspose characterstWTranspose lines t[,tWTranspose words sWUndo t[,XUndo jUndo changes tjUndo changes t[,tXUppercase word sX

Scrap/ClipboardAppend next kill tsZCopy region sZCopy to scratch t[,[Insert scratch t[,\Yank t\Yank pop s\

Search/Replace

Find delimiter s�Incremental search tVQuery replace s�Query replace sURegex replace s Regex replace sRegex search tsVReplace string sReverse incrementalsearch

tU

Reverse regex searchtsUSelect tag file t[,s�tag files t[,s�

Selections/Marks

Exchange point andmark

t[,t[

Highlight region t[,tKJump to lastbookmark

sM

Mark paragraph sKRectangle mode t[,�Set bookmark s�Set mark t#Set mark s


93

Selections/Marks

Set named bookmark t[,�Tabify region t[,

tsLUntabify region t[,sLWrite region t[,Z

System

Abort tJAlt prefix t>Alt prefix t[,t>Argument tXArgument s�Argument sBind to key ecd hChange modified saCompare windows tcCount lines t[,OCtrl prefix tACtrl prefix tsACtrl prefix t[,

tsACtrl prefix t[,tADired t[,G

System

End kbd macro t[,�Exit t[,tFExit level t[,t]Find file t[,tIGoto tag t[,�Grep shHelp tBHelp bLast kbd macro teLast kbd macro t[,HLoad bytes dMake t[,PName kbd macro t[,sQNamed command s[Named command cPluck tag t[,�Push t[,tHSet comment column t[,�Set fill column t[,ISet variable iShow bindings fShow menu scShow variable ti


94

System

Start kbd macro t[,�Start process t[,tPStop process tFWhat is gWrite state td

Window

Enlarge window t[,AEnlarge window tEnlarge window t[,AEnlarge windowhorizontally

s

Enlarge windowhorizontally

t[,#

Enlarge windowinteractively

t[,

Enlarge windowinteractively

t[,�

Kill window t[,tGKill window t[,�Move to window t[,oMove to window t[,rMove to window t[,qMove to window t[,pNext window t[,QNext window t[,RNext window s

Window

One window t[,�Previous window t[,SPrevious window sShrink window tShrink windowhorizontally

s

Shrink windowinteractively

t[,

Shrink windowinteractively

t,[�

Split window t[,�Split windowvertically

t[,�

Zoom window t[,]


95

Epsilon Emulation Commands by Key

r ............Backward character

o ............Down line

q ............Forward character

p ............Up line

............Delete character

............Beginning of window

............Overwrite mode

............End of window

b ............Help

c ............Named command

d ............Load bytes

e ............Bind to key

f ............Show bindings

g ............What is

h ............cd

i ............Set variable

j ............Undo

k ............Redo

.............Previous buffer

............Next buffer

............Next page

............Previous page

sp .......Backward paragraph

sr .......Beginning of line

sq .......End of line

so .......Forward paragraph

s� .......Argument

s .......Argument

s� .......Beginning of window

s .......Regex replace

sa .......Change modified

s> .......Backward paragraph

s@ .......Forward paragraph

s? .......Delete horizontal space

s� .......End of window

s� .......Find delimiter

s� .......Goto beginning

s .......Backward kill levelhorizontally

s .......Next window

s .......Previous window

s .......Shrink windowhorizontally

s .......Enlarge window

sc .......Show menu

sh .......Grep

s! .......Goto end

s" .......Help

s� .......Indent for comment

s� .......Query replace

s� .......Insert ascii


96

s# .......Set mark

s .......Regex replace

s .......Replace string

s� .......Set bookmark

s^ .......Scroll left

s` .......Scroll right

sD .......Backward sentence

sE .......Backward word

sF .......Capitalize word

sG .......Kill word

sH .......Forward sentence

sI .......Forward word

sK .......Mark paragraph

sM .......Jump to last bookmark

sN .......Kill sentence

sO .......Lowercase word

sP .......To indentation

sT .......Fill paragraph

sU .......Query replace

sV .......Center line

sW .......Transpose words

sX .......Uppercase word

sY .......Previous page

sZ .......Copy region

s[ .......Named command

s\ .......Yank pop

s] .......Scroll down

tp ........Backward sentence

tr .......Backward word

tq .......Forward word

to .......Forward sentence

t .......Goto beginning

t .......Goto end

t .......Shrink window

t .......Enlarge window

tc .......Compare windows

td .......Write state

te .......Last kbd macro

th .......Copy to file

ti .......Show variable

tj .......Undo changes

tk .......Redo changes

tB .......Help

t# .......Set mark

t> .......Alt prefix

t" .......Backward delete character

tA .......Ctrl prefix

tD .......Beginning of line


97

tE .......Backward character

tF .......Stop process

tG .......Delete character

tH .......End of line

tI .......Forward character

tJ .......Abort

tK .......Backward delete character

tL .......Indent previous

tM .......Maybe break line

tN .......Kill line

tO .......Center window

tP .......Enter key

tQ .......Down line

tR .......Open line

tS .......Up line

tT .......Quoted insert

tU .......Reverse incremental search

tV .......Incremental search

tW .......Transpose characters

tX .......Argument

tY .......Next page

tZ .......Kill Region

t\ .......Yank

t] .......Scroll up

tsA .. Ctrl prefix

ts? .. Indent region

tsE .. Backward level

tsI .. Forward level

tsK .. Backward kill word

tsL .. Indent under

tsN .. Kill level

tsU .. Reverse regex search

tsV .. Regex search

tsZ .. Append next killinteractively

t[,o ... Move to window

t[,r ... Move to window

t[,q ... Move to window

t[,p ... Move to window

t[,� .. End kbd macro

t[,A .. Enlarge window

t[,# .. Enlarge windowhorizontally

t[,� .. Enlarge windowinteractively

t[, .. Enlarge window

t[, .. Shrink windowinteractively

t[,� .. Set named bookmark

t[, .. Show point


98

t[,� .. Shrink windowinteractively

t[,� .. Start kbd macro

t[,� .. Goto tag

t[,� .. Kill window

t[,� .. One window

t[,� .. Split window

t[,� .. Split window vertically

t[,F .. Compare windows

t[,! .. Next buffer

t[,� .. Pluck tag

t[,� .. Previous buffer

t[,� .. Rectangle mode

t[,� .. Set comment column

t[,E .. Select buffer

t[,G .. Dired

t[,H .. Last kbd macro

t[,I .. Set fill column

t[,J .. Goto line

t[,L .. Insert file

t[,M .. Jump to named bookmark

t[,N .. Kill buffer

t[,O .. Count lines

t[,P .. Make

t[,Q .. Next window

t[,R .. Next window

t[,S .. Previous window

t[,U .. Redo

t[,V .. Save all buffers

t[,X .. Undo

t[,Z .. Write region

t[,[ .. Copy to scratch

t[,\ .. Insert scratch

t[,] .. Zoom window

t[,s� ..tag files

t[,s� ..Select tag file

t[,sL ..Untabify region

t[,sQ ..Name kbd macro

t[,t> ..Alt prefix

t[,tA ..Ctrl prefix

t[,tE ..Bufed

t[,tF ..Exit

t[,tG ..Kill window

t[,tH ..Push

t[,tI ..Find file

t[,tK ..Highlight region

t[,tL ..Indent rigidly

t[,tP ..Start process

t[,tQ ..Next position


99

t[,tR Delete blank lines

t[,tS Previous position

t[,tU Redo changes

t[,tW Transpose lines

t[,tV Save file

t[,tX Undo changes

t[,tY Visit file

t[,tZ Write file

t[,t[ Exchange point and mark

t[,t] Exit level

t[,tsA Ctrl prefix

t[,tsL Tabify region


This section describes the major functions defined and used in the Epsilon keymap. Youwill find this listing useful when you want to change or add key assignments. Thefunctions are listed here followed by a terse description of each.

EPSAltPrefix

reads the next character as an alt character

EPSAppendNextKill

causes the next kill command to append to the previous kill buffer. An appendwill occur ONLY of the next IMMEDIATE command is a kill command.

EPSArgument

will set the global argument variable. Assumes input of Ctrl-U, Alt--, or Alt-0through Alt-9. Any other input will result in bizarre argument values.

EPSAutoFillMode

switches in and out of fill mode

EPSBackwardCharacter

backs up in the buffer towards the start of the buffer

EPSBackwardDeleteCharacter

deletes characters towards the start of the buffer


100

EPSBackwardKillWord

removes all characters to the beginning of the word closest to the cursor towardsthe start of the buffer.

EPSBackwardParagraph

moves the cursor to the previous paragraph

EPSBackwardSentence

moves the cursor to the previous sentence

EPSBackwardWord

move back in the buffer by words.

EPSBeginningOfLine

moves the character to the beginning of the current line.

EPSBeginningOfWindow

moves the cursor to the top left of the current window.

EPSBindToKey

starts the key binding dialog box

EPSBufed

starts the buffer selection dialog

EPSBufferInit

will set buffer specific variable for emulation and is executed on buffer creation.This is an EVENT_BUFFER_CREATED event handler.

EPSCapitalizeWord

sets the first character of the current word to uppercase and the rest to lower


101

EPSCd

starts the directory select dialog

EPSCenterLine

centers the current line horizontally

EPSCenterWindow

scrolls the buffer so that it is centered vertically in the current window

EPSChangeModified

toggles the read only state of the current buffer.

EPSCopyRegion

copies all text between the current point and mark to the kill buffer.

EPSCopyToFile

will start the file save as dialog. The previous filename will not be associatedwith the buffer unless the keep old file check box in the save as dialog ischecked.

EPSCountLines

tells the number of lines and bytes in the buffer and the line number of the point

EPSCtrlPrefix

reads the next character as a ctrl character

EPSCtrlXTable

switches the current keymap to the ctrl-x key table

EPSDeleteBlankLines

deletes lines that are empty or contain only whitespace


102

EPSDeleteChar

removes characters in the buffer. It will remove characters in the forwarddirection if numChars is positive and will remove characters in the backwarddirection if numChars is negative. No characters are removed if numChars is 0.

EPSDeleteCharacter

deletes characters from the current position towards the end of the buffer.

EPSDeleteHorizontalSpace

removes all whitespace around the current cursor.

EPSDired

calls the Codewright file browser

EPSDownLine

move the cursor down a line

EPSEndKbdMacro

ends keyboard macro recording

EPSEndOfLine

moves the cursor to the end of the current line.

EPSEndOfWindow

moves the cursor to the lower right corner of the current window.

EPSEnlargeWindow

grows the window vertically by the number of lines of text specified in theargument (defaults to 1)

EPSEnlargeWindowHorizontally

grows the window horizontally by the number of lines of text specified in theargument (defaults to 1)


103

EPSEnlargeWindowInteractively

lets you use the keyboard to resize the current window

EPSEnterKey

inserts a newline at the point

EPSExchangePointAndMark

swaps point and mark. Any existing highlight is preserved.

EPSExit

will terminate the editing session. This relies on Codewright file save hooks andis therefore slightly different on User Interface when there are modified buffers.

EPSExitLevel

will perform the same command as EPSExit since there appears to be noconcept of a recursive edit level.

EPSFillParagraph

fills the current paragraph to the current right fill margin.

EPSFindFile

starts the file open dialog

EPSForwardCharacter

moves the cursor in the direction of the end of the current buffer.

EPSForwardParagraph

moves the cursor to the next paragraph

EPSForwardSentence

moves the cursor to the next sentence


104

EPSForwardWord

moves the cursor to the next word

EPSGotoBeginning

will place the cursor at the beginning of the buffer.

EPSGotoEnd

will place the cursor at the end of the buffer.

EPSGotoLine

puts the cursor on the line given as an argument. If no argument is given, theCodewright Goto Line dialog comes up.

EPSGotoTag

puts the cursor at the next occurrence of the current tag. In Epsilon, tagging iscase-insensitive.

EPSGrep

starts the file grep dialog.

EPSHelp

brings up the Codewright help engine

EPSHighlightRegion

begins a highlight if none is active; otherwise it removes the current highlight

EPSIncrementalSearch

initiates an I-Search

EPSIndentPrevious

makes the current line start at the same column as the previous non-blank line.Specifically, if you invoke this command with point in or adjacent to a line's


105

indentation, that indentation is replaced with the indentation of the previousnon-blank line. If point's indentation exceeds that of the previous non-blankline, or if you invoke this command with point outside of the line's indentation,this command simply inserts a tab character.

EPSIndentRegion

performs a tab operation on every line in the region.

EPSIndentRigidly

will indent a block of code

EPSInsertChar

inserts characters into the current buffer

EPSInsertEOL

inserts newline characters into the current buffer. This function is used locallyonly.

EPSInsertFile

brings up a file open dialog or gets command line input and inserts the returnedfile name.

EPSInsertToColumn

inserts whitespace to the given column.

EPSJumpToLastBookmark

puts the cursor on the most recently set bookmark

EPSJumpToNamedBookmark

brings up Codewright's Go to Bookmark dialog

EPSKillBuffer

brings up a dialog that lets you delete a specified buffer


106

EPSKillLevel

(not implemented)

EPSKillLine

deletes the current line

EPSKillRegion

removes all text between the current point and mark and copies it to the currentkill buffer.

EPSKillSentence

deletes the current sentence

EPSKillWindow

deletes the current window

EPSKillWord

deletes the current word

EPSLastKbdMacro

executes the last recorded keyboard macro

EPSLoadBytes

loads a pre-compiled library (DLL) into Codewright

EPSLowercaseWord

converts the entire current word to lower case

EPSMake

with no arguments executes the build command. If an argument is given, theuser is prompted for the name of an application to run.


107

EPSMarkParagraph

highlights the entire current paragraph

EPSMaybeBreakLine

inserts a new line into the buffer

EPSMouseLeftButtonDown

calls the standard binding, sets the mark and switches out of rectangle mode ifrequired.

EPSMouseRightButtonDown

calls the standard binding, sets the mark switches out of rectangle mode ifrequired.

EPSMouseRightButtonUp

current does nothing

EPSMouseRightClick

currently does nothing

EPSMoveToWindow

will move to another window in the indicated direction. If a window does notexist in the wanted direction the function does nothing.

EPSNamedCommand

executes a Codewright or user-defined API call

EPSNextBuffer

moves to the next buffer in the buffer list

EPSNextPage

moves the cursor down one page in the buffer


108

EPSNextPosition

goes to the next error or the next FGrep item

EPSNextWindow

moves to next window in the window list.

EPSOneWindow

make the current window the only window

EPSOpenLine

adds newlines at the after the current cursor position.

EPSOverwriteMode

toggles overwrite mode (or sets is if an argument exists).

EPSPluckTag

finds the tag for the word at the cursor

EPSPreviousBuffer

moves to the previous buffer in the buffer list.

EPSPreviousPage

moves to the previous page in the buffer

EPSPreviousWindow

moves to the previous window in the window list.

EPSPush

calls Codewright's ExecCommand

EPSQueryReplace

does an interactive search/replace


109

EPSQuotedInsert

takes the next character literally and inserts it into the text at the cursor position.If an argument is given, it is taken as the number of times to insert the characterrepeatedly.

EPSROEditEvent

will check for a read-only buffer and abort the insert if the buffer is read-only.

EPSRectangleMode

toggles rectangle mode

EPSRedo

redo an undo

EPSRedoChanges

currently just calls EPSRedo

EPSRegexReplace

performs an interactive search/replace using regular expressions

EPSRegexSearch

performs a text search on the current file using regular expressions

EPSReplaceString

performs an interactive search/replace

EPSReverseIncrementalSearch

performs an I-search backwards

EPSReverseRegexSearch

is performs a regular expression search backwards


110

EPSSaveAllBuffers

saves all currently modified non-system buffers

EPSSaveFile

writes the contents of the current buffer.

EPSScrollDown

scrolls the current text down in the current window

EPSScrollLeft

scrolls the current text left in the current window

EPSScrollRight

scrolls the current text right in the current window

EPSScrollUp

scrolls the current text up in the current window

EPSSelectBuffer

starts the buffer selection dialog

EPSSelectTagFile

sets the name of the file to use for a tags database. The browser file is not set.

EPSSetBookmark

sets a bookmark at the cursor

EPSSetFillColumn

sets the column to be used for paragraph fills

EPSSetMark

sets the mark at the current cursor position


111

EPSSetNamedBookmark

presents a dialog that lets you set and name a bookmark at the cursor

EPSShowBindings

brings up the dialog bindings dialog.

EPSShowPoint

displays information about the cursor position. Includes column number, byteoffset, size of file in bytes, and ASCII, decimal, and hex values for the characterat the cursor.

EPSShrinkWindow

decrements the window vertically by the given number of lines of text (defaultsto 1)

EPSShrinkWindowHorizontally

decrements the window horizontally by the given number of lines of text(defaults to 1)

EPSShrinkWindowInteractively

lets you use the keyboard to resize the current window

EPSSplitWindow

splits the current window into two windows one above the other.

EPSSplitWindowVertically

creates two windows side by side in the real estate occupied by the current one.

EPSStartKbdMacro

starts recording a keyboard macro


112

EPSStartProcess

calls Codewright's ExecCommand to execute an application

EPSToIndentation

moves the cursor to the first nonwhite space in the line

EPSTransposeCharacters

swaps the current character with the next

EPSTransposeLines

swaps the current line with the next

EPSTransposeWords

swaps the current word with the next

EPSUnassignedKey

will beep if an unassigned key is pressed

EPSUndo

undoes previous editing tasks

EPSUndoChanges

currently just hooks into EPSUndo

EPSUpLine

moves the cursor up lines towards the beginning of the buffer.

EPSUppercaseWord

converts words towards the end of the buffer to uppercase.


113

EPSVisitFile

closes the current buffer and prompts the user for a new file to open

EPSWhatIs

prompts for a key and displays the function associated with it

EPSWriteFile

brings up the file save as dialog. The buffer may or may not have a new filename associated with it depending on how the keep old file check box ismarked.

EPSWriteRegion

prompts the user for a filename and saves the current region (selection) to thatfile

EPSWriteState

updates the state file which saves editor context information between sessions

EPSYank

inserts the current kill region into the buffer at the cursor

EPSYankPop

replaces the last-yanked item with the next item on the kill ring

EPSZoomWindow

toggles the maximize state of the current windower4t56w.

114

Version Control Setup

Codewright can work with your version control software in one of two ways:

• Using a command line interface

• Using your provider’s Application Programming Interface (API)

Your selection of which interface to use will control the operation of all of the items onthe Version Control submenu of the Tools menu, and version control related buttons onany toolbars. The capabilities that Codewright provides will vary somewhat dependingon which of these interfaces you use. You select which you plan to use by selectingSetup from the Version Control submenu on the Tools menu.

Which Interface Do I Use?

To use the command line interface for Version Control, you need only have a versioncontrol system that processes arguments on the command line to tell it what file to operateon, and what options you are specifying. The application can be Windows or DOS based.

To use your provider’s Application Programming Interface (API) requires more. For thisreason, only a few providers are supported in this manner. You need the following:

• A version control system that offers a robust API.

• The version that supports that API installed on your system

• An interface DLL

The last item, the interface DLL, must be developed specifically for the provider’ssystem. Whether it is done by Premia, the provider, or as a collaborative effort maydetermine where you can obtain this DLL. It may come on your provider’s disks, on yourCodewright disks, or may be downloaded from an online service or BBS.

As of this writing, interface DLLs are only available for Intersolv’s PVCS andMicrosoft’s Visual SourceSafe. Any system that is designed to be used with Microsoft’spublished version control interface for Visual C++ may be readily adapted to work withCodewright, however.

Command Line Interface

115


Codewright has predefined commands for several version control systems, includingIntersolv’s PVCS, MKS’s Source Integrity, and various versions of the RCS utility,ported from Unix.

The first step in setting up your command lines is to find the Version Control submenu onthe Tools menu, and select the Setup item. Make sure that the Command Line Providerradio button is selected, and then choose a command set from the list. You are then readyto use the commands on the Version Control submenu that you will find on the Toolsmenu.

Unlisted Providers

If you do not see you provider listed, you will need to create your own command lines. Ifyou know that one of the command sets listed is similar to yours, you may want to selectthat one, and use its commands as a starting point for your own. To start from scratch,select Other from the list. In either case, you will need to pay a visit to the ProjectProperties dialog to define or modify the command lines.

Select the Tools tab, and you will see a list of command lines. Scroll toward the end ofthe list, and you will see seven “External VCS” commands that you can define orcustomize.

Check In Command

The Check-in command is the command line needed to check in a file to your versioncontrol system or archive. If possible, this command should work whether an archivecurrently exists for the workfile or if one must be created.

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 orof the archive itself, when creating a new archive, to the check-in command. This is done


116

through prompting, or through the Comment String edit box in the check-in dialog. Thetext 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.

There are predefined command lines for several version control vendors. You selectbetween these in the Setup dialog on the Version Control submenu of the Tools menu.

Check Out Command

The Check-out command is the command line to execute when you are checking out arevision from a version control system or other archive. If your version control systemoffers revision locking, this command should not lock the revision. This is the commandto 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 theAdditional Options edit box in the Check-out dialog, use a command like the one below:

get @%Q %b%e

Predefined command lines are provided for a number of vendors. You select betweenthese in the Setup dialog on the Version Control submenu of the Tools menu.

Check Out with Lock Command

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

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

get -l %b%e


117

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

get -l @%Q %b%e

Command lines for several vendors are provided. You select between these in the Setupdialog on the Version Control submenu of the Tools menu.

Lock Command

This is the command that your version control system uses to lock a revision withoutchecking it out. This is useful when you already have a modified version of the sourcefile that you want to check in, but you discover that the file was not locked.

Note Make sure that your modified version contains all the changes in the most recentrevisions before doing this. If it does not, use a merge utility (such asCodewright’s) to merge your changes with the ones you are missing before youcheck it in.

Unlock Command

This is the command your version control system uses to unlock a revision withoutchecking it in. It is useful when you discover that you have a file checked out that you donot plan to modify at present.

Log Command

This is a command to obtain a report about activity in the current document’s archive.You may make it general or specific – whichever best meets your needs. It can beanything from “list all changes and their descriptions” to “what is the number of the latestrevision?”

Manager Command

This is the command that brings up you version control package’s manager, if any. Themanager is a general purpose, menu or form driven program that lets you perform avariety of version control functions. It is useful when you have a slightly unusual needthat is not covered by the other version control commands.

VCS Maintenance Dialog

118

SCC Provider Interface

Microsoft published an interface to allow version control systems to interact with theirproduct, Visual C++ 4.0 and later. We have adopted this interface as a standard for directinteraction between Codewright and version control systems. Microsoft has referred tothis interface as the “Source Code Control Provider” interface, or SCC Provider. Hence,we use the name SCC Provider to refer to direct manipulation of a version control systemthrough DLLs and an API.

When you are using the SCC Provider Interface, you make the same selections from theVersion Control submenu as you would with the command line interface. The differenceis that any setup required is done through your version control system (SCC Provider),rather than by specifying command lines for Codewright to use.

VCS Maintenance Dialog

The VCS Maintenance dialog is a multi-purpose dialog that works for either thecommand line interface or the SCC Provider interface. You invoke it by selectingMaintenance from the Version Control submenu of the Tools menu. It lets you applylabels to revisions, lock and unlock revisions without checking them in or out, plus reviewthe revision history and properties of an archive. Some of these services, such as historyand properties, are very specific to the version control system or SCC provider. You setit up to do what you want, depending on what is available. The dialog stays open througha series of maintenance functions until you explicitly close it.

119

Projects and Workspaces

This chapter describes how to use the Codewright Project and Workspace facility. Thecomplex relationships between files and groups of files that are almost routine in programdevelopment for Windows demand this type of organization. Without the simplifyingeffect of Projects, dealing with the demands of Windows programming would be evenmore taxing.

What is a Project?

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 usingversion control, creating a "Tags" database, or even if you are just loading files. Theproject 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 filesmay contain almost as much information as your Codewright configuration file.

What is a Workspace?

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 agroup of files. It doesn't matter if you worked on that group of files a half hour before orthree months ago. It is as if an instance of Codewright were frozen in time containingthese files.

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

Adding and Deleting Project Members

120

Creating a Project

Creating a Codewright project is as simple as selecting New from the Project menu andentering a name for your new project. The name is the filename and path in which theproject information will be stored. In selecting a name, keep in mind that Codewrightassumes the filename extension .PJT for project files if you don't supply one. If you wantanother extension, you must specify it. If you wish to have no extension, put a dot ( . ) atthe end of the root.

After creating the project, you are given the opportunity to specify the names of files thatare members of the project. You should also select the Options tab from the ProjectProperties dialog to define how much configuration information will be saved along withthe filenames in the project file.

Adding and Deleting Project Members

Using Projects

121

You specify the members of a project by selecting the Files tab of the Project Propertiesdialog. Locate the files you want to add by navigating your file system as you wouldwhen using the File Open dialog. You may select a series of files and then add them bypressing 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 grouptogether 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 asyou add them. You may delete files from the project by selecting them in this box andthen pressing the Delete button.

Project Setup Checklist

Whenever you create a new project, it is a good idea to make sure that the settings areappropriate for the project. A quick once over will avoid surprises later. There areseveral dialogs that you should visit. Begin by selecting the Directories tab in the ProjectProperties dialog:

• Working Directory Define a working directory for your project. An explicitdirectory or %x (the path of the project file) are usually the best choices.

Next select the Tools tab:

• Project Command Lines Define the major project-wide command lines you willbe using (other than the command to compile the current file). For example,your Make command might be “Ftee nmake -f %y.mak”. (%y indicates the pathand root of your project file) If you already have a makefile, just name itexplicitly instead of using %y. If you will be using VDOS instead of FTEE towatch the progress of the command, just omit FTEE from the command.

Finally, select Compile from the list of tools, and then press the Compiler button thatappears in place of the Browse button.

• Compiler Command Lines The compiler to use is associated with the extensioninstead of being associated directly with the project. Compiler associations areproject specific, by default, so make sure the right associations are in effect.

Using Projects

This section describes the uses you can make of projects, once defined. The primary usesof projects covered here are listed below:

Using Projects

122

• Selecting or Changing Projects

• Loading Files for Editing

• Creating and Selecting Workspaces

• Searching Project Files

• Selecting files for Check-in or Check-out

• Generating a compiled tags database

• Making different build parameters for different purposes

Selecting or Changing Projects

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

Recently selected projects will be listed at the bottom of the Project menu, numberedfrom one to nine. The active project will have a check mark next to it. You may selectfrom this list to reload any of the projects listed.

Loading Files for Editing

One of the best things about organizing your work into projects is the convenience itprovides in selecting files for loading. Just choose Load Files from the Project menu andyou will be presented with a list of files in the current project. You can select one ormore files from this list for loading and editing. If you find that some members of theproject aren't listed, select the Files tab of the Project Properties dialog to add them. Ifyou 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.

Project Window

Alternately, you may wish to use the Project Window to operate on files in a project. Aswith the Load Files dialog, you just select the desired files from the list and press ( to

load the files. It has the advantage, however, of showing which files are actually on disk(some may currently be archived), and whether they are read/write. In addition, you maydefine filters (file specification patterns) to sort the file list into groups.

Using Projects

123

The primary purpose of the Project Window is to facilitate version control operations.For this reason, you will find that by right clicking on a file or one of a selected group offiles will bring up a menu with a list of available version control operations.

Creating a Workspace

One of the most powerful aspects of projects is the workspace. At any time whileworking on a project, you can select Save Workspace from the Project menu and create anew workspace. Just give your workspace a name -- a descriptive name this time, ratherthan just a file name -- and you are done. A workspace name may contain any printablecharacters (including spaces) except apostrophe ( ' ), backslash ( \ ), quote ( " ), andsquare brackets ( [ ] ).

Suppose that you have a number of files open, and want to create a new workspace thatdoesn't include any of the files currently open. Select Load Workspace from the Projectmenu. You will see listed there a workspace that is always available, called <none>. Youcan 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 willbe given an opportunity to do so.

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

Remember that workspaces are specific to the projects in which they are created. Youcould have an "options dialog" workspace in several different projects, but as far asCodewright is concerned, they are unrelated.

Workspace Saving

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

• close or change projects,

• exit Codewright,

• and optionally when you change workspaces.

Using Projects

124

Changing Workspaces

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

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

Close Windows/Delete BuffersYou may choose to close all windows and buffers after leaving one workspace and beforethe next is loaded. In this event, no buffers or windows are carried over from oneworkspace to the next. You may elect to just close the files that are members of theworkspace. This means that any files you opened during the session, such as a specialheader file, will carry over to the next workspace. You may even choose to have all filescarry over into the next workspace. If you do this, we recommend that you either deletethe carry-over buffers before saving the workspace, or save the workspace under a newname. 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 isunaffected by which of these options you select.

Configuration and State Hierarchy

125

Searching Project Files

You can search as a group the files that are members of the current project, or you canselect a subset of the member files on which to perform a search. This feature is availablein the Multiple Sources portion of the Search and Replace dialog (Project Files) and isdescribed in detail in the Search and Replace chapter of this manual.

Selecting files for Check-in or Check-out

Codewright's version control interface (Check-in, Check-out and related commands) canoperate independently of, or in conjunction with Projects. The dialog allows you to selectfrom files in the project or the current directory.

You can make your version control commands project-specific, if you like. Just locatethe Options tab in the Project Properties dialog and put a check in the Version ControlSetup checkbox. This will cause your Check-in, Check-out and related commands to bestored in your project file.

Project Files

A project file is essentially a configuration file and state file all in one. Workspaces arestored as additional "state files" within the project file. Once you understand the formatof a Codewright configuration file, you understand a Codewright project file. These fileslook just like standard Windows .INI files with headings enclosed in square brackets, andstatements on lines following these headings. Statements take the form of<keyword>=<value>.

The primary difference between a Codewright configuration or project file and aWindows .INI file, is that keywords may not be repeated within a section of a Windows.INI file. In a Codewright configuration or project file, keywords may be repeated. Thisis possible because Codewright processes these files directly, without going thoughWindows. For more information on the format of configuration and related files, refer tothe "Configuration and State" chapter of this manual.


When you have no projects in use, Codewright stores its configuration information in itsconfiguration file (CWRIGHT.INI). Between sessions, Codewright stores the moretransient information about the files you are working on in its state file. When you are


126

using a project, however, some configuration information is kept in the project file, andalmost all of the state information is stored there also. The state file then serves largely toidentify which project file you were last using.

You determine the amount of configuration information kept in the project file. TheOptions tab in the Project Properties dialog lets you select which categories of settings arestored in the project file, and therefore change as you change projects. The moreinformation that goes into the Project file, the less information goes into the Configurationfile.

If you are using one or more workspaces within your project, document and window stateinformation is stored with the active workspace when you exit, rather than in the statesection of the project.

127

Regular Expressions

Regular Expressions are a powerful notation for describing string matching patterns thathas gained wide acceptance. Codewright Professional optionally makes available Unix-style Regular Expressions for use in searching. They have now gained wide acceptanceoutside the Unix realm. The relatively small investment of time required to gain a usefulknowledge 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 helpyour 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 simpleexpressions are usually a subexpression of a more complex regular expression. Inreading the descriptions that follow, an "expression" may mean a single character, a groupor class of characters. These topics are described in detail in this section of the manual.

Special Characters

Regular Expressions give special meaning to certain characters. Some are operators andsome 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 calledmetacharacters. These characters and their meaning are shown below:

Escape Sequences

128

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 aReference Group which may be pasted into a replacement string.

| Alternation. Allows matching the expression on the left or on the right ofthe 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 asuccessful search.

Escape Sequences

There are times that you want to use a metacharacter as itself -- without the specialmeaning that Regular Expressions gives it. For example, you may wish to match a dollarsign, rather than look for the end of a line. To match a dollar sign you must escape orquote it. This is done by preceding the character with a backslash. This is true of all themetacharacters. To match a dollar sign, for example, you use \$ in your RegularExpression, rather than just $.

Below is a list of other escape sequences supported by Codewright Professional's RegularExpressions:

Character Classes

129

Escape Meaning\n Newline (<CR><LF> or <LF>, depending on how it is defined for

the document)\t Tab\b Ctrl-H (backspace)\r Carriage return\f form feed

\ nnn Octal value between 0 and 0377.\x nn Hexadecimal digit between 0x00 and 0xFF\ m The literal character m.

Matching a Character

The basic unit of a regular expression is matching a single character. You can match asingle 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 escapesequence. 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 thedot 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 ofcharacters, any one of which may match. For example, the character class

[AEIOUYaeiouy]

matches any vowel, whether upper or lower case.

Ranges of characters may also be specified within a character class. This is done byplacing a dash between the character that begins the range and the character that ends therange. The following character class

Iteration Qualifiers

130

[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, justplace it at the beginning or end of the character class where it is not between twocharacters of the class. If you precede the dash with a backslash ( \ ) you can put itanywhere within the class.

The caret ( ^ ) has a special meaning when it appears as the first character of a characterclass. It complements the class. When it appears at any other position within thecharacter class, it just adds the up-caret to that class. You may use it as a shorthandmethod of saying "match any characters except for the following:", rather than specifyinga large character class. For example,

[^$.|(){}*+?^]

matches anything except the eleven characters following the up-caret.

Escaping Characters in a Class

Metacharacters may be used in character classes without escaping. The only charactersthat must be escaped are as follows:

] " \ and sometimes - and ̂ depending on the position within the class.

Escape the - when you use it in the middle of a class but don't intend it to signify a range.Escape the ^ when it would otherwise be at the beginning of a class but you do not intendfor it to signify complement. When in doubt, escape the character. It can't do any harm.These characters look like this when escaped:

\] \" \\ \- \^

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 canbe, in order to match. These metacharacters are: *, + and ?. As stated in the table above,the * matches any number of occurrences, the + matches one or more, and the ? matches

Beginning and End of Line

131

zero or one. Without these qualifiers, a regular expression will match exactly oneoccurrence in the text.

Let us consider some specific examples of how these qualifiers might be used in the taskof 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, itcould 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 , andthe plus sign says "one or more of the previous". To match whitespace, we need to matchspaces too. We don't know what order the spaces and tabs will come in, and we don'tknow 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 + signfollowing it means that this Regular Expression will match any combination of spaces andtabs, 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 mightbe 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. Sincethe left parenthesis is a metacharacter it is necessary to escape or quote it with a precedingbackslash. The \t we have used before to represent a tab character. The question marksays "zero or one of the preceding".

Beginning and End of Line

You may use the metacharacters ^ and $ to qualify your Regular Expression further. Wehave already seen how the ^ may be used to complement a character class, but it hasanother 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 endof a line, respectively. Unlike the iteration qualifiers, however, these metacharacters can

Alternation and Grouping

132

stand alone as Regular Expressions. That is, you can search for just the end of the line orjust the beginning of the line.

^PUBLIC$$^\)$

The first of the examples above matches the word "PUBLIC" when it occurs at thebeginning of a line. The second example matches a right parenthesis, a character whichmust be escaped, when it is found at the end of a line. The third example matches a rightparenthesis 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 theprimary need for grouping.

Alternation uses the metacharacter | to denote that a match has been found if the textmatches either of two Regular Expressions. This operator may be repeated to indicatethat the text may match any one of several expressions.

Because of the typical order of precedence, the alternation applies to the entireexpression, if not limited by grouping. Grouping occurs when you place parenthesesaround one or more expressions that are part of a larger expression.

Here are some examples of how these two features work together:

PUBLIC|PRIVATEPUBLIC (void|DWORD)^PUBLIC[ \t]+(void|int|long|DWORD)

The first of these examples matches either the word "PUBLIC" or "PRIVATE". Thesecond matches the word "PUBLIC", when followed by a single space, and then followedby either the word "void" or "DWORD". Note the use of grouping in this example. Thethird 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 followingwords: "void", "int", "long" or "DWORD". This begins to show the power of regularexpressions.

Placing the Cursor

133

Reference Groups and Replacement Strings

In addition to showing association and precedence, grouping allows the use of ReferenceGroups. A reference group is one or more expressions that have been placed betweenparentheses and then pasted into a replacement string by referencing its number.

Codewright Professional assigns a reference number, from 1 to 9, to the text matchingeach group defined. Reference numbers are assigned from left to right. You may pastethe associated text into a replacement string by using this number, preceded by abackslash.

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 leftparenthesis, with a backslash. There are a few escape sequences that are meaningful in areplacement string, such as those used by reference groups, but such sequences are notthemselves regular expressions.

An operation using reference groups, such as that depicted above, could be used toreverse 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 representthe matching text in its entirety. You reference this group in the replacement string withan & at the desired location. This means that you must use \& to specify an ampersand ina 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 somethingwith it or to it. After a successful search operation, Codewright Professional positions thecursor at the beginning of the matching text -- at least, that is the default action. What ifyou want to edit the other end of the matching text, or perhaps the middle?

Examples

134

When using Codewright Professional's regular expressions, you have a special escapesequence available that allows you to indicate where in the matching text the cursorshould be positioned. You should note that this is available only for search operations. Itis 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 theleft and right square brackets. The square brackets are metacharacters and are thereforeescaped. This cursor positioning facilitates editing the contents of the square brackets.

Examples

135

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)

([Â-Za-z0-9]|^)[A-Za-z0-9]+ Beginning of word (Non-alphanumeric)

[A-Za-z0-9]+\c([Â-Za-z0-9]|$) End of word (Non-alphanumeric)

/\*.*\*/ Single-line comment (C language)

/\*.*\n([ \t]*\*.*\n)*.*\*/ Multi-line comment (C language)

136

General Operation

This chapter presents Codewright Professional topics that you may need to consult on areference basis from time to time. The topics are presented in alphabetical order, foradded convenience.

Backup Files and Directories

Codewright Professional allows you to specify where and under what name you wish tostore backup files. It even allows you to define how to derive the root or extension of thebackup filename from the file being backed up.

If you find, even with this flexibility, that it is hard to come up with a backup system thatapplies equally well to all files, there is more. There is also the notion of global and localbackup specifications. The functions BufSetGlobalBackupSpec andBufSetBackupSpec allow you to set a system wide method of dealing with backups, andallow setting an individualized method for a document that overrides the global method.These functions are paired with the query functions BufQGlobalBackupSpec andBufQBackupSpec that allow you to discover the current backup settings.

If you plan to assign backup specifications to individual buffers, you may automate theprocess by assigning a function to the "Document Created" event. This function could,for example, look at the extension on a file whenever a new document is created, andassign an appropriate backup specification.

Backup locations and the filenames used are controlled with formatting strings. Theformatting strings contain format controls and transformation patterns that tell CodewrightProfessional how to deal with file names that are unknown as yet.

It is possible to specify a format that will result in an illegal filename.Codewright Professional does not attempt to ensure that the resultingfilename is legal. When you attempt to backup the file, an error will occur,just as if you had specified an illegal filename for saving a file.

Setting both the local and global formatting strings to empty strings effectively turnsbackups off. This may also be done by turning off the DOCUMENT_BACKUP attributeof the document's SysFlag, using the BufSetSysFlags function. Initially, backups are


137

turned on, and the backup is made in the same directory as the file being backed up. Thebackup file is given the extension .BAK.

Backup Formatting Strings

The formatting strings used to specify the location and names of backup files may remindyou of the formatting strings used by printf() and similar C language library functions. Aspreviously stated, these strings contain format controls and transformation patterns, whichare used in conjunction with some of the format controls. Format controls begin with asingle percent sign ( % ). Any other text is treated literally.

The format controls available for use in backup formatting strings are listed in the tablebelow. Note that optional portions of these format controls are enclosed in italicizedsquare brackets. Examples are based on the output filename C:\SRC\FOO.BAR:

Control Represents Description%b basename The entire name of the output file (fully qualified),

less the extension. (e.g., C:\SRC\FOO)%d directory Includes the path, less the drive (volume) specifier

and filename, but ends with a backslash only ifdescribing the root directory. (e.g., \SRC)

%[ {...} ] e extension Includes the dot that separates the basename from theextension, unless the name of the output file has noextension. May optionally contain a transformationpattern, as described below. (e.g., .BAR if notransformation pattern supplied)

%f filename The root name and extension.%p path Does not include the drive (volume) or filename.

Always ends with a backslash. (e.g., \SRC\)%[ {...} ] r root Does not include extension, drive (volume) or path.

May contain an optional transformation pattern, asdescribed below. (e.g., FOO if no transformationpattern supplied)

%v volume The drive letter and the colon. (e.g., C:)%% percent A single percent sign is represented by two

consecutive percent signs (%%).

As an example, the formatting string which represents the initial default is "%b.BAK" .You would set this default using a function call like the one below:

BufSetGlobalBackupSpec="%b.BAK"


138

Transformation Patterns

The root and extension format controls, described above, may contain transformationpatterns. These patterns describe modifications within the root filename and extension.You enclose the pattern within curly braces and place it between the percent sign and thecontrol character, r or e respectively.

You supply the pattern in two parts: the override pattern and the fill pattern:

• The override pattern specifies characters, each of which replaces characters atthe same position within the original root or extension string. The overridepattern also may limit the length of the resulting string.

• The fill pattern specifies characters to fill empty positions within the root orextension string.

A single vertical bar ( | ) separates the override pattern from the fill pattern. If you aresupplying only the override pattern, you may omit the vertical bar. Supplying only the fillpattern is pointless, since the resulting string will be empty.

The rules are the same for using transformation patterns, whether you are using them onthe root of a filename or its extension. There is one noteworthy difference in their result,however. After the transformation is performed on an extension, the resulting extensionis examined. If the extension is not null, a dot is added to the beginning of the extension.This is true whether or not the original extension was null.

Override PatternThere is a character in the override pattern for each character in the resulting string. Thecharacter at each position may be either a valid filename character, or a question mark ( ?). If a filename character ivs specified, the character in the original string is replaced bythat character. If a question mark appears at a given position in the string, the character inthe original string is used. If no character appears in the override pattern for a givenposition (i.e., the root is shorter than 8 characters or the extension is shorter than 3), theresulting string is truncated at that position, even if a you have supplied a fill pattern.

Fill PatternThe fill pattern may contain only valid filename characters. The character at a givenposition in the pattern is used in the resulting string if that position in the original string isempty (i.e., the original string is shorter than the fill pattern) and a question mark isspecified by the override pattern.

Command Key

139

Illustrative Examples

The following illustration shows how the characters in the override pattern takeprecedence over those in the original extension, and how the fill pattern charactersbecome the default:

Here is the resulting extension (less the preceding dot):

The following examples demonstrate the effects of various override and fill patterns:

Pattern Original Name Backup Name

%r%{??~|___}e foo.cpp

foo.c

foo.cp~

foo.c_~

%r%{??~}e foo.cpp

foo.c

foo.cp~

foo.c

%r%{~??}e foo.cpp

foo.c

foo.~pp

foo.~

%r%{~}e foo.cpp

foo.c

foo.~

foo.~

%r%{?}e foo.cpp

foo.c

foo.c

foo.c

%{???????~|~~~~~~~~}r%e foo

foo.c

testfile.c

foo~~~~~

foo~~~~~.c

testfil~.c

%{?????}r%{???|bak}e foo

foo.c

testfile.c

foo.bak

foo.cak

testf.cak

Command Key

The Command Key is a keystroke that calls the LibFunctionExec function. It providesan interface to Codewright's API while you are running Codewright.

Command Key

140

If you find you want to do something in Codewright for which there is neither a keycommand nor a menu entry, you can probably do it using the Command Key. If you areusing the CUA and vi command set, the Command Key is �. If you are using the

BRIEF-compatible command set, the Command Key is �, which in BRIEF provides

access to the BRIEF interpreter. In keymaps where there is no such assignment, you canstill execute an API Command by selecting API Command from the Tools menu.

When you press the Command Key, a prompt appears on the status line or in a pop-updialog box, depending on which is enabled:

Command:

You then respond by entering a Codewright API function call, much as you would enter itin Codewright's C source code. Pressing ( sends the command off for processing.

Command Completion

In addition to the command history, described in the previous section, you can also usethe command completion feature. This feature is only available when status lineprompting is in effect, rather than the pop-up dialog. You can control which type ofprompting is used through the System tab of the Environment dialog found on the Toolsmenu.

Figure 3: Command Completion list after entering "color"

Command completion allows you to enter as much of a command (function name) youcan recall and then press the 7 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

Command Key

141

from that list and it is placed on the prompt line for you. If you want a complete list ofthe 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 theCodewright API -- at a minimum, you need to know the name of a function you want toexecute. The Online Programmer's Reference is the place to learn more about theCodewright API and specific functions, whether you want information about a topic orjust 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 wantmore. Soon they start delving into the supplied DLL source code and, before they knowit, 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 dialogs and menu entries to see if what you aretrying to do can be done through the menu. On the other hand, those who are morecomfortable issuing commands than making selections from a menu (a la SPF, or evenBRIEF), 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 andthrough the Command Key:

• Parameters may be only numeric values and strings. Parameters may not bevariables or nested function calls, when issued through the Command Key. Theonly exception to this is that the various identifiers/labels listed in the OnlineProgrammer's Reference may be substituted for numeric values. Expressionsthat employ only bit-wise AND, OR and complement (&, | and !) may also beused.

• Some API functions cannot be issued through the Command Key. In particular,functions that return allocated strings and functions that have a variable numberof 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 aparameter cannot be issued. These functions may only be used in source code.The description of each affected function clearly notes this limitation.

Command Key

142

• User written functions are available only when registered. The functionLibExport must be used to register a user function, its parameters and returnvalue before it may be called from the Command Key.

• Parameters may be omitted. If you omit parameters from a function call issuedthrough the Command Key, Codewright will either fill in default values or thecall will fail. In source code, you have no option but to supply parameters, ifyou want it to compile.

• The format permitted and required varies from that of source code. Therequirements on quoting string constants are stringent so that other requirementsmay be more lax. Spaces can be used to separate function parameters in place ofcommas, and spaces, equal signs, or parentheses may be used to separate afunction name from its parameters.

Displaying Return Values

It isn't very useful to use one of the Query functions via the Command Key to queryCodewright about one thing or another unless you can see a response. Since virtually allCodewright Query functions respond by returning a value, you'll need to tell Codewrightto show you what value a function returns. You can do this by beginning your commandwith a question mark. Here is an example of how such a command might look, justbefore sending the command off for processing:

Command: ?BufQModifiedCount

When the return type is a numeric value, Codewright displays that number on the statusline 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

BufSetHexBinaryBufSetHexBinary()bufsethexbinary

All three of these examples do the same thing. They put Codewright in the Hex Editingmode, with the cursor located in the "binary" portion of the display.

MovNextChar( 2 )Movnextchar 2

Command Key

143

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 document 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 Online Programmer'sReference.

Expression Evaluator

The Command Key provides another capability that you may find useful in programming,debugging, or just in place of a calculator. Codewright can evaluate a numeric expressionthat uses C language operators and grouping, and display the result.

You signify that your response to the Command: prompt is an expression you wish toevaluate by preceding the expression with two question marks. You can use Codewrightidentifiers in these expressions. Here are examples of an expression to be evaluated:

??SELECTION_INCLUSIVE

??0xcf54-3*4

??MARK_GLOBAL+1

The following operators are supported in expressions, grouped by precedence, and listedin order of decreasing precedence:

Line Drawing

144

Operator Operation( ) Grouping

- Unary Minus

~ Bitwise Complement

! Logical NOT

/ Division

* Multiplication

% Modulus

- Subtraction

+ Addition

<< Bitwise Shift Left

>> Bitwise Shift Right

> Greater Than

< Less Than

<= Less Than or Equal

>= Greater Than or Equal

== Equivalence

!= Non-Equivalence

& Bitwise AND

^ Bitwise Exclusive OR

| Bitwise OR

&& Logical AND

|| Logical OR

Line Drawing

A line drawing package is supplied with Codewright Professional that allows you to drawboxes, lines and simple charts, using the IBM Extended Character Set. If you or asubsequent viewer are using a font other than one of the "OEM" or terminal fonts, thelines and boxes drawn with this package will look like garbage.

To use this package, a Dynamic Link Library named CWLDRAW.DLL must be loaded.Look in your Codewright Professional configuration file, usually CWRIGHT.INI, andfind a line like the one below in your [LibPreload] section:

LibPreLoad=CWLDRAW.DLL

In your file, the line may be preceded by a semicolon, which disables the use of the DLLby commenting it out. If so, remove the semicolon so that the line drawing package will

Line Drawing

145

be available the next time you start Codewright Professional. If your configuration filedoes not have a line like the one depicted above, place this line in the file.

The line drawing package uses the arrow keys on the cursor pad to draw lines when the) and + keys are also depressed. There is another entry you can place in your

configuration file to make the necessary key bindings to do this. Put the command belowon the line following the line that loads CWLDRAW.DLL:

SetLineDrawBindings=

Here are the key assignments installed by this command:

)+= Move up and insert appropriate character.

)+< Move down and insert appropriate character.

)+4 Move left and insert appropriate character.

)+5 Move right and insert appropriate character.

The "appropriate character" is determined by whether you are drawing a straight line,turning a corner, or intersecting with another line. It also depends on which line drawingstyle you select. The example below demonstrates the styles available:

Use the function SetLineDrawStyle in your configuration file, or through the APICommand Key to set which style the line draw package will use. The default style isStyle 1. You can use the same command, regardless of which method you are using to setthe style. From the API Command Key, it would look something like this:

Command: SetLineDrawStyle=4

This sets the line drawing style to 4. You will probably find that Overtype mode is bestfor adding labels to boxes and charts.

Menu Editor

146

Menu Editor

The Menu Editor allows you to change, delete and add menus and menu itemsinteractively. It is located on the Menu tab of the Environment dialog on the Tools menu.(At least, before you use the Menu Editor that is where it is.

MenusMenus 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 relativeto other menus. Up and down refer to the position in the listbox. Up moves theselected menu to the left on the menu bar, while Down moves the menu to theright.

• Add Menu The Add Menu dialog lets you add a menu to Codewright's menubar. You must provide a name for the menu, a unique ID number, a helpfulmessage to display when the menu is selected, and, optionally, one or morefunctions to initialize the menu. The initialization functions are responsible fordisabling or check marking menu items as necessary.

Menu Editor

147

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

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

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

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

• Add Item The Add Item dialog lets you add an item to one of Codewright'smenus. You must provide a name for the item (Menu item text), a unique IDnumber (ID), a helpful message to display when the menu is selected (Helpstring), 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 enterthat keystroke for display on the menu (Key string).

• 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 functionsto initialize the submenu.

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

• Delete The Delete button deletes the selected item. You could delete all itemsin 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 atthe selected position within the menu.

Prompt Histories

148

• 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 areusing One-document-per-window mode, the list of edit buffers is not available.(See System tab on the Environment dialog) Each of these lists may only appearon one menu. Therefore, you must first delete a list from a menu before you canadd it to another. This button is disabled if there are no unassigned lists.

Operating on SubmenusTo 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 theleft 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 onthe right by double clicking on the name again. The minus sign will change back to a pluswhen it arrives in the list on the right.

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

Prompt Histories

Many of Codewright's prompts remember previous responses you have made at thatprompt. Most notably, the Command Key prompt, the Search and Replace prompts, andthe prompt at which you enter the name of a file to edit have prompt histories.

Status LineWhen the prompt appears on the status line, the prompt history may be activated bypressing either the up arrow or the down arrow. Pressing the up arrow reuses the mostrecently entered response, whereas pressing the down arrow reuses the oldest. Repeatedlypressing the up arrow allows you to view earlier responses. Repeatedly pressing the downarrow key views more recent responses. Pressing ( accepts the response displayed.

As each historical response is displayed, you will note that it is highlighted. If you issuean editing command, such as , , or , the highlighting disappears andyou are permitted to continue editing the response. You can accept the edited response atanytime by pressing (. If, when the response is still highlighted, you type characters,

the typing replaces the highlighted text. This allows you to easily type in a new response,if the one you are looking for isn't in the history.

Prompt Histories

149

Dialog BoxesIn dialog boxes, a "combo" box is used to present prompt history. Pressing the downarrow button to the right of the edit box will cause a list box to drop down, containingprevious responses to the prompt. Select one, and you are ready to edit or execute thecommand.

There is a history editor on the History tab of the Environment dialog on the Tools menu.It allows you to view and remove members of these prompt histories. Many prompthistories are saved between Codewright sessions by default. This information is saved inthe State file. For more information about Codewright State files, refer to the"Configuration and State" chapter of this manual.

150

Configuration and State

Codewright's configuration data is kept in a separate file. During initial installation, theconfiguration file CWRIGHT.INI is placed in the same directory as your Codewrightexecutable file. You may move it to another location, if you like, or you may have severalconfiguration files in different work areas. You may even specify another name for thefile.

If your Codewright executables are installed on a network, you will almost certainly wantto place your configuration file somewhere else. By placing your configuration file in aprivate or local directory, you ensure that you will not be using or changing someoneelse's configuration.

Codewright looks in several places to determine what configuration file to use. When itfinds a place where you have indicated the location of the configuration file, or the fileitself, it looks no further but proceeds to read the file. Here are the places thatCodewright looks, in the order of searching: It looks

• on the command line to see if you specified the /C flag ,

• in your environment for a variable named CWINI ,

• for CWRIGHT.INI in your working directory (working directory is also setthrough File Properties in the Program Manager),

• for CWRIGHT.INI in the directory containing CW.EXE or CW32.EXE,

• or for CWRIGHT.INI in the Windows directory.

The command line flag, or the environment variable will have an associated string value,when it is used to point to the configuration file. This string names the directory in whichthe configuration file resides. It may also name the file itself. For example, the stringmay take this form when specifying a directory:

d:\source\project1

It may also take this form when specifying a file:

d:\source\projects\cencom.cfg

If Codewright does not find a configuration file at all, it will create one in the workingdirectory, when it needs one. Codewright has no problem running without a configurationfile, but it does notify you if one could not be found.

Introduction to Configuration and State

151


To properly understand Codewright's projects and workspaces, you need to have someknowledge of how Codewright maintains its configuration and how it preserves its statebetween sessions. This will help you intelligently choose which information is kept inwhich file. In addition, you may find it expedient to modify Codewright's configurationfile directly. This section will give you the information to do these things.

Configuration File

The configuration file normally contains information about the way you have Codewrightset up. This information may be put there during installation, through modifying thesettings in dialog boxes, or by directly editing the configuration file. In the latter case, theconfiguration file might contain almost any Codewright commands. The configurationfile is nominally CWRIGHT.INI.

The configuration file is a text file that follows the same general format as other Windows.INI files. It contains section headings enclosed in square brackets followed byconfiguration statements. Headings that appear in a Codewright configuration fileinclude: [Editor], [LibPreload], [Colors], [DefaultKeymap], [KmapAssign], [Printer],[Compiler], [VersionControl], [Definitions] and [Fmatch].

The configuration statements contain keywords with string assignments. For the linescontaining keywords, the format is as follows:

<function>=<param 1>[,<param 2>,...<param n>]

The keywords are actually the names of functions in the Codewright API. The stringassigned to the keyword contains the parameters required by that function. The assignedstring may contain whitespace. The parameters may be numbers, strings, constantidentifiers and operators. Variables and nested function calls may not be used asparameters.

State File

The State file contains information about the buffers and windows you had open when lastyou exited Codewright. It also contains the more transient information about yourCodewright settings, such as your search options and responses to prompts. It follows thesame rules as a configuration file, but it is normally limited to one section named [State].This file is nominally CWRIGHT.PST.


152

Other Files Containing Configuration Data

Project files also contain configuration information. These files are intended to beswapped on the fly, whereas the configuration file remains constant throughout a session.The project file overrides any information duplicated in the configuration file.

As you change settings in the various dialog boxes, you are automatically updating yourconfiguration. You may select which file the dialogs use to update configurationinformation: the configuration file or the project file. You may further select whichcategories of information are kept in which file.

These selections are made through the Options tab in the Project Properties dialog. Themain question you need to ask yourself in order to be able to make these selections is "DoI want this setting to travel with the project, or have it transcend individual projects?" Ifyou want to have it travel with the project, have it stored in the project file. To transcendprojects, the information should be updated in the configuration file.

Example File

Here is an abbreviated example of a configuration file:

[DefaultKeymap]DefaultKeymap=brief

[KmapAssign]KmapAssign=<Ctrl-`>, Preprocess

[LibPreload]LibPreload=PRG.DLL

[Editor]KeyDelay=1200KeyRepeat=5Autosave=20SysSetFileLocking=30

[Colors]ColorError=0xe0ColorWarning=0xd4SysSetDefault=DEFAULT_COLOR_TEXT,0x1fSysSetDefault=DEFAULT_COLOR_SELECTION,0x9e

[Printer]PrintLineInc=5PrintFooter="-Page %p-"PrintHeader="%f %d %t"PrintFlags=145


153

PrintMarginBottom=0PrintMarginRight=0PrintMarginLeft=0PrintMarginTop=0

[Definitions]EvalStrAdd=DEBUG,1

[Compiler]CompilerAssign='Borland C++','.c'

Example Interpretation

Here is an interpretation of the contents of the example configuration file above. Theanalysis proceeds section by section:

Editor SectionThe Editor section of the example configuration file sets the keyboard delay and repeatrate. Auto-save is set to occur after 20 seconds of keyboard inactivity. File locking isenabled for 30 file handles

Colors SectionThe Colors section of the example sets the color of error messages to black on yellow,and the color of warning messages is set to red on gray. These are global settings. Thenext two color settings may be set differently for each edit window. For this reason, wedo not use the functions ColorText and ColorSelection to set the colors, but rather setwhat the default color will be. You use the SysSetDefault functions when setting defaultsfor things that are specific to individual buffers or windows. In this case, the color of textis set to white on blue, and the highlight for the selection is set to yellow on light blue.

DefaultKeymap SectionThe default key command set to BRIEF. This will cause BRIEF.DLL to be loaded and itsfunction brief to be called.

KmapAssign SectionIn the KmapAssign section, a key assignment is added to the default keymap. ThePreprocess function is assigned to the Control - Backquote keystroke.

LibPreloadOne of the supplemental language support DLLs is loaded for use.

Processing At Startup

154

Printer SectionThe Printer section and a number of other sections use private, undocumented functions.The Print menu item within Codewright controls the contents of this section. You canprobably guess what most of it does, but you are not encouraged to fiddle with it.

Definitions SectionThis section defines the label DEBUG and gives it a value of one. This label may be usedin numeric expressions processed by Codewright, including those given through theCommand Key and the Preprocess function (#ifdefs).

Compiler SectionIn this section, the Borland C++ compiler is assigned for use on files that have the .C fileextension.


When Codewright is launched, the command line is processed before the configurationfile or the state file. This gives the command line the opportunity to specify the locationof these files. It also means there is some potential for the configuration file to reverse theeffects of a parameter specified on the command line.

The following sections of the configuration file are automatically read at startup in theorder given:

• Menu

• DefaultKeymap

• KmapAssign

• LibPreload

• Editor

• VersionControl

• Template

• Colors

• Ribbon

After the portions of the configuration file that are automatically read have beenprocessed, the state file is processed. This gives settings in the state file priority oversimilar commands in the configuration file.


155

Order of Processing

The functions under each of the section headings are executed in the order they are listed.Regardless of the order in which the sections occur, however, the sections are alwaysexecuted in the same order. The Printer, Compiler, Definitions and other sections areprocessed as needed.

Each section heading represents a logical grouping of functions, as shown in the listbelow:

+HDGLQJ )XQFWLRQV

Colors Functions to set the colors for text, messages and so on. This is donewith the SysSetDefault function described in the OnlineProgrammer's Reference.

Compiler Used primarily by Codewright for saving associations between fileextensions and compilers.

DefaultKeymap The function that sets the initial key command set, usually Brief orCUA. For example, the statement DefaultKeymap=brief will causeCodewright to load BRIEF.DLL and call its keymap function, whichit assumes to be the same as the filename root -- brief .

Definitions Defines labels for use in expression evaluation.Editor System-wide functions, default settings (except for keymap), and any

other functions that are not order dependent.Fmatch Used by Codewright for saving the parameters used by the File Find

and File Grep features.KmapAssign Key assignments that are additions or modifications to the default

keymap.LibPreload Load DLLs that are not automatically loaded.Menu Defines the menu structure, if other than the default. The results of

using the Menu Editor are placed here.Printer Used by Codewright for defining print margins and headers.Ribbon Defines modifications to the default ribbon and sidebar configuration

after using the ribbon editor.Template Contains user-defined Language Template definitions.VersionControl For defining command lines for Check-in, Check-out and several

other related commands. The section is duplicated for each versioncontrol system defined, so that you may have separate commands foreach.

You may place any Codewright function under any of the section headings, but groupingfunctions logically under section headings will help ensure that the functions are executed

User Defined Sections

156

in their proper order. For example, you could place the default keymap in the Editorsection, but then the modifications and additions made in the KmapAssign section wouldbe lost when the keymap is loaded over top of them.


You may define other section headings and place other editor commands under thosesections. These commands will not be processed automatically at startup, however.

Many functions you might want to create for assignment to a keystroke are a simplesequence of functions to execute consecutively. Return values are not examined, and nocontrol structures are required. Under these conditions, you can place the sequence offunctions in a user defined section, and assign the processing of that section to akeystroke. Here is an example:

[ISearchBack]SrchSetFwd=FALSEISearch=SrchSetFwd=TRUE

This example simplifies the process of performing an incremental search backwards in thebuffer. Usually, the search options are set to search forward. You could bring down themenu and change the options and then change them back, after performing yourincremental search. The example above changes the search options to search backward,performs the incremental search and then sets the search direction to forward.

After you have created this section in your configuration file, you could make a keyassignment like the one below, also in your configuration file:

[KmapAssign]KmapAssign="<F12>","ConfigFileRead '' 'ISearchBack'"

This key assignment will cause Codewright to do a backwards incremental search when� is pressed. You can use this example key assignment to implement other examples or

sections of your own.

Save and Restore PositionThe following example can be used in place of the standard save and restore positioncommands:

[RotateMarks]


157

MarkRestorePos=MarkSavePos=MarkRotatePos=

[StackMarks]MarkSavePos=MarkRotatePos=

If you use StackMarks to save your current position, you will restore positions in the sameorder you saved them instead of the reverse order in which you saved them. By usingRotateMarks instead of the restore position command, restored positions are not lost, butrather moved to the other end of the list. You can then continuously cycle through yoursaved positions. Together, these two sections give a functionality similar to that ofMicrosoft's PWB.

Scrap BuffersThis next example makes good use of Codewright's Multiple scrap buffers. For it to beuseful, you must first define more than one scrap buffer. You define the number of scrapbuffers in the Clipboard tab of the Document Preferences dialog. Use these sectionsinstead of Cut, Copy and Paste:

[RingCopy]BlockCopy=ScrapNext=MsgMessage="Copied to current scrap"

[RingCut]BlockCut=ScrapNext=MsgMessage="Cut to current scrap"

[RingPaste]ScrapPrev=BufInsertScrap=MsgMessage="Current scrap inserted"

When using these three sections in place of Copy Cut and Paste, you get a last-in first-outring of scrap buffers. Successive copy or cut operations (without an intervening Paste) donot overwrite each other until you run out of scrap buffers. Successive Paste operationslet you paste the contents of each scrap buffer in the reverse order they were used.

Relating Checkboxes to Functions

158

Relating Checkboxes to Functions

There are a series of checkboxes common to the Options tab of the Project Propertiesdialog and the Read Configuration Data dialog. The following list will help you relatethose checkboxes to the contents of your configuration file or project file:

Checkbox Option Related Configuration FunctionBuffer 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

TagSetFileCompilerAdd

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

State File

159

State File

At your option, Codewright's condition at the time you exit may be recorded in a file. Aspart of the installation process, you had the opportunity to turn this feature on or off. Ifyou elected the default setting, saving the state was turned on.

You may specify the location and name of your state file in your Codewrightconfiguration file. If you name a location for your state file by accessing a dialog boxthrough the menu, it will be saved in your configuration file. If your configuration filedoes not contain the name of your state file, and saving state information is turned on,Codewright will search for the location of the state file in much the same manner used tolocate the configuration file. The differences are as follows:

• The command line flag for specifying the state file is /S.

• The environment variable that points to the state file is CWPST.

• Instead of looking for CWRIGHT.INI, however, it will be looking forCWRIGHT.PST.

Once again, if no location is dictated for the state file, and no existing file is found, thefile is created in the working directory. Codewright can operate just fine without a statefile. In fact, you may turn off the saving of state information, and Codewright will ignoreany state file and the information it contains.

Similar to the configuration file, the strings that give the location of the state file mayalso dictate a name for the file. If the string names only a directory, the nameCWRIGHT.PST will be used. The following methods of setting the location of the statefile are all valid:

Using the environment variable --set CWPST=d:\premia

On the command line --cw /sd:\premia\cwright.pst

In the CWRIGHT.INI file --StateSetFilename=H:\home\ericj

Contents of the State File

The following are among the data kept in the state file:

State File

160

Windows• Visible attributes• Colors• Coordinates and extents• System flags• Attached buffer, if any• Default Window Properties for the above

Buffers• File name• Output file name• Tab settings• Backup file specification• Line and column• Max. virtual lines• Current mode (hex, compact, normal)• System flags• Default Buffer Properties for all of the above

Prompt Histories• Search and Replace• Command Key• Open file

Miscellaneous• Search flags• Codewright's Window frame coordinates and extents

161

Command Line Parameters

Codewright supports a number of command line parameters. You may add theseparameters to the command line by editing the file’s shortcut, or through the FileProperties selection in the Program Manager's menu. If you have multiple Codewrightshortcuts or program items, the command line may be used to have each operatedifferently.

Different program items may, through the command line, specify different configurationfiles, different files to load, and even different state files. The process of creatingmultiple Codewright program items is described in the "Getting Started" manual.

The command line is processed before the configuration file and state file have been read.This allows the command line to specify the location of those files. This also has theeffect of allowing the configuration file and state file to override things on the commandline. This is not normally a problem, if you follow the stated guidelines for the use offlags and the contents of these files. Configuration files and state files are furtherdescribed in the chapter "Configuration and State".

Codewright allows three types of command line parameters. The first of these is thenames of files to edit. The second is flags or switches. The third is the command file,which contains command line parameters. The command line is processed before thestate file is read. As a result, some command line parameters may be overridden, unlessreading the state file is inhibited. Such possible conflicts are noted in the descriptionsbelow.

Filenames

You may specify any number of files to edit on the command line, limited only by thecommand line length. You may use wildcards to specify multiple files. These files areloaded in addition to, rather than in place of, any named in the state file.

Flags

Consider whether you wish to allow the configuration file to be read before or after eachflag that you specify. The configuration file may in some cases cause a command lineflag to be ineffective if the flag is processed first. There are upper case and lower case

Flags

162

versions of each of the Command line flags, where ever applicable. Flags specified with alower case character will be processed before the configuration file is read. Flags that usean upper case character will be processed after the configuration file is read.

Some flags require additional information in the form of an argument. The argumentsappear in italics following the flag, in the descriptions below. When supplying anargument to a flag, Codewright permits the argument to immediately follow the flag, withno intervening whitespace, or to be separated from the flag by whitespace.

The flags listed below are depicted as preceded with a minus or dash character ( - ).While a slash will also work in most instances, these can be mistaken for filename pathsand should be avoided.

-C<configLoc>

The configuration location flag allows you to specify the directory or file in whichconfiguration information is to be found. The configLoc argument names that directoryor file. If configLoc names only a directory, Codewright looks for a file namedCWRIGHT.INI in that directory from which configuration is read. If it names a completepath, including filename, Codewright will attempt to read configuration information fromthat file.

When this flag does not appear on the command line, Codewright looks for aconfiguration information in a series of places. These places include:

• a directory or file named by the CWRIGHTINI environment variable,

• in CWRIGHT.INI in the Working Directory,

• in CWRIGHT.INI in the directory in which the CW.EXE or CW32.EXE file islocated,

• or in CWRIGHT.INI in the windows directory.

This default search for configuration information is described in greater detail in the"Configuration and State" chapter of this manual.

Example:

cw -c c:\source\proj1

-C-

This is a variant of the configuration location flag that instructs Codewright not to read aconfiguration file.

Flags

163

Example:

cw -c-

-G <lineNumber>

Go to the line number indicated by the argument. It should follow the name of the file towhich it refers, and it may be specified following each file named on the command line.This flag will be overridden if you attempt to position the cursor in a file loaded as part ofthe state restoration.

Example:

cw -g215

-heapalloc

The heap allocation flag may be used for user debugging purposes. THIS OPTION ISONLY AVAILABLE ON THE 32 BIT VERSION OF CODEWRIGHT. When used,Codewright will use global allocation of memory. This makes it easier to detectallocation errors. Use this if you suspect your DLL has this type of memory error.

Example:

cw -heapalloc

-K <keymap>

The keymap flag names a default keymap to be used by Codewright. If this flag is used,the [DefaultKeymap] section of the Codewright configuration file will not be read. Thekeymap argument to this flag names a DLL (less the .DLL extension) containing thedefault keymap. The argument at the same time names the function contained in the DLLwhich initializes the keymap and makes the key assignments.

Example:

cw -k mycua

-L <library>

The library flag designates a dynamically linked library to be loaded at startup time. Thisflag is useful for testing user created or modified DLLs before a more permanent

Flags

164

installation. It can, however, significantly increase the amount of time it takesCodewright to start up.

The library argument is the name of the library to be loaded. If this argument does notname a path to the DLL, Codewright will look in the current directory, the Windowsdirectory and on the PATH, in an attempt to locate the DLL.

Example:

cw -Lmyutils

-M

The multi-instance flag allows you to run more than one instance of Codewright at a time.By default, multiple instances are disallowed. Your operating system must be eitherWindows 95 or Windows NT for this option to work.

Example:

cw -M

-N

The no files flag indicates that the state file is to be processed, except that no files fromthe previous session are to be restored.

Example:

cw -N

-NOSPLASH

The No splash flag suppresses the display of Codewright’s opening splash screen. Thiscan save a small amount of loading time.

Example:

cw -NOSPLASH

Flags

165

-P <section>

The paragraph flag tells Codewright to read the named section of the configuration file.The section will be read after all of the standard portions of the configuration file havebeen read, to give it priority over the other contents of the configuration file. Foradditional information about configuration files and their contents, consult the"Configuration and State" chapter of this manual.

The section argument to this flag is the name of the section of the configuration file to beprocessed. If you name a section that is automatically read at startup, it will be processedtwice. This section name may contain whitespace. If it does, however, it must beenclosed in either single or double quotes.

Examples:

cw -p "Windows driver"

-S <stateLoc>

The state location flag allows you to specify the directory or file in which stateinformation is to be found. The stateLoc argument names that directory or file. IfstateLoc names only a directory, Codewright looks for a file named CWRIGHT.PST inthat directory, from which state information is read. If stateLoc names a complete path,including filename, Codewright will attempt to read state information from that file.

When this flag does not appear on the command line, Codewright looks for a stateinformation file in a series of places, unless the saving and restoring of state informationhas been turned off. These places include:

• a directory or file named by the CWPST environment variable,

• in CWRIGHT.PST in the Working Directory,

• in CWRIGHT.PST in the directory in which the CW.EXE or CW32.EXE file islocated,

• or in a location named in CWRIGHT.INI.

This default search for state information is described in greater detail in the"Configuration and State" chapter of this manual.

Example:

Command Files

166

cw -s h:\home\ericj

-S-

This is a special form of the state location flag that instructs Codewright not to read astate file. State information, however, is not automatically reinitialized, and may be usedsubsequently.

Example:

cw -s-

-X <function>

The execute function flag names a function to be invoked as part of Codewright startup.This function should not attempt to perform any configuration, since such configurationmay be overridden or reversed by the subsequent processing of the configuration and statefiles.

The function argument to this flag contains the function call. If the call contains anyparameters to the function, the entire function call must be enclosed in single or doublequotes. In addition, it must conform to the syntax required by LibFunctionExec. Formore information about this format, refer to the "Using the Editor -- The Command Key"section of this manual.

Example:

cw -X"special_init 1"

Command Files

@<commandFile>

A command file is a file that may contain any valid command line parameters, includingadditional command files. Codewright identifies filenames preceded by an @ sign ascommand files. Command files are useful for overcoming command line length limitsand also for creating reusable, logical groupings of filenames and flags.

Parameters within a command file may be separated by whitespace or newlines. Newlinesare often used to promote readability.

167

Appendix A -- Color Guide

The methods of setting colors in Codewright Professional use a common scheme, intended tosimplify selection of foreground and background colors. The scheme is similar to the one used byDOS, in that it has 16 predefined color settings available that you can use as either foreground orbackground colors. You can, however, change the RGB color settings for each of the colors in thetable.

This color scheme is also used by the following functions:

ColorAlternate... AttrFindColorColorCommandLine AttrQColorColorError AttrSelColorColorLineNumbers AttrSetColorColorMessage AttrSetPaletteEntryColorSelectionColorTextColorWarning

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 mostsignificant nibble describes the background color and the least significant nibble describes theforeground.

Figure 9: Example Color Byte

Palette Settings

168

Palette Settings

The table below shows the default red, green and blue values used for each of the predefinedcolors. The function AttrSetPaletteEntry allows you to change these mappings:

Color Number Blue Green RedBlack 0 0 0 0Blue 1 128 0 0BlueGreen 2 128 128 0Green 3 0 128 0Red 4 0 0 128Purple 5 128 0 128Brown 6 0 128 128Gray 7 128 128 128DarkGray 8 64 64 64LightBlue 9 255 0 0LtBlueGreen 10 (A) 255 255 0LightGreen 11 (B) 0 255 0LightRed 12 (C) 0 0 255LightGray 13 (D) 192 192 192Yellow 14 (E) 0 255 255White 15 (F) 255 255 255

169

Appendix B -- Technical Support

If a problem arises in using or programming Codewright Professional, there are a numberof things you can do to try and solve the problem. First, check the README.TXT filethat was shipped along with Codewright Professional. It is placed in CodewrightProfessional's home directory during installation. It will warn you about any known"gotchas" that are not covered by the manual. The next place to look for help is in themanual.

Web Page

You can access our home page on the Internet’s World Wide Web using the followingURL: http://www.premia.com. Information and services available there include:

• messaging to sales and tech support

• pricing and product descriptions

• problem report form

• downloading of add-ons and patches

Internet Mail

You can send email to [email protected], and we will assist you as soon as practical.For sales matters, use the address [email protected].

CompuServe

Premia has a section in one of the Windows Vendor Forums on CompuServe. You cantype “Go Premia” at any ! prompt, or look in the WinAPA forum, section 9. You mayalso reach us at 70673,2627.

Fax

170

Fax

A fax will normally get a quick response. Our fax number is (503) 641-6001.

Phone Support

If you urgently need some information in order to continue using CodewrightProfessional, or if you have an urgent bug report, give us a call. The phone number is(503) 641-6000.

Maintenance Policy

Registered users who report bugs that are later fixed are entitled to a patched version orcopy of maintenance release software.

171

Appendix C -- Updating Source with Merge

The C source code files for many of Codewright's DLL's are supplied along with theprogram. This facilitates the process of modifying and extending the capabilities ofCodewright. Changing the source code, however, presents a problem when subsequentversions arrive. There are your changes and our changes, both too valuable to give up.The solution is to merge the changes into a single new file.

This appendix describes the process of updating changed files with AutoMerge. Themerging capability is provided through the Merge function in the Codewright API. For adescription of the Merge function, refer to the Online Programmer's Reference.

Steps to Merging

This section describes a relatively simple method of merging your Codewright V4.0source files with the source files provided in the Codewright Professional V5.0 release.The method described does not try to conserve disk space, and could use as much as18MB for all Codewright files. Most users will not require nearly this amount, andadditional steps may be taken which will substantially reduce this requirement. So thatyou will know where this space is going, here is a table of the maximum expected diskstorage requirements:

Category StorageOld Installation 6MBNew Installation 6MBOriginal Source 3MBMerged Source 3MB

A more typical example would be as follows:

Category StorageOld Installation 6MBNew Installation 6MBOriginal CWSTART Source 850KMerged CWSTART Source 50K

Steps to Merging

172

Identify Merge Candidates

Compare the dates on the source files in Codewright's sub directories to the release date.Most of the source files should be marked with the release date, but if you are in doubt,compare the source file date to the date on the CW.EXE or CW32.EXE file.

If you have PKZIP available, you will probably find it useful to execute a DOS commandlike the one below in each of your Codewright source code subdirectories from your oldinstallation:

pkzip -t040494 modified *.c *.h

Substitute the date on your Codewright executable in place of the 040494 in the commandabove.

When you have done this, you will not only have archived your modified files, you willhave also generated a list of these files that you can view or capture with a command likethe one following:

pkunzip -v modified

Make the Source Files Available

After you have identified which files need to be modified, make a list of the directoriesthat contain these files. For use in subsequent examples, let us say that you have modifiedfiles in CWSTART, CUA, and CWDIALOG.

Using the distribution disks from your old installation, run INSTALL to install only thefiles for the subdirectories on your list into a new directory structure. Let us call thisdirectory CWBASE. Do not install the executables or helpfile. Don’t worry if you havepatched the source files since your original installation. The Merge process will applythese changes along with your own.

If you have not already installed Codewright Professional V5.0, do so now. Install it intoa new directory rather than installing over top of your previous installation. We suggestthe name CW40 for this purpose. If disk space is tight, install only the source code forthe directories on your list (plus the INCLUDE and LIB subdirectories). This will allowyou to perform the Merge, and then install other source code as you need it.

Steps to Merging

173

Install AutoMerge

Find the disk marked “Best of BBS” in your new Codewright Professional V5.0distribution disks, and locate the file AUTOMG.EXE. If you have the CD version ofCodewright, you will find the “Best of BBS” disk in a subdirectory named BBS16 orBBS32, depending on whether you are using the 32 bit version of Codewright or the 16bit version. If you have trouble locating this file, check the file MANIFEST.TXT in theroot of that disk or directory. AUTOMG.EXE is a self-extracting executable thatcontains the AUTOMRG.DLL and its source

In a DOS shell, log to the new executable directory for Codewright Professional V5.0 andRun AUTOMG.EXE from the disk, using a command like the one below:

b:\utils\automg automrg.dll

This will extract just the DLL. If you later want the source, you can create a subdirectoryand extract the entire executable into it by running AUTOMG with no parameters.

Next, run Codewright V5.0 and load the configuration file CWRIGHT.INI in itsexecutable directory. Locate the [LibPreload] section of the file and add a line to load theAUTOMRG.DLL library as follows:

[LibPreload]LibPreload=automrg.dll

Define AutoMerge Directories

The next step is to create a new section in the CWRIGHT.INI configuration file. Anexample of such a section appears below:

[Merge]MergeBaseDir=c:\\cwbase\\cwstartMergeRevDir=c:\\cw40\\cwstart

Note that backslashes in the directory names must be doubled. This is because thedirectory string may contain any of the escape sequences documented for theExtExpandTemplate function. We shouldn’t be needing them here, however.

In our example, we are merging files in the CWSTART, CUA and CWDIALOGsubdirectories. The example above prepares to merge the files in the first of thesedirectories, CWSTART. The commands in the example above specify the directories we

Steps to Merging

174

used in our example, CW40 and CWBASE. If you used other names or your files are onanother drive, substitute those names in the commands above.

The last directory in these paths will need to change as we go on to merge files in anotherdirectory. The rest should stay the same. You need only change the path and save thefile. You need not restart Codewright for these changes to take effect. At this point,however, we do need to restart Codewright to allow the AutoMerge DLL to be loaded.

Execute the AutoMerge Function

After restarting Codewright with the AUTOMRG.DLL loaded, load your modifiedversion of the source files from your previous installation. For example, if you modifiedUTIL.C and ERRORFIX.C in your C:\CWRIGHT\CWSTART subdirectory, load thosefiles now. Wait until you change the AutoMerge commands in your CWRIGHT.INIbefore loading other files you have modified.

Now, for each source file loaded (except CWRIGHT.INI),

• obtain an API Command Prompt

• Execute the AutoMerge function (no parameters)

• Note whether or not conflicts are reported.

• Close the file.

The AutoMerge function creates a .MRG file for each of the files you modified.Continuing our example, AutoMerge would create the files UTIL.MRG andERRORFIX.MRG in the C:\CWRIGHT\CWSTART subdirectory. Note that this is thesubdirectory for your original installation.

Modify your CWRIGHT.INI file so that the commands in your [Merge] section point tothe next directory of files to merge, load the files in that directory and repeat the process.When you have repeated this for all of the subdirectories on your list, the merge iscompleted.

Resolve Conflicts

If conflicts were noted in any of the files you merged, load the .MRG file and search forsix dashes at the beginning of a line (^------ with regular expressions on). This is howconflicts are identified within the file.

Steps to Merging

175

When you have resolved any conflicts in a merged file, you are ready to copy the file tothe original filename in the new installation’s directory. For example, you might resolveconflicts in C:\CWRIGHT\CWSTART\UTIL.MRG and then copy it toC:\CW40\CWSTART\UTIL.C. If a version control system is available, it is advisable toput all four revisions of the file under version control before copying the file to itsoriginal name. Recompile the DLLs and test the features you previously added.

176

Appendix D -- TAGSWNN Utility

TAGSWnn (TAGSW16 or TAGSW32, depending on your platform) is the Tags programsupplied with Codewright to automatically generate a tags database and compile it into aformat that can be used by the built-in browser. The program is called when you selectBuild Tags from the Project menu. You may not ever need to run the program from thecommand line, but in the event that you do, or if you just wish to know more about theprogram, its options are briefly described here.

TAGSWnn is based on the GNU Tags program written by John Kerchival. The primarychanges made to it are to allow output in the Premia Compiled Tags format. This is the -poption, which is the only option we have added. Other options are as described in theTAGS.DOC file supplied with the GNU Tags program and provided with Codewright.

Usage

TAGSWnn {[OPTIONS] [SOURCEFILE|@LISTFILE]}

TAGSWnn Command Line Options

An option summary follows:

-h, -?Obtain a detailed help screen directed to standard output.

@LISTFILEUse LISTFILE as a "response" file. This file is a list of input filenames. This file listsfilenames (with or without wildcards) one at a time and the filenames may be separated by'+', ',', ';' or by whitespace. In addition, comments are allowed within the LISTFILE.Comments are delimited by placing a pound sign '#' before the comment. This is verysimilar to comments allowed in a makefile except that comments are allowed on any lineor at the end of any line, start at the '#' and go to the end of the current line. There mustbe at least one character between the filename and the comment character (i.e. '+', ',', ';' orwhitespace) to differentiate between the beginning of comment and a filename character(since '#' is a valid element of a filename).

-x{EXCLUDEFILE|@LISTFILE}


177

Excludes the files specified by EXCLUDEFILE or excludes all files listed in LISTFILEusing the same syntax described above.

-tTAGFILEAdd new generated tags to TAGFILE. This file may or may not exist. All tags fromTAGFILE which were derived from files currently being parsed will be removed duringthe merge phase. This tagfile is assumed to be in one of this utilities output formats. Ifsorting is specified then new tags will be merged in correct order with current casesensitivity, otherwise tags will be placed at the beginning of the new resulting tag file (thiswill result in quicker responses during tag searches while editing). if -m or -s are usedthis switch is ignored (all output is to stdout). The behavior regarding existing files isdetermined by the case of the switch as follows:

-t (lower case) creates and outputs to a file overwriting any currently existingfile

-T (upper case) merges all output to the tagfile if there is an already existingfile

-pCOMPILEFILEConvert output tag file (specified by -t) into a compiled file suitable for use withCodewright. The output flag (-t) and the Codewright output format flags (-oc) must bespecified for this flag, otherwise it is ignored.

-lLOGFILEOutput all activity to LOGFILE. The log file will be created in a LISTFILE format (i.e.suitable as input using the @LISTFILE syntax). The behavior regarding existing files isdetermined by the case of the switch as follows:

-l (lower case) creates and outputs to a file overwriting any currently existing file

-L (upper case) appends all output to the logfile if there is an already existing file

-o[options]This switch is used to determine the output format to the output stream. [options] may beone of the following:

e Epsilon (>= V6.0) tag format

( tokenString {tab} fileName {tab} characterOffset {tab} line )This format is used by the Epsilon editor (V6.x) created by Lugaru Software andspecifies the token identifier, the file name (including full path, normally), the


178

character offset of the beginning character (starting at character 0) and the linewhich that offset is located on.

5 Epsilon (<= V5.03) tag format

( tokenString;fileName;characterOffset )This format is used by the Epsilon editor (V4.x and V5.x) created by LugaruSoftware and specifies the token identifier, the file name (including full path,normally) and the character offset of the beginning character (starting atcharacter 0).

g GNU tag format

( tokenString {tab} fileName {tab} /$line^/ )This format is used by GNU's EMACS editor, originally written by RichardStallman and widely used in the UNIX community. This is also the formatcreated by its companion utility "ctags" which does very simple function headertagging.

s Space-Delimited format

( tokenString fileName lineNumber )This format is the simplest format available and requires very little parsing and isvery simple to import into foreign formats (i.e. database formats, etc.).

m Microsoft Error format

( tokenString fileName(lineNumber) )This format has an advantage in that it has been around for quite some time and afair amount of effort has been expended to parse this format and move to thelocation in the source specified during compilation stages. Many macros may bemodified to use this type of tag format with very minor changes.

c Codewright tag format

( tokenString FileName(lineNumber) tokenType )This format is a minor variant of the Microsoft format but is generally used inconjunction with a compiled database file format (see -p above). This is theformat used by Premia's Codewright editor.

-a[options]This switch is used to specify the types of tokens for which tags are generated for taggingof assembly files. All token types are tagged as the default ( -afdlmsu ). Source modules


179

are expected in 80x86 assembly using MASM/TASM syntax. The location of the -aswitch on the command line is important. All files (and files found in LISTFILEs) will betagged using assembly tagging (and the options specified on that switch) until another -aor -c switch is found. Order is not important for the options to this switch.

f procedure labels

( token proc )( proc token )This is a mnemonic for function (which has nothing to do with a procedure callin assembly, but does well for frail human memory. This option specifiestagging of the "proc" keyword.

d definition labels

( token equ const )( token db declaration )This option specifies tagging of defines and definition labels such as the tokens"equ", "db", "dq", "dw", "df", etc.

l local labels

( token label )( label token )( token: )This option specifies tagging of local labels (labels of local file duration). Thisincludes the keyword "label" as well as the shorter ':' notation.

m macro labels

( token macro )( macro token )This option specifies tagging of defined macros using the keyword "macro".

s struc labels

( token struc )( struc token )This option specifies tagging of structure definitions defined using the keyword"struc".

u union labels

( token union )( union token )This option specifies tagging of union definitions defined using the keyword"union".

-c[options]


180

This switch is used to detail the token types to tag in C and C++ source files. All tokentypes are tagged by default ( -cdmstekuvcfpxi ). Source files are expected in standardANSI 2.0 C/C++ syntax. The location of the -c switch on the command line is important.All files (and files found in LISTFILEs) will be tagged using C tagging (and the optionsspecified on that switch) until another -a or -c switch is found. Order is not important forthe options to this switch.

d defines

( #define token statement )This option specifies that defines are to be tagged (preprocessor defines). Thisdoes not include macros which are an extended use of the #define preprocessordirective.

m macro labels

( #define token() statement )This option specifies tagging of macros defined via use of the preprocessor#define directive.

s struct globals

( struct token {} )This option specifies tagging of structures defined via use of the "struct"keyword and implicitly defined within C++ syntax variations.

t typedef globals

( typedef declaration token, token, ... )This option specifies tagging of identifiers defined via use if the "typedef"keyword.

e enum globals

( enum token {} )This option specifies tagging of enumerations defined via use of the "enum"keyword.

k enum konstants

( enum { token, token, token, ...} )


181

Note the cute spelling of constants with a 'k' so that I can justify the assignmentof this letter. This option specifies tagging of enumeration constants withindeclared enumerations.

u union globals

( union token {} )This option specifies tagging of unions defined via use of the "union" keyword.

v global variable

( declaration token, token = {}, token, ... )This option specifies tagging of global variable declarations.

c global class

( class token: {} )This option specifies tagging of class definitions specified via use of the "class"keyword.

f function definitions

( token() declaration {} )This option specifies tagging of function declarations.

p prototypes

( token(); )This option specifies tagging of prototypes.

x extern defines

( extern declaration )( extern "C" declaration )( extern "C" { declaration; declaration; ... } )This option will specify that tags which have the extern storage class are to beoutput. The x option is a modifier and will only be effective when other optionsare used (i.e. -cpx must be specified to obtain extern prototypes, -cx alone yieldsnothing). Note also that the -cx modifier has no effect for function, define andmacro tags which are tagged only according only to the f, d and m optionsrespectively. This modifier may be placed anywhere within the options list.


182

i static declarations

( static declaration )This option will specify that tags which have internal static storage class are tobe output. The i option is a modifier and will only be effective when otheroptions are used (i.e. -cvi must be specified to obtain static variabledeclarations, -ci alone yields nothing). Note also that the -ci modifier has noeffect for define and macro tags which are tagged only according only to the dand m options respectively. This modifier may be placed anywhere within theoptions list.

-dThis flag specifies that all input listfiles and exclude response files should be deleted onceparsed. This allows an automated list file generation which is cleaned up by the tagspackage. See description of LISTFILE below.

-jThis is the junk filter switch to allow the filtering of functions and declarations which areoverloaded operators in C++. For example, if the junk filters are enabled then thedeclaration "inline myType operator+(MyType m1, MyType m2);" would not be taggedfor "+" which is normally a standard C delimiter token and operator. The junk filter ifenabled will filter all standard C delimiters from the output.

-qThis is the quiet switch and will suppress normal status output to stderr and programversion information.

-rThis switch will suppress the default output of the full file path name and will specify theuse of relative pathnames in the generated output.

-nThis switch will suppress sorting of the tag output (Often used in conjunction with GNUor Epsilon style tags)

-iThis switch specifies the use of a case sensitive sort (Normally a case insensitive sort isused). I know, the character 'i' is normally used for switching to a case insensitivebehavior, things are tough all over, you'll learn to live with it.

183

Appendix E -- Specifications

Line Length Limit

Lines are limited to 536,870,911 characters.

Lines per Buffer Limit

The maximum number of lines per buffer is 536,870,911.

Buffers Limit

The maximum number of buffers is limited only by storage (memory and disk).

Windows Limit

The number of windows is limited by Microsoft Windows.

File Size

The total of all file being edited is limited by the Operating System or 536,870,911 characters,whichever is less.

Number of Files

The number of files being edited is limited to 65,535, subject to the limit on total file size givenabove.

Clipboard/Scrap Buffer Size

The Clipboard is limited by Windows to 64K. Scrap buffers operate under the buffer limitsdescribed above.

Search String Length

Search strings are limited to 64K.

184

??

Part 2, Function Reference

186

187

Function Reference

This portion of the Codewright Professional User’s Guide lists and defines API functions.These functions may be used in the configuration file, or in key assignments, and mostmay be used interactively, through the API Command Key. The syntax used byconvention in these three contexts differs slightly, but since Codewright Professionalgives you broad latitude in the syntax you use; the three are essentially interchangeable.The syntax used in the function descriptions below is the syntax recommended for theconfiguration file.

Function Description Format

The description of each function is made up of several components: the Name andSyntax, the Remarks, the Return Value, and the See Also reference. Here is a descriptionof those components:

• Function Name and Usage SyntaxThe Syntax line provides a synopsis of the function's name, parameters andparameter types. An equal sign separates the function name from its parameters.If nothing follows the equal sign, the function takes no parameters.

Each parameter and its identifying type are enclosed in angle brackets, < and >.Parameter names enclosed in quotes are static strings or string constants (e.g.,<"example"> )

• RemarksThe Remarks describe the purpose and use of the function.

• Parameters DescribedWithin the Remarks section of the Function Description is a listing anddescription of each parameter taken by the function. This part of the remarkssection appears only if the function takes one or more parameters.

• API Key defaultsAlso in the Remarks section is a list of default values for each parameter whenparameters are omitted. When a parameter is omitted, Codewright Professionalmust supply a default value.

188

• Return ValueThe value returned by the function is described here. This information isprovided for diagnostic purposes only.

You cannot test the return value of a function executed from the configurationfile or from key assignments. You may, however, see return values whenexecuting functions through the API Command Key, if you prefix the functioncall with a question mark. This can assist you in performing diagnostics andmodifying flag values.

• See Also ReferencesThe See Also section lists related functions which may further inform you, orwhich may serve as an alternative to the function just described.

Autosave

189

AssignMouseKeys=

Remarks AssignMouseKeys assigns the standard functions to the mouse keys. It is primarily foruse in keymaps.

See Also KmapAssign

AttrSetPaletteEntry=<int entry>, <DWORD color>

Remarks AttrSetPaletteEntry changes the definition of one of the colors in CodewrightProfessional's color palette. This can affect the appearance of the entire program.

Parameter Descriptionentry The table entry number (0 to 15) for which the color is to be

changed.

color The new Blue, Green and Red encoded value for the entry. Themethod of encoding this value is as follows:

Select a value for each color from 0 to 255. Place each value in aseparate byte of the color DWORD. Red goes in the leastsignificant byte, green the next and blue the next. For example, thehex value 0x00FF7F3F specifies 0xFF for blue, 0x7F for green and0x3F for red.

Default value when parameters not suppliedThe function reports a zero value if either parameter is omitted.

The Codewright Professional color palette and the factory supplied values are describedin Appendix A of this manual.

ReturnValue

AttrSetPaletteEntry returns the value in the color table that has been replaced by thenew value.

Autosave=<int idleTime>, <int forceTime >

Remarks Autosave specifies the time intervals used for automatic file backups, when enabled.

AutosaveDir

190

Parameter DescriptionidleTime The number of seconds of keyboard inactivity that must elapse

before an auto-save is performed. A zero value effectively turnsthe feature off.

forceTime The number of minutes of editing time that must elapse before asave is performed, regardless of keyboard activity.

Using this function to set both time parameters to zero effectively turns this feature off.

See Also AutosaveDir

AutosaveDir=<" dir ">

Remarks AutosaveDir permits you to specify a directory in which you wish to have auto-savefiles created. Auto-save is a feature that periodically saves your edit file, normally to afilename or directory other than the original.

Parameter Descriptiondir A string containing the name of the directory in which auto-save

files are saved.

If a directory for auto-save files is not specified in this manner, the auto-save file iscreated in the same directory in which the original file resides.

See Also Autosave

BackTab=

Remarks BackTab is the function normally assigned to the %7 keystroke. If a selection is

defined, the function outdents the block. If no selection is defined, the function movesthe cursor to the preceding tabstop.

See Also Tab, SlideOut, SlideIn

BlockCopy=

BraceMatch

191

Remarks BlockCopy copies the current selection to either the current scrap buffer or the WindowsClipboard, whichever is the designated data staging area. An informative message isprinted to indicate the type of selection and the destination.

See Also BlockCut, Paste

BlockCut=

Remarks BlockCut cuts (copies and deletes) the current selection to either the current scrap bufferor the Windows Clipboard, whichever is the designated data staging area. Aninformative message is printed to indicate the type of selection and the destination.

See Also BlockCopy, Paste

Brace=<BOOL commentsToo >

Remarks Brace processes the current buffer, looking for unmatched curly braces. The cursor ispositioned on the first unmatched curly brace, if one is found.

Parameter DescriptioncommentsToo If this parameter is TRUE, the function does not exclude braces

that occur within the C language comments of the file ( /* */and // ). If FALSE, only braces outside of comments will beconsidered for matching.

BraceMatch=<BOOL parens_too >

Remarks BraceMatch searches forward, beginning at the current position, for a matched pair ofcurly braces, { }, and optionally parentheses, ( ). The matched set and any text betweenthem are highlighted.

Parameter Descriptionparens_too If TRUE, match the next set of {} or (), otherwise just {}.

BraceMatchNext

192

Default values when parameters are not suppliedparens_tooFALSE

If a '}' or ')' is encountered first, the function searches backward for a previous matching'{' or '(' . Since this function always begins the search with the current position, it is notwell suited for highlighting a series of matched braces. It will continue to find thecurrently highlighted set.

ReturnValue

BraceMatch returns TRUE when a matched set of braces or parentheses are found. Ifnone were found, or an unbalanced set was found the function returns FALSE.

See Also Brace, BraceMatchNext

BraceMatchNext=<BOOL parens_too >

Remarks BraceMatchNext searches forward for a matched pair of curly braces, { }, andoptionally parentheses, ( ). The matched set and any text between them are highlighted.

Parameter Descriptionparens_too If TRUE, match the next set of {} or (), otherwise just {}.

Default value when parameter not suppliedparens_tooFALSE

The search will find matched sets nested within a currently highlighted block, andsubsequent pairs, when called repeatedly.

ReturnValue

BraceMatchNext returns TRUE when a matched set of braces or parentheses are found.If none were found, or an unbalanced set was found the function returns FALSE.

See Also Brace, BraceMatch

BufBackspace=<DWORD count>

Remarks BufBackspace removes one or more characters preceding the current position in thebuffer.

BufDelChar

193

Parameter Descriptioncount The number of characters to remove.

Default value when parameter not suppliedcount 1

Any remaining text shifts to fill the position previously occupied by the removedcharacter.

ReturnValue

This function returns 0 if the operation is successful. It returns -1 upon error, such aswhen there is no current buffer or the buffer is read-only.

See Also BufDelChar

BufDelChar=<DWORD count>

Remarks BufDelChar removes characters from the buffer, beginning at the current position.While the function will delete the end-of-line sequence when the count parameter soindicates, it will not delete beyond the end of the current line, regardless of the value ofcount.

Parameter Descriptioncount The number of characters to delete.


The end-of-line sequence is counted as a single character, whether it is one character ortwo. Specifying a large value for count may be used as a method of deleting through theend of the line.

ReturnValue

BufDelChar returns zero to indicate success, even if fewer than the specified number ofcharacters are available for deletion. It only returns non-zero if the buffer is read only orif there is no current buffer.

See Also BufDelLine

BufDelLine

194

BufDelLine=<DWORD count>

Remarks BufDelLine removes one or more lines from the buffer, beginning with the linecontaining the current position.

Parameter Descriptioncount The number of lines to delete.


The value of count may be greater than the number of lines subsequent to the currentposition in the buffer.

ReturnValue

BufDelLine returns zero to indicate success, even if fewer than the specified number oflines are available for deletion. It only returns non-zero if the buffer is read only or ifthere is no current buffer.

See Also BufDelChar

BufDelSelection=

Remarks BufDelSelection removes the current selection. The contents of the selection is notplaced in the scrap buffer. It may, then, only be recovered by executing Undo.

ReturnValue

On success, BufDelSelection returns 0. If no selection was defined, the function returnsa non-zero value.

See Also BufDelChar

BufDelToEOL=

Remarks BufDelToEOL removes characters from the current position to the end of the line. Itdoes not remove the end of line marker.

BufEditFile

195

ReturnValue

BufDelToEOL returns zero to indicate success, even if the cursor is already at the endof the line, and it therefore deletes nothing. It only returns non-zero if the buffer is readonly or if there is no current buffer.

See Also BufDelLine

BufEditFile =<" file" >

Remarks BufEditFile creates a new buffer for the specified file and assigns it to the currentwindow. If no window is currently defined, one is created. If the system flag is set thatindicates One buffer per window a window is created for each file read into a buffer.The buffer or buffers are added to the buffer list following the one that was previouslycurrent, if any.

If a file opened by BufEditFile is already loaded, it is made current.

Parameter Descriptionfile The filename and optional path of the file to be edited. May

contain DOS standard wildcard characters.

Default value when parameter not suppliedfile ""

If file is an empty string, the function prompts for a filename. If file contains wildcards, abuffer is created for each file that matches the pattern and the first is assigned to thecurrent window. This function honors the "One Buffer Per Window" System Option, ifset.

When BufEditFile is used to prompt for a file to edit, the functions provides additionalassistance in selecting a file to edit. When command-line prompting is enabled (ratherthan prompting via pop-up dialogs), the user may select from a list of files matching aspecified pattern by first entering the pattern and then pressing 7. Alternately, if the

user presses the up or down arrow keys in response to the prompt, the user may select afile specified previously.

BufInsertChar

196

BufInsertChar =<int key>

Remarks BufInsertChar inserts a character at the current buffer position.

Parameter Descriptionkey The character to insert.

Default value when parameter not suppliedkeyAscii portion of the current keycode

This function causes the current position in the buffer to be advanced. If the character isinserted beyond the end of a line, the virtual space is filled with spaces or tabs to theposition at which the character was inserted.

If a keycode is used as a parameter to this function, the ASCII portion of that code isinserted into the buffer.

Newline characters (0x0A) may be inserted with this function. They will, however, beinserted by calling the BufInsertEOL function. Likewise, inserting a tab character withthis function will result in the appropriate tab expansion being inserted in the buffer --that is, a tab if "use tabs" is enabled and otherwise the appropriate number of spaces. Toinsert a raw newline or tab, use the BufInsertStr function.

See Also BufInsertStr, BufInsertEOL

BufInsertEOL =

Remarks BufInsertEOL inserts a newline sequence at the current position. This has the effect ofmoving the cursor to the beginning of the new line.

The specific newline sequence inserted will be either a carriage-return and line-feed, orjust a line-feed, depending on the buffer setting selected. The factory setting is thecarriage-return and line-feed combination.

BufInsertFile=<" path" >

BufInsertScrap

197

Remarks BufInsertFile reads the named file into the buffer at the current position.

Parameter Descriptionpath The string containing the filename and optional path.

Default value when parameter not suppliedpath NIL

At the completion of this function, the cursor is positioned immediately following theinserted text.

ReturnValue

On success, BufInsertFile returns 0. If the file could not be found, or some other erroroccurred, a non-zero value is returned to indicate the nature of the failure.

BufInsertScrap=

5HPDUNV BufInsertScrap inserts the contents of the Scrap buffer into the edit buffer at the currentposition. The resulting cursor position depends on the type of selection used to place thetext into the scrap buffer.

Selection type Cursor positioninclusive/exclusive At the end of the inserted text.

line Text is inserted at the beginning of the current line. The cursorfollows the text in which it was originally located.

column On the line following the last of the inserted text, at the originalcolumn position.

There are other functions which performs similar operations on the Windows Clipboard.These functions begin with the Clipboard... prefix.

5HWXUQ 9DOXH This function returns 0 unless the Scrap buffer is empty. In that case, it returns a non-zero value.

6HH $OVR BufCopyToScrap, BufCutToScrap, BufAppendToScrap

BufInsertStr

198

BufInsertStr =<" string" >

Remarks BufInsertStr inserts the supplied string into the buffer at the current buffer position.

Parameter Descriptionstring The string to insert.

Default value when parameter not suppliedstring NIL

This function causes the current position in the buffer to be advanced. If the string isinserted beyond the end of a line, the virtual space is filled with spaces or tabs to theposition at which the character was inserted.

The string may contain newline sequences and tab characters, but newlines will notreceive any of the special treatment afforded by BufInsertEOL and a raw tab will beinserted regardless of the state of the "use tabs" option.

See Also BufInsertChar, BufInsertEOL

BufSetAutoIndentMode=<WORD mode>

5HPDUNV BufSetAutoIndentMode sets the fill mode to be used by the auto indent feature. Thisfunction does not turn auto-indent on or off.

Parameter Descriptionmode A value from 0 to 4 indicating the method of filling white space at

the beginning of lines, when auto-indent is in effect. Labels for thevalues and their meaning appear below:

Value Label DescriptionAUTO_INDENT_DUPLICATE Immediately fills the indent by duplicating exactly the

whitespace present on the preceding line.AUTO_INDENT_SEEK Used with AUTO_INDENT_VIRTUAL, searches backward,

skipping empty lines, until it finds a line with text on it.The white space on the new line is modeled after that line.

BufSetBackupSpec

199

AUTO_INDENT_SPACE Immediately fills the indent with spaces, even if the linereceives no further edits.

AUTO_INDENT_TAB Immediately fills the indent optimally (tabs, then spaces asneeded), even if the line receives no further edits.

AUTO_INDENT_TABMODE Immediately fills the indent with spaces, or spaces andtabs, depending on whether tab usage is enabled.

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

Default value when parameter not suppliedmode

0

5HWXUQ 9DOXH BufSetAutoIndentMode returns the old fill mode for auto-indent. If the value for theparameter is out of range, the function returns -1.

6HH $OVR BufSetAutoIndent, BufQAutoIndentMode

BufSetBackupSpec=<"format">

5HPDUNV BufSetBackupSpec defines where backup files are placed.

Parameter Descriptionformat The format string describing the location where backup files are

placed.

Default value when parameter not suppliedformatBufQBackupSpec()

The format string may contain certain control characters that refer to portions of thefilename of the file to be backed up. This allows you to describe in a generalized way amethod for deriving the name of the backup file from the name of the output file.

When used in the format string, each of these control characters must be preceded by apercent ( % ) sign. Below is a list of these format control characters and their meaning:

BufSetGlobalBackupSpec

200

Format Control Represents Description%b basename The entire name of the output file (fully qualified).

%d directory Includes the path and drive (volume) specifier, but onlyends with a backslash if describing the root directory.

%[ {...} ] e extension Includes the dot, unless the name of the output file hasno extension. May optionally contain a transformationpattern.

%f filename The root name and extension.

%p path Does not contain the drive (volume) or filename.Always ends with a backslash.

%[ {...} ] r root Does not contain extension, drive (volume) or path.May optionally contain a transformation pattern.

%v volume The drive letter and the colon.

%% percent A single percent sign is represented by two consecutivepercent signs (%%).

Example:

BufSetBackupSpec("%b%{??~|__}e")

The initial default for this local backup specification is an empty string. This means thatthe global backup specification is relied upon for locating and naming backup files. If theglobal string is also empty, backups are effectively turned off.

Formatting strings, transformation patterns and the subject of backup files are discussed,and examples provided in the "General Operations -- Backup Files and Directories"section of this manual.

5HWXUQ 9DOXH BufSetBackupSpec returns 0 on success, and non-zero on failure. The most likelycause of this function failing is when there is no current buffer.

6HH $OVR BufSetGlobalBackupSpec, BufQBackupSpec, BufQGlobalBackupSpec

BufSetGlobalBackupSpec=<"format">

5HPDUNV BufSetGlobalBackupSpec defines where backup files are placed.

BufSetTabStr

201

Parameter Descriptionformat The format string describing the location where backup files are

placed.

Default value when parameter not suppliedformatBufQGlobalBackupSpec

The format string may contain literal text and certain control characters that refer toportions of the filename of the file to be backed up. This allows you to describe in ageneralized way a method for deriving the name of the backup file from the name of theoutput file.

The initial value for this string is "%b.bak" , which causes backups to be made in thesame directory as the file being backed up. The backup file is given the extension .BAK .

Setting this backup specification an empty string has the effect of turning backups off,unless a backup specification has been defined for a specific buffer. The initial defaultdoes not assign backup specification strings to individual buffers.

Example:

BufSetGlobalBackupSpec("%b.bak")

Formatting strings, transformation patterns and the subject of backup files are discussed,and examples provided in the "General Operations -- Backup Files and Directories"section of this manual.

5HWXUQ 9DOXH BufSetGlobalBackupSpec returns 0 on success, and non-zero on failure.

6HH $OVR BufSetBackupSpec, BufQBackupSpec, BufQGlobalBackupSpec

BufSetTabStr=<"tabPicture">

5HPDUNV BufSetTabStr defines the tab settings for the current buffer.

Parameter DescriptiontabPicture Contains a list of column numbers at which tab stops are to occur.

If tab stops are at regular intervals, only the first two need to be

BufSetTabUsage

202

named. The distance separating the last two entries is repeated tothe limit indicated by BufQMaxTabCol .

Default value when parameter not suppliedtabPicture "5 9"

The initial default tab string is "5 9" . This sets tabs at four column intervals.

The tab string for the current buffer may be obtained with the BufQTabStr function. Themaximum tab column may be set with the BufSetMaxTabCol function.

6HH $OVR BufQMaxTabCol, BufQTabStr, BufSetMaxTabCol

BufSetTabUsage=<BOOL use_tabs>

5HPDUNV BufSetTabUsage sets whether a tab character or spaces are inserted into the buffer whenthe tab key is pressed. It also determines how virtual space is filled when characters areinserted beyond the end of a line.

Parameter Descriptionuse_tabs Tells whether to set use of tabs on (TRUE) or off (FALSE).

Default value when parameter not supplieduse_tabs 1

When use of tabs is on, the 7 key simply inserts a tab character. Inserting text in the

virtual space beyond the end of a line will cause an appropriate combination of spacesand tabs to fill the virtual space to the left of the column where text is inserted.

When use of tabs is off, pressing the 7 key causes spaces to be inserted up to the

position of the next tab stop. In this case, only spaces are used to fill the virtual spacebeyond the end of a line.

Some users may require that virtual space be filled in a manner different from the way theTab key operates. Those users will find it relatively simple to devise a function toperform the task of filling virtual space to the current position.

BufWriteFile

203

The initial default for this feature enables the use of tab characters.

6HH $OVR BufQTabUsage

BufWrite =

Remarks BufWrite writes the contents of the current buffer to its assigned output filename. Thischanges the value of the buffer's SysFlags.

ReturnValue

This function returns 0 upon successful completion. If an error occurs, a non-zero valueis returned, indicating the nature of the failure.

BufWriteFile =<" filename">

Remarks BufWriteFile writes the contents of the current buffer to the file named by theparameter.

Parameter Descriptionfilename The name of the file, and optionally its path, to which the current

buffer is written.

Default value when parameter not suppliedfilename NIL

This function sets the buffer's saved attribute. The modified attribute of the buffer,however, is not altered, as it would be with the BufWrite function. BufWrite writes thebuffer to its assigned output file and resets the modified attribute. For this reason, youwould not normally write to the buffer's output file using this function. This function isused by the auto-save feature.

ReturnValue

BufWriteFile returns 0 upon successful completion, and a non-zero value when an erroroccurs. The most likely causes of an error are either an invalid path, or insufficientstorage available.

See Also BufWrite, BufWriteSelection

BufWriteSelection

204

BufWriteSelection=<" path" >

Remarks BufWriteSelection writes the contents of the currently defined selection to the specifiedfilename.

Parameter Descriptionpath The string containing the output filename and optional path.

Default value when parameter not suppliedpathNIL

Unlike other selection operations, BufWriteSelection does not remove the selection.

ReturnValue

On successful completion, BufWriteSelection returns zero. If an invalid path isspecified or no selection is marked, the function returns a non-zero value.

See Also BufWrite

CenterLine=

Remarks CenterLine scrolls the current window up or down so that the line that the cursor is on isin the center of the window. It is useful for showing the context surrounding text thatmatched a search, for example.

See Also ToBottom, ToTop

CheckIn=<" cmd">, <" project">, <" archive">, <" file">

Remarks CheckIn executes a command to check a file into a version control system or otherarchive.

Parameter Descriptioncmd A string containing the command line that performs the check-in.

If this parameter is a NULL, the command "PUT %b%e" will beused. The command may contain any of the following escape

CheckIn

205

sequences, which are decoded using the other parameters of thisfunction:

Escape Meaning%% % (a single percent sign)

%B The basename (the complete filename, except for the extension) of the version control

archive.

%b The basename (the complete filename, except for the extension) of the workfile.

%D The directory of the version control archive. (only ends in backslash if root directory)

%d The directory of the workfile. (only ends in backslash if root directory)

%E The extension of the version control archive. (includes the dot, unless extension is null)

%e The extension of the workfile. (includes the dot, unless extension is null)

%n The project name, as named by the project parameter.

%p The path element of the filename (ends with a backslash)

%R The root of the version control archive. (filename less path and ext.)

%r The root of the workfile. (filename less path and extension.)

%V The volume of the version control archive. (drive letter and colon)

%v The volume of the workfile to check-in. (drive letter and colon)

project A string naming the project of which the file to be checked-in ispart. The %n project name escape sequence is based on thecontent of this string.

archive This parameter is not currently used. It may therefore be NULL. Itis not required by Codewright Professional as currentlyimplemented, but is available in the event that it is useful to, orrequired by a version control system.

file A string containing the filename of the file to check-in. All theescape sequences above are based on the filename in this string,except %n.

Default value when parameter not suppliedcmd project archive fileNIL NIL NIL NIL

ReturnValue

CheckIn returns the error level resulting from the execution of the command, or -1 if anerror prevents execution.

See Also ExecComand, CheckOut

CheckInBuffer

206

CheckInBuffer=<" filename" >

Remarks CheckInBuffer executes the CheckIn function on the specified buffer. The buffer issaved to disk before the check-in command is executed.

Parameter Descriptionfilename A string containing the filename of the buffer to be checked in. If

this string is empty or a NULL the function uses the effectiveoutput filename for the current buffer.

Default value when parameter not suppliedfilename

NIL

After the operation is completed, Codewright Professional checks to see if the file is stillthere and, if so, checks the read/write status of the file. If the file is gone, the buffer isautomatically closed. If the file is Read-Only, the status of the buffer is changed tomatch.

ReturnValue

CheckInBuffer returns the value returned by the check-in command executed.

See Also CheckIn, CheckOutBuffer

CheckInSetCmd=<" command">

Remarks CheckInSetCmd sets the command line to be used for checking in a file under a versioncontrol or other archiving system. This function operates in support of the Check-indialog box, and may appear in your Codewright Professional configuration file.

Parameter Descriptioncommand A string containing the command line to execute when checking in

a file is requested. The file to be checked in is selected in thedialog box, but that name is not automatically added to thecommand line. A series of macros are available for referencing

CheckOut

207

portions of the selected filename within the command line. Thosemacros are listed below:

Macro Element of Selected Filename(s)%b The basename (drive, path and root -- no extension)%d The directory (path with no trailing backslash, no drive)%e The extension (begins with the dot)%n The project name%p The path (ends with a trailing backslash)%r The root (filename less drive, path and extension)%v The volume (drive letter and colon)%% Percent sign

Default value when parameter is not suppliedcommand

NIL

See Also CheckOutSetCmd

CheckOut=<" cmd">, <" project">, <" archive">, <" file">, <BOOL lock>

Remarks CheckOut executes a command to check-out a file from a version control system orother archive.

Parameter Descriptioncmd A string containing the command line that performs the check-out.

If this parameter is a NULL, the command "GET %b%e" or "GET-l %b%e" will be used, depending on the condition of the lockparameter. The command may contain any of the following escapesequences, which are decoded using the other parameters of thisfunction:

Escape Meaning%% % (a single percent sign)

%B The basename (the complete filename, except for the extension) of the version control

archive.

%b The basename (the complete filename, except for the extension) of the workfile.

CheckOutBuffer

208

%D The directory of the version control archive. (only ends in backslash if root directory)

%d The directory of the workfile. (only ends in backslash if root directory)

%E The extension of the version control archive. (includes the dot, unless extension is null)

%e The extension of the workfile. (includes the dot, unless extension is null)

%n The project name, as named by the project parameter.

%p The path element of the filename (ends with a backslash)

%R The root of the version control archive. (filename less path and ext.)

%r The root of the workfile. (filename less path and extension.)

%V The volume of the version control archive. (drive letter and colon)

%v The volume of the workfile to check-in. (drive letter and colon)

project A string naming the project of which the file to be checked-out ispart. The %n project name escape sequence is based on thecontent of this string.

archive This parameter is not currently used. It may therefore be NULL. Itis not required by Codewright Professional as currentlyimplemented, but is available in the event that it is useful to, orrequired by a version control system.

file A string containing the filename of the file to check-in. All theescape sequences above are based on the filename in this string,except %n.

lock This parameter is only used when the cmd parameter is null. Itselects between the default command lines for checking out a filewithout or with a lock. If TRUE, the default command is "GET -l%b%e". If FALSE, the command used is "GET %b%e".

Default value when parameter not suppliedcmd project archive file lockNIL NIL NIL NIL FALSE

ReturnValue

CheckOut returns the error level resulting from the execution of the command, or -1 ifan error prevents execution.

See Also ExecCommand, CheckIn

CheckOutBuffer=<BOOL withLock>, <" filename">

CheckOutSetCmd

209

Remarks CheckOutBuffer executes the CheckOut function to replace the specified buffer andassociated file with one that has been previously archived. The checked-out version ofthe file is loaded into the buffer. The "check-out w/Lock" command is used to signal anintention to modify the file.

Parameter DescriptionwithLock When this parameter is TRUE, the "check-out w/Lock" command

is used to signal an intention to modify the file. When FALSE, the"check-out for browse" command is used.

filename A string containing the filename of the buffer to be checked out. Ifthis string is empty or a NULL the function uses the effectiveoutput filename for the current buffer.

Default value when parameter not suppliedfilename withLock

NIL FALSE

Use this function with caution. Any unsaved edits will be lost, and the existingfile will be overwritten without further prompting.

ReturnValue

CheckOutBuffer returns the value returned by the check-out command executed.

See Also CheckOut, CheckInBuffer

CheckOutSetCmd=<BOOL lockIt>, <"command">

Remarks CheckOutSetCmd sets the command line to be used for checking in a file or file under aversion control or other archiving system. This function operates in support of theCheck-out dialog box.

Parameter DescriptionlockIt When TRUE, this function specifies the command line for

checking out a file with a lock, indicating the intention to modify

ClipboardEnableSepStr

210

the file. The locking capability is not supported by all versioncontrol and archiving systems.

When FALSE, this function specifies the command line forchecking out a file without locking it. This is usually referred to asgetting a "browse" copy, and is often write-protected.

command A string containing the command line to execute when checkingout a file is requested. The file to be checked out is selected in thedialog box, but that name is not automatically added to thecommand line. A series of macros are available for referencingportions of the selected filename within the command line. Thosemacros are listed below:

Macro Element of Selected Filename(s)%b The basename (drive, path and root -- no extension)%d The directory (path with no trailing backslash)%e The extension (begins with the dot)%n The project name%p The path (ends with a trailing backslash, no drive)%r The root (filename less drive, path and extension)%v The volume (drive letter and colon)%% Percent sign

Default value when parameter is not suppliedlockIt command

FALSE NIL

See Also CheckInSetCmd

ClipboardEnableSepStr=<int state>

5HPDUNV ClipboardEnableSepStr enables or disables the use of a clipboard separator string.The clipboard separator string is used to separate lines or line segments when they arecopied from a Codewright Professional buffer to the Windows Clipboard.

Parameter Descriptionstate When non-zero, the separator string is enabled. When zero, the

separator is disabled.

ColorCommandLine

211

Default value when parameter not suppliedstate

TRUE

The function ClipboardSetSepStr defines the string. This function enables or disablesits use. The initial setting for this feature is enabled.

5HWXUQ 9DOXH ClipboardEnableSepStr returns the previous state, enabled (non-zero) or disabled(zero).

6HH $OVR ClipboardEnableTermStr, ClipboardSetSepStr, ClipboardQSepStr

ClipboardSetSepStr=<"sepStr">

5HPDUNV ClipboardSetSepStr assigns a new value to the clipboard separator string. Theclipboard separator string is used to separate lines or line segments when they are copiedfrom a Codewright Professional buffer to the Windows Clipboard.

Parameter DescriptionsepStr A pointer to the string containing the new value for the clipboard

separator string.

Default value when parameter not suppliedsepStrNIL

The initial value for this string is "\n", a newline sequence. This string is only used whenenabled.

6HH $OVR ClipboardSetTermStr, ClipboardQSepStr, ClipboardEnableSepStr

ColorCommandLine=<int ColorCode>

Remarks ColorCommandLine sets the foreground and background color that is applied to theCodewright Professional API command line .

Color...

212

Parameter DescriptionColorCode The code indicating the foreground and background color desired.

A value of -1 for this parameter causes the function to report thecurrent setting without modifying it.

Default value when parameter not suppliedColorCode -1

A table listing the 16 color combinations available appears in Appendix A of this manual.

ReturnValue

ColorCommandLine returns the code of the color in effect when the function wascalled.

See Also ColorError, ColorWarning, ColorMessage

Color...ColorComments=<int color>ColorDiffAdd =<int color>ColorDiffDel =<int color>ColorInsertedLines=<int color>ColorKeywords=<int color>ColorModifiedLines=<int color>ColorLinenumbers=<int color>ColorSelection=<int color>ColorText=<int color>

Remarks The Color... functions set or retrieve the color setting for various objects for the currentwindow. The table below describes which of these functions sets which objects:

Function ObjectColorComments The color used, when Language Dependent ChromaCoding is on,

to color comments in the source code.ColorDiffAdd The color applied to lines that are flagged as added in the output

of a File Difference operation.ColorDiffDel The color applied to lines that are flagged as deleted in the output

of a File Difference operation.

ColorError

213

ColorInsertedLines The color used, when Changed Lines ChromaCoding is on, tocolor lines that have been inserted during the current edit session.

ColorKeywords The color used, when Language Dependent ChromaCoding is on,to color keywords in the source code.

ColorLinenumbers The color used for the line numbers that appear to the left of eachline, when enabled.

ColorModifiedLines The color used, when Changed Lines ChromaCoding is on, tocolor lines changed during the current edit session.

ColorSelection The color used for the selection (marked block).ColorText The color used for normal, unselected text.

Parameter Description

color The id of the foreground/background combination to be used.Color ids are listed in Appendix A of this manual.

Default value when parameter not suppliedcolor

-1

ReturnValue

The Color... series of functions return the id of the color previously in use for the objectin question.

See Also ColorCommandLine, ColorError, ColorMessage, ColorWarning

ColorError =<int ColorCode>

Remarks ColorError sets the foreground and background color applied to error messages.




ColorMessage

214


ReturnValue

ColorError returns the code of the color in effect when the function was called.

See Also ColorWarning, ColorMessage, ColorCommandLine

ColorMessage=<int ColorCode>

Remarks ColorMessage sets the foreground and background color applied to messages.





ReturnValue

ColorMessage returns the code of the color in effect when the function was called.

See Also ColorError, ColorText, ColorWarning

ColorWarning=< int ColorCode>

Remarks ColorWarning sets the foreground and background color applied to Warning messages.



ConfigFileRead

215

Default value when parameter is not suppliedColorCode -1 (reports the current setting)


ReturnValue

ColorWarning returns the code of the color in effect when the function was called.

See Also ColorError, ColorText, ColorMessage

ColorWarning =<int ColorCode>

5HPDUNV ColorWarning sets the foreground and background color applied to Warning messages.These are the messages displayed using the MsgWarning function.



Default value when parameter not suppliedColorCode -1 (reports the current setting)

A table listing the 16 color combinations available appears in Appendix A of this manual.These color combinations may be modified using the ColorSetPallete function.

5HWXUQ 9DOXH ColorWarning returns the code of the color in effect when the function was called.

6HH $OVR ColorError, ColorText, ColorMessage

ConfigFileRead=<"fname">, <"sectionName">, <BOOL leaveOpen>

5HPDUNV ConfigFileRead reads a section from a configuration file.

CWHelp

216

Parameter Descriptionfname A pointer to the string containing the name and path of the

configuration file. If the string is empty, Codewright Professionaluses the configuration file read at startup.

sectionName The name of the paragraph or section that is processed. This nameis specified without the enclosing square brackets that are requiredin the file.

leaveOpen When TRUE, this parameter indicates that the configuration file isto be left open for impending updates. This speeds the process ofupdating the file. The file must not be left open indefinitely,however. If it is, another source may attempt to update the file,which could result in a sharing violation.

Default value when parameter not suppliedfname sectionName leaveOpen

NIL NIL FALSE

CWHelp=<long key>, <int mode>

Remarks CWHelp calls the appropriate help library, based on the parameters and filenamesdefined.

Parameter Descriptionkey This long integer can be either a string containing the name of the

topic, or a 32 bit context identifier, depending on the modespecified. The latter is for looking up a topic by number.

mode A value, as defined in WINDOWS.H, indicating the look-upmethod to use. A list of accepted values and their labels appearsbelow:

Label Description

HELP_KEY Perform a lookup on the string pointed to bythe key parameter.

HELP_CONTEXT Perform a numeric lookup on the context-identifier in the key parameter.

HELP_HELPONHELP Ignore the key parameter and display help onusing Help.

DeleteNextWord

217

HELP_INDEX Ignore the key parameter and display anindex of the Codewright Professional helplibrary.

Default value when parameter not suppliedkey modeNIL HELP_KEY

If a default help library has been named with the CWHelpDefaultName function, specialaction is taken whenever a topic cannot be located in Codewright Professional's internaltables. In that case, WinHelp is called upon to find the topic in that default library.

ReturnValue

CWHelp returns TRUE if the help executable is called. FALSE is returned otherwise.

DefaultKeymap=<" keymapName" >

Remarks DefaultKeymap initializes a keymap DLL and makes it current.

Parameter DescriptionkeymapName A string containing the name of the keymap function, which is also

the basename of the DLL containing that function. For example"cwvbrief", "cwvcua" or "mykeys". The keymap function mustinstall and initialize the keymap.

Default value when parameter not suppliedkeymapName

NIL

Return Value DefaultKeymap returns TRUE if the keymap DLL was found and loaded, and thekeymap function was found and invoked.

See Also QDefaultKeymap

DeleteNextWord=

DeletePrevWord

218

Remarks DeleteNextWord deletes from the cursor position to the beginning of the next word.The NextWord function is used to determine the beginning of the next word. Assupplied, NextWord defines the beginning of a word as the first non-whitespacecharacter immediately following the next space, tab or newline. If you modifyNextWord this function will operate differently.

See Also NextWord, DeletePrevWord

DeletePrevWord=

Remarks DeletePrevWord deletes from the cursor position to the beginning of the previous word.The PrevWord function is used to determine the beginning of the next word. Assupplied, PrevWord defines the beginning of a word as the first non-whitespacecharacter immediately following the preceding space, tab or newline. If you modifyPrevWord this function will operate differently.

See Also DeleteNextWord

DisplayFileName=

Remarks DisplayFileName displays the name associated with the current buffer. This will be thebuffer name, if one is defined. Usually, no buffer name has been defined, in which casethis function prints the original filename from which the buffer was read.

Dlg...

Dlg...

219

DlgBufferSave=0, <"caption">DlgBufSettings=DlgDiff =DlgExtensionConfig=DlgFFind=DlgFGrep=DlgFileBuild=DlgFilter =DlgKeys=DlgMarkGoto =DlgMarkGotoLine =DlgMarkSet=DlgMerge=DlgMultiBufSearch=DlgMultiFileSearch=DlgOpenFile=DlgPrint =DlgPrintSetup=DlgSaveAs=0, <"initFilename">DlgSelectDir=DlgSetSelectBuffer=DlgSysColor=DlgWinColor =DlgWinFont=DlgWinSettings=

Remarks The Dlg... series of functions are functions that let you call dialog boxes directly. Manyof them are available for assignment to a keystroke sequence. Those that return bufferhandles or string pointers are intended for use in extension functions written by the user.A description of the purpose of each of these dialogs appears below:

Function Dialog Invoked...DlgBufferSave The Buffer Save dialog and saves the selected buffers.

DlgBufSettings The Buffer Settings dialog to allow changing one or more buffer's settings.

DlgDiff The Differencing dialog.

DlgExtensionConfig The Extension-specific Settings dialog.

DlgFFind The File Find dialog.

DlgFGrep The File Grep dialog.

DlgFilter The Filter dialog (Not on any menu).

DlgKeys The Key Bindings dialog.

DlgMenuPopup=<LPSTR menuName>

220

DlgMarkGoto The Goto Mark dialog.

DlgMarkGotoLine The Goto Line dialog.

DlgMarkSet The Mark dialog.

DlgMerge The Merge dialog.

DlgMultiBufSearch The Multi-buffer dialog.

DlgMultiFileSearch The Multi-file dialog.

DlgOpenFile The File/Open dialog.

DlgPrint The Print dialog.

DlgPrintSetup The Printer Setup dialog.

DlgSaveAs The File/Save As dialog.

DlgSelectDir The File/Change Dir dialog.

DlgSetSelectBuffer The Buffer Selection dialog, allows the user to select a new current buffer,

and then assigns that buffer as current.

DlgWinColor The Colors dialog from the Options menu.

DlgWinFont The Font dialog from the Options menu.

DlgWinFontDefault The Default Font dialog from the Options menu.

DlgWinSettings The Settings dialog from the Options menu.


caption The functions that accept a caption parameter string use it as a titlefor the dialog. These functions call multi-purpose dialogs and thesupplied caption indicates the purpose in this instance.

initFilename The function DlgSaveAs takes this parameter as a string to initiallydisplay in the Filename edit box. In many cases this is the name ofthe current buffer. If this pointer is NIL the edit box will initiallybe empty.

DlgMenuPopup=<LPSTR menuName>

Remarks DlgMenuPopup reads a popup menu definition from a file and displays the menu itdescribes.


menuName The name of a popup menu definition section in the fileCWRIGHT.MNU, or the name of a file containing a popup menu’s

EditPrevBuffer

221

definition. If the parameter is a section name, the parameter beginsand ends with square brackets.

Here is an example key assignment using the DlgMenuPopup function in yourCWRIGHT.INI file:

[KmapAssign]KmapAssign=‘<Mouse_right_click>‘ ‘DlgMenuPopup [Utilities]’

DlgMenuExec=<LPSTR sectionName>

Remarks DlgMenuPopup reads a section in the CWRIGHT.MNU file and executes the lines itcontains sequentially.


sectionName This parameter contains the name of a section in the fileCWRIGHT.MNU that is a series of Codewright API calls. Thisparameter should begin and end with square brackets.

This function is intended primarily for use in the function call portion of an itemdefinition line, but it may be assigned directly to a key, if desired.

EditNextBuffer =

Remarks EditNextBuffer makes the next buffer in the buffer list current. The function skips anysystem buffers in the list. The name of the buffer made current is printed on the statusline or in a pop-up window.

See Also EditPrevBuffer

EditPrevBuffer =

Remarks EditPrevBuffer makes the previous buffer in the buffer list current. The function skipsany system buffers in the list. The name of the buffer made current is printed on thestatus line or in a pop-up window.

EdVersion

222

See Also EditNextBuffer

EdVersion=

Remarks EdVersion displays Codewright Professional's version number on the status line or apop-up message box.

ErrKmapAssign=<"keyName">, <"funcCall">

5HPDUNV ErrKmapAssign makes key assignments to the Window keymap used for the OutputWindow. There are few assignments in this keymap by default. This prevents accidentalediting.

Parameter DescriptionkeyName A string describing the key combination to which the function call

is assigned (e.g., "<alt-a>" ).

funcCall A string describing the function call to assign to the keycombination (e.g., "MovUp 1" ). If this parameter is NIL theassignment is not made.

Default value when parameter not suppliedkeyid function_call NIL NIL

The method of representing key combinations in strings is detailed in "Key Bindings --Keymaps and Keystrings" section of this manual.

5HWXUQ 9DOXH ErrKmapAssign returns TRUE upon successful completion, and FALSE if theassignment cannot be made. Failure is usually due to an invalid keystring, since thefunction assigned to it is not checked for validity at this time.

6HH $OVR KmapAssign

EvalStrDel

223

EvalStrAdd=<" label">, < long value>

Remarks EvalStrAdd adds a string identifier to the list of those recognized by the expressionevaluator. The string can then be used in place of a number, in expressions to beevaluated. This function may also be used to change the value associated with stringsthat are already defined.

Parameter Descriptionlabel The string which to associate with a numeric value. Case is

significant in defining this string.

value The numeric value to associate with the string.

Default value when parameter not suppliedlabel valueNIL 0

ReturnValue

EvalStrAdd returns TRUE if the string definition was added to the list. If the string wasalready defined, and the change parameter is FALSE, the function returns FALSE.

See Also EvalStrDel

EvalStrDel=<" label" >

Remarks EvalStrDel deletes a string identifier from the list of those recognized by the expressionevaluator.

Parameter Descriptionlabel The string identifier that to delete. Case is significant in specifying

this string.

Default value when parameter not suppliedlabelNIL

ReturnValue

EvalStrDel returns TRUE if the label was found and deleted. If the label was notdefined, the function returns FALSE.

ExecApp

224

See Also EvalStrAdd

ExecApp=<" command" >

Remarks ExecApp executes a specified command line. If the command is not supplied in theparameter, the function prompts for it. The command line may invoke either a Windowsor DOS application. If executing a DOS application, the subprocess terminates at theconclusion of the command.

Parameter Descriptioncommand A string containing the command line to execute, including any

arguments and flags. When this string is empty or NIL, thefunction prompts for a command line.

Default value when parameter not suppliedcommand

NIL

ReturnValue

ExecApp returns the exit code returned by the executed application, if any.

See Also ExecCommand

ExecCommand=<" command " >

Remarks ExecCommand spawns a command shell from which a command or a series ofcommands may be executed. The shell used is the one pointed to by the COMSPECenvironment variable.

Parameter Descriptioncommand A string containing the command line to execute, including any

arguments. If this string is omitted or empty, the command shellitself is run. The user must then type "Exit" to close the shell.

ExecUserCmnd

225

Default value when parameter not suppliedcommand

NIL

Return Value ExecCommand returns the error level returned by the executed command, or-1 if an error prevents execution. If just the command shell is invoked, the function willreturn 0.

ExecUserCmnd=<" command">, <WORD wflag>

Remarks ExecUserCmnd executes a specified command line, after expanding any % macros.

Parameter Descriptioncommand A command line which may contain macros referencing the name

of the current buffer or some portion thereof. The followingmacros are defined for use in this parameter:

Macro Element of Current Buffer Name%b The basename (drive, path and root -- no extension)%d The directory (path with no trailing backslash)%e The extension (begins with the dot, if not null)%p The path (ends with a trailing backslash)%r The root (filename less drive, path and extension)%v The volume (drive letter and colon)%% Percent sign

wflag When this parameter is 0 the task is executed in the foreground.When this parameter is 1 the task is executed in the background.

Default value when parameter not suppliedcommand wflag

NIL 0

This function may be used to execute either a Windows or DOS command line.

ReturnValue

ExecUserCmnd returns the exit code of the command executed.

ExecuteMacro

226

See Also ExecCommand

ExecuteMacro=<" funcStr" >

Remarks ExecuteMacro invokes an API or user-defined function provided in a string parameter.If the string is NIL, the command is prompted for.

Parameter DescriptionfuncStr The string containing the name of the function to be executed and

the parameters to provide to that function. If this string is NULL,the function prompts for this information. The case used for thefunction name is not significant.

Default value when parameter not suppliedfuncStr NIL

To see the value returned from a function, place a question mark at the beginning of thefunction call. To display the result of an expression evaluation, prefix the function callwith two question marks.

ExtAddKeyword =<" ext">, <" keyword ">

Remarks ExtAddKeyword adds a keyword to the table of keywords for Language DependentChromaCoding, associated with a specified filename extension.

Parameter Descriptionext A string containing the extension with which the keyword is to be

associated. This extension must be one for which there is built-insupport, or one you have added support for. Support is currentlybuilt-in for the following extensions: .C, .CPP, .CXX, .PAS,.ASM, and if the appropriate DLLs are loaded .SC and .PRG.

keyword A string containing the keyword to be colored by LanguageDependent ChromaCoding, when enabled for the specifiedextension.

ExtAlias

227

Default value when parameter not suppliedext keyword

NIL NIL

ReturnValue

ExtAddKeyword does not return a value

See Also ExtReadKeywordFile

ExtAlias=<" new">, <" existing ">

Remarks ExtAlias confers a set of extension-specific attributes on an additional extension. Fileswith the specified extension (File Type) are processed in the same manner as apredefined type.

Parameter Descriptionnew A string containing the filename extension which is to be treated

synonymously with another extension.

existing A string containing the filename extension that is currentlyprocessed in the desired manner.

Default value when parameter not suppliednew existingNIL NIL

There are several features that are language-specific, and are predefined as applying tofiles with a certain extension. These features are ChromaCoding, Template Expansion,and Smart Indenting. For the purposes of these features, files with certain extensions areassumed to contain source code for a specific programming language. These assumptionsare listed in the table below:

Extensions Programming Language.ASM Assembly.C; .H C.CPP; .CXX C++.PAL Paradox.PAS Pascal

ExtAssignTemplate

228

There may be additional extensions to which you want to apply these language-specificfeatures. For example, you may wish to classify files with the extension .INC asAssembly or Pascal files. The ExtAlias function allows you to do this. Some WindowsCASE tools require that include files follow special naming conventions. ExtAliasallows you to follow these conventions without losing Codewright Professional'slanguage-specific features for these files.

Example:

ExtAlias=".CWL",".C"

This statement in your Codewright Professional configuration file would cause files withthe extension .CWL to be treated as C language files for ChromaCoding, TemplateExpansion, and Smart Indenting.

ExtAssignTemplate=<" ext">, <" keyw">, <" templ">

Remarks ExtAssignTemplate provides a means of adding or modifying language templates. Youwill find a general description of Language Templates in the “General Operation”chapter of this manual.

Parameter Descriptionext A string containing the filename extension to which the template

applies. The extension is used to identify files containing sourcecode for a certain language. The template being defined onlyapplies when the current buffer has this file extension.

keyw A string containing the keyword or abbreviation that triggerstemplate insertion. Pressing the space bar after typing this wordinserts the template.

templ A string containing the encoded template. There are specialcharacters defined for use in language templates, that giveCodewright Professional instructions. Here is a table of the specialcharacters available, and their meanings:

Char. Purpose\n New Line. Simulates pressing enter at this point.& Specifies cursor position after template insertion.@ Issues a backspace.

ExtColorsAssoc

229

\c Insert 'c' literally, (e.g., \&, \@, \\)

Default value when parameter not suppliedext keyw templ

NIL NIL NIL

ExtColors=<int level>

Remarks ExtColors controls the status of the ChromaCoding features. Use it to turn on thehighlighting of programming language keywords and comments, or to turn on changedline highlighting.

Parameter Descriptionlevel When this parameter has a value of 1, ChromaCoding is enabled

for keywords and comments. A value of 2 enables ChromaCodingfor changed lines. These two modes are mutually exclusive. Azero value turns off ChromaCoding completely. To obtain thecurrent status without changing it, supply a -1 value for thisparameter.

Default value when parameter not suppliedlevel-1

Return Value ExtColors returns the current setting of the ChromaCoding feature.

See Also ExtIndentEnable, ExtAssignTemplate

ExtColorsAssoc=<" ext" >, <int level >

Remarks ExtColorsAssoc enables or disables ChromaCoding for files having a specifiedextension, or for all extensions.

Parameter Descriptionext A string containing the extension for which ChromaCoding is to be

enabled or disabled. The extension .* causes the command to

ExtCommentSearchLimit

230

apply to all extensions, overriding the settings for specificextensions.

level When this parameter is 0, ChromaCoding is turned off. A value of1 for this parameter turns on Language Dependent ChromaCoding.A value of 2 turns on Changed Lines ChromaCoding. When thisparameter is -1 the function reports the current state ofChromaCoding without altering it.

Default value when parameter not suppliedext level

NIL 0

Return Value ExtColorsAssoc returns the previous setting of ChromaCoding for the specifiedextension. This value is interpreted in the same manner as the level parameter above.

See Also ExtIndentEnableAssoc

ExtCommentSearchLimit=<long limit>

5HPDUNV ExtCommentSearchLimit sets the maximum number of lines that ChromaCoding willscan, forward and backward from the cursor, to determine if that position is in acomment. The default setting for this feature is 30.

Parameter Descriptionlimit The new line limit for searching for comment delimiters.

Default value when parameter not suppliedlimit

0

This function helps optimize the performance of ChromaCoding. By default, CodewrightProfessional searches 100 lines in each direction to find the beginning and end ofcomments, relative to the current position. You can safely reduce this amount if you havevirtually no single comment that spans 100 lines. This will allow the ChromaCodingfeature to make assumptions faster, thereby improving performance.

ExtExpandTemplate

231

5HWXUQ 9DOXH ExtCommentSearchLimit returns the previous setting of the comment search limit.

6HH $OVR ExtColorsAssoc

ExtDelayedColoring=<int on>

5HPDUNV ExtDelayedColoring turns on, off or reports the current setting of delayed coloring.This determines if a newly loaded file should be ChromaCoded first and then display(not delayed), or displayed and then ChromaCoded (delayed).

Parameter Descriptionon When this parameter is non-zero, delayed coloring is turned on.

When it is zero, delayed coloring is turned off. If the value of thisparameter is -1, the setting is not modified, but the function reportsthe current setting by way of the return value.

Default value when parameter not suppliedon0

5HWXUQ 9DOXH ExtDelayedColoring returns the new setting of the delayed coloring feature.

6HH $OVR ExtCommentSearchLimit

ExtExpandTemplate=<"template">

5HPDUNV ExtExpandTemplate expands the specified template string. This is a relatively lowlevel function that does no checking to see if the template expansion is appropriatelyplaced.

Parameter Descriptiontemplate A string containing the template to execute at the current cursor

position. The string may require escape sequences and predefinedmacros. Macros are identified with a %. A list of these macrosappears below:

ExtExpandTemplate

232

Macro form Description%col Num 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.

%line Num 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 CW??.EXT or your configuration file. 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 andpressing ( .

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

ExtIndentEnableAssoc

233

%xFuncCall $ Execute the Codewright Professional API function call in FuncCall. This may be any

function that could be assigned to a key or otherwise executed through

LibFunctionExec.

Default value when parameter not suppliedtemplate

NIL

ExtIndentEnable=<int level>

Remarks ExtIndentEnable controls the smart-indenting and language template features ofCodewright Professional.

Parameter Descriptionlevel When this parameter has a value of 1, Smart-indenting is enabled.

A value of 2 enables Template Expansion and Smart-indenting.(Template Expansion relies on Smart-indenting and thereforecannot be enabled alone.) A zero value turns off both of thesefeatures. To obtain the current status without changing it, supply a-1 value for this parameter.

Default value when parameter not suppliedlevel-1

Return Value ExtIndentEnable returns the current setting.

See Also ExtColors, ExtAssignTemplate

ExtIndentEnableAssoc=<" ext" >, <int level >

Remarks ExtIndentEnableAssoc enables or disables Smart Indenting and/or Template Expansionfor files having a specified extension, or for all extensions.

Parameter Descriptionext A string containing the extension for which Smart

Indenting/Template Expansion is to be enabled or disabled. Theextension .* causes the command to apply to all extensions.

ExtKmapAssign

234

level When this parameter is 0 both Smart Indenting and TemplateExpansion are disabled. A value of 1 enables Smart Indenting. Avalue of 2 enables both Smart Indenting and Template Expansion.When this parameter is -1 the current setting is reported but is notaltered.


NIL 0

Return Value ExtIndentEnableAssoc returns the previous setting of Smart Indenting and TemplateExpansion for the specified extension. This value is interpreted in the same manner asthe level parameter above.

See Also ExtColorsAssoc

ExtKmapAssign=<“keyName”>, <“funcCall”>

Remarks ExtKmapAssign makes key assignments to the keymap overlay used for languageindentation and template expansion.

Parameter DescriptionkeyName A string describing the key combination to which the function call


funcCall A string describing the function call to assign to the keycombination (e.g., "MovUp 1" ). If this parameter is NIL theassignment is not made.

Default values when called from LibFunctionExec (Command Key)keyid function_call NIL NIL


ExtReadTemplateFile

235

ReturnValue

ExtKmapAssign returns TRUE upon successful completion, and FALSE if theassignment cannot be made. Failure is usually due to an invalid keystring, since thefunction assigned to it is not checked for validity at this time.

See Also KmapAssign

ExtReadKeywordFile=<"ext">, <"filename">

Remarks ExtReadKeywordFile reads a series of keywords from a file and associates them with aspecified extension. When Language Dependent ChromaCoding is enabled for thatextension the added keywords will be colored.

Parameter Descriptionext A string containing the extension with which the keywords are to

be associated. This extension must be one for which there is built-in support, or one you have added support for. Support is currentlybuilt-in for the following extensions: .C, .CPP, .CXX, .PAS,.ASM, and if the appropriate DLLs are loaded .SC and .PRG.

filename A string containing the name of the file in which the list ofadditional keywords has been placed. The keywords in the filemust be in the format of one keyword per line.

Default value when parameter not suppliedext filename

NIL NIL

ReturnValue

ExtReadKeywordFile returns TRUE when the keyword file is successfully found andread. The function returns FALSE otherwise.

See Also ExtAddKeyword

ExtReadTemplateFile=<"ext">, <"fname">

5HPDUNV ExtReadTemplateFile allows loading a series of template assignments from a file.

ExtSetDelimiters

236

Parameter Descriptionext A string containing the name of the extension to which the

templates apply. This string may optionally begin with a dot. (e.g.,".C" or "cpp")

fname A string containing the name of the file in which the templatedefinitions are found.

The format of this file is one template assignment (or definition)per line. Each line contains two string parameters. They may eachbe enclosed in quotes and separated by whitespace. These are usedas the last two parameters of the function ExtAssignTemplate.

The first is the word or words that are to trigger the templateinsertion. The second parameter is the template that is insertedwhen triggered. This string contains % macros, escape sequencesand literal text, as necessary to insert the desired form. See thedescription of ExtAssignTemplate for further details.

Default value when parameter not suppliedext fname

NIL NIL

5HWXUQ 9DOXH ExtReadTemplateFile returns TRUE if the named file was found and read. This is notindicative of the contents of the file being in proper format. If the file could not be reador found, the function returns FALSE.

6HH $OVR ExtReadKeywordFile, ExtAssignTemplate

ExtSetDelimiters=<"ext">, <"delimiters">

5HPDUNV ExtSetDelimiters is used to set extension-specific word delimiters in the Extension-specific Settings file. It appears under the [Extension.xxx] headings in either theconfiguration file, the project file, or a user-defined file, depending on which option hasbeen selected.

Parameter Descriptionext A string containing the affected extension. If this parameter is NIL

the delimiters for the current buffer's file type are set.

ExtSetStyle

237

delimiters A string containing those characters, in addition to whitespace, thatseparate words for this file type. This string is used as a characterclass in a regular expression. The characters - ^ " and ] thereforeneed to be escaped. Precede these characters with a backslash. Ifthis parameter is NIL, the delimiters are not modified, but thecurrent setting may be obtained from the return value.

Default value when parameter not suppliedext delimiters

NIL NIL

5HWXUQ 9DOXH ExtSetDelimiters returns a string containing the new set of delimiters for the specifiedextension.

6HH $OVR NextWord, PrevWord

ExtSetStyle=<"ext">, <int level>

5HPDUNV ExtSetStyle sets or query Extension-specific indentation style used. At present, thisfunction is only effective on C and C++ files for determining the positioning of braceswhen templates are expanded.

Parameter Descriptionext A string containing the affected extension.

level A number indicating the desired style. A value of -1 for thisparameter does not modify the setting, but allows the currentsetting to be reported via the return value. Other possible valuesare noted below:

Value Meaning1 Braces on their own lines, not indented.2 Opening brace at end of line, closing brace on its

own line. (K&R)3 Braces on their own lines, indented.


NIL 0

ExtSetTemplateMacro

238

5HWXUQ 9DOXH ExtSetStyle returns the new setting for the indentation style for the specified extension.

6HH $OVR ExtQIndenting

ExtSetTemplateMacro=<int number>, <"macro">, <"ext">

5HPDUNV ExtSetTemplateMacro sets the string associated with a numbered template expansionmacro.

Parameter Descriptionnumber A number from 0 to 31 indicating which numbered macro is being

defined. The macro may then be used in templates, by referencingthis number preceded by a percent sign (e.g., %1, %3). Macrosfrom 0 to 9 may be associated with an extension so that templatesmay operate differently for different languages.

macro The string to insert in place of the macro reference. This stringmay contain other % macros, escape sequences or literal text. Formore information on % macros, refer to the description ofExtExpandTemplate.

ext A string containing the file extension with which the macro is to beassociated. This parameter is ignored if the number parameter is avalue greater than 9, since these cannot be associated with anextension. For values 0 through 9, if this parameter is NIL themacro is not associated with any extension. It will then only beused if the current buffer has no corresponding macro defined forits extension.

Default value when parameter not suppliednumber macro ext

0 NIL NIL

6HH $OVR ExtExpandTemplate, ExtAssignTemplate

ExtSetUpdateDelay=<int numCalls>

ExtSetWrap

239

5HPDUNV ExtSetUpdateDelay sets the number of times that the ChromaCoding update function iscalled before it does a complete update. This allows you to control how quickly or howintrusively colors are updated.

Parameter DescriptionnumCalls The number of times the update function is called before a

complete update is triggered.

Default value when parameter not suppliednumCalls

0

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.

6HH $OVR ExtCommentSearchLimit

ExtSetWrap=<"ext">, <int level>

5HPDUNV ExtSetWrap determines whether the word wrap feature will be turned on or off for fileswith a specified extension.

Parameter Descriptionext A string containing the extension with which the setting is to be

associated. This may optionally begin with a dot. (e.g., ".txt" or"C")

level When this parameter is 0, the word wrap feature is turned off.When it is a value of 1, word wrap is enabled, but only on thecurrent line. Lines following may require reformatting as a resultof edits. A value of 2 for this parameter enables continuousreformatting of the lines from the cursor to the end of theparagraph. See the function WrapEnable for a further description.


NIL 0

FFind

240

5HWXUQ 9DOXH ExtSetWrap returns the new setting of the word wrap feature for the specifiedextension.

6HH $OVR WrapEnable, WrapSetRightMargin, WrapParagraph

FFind=<"filePattern">

5HPDUNV FFind searches for files matching a specified pattern. It writes the names of matchingfiles in a file for review. The name of the file in which the names of matching files arestored is set with the function FFindFile.

Parameter DescriptionfilePattern A string containing the pattern for which a list of matching files is

desired. The pattern may contain the standard DOS wildcardcharacters ? and *. If the pattern contains a path element, the scopeof the search is limited to that directory and its subdirectories. Ifthe pattern does not contain a path element, the search covers thecurrent directory and its subdirectories.

Default value when parameter not suppliedfilePattern

NIL

When the filePattern parameter is NIL or an empty string, the default file pattern,specified with the FFindPattern function, will be used.

5HWXUQ 9DOXH FFind returns the number of matches found.

6HH $OVR FFindFile, FFindPattern, DlgFFind

FFindFile=<"filename">

Remarks FFindFile defines the name of the file in which the FFind function will place the namesof files that satisfy its search.

Parameter Descriptionfilename A string containing the name of the output file for FFind.

FFindShow

241

Default values when parameters not suppliedfilename

NIL

ReturnValue

FFindFile returns the new output filename.

FFindNext=

Remarks FFindNext highlights and processes the next entry in the File Find list of matching files.The indicated file is automatically loaded.

FFindPattern=<"defaultFPat">

5HPDUNV FFindPattern defines the default filename search pattern for the DlgFFind function.

Parameter DescriptiondefaultFPat A string containing the default filename pattern for the DlgFFind

dialog (the pattern initially displayed). The pattern may contain thestandard DOS wildcard characters ? and *. If the pattern contains apath element, the scope of the search is limited to that directory andits subdirectories. If the pattern does not contain a path element,the search covers the current directory and its subdirectories.

Default value when parameter not supplieddefaultFPat

NIL

5HWXUQ 9DOXH FFindPattern returns a string containing the new default pattern.

6HH $OVR FFindFile, FFind, DlgFFind

FFindShow=

Remarks FFindShow displays the list of files matching a recent File Find operation.

FGrepFile

242

See Also DlgFFind

FGrepFile=<"outputFile">

5HPDUNV FGrepFile defines the name of the message file in which FGrep and DlgFGrep placetheir output for review.

Parameter DescriptionoutputFile A string containing the name of the message file used by the File

Grep functions.

Default value when parameter not suppliedoutputFile

NIL

5HWXUQ 9DOXH FGrepFile returns the new name of the message file.

6HH $OVR FGrep, DlgFGrep

FGrepFlags=<WORD flags>

5HPDUNV FGrepFlags specifies the default search options used by FGrep if none are specified,and also the initial settings of these options in the DlgFGrep dialog.

Parameter Descriptionflags A value dictating the attributes of the search. The following values

may be ORed together to obtain the desired combined value:

Label DescriptionFGREP_DIRSEARCH Include subdirectories in the search.

FGREP_REGEX Consider the search string to be a regularexpression.

FGREP_IGCASE Allow lower case or upper case characters tomatch the pattern.

FGrepPattern

243

FGREP_BUFSEARCH Search only the currently loaded buffers.

Default value when parameter not suppliedflags

0

5HWXUQ 9DOXH FGrepFlags returns the new value for the File Grep flags.

6HH $OVR FGrep, DlgFGrep

FGrepNext=

Remarks FGrepNext highlight and processes the next entry in the File Grep list of locations ofmatching text. The file containing the matching text is loaded, and the cursor is placedon the line containing the match.

See Also DlgFGrep, FgrepShow

FGrepPattern=<"defaultRegex">

5HPDUNV FGrepPattern defines the text or regular expression search pattern initially displayed inthe DlgFGrep dialog.

Parameter DescriptiondefaultRegex A string containing the search pattern for the DlgFGrep dialog (the

pattern initially displayed). The pattern may be an ordinary stringsearch, or a regular expression, depending on the option flagsspecified.


NIL

5HWXUQ 9DOXH FGrepPattern returns a string containing the new default pattern.

FGrepScope

244

6HH $OVR FGrepFile, FGrep, FGrepFlags, DlgFGrep

FGrepScope=<"defaultFPat">

5HPDUNV FGrepScope defines the default filename search pattern for the DlgFGrep function.

Parameter DescriptiondefaultFPat A string containing the default filename pattern for the DlgFGrep

dialog (the pattern initially displayed). The pattern may contain thestandard DOS wildcard characters ? and *. If the pattern contains apath element, the scope of the search is limited to that directory andits subdirectories. If the pattern does not contain a path element,the search covers the current directory and its subdirectories.


NIL

5HWXUQ 9DOXH FGrepScope returns a string containing the new default pattern.

6HH $OVR FGrepFile, FGrep, DlgFGrep

FGrepShow=

Remarks FGrepShow display the message file generated by the DlgFGrep function.

See Also DlgFGrep

FileTabs=<"extension">, <"tabString">

5HPDUNV FileTabs creates an association between a filename extension and a tab string. After theassociation has been made, whenever a file with that extension is loaded into a buffer theassociated tab string is used to define tab stops in that buffer.

FilterAdd

245

Parameter Descriptionextension A string containing the filename extension to associate with the tab

string. When this string is empty, the tab string is applied globally.

tabString A string describing the locations of tab stops in buffers associatedwith the extension.

Default value when parameter not suppliedextension tabString

NIL NIL

Tab strings are further described under the Tabs and BufSetTabStr functions. Thisfunction is used primarily in the configuration file.

6HH $OVR Tabs, BufSetTabStr, BufQTabStr

FilterAdd =<"desc">, <"types">, <WORD position>

5HPDUNV FilterAdd permits the user to add file filters to those used by the File Open, File SaveAs, File New Browse, Edit Insert dialog boxes. File filters are the wildcard patterns thatappear in the "List file of Type" box that is in the lower left of these dialog boxes.

Parameter Descriptiondesc A string containing a description of the files that match the filter.

For example, "C source Files(*.c;*.h)". by convention, the filtersare part of this string, placed in parentheses. This string must notbe zero length.

types A string containing a list of the wildcard patterns that define thefiles to display, when this filter is selected. Members of this list areseparated by semicolons. For example, "*.c;*.h". This string mustnot be zero length.

position A number specifying the position within the list of file filters wherethis filter is placed, with 0 indicating the first position. Numberslarger than the number of members in the list will place the filter atthe end of the list.

FilterDeleteList

246

Default value when parameter not supplieddesc types positionNIL NIL 0

File filters may be created interactively, through the use of the File Filters dialog. Thisfunction is primarily used in the configuration file.

6HH $OVR FilterDeleteList, FilterGetList

FilterDeleteList

5HPDUNV FilterDeleteList deletes the entire list of user-defined file filters.

6HH $OVR FilterAdd, FilterGetList

FontSelectMsg=<int fhandle>, <int stockFont>

5HPDUNV FontSelectMsg sets a default font for status line messages. Use of this function mayrequire the Microsoft Window SDK.

Parameter Descriptionfhandle The numeric handle of a previously created font. If zero, a stock

font may be specified.

stockFont Specifies a built-in Windows font. Numeric values for thisparameter are predefined in WINDOWS.H. (values 10 to 16)

5HWXUQ 9DOXH FontSelectMsg returns TRUE if a font was successfully selected. If not, the functionreturns FALSE.

6HH $OVR FontSelectWin, FontCreate, FontQCurrent

GotoLine=

Remarks GotoLine prompts the user, on the status line or in a pop-up window, for the number ofthe line at which the cursor is to be placed. This function is usually assigned to a key.

KeyPlayback

247

InsertMode=

Remarks InsertMode toggle the condition of the insert/overtype flag for the current buffer, andprints a message stating which mode is in effect. The message appears on the status lineor in a pop-up window. The function is intended for assignment to a key.

ISearch=

Remarks ISearch performs an incremental search forward from the cursor position in the currentbuffer. An incremental search is a search in which the program does not wait for theentire search string to be entered. Instead, it searches for a match for what has beentyped thus far, after each character is typed. For example, if you type a character "a" itsearches forward for the character "a". If next you type "b" it searches forward,including the current position, for "ab". When you find the desired string, or want tocancel the search, just press [Esc].

See Also SrchFind

KeyPlayback=<"keystring">

Remarks KeyPlayback plays back the keystrokes recorded in the string supplied as a parameter asif they had been typed from the keyboard.

Parameter Descriptionkeystring The string containing the keystroke representations.

Default value when parameter not suppliedkeystringThe current keystroke recording

The keystrokes represented in the string follow the format described in the "Key Bindings-- Keymaps and Keystrings" section of this manual.

KeyRecord

248

ReturnValue

KeyPlayback returns one of the following values:

Value Meaning0 Successful completion1 There is nothing to play back.2 A series of keystrokes is currently being recorded.3 A recording is currently playing.

See Also KeyRecord

KeyRecord=<BOOL overwrite>

Remarks KeyRecord toggles the recording of keystrokes entered at the keyboard. If keystrokerecording is not currently on, it is turned on. Otherwise it is turned off.

Parameter Descriptionoverwrite When the value of this parameter is TRUE, any previous recorded

keystrokes will be overwritten. If FALSE, the function will failinstead.

Default value when parameter not suppliedoverwrite

0

ReturnValue

KeyRecord returns 0 upon successful completion and 1 if a playback is currently inprocess. A value of -1 is returned if the function fails.

See Also KeyPlayback

KmapAssign=<" keyid">, <" function_call">

Remarks KmapAssign assigns a function call, including any necessary parameters, to a keycombination in the current keymap.

LibAutoLoad

249

Parameter Descriptionkeyid A string describing the key combination to which the function call


function_call A string describing the function call to assign to the keycombination (e.g., "MovUp(1)" ). If this parameter is NIL theassignment is not made.

Default value when parameter not suppliedkeyid function_call NIL NIL


Example:

KmapAssign="<Shift-ctrl-UP>","movup 5 "

ReturnValue

KmapAssign returns TRUE upon successful completion, and FALSE if the assignmentcannot be made. Failure is usually due to an invalid keystring, since the functionassigned to it is not checked for validity at this time.

LibAutoLoad =<" libNames" >

Remarks LibAutoLoad creates associations between function names and libraries (DLLs) inwhich they are found when the library has not been loaded into memory. CodewrightProfessional then knows to load the DLL when the associated function is called. This isnot necessary if the library has been loaded in to memory.

Parameter DescriptionlibNames A string containing the name of the DLL, followed by the function

names it contains. The details of this string's format and exampleusage is provided below.

Default value when parameter not suppliedlibNames NIL

LibFunctionReplace

250

The libNames string begins with the name of the DLL. Note that this is the name only --no path or extension should be specified. The DLL must be in the current directory, or inone of the series of directories named by the CWLIB environment variable. The DLLname may be followed by a colon or left parenthesis to offset it from the names of thefunctions. This is not required, but is allowed for purposes of readability.

Next comes the list of functions. The functions are separated from each other and fromthe library name by whitespace (spaces or tabs). In addition to the whitespace, which isrequired, the function names may also be separated by commas.

Examples:

LibAutoLoad="myDLL: func1 func2 "LibAutoLoad="myDLL func1 func2 "LibAutoLoad="myDLL= func1 func2 )"LibAutoLoad="myDLL= func1, func2 )"

ReturnValue

LibAutoLoad does not return a value.

See Also LibPreload

LibFunctionReplace=<"original">, <"replacement">

5HPDUNV LibFunctionReplace allows limited aliasing or replacement of one function withanother. The replacement is limited to execution through the LibFunctionExecfunction. This includes execution of all keymap assignments and execution through theCommand Key. When the original function is called, the designated replacement isexecuted.

Parameter Descriptionoriginal A string containing the name of the function which is replaced.

replacement A string containing the name of the function to call in its place.

Default value when parameter not suppliedoriginal replacement

NIL NIL

LibPreLoad

251

If the function is called directly, through compiled source code, for example, the originalfunction will execute rather than the replacement.

5HWXUQ 9DOXH LibFunctionReplace returns TRUE on successful completion and FALSE if both of thearguments is NIL.

6HH $OVR LibFunctionExec, LibQReplacement

LibPreLoad=<" libName" >

Remarks LibPreLoad loads a dynamic link library (DLL) other than those supplied. Thesupplied DLL's, including the User's DLL, are loaded automatically.

Parameter DescriptionlibName The name of the DLL to load. This name may contain a path

element, but need not name an extension. If an extension otherthan .DLL is named, the function will fail.

Default value when parameter not suppliedlibName NIL

If the DLL contains functions with names identical to those defined in a supplied DLL,the functions will only be accessible by preceding the function name with the name of theDLL and a colon.

If no path to the DLL is specified, the DLL must be in the current directory, or in one ofthe series of directories named by the CWLIB environment variable.

Examples:

LibPreLoad("myDLL");LibPreLoad("c:\windows\mydll");

ReturnValue

LibPreLoad returns TRUE when successful, and FALSE upon failure. Failure isusually caused by Codewright Professional being unable to locate the named DLL.

See Also LibAutoLoad

LibUnLoad

252

LibUnLoad =<" libName" >

Remarks LibUnLoad releases the memory occupied by the DLL named in the parameter.

Parameter DescriptionlibName The name of the DLL of which to dispose.

Default value when parameter not suppliedlibName NIL

Even when a DLL has been removed from memory, Codewright Professional retains theinformation on what functions the DLL contained. If a function contained within thelibrary is subsequently called, the library is reloaded.

ReturnValue

This function returns TRUE when successful, and FALSE upon failure. Failure isusually caused by Codewright Professional being unable to locate the named DLL. Thefunction will also fail if a function in the library is being executed (is on the call stack).

See Also LibPreLoad, LibAutoLoad

Lower=

Remarks Lower forces all alphabetic characters in the current selection to lower case. If noselection has been defined, the current line is converted to lower case.

MarkGoto =<MarkID mark>

Remarks MarkGoto moves the cursor to the position assigned to the bookmark named as aparameter.

Parameter Descriptionmark The mark whose location becomes the current cursor position.

Default value when parameter not suppliedmarkMARK_INVALID

MarkSet

253

ReturnValue

MarkGoto returns 0 upon successful completion and a non-zero value upon failure. Forexample, failure will result if the specified MarkID is not currently defined.

MarkRestorePos=

Remarks MarkRestorePos pops the most recently saved cursor position off the stack and makesthat position the current position. Cursor positions are saved onto the stack through acall to MarkSavePos.

ReturnValue

MarkRestorePos returns 0 upon successful completion and a non-zero value uponfailure.

See Also MarkSavePos

MarkSavePos=

Remarks MarkSavePos saves the current buffer position described by the parameters in a markon a stack. This stack is called the "saved positions" stack.

The MarkRestorePos function may be used to move to a saved position.

See Also MarkRestorePos

MarkSet=<MarkID mark>, <long line>, <long column>

Remarks MarkSet assigns the line and column location, specified by the parameters, to the namedmark.

Parameter Descriptionmark The MarkID of the mark to which the assignment is made. This

must be a pre-existing mark.

line If non-zero, the line number of the current buffer at which the markis to be set. If zero, place mark in current line.

column If non-zero, the column number of the current buffer at which themark is to be set. If zero, use current column number.

MenuCmnd

254

Default value when parameter not suppliedmark line column

MARK_INVALID 1 1

The reserved mark, mark 0, which is the current cursor position, may be used as aMarkID parameter. This may result in the cursor being moved.

ReturnValue

MarkSet returns 0 upon successful completion and a non-zero value upon failure.

MenuCmnd=<“menuStr”>, <“itemStr”>

Remarks MenuCmnd allows you to access any menu item directly by specifying strings thatmatch menu and item. This makes it convenient to create your own shortcut keys. Itdoes not work for submenus.

Parameter DescriptionmenuStr A descriptive string indicating which menu to select. For example,

the string “File” would select the File menu. The case of the stringis not significant, and you need only specify enough of the menuname to distinguish it from other menus.

itemStr A descriptive string indicating which item to select from the menu.For example, the string “Open” would select the Open item ifmenuStr selected the “File” menu. The case of the string is notsignificant, and you need only specify enough of the item name todistinguish it from other items.

Default values when parameters not suppliedmenuStr itemStr

NIL NIL

Here is an example of how this function might be used in a key assignment in yourconfiguration file (CW??.INI):

[KmapAssign]; same as selecting Window | Tile from menuKmapAssign="<F12>", "MenuCmnd ‘w’ ‘t’"

MouseLeftDown

255

MenuCommand=<int menuItemID>

Remarks MenuCommand allows you to access any menu item directly by specifying its menuitem ID number. This makes it possible to create your own shortcut keys.

Parameter DescriptionmenuItemID The numeric ID of the menu item you wish to execute. You can

find these IDs in the file EXPORTS.H, in CodewrightProfessional's INCLUDE subdirectory. They all begin with IDM_and are grouped together.

Default values when parameter not suppliedmenuItemID

0

Here is an example of how this function might be used in a key assignment in yourconfiguration file (CW??.INI):

[KmapAssign]; same as selecting Window | Tile Vertically from menuKmapAssign="<F12>", "MenuCommand 0x150d"

MouseLeftDClick=

Remarks MouseLeftDClick is the function that processes a double click with the left mousebutton. Its operation depends upon the context in which the double click was performed.By default, it is used to select a word.

See Also MouseRightDClick, MouseLeftDown

MouseLeftDown=<int selType>, <BOOL oneLine >

MouseRightDown

256

Remarks MouseLeftDown is the function that processes a press on the left mouse button. Theduration of a press has indicated that it is not a click or a double click. This usuallymeans that the mouse will be dragged to create a selection.

Parameter DescriptionselType This parameter sets the type of selection that will be created by the

function. This parameter may be omitted to indicate a normalselection, as opposed to line or column selection.

oneLine When this parameter is TRUE, the selection is limited to a singleline. This parameter is usually omitted, in which case the selectionis not limited.

Default value when parameter not suppliedselType oneLine

0 FALSE

See Also MouseRightDown, MouseLeftDClick

MouseRightDown=<int selType>, <BOOL single >

Remarks MouseRightDown is the function that processes a press on the right mouse button. Theduration of a press has indicated that it is not a click or a double click. This usuallymeans that the mouse will be dragged to create a column selection.

Parameter DescriptionselType This parameter sets the type of selection that will be created by the

function. This parameter may be omitted to indicate a columnselection, as opposed to line or normal selection.

oneLine When this parameter is TRUE, the selection is limited to a singleline. This parameter is usually omitted, in which case the selectionis not limited.

Default value when parameter is not suppliedselType oneLine

SELECTION_COLUMN FALSE

See Also MouseLeftDown, MouseRightClick, MouseRightDClick

MovEOF

257

MovDown=<long lines>

Remarks MovDown moves the cursor position in line units, usually toward the end of the currentbuffer.

Parameter Descriptionlines The number of lines to advance the cursor position in the buffer.

Default value when parameter is not suppliedlines

1

If the parameter is a negative number, the cursor advances toward the beginning of thebuffer. This allows a variable, whose value is not known, to be passed as a parameter andobtain the desired result.

If a buffer extreme (the beginning or end of the buffer) prevents the cursor from beingmoved the specified number of lines, the cursor is placed at the closest permissible line.MovDown attempts to leave the column position unaltered.

ReturnValue

MovDown returns TRUE if the cursor was moved, and FALSE if it did not (forexample, the cursor could not advance any further in the direction specified).

See Also MovUp

MovEndWin =

Remarks MovEndWin moves the cursor to the last line visible in the window. The columnposition does not change, if the current settings allow.

ReturnValue

This function returns TRUE if the cursor was moved. It returns FALSE if the cursor wasalready on the last line of the window, or as close as current settings allow.

See Also MovTopWin

MovEOF=

MovEOL

258

Remarks MovEOF moves the cursor position to the last real (non-virtual) line of the currentbuffer.

ReturnValue

This function returns TRUE if the cursor position was changed, and FALSE if the cursorposition was already within the last line of the buffer.

See Also MovEOL

MovEOL =

Remarks MovEOL repositions the cursor to the position following the last character of the currentline.

ReturnValue

This function returns TRUE if the cursor moved, and FALSE if the cursor was already atthe end of the line.

MovHome=

Remarks MovHome moves the cursor to the beginning of the current line.

ReturnValue

This function returns TRUE if the cursor was moved, and FALSE if the cursor wasalready at the beginning of the line.

See Also MovEOL

MovLeft =<long columns>

Remarks MovLeft repositions the cursor toward the beginning of the line by the indicated numberof columns.

Parameter Descriptioncolumns The number of columns to move, relative to the current.

Default value when parameter not suppliedcolumns

1

MovPageDown

259

The function will not move the cursor past the beginning of the line. if the parameter is anegative number, the cursor is repositioned toward the end to the line. If the cursorcannot be moved the full number of columns indicated, the function moves the cursor tothe closest permissible position.

ReturnValue

MovLeft returns TRUE if the cursor was moved, and FALSE if it was not (primarilywhen the cursor is already at the beginning of the line).

See Also MovRight

MovNextChar=<long chars>

Remarks MovNextChar advances the current cursor position by the specified number ofcharacters toward the end of the buffer.

Parameter Descriptionchars The number of characters to advance the cursor. Negative values

for this parameter move the cursor toward the beginning of thebuffer.

Default value when parameter not suppliedchars

1

The nature of this function does not allow the cursor to be placed in virtual space, butallows it to advance the cursor beyond the boundaries of the current line.

ReturnValue

This function returns TRUE if the cursor was moved, and FALSE if the cursor wasalready at the buffer extreme.

See Also MovPrevChar

MovPageDown=

MovPageUp

260

Remarks MovPageDown advances the cursor by a "page". A page is the number of linesdisplayed in the current window, less one line.

The function does not alter the position of the cursor relative to the window, if thatposition is permissible at the new buffer location.

ReturnValue

This function returns TRUE if the cursor is moved, and FALSE if it was not.

MovPageUp=

Remarks MovPageUp moves the cursor toward the beginning of the buffer by a "page". A pageis the number of lines displayed in the current window, less one line.

The function does not alter the position of the cursor relative to the window, if thatposition is permissible at the new buffer location.

ReturnValue


See Also MovUp

MovPrevChar=<long chars>

Remarks MovPrevChar decrements the current cursor position by the specified number ofcharacters, moving it toward the beginning of the buffer.

Parameter Descriptionchars The number of characters to decrement the cursor. Negative values

for this parameter advance the cursor toward the end of the buffer.

Default value when parameter not suppliedchars

1

The nature of this function does not allow the cursor to be placed in virtual space, butallows it to move the cursor beyond the boundaries of the current line.

MovTopWin

261

ReturnValue

This function returns TRUE if the cursor was moved, and FALSE if the cursor wasalready at the buffer extreme.

See Also MovNextChar

MovRight=<long columns>

Remarks MovRight repositions the cursor the specified number of columns to the right of thecurrent position.

Parameter Descriptioncolumns The number of columns to move the cursor.

Default value when parameter not suppliedcolumns

1

Positive values move the cursor toward the end of the line and negative numbers move ittoward the beginning of the line. If MovRight is unable to position the cursor at thelocation indicated, it repositions the cursor to the closest permissible location.

ReturnValue


See Also MovLeft

MovTopBuf=

Remarks MovTopBuf repositions the cursor at the first character of the buffer.

ReturnValue

This function returns TRUE if the cursor is moved, and FALSE if it was already at thetop of the buffer..

See Also MovEOF

MovTopWin =

MovUp

262

Remarks MovTopWin positions the cursor on the first line visible in the window. The columnposition is not altered by this function, unless the column is not a permissible locationwithin the new line.

ReturnValue


See Also MovEndWin

MovUp=<long lines>

Remarks MovUp moves the cursor position in line units, usually toward the top of the currentbuffer.

Parameter Descriptionlines The number of lines for the cursor position to regress in the buffer.

Default value when parameter not suppliedlines

1

If the parameter is a negative number, the cursor advances toward the end of the buffer.This allows a variable, whose value is not known, to be passed as a parameter and obtainthe desired result.

If a buffer extreme (the beginning or end of the buffer) prevents the cursor from beingmoved the specified number of lines, the cursor is placed at the closest permissible line.MovUp attempts to leave the column position unaltered.

ReturnValue

MovUp returns TRUE if the cursor was moved, and FALSE if it did not (for example,the cursor could not advance any further in the direction specified).

See Also MovDown

MsgLevel=<int newLevel>

MsgMessage

263

Remarks MsgLevel sets the message priority level. The purpose of messages ranges frominformative to error notification. The function used to display a message indicates itspriority. Setting the message level allows you to determine which priority output youwill see.

Select the appropriate message level from the table below:

Level Message Origins0 All messages are displayed.1 Error and warning messages are displayed.2 Only errors are displayed.3 All messages are suppressed

Parameter DescriptionnewLevel The number of the message level to assign. A value of -1 for this

parameter causes the function to report the current setting only.

Default value when parameter not suppliednewLevel

-1

ReturnValue

MsgLevel returns an integer value from 0 to 3 indicating the previous message level.

MsgMessage=<“message”>

5HPDUNV MsgMessage displays the supplied message on Codewright Professional's status line (thebottom of the parent window).

Parameter Descriptionmessage The message to display.

Default value when parameter not suppliedmessage

NIL

MsgPauseOnError

264

The color of this message may be set using the function ColorMessage. When theMessage Level is greater than 0 (MsgLevel), messages that would otherwise be displayedare suppressed.

6HH $OVR MsgLevel, ColorMessage, MsgWarning, MsgNotify, MsgError

MsgPauseOnError=<BOOL setting>

Remarks MsgPauseOnError prescribes whether Codewright Professional should pause betweenmultiple warning or error messages.

Parameter Descriptionsetting This value is TRUE to turn pausing on, and FALSE to turn pausing

off.

Default value when parameter not suppliedsetting

0

When pausing is on, Codewright Professional pauses for input from the keyboard betweenmessages. This provides you with an opportunity to read each message before it isoverwritten by the next. When pausing is off, messages are displayed as they aregenerated.

ReturnValue

MsgPauseOnError returns the previous pause on error setting.

NextWord=

Remarks NextWord moves the cursor position to the first non-whitespace character immediatelyfollowing the next space, tab or newline.

See Also PrevWord, SrchFind

OutputFile=

Paste

265

Remarks OutputFile prompts the user to enter an output filename for the current buffer. This isthe file to which the buffer will be written upon the next save.

OutputWindow =<int showMode>

Remarks OutputWindow lets you display or hide the tabbed output window, or specify which tabis selected.

Parameter DescriptionshowMode This parameter specifies whether the window is showing and which

tab is selected, if it is showing. Values of 0 or greater represent theoffset of the tab from the left side of the window. 0 represents thefirst tab, 1 represents the second and so on. Specifying a tab toselect makes the output window visible.

Values less than 0 receive special treatment as indicated below:

Value Purpose-1 Query current visibility status.-2 Display output window without changing which

tab is selected.-3 Hide output window

Default values when parameters not suppliedshowModetoggles current visibility

ReturnValue

OutputWindow returns a BOOL indicating TRUE if the window is visible and FALSEif it is hidden.

Paste=

Remarks Paste inserts the contents of the Scrap buffer or Windows Clipboard, depending uponwhich is enabled, at the current cursor position. An informative message is printed onthe status line. This function is intended for assignment to a key.

PrevWord

266

PrevWord=

Remarks PrevWord moves the cursor position to the first non-whitespace character immediatelyfollowing the previous space, tab or newline.

See Also NextWord, SrchFind

Print =<BOOL direct>

Remarks Print prints the contents of the current buffer on the default printer device.

Parameter Descriptiondirect If this parameter is TRUE, printing occurs without further input,

using the current settings. If this parameter is FALSE, the Printdialog box is invoked to allow reviewing and modifying thesettings prior to printing.

Default value when parameter not supplieddirect hWndParent

FALSE 0

ReturnValue

Print returns TRUE when the printing is successfully commenced. It returns FALSE ifthe print job was cancelled.

See Also PrintSelection

PrintFlags=<WORD flags>

Remarks PrintFlags sets the flags associated with the File Print dialog (Print ) that control variousoption settings.

Parameter Descriptionflags A value whose bit settings determine various attributes of the Print

task. The bits and their meanings are as follows:

Bit Purpose

PrintFooter

267

PRN_SELECTION Print only the contents of the current selection.PRN_LHEADER Left justify the header.PRN_CHEADER Center the header.PRN_RHEADER Right justify the header.PRN_LFOOTER Left justify the footer.PRN_CFOOTER Center the footer.PRN_RFOOTER Right justify the footer.PRN_CHROMACODING Use ChromaCoding in printing.PRN_CC_ITALIC Use italic text for ChromaCoding.PRN_CC_BOLD Use bold text for ChromaCoding.PRN_CC_SWITCH Make ChromaCode use plain text and give ChromaCode attributes

to other text.PRN_NO_FF Treat form feed as just another character.

Default value when parameter not suppliedflags

0

ReturnValue

PrintFlags does not return a value.

See Also Print

PrintFooter=<" footer" >

Remarks PrintFooter specifies the footer string to use when printing.

Parameter Descriptionfooter A string containing the footer string to print on each page printed.

This string may contain any of several macros which are defined asfollows:

Macro Expands to%f Current filename%d Today's date%p Current page number

PrintHeader

268

Default value when parameter not suppliedfooterNIL

ReturnValue

PrintFooter does not return a value.

See Also PrintHeader, PrintFlags

PrintHeader=<" header" >

Remarks PrintHeader specifies the header string to use when printing.

Parameter Descriptionheader A string containing the footer string to print on each page printed.

This string may contain any of several macros which are defined asfollows:

Macro Expands to%f Current filename%d Today's date%p Current page number

Default value when parameter not suppliedheaderNIL

ReturnValue

PrintHeader does not return a value.

See Also PrintFooter , Print , PrintFlags

PrintLineInc =<WORD inc>

5HPDUNV PrintLineInc defines at what increment line numbers are printed.

PrintMargin...

269

Parameter Descriptioninc A value that determines the interval between line numbers on a

printout. A value of 0 for this parameter turns line numbering off.A value of 1 prints the line number on each line. The default valueis 5, which means that line numbers are printed on every fifth line.

Default value when parameter not suppliedinc0

5HWXUQ 9DOXH PrintLineInc does not return a value.

6HH $OVR Print , PrintFlags

PrintLineInc =<WORD inc>

Remarks PrintLineInc defines at what increment line numbers are printed.

Parameter Descriptioninc A value that determines the interval between line numbers on a

printout. A value of 0 for this parameter turns line numbering off.A value of 1 prints the line number on each line. The default valueis 5, which means that line numbers are printed on every fifth line.

Default value when parameter not suppliedinc0

ReturnValue

PrintLineInc does not return a value.

See Also Print , PrintFlags

PrintMargin...

PrintSelection

270

PrintMarginBottom =<WORD margin>PrintMarginLeft =<WORD margin>PrintMarginRight =<WORD margin>PrintMarginTop =<WORD margin>

5HPDUNV The PrintMargin... functions define how many lines or columns are reserved as amargin at the top, bottom, left and right edge of the page.

Parameter Descriptionmargin The number of lines (top or bottom) or columns (left or right) to

reserve as a margin. Lines that do not fit between the margins aretruncated.

Default value when parameter not suppliedmargin

0

These functions are used largely for maintaining the desired configuration, and aretherefore usually found in the CW??.INI configuration file under the [Printer] heading.

6HH $OVR Print , PrintFlags

PrintSelection=

Remarks PrintSelection prints the contents of the current selection on the default printer device.Unlike most functions that operate on selections, this function does not remove theselection upon completion.

ReturnValue

If a selection is marked, PrintSelection sends it to Windows for printing and returnsTRUE. If no selection is marked, the function returns FALSE and nothing is printed.Print errors are handled by Windows.

See Also Print

QDefaultKeymap=

Remarks QDefaultKeymap reports the name of the keymap currently in effect.

ScrapPrev

271

Return Value QDefaultKeymap returns a string containing the name of the keymap, e.g., "CUA" or"brief".

See Also DefaultKeymap

Redo=

Remarks Redo undoes the undo immediately preceding. It prints a message indicating that theundo has been redone, or prints "nothing to redo" if there was no undo operationimmediately preceding. This function is intended for assignment to a key.

See Also Undo

Repeat=

Remarks Repeat is an interactive function intended for assignment to a key. It first prompts forthe number of times that you wish to repeat a command, and then waits for the command.That command is repeated the specified number of times.

ResizeWindow=

Remarks ResizeWindow allows the user to interactively resize the current window. This functionis the same as selecting "Size" from the window's System menu.

ScrapNext=

Remarks ScrapNext selects the next scrap buffer in the circular list of scrap buffers.

ReturnValue

ScrapNext returns the index of the previously current scrap buffer.

See Also ScrapPrev

ScrapPrev=

ScrapSetCount

272

Remarks ScrapPrev selects the previous scrap buffer in the circular list of scrap buffers.

ReturnValue

ScrapPrev returns the index of the previously current scrap buffer.

See Also ScrapNext

ScrapSetCount=<WORD count>

5HPDUNV ScrapSetCount sets the number of scrap buffers available for use.

Parameter Descriptioncount The number of scrap buffers to allow in the list.

Default value when parameter not suppliedcount

0

If the number of scrap buffers is reduced, the scrap buffers with a higher index than countare lost. If the current scrap buffer was one of those lost, the remaining scrap buffer withthe highest index is made current.

5HWXUQ 9DOXH ScrapSetCount returns the new setting for the number of scrap buffers that exist.

SelectWord=

Remarks SelectWord creates a selection around the word in which the cursor is positioned. If thecursor is located in whitespace no selection is created. This function is normallyassigned to the mouse Left-Double-Click action.

ReturnValue

SelectWord returns TRUE is a selection was created and FALSE if not.

See Also NextWord, PrevWord

SetLineDrawBindings=

SetLineDrawStyle

273

Remarks SetLineDrawBindings makes the key assignments for line drawing with the arrow keys.Assignments are made to the up, down, left and right keys that allow them to be used fordrawing lines in documents when the ) and + keys are also depressed.

This function is only available when the "add-on" CWLDRAW.DLL has been loaded.This can be done by adding a line to your .INI file under the [LibPreload] section. Addthe statement LibPreload=CWLDRAW.DLL.

The characters inserted by the Line Draw keys will only appear as lines if a fontsupporting the IBM OEM character set is used. The functions that perform the actualdrawing are as follows: LDUp , LDDown, LDRight , and LDLeft . These functions arenot documented elsewhere.

ReturnValue

SetLineDrawBindings does not return a value.

See Also SetLineDrawStyle

SetLineDrawStyle=<WORD style>

Remarks SetLineDrawStyle sets the types of lines used by the Line Draw functions.

Parameter Descriptionstyle A value from 1 to 4 indicating which style of lines to use. If a style

is not specified, style 1 will be used.

Default value when parameter not suppliedstyle

0

This function is only available when the "add-on" CWLDRAW.DLL has been loaded.This can be done by adding a line to your .INI file under the [LibPreload] section. Addthe statement LibPreload=CWLDRAW.DLL.

ReturnValue

SetLineDrawStyle returns the style number that has been put into effect.

SlideIn

274

See Also SetLineDrawBindings

SlideIn=<" ch " >

Remarks SlideIn indents a line or block of lines using a specified character.

Parameter Descriptionch The string to use for indenting. This parameter usually specifies a

space or a tab, but may also specify a comment character, such as";", "#" or "C" or decorative character such as "*". If this is aNULL no action is taken.

Default value when parameter not suppliedch

NIL

See Also SlideOut

SlideOut=<" ch " >

Remarks SlideOut outdents a line or block of lines by the character specified.

Parameter Descriptionch The string by which the line or block is outdented. If this is a

NULL no action is taken.

If the string specified is whitespace (space or tab), and the line isprefixed with whitespace, the parameter is treated as an incrementrather than a literal character. For example, if the line begins with atab and a space is the parameter, the whitespace is adjusted tooutdent it one column. Similarly, if the line is preceded by spacesand a tab is specified, the line is outdented the equivalent numberof spaces.

Other strings are treated literally, such as ";" which removes onlysemicolons, when present at the beginning of the line. If the

SrchFind

275

specified string is not present at the beginning of the line, no actionis taken for that line.

Default value when parameter not suppliedch

NIL

See Also SlideIn

Space=

Remarks Space is intended to be bound to the space key. If there is no current selection, thisfunction merely inserts a space character into the buffer. If there is a selection defined,the function indents that selection by a single space.

See Also SlideIn

SrchFind=<"sPattern">, <DWORD sFlag>

Remarks SrchFind searches for text that matches the supplied string or regular expression pattern.

Parameter DescriptionsPattern The string or regular expression pattern to match.

sFlags The search attribute word, which controls case-sensitivity, directionand scope of the search, and whether the pattern is considered aregular expression or an ordinary string.

Default value when parameter not suppliedsPattern sFlags

NIL SrchQFlags

When a match is found, the cursor is positioned at the beginning of the matched text,unless a regular expression pattern is used which dictates otherwise.

ReturnValue

SrchFind returns TRUE if a match was found, and FALSE if no match was found.

SrchQFlags

276

See Also SrchQFlags

SrchQFlags=

Remarks SrchQFlags reports the value of the search attribute word. There are functions forsetting each of the individual attributes. These attributes include: case-sensitivity,direction and scope of the search, and whether patterns are treated as regular expressionsor as ordinary strings.

This provides a method of obtaining a snapshot of the search attribute settings at anyparticular time. That state can later be restored by supplying the value obtained from thisfunction to the SrchSetFlags function.

ReturnValue

SrchQFlags returns the search attribute word currently in effect. The meaning of theindividual bits of this value are listed in the description of the SrchSetFlags function.

See Also SrchSetFlags

SrchSetFlags=<DWORD sFlags>

Remarks SrchSetFlags sets the search attribute word to a specified value.

Parameter DescriptionsFlags The value to which the search attribute word is set. A value of -1

for this parameter causes the function to report the current settingonly.

Default value when parameter is not suppliedsFlags

-1

There are functions for setting each of the individual attributes. These attributes include:case-sensitivity, direction and scope of the search, and whether patterns are treated asregular expressions or as ordinary strings. This function is useful for setting the attributesas a group, such as when restoring a previous state that has been saved. The attributesgoverned by individual bits are as follows:

SrchTranslate

277

Label PurposeSEARCH_IGCASE Turns case-sensitivity on or off. When the bit is off, case is significant in

matching. When on, it is not.

SEARCH_MAXIMAL When regular expressions are in use, this indicates whether the search will

match the largest unit of text or the smallest that fits the specified pattern.

SEARCH_REGEX Determines whether the pattern to match is treated as a regular expression

or an ordinary string. When the bit is on, it is treated as a regular

expression. When off, it is treated as an ordinary string.

SEARCH_FORWARD Determines the direction the search takes, relative to the cursor position.

When the bit is on, the search begins with text subsequent to the cursor.

When off, the search begins with text preceding the cursor.

SEARCH_SELECTION Determines if search operations and replace operations are limited to the

current selection . When the bit is on, the operation is limited to the

selection. When off, the operation is not limited.

SEARCH_WRAP Determines if operations terminate after reaching a buffer extreme

(beginning or end). When the bit is on, the operation continues from the

opposite extreme to the point at which the operation began. When off, the

operation is discontinued when a buffer extreme is reached.

SEARCH_GLOBAL Used only during replace operations. When the bit is on, all matches

within the scope of the operation are subject to translation. When off, the

operation only applies to the first match found.

SEARCH_PROMPT Used only during replace operations. When the bit is on, replace

operations prompt before changing text matching the pattern. When off,

text is replaced without prompting.

SEARCH_ONCE Used only during replace operations. When this bit is on, one occurrence

is replaced without prompting and then the function returns.

SEARCH_LOW_ALT_PRECE

DENCE

Used in regular expression searches, primarily for BRIEF compatibility.

Forces the Alternation operator, |, to have a lower precedence than other

operators.

ReturnValue

SrchSetFlags returns the value previously in effect.

See Also SrchQFlags

SrchTranslate=<"sPattern">, <"rString">, <DWORD sFlags>

StateSetMarkLevel

278

Remarks SrchTranslate searches for text that matches a string or regular expression pattern. If amatch is found, the text is replaced with a supplied string, with permission.

Parameter DescriptionsPattern The string or regular expression pattern to match.

rString The string to replace the matched text.

sFlags The search attribute word, which controls case-sensitivity, directionand scope of the search, and whether the pattern is considered aregular expression or an ordinary string. The attribute word mayalso stipulate replacement without prompting.

Default value when parameter not suppliedsPattern rString sFlags rLen

NIL NIL SrchQFlags NIL

The cursor is positioned at the beginning of the matching text when prompting forreplacement. The cursor returns to its original position at the end of multiplereplacements, if allowed to run to completion. If aborted by the user, the cursor is left atthe last occurrence of matching text.

ReturnValue

SrchTranslate returns the number of replacements made.

See Also SrchFind, SrchQFlags, SrchSetFlags

StateSetMarkLevel=<int LevelFlags>

Remarks StateSetMarkLevel defines what kinds of bookmarks will be recorded in the statefilefor restoration.

Parameter DescriptionLevelFlags A value whose bits determine which types of marks are saved in

the Codewright Professional state file. A -1 for this value indicatesthat it is a query only, and the setting is not changed. A value of 0turns off mark saving, while a value of 0x000f turns on saving forall types of marks. The labels below have been defined to assistyou in defining the proper flags value.

SysCaretHeight

279

Default values when called from LibFunctionExec (Command Key)fname

0

Label DescriptionSAVE_MARK_LOCAL Save local bookmarks in the state file for restoration.SAVE_MARK_GLOBAL Save global bookmarks in the state file for restoration.SAVE_MARK_POS Save the Saved Position stack in the state file for

restoration.SAVE_MARK_SEL Save the current selection in the state file for restoration.

ReturnValue

StateSetMarkLevel returns the previous setting of the mark level flags.

SysBeep=

Remarks SysBeep emits an unobjectionable, if not pleasant, tone from the speaker.

SysCaretHeight=<int percent>, <int cursor>

Remarks SysCaretHeight sets the height of the caret or cursor for one of four cursors used byCodewright Professional.

Parameter Descriptionpercent The height or the cursor as a percentage of the character cell

height. Positive values fill from the top of the cell, while negativevalues fill from the bottom.

cursor An index, specifying which of the four cursors is being defined.The predefined labels for this purpose are as follows:

SysCaretWidth

280

Label DescriptionCARET_INSERT Cursor used in insert mode, when the cursor is in the text area.

CARET_INSERT_VIRTUAL Cursor used in insert mode, when the cursor is in virtual space.

CARET_OVERTYPE Cursor used in overtype mode, when the cursor is in the textarea.

CARET_OVERTYPE_VIRTUAL Cursor used in overtype mode, when the cursor is in virtualspace.

ReturnValue

SysCaretHeight returns the previously defined caret height. If a cursor other than thefour above is specified, the function returns 0.

See Also SysCaretWidth

SysCaretWidth=<int percent>

Remarks SysCaretWidth sets the width for the cursors used by Codewright Professional.

Parameter Descriptionpercent The width or the cursor as a percentage of the character cell width.

Fill begins at the left of the cell.

ReturnValue

SysCaretWidth returns the width of the caret that was previously in effect.

See Also SysCaretHeight

SysExit=<int exitcode>

Remarks SysExit terminates Codewright without performing any cleanup, such as saving buffersto output files and deleting temporary files.

Parameter Descriptionexitcode The termination code returned to the operating system upon exit.

This function represents an abnormal termination of the program.

SysQFlags

281

SysQFlags=

Remarks SysQFlags reports the state of various system-wide attributes. These settings may alsobe changed through the menu system and dialogs.

ReturnValue

This function returns a value that describes the status of various system-wide attributes.Each attribute is represented as a bit within this value. To facilitate analysis of thisvalue, a number of labels have been defined, representing the values of the respectivebits. These labels and a description of each are provided below:

Bit Label Meaning when setSYSFLAG_AUTOSAVE_ENABLED If an interval has been defined, buffers will be periodically

saved during keyboard inactivity.

SYSFLAG_CLIPBOARD Use the Windows clipboard for a staging area, instead of theCodewright Professional scrap buffers.

SYSFLAG_CMND_LINE_PROMPT Use the status line for prompting, rather than a pop-upwindow.

SYSFLAG_CONFIG_UPDATE Update the configuration file when exiting dialogs to reflectchanges made.

SYSFLAG_HIDE_BUTTON_MSGS Don't show descriptions on status lines when the mousepasses over the Tool Box.

SYSFLAG_HIDE_CURSOR Hide the mouse cursor when typing begins. The mousecursor returns when moved.

SYSFLAG_IBEAM_CURSOR Use an I-Beam style cursor in the text area.

SYSFLAG_RETAIN_DIR When using the File Open dialog, or otherwise browsing fora file, remember the last directory accessed and return to thatdirectory when next invoked.

SYSFLAG_SHOW_TOOLBOX Show the Tool Box at its last or default location.

SYSFLAG_TRAP_SYS_KEYS Process the Alt key and other system keys before Windowscan. This allows assignments to key combinations thatincluded these keys. The BRIEF key commands, forexample, require this.

SYSFLAG_UNDO_PAST_SAVE Rather than reinitializing the Undo information at each save,allow undo to the time the file was loaded.

All of these bits are read-write and may be set with the SysSetFlags function.

SysSetCwd

282

See Also SysSetFlags

SysSetCwd=<" cwd" >

Remarks SysSetCwd sets a new working directory for Codewright Professional. This directorybecomes the default for various dialog boxes. It does not affect Windows or otherapplications running concurrently.

Parameter Descriptioncwd A string, naming the directory that is to be made current. The

string may indicate a new drive as well as directory, and the pathmay be relative. Either forward or backward slashes may be usedto separate elements of the path.

Default value when parameter not suppliedcwdNIL

ReturnValue

SysSetCwd returns TRUE if the specified directory was successfully made the default.If the directory or path does not exist, the function returns FALSE.

SysSetDefault=<long defaultIndex>, <DWORD setting>

Remarks SysSetDefault allows changing the default settings for newly created buffers and editwindows. These defaults are stored in the model window and model buffer. Therefore,changing the settings of the current window or buffer does not affect them.

Parameter DescriptiondefaultIndex A value indicating which feature's setting to modify. A series of

labels have been defined for specifying which feature the requestpertains to. These labels correspond to features of the currentwindow or buffer. The labels are listed below:

SysSetFlags

283

LabelDEFAULT_BUFFER_AUTOINDENT_MODEDEFAULT_BUFFER_BACKUP_SPECDEFAULT_BUFFER_MAX_TABDEFAULT_BUFFER_MAX_VLINESDEFAULT_BUFFER_SYSFLAGSDEFAULT_BUFFER_TABSDEFAULT_COLOR_COMENTSDEFAULT_COLOR_DIFF_ADD_LINESDEFAULT_COLOR_DIFF_DEL_LINESDEFAULT_COLOR_INS_LINESDEFAULT_COLOR_KEYWORDSDEFAULT_COLOR_LINENUMBERSDEFAULT_COLOR_MOD_LINESDEFAULT_COLOR_SELECTIONDEFAULT_COLOR_TEXTDEFAULT_WINDOW_FONTDEFAULT_WINDOW_HINCDEFAULT_WINDOW_KEYMAPDEFAULT_WINDOW_LEFT_MARGINDEFAULT_WINDOW_SYSFLAGSDEFAULT_WINDOW_USERFLAGSDEFAULT_WINDOW_VIS_ELISIONDEFAULT_WINDOW_VIS_EOFDEFAULT_WINDOW_VIS_EOLDEFAULT_WINDOW_VIS_MARGIN_COLDEFAULT_WINDOW_VIS_SPACESDEFAULT_WINDOW_VIS_TABSDEFAULT_WINDOW_VIS_VIRTLINESDEFAULT_WINDOW_VIS_VIRTSPACES

setting This parameter may be either a numeric value or a string,depending on which default is being set.

Default value when parameter not supplieddefaultIndex setting

0 NIL

SysSetFlags=<DWORD flags>

Remarks SysSetFlags sets the system-wide Flags DWORD to a specified value.

Parameter Descriptionflags The value to assign to the Flags word.

SysSwapBlocks

284

The predefined labels for this flag and their meaning are given below:

Bit Label Meaning when setSYSFLAG_AUTOSAVE_ENABLED If an interval has been defined, buffers will be periodically saved

during keyboard inactivity.

SYSFLAG_CLIPBOARD Use the Windows clipboard for a staging area, instead of the

Codewright Professional scrap buffers.

SYSFLAG_CMND_LINE_PROMPT Use the status line for prompting, rather than a pop-up window.

SYSFLAG_CONFIG_UPDATE Update the configuration file when exiting dialogs to reflect changes

made.

SYSFLAG_HIDE_BUTTON_MSGS Don't show descriptions on status lines when the mouse passes over

the Tool Box.

SYSFLAG_HIDE_CURSOR Hide the mouse cursor when typing begins. The mouse cursor

returns when moved.

SYSFLAG_IBEAM_CURSOR Use an I-Beam style cursor in the text area.

SYSFLAG_RETAIN_DIR When using the File Open dialog, or otherwise browsing for a file,

remember the last directory accessed and return to that directory

when next invoked.

SYSFLAG_SHOW_TOOLBOX Show the Tool Box at its last or default location.

SYSFLAG_TRAP_SYS_KEYS Process the Alt key and other system keys before Windows can.

This allows assignments to key combinations that included these

keys. The BRIEF key commands, for example, require this.

SYSFLAG_UNDO_PAST_SAVE Rather than reinitializing the Undo information at each save, allow

undo to the time the file was loaded.

ReturnValue

SysSetFlags returns the previous setting of the flags.

See Also SysQFlags

SysSwapBlocks=<int lockedBlocks>

Tabs

285

Remarks SysSwapBlocks allows you to increase or decrease the number of memory blocksreserved by Codewright Professional. When Codewright Professional needs morememory than it has reserved, it swaps some blocks to disk. If Codewright Professionalseems to be swapping to disk too much, and more memory is available, you can improveperformance by increasing the number of reserved memory blocks. The initial default is20 blocks.

Parameter DescriptionlockedBlocks The number of 8K blocks to reserve (lock) for use by Codewright

Professional.

Default value when parameter not suppliedlockedBlocks

0

Tab=

Remarks Tab is the function normally assigned to the tab key. It not only inserts the tab characteron request, it also indents when a selection is defined.

See Also BackTab

Tabs=<" tabString ">

Remarks Tabs defines a new tab string for the current buffer. The tab string describes where tabstops occur by listing the column numbers at which tab stops are to be placed.

Parameter DescriptiontabString A string containing a list of column numbers at which tab stops are

placed. These column numbers are separated by spaces. If thisparameter is omitted, the function prompts for the tab string. If thetab string is invalid (e.g., does not begin with a number), thedefault value of "9 17" is used.

TagFind

286

Normally, all but the first one or two tab stops are implicit, rather than at explicitly namedcolumns. The interval between the last two explicit tab stops is repeated to the maximumcolumn allowed for tab stops, thus creating numerous implicit tab stops. If a single tabstop is listed, the interval between that tab stop and the beginning of the line is repeated.

TagFind=<" label ">

Remarks TagFind looks for the specified label in the "tags" data file. If the data file indicates inwhat file and at what line the label is defined, that file is loaded and the positiondisplayed.

Parameter Descriptionlabel A string containing the label to search for in the tags data file. If

this parameter is NIL the function uses the word at the cursorposition.

Default value when parameter not suppliedlabelNIL

Some setup is required for this function to work. Primarily, the name of the tags data filemust be defined with the TagSetFile function. TagFind works with CTags other Tagsdata files using the standard Tags format. Codewright does not maintain the Tagsdatabase. This job must be periodically performed by an external process.

Return Value TagFind returns TRUE if the tag definition was found in the data file. It returnsFALSE, otherwise.

See Also TagSetFile, TagIgnoreCase, TagPrompt

TagIgnoreCase=<BOOL igcase >

Remarks TagIgnoreCase indicates whether case is significant when searching for a label in aTags data file. This function is usually used in connection with Tags file setup.

TagSetFile

287

Parameter Descriptionigcase If this parameter is TRUE case will not be treated as significant. If

FALSE, case is significant.

Default value when parameter not suppliedigcase

(current state is toggled)

This function affects the searches performed by the functions TagFind and TagPrompt.It is usually used in conjunction with specifying the name of a data file, to match themethod in which tag definitions are stored in that file.

Return Value TagIgnoreCase returns the resulting state of this feature: TRUE when case is ignored,FALSE when case is significant.

See Also TagPrompt, TagFind

TagPrompt=

Remarks TagPrompt prompts the user for a label to search for in the Tags data file. If the datafile indicates in what file and at what line the label is defined, that file is loaded and theposition displayed.

Some setup is required for this function to work. Primarily, the name of the tags data filemust be defined with the TagSetFile function. TagPrompt works with CTags other Tagsdata files using the standard Tags format. Codewright Professional does not maintain theTags database automatically. This job must be periodically performed by an externalprocess.

Return Value TagPrompt returns TRUE if the tag definition was found in the data file. It returnsFALSE, otherwise.

See Also TagFind, TagSetFile

TagSetFile=<" fname ">

ToBottom

288

Remarks TagSetFile sets the name and directory of the Tags data file used in Tags searches.

Parameter Descriptionfname A string containing the path and complete filename of the file

containing the Tags definitions. This file must conform to thestandard Tags file format.

Default value when parameter not suppliedfnameNIL

The data file named is not validated until the first search is performed.

Return Value TagSetFile returns TRUE if the filename is found to be in valid format. If the filenamespecified is not a valid DOS path or filename, the function returns FALSE.

See Also TagFind, TagIgnoreCase, TagPrompt

ToBottom=

Remarks ToBottom scrolls the current line of the buffer to the bottom of the window. The cursorposition is not altered, relative to the text.

See Also ToTop

ToTop=

Remarks ToTop scrolls the current line to the top of the window. The cursor position is notaltered, relative to the text.

See Also ToBottom

Undo=

WinScrollHInc

289

Remarks Undo reverses the effects of the most recent edit operation or cursor motion. It prints amessage indicating that the edit has been undone, or prints "nothing to undo" if there areno further undos available. This function is intended for assignment to a key.

See Also Redo

Upper=

Remarks Upper converts all of the characters in the current selection to upper case. If noselection is defined, the function converts the entire line to upper case.

See Also Lower

Visibles=<int on >

Remarks Visibles turns on, off or toggles the display of special characters in place of otherwiseinvisible portions of the buffer. Such things as the end of file, end of line, spaces, tabs,and virtual space normally appear as undifferentiated blank space in a window. Thisfunction assigns more visible representations to these items. For example, a paragraphsymbol is used for end of line, and a dot for a space.

Parameter Descriptionon When non-zero, this parameter turns on the use of the visible

representations. When zero, it turns their use off. If the parameteris omitted, the feature is toggle to the opposite of its currentcondition.

See Also WinVisible...

WinScrollHInc =<long unit>

Remarks WinScrollHInc defines the number of columns that Codewright Professional scrolls leftor right when scrolling is required.

WinSetCreationPos

290

Parameter Descriptionunit The number of columns to shift the view each time horizontal

scrolling is needed. Negative values for this parameter cause thefunction to report the current setting without changing it.

Default value when parameter not suppliedunit0

The initial default is 3. The smaller this unit is, the more likely it is that more scrolloperations will have to be performed. This has the effect of slowing down the editingprocess.

ReturnValue

This function returns the new horizontal scroll incremental unit. If the parameter is anegative value, the function merely returns the current setting.

WinSetCreationPos=<int X>, <int Y>, <int width>, <int height>

Remarks WinSetCreationPos sets a default creation position for new edit windows.

Parameter DescriptionX, Y The coordinates, relative to the Upper lefthand corner of the client

area, at which the Upper lefthand corner of the window is placed.

The label CW_USEDEFAULT may be used for either or both of theseparameters, in which case a random value for that parameter ischosen by Windows each time a window is created.

width, height The extents in each dimension of the window.

The label CW_USEDEFAULT may be used for either or both of theseparameters, in which case a random value for that parameter ischosen by Windows each time a window is created.

Default value when parameter not suppliedX Y width height

CW_USEDEFAULT CW_USEDEFAULT CW_USEDEFAULT CW_USEDEFAULT

ReturnValue

WinSetCreationPos does not return a value.

WinVisible...

291

WinVisible...WinVisibleEOF=< int symbolic>WinVisibleEOL=< int symbolic>WinVisibleSeparator=<int symbolic>WinVisibleSpaces=<int symbolic>WinVisibleTabs=<int symbolic>WinVisibleVirtLines=< int symbolic>WinVisibleVirtSpaces=<int symbolic>

Remarks The WinVisible... functions allow you to specify printable characters to representvarious characters that are not otherwise visible. These functions effect only theappearance in the current window. The contents of the buffer is not effected.

Parameter Descriptionsymbolic The character which is to symbolize the non-printing character. A

value of -1 for this parameter causes the function to report thecurrent setting only.

Default value when parameter not suppliedsymbolic

-1

Below is a table of these functions and the aspects of appearance they control:Function DescriptionWinVisibleEOF A visual representation of where the buffer ends. Anything

beyond this marker is virtual space and virtual lines. Thereis no character in the buffer corresponding to this marker.

WinVisibleEOL A character to represent the newline sequence, whether thesequence is one character or two. Space to the right of thisis virtual.

WinVisibleSpaces A character to represent the space character within the text.WinVisibleTabs A character to represent the tab character within the text.WinVisibleVirtLines A character to represent lines beyond the end of the buffer.WinVisibleVirtSpaces A character to represent space beyond the end of lines and

the end of the buffer.

WinVisibleMarginColumn

292

ReturnValue

These functions return the character that was the previous setting.

See Also Visibles, SysSetDefault

WinVisibleMarginColumn =<int column>

Remarks WinVisibleMarginColumn draws a vertical line at a specified column, within thecurrent window. The line does not affect editing in any way, but can serve as a reminderfor those who must adhere to a line length standard.

Parameter Descriptioncolumn The column number at which the margin line is to appear. A zero

value disables this feature. A value of -1 for this parameter causesthe function to report the current setting, but not to change it.

Default value when parameter not suppliedcolumn

0

ReturnValue

WinVisibleMarginColumn returns the previous column setting.

WrapEnable=<int state>

Remarks WrapEnable selects one of three states for the Word Wrap feature.

Parameter Descriptionstate When this parameter is 0, the Word Wrap feature is turned off.

When a value of 1 is supplied, Word Wrap is enabled, but it onlywraps the current line. If typing into an existing paragraph, one ormore subsequent lines may require reformatting. When thisparameter is 2, the current line and all lines following in theparagraph are wrapped.

A series of labels has been defined for use with this function:

Label ValueWRAP_DISABLED 0

WrapSetRightMargin

293

WRAP_ENABLED lWRAP_CONTINUOUS 2

Default value when parameter not suppliedstate

0

A paragraph is defined as one or more lines of text surrounded by blank lines. Thisfeature relies on Auto-indent to maintain the whitespace margin you create on the left. Ittherefore turns Auto-indent on or off as necessary. The right margin is defined by thefunction WrapSetRightMargin , the Right Margin Mark, or the right edge of thewindow.

ReturnValue

WrapEnable returns the new state for the Word Wrap feature.

See Also WrapParagraph, WrapSetRightMargin, WinVisibleMarginColumn

WrapParagraph=

Remarks WrapParagraph formats the paragraph in which the cursor is placed to conform withleft and right margins.

A paragraph is defined as one or more lines of text surrounded by blank lines. Thisfeature relies on Auto-indent to maintain the whitespace margin you create on the left. Ittherefore turns Auto-indent on or off as necessary. The right margin is defined by thefunction WrapSetRightMargin , the Right Margin Mark, or the right edge of thewindow.

See Also WrapEnable, WinVisibleMarginColumn , WrapSetRightMargin

WrapSetRightMargin =<long margin>

Remarks WrapSetRightMargin sets the right-hand column after which text will wrap to the nextline, when the Word Wrap feature is enabled.

WriteBuffer

294

Parameter Descriptionmargin The column number that is the maximum width for text on a line

when Word Wrap is on. A value of 0 for this parameter tells WordWrap to use either the Right Margin Mark or the edge of thewindow as the right margin.

Default value when parameter not suppliedmargin

0

A paragraph is defined as one or more lines of text surrounded by blank lines. Thisfeature relies on Auto-indent to maintain the whitespace margin you create on the left. Ittherefore turns Auto-indent on or off as necessary.

ReturnValue

WrapSetRightMargin returns the new setting for the right margin.

See Also WrapEnable, WrapParagraph, WinVisibleMarginColumn

WriteBuffer =

Remarks WriteBuffer writes the currently defined selection, or the entire buffer to disk. If aselection is defined, the function prompts for a filename to which to write the contents ofthe selection. If no selection is defined, the function saves the entire buffer to its outputfile, if the buffer contains changes that have not been saved. The function prints amessage indicating whether the operation was successful.

See Also BufWrite, BufWriteSelection

ZoomWindow=

Remarks ZoomWindow zooms in or out on the current edit window, depending on its setting atthe time. If the window is maximized, the window is returned to its normal state. If thewindow is in its normal state, it becomes maximized.

Changing and Extending Codewright

In addition to being used in key assignments and .INI file entries, Codewright’s API functions canbe used to create programs in DLLs. When doing this, there are many more API functions that youmay employ which are not documented in this manual. They are instead documented online,where they can be explored more conveniently, using hypertext links and popups.

Codewright has been designed to be changed. The users of some applications may be content withthe response, "You can't do that," when inquiring about a certain capability of the program.Programmers, on the other hand, are much less apt to be content. Many of them just can't helpenvisioning how simple it would be to add this capability or change that. By making Codewrightextensible, we have come as close as we can to making this product all things to all people.

This chapter helps you with the three major steps you must take to change or add capabilities toCodewright:

• • It helps you find the source code that you want to change or add to.

• • It assists you in making the changes or additions you want to make.

• • It tells you how to compile and make use of the changes or additions you havemade.

System Overview

The first step in changing Codewright is to understand its anatomy. You can then move from thegeneral to the more specific, in locating the part of Codewright that you want to concentrate on.

The primary executable, CW.EXE or CW32.EXE, contains the Codewright ApplicationProgramming Interface (API). These are the functions and capabilities that are basic toCodewright's operation. Although you cannot rewrite the functions in the API, you can replacethem, in a limited fashion. We will discuss function replacement later. The point is, the sourcecode for main executable is not supplied.

External to the primary executable are several Dynamically Linked Libraries (DLLs) whichprovide services in several areas:

• Core services.

• Supplemental language support.

• Keyboard command sets.

Core Services

296

• Auxiliary services.

The following illustration depicts the organization of Codewright's software system:

Figure 1.: Overview of Codewright System Components

Core Services

The core services are those that Codewright always expects to have available. Some of theseservices are so essential that Codewright is unable to properly initialize without them. Forexample, you could use Codewright if no keyboard command sets were available -- you could evenbuild or find a keyboard command set. If the core services were missing, however, the keyboardcommands would be of no use.

CWSTART DLL

The CWstart DLL is named CWSTART.DLL. It performs numerous initialization tasks, such asloading other DLLs and reading the configuration file. The source code to CWSTART.DLL isprovided. Many of the extension functions are defined in this DLL. To utilize them in your own

Core Services

297

source code you will need to include the header file CWSTART.H, which is in Codewright'sCWSTART subdirectory.

The tree diagram and file descriptions below will help you locate the functions provided in thevarious source files.

ASM.C AUTOSAVE.C BRACE.C ERRORFIX.C

C.C COMPILE.C CURSOR.C ERRINFO.C

CPP.C CONFIG.C ENTAB.C

LANGUAGE.C CWSTART.C PREPROC.C

PAS.C DLGMENU.C PROMPT.C

FILTER.C REPEAT.C

OUTPUT.C SLIDE.C

STATE.C TABSET.C

UTIL.C TAGS.C

VCS.C

WWRAP.C

* Support for additional languages, such as Paradox and dBASE/Clipper, are contained in separateDLLs. These DLLs are Language Supplements, and their use is optional. See the "SupplementalLanguage Support" section below for a more complete description.

Language Features

File DescriptionLANGUAGE.C The file that contains the engine for language specific features, such as

ChromaCoding, Template Expansion, and Language Indenting. It relies on aseries of functions being defined elsewhere that incorporate the correspondingfilename extension into the function name (e.g., _c_indent(), _pas_indent() ).

ASM.CThis file contains the functions that support language specific features forassembly language source files (.ASM files).

C.C This file contains the functions that support language specific features for Clanguage source files (.C files).

Core Services

298

CPP.C This file contains the functions that support language specific features forC++ language source files (.CPP files).

PAS.C This file contains the functions that support language specific features forPascal language source files (.PAS files).

Utilities

File DescriptionAUTOSAVE.C Contains the functions in support of the Auto-save feature.COMPILE.C Contains the functions for the Compile, Make, and Rebuild selections on the

Project menu.CONFIG.C Contains the functions that read, write and process the configuration file.CWSTART.C The functions in this file initialize the CWSTART DLL.DLGMENU.C Contains the supporting functions for the Popup Menu defined by

CWRIGHT.MNU.FILTER.C Contains the functions that support the Filter selection on the Project menu.OUTPUT.C Contains the supporting functions for the tabbed Output Window.STATE.C Contains the functions that read, write and process the state file.UTIL.C Contains functions used by one or more of the keymaps and other shared

functions, such as NextWord /PrevWord.VCS.C Contains the functions supporting the Version Control submenu.WWRAP.C Contains the function in support of the Word Wrap and related features.

Error Parsing

File DescriptionERRORFIX.C This file contains the engine that drives the various error parsers for different

compilers and languages.ERRINFO.C This file contains the actual error parsers for the various compilers.

Macros

File DescriptionBRACE.C The source code file for the Codewright brace matching features, including

the functions Brace, BraceMatch and BraceMatchNext.CURSOR.C This file contains functions to make and support mouse assignments and

operations.ENTAB.C The functions that support entabbing and detabbing the current buffer are

contained in this file.PREPROC.C Contains the functions in support of the Preprocess function.PROMPT.C This source file contains the prompting functions and supporting functions

that use the prompt history facility.

Keyboard Command Sets

299

REPEAT.C Contains the source code for the function Repeat, which repeats a command aspecified number of times.

SLIDE.C Contains the functions for moving a block of text in or out.TABSET.C Contains the functions supporting setting tabs, including extension specific

settings.TAGS.C The source file for the functions that support the CTags features.

CWDIALOG DLL

The CWdialog DLL is one of the DLLs that is loaded during initialization. The name of this file isCWDIALOG.DLL. This library contains the dialog functions that support the menuing and otherinteractive operations. The source code for the CWdialog DLL is also supplied.

There are a number of functions in this DLL that allow you to access the dialogs on the menudirectly. It is sometimes useful to assign these functions directly to keys, or to call them from yourown source code. These functions are the functions beginning with Dlg... and Print . To use thesefunctions, just include the file CWDIALOG.H into your C source code. You will find this file inCodewright's CWDIALOG subdirectory.

CWHELP DLL

The CWhelp DLL contains the functions that access the various Help libraries used byCodewright. These include the contextual help for the editor, the Codewright API function help,and the Microsoft Windows API (SDK) help, if you have it. The name of the DLL isCWHELP.DLL.

If you want to call the function cwhelp from your C source code, you will need to include the fileCWHELP.H in your file. This header file is located in Codewright's CWHELP subdirectory.

Keyboard Command Sets

Codewright is supplied with four keyboard command sets, also called keymaps. They are: CUA(Common User Access), BRIEF emulation, Epsilon emulation, and VI emulation. Each iscontained in a separate DLL. The C source code files and makefiles are included for each of theseDLLs. Unless you have elected not to install portions of the source code, each set of source codehas been installed in its own subdirectory.

Supplemental Language Support

300

The first of these contains the Common User Access or CUA command set. This command setconforms to Windows standards whenever possible. It is contained in the file CUA.DLL.

The second command set is fashioned after the DOS programmer's editor, BRIEF, originally fromUnderWare, Inc. It does not conform to Windows standards, but is itself something of a standardfor programmers. It is supplied in the file BRIEF.DLL.

The third command set is an emulation of the Epsilon editor, which is an adaptation of Emacs fromLugaru. This keymap does not conflict with Windows standards as directly as the BRIEFemulation does, but neither does it support Windows standards.

The forth command set is an emulation of the Unix editor, vi. There are somewhat differentflavors of this editor in use. We have attempted to support the common features of these. Youwill find this support in VI.DLL

Supplemental Language Support

In addition to the support for C/C++, Pascal, HTML, and assembly language built into theCWSTART DLL, support is provided for other languages in separate DLLs. The source code forthese DLLs is provided.

Here is a description of the language support DLLs provided:

DLL DescriptionPRG.DLL This DLL contains the functions that support language specific features for

dBASE and Clipper language source files (.PRG files).SC.DLL This DLL contains the functions that support language specific features for

Paradox PAL source files (.SC files).COB.DLL This DLL contains the functions that support language specific features for

COBOL source files (.COB files).BAS.DLL This DLL contains the functions that support language specific features for

Visual Basic for Windows (.BAS files).CWHTML.DLL This DLL contains additional support for the HTML language, including a

split window viewer.CWJAVA This DLL contains the functions that support language specific features for

JAVA source files.

These DLLs are not automatically loaded, as is CWSTART.DLL. You will need to use theLibraries dialog on the Tools menu. It adds a statement to your Codewright configuration file(CWRIGHT.INI). Here are example load statements for these DLLs:

Auxiliary Services

301

[LibPreload]LibPreload=PRG.DLLLibPreload=SC.DLLLibPreload=COB.DLLLibPreload=BAS.DLL

The statements above load the DLLs and make the functions in them immediately available foruse. This does have the effect of slowing the initial loading of Codewright. An alternative is touse LibAutoLoad rather than LibPreload. This will cause the DLLs to be loaded only ondemand. It does, however, require listing all of the function in the DLL in the statement. See thedescription of this function for details.

Auxiliary Services

The Auxiliary Services or DLLs provide support for supplemental features. These features orgroups of features are generally provided in separate DLLs. The source code for each DLL, ifprovided, is in a subdirectory within Codewright's home directory. Each subdirectory is given aname that is the same as the root name of the DLL.

These Features or DLLs are add-on packages that may not be required by every user. Like theadditional language support DLLs, they may require a little setup to use. They are generally notloaded automatically.

DLL DescriptionCWLDRAW.DLL This DLL allows remapping the keyboard so that you can draw lines and

boxes in your file, using the IBM OEM character set. You must be usingOEMfixed, 8514oem, terminal, or similar font. If not, these lines will bedisplayed as international characters. It is not loaded automatically.

CWREDIT.DLL This DLL provides the user with the ability to edit the Tool Ribbon andSideBar interactively. It supports the Tools/Toolbars Editor menuselection.

CWDIFF.DLL This DLL contains the support for Codewright's differencing feature. Itallows side-by-side differencing of files or buffers, in addition to singlebuffer difference analysis.

CWFOPEN.DLL This DLL supports the File Open mode of the Codewright SideBar.CWDDE.DLL This DLL contains the functions that turn Codewright into a DDE server.

Other applications can then operate Codewright remotely to performsyntax checking, Lint, and Tags database updating. The DLL is notloaded automatically.

CWBROWSE.DLL This DLL contains the main support for Codewright's Browser. ThisDLL is loaded automatically, when needed.

Dissecting a Codewright DLL

302

CWTAGS.DLL This DLL supports the use of Premia compiled Tags databases with theBrowser. It is loaded as needed.

CWBSC7.DLL This DLL supports the use of Microsoft Browser databases (C/C++V7.0+) with the Browser. It is loaded as needed.

CWWEB.DLL This DLL supports loading files edited in Codewright into various Webbrowsers. It is not loaded automatically.

Sample DLL

The source code for an essentially empty DLL has been included. You will find it in the SAMPLEsubdirectory in the Codewright home directory. You can put some flesh on this skeleton, or youmay use it as an example of what elements go in to a Codewright DLL.

The source code for SAMPLE.DLL is a skeleton of comments and function stub or two. Thecomments show you where to insert additions or changes that you want to make to Codewright.These insertions might include:

• • Loading other DLLs, possibly written in a programming language other than C.

• • Adding event handlers.

• • Setting defaults, much as you would in the configuration file.

• • Adding key commands.

• • Writing and installing replacement functions.

A makefile is also included for the this DLL.

Dissecting a Codewright DLL

Your compiler imposes certain requirements in order to correctly produce a Microsoft Windowscompatible DLL. In addition to those requirements, there are a few essentials required byCodewright. This section will help you understand what is required and why.

Let's take apart a Codewright DLL and see what is typically there.

The _init Function

Whenever Codewright loads a library, it executes that DLLs _init function, if the library has one.This is the function you use for initializing the DLL and letting Codewright know what functions

Making Changes and Additions

303

the library has to contribute. Generally, this function consists of a series of LibExport functioncalls, which export the functions defined in that DLL for use by other entities in Codewright.

Exporting Functions

The functions in a DLL, and the parameters for each, must be registered with Codewright beforeyou can make full use of them. If you don't register them with Codewright, you will not be able toassign them to a key or call them from the API Command Key. You register or export thefunctions with the LibExport function. This is in addition to any export declarations required bythe programming language.

This requirement is a result of the use of Pascal calling conventions. When using Pascal callingconventions, the program stack would become unbalanced if any function parameters wereomitted. Yet, the function LibFunctionExec, which services the API Key and the keyassignments, has no way of knowing the type and number of parameters are required unless youtell it. The LibExport function does this.

Note: If you change the number or type of parameters in a DLL function, you mustremember to change the corresponding LibExport call that registers that function.

Making Changes and Additions

When you have determined that you are going to modify Codewright's source code, you have twoapproaches available to you. You can change existing functions or add new functions to thesystem.

Changing Existing Functions

Changing an existing function is often the best way to go, if your change is small and you want thechange to be reflected whenever a certain function is called. This usually avoids the need to createor change a LibExport call.

For example, you might want to change the function that moves the cursor ahead in increments of aword. You can be relatively certain that this function is going to be called as the result of somekey command.

If you were less certain about what other routines might be using the function, you would need toconsider the effects of your changes on those other routines. If you are in serious doubt about whatroutines may be relying upon the function, it is best not to change it. Instead, create a new functionthat is called when you want it, and leave the old function in place for the routines that use it.

Creating New Keymap Command Sets

304

Adding Your Own Functions

When adding your own functions, you must be sure that they are declared in the same manner asother Codewright functions. You won't be able to assign your functions to keys, call them from theAPI Command Key, and other useful things, unless you properly export your functions toCodewright. This means using LibExport .

If you create a new file for your functions, you will have to be sure it uses the necessary headerfiles (CWSTART.H, CWDIALOG.H, CWHELP.H...), and that it is included in the compile andlink.

There is a macro defined in EXPORTS.H that simplifies defining new functions for Codewright,when programming in C. Just define your function as DLL and it is automatically declared asPascal calling conventions, exported, and so forth. Here is an example of its use:

void DLLKeyNotInUse( void ) {

SysBeep();MsgWarning( "Unassigned key" );

}

Windows NT also requires that all functions be added to the .DEF file in order to be properlyexported. Just edit this text file and add your function name to the end of the existing list. Alsonote that NT is case sensitive in function names, whereas Windows is not.


Keymaps have additional requirements over and above those of a Codewright DLL. This sectionwill walk you through the basic outline of a keymap.

Keymap _init Function

Like the _init function for any other Codewright DLL, the Keymap's _init function typicallycontains a series of LibExport calls that make functions available to the outside Codewrightworld. This is necessary for any functions you create to assign to keys within the keymap.

Normally, the _init function does not install the keymap. If it did, you would not be able to loadthe DLL to have access to its functions without loading the keymap.


305

Keymap Function

The keymap function is the function that creates and installs the new keymap. To be compatiblewith the DefaultKeymap function, this function must have the same name as the root of the DLLin which it resides. For example, the CUA keymap is in the file CUA.DLL and is installed withthe cua function. If you are creating an EMACS keymap in EMACS.DLL, name the keymapfunction emacs().

Flag Initialization

One of the first things you will want to do in your keymap function is to set options the way usersof your keymap will expect to find them. For example, the Brief keymap needs to allowassignments to Alt keys, and doesn't create a new window for each new file that is loaded. If theusers of your keymap will expect to have vertical and horizontal scroll bars on their edit windows,now is the time to make that happen.

There are several functions that will assist you in setting the options you require. They are:SysSetFlags, SysSetDefault, and SrchSetFlags. Use SysSetFlags to set options you mightotherwise set from the System Options dialog. To set up window and buffer settings the way youwant, even before any buffers or windows have been created, use SysSetDefault. To set thedefault search settings, use SrchSetFlags. You will find these functions described further in thesecond part of this manual.

You are not dictating with these settings how a user must operate. The settings you create heremay be overridden by settings stored in the configuration file or state file.

Basic Assignments

When you create a new keymap, it is empty -- and we mean really empty. The only keys or mouseactions that will work are those that Codewright lets Windows process. This includes menus,+7, +;, +� and such. If you want pressing the A key to produce and A in a buffer,

you need to make that key assignment.

There are functions provided to take the drudgery out of making these assignments.KmapAssignTypables and KmapAssignRange are your primary assistants. The differencebetween these two functions is that the first makes assumptions about what you want the keys todo, whereas the second allows you to specify the function that is assigned to the keys.

Recompiling a DLL

306

Keymap Specific Assignments

Now you are ready to make assignments specific to your keymap. Your main tool in doing thiswill be the function KmapAssign. Use the Codewright API functions, or create your ownsupporting functions to assign to keys. Remember that when you create your own functions youwill need to export it with a LibExport call in the DLL's _init function in order for the keyassignment to work. Otherwise, you will get a "function not found" message when you press thekeystroke.

Menu Accelerators

The last step in creating your own keymap is to put strings indicating any "short cut" keys oraccelerators on the menu. You will rely on the MenuAddKeyString function to do this.

Recompiling a DLL

Part of the Codewright directory structure is a miniature of that used by most C compilers. Thereis an INCLUDE subdirectory that contains header files, a LIB subdirectory to contain .LIB files,and subdirectories to contain the source code for each of the Codewright DLLs you can rebuild.The INCLUDE and LIB subdirectories must be made known to your compiler and linker. You cando this manually, or through the use of a MAKE utility or Project file, if your compiler supportsthese things.

Using and Modifying the Makefiles

There are two makefiles supplied for each of the DLLs that you can modify to suit your specificneeds and desires. The makefiles are installed in each subdirectory that contains DLL source code.One makefile is a Microsoft makefile and the other is a Borland makefile.

The primary things that makes these files specific to one compiler or another are the compile andlink command lines that they employ. If you are using some other compiler, you should findadapting it to your compiler is a straight forward task. You can recognize the Microsoft makefileby looking for the file with no extension that has the same root name as the DLL it makes. TheBorland makefile uses the same name, except that the extension used is .MAK.

The same makefiles are used for generating 32 bit DLLs as for generating 16 bit DLLs. If youhave the environment variable CPU defined this is normally sufficient to cause the Microsoftmakefile will generate a 32 bit DLL. You may also cause a 32 bit DLL to be generated forBorland or Microsoft by defining a macro named WIN32 at the beginning of the makefile:

Recompiling a DLL

307

WIN32=TRUE

The DLLs themselves are generated in either a WIN16 or WIN32 subdirectory of the source filedirectory, depending on which platform you are compiling for. You will then need to move theDLL up to the Codewright executable directory for it to be used.

The Borland compiler relies on configuration files and command line switches to locate includefiles and libraries, rather than environment variables. As a result, it may be necessary to modify amacro definition in the Borland makefile to indicate the location of these files, unless you haveinstalled the Borland compiler in the default directory of C:\BC45. If you have installed yourBorland compiler in another location, modify the value assigned to BORPATH toward thebeginning of the makefile. For example, if you installed the compiler in the directory D:\BC45,change the assignment to read as follows:

BORPATH=D:\BC45

Adding FilesGroups of related files have been defined as macros toward the beginning of each makefile. Thisfacilitates operating on the filenames as a group. Also, if you choose to place the source code forsome extensions to Codewright in a separate file, you can readily add those filenames to the macrodefinitions. If the makefile employs a linker response file, such as CWSTART.LNK, don't forgetto add your file to the list in the response file so that it will get linked in.

Compile and Link Options

The compiler options you use for compiling Codewright DLLs are largely the same as you woulduse for compiling any Microsoft Windows DLL. Codewright DLLs must be compiled using LargeMemory Model. If you specify your include directories on the command line, be sure to includethe Codewright CWSTART and INCLUDE subdirectories in your command. You will find thatthis has been done for you in the makefile.

Similar requirements apply to your Link command. Begin with your basic Link command line forproducing a Windows DLL. The libraries in Codewright's LIB subdirectory must be linked withthe other objects. A standard .DEF file has been supplied for each DLL.

Link Libraries

The makefiles provided reference certain libraries in the linker command. You may find it usefulto know the purpose of each of these libraries in case you have a different version of the samecompiler or would like to construct a similar command line for a compiler not supported.

Recompiling a DLL

308

Microsoft LinkThis is the command line in the makefile for Microsoft C invoking the linker:

link /NOD $(LIBDIR)\libentry @cwstart.lnk, $(DLLDIR)\cwstart.dll,,libw oldnames \

ldllcew $(LIBDIR)\cwright,cwstart.def

The libraries used in this link command are LIBW.LIB, OLDNAMES, LDLLCEW.LIB, andCWRIGHT.LIB. Of these, the files LIBW.LIB and CWRIGHT.LIB are import libraries. Theydon't contain any object code themselves, but rather tell where the routines may be accessed atruntime. LIBW.LIB points to addresses in USER.EXE, GDI.EXE and other executables thatprovide the Windows API. CWRIGHT.LIB points to addresses in the Codewright kernel thatsupport the Codewright API.

You may need to link in other import libraries at times, for example, if you are making direct callsto routines in CWSTART.DLL, CWMATCH.DLL or a DLL of your own creation. If you don'thave an import library (.LIB) file corresponding to the DLL you are using, you can create one withthe ILIB utility supplied. ILIB is described a little later in this chapter.

The library LDLLCEW.LIB contains object code to use when creating Large memory modelWindows DLLs. Depending on your installation of Microsoft C, you may find that your Largememory model library is named LDLLCAW.LIB instead. Alternately, you may find that you havenot installed any large model library at all. If so, you can run the setup program that came withyour compiler to add to your installation. If you use a library intended for any other memorymodel you are guaranteed to have a program that doesn't work right, and will probably crashWindows.

The library OLDNAMES.LIB is included to avoid unresolved externals. This is becauseMicrosoft changed the names of some of their library routines. See your MSC 7.0 README filefor details. If you are using an older version of the Microsoft compiler, you should remove thislibrary from your command line.

Borland LinkBelow is a portion of the input script for TLINK in the makefile for Borland C/C++:

..\lib\cwright.lib+import.lib+cwl.lib

The purpose of these libraries follows closely the libraries described above for Microsoft. Thelibraries CWRIGHT.LIB and IMPORT.LIB are import libraries. IMPORT.LIB is supplied to youby Borland for the Windows API and CWRIGHT.LIB comes from Premia for the CodewrightAPI.

Using Your Own DLL

309

You may need to link in other import libraries at times, for example, if you are making direct callsto routines in CWSTART.DLL, or a DLL of your own creation. If you don't have an importlibrary (.LIB) file corresponding to the DLL you are using, you can create one with the ILIB utilitysupplied. ILIB is described a little later in this chapter.

The third library CWL.LIB contains object code to use when creating Large memory modelWindows DLLs. This library was named CWINL.LIB in versions prior to 3.0. Use only a Largememory model library intended for Windows for this purpose.

Using Your Own DLL

There are several reasons that you may have for wanting to use a DLL that you have developed onyour own, rather than modifying one of those supplied. It is expected that if you write a newcommand set for the keys that you will place it in a separate DLL. You can then use theDefaultKeymap function to facilitate loading the DLL and calling the keymap subroutine thatmakes the key assignments.

You may find it more convenient to develop a DLL with Borland Pascal for Windows, orMicrosoft's Visual Basic than to modify an existing C language DLL. Alternately, you may just beconcerned about how well your C language additions will coexist with the source code provided.

Your DLL will need all of the same parts described in the "Dissecting a Codewright DLL" sectionabove, regardless of what language you use to produce it. Be sure to compile using a Largememory model. You need Far calls and pointers for things to work properly.

Installing Your DLL

When you are ready to use your DLL, you need only reference it in the proper section of yourconfiguration file. If your DLL is a keymap and supporting functions, just change the nameassigned to DefaultKeymap to the basename of the DLL file; if your DLL is namedMYKEYS.DLL, change the statement to read DefaultKeymap=mykeys under the[DefaultKeymap] section.

If your DLL just contains some additional subroutines you want to have available, you have acouple of options:

• • Always load the functions at startup-time

• • Tell Codewright to load them when needed.

The first option may slow down the initial loading of Codewright, whereas the second can cause ashort pause when the function is first called. The second option may be better if you have a

Using Your Own DLL

310

nominal amount of memory installed. If you have a fast CPU and hard disk, you probably won'tnotice much difference in daily use.

The following examples assume that you have put your DLL in Codewright's home directory, or ina directory that your CWLIB environment variable points to. The first loads the DLLimmediately, while the second loads it only when needed. Place only one of these commands inyour configuration file, under the [Editor] section heading:

LibPreLoad=mydll

LibAutoLoad="mydll func1 func2"

The second option, loading the DLL only as needed, requires that you supply more information.You must supply the names of the functions in the DLL which may be called. For moreinformation on configuration files, refer to the "Configuration and State" chapter in the first part ofthis manual..

Index

311

##Ifdefs, 58

((File) Open Window, 43

__init , 305_init Function, 307

332 bit disk and file access, 50

AAdd to User Dictionary

Spell Correction Dialog, 22Adding Your Own Functions, 307Additional Language Support, 303Alternation And Grouping, 134Anchors. See BookmarksAPI Assistance, 1API Assistant, xiv, 65

Automation Tools, 2checkboxes, 2Modifying the Database, 2using, 1

API Database Editor, 2ASM.C, 300assembly language, 303AssignMouseKeys, 191Associated Dialogs, 50AttrFindColor , 169AttrQColor , 169AttrSelColor , 169AttrSetColor , 169

AttrSetPaletteEntry , 169, 170, 191Auto-Expand/Collapse, 47auto-indent

fill mode, 200set mode, 200

Auto-save, xiii, 154, 155, 192, 206Autosave, 191AUTOSAVE.C, 300AutosaveDir, 192AUTOTOOL.TXT, 3Auxiliary Services, 304

BBackTab, 192Backup

set file name/locationglobal, 203

set file name/location, 201Backup files, 80, 138, 139, 162, 202, 203Backup Files And Directories, 138Backup Formatting Strings, 139Backup specification, 202, 203Backup Specs

Illustrative Examples, 141BlockCopy, 193BlockCut, 193Bookmark Window, 47Bookmarks, 79

Global, 47Bookmarks Window, 43, 47Borland, 156Borland Link, 311Borland Pascal, 312Borland’s Delphi, xiiiBORPATH, 310BR_adjacent_window, 81BR_attach, 81BR_backspace, 81BR_beginning_of_line, 81

Index

312

BR_borders, 81BR_copy, 81BR_create_edge, 81BR_cut, 81BR_del_to_BOL, 82BR_delete, 81BR_delete_curr_buffer, 82BR_delete_edge, 82BR_delete_macro, 82BR_drop_bookmark, 82BR_edit_file, 82BR_end_key, 82BR_end_of_buffer, 82BR_end_of_line, 82BR_end_of_window, 82BR_esc, 82BR_exit, 82BR_goto_bookmark, 82BR_home_key, 82BR_left_side, 83BR_load_macro, 83BR_mark, 83BR_open_line, 83BR_playback, 83BR_print, 83BR_quote, 83BR_read_file, 83BR_remember, 83BR_right_side, 83BR_search_again, 83BR_search_back, 83BR_search_case, 83BR_search_fwd, 83BR_set_backup, 83BR_set_mode, 84BR_tab, 84BR_toggle_clipscrap, 84BR_toggle_re, 84BR_top_of_buffer, 84BR_top_of_window, 84BR_translate, 84BR_translate_again, 84BR_translate_back, 84BR_translate_fwd, 84

BR_write_and_exit, 84Brace, 193

placement in templates, 241Brace Matching, 55BRACE.C, 300BraceFind, 57BraceMatch, 57, 193Bracematch, 57BraceMatchNext, 57, 194Brief, 14, 142, 143, 155, 157BRIEF, 60, 75Brief Keymap Functions, 81Browse, 49Browser

Filter Toggle Buttons, 8Inspect window, 5Jump to Code, 6Query Buttons, 7Ribbon, 6Selecting a Database, 5String Search, 6Traversing the Tree, 5Tree window, 5Window, 4

Browser and Tags Support, 3Browser ribbon, 5Browser Support, 4Browser tree

expand or collapse, 5browsing, xiv, 3

Outline Symbols, 10Supported File Types, 11using Microsoft .BSC files, 3

BSC file, 5BSCMAKE, 5BufBackspace, 195BufDelChar, 195BufDelLine, 196BufDelSelection, 196BufDelToEOL , 197BufEditFile , 197Buffer

current, 79filter dialog , 222

Index

313

settings dialog, 222Buffer save dialog, 222BufInsertChar , 198BufInsertEOL , 200BufInsertEOL , 198BufInsertFile , 199BufInsertScrap, 199BufInsertStr , 200Bufqbackupspec, 138Bufqglobalbackupspec, 138BufQMaxTabCol, 204BufQTabStr , 204BufSetAutoIndentMode, 200BufSetBackupSpec, 201Bufsetbackupspec, 138BufSetGlobalBackupSpec, 203Bufsetglobalbackupspec, 138Bufsethexascii, 145BufSetMaxTabCol, 204Bufsetsysflags Function, 138BufSetTabStr, 204, 248BufSetTabUsage, 204BufWrite , 205, 206BufWriteFile , 205BufWriteSelection, 206Bugs, 172Build, 49Button Link

Deleting, 14Button links, 12

Comment prefixes, 12Defining buttons, 12How it works, 12View Links, 13What you see, 12

buttons, 12action, 12

CC Language Operators, 145C Language Support, 55C.C, 300Called By, 8

Calls To, 8Carriage Return, 131CenterLine, 206Change directory dialog, 222Changing Existing Functions, 306Character Classes, 131Character Matching, 131Check Document Button

Spell Check Dialog, 21Check In Command, 117Check Out Command, 118Check Word Button

Spell Check Dialog, 21CheckIn, 207Check-in Dialog, 209CheckInBuffer , 208CheckInSetCmd, 209CheckOut, 209Check-out Dialog, 212CheckOutBuffer, 211CheckOutSetCmd, 212ChromaCode, xiiiChromaCoding, 231, 232, 300

language dependent, 229setting update delay, 242speeding up, 233

ChromaCoding, 232Clipboard, 17, 213, 268, 284, 287

define separator string, 213separator string enable, 213

ClipboardEnableSepStr, 213ClipboardSetSepStr, 213Closed Selections, 14Codewright API, 142Codewright Api, 143Codewright CUA Variant, 61Color Settings

Predefined, 169Color value

set for Codewright palette, 191Color..., 215ColorAlternate..., 169ColorCommandLine, 169, 214ColorComments, 215

Index

314

ColorDiffAdd , 215ColorDiffDel , 215ColorError , 169, 216ColorInsertedLines, 215ColorKeywords, 215ColorLineNumbers, 169, 215ColorMessage, 169, 216, 267ColorModifiedLines , 215Colors

warning messages, 217window dialog, 222

ColorSelection, 169, 215Colorselection, 155ColorSetPallete, 218ColorText, 169, 215Colortext, 155ColorWarning , 169, 217Column Marking, 15Column Selection, 15Command Completion, 142Command Key, 58, 59, 141, 142, 143, 144, 145,

150, 156, 162, 168Displaying Return Values, 144examples, 144

Command Linecommand files, 168Flags, 163Parameters And Options, 163

Command Line Parameters, 163Command lines, 209, 212, 214, 227command shell

in child window, 50Comment length

optimizing for ChromaCoding, 233Comments, 193, 231Common Dialogs, xiiiCommon User Access, 60Compact mode, xiii, 57, 65, 67, 80Compile and Link Options, 310COMPILE.C, 300CompuServe, 171Conditional code, xiii, 58, 156

Definitions Used In, 58CONFIG.C, 300

ConfigFileRead, 218Configuration

Example File, 154Configuration and State

introduction to, 153Configuration File, xiii, 58, 152, 153, 155, 156,

161, 163, 164, 165, 167, 218, 248, 249Execute section in, 218User Defined Sections, 158

Configuration Hierarchy, 128Contents Of The State File, 161Copy, 193Core Services, 299Correct All button

Spell Correction Dialog, 22Correct button

Spell Correction Dialog, 22CPP.C, 300Creating a Project, 122Creating Definitions, 58Creating New Keymap Command Sets, 307Creating Windows With A Mouse, 17CTags

setup, 289, 291CTags, 289, 290Ctags Support, 9Cua, 14, 60, 142, 157CUA, 60, 75CUA Key Commands, 60CUA Variant, 61CUA_attach, 69CUA_auto_indent, 69CUA_back_tab, 69CUA_backspace, 69CUA_copy, 69CUA_cut, 69CUA_delete, 69CUA_delete_curr_buffer, 70CUA_delete_curr_window, 70CUA_deletion, 68, 70CUA_drop_bookmark, 70CUA_edit_file, 70CUA_edit_next_window, 70CUA_edit_prev_window, 70

Index

315

CUA_enable_virtual, 63CUA_end_of_buffer, 70CUA_end_of_window, 70CUA_exit, 71CUA_goto_bookmark, 71CUA_left_side, 71CUA_make_window_icon, 71CUA_mark, 71CUA_motion, 68, 71CUA_mouse, 68CUA_mouse, 71CUA_mouse_selextend, 71CUA_next_winbuf, 71CUA_open_line, 71CUA_playback, 72CUA_QPersistSel, 72CUA_quote, 72CUA_read_file, 72CUA_remember, 72CUA_right_side, 72CUA_search_again, 72CUA_search_back, 72CUA_search_fwd, 72CUA_sel_persist, 73CUA_selection, 68, 72CUA_self_insert, 73CUA_shiftpage, 73CUA_tab, 73CUA_tab_use, 73CUA_toggle_clipscrap, 73CUA_top_of_buffer, 73CUA_top_of_window, 73CUA_translate, 73CUA_translate_again, 73CUA_translate_back, 74CUA_translate_fwd, 74CUA_write_and_exit, 74Cursor

Placement After Search, 136CURSOR.C, 300Customization, xii, xiii, 143Cut, 193CW CUA, 61CW32.EXE, 152

CWBUTTON.BTN, 43CWDDE.DLL, 304CWDIALOG DLL, 302CWDIALOG.H, 302, 307CWHelp, 219CWHELP.H, 307CWHelpDefaultName, 219CWINL.LIB, 312CWL.LIB, 312CWLDRAW.DLL, 146, 304Cwpst, 161Cwright.Ini, 161, 303Cwright.Ini, 164CWRIGHT.LIB, 311CWRIGHT.PST, 167Cwrightini, 164CWSTART DLL, 299CWSTART.DLL, 303, 312CWSTART.H, 300, 307cwvdos.386, 51

DdBASE/Clipper, 300Debugging, 145Default

Backup Specification, 139Function Parameters, 144Keymap, 158Keymap, 165

Default font dialog, 222DefaultKeymap, 220, 312Defines

creating, 58Definitions

Creating, 58Delay

ChromaCoding update, 242DeleteNextWord, 220DeletePrevWord, 220Dialog

change directory, 222default font, 222file differencing, 222

Index

316

file find , 222file grep, 222file open, 222filter utility , 222go to line, 222go to mark, 222merge, 222multi-buffer search, 222print , 222print setup, 222save as, 222set mark, 222Spell Correction, 22window colors, 222window font, 222window settings, 222

Dialogsbuffer save, 222buffer settings, 222Extension-specific Setup, 222key bindings, 222

DICT.APP, 20DICT.D, 20DICT.I, 20DICT.S, 20DICT.U, 20dictionary files, 20Difference, 49Differencing dialog, 222directory

set working, 285Directory change dialog, 222Disabling Virtual Space, 62DisplayFileName, 221Displaying Return Values, 144Dissecting a Codewright DLL, 305DlgFGrep, 247DlgMenuExec, 223DlgMenuPopup, 223Dll

Source Code, 143Dockable Toolbars

manually dock and undock, 42Dockable Toolbars and Windows, 41

dockable windows, 43Document Languages dialog, 54Document Settings, 53Document_Backup Attribute, 138Drag and Drop

Copy, 16File Loading, 18Move, 16Text, 16

Drag and Drop, xiii

EEditNextBuffer , 224Editor Highlights, 1EditPrevBuffer , 224EdVersion, 224Elision, xiii, 57, 286email, 171End of file, 292Environment Dialog, 18Environment variables, 227, 253, 254Environment Variables, 161EPSAltPrefix, 100EPSAppendNextKill, 100EPSArgument, 100EPSAutoFillMode, 100EPSBackwardCharacter, 100EPSBackwardDeleteCharacter, 101EPSBackwardKillWord, 101EPSBackwardParagraph, 101EPSBackwardSentence, 101EPSBackwardWord, 101EPSBeginningOfLine, 101EPSBeginningOfWindow, 101EPSBindToKey, 101EPSBufed, 101EPSBufferInit, 101EPSCapitalizeWord, 102EPSCd, 102EPSCenterLine, 102EPSCenterWindow, 102EPSChangeModified, 102EPSCopyRegion, 102

Index

317

EPSCopyToFile, 102EPSCountLines, 102EPSCtrlPrefix, 102EPSCtrlXTable, 103EPSDeleteBlankLines, 103EPSDeleteChar, 103EPSDeleteCharacter, 103EPSDeleteHorizontalSpace, 103EPSDired, 103EPSDownLine, 103EPSEndKbdMacro, 103EPSEndOfLine, 103EPSEndOfWindow, 103EPSEnlargeWindow, 104EPSEnlargeWindowHorizontally, 104EPSEnlargeWindowInteractively, 104EPSEnterKey, 104EPSExchangePointAndMark, 104EPSExit, 104EPSExitLevel, 104EPSFillParagraph, 104EPSFindFile, 104EPSForwardCharacter, 105EPSForwardParagraph, 105EPSForwardSentence, 105EPSForwardWord, 105EPSGotoBeginning, 105EPSGotoEnd, 105EPSGotoLine, 105EPSGotoTag, 105EPSGrep, 105EPSHelp, 105EPSHighlightRegion, 106Epsilon Key Commands, 91Epsilon Keymap Functions, 100EPSIncrementalSearch, 106EPSIndentPrevious, 106EPSIndentRegion, 106EPSIndentRigidly, 106EPSInsertChar, 106EPSInsertEOL, 106EPSInsertFile, 106EPSInsertToColumn, 106EPSJumpToLastBookmark, 107

EPSJumpToNamedBookmark, 107EPSKillBuffer, 107EPSKillLevel, 107EPSKillLine, 107EPSKillRegion, 107EPSKillSentence, 107EPSKillWindow, 107EPSKillWord, 107EPSLastKbdMacro, 107EPSLoadBytes, 108EPSLowercaseWord, 108EPSMake, 108EPSMarkParagraph, 108EPSMaybeBreakLine, 108EPSMouseLeftButtonDown, 108EPSMouseRightButtonDown, 108EPSMouseRightButtonUp, 108EPSMouseRightClick, 108EPSMoveToWindow, 109EPSNamedCommand, 109EPSNextBuffer, 109EPSNextPage, 109EPSNextPosition, 109EPSNextWindow, 109EPSOneWindow, 109EPSOpenLine, 109EPSOverwriteMode, 109EPSPluckTag, 109EPSPreviousBuffer, 110EPSPreviousPage, 110EPSPreviousWindow, 110EPSPush, 110EPSQueryReplace, 110EPSQuotedInsert, 110EPSRectangleMode, 110EPSRedo, 110EPSRedoChanges, 110EPSRegexReplace, 111EPSRegexSearch, 111EPSReplaceString, 111EPSReverseIncrementalSearch, 111EPSReverseRegexSearch, 111EPSROEditEvent, 110EPSSaveAllBuffers, 111

Index

318

EPSSaveFile, 111EPSScrollDown, 111EPSScrollLeft, 111EPSScrollRight, 111EPSScrollUp, 111EPSSelectBuffer, 112EPSSelectTagFile, 112EPSSetBookmark, 112EPSSetFillColumn, 112EPSSetMark, 112EPSSetNamedBookmark, 112EPSShowBindings, 112EPSShowPoint, 112EPSShrinkWindow, 112EPSShrinkWindowHorizontally, 113EPSShrinkWindowInteractively, 113EPSSplitWindow, 113EPSSplitWindowVertically, 113EPSStartKbdMacro, 113EPSStartProcess, 113EPSToIndentation, 113EPSTransposeCharacters, 113EPSTransposeLines, 113EPSTransposeWords, 113EPSUnassignedKey, 114EPSUndo, 114EPSUndoChanges, 114EPSUpLine, 114EPSUppercaseWord, 114EPSVisitFile, 114EPSWhatIs, 114EPSWriteFile, 114EPSWriteRegion, 114EPSWriteState, 114EPSYank, 115EPSYankPop, 115EPSZoomWindow, 115ERRINFO.C, 300ErrKmapAssign, 224ERRORFIX.C, 300Escape Sequences, 130EvalStrAdd , 225EvalStrDel, 59, 226Exclusive Selection, 14

ExecApp, 226ExecCommand, 227ExecUserCmnd, 227ExecuteMacro, 228Executing menu items from keyboard, 257, 258Expand / Collapse, 18Expanding And Collapsing Text, 18EXPORTS.H, 258Expression Evaluator, 145, 225, 226ExtAddKeyword , 229ExtAlias, 229Extassigntemplate, 23, 231, 239, 241Extassigntemplate, 24ExtColors, 231ExtColorsAssoc, 232ExtCommentSearchLimit, 233, 242ExtDelayedColoring, 233Extensibility, 143Extension specific tab stops, 247Extensions File

editing, 54Extension-specific Setup dialog, 222ExtExpandTemplate, 234, 241ExtExpandTemplate, 25ExtIndentEnable, 236ExtIndentEnableAssoc, 236ExtKmapAssign, 237ExtReadKeywordFile, 238, 239ExtReadTemplateFile, 239ExtSetDelimiters, 239ExtSetStyle, 240ExtSetTemplateMacro, 27, 235, 241ExtSetUpdateDelay, 242ExtSetWrap, 242

FFax

support via, 172Fax Number, 172FFind, 243FFindFile, 243FFindNext, 244FFindPattern, 244

Index

319

FFindShow, 245FGrepFile, 245FGrepFlags, 245FGrepNext, 246FGrepPattern, 246FGrepScope, 247FGrepShow, 247File differencing

dialog, 222File filters

add, 248delete, 249

File filters, 249File Filters dialog, 249File Find, 49, 243

file specification, 244output file, 243

File find dialog, 222File Grep, 36

files to search, 247option flags, 245output filename, 245search pattern, 246

File grep dialog, 222File locking, 155file manager, 48File merge dialog, 222File Open Dialog, 48, 222File print dialog , 222File save as, 222File type

set word wrap for, 242File Type Specific Settings, 54File types

associating with language, 54File View Window, 43, 44

File Icons, 44filters, 44Operating on the files, 45

FILE.TPL, 25Filename Transformation, 138, 139, 140Filenames, 163Files

loading, 124

FileTabs, 247Fill Pattern, 140FILTER.C, 300FilterAdd, 248FilterDeleteList, 249filters

file specification, 44Find files, 243Flags, 163Fmatch, 153, 157FMATCH.DLL, 311Font

default dialog, 222window dialog, 222

FontSelectMsg, 249form, 1forms approach

completing function calls, 1FTEE, 51FUNCT.TPL, 25Function

substitution, 253Function Definitions Outline, 55Function Reference, 189

GGDI.EXE, 311General Operation, 138Get command, 210Global Bookmarks, 47Gnu Tags, 9Go to line dialog, 222Go to mark dialog, 222GotoLine, 249grep, xiii, 19

Hhelp, 219Help DLL, 302Hex mode, xiii, 65, 67, 80, 288History Of Responses, 150, 151hotspots on the status line, 15Hunt for files, 243

Index

320

IIgnore All button

Spell Correction Dialog, 22Ignore button

Spell Correction Dialog, 22ILIB utility, 311INCLUDE subdirectory, 309Inclusive Or Exclusive Selection, 14Incremental Searching, 38indenting

spaces, 278InfoView, 2Insert

scrap, 199Insert Link, 12InsertMode, 250Installing Your DLL, 312Internet Mail, 171ISearch, 250ISearch Function, 38ISearch Function, 38Iteration Qualifiers, 133

KKey Assignments, 157, 165Key bindings dialog, 222Keyboard

executing menu items from, 257, 258Keyboard Command Sets, 302Keyboard inactivity, 192, 284, 287Keycode, 198Keymap, 251, 253, 286

basic outline of, 307current, 273

Keymap for Outputassigning to, 224

Keymap Function, 308Keymap overlay

assigning to, 237Keymap Specific Assignments, 309Keymaps, 191KeyPlayback, 250

KeyRecord, 251Keystrings, 225, 238, 250, 252Keystrokes

playback, 251playback, 65, 67, 77recording, 251

KmapAssign, 225, 238, 251, 309KmapAssignRange, 308KmapAssignTypables, 308

LLanguage

mapping extensions, 54Language

Dialog, 53Language dialog, 23Language Features, 53Language Indenting, 300Language settings, 54Language specific processing

assigning to file type, 229Language Templates, 231

expanding, 234keymap for, 237reading definitions from file, 239special chars in, 231Special Chars In, 24

LANGUAGE.C, 300LDDown, 276LDLeft , 276LDLLCAW.LIB, 311LDLLCEW.LIB, 311LDRight , 276LDUp , 276LIB subdirectory, 309LibAutoLoad , 252LibExport , 306, 307LibExport, 307LibFunctionExec, 27, 236, 253, 306LibFunctionExec, 141LibFunctionReplace, 253LibPreLoad , 254LibUnLoad , 255

Index

321

LIBW.LIB, 311Limits, 185line draw, 276Line Drawing, 146line drawing, 276Line length, xiiiLine numbers

in print output, 271Line Selections, 15LINEDRAW.DLL, 276Link

insert, 12Link Libraries, 310List file of Type, 248Local Bookmarks, 47Lock Command, 119Lower, 255

MMacros

run from Button Links, 13Maintenance Policy, 172makefile, 310Making Changes and Additions, 306Making Mouse Assignments, 19Margin

right mark, 295margin mark, 55Margins

for printing, 273Mark set dialog, 222MarkGoto , 255MarkRestorePos, 256Marks. See BookmarksMarkSavePos, 256MarkSavePos., 256MarkSet, 256Matching braces, 193, 194Matching parentheses, 194memory usage

specifying, 288Menu Accelerators, 309Menu Editor, 148

Menu Editor, 148Menu item

executing from keyboard, 257, 258Menu Items

adding, 149deleting, 149separator, 149

Menu items, 149MenuAddKeyString, 309MenuCmnd, 257MenuCommand, 258Menus

adding, 148changing position, 148deleting, 149file lists, 150

MergeFunction, 173

Merge dialog, 222Message

informativeprint on status, 266

Metacharacters, 129, 130, 132, 133, 134, 135,136

Microsoft Foundation Classes, 1Microsoft Link, 311Model Buffer, 285Model Window, 285Mouse, xv, 14, 17, 191

Copying Text, 17Creating Windows With, 18Moving Text, 17

Mouse Commands, 14Mouse Copy

And Move, 17MouseLeftDClick, 258MouseLeftDown, 259MouseRightDown, 259MovDown, 260MovEndWin , 260MovEOF, 261MovEOL , 261MovHome, 261MovLeft , 261

Index

322

MovNextChar, 262MovPageDown, 263MovPageUp, 263MovPrevChar, 263MovRight , 264MovTopBuf , 264MovTopWin , 265MovUp, 265MsgLevel, 266, 267MsgMessage, 266MsgPauseOnError, 267MsgWarning, 217Multi-buffer search dialog, 222Multiple Sources Search Dialog, 34Multi-source Search Options, 34

Nnewline

inserting raw, 198Newline Character, 24, 130, 131, 198, 199, 200,

214, 220, 231, 267, 269, 294Next Button

Spell Check Dialog, 21NextWord, 220, 267note links, 13NotePad, 60

OOLDNAMES.LIB, 311Open File Window, 48Outline Symbols, xiv, 10

Supported File Types, 11, 46Outline Window, 3, 43, 45, 46

using, 11, 45Output filename, 205, 206, 268Output Window, 3, 4, 11, 36, 41, 46, 48, 49

keymap for, 224OutputFile , 268OutputWindow , 268Override Pattern, 140

PParadox, 300Parameter checking, 1PAS.C, 300Pascal, 303Paste, 268Pctags, 9Persistent Selections, 62Phone

support via, 172Phone Number, 172Playback Strings, 251PlaybackRecStr, 74Popup Menu, 19, 27

Definition Sections, 28Item Definition Lines, 28Item Hot Keys, 29pseudo-comment, 28Separator Lines, 29Supporting Functions, 29

Pop-up notes, 13Predefined Templates, 23PREPROC.C, 300Pre-Processed View, 57Pre-Processor Commands, 58Preprocessor Conditionals, 156PrevWord, 220, 269PRG.DLL, 303Print , 269Print dialog, 222Print setup dialog, 222PrintFlags, 269PrintFooter , 270PrintHeader, 271PrintLineInc, 271, 272PrintMargin..., 273PrintSelection, 273Processing At Startup, 156Project

creating, 122defined, 121

Project fileformat, 154

Index

323

Project Files, 127Project Members

adding and deleting, 122Project Properties dialog,, 5Project Setup Checklist, 123Project Window, 3, 41, 43, 124Projects

loading member files, 124selecting or changing, 124use with version control, 127using, 124

Projects and Workspaces, 121Prompt Histories, 150PROMPT.C, 300PTG file, 5Put command, 207PVCS, 116PWB, 159

QQDefaultKeymap, 273Query functions

displaying results, 144Quick Search, 8, 39Quit button

Spell Correction Dialog, 22Quoting, 130, 134, 135, 136

RREADME.TXT, 171Recompiling a DLL, 309Recording keystrokes, 251Redo, xiii, 64, 66, 67, 76, 79, 274, 292Reference Groups and Replacement Strings, 135Regular Expressions, xiii, 129, 130, 133, 135,

136, 137, 279, 280Alternation And Grouping, 134Character Classes, 132Escape Sequences, 130Examples, 137Iteration Qualifiers, 133Matching End Of Line, 134

positioning at Beginning/End of Line, 134Special Characters, 129

Relating Checkboxes to Functions, 160Repeat, 274REPEAT.C, 300Replace

Global replacement, 33Prompted replacement, 33Single replacement, 33

Replace one function with another, 253Replace with

Spell Correction Dialog, 22Replacement Options, 33ResizeWindow, 274response files, 168Restrict to Comments/Strings

Spell Check Dialog, 21Restrict to Selection

Spell Check Dialog, 21Restrict to Strings

Spell Check Dialog, 21Ribbon Search, 16Right Margin Mark, 295right mouse click, 19

SSample DLL, 305SAMPLE.DLL, 305Save as dialog, 222SC.DLL, 303SCC Provider Interface, 120Scrap

insert, 199select next, 274select previous, 275

Scrap Buffer, 17, 196, 199, 200, 268Scrap buffers

multiple, 275multiple, 159

ScrapNext, 274ScrapPrev, 274, 275ScrapSetCount, 275SDK, 249

Index

324

Searchfor word at cursor, 39Ignore case, 32Maximal match, 32multi-source

Documents only, 35Edit Modified Files, 36Files and folders, 35Output Window, 36Project, 35Threaded, 36

on toolbar, 39Regular expression, 32Restrict to selection, 33Retain selection, 33Select matching string, 33Whole word, 33Wrap, 33

Search After Go To, 8search and replace, 31

Dialog, 31Multi-source, xiiiSettings, 32

Search List, 35Drive and Directory Lists, 37File Pattern, 37Include Directory, 37List Editing Buttons, 38Patterns List, 37

Search Options, 39Search Options dialog, 16, 32Search Pattern List

editing, 37Search results window, 49Search Subdirectories, 36Searching

incremental, 38Searching Project Files, 127Select View via Tabs, 49Selections

by Word, 15Closed, 14Exclusive, 14Inclusive, 14

Line, 15Mouse, 14, 15persistent in CUA, 62Reopening, 14

Selective Display, 19dialog, 19Using, 19

SelectWord, 275Separator string

enable, 213Set

auto-indent mode, 200backup file location, 201backup file name/location

global, 203color value for Codewright palette, 191name of state file, 281tab character usage, 204tab stop definition string, 204word wrap by file type, 242

SetLineDrawBindings, 147, 276SetLineDrawStyle, 276SetLineDrawStyle, 147Settings

buffer dialog, 222window dialog, 222

Shell buffer, 50Sidebar

File Open, 48SLIDE.C, 300SlideIn, 277SlideOut, 277Smart Indenting, 236Source Code v. Command Key, 143Source Integrity, 117Space, 278space key, 278Special Characters, 24, 129, 231Specifications, 178, 185Spell Check Dialog, 20Spell checker, xiv, 20Spell Correction Dialog, 22SrchFind, 278SrchQFlags, 279

Index

325

SrchSetFlags, 279SrchTranslate, 281STARTUP.C, 300State File, 151, 153, 156, 161, 163, 168

Contents, 161set filename, 281

STATE.C, 300StateSetFilename, 281Status line

set font for, 249Status Line Actions, 15Submenu

adding, 149Submenus, 149, 150Suggest Alternate Spellings

Spell Check Dialog, 21Symbol Definitions

Creating, 58Symbol Window, 11, 46Symbols, 3

Output Window tab, 49Symbols Window, 3SysBeep, 282SysCaretHeight, 282SysCaretWidth, 283SysEdit, 60SysExit, 283SysQFlags, 284SysSetCwd, 285SysSetDefault, 285, 308Syssetdefault, 155, 157SysSetFileLocking, 154SysSetFlags, 284, 308SysSetUserFlags, 286SysSwapBlocks, 288System Overview, 298

TTab, 288

inserting raw, 198menu editor, 148

Tab characterenable usage, 204

Tab stops, 204, 247, 248, 288, 289define for file type, 247set definition string, 204

Tabbed Output Window, 48Tabs, 133, 135, 198, 200, 204, 205, 248, 253,

286, 288, 292Select View via, 49

TABSET.C, 300TagFind, 289, 290Tagfind Function, 10TagIgnoreCase, 289TagNext, 10TagPrev, 10TagPrompt, 290Tags Database

Using, 10Tags Database, 9Tags Setup, 9Tags Support, 3, 9TAGS.C, 300TagSetFile, 290, 291TagsWnn, 4Technical Support, 171Template Definitions

adding and changing, 23Template Expansion, 300Template Expansion, 236Template Macros, 23

list of, 26Templates

containing macros, 234for language constructs, 23predefined, 23reading definitions from file, 239run from Button Links, 12special characters in, 24using macros in, 24

The _init Function, 305The Key Commands, 60TLINK, 311ToBottom, 291Toolbar

Bindings, 43Select Buttons, 42

Index

326

Toolbar Search, 39Toolbars, xiii

Docking and moving, 42Enabling and Disabling, 41

Toolbars and Buttons, 42Toolbars and Windows

dockable, 41ToTop, 291Transformation

Fill Pattern, 140Override Pattern, 140

Transformation Patterns, 140

UUndo, xiii, 64, 66, 67, 77, 79, 80, 196, 292Unmatched curly braces, 193Updating Source With Merge, 173Upper, 292User Defined Sections, 158USER.EXE, 311User-definable Popup Menu, 27Using and Modifying the Makefiles, 309Using the API, 143Using the Tags Database, 10Using Your Own DLL, 312

VVCS Maintenance Dialog, 120VCS.C, 300VDOS, 49, 50Version Control, 208, 209, 211, 212

Check In Command, 117Check Out Command, 118Check Out with Lock Command, 118Command Line Interface, 117interface, 207, 209interface selection, 116Log Command, 119Manager Command, 119Unlock Command, 119

Version Control Setup, 116VI Command Summary, 85

VI Key Commands, 85virtual space

Disabling in CUA, 62Visibles, 292Visual Basic, 312Visual SourceSafe, 116

WWarning messages

color, 217Web Page, 171Wildcard, 197, 248Wildcard patterns, 248Win.Ini, 18Window

default creation position, 293window font dialog, 222Window settings dialog, 222Windows, xiiiWindows .Ini Files, 153Windows API, 1Windows File Manager, 18Windows for Workgroups V3.11, 50WINDOWS.H, 219WinScrollHInc , 292WinSetCreationPos, 293WinVisible..., 294WinVisibleEOF, 294WinVisibleEOL, 294WinVisibleMarginCol , 295WinVisibleSeparator, 294WinVisibleSpaces, 294WinVisibleTabs, 294WinVisibleVirtLines, 294WinVisibleVirtSpaces, 294Word Selections, 15Word Wrap, 54

enabling, 295paragraph reformat, 296set by extension, 242setting right margin., 296

Working Directory, 152, 161, 164, 167, 285

Index

327

Workspacecreating, 125defined, 121saving, 125updating current, 126

Workspacesselecting or changing, 126

WrapEnable, 243, 295WrapEnable, 242WrapParagraph, 243, 296WrapSetRightMargin , 243, 296WrapSetRightMargin, 296WriteBuffer , 297

ZZoomWindow, 297

Index

328