Made in Borland® Copyright © 1991-2003 Starbase Corporation, a wholly owned subsidiary of

Borland Software Corporation. All rights reserved. All Borland brand and product names are
trademarks or registered trademarks of Borland Software Corporation in the United States and
other countries. All other marks are the property of their respective owners.
This document contains trade secrets and other proprietary information which belong to
Borland Corporation or others. Information in this document is subject to change without
notice. The software described in this document is furnished under a license agreement or
nondisclosure agreement. The software may be used or copied only in accordance with the
terms of those agreements. No part of this publication may be reproduced, stored in a retrieval
system, or transmitted in any form or any means electronic or mechanical, including
photocopying and recording for any purpose other than the purchaser's personal use or by any
method conveyed or disclosed to a third party or parties without the written permission of
Borland Corporation.

The following copyright message is required due to the inclusion of CTL3D.DLL with our
product: Portions ã Microsoft Corporation, 1985-2002. All rights reserved.

Publication History

October, 1991 First Release

February, 1992 Updated for 1.1
June, 1992 Updated for 2.0
August, 1993 Updated for 3.0
August, 1994 Updated for 3.1
November, 1995 Reformatted and updated for 4.0
January, 1997 Updated for 5.0
May, 1999 Reformatted and updated for 6.0
October, 1999 Updated for 6.0b
April, 2000 Updated for 6.0d
August, 2000 Updated for 6.5
April, 2001 Updated for 6.6
June, 2001 Updated for 6.6a
February, 2002 Updated for 7.0
April, 2002 Updated for 7.0a
July, 2002 Updated for 7.0b
April, 2003 Updated for 7.5

Trademarks

Borlandâ, C++ Builderâ, BRIEFâ, CodeWright â and StarTeamâ are registered trademarks
of Borland Software Corporation.
Delphiä, CodeSenseä, CodeFolioä, CodeMeetingä, ChromaCodeä, ChromaCodingä,
Programmer’s Editing Systemä and ChatWrightä are trademarks of Borland Software
Corporation.
Texas Instrumentsâ is a registered trademark and Code Composer StudioÔ is a trademark of
Texas Instruments Incorporated. TICCSync only works with Code Composer StudioÔ from
Texas Instrumentsâ.
MERANTä is a trademark of MERANT International Limited. PVCSâ is a registered
trademark of MERANT Solutions Incorporated.

ii
Microsoftâ, Windowsâ, MS-DOSâ, Internet Explorerâ, Visual C++â, Visual Studioâ .NET
and Visual Basicâ are registered trademarks of Microsoft Corporation.
Macintoshâ is a registered trademark of Apple Computer, Inc.
UNIXâ is a registered trademark of The Open Group.
Netscapeâ is a registered trademark of Netscape Communications Corporation.
Javaä is a trademark of Sun Microsystemsâ.
Operaä is a trademark of Opera Software.
Epsilonä is a trademark of Lugaruâ, Inc.
Vignetteâ StoryServerä Tool Command Language is a trademark of Vignette Corporation.
AppBasic uses WinWrapâ Basic, Copyright ã 1993-1996, Polar Engineering and Consulting.
Sentry Spelling-Checker Engine, Copyright ã 1993-1997, Wintertree Software Inc.
All other brand or product names are trademarks or registered trademarks of their respective
companies.

Contact Information

SALES:
Borland Software Corporation
9615 S.W. Allen Blvd
Suite 107
Beaverton, Oregon 97005
www.codewright.com
503.641.6000
800.547.9902
503.641.6001 fax

PRODUCT SUPPORT:
503.207.1190
[email protected]

HEADQUARTERS:
Borland Software Corporation
100 Enterprise Way
Scotts Valley, CA 95066-3249
www.borland.com
831.431.1000

iii
iv
Table of Contents
Publication History ii
Trademarks ii
Contact Information iii

TABLE OF CONTENTS V

CHAPTER OUTLINE 1

Chapter 1: Introduction 1
Chapter 2: Run CodeWright for the First Time 1
Chapter 3: Build Your First Project 1
Chapter 4: Command Key, Libraries, & Environment 1
Chapter 5: View Themes and Language Support 1
Chapter 6: Editing & Printing 2
Chapter 7: Projects, Project Spaces, and Workspaces 2
Chapter 8: Set up a Compiler 2
Chapter 9: Version Control 2
Chapter 10: Synchronization 3
Chapter 11: Search and Replace and Navigational Tools 3
Chapter 12: Checking and Reformatting Files 3
Chapter 13: Custom Interface 3
Chapter 14: File Support and Sharing 3
Chapter 15: Large Files 3
Chapter 16: Extend CodeWright 4
Chapter 17: UNIX 4
Chapter 18: Configuration Files & Command Line Parameters 4
Appendix A: TagWnn Utility 4
Appendix B: Making and Modifying DLLs 5

1- INTRODUCTION 7

What's In This Chapter 7

What Makes CodeWright Different 7
Additional Product Support 8
Web Page 8
Additional Support 8
Email 8
Fax 9
Phone Support 9
Key Editor Features 9

2- RUN CODEWRIGHT FOR THE FIRST TIME 31

Registering your Copy of CodeWright 31

Configuration Wizards 32
A First Look 32
Document, Menu and Toolbar Styles 33
Tabbed Multi-Document View 34
Operating System Standard Style 34
Visual Styles 35

Table of Contents v
The Menu Bar 36
File Menu 36
Edit Menu 37
Search Menu 38
Project Menu 38
Build Menu 39
Text Menu 39
Document Menu 40
Tools Menu 40
Window Menu 44
The Difference between Windows and Documents 44
Details of the Window Menu 45
Help Menu 46
Output and Project Windows 47
Output Window 47
Default Tabs 48
Optional Tabs 48
Output, File Find and Search Tabs 48
The Project Window 49
Detaching Project Window Tabs 51
Incremental Searching in the Project Window 53
More on the Open Tab 53
The Standard Toolbar 55

3- BUILD YOUR FIRST PROJECT 57

Making CodeWright Projects and Project Spaces 57

Creating a Project Space 57
Setting Project Defaults 58
Creating a Project 58
Adding Files to a Project 59
Project|Properties 60
Project Tools 60
Project Window: Project Tab 61

4- COMMAND KEY, LIBRARIES, & ENVIRONMENT 63

API Command Dialog/Prompt 63

API Command Key 64
Tab Completion for Functions and Constants 64
Rules for Tab Completion 65
API Tab Completion Example 65
Tools|Customize|Libraries: Loading CodeWright Add-Ons 66
General Environment Settings 66

5- VIEW THEMES AND LANGUAGE SUPPORT 69

View Themes: Colors, Window Attributes, Scrollbars, Fonts, Etc. 69

CodeWright View Themes 71
Default View Theme 71
Using View Themes 72

vi Table of Contents
CodeWright Language Support 72
Language Support Lexers and DLL’s 73
Language DLLs 74
Tools|Customize|Libraries 74
ChromaCoding Lexers 74
Creating a Lexer 75
Configuring Options in the Language Dialog 83
File Types 84
Options Tab 84
Tabs/Indenting Tab 85
Templates Tab 85
Coloring Tab 85
CodeSense Tab 87
Format Tab 87
Comments Tab 87
Adding a New File Type to the Language Dialog 88
Aliasing 88
Creating a Language Support DLL 89

6- EDITING & PRINTING 91

Templates and Brace Expansion 91

Templates 91
Language Specific Templates 91
Creating and Modifying Language Specific Templates 92
Non-Language-Specific Templates, Function and File Headers, and
Macros in Templates 94
Template Macros 95
CodeFolio Snippets 99
Using an Existing Code Snippet 99
Creating a New Code Snippet 102
Deleting or Renaming a Snippet 103
Editing a Snippet 104
Adding or Removing Snippets Directories 104
Brace Matching and Brace Expansion 105
Brace Function: Finding Unmatched Braces 106
Brace Highlighting 106
Brace Locating 107
BraceFindEx 107
Language-Specific Brace Matching 107
Brace Expansion 108
Align Beginning and End of Block 108
Indenting 109
Setting Spaces and Tabs 109
Tab Columns 109
Indent Columns 109
EnTab and DeTab 110
Seek Indentation and Smart Indenting 110
Block Alignment 111
Name Completion 112

Table of Contents vii

CodeSense 113
Where CodeSense Gets its Information 113
Library and Project Databases 113
CodeSense for Files that are Open in CodeWright 115
CodeSense Lookups for the Current Document 115
CodeSense Global Configuration Dialog 116
Create CodeSense Library Database 117
Edit CodeSense Library Database Location 117
Delete CodeSense Library Database 118
Parser Priority/Resource Use 118
CodeSense Databases 118
Database Files 120
Database Corruption 120
CodeSense: Main Features 121
Name Completion 121
Auto-list Members 122
Auto-type Info 123
Auto-Parameter Info 124
Extending CodeSense Functionality 124
ANSI and Unicode CodeSense Translations 124
Disable CodeSense for Sections of Code Only 124
Enable Extended Popup Hotkeys 125
Consolidate Matching Lookup Definitions 125
Project Matches in Non-Project Files 126
Maximum Number of Hits 126
Maximum Cache Size 127
Symbol Lookups 127
Troubleshooting 128
My file is not being parsed at all... 128
My file is not being parsed correctly (syntax issues)… 128
Comments and Comment Boxes 129
HTML Editing 130
HTML Language Support 130
HTML Popup Menu 130
WYSIWYG Editor/Viewer 131
HTML Viewing - Web Browser Interface 131
Viewing and Editing Internet Files: Installation Instructions 131
Using HTML WYSIWYG 132
Editing Capabilities 133
Differencing/Merging 133
XML Editing 134
XML and XSL Viewers 134
XML Split Window View 134
XML Source Code View 137
XML Browser View 138
XSL Transformation View 138
Template Expansion 139
Format Source 140
Project Filters 140

viii Table of Contents

COBOL Editing 141
COBOL Lexer and DLL 141
COBOL Extensions 142
Resequence Line Numbers 142
Line Number Handling when Lines are Copied or Moved 143
Toggle COBOL Comment 143
Automatic Time/Date Stamp on Modified Lines 143
String Literals Automatically Continue on New Lines 144
Validate Line Number Sequence 144
Patch File Shows Changes in a File 144
Hex Editing 145
Insert vs. Overtype Mode 146
Handy Hex-Editing Tips and Features 146
Clipboard and Scrap Buffers 146
Scrap Buffers 147
Multiple Clipboard/Scrap Buffers 147
Clipboard/Scrap Viewer 148
Using Help in CodeWright 148
Indexing and Accessing Help Files 149
Indexing .HLP Help Files 149
Accessing Visual Studio 6.0 or Visual Studio .NET Help Files 149
Accessing Compiled Microsoft HTML (.CHM) Help Files 150
Accessing MSVC 5.0 (.IVT) Help Files 151
Accessing MSVC 4.0 (.MVB) Help Files 151
Printing 152
Print Configurations 152
Paper Selection Override 153
Color Printing 153
Print Preview 153
Multi-Copy Printing 153
Printing Line Numbers 153
Wrapping Long Lines in Printed Documents 154
Print Headers and Footers 154
Formatting Headers and Footers 154
Macros for Headers and Footers 155
Side-by-Side Difference Printing 155
Modified Print Dialog 155
Functionality 156

7- PROJECTS, PROJECT SPACES, AND WORKSPACES 157

Definitions 157
What is a Project? 157
What is a Project Space? 158
What is a Workspace? 158
Creating a Project Space 158
The Project Properties List and Project Settings 160
Project Properties List 160
Default Settings 160
Working Directory 161

Table of Contents ix
Creating a Project and the Members Tab of Project Properties 161
Creating a New Project 162
Adding Files to a Project 163
Adding Existing Projects to a Space 163
Auto-detect File Type 164
Reading External Makefiles and Visual Studio Workspaces 165
Steps for Setting up New Makefile/Workspace Parsers 166
Synchronize Makefile/Workspace with Project/Project Space 167
Characteristics of the Project Tab 168
Organizing the Hierarchy 168
Version Control 169
Directories Tab of Project Properties 170
Storing Configuration Options with a Project 172
Reading Configuration Settings from Other Files 173
Tools Tab of Project Properties 174
Tool Categories 174
Build Tools 175
Compile Tools 176
Custom Tools 179
VCS Tools 180
Setting up Project Tools 181
Command Options on the Tools Tab 182
Filename Component Macros 183
Uppercase Macros 185
Response File 185
Symbolic Macros 186
Errors tab of Project Properties 187
Custom Error Parsers 189
Navigating Build and Rebuild Command Output 190
Traversing the Output 191
Filters tab of Project Properties 192
Project Setup Checklist 193
Using Project Spaces 194
Selecting or Changing Projects 194
Selecting or Changing Project Spaces 195
Using Projects 195
Loading Files for Editing 195
Creating, Selecting and Saving Workspaces 196
Creating a New Workspace 196
Automatic Saving 197
Loading an Existing Workspace 197
Searching Project Space and Project Files 197
Selecting files for Check-in or Check-out 198
Project Files 198
Configuration and State Hierarchy 198

8- SET UP A COMPILER 201

Categories of Command Line Tools 201

Compiler Definition 202
Response File Contents 203
Compiler Command Line 203
Special Considerations 204

x Table of Contents
Modifying the Command Line Environment 204
Displaying Output in CodeWright (FTEE and VDOS) 205
FTEE 205
Use VDOS 206
Version Control Commands 207

9- VERSION CONTROL 209

Using Version Control in CodeWright 209

Version Control Menu 209
Source Code Revision Control - Maintenance 210
Version Control and CodeWright Projects 211
Associate Version Control Projects with CodeWright Projects 211
Add Version Control Project Files to a CodeWright Project 212
Add CodeWright Project Files to an SCC Provider Project 213
Current Project Tree List 214
VCS and the User-Defined Popup Menu 215
Modifying the Standard Popup: A Simple Example 215
Making Your Own Version Control Popup Menu 216
Using Multiple Configuration/Project Files (DOS VCS Utilities Only) 216
Version Control Integration Configuration 217
Using a Command Line Version Control Provider 218
Adding a New Command Line Provider 218
Customizing Version Control Commands 219
Default Command-Line Version Control Commands 219
Additional Tips 221
CodeWright SCC Integration with Version Control Systems 222
Version Control for Use with a Source Code Provider DLL 222
Location of the SCC Provider DLLs 223

10- SYNCHRONIZATION 225

Initial CodeWright Setup 225

The CodeWright Synchronization Wizard, and Loading CWSync.DLL 226
Synchronization Setup Within the Development Environments 226
Microsoft Visual Studio .NET File Synchronization 227
Configure Synchronization Options 227
A First View 228
MSVC++ File Synchronization (5.x and 6.x) 229
VCSync Setup 229
A First View 231
Delphi File Synchronization 231
DPRSync Setup 232
A First View 233
Known Problems 233
Borland C++ Builder File Synchronization 233
BCBSync Setup 234
A First View 235
Visual Basic File Synchronization 235
VBSync Setup 236
A First View 237

Table of Contents xi
TI Code Composer Studio File Synchronization 237
TICCSync Setup 238
A First View 239
Bi-directional Synchronization 239
Sync Configuration Options 240
Accessing Menu Items via Synchronization 241

11- SEARCH AND REPLACE AND NAVIGATIONAL TOOLS 243

Search and Replace and Regular Expressions 243

Search and Replace Dialog 244
Search and Replacement Edit Boxes 244
Save Settings 244
Multiple Sources Search Dialog 244
Search and Replacement Edit Boxes 245
Current Directory 245
Multiple Source Options 246
File Pattern 246
Search List 247
Search Text Files Only 247
Search Subdirectories 247
Edit Modified Files 248
Threaded 248
Send Listing to Output Window 248
Edit Search List 249
Default Options 251
Search Direction 251
Replacement 251
Prompt 252
Search Options 253
Matches 254
Start 255
Example: Multi-Source Search 255
Fast Find on Edit and Search Window Popup 256
Incremental Searching 257
Edit Windows 257
Tree Controls 258
Quick Search 258
Toolbar Search 258
Regular Expressions 259
Special Characters 259
Escape Sequences 261
Matching a Character 261
Character Classes 262
Escaping Characters in a Class 262
Iteration Qualifiers 263
Examples 263
Regular Expressions: Positioning at Beginning/End of Line 264
Alternation and Grouping 264
Reference Groups and Replacement Strings 265
Placing the Cursor 265
Examples 266

xii Table of Contents

 Searching for Spaces, Tabs and other Blank Characters 266
Searching for Spaces or Tabs 267
Searching for New lines 267
Searching for control characters (binary/hex data) 267
Searching for New lines: Issues 268
Selective Display 268
Selective Display Options 269
Pre-processed View 269
Viewing/Hiding Lines 270
Saving Visible Lines 271
Browse, Tags, Symbols and Objects 271
Which Navigational Tool Should I Use? 271
Browser 271
Tags 272
Outline Symbols 272
Objects Window 272
Browser Support 272
Selecting a Database 273
Traversing the Tree 273
Label Bitmaps 274
Browser Toolbar 274
Tags Support 277
Tags Setup 278
Using the Tags Database 278
Outline Symbols: Overview 279
What are Symbols? 279
Symbol Scanning 280
Outline Window 281
Outline Scanning 283
Symbol Parsers 283
Symbols Database 284
Popup Symbols Menu 285
Objects Window 285
Display an Object Hierarchy 286
Using the Objects Window 287
Objects Window and CodeSense 288
Objects Window Popup Menu 288
Symbols vs. Objects vs. Tags 291
Pros and Cons of CodeWright Browsing Tools 291
Bookmarks 292
Global and Local Bookmarks 292
Graphical Bookmark Images 292
Setting and Removing Bookmarks 292
Bookmarks Tab 293
Bookmarks Window 293
Global Bookmarks 294
Local Bookmarks 294
"Other Documents" Node 294
Auto-Expand/Collapse 295

Table of Contents xiii

Button Links 295
How it Works 295
What you See 295
Defining Buttons 295

12- CHECKING AND REFORMATTING FILES 297

Differencing 297
Interleaved Differencing 298
Text Difference Analysis Dialog for Interleaved Differencing 298
Interleaved Document 300
Side-by-Side Differencing 300
Text Difference Analysis Dialog for Side-by-Side Differencing 300
Side-By-Side Difference Window 301
Side-by-Side Difference Printing 307
Binary File Differencing 308
Directory Differencing 309
Directory Difference Analysis Dialog 309
Tree Difference Window 311
Metrics Reports 313
Create Difference Metrics Report Dialog 313
File Difference Metrics Dialog 316
Using Difference Utilities 317
Merging 317
Using the Merge Files Dialog 317
Merge Output 319
Removing Changes with Merge 320
Format Source 320
Setting up Your Formatting Criteria 321
Using the Format Feature 322
Spell Check 323
Check Spelling 323
General Tab of Check Spelling 323
Word Format Tab of Check Spelling 324
Advanced Tab of Check Spelling 326
Documents Tab of Check Spelling 327
Dictionaries Dialog 328
Dictionaries 328

13- CUSTOM INTERFACE 331

Dockable Toolbars and Windows 331

Toolbars 331
Auto-hide Toolbars 334
What Does Dockable Mean? 334
Toolbar Docking Precedence 335
Enabling and Disabling Toolbars 335
Docking and Moving Toolbars and Windows 335
Customizing Toolbars and Buttons 336
Adding New Toolbars 336
Adding and Changing Toolbar Buttons 336
Binding a Function to a Button 337

xiv Table of Contents

Combo Box History Lists 339
Editing Combo box History Lists 339
Customizing Menus 339
Menu Editor 339
Menus 340
Menu Items and Submenus 341
Changing the Functionality of a Menu Item 342
Adding a Menu Item 343
Customizing External Operations within CodeWright 344
User-Definable Popup Menus 344
Editing or Creating a Popup Menu 345
Adding or Modifying a Popup Menu Item 345
Popup Menu Semantics 349
Dynamic Menu Generation 350
Supporting Popup Menu Functions 351
Using Keymaps 351
CUA Key Commands 352
BRIEF Key Commands 352
Mouse Commands 353
Mouse Scrolling Speed 353
Inclusive or Exclusive Selection 353
Closed Selections 354
Column Marking 354
Line Selections 354
Word Selections 355
Status Line Actions 355
Text Drag and Drop 356
Mouse Copy and Move 356
Creating Windows with a Mouse 357
Drag-and-Drop File Loading 357
Expand / Collapse Selective Display 358
Reassigning Keys and Mouse Actions 358
Keymap-Specific Assignments 358
Customizing with Keybindings 359
Keystroke Recording/Playback 359
Recording a Keystroke Macro 359
Saving a Macro 359
Binding Keystrokes to Functions or Macros 360

14- FILE SUPPORT AND SHARING 363

File Loading, Reloading and Validation 363

File Backups and Auto-save 367
Global Backup and Auto-Save Settings 367
Backup Settings for Specific File Types 370
Backup Settings for Individual Files 370
Formatting the Backup Specification 371
Format Controls 372
Transformation Patterns 373
Making Files Read-only 374
File Types 375
Individual Files 375
Individual File upon Opening 376

Table of Contents xv
FTP: File Transfer in CodeWright 377
Enabling the FTP Manager 377
Creating Profiles 377
Logging in to a Remote Server 378
Using the FTP Manager 378
Directory Trees vs. Base Directories 379
Put or Get using Base Directories from your Profile 379
Transferring Open Documents or Project Files 380
Displaying the FTP Toolbar 380
CodeMeeting: Messaging and File Sharing 381
Preparing for Initial Use 382
User Maintenance 383
Adding a User or Modifying User Settings 383
Updating Your Own User Settings 385
Deleting a User 385
Connecting to Other Users 385
Creating a Connection 385
Posting Away from Desk Message 385
Ending a Connection 386
Sending Messages 386
Broadcast vs. Private Chat 386
Notification of Incoming Message 386
Sharing Documents 387
Begin or End Document Sharing 387
Editing Control 388
Following Along when Switching between Documents 389
Following Along in the Current Document 389

15- LARGE FILES 391

Swap Blocks 391

How to Change the Number of Swap Blocks 391
Block Size 392
Consider Your Resources 393
Backup Files 393
Scroll Bars 393
Pre-loading Files 394
Turn off ChromaCoding 395
Saving Large Files 395
Default File Saving Method 396
File Rewrite Save Method (for Files over 1MB) 396

16- EXTEND CODEWRIGHT 397

CodeWright API 397

Using the API from the Command Key 398
Displaying Return Values With the Command Key 398
Running Multiple Commands 398
Examples of Command Key Usage 399
Command Key Evaluation of Expressions or Constants 399
Macros, Macro Languages and DLL’s 401
Macros and Macro Languages 401
DLL Extensions 403

xvi Table of Contents

Where is it Defined? 403
Perl 404
Getting Started with Perl 404
Creating and Editing Perl Scripts 405
Supplied Perl Macros 405
Perl Window 405
Popup Menu and Options 406
Online Help 406
Loading and Running Scripts 407
Running a Script Directly 407
Loading a Perl Macro 407
Running a Perl Macro 408
Accessing CodeWright Functions from Perl Scripts 409
Importing Names into the Perl Namespace 409
Unloading a Perl macro 410
Using Perl Debug Mode 410
Accessing Perl Functions 410
Avoiding Ambiguity 411
Special API Functions for Perl 411
Files used by Perl for CodeWright 413
Other Perl Resources 414
AppBasic 414
Getting Started 415
Two Editors 415
Special Keybindings 415
Two Toolbars 417
Popup Menu 417
Online Help 417
UserDialog Editor 417
Object Browser 417
Creating a Macro 418
Creating a Handler 418
Object and Proc Drop-down Lists 420
Private Sub Main 420
Tips on Creating Macros 421
Creating a Modal User Dialog 421
Running the Macro 424
Creating an EventHandler in AppBasic 424
Sample EHTEST.CWB 425
Debugging Your AppBasic Macro 425
Break Points 426
Evaluate Expression and Add Watch 426
Object Browser 427
Load Macros Dialog 427
AppBasic Sample Macros 428
AppBasic-related API Commands 428
AppBasic Edit Window Configuration 429
Example Configuration File Settings 430
Exported Functions in CWBASIC.DLL 430

Table of Contents xvii

API (C-like) Macros 432
API Macros Defined 432
Getting Started with API Macros 433
Creating a Macro 433
Editing a Macro 433
Special Editing Keystrokes 433
Creating and Editing API Macros in a CodeWright Window 434
Running a Macro 434
Language Definition 434
Comments 435
Identifier Naming Rules 435
Data Types for Variables 435
Declaring Variables and Arrays 435
Literal Values 437
Array Initializers 439
Automatic Type Conversion 439
Expressions 441
Statements and Statement Blocks 448
Program Flow Control Structures 448
Run-time Error Handling 451
CodeWright Event Handling 451
Special API Macro Functions 452
Differences between API Macros and C 453
String functions 453
Creating New Keymap Command Sets 455
Keymap _init Function 455
Keymap Function 455
Flag Initialization 455
Basic Assignments 456
Keymap-Specific Assignments 456
Menu Accelerators 456
Installing the Keymap DLL 456

17- UNIX 457

Converting File Type and EOL Characters 457

Save File as New Type 458
Enable Auto-sense File EOL Option 458
Specify UNIX EOL Characters on a File Type or Per File Basis 459
Search/Replace EOLs in the Source File 460
Macro for Automating Search/Replace Conversion 460
Compiling UNIX Programs from CodeWright 461
Preserving Filename Case, File Securities and File Links between UNIX and
Windows Environments 461

xviii Table of Contents

18- CONFIGURATION FILES & COMMAND LINE PARAMETERS 463

Configuration and State 463

Location of the Configuration File 463
Introduction to Configuration and State 464
Configuration File 464
State File 465
Other Files Containing Configuration Data 465
Example File 466
Example Interpretation 467
Processing At Startup 468
Order of Processing 468
Descriptions of Sections 469
User-Defined Sections 470
Relating Checkboxes to Functions 472
State File 473
Location of the State File 474
Contents of the State File 474
Command Line Parameters 475
Filenames 476
Parameters 476
-C<configLoc> 477
-C- 477
-G <lineNumber> 478
CW32 -g215 478
CW32 -heapalloc 478
CW32 -k mycua 478
-L <library> 479
CW32 -N 479
-P <section> 480
CW32 -s h:\home\ericj 481
Command Files 482
CW32 -s- 482

A- TAGSWNN UTILITY 483

TagsWnn Command Line Options 483

B- MAKING AND MODIFYING CODEWRIGHT DLLS 491

Core Services 493

CWSTART DLL 493
CWDIALOG DLL 496
CWHELP DLL 496
Keyboard Command Sets 497
Supplemental Language Support 497
Auxiliary Services 498
Sample DLL 499
Dissecting a CodeWright DLL 500
The _init Function 500
Exporting Functions 500
Making Changes and Additions 501
Changing Existing Functions 501
Adding Your Own Functions 501

Table of Contents xix

Recompiling a DLL 502
Using and Modifying the Makefiles 502
Adding Files 503
Compile and Link Options 503
Link Libraries 503
Microsoft Link 504
Borland Link 504
Using Your Own DLL 505
Installing Your DLL 505
Load Functions at Startup 506
Load DLL as Needed 506

INDEX 507

xx Table of Contents
Chapter Outline
The Chapter Outline provides an overview of the chapters in this manual.

Chapter 1: Introduction
The first chapter of this manual is a brief introduction to CodeWrightâ. It includes a
list of some of the latest and greatest features and information on where to get
additional product support.

Chapter 2: Run CodeWright for the First Time

Chapter 2 describes how the initial CodeWright screen looks and briefly goes over
the items on the main menu and Standard toolbar. Most of the items will be given a
preliminary description only, and will be described in greater detail in other
chapters.

Chapter 3: Build Your First Project

This chapter quickly describes the process for building a CodeWright project within
a project space. The chapter is short, intending to be a preliminary guide only, to the
steps for building a CodeWright project. CodeWright projects and project spaces will
be described in more detail in the chapter on Projects, Project Spaces, and Workspaces,
later in the manual.

Chapter 4: Command Key, Libraries, &

Environment
The API Command, Libraries, and Environment options on the Tools Menu and
Tools|Customize dialog are used and referred to extensively throughout this
manual. For this reason, they have been described as close to the beginning of the
manual as possible. They are necessary and handy tools that are used for many
CodeWright operations.

Chapter 5: View Themes and Language

Support
Chapter 5 provides information for setting up the visual environment within
CodeWright, such as colors, fonts, scroll bars, and line numbers. It also goes through
the steps necessary for creating and/or loading language support for languages that
were previously unsupported in CodeWright.

Chapter Outline 1
Most of the available language support modules in CodeWright are loaded out-of-
the-box, but there are a few that need to be loaded manually. For those languages for
which no language support modules are provided (whether loaded or not),
CodeWright has two methods for creating language support. Chapter 5 describes
those methods. It also talks about how to configure CodeWright to ChromaCodeÔ
languages that are embedded in other languages (e.g. JavaScript in an HTML file).

Chapter 6: Editing & Printing

Chapter 6 provides information about the various editing features available in
CodeWright, such as template expansion, file and function headers, CodeFolioÔ
Snippets, and automatic indenting. The CodeSenseÔ feature, a utility that inserts
functions with their necessary parameters and flags, is also described, along with the
Clipboard/Scrap, COBOL, HTML, XML, and print features. The chapter also
explains the process for setting CodeWright up to access help from different
environments.

Chapter 7: Projects, Project Spaces, and

Workspaces
Chapter 7 provides detailed instructions for building and using CodeWright
projects, project spaces, and workspaces. The chapter describes the Project|
Properties dialog and how external tools can be set up in the dialog.

Chapter 8: Set up a Compiler

Chapter 8 talks about setting CodeWright up to use DOSâ compilers. CodeWright is
not a compiler, nor does it provide one. CodeWright can, however, be configured to
use third-party DOS compilers. Once the compiler's command-line command is
properly set, CodeWright will use the command in a DOS shell to compile the
current edit buffer. When properly set up, compiles can be done from within
CodeWright with the push of a button.

Chapter 9: Version Control

Chapter 9 discusses the process for using existing version control systems from
within the CodeWright environment. There are 3 sections in this chapter. The first
section describes the CodeWright version control interface, i.e. the menus, dialogs
and buttons that are used for performing version control operations. The second and
third sections describe the two alternative methods for integrating CodeWright with
version control systems: Command Line integration, or integration via the SCC
Application Programming Interface (API). Which of the two methods to use depends
on the type of version control system being used.

2 Chapter Outline
Chapter 10: Synchronization
This chapter talks about the various Synchronization programs that come with
CodeWright, and how they are used. With Synchronization, CodeWright can be
used in conjunction with certain GUI-based development environments, such as
Microsoft Visual Studio. Borlandâ Sync Technology coordinates tasks performed in
CodeWright with tasks performed in the synchronized environment. It is designed
to make the many features in CodeWright available to the synchronized
environment. Synchronization programs are available for Borlandâ DelphiÔ and
C++ Builderâ, Microsoftâ Visual Studioâ .NET, Visual Studio C++â and Visual
Basicâ, and Texas Instrumentsâ Code Composer Studioâ.

Chapter 11: Search and Replace and

Navigational Tools
This chapter has detailed information about the Search and Replace feature in
CodeWright, including information on using regular expressions. It also describes
other code-navigation tools that come with CodeWright, specifically: Tags, Symbols,
the Objects Window, Selective Display, Bookmarks and Button Links.

Chapter 12: Checking and Reformatting Files

When the editing is finished, it may be necessary to check, reformat, and/or
compare/merge the finished file with previous versions. This chapter covers the tools
that CodeWright supplies for this purpose. The reformat and file-checking tools
include Differencing, Merging, Format Source and Spell Check.

Chapter 13: Custom Interface

Chapter 13 describes CodeWright toolbars and talks about modifying existing
keystrokes; modifying, adding, and removing menu items and toolbar buttons; and
making keystroke macros. It briefly describes the keymap-choices that are available
in CodeWright, the main ones being Microsoftâ Visual Studioâ .NET, IBMâ CUAâ,
Borlandâ BRIEFâ, Lugaruâ EpsilonÔ, and vi. It also describes some of the mouse
actions CodeWright has that are not available in most other editors, such as column
selection and text dragging and dropping.

Chapter 14: File Support and Sharing

Chapter 14 talks about our Autosave, File Backup, and FTP features. It details the
file-validation and file-preloading features, which are designed to prevent file loss
and/or file corruption. The CodeMeetingÔ section describes instant messaging and
file sharing functionality in CodeWright.

Chapter 15: Large Files

The steps for preparing CodeWright to handle files as large as 2 Gigabytes are
covered in this chapter.

Chapter Outline 3
Chapter 16: Extend CodeWright
CodeWright is a fairly complete product; there is not much that it lacks.
Nevertheless, there always seems to be one job for which necessary tools just can't be
found. If this is the case, CodeWright has three macro languages (Perl, AppBasic, and
API Macros) for extending functionality. They are provided in the event that
CodeWright doesn't already have the necessary functions for handling the task at
hand. Chapter 16 describes these tools in detail.

Chapter 17: UNIX

CodeWright is a Windowsâ-only product. That is to say that it can't be installed on
any operating system other than Windows (98, 2000 and XP). Even so, it is possible to
edit UNIXâ files in CodeWright. The main difference between files edited on UNIX
systems and files edited on Windows systems are the characters that make up the
ends of lines. Chapter 17 describes CodeWright features for automatically detecting
and inserting the proper End of Line characters. It also provides other information
about editing UNIX files in CodeWright.

Chapter 18: Configuration Files & Command

Line Parameters
There are a number of files CodeWright uses for maintaining configuration
information. These files are stored by default in CodeWright's installation directory
(project files being the exception), but they can be stored in any directory desired.
The files are listed and manipulated in CodeWright's Project|Properties
|Directories dialog, which is described in the chapter on Projects, Project Spaces, and
Workspaces. Chapter 18 briefly describes the two main configuration files used by
CodeWright, CWRIGHT.INI, and CWRIGHT.PST. It also describes command line
parameters that can be used for specifying different configuration files, different
files, and different CodeWright states (among other things), to load when the
CodeWright executable loads.

Appendix A: TagWnn Utility

TAGSWnn (TAGSW16 or TAGSW32, depending on your platform) is the Tags
program supplied with CodeWright. It automatically generates a tags database and
compiles it into a format that can be used by the built-in browser. The program is
run when Build Tags is selected from the Build menu. You may not ever need to
run the program from the command line, but in the event that you do, or if you just
wish to know more about the program, its options are briefly described in this
appendix.

4 Chapter Outline
Appendix B: Making and Modifying DLLs
In the CodeWright SDK, you can obtain resources to create new DLLs, and resources
to modify existing fundamental DLLs. Appendix B describes some of the
CodeWright architecture as it pertains to the construction or modification of
CodeWright DLLs, as well as the preliminary components of a CodeWright DLL.
Also look for tips on compiling the DLLs.

Chapter Outline 5
6 Chapter Outline
1- Introduction
CodeWright is an editor with features geared towards software programmers and
web content providers. It is designed to support multiple programming languages in
that (at a minimum) it ChromaCodes™ the syntax elements of the language. It is the
first professional-quality, extensible programmer's editor written for Windowsâ
from the ground up.

What's In This Chapter

This chapter introduces CodeWright and lists some of the features that make it a
great tool for editing needs. It specifically covers the following items:
n What makes CodeWright different.
n Additional product support.
n A list describing some of the key features in CodeWright.

What Makes CodeWright Different

Listed below are some of the things that make CodeWright different from other
editors:
n CodeWright is from Borland Software Corporation, which ensures guaranteed
satisfaction and the best support available.
n CodeWright is not a port of a program from DOS, UNIX, or any other operating
system.
n CodeWright is the innovator. Here are just a few of the innovations CodeWright
brought to programmer ’s editors under Windows:
3 CodeMeeting - provides instant messaging and remote file editng within
the editor.
3 Syntax Highlighting (ChromaCode)
3 DLL extensibility, using the CodeWright SDK
3 Binary File Differencing

1- Introduction 7
 3 Merge and Difference
3 Elided text (Selective Display)
3 Help Manager
3 IDE integration
3 Button Links
3 HTML WYSIWYG viewer
3 MVB, IVT, and HTML help file support along with traditional HLP help file
support.

Additional Product Support

If a problem arises in using or programming CodeWright, there are a number of
resources you can use. First, check the README.TXT file that was shipped along
with CodeWright. It is placed in the CodeWright home directory during installation.
It will warn you about any known "gotchas" that are not covered by the manuals.
The next places to look for help are in the Getting Started manual, this User’s Guide,
the What’s New manual, the online help files, and our various web resources.

Web Page
You can access our home page on the Internet’s World Wide Web using the following
URL: http://www.codewright.com. Information and services available there include:
n Knowledge Base and Developer ’s Forum
n Online (PDF) versions of our manuals
n Messaging to sales and product support
n Pricing and product descriptions
n Problem and enhancement report forms
n Downloading of Add-Ons and patches

Additional Support
Support for installation issues will be provided regardless of support coverage. Any
issue that arises during installation of CodeWright, up to the first execution of the
program, is considered an installation issue. After CodeWright has been successfully
installed and executed one time, the following additional resources are available
under a support contract.

Email
You can send email to [email protected], and we will assist you as soon as
possible.

8 1- Introduction
Fax
A fax normally gets a quick response. Our fax number is (503) 641-6001.

Phone Support
If you urgently need some information in order to continue using CodeWright, or if
you have an urgent bug report, give us a call. The phone number is (503) 207-1190.

For more information on arranging a support contract, please contact our Sales
Department at [email protected].

Key Editor Features

The following list describes some of the items CodeWright provides for making the
task of editing easier. Combined, they make CodeWright the most powerful
Windows editing tool on any platform.

Key Editing Features

Category/ Feature
Chapter

Introduction Flexible multiple-window, multiple-file interface.

Edit as many files in as many windows as your
resources allow.

Run CodeWright New Make your document easier to read by eliminating

for the First the need to scroll right to see long lines. With the
Time Edit toolbar visible, simply press the Wrap Mode
button or Wrap Words Mode button to turn on
display wrap in the current document.

New Each default tab of the Output Window can be

hidden or made visible from the Window|Output
submenu, the Toolbars tab of theTools|Customize|
Toolbars dialog, or the right-click toolbar selection
menu (available from any toolbar). The AppBasic,
Perl, ClipView and FTP Manager tabs are available
in these locations once their respective modules
have been loaded on the Tools|Customize|
Libraries dialog.

1- Introduction 9
 Key Editing Features

Category/ Feature
Chapter

New Like Project Window tabs, you can now detach

individual Output Window tabs to create
independent toolbars; these may be docked or free-
floating, set to auto-hide, etc.. To detach a tab, left-
click on the tab and drag it away from the Output
Window, or right-click on the frame or title bar and
select Detach tab.

Wrap option on the Display tab of the Document/

Window Manager allows you to wrap text on the
display only, adjusting the wrap column
automatically when you resize the window. Check
Column and enter a column number to wrap at a
specified column. Check the Words box to avoid
splitting words at the wrap column.

The File|New (Create New Document) dialog

allows you to jumpstart your editing session by
populating a new document with one or more Code
Snippets from the CodeFolio directory. Include file
headers, function headers, structs and more to help
eliminate repetitive typing and ensure consistent
code formatting.

The CodeFolio directory on the Create New

Document dialog mirrors the CodeFolio tab of the
Project Window; you can add, edit or delete
Snippets from the CodeFolio tab.

10 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

Documents, menus and toolbars have a new look in

Version 7.0, similar to the style available in
Microsoftâ Visual Studioâ.NET.

If you prefer to use the standard menu and toolbar

styles for your operating system, you can create a
registry entry to adopt that style within
CodeWright.

New If you prefer the traditional view for your

documents (in which documents can be tiled
horizontally or vertically, cascaded or minimized),
mark the option Standard MDI or Both in the
Tools|Customize|Environment|General dialog.

Put information where you need it! You can now

detach individual Project Window tabs to create
independent toolbars; these may be docked or free-
floating, set to auto-hide, etc.. To detach a tab, left-
click on the tab and drag it away from the Project
Window.
Each tab may be hidden or made visible on the
Project submenu of the Window Menu, the
Tools|Customize|Toolbars dialog, or the right-click
toolbar selection menu (available from any toolbar).

Configuration Wizards: to assist you in setting up

the Help Index file, setting up synchronization, etc.

Support available for the Microsoft HTML Help

Viewer.

Customization Shortcut on the Status bar allows

you to quickly access many of the items you’ll want
to configure.

Document/Window Manager has a Window tab

that consolidates settings that affect individual
documents and windows.

1- Introduction 11
 Key Editing Features

Category/ Feature
Chapter

Forward and back buttons on the Standard toolbar

allow you to navigate based on a history of the
documents and positions that have been accessed
during the current CodeWright session.

Command Key, UTF-8 Support: The option Auto-detect File

Libraries and Encoding on theTools|Customize|Environment|
Environment File Options dialog supports auto-detection and bi-
directional conversion of both UTF-8 and Unicode
encoded files. UTF-8 file conversion can also be
accomplished from the File|Save As or File|Open
dialogs.

To make the current position (flashing caret) move

as you use scrollbars in a CodeWright edit window,
mark Scrolling Moves Cursor Position on the
Tools|Customize|Environment|General dialog.

When a project is open, save state information with

either the project or project space by marking the
corresponding option on the Tools|Customize|
Environment|State dialog.

View Themes New Enhanced ChromaCoding support for embedded

and Language languages. Configure up to three “Override” screen
Support elements within a View Theme; apply the View
Theme to a file type; then choose “Override” colors
for embedded file types to differentiate sections of
those languages.

New On the Tools|Customize|View Themes|Visibles

dialog, visible characters for end of line are now
separately supported for DOS, Macintosh and
UNIX.

12 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

Regular expression support is available for both

strings and numbers, allowing you to more flexibly
define what should be ChromaCoded.
n For strings, mark Identify strings with Regex
on the ChromaCoding Lexer Settings|Strings
dialog and use the enabled fields to define
which strings to color.
n For numbers, select Regex on the
ChromaCoding Lexer Settings|Numbers
dialog and use fields in the Characters group
to define which numbers to color.

Select an extension from the Extension Override

combo box on the Document/Window
Manager|General dialog to override the file type of
the current file (highlighted in the Document/
Window List).
This allows CodeWright to treat the file as if it has
the selected extension (e.g. for coloring or
beautification), rather than its actual extension. This
is especially useful if the file has no extension or the
file's extension is not commonly used for the
language.

ChromaCoding lexers are available for Install

Scripts and .INI files, in addition to existing lexers
for XML, ASP, PHP, Cold Fusion Mark up Language,
Cold Fusion script, and many others.

Tile specified windows horizontally or vertically, all

in one row, from the Document/Window Manager
or globally from Tools|Customize|Environment.

ChromaCodingÔ Lexers: Interactively create

ChromaCoding lexers to color the syntax for your
programming language.

1- Introduction 13
 Key Editing Features

Category/ Feature
Chapter

A lexer and CodeFolio Snippets are available for the

Vignetteâ StoryServerä Tool Command Language:
n On the Tools|Customize|ChromaCoding
Lexers dialog, select Vignette TCL from the
Lexer list.
n On the CodeFolio tab of the Project Window,
expand the vtcl Snippets directory.
You may also download additional Code Snippets.
Refer to applicable sections of the Web Library
document How To: Setup “Vignette TCL”
ChromaCoding Lexer and CodeSnippets for Vignette
StoryServer.

Split Windows. Windows can be split up to 4 ways

using the appropriate CUA key sequence, or using
splitter ‘notches’ that are available on vertical and
horizontal scrollbars.

Support for keywords that can be defined by the

user. For example, XML allows users to define
unique keywords for their projects. CodeWright has
an option and controls for parsing and coloring
those keywords.

View Themes for storing sets of colors, fonts and

window attributes under individual names.

Background and foreground palette colors can be

changed (up to 16 million colors, if supported by
your display).

Associate a View Theme with a particular file type

on the Language dialog.

ChromaCodeÔ use of color to signal changed lines

or highlight language syntax.

Editing & New WYSIWYG HTML editing with an embedded

Printing toolbar for quickly inserting graphics, tables, and
commonly used tags and attributes.

14 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

New In the Hierarchy pane of the XML Split Window

View, cut, copy and paste operations are now
supported for elements and element attributes. You
can also right-click within the Hierarchy to access a
new context menu, with options to add or delete an
element row, save changes, refresh the view, and
jump to the corresponding location in the source
code view.

Enjoy robust XML support with XML viewers (XML

Split Window View, XML Source Code View, and
XML Browser View), a formatted XSL
Transformation View, XML/XSL templates and
template expansion, and XML/HTML project filters.

Select a parser language (C, C++, C# or Java) on

the Tools|Customize|Language|CodeSense dialog
to be used for the file type currently highlighted in
the Customize dialog navigation tree. This allows
you to set the language to be used to parse header
files, or to set a parser language for a non-standard
extension without having to map the extension to
an existing file type.

In the Language field on the Add/Edit Library

Database dialogs, you can choose a language to act
as a filter for the specified library.
CodeSense drop-down lists and tooltips will ignore
library databases that are configured for a language
other than that of the current document. This
results in faster lookups if you work in multiple
languages.

Keyboard aficionados -- spend more time on "home

row". From the Visual Studio .NET, CUA, vi, BRIEF
or Epsilon emulations, you may now display a
CodeSense function parameter tooltip with [Alt]-
[F1] or a CodeSense symbol definition tooltip with
[Shift]-[F1].

1- Introduction 15
 Key Editing Features

Category/ Feature
Chapter

CodeSense Filtering by File Type: Mark the option

Filter Matches by File Type on the
Tools|Customize|Language|CodeSense dialog to
filter lookups for the file type(s) selected in the
Customize dialog navigation tree. To see
CodeSense information that applies to any file type,
disable this option.

C++ and C# namespaces and Java packages are

supported by CodeSense; a Namespaces filter is
available on the Filter/Legend dialog and on the
popup menu available from the Objects Window.

Many options to extend the functionality of

CodeSense are available on the CodeSense
Advanced Options dialog (press Advanced Options
on the Tools|Customize|CodeSense|General
dialog to access).

For example, you can adjust the amount of memory

devoted to CodeSense lookups using the Maximum
Cache Size option, accelerating subsequent lookups
of the same data.

CodeSense: Parses C/C++, C# and Java source

files, to provide word completion for symbols;
function parameter help; and symbol definition
help.

16 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

CodeSense is able to parse source files inside .zip or

.jar files (a .jar file is like a .zip file for Java). This
means that all the functionality that exists with
normal source files is now available for source files
that are inside a .zip or .jar file, including “Go to”
functionality when you click on a symbol definition.

To use this capability, just configure your

CodeSense library database to use the desired .zip
or .jar file instead of a directory of individual files.
On the Add Library Database or Edit Library
Database dialog, click on the File button to browse
for a .zip/.jar file.

The option Indent Columns on the Tabs/Indenting

tab of both the Tools|Customize|Language dialog
and Document/Window Manager dialog controls
the amount of indenting/outdenting that occurs
when hitting [Tab]/[Shift]-[Tab] in the CUA
keymap.

When used in conjunction with the Tab Columns

setting on either dialog, this allows you to have a
larger tab interval (say 8 spaces), with a smaller
indention interval (say 4 spaces). This can be
especially useful in a DOS file.

The option Indent ‘case’ Statements on the

Tools|Customize|Language|Tabs/Indenting dialog
indents 'case' statements one additional tab space.

The option is available when you have selected

Smart Indenting on the Tools|Customize|
Language|Tabs/Indenting dialog, and the language
you are using supports ‘case’ statements.

1- Introduction 17
 Key Editing Features

Category/ Feature
Chapter

The EnTab and DeTab functions allow you to

replace spaces in a file with tabs, or tabs with spaces,
respectively. When you call the functions from the
Edit toolbar or right-click menu in an edit buffer, or
do not specify a flags parameter for either function,
new dialogs allow you to configure the replacement
operation. You can:
n Restrict replacement to tabs or whitespace at
the beginning of lines.
n Skip comments
n Skip strings
n Skip single spaces (EnTab only)

The Additional Clipboard Formats and Options on

the Tools|Customize|Environment|Clipboard
dialog allow you to save clipboard content in RTF
and/or HTML format (in addition to text format),
replace tabs with spaces, and preserve background
color settings in the clipboard content from the
current View Theme.

Multiple Clipboards/Scrap Buffers allow copying

more than one item for later use without
overwriting previous items.
An auto-increment clipboard option increments the
clipboard/scrap buffer to be used, just prior to
copying or cutting the new content.

Clipboard and Scrapboard viewer is available in the

ClipView tab on the Output Window for viewing
and selectively pasting items in the current buffer.

18 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

Brace Matching functions have an expanded

definition of braces. In addition to recognizing and
locating curly braces, square brackets, and
parentheses, language-specific definitions allow
CodeWright to match various brace/tag pairs.

For Pascal, the keywords Begin and End are

treated like braces; CodeWright looks for Begin
and finds the matching End. For HTML/XML, tags
are also included; CodeWright considers the current
tag an open brace and finds the matching tag.

A Print button and modified Print dialog let

you print from the Side-by-Side Difference Window
in a manner similar to two-up mode, except the left
side will contain the Reference document/file and
the right side will contain theTarget document/file.

Enhanced command line editing allows you to

select text on the command line for cut and paste.
Keyboard shortcuts are available for the command
line prompt.

COBOL Extensions: Automatically insert COBOL

line numbers, toggle comment delimiters, insert
time/date stamps to modified lines, and more.

CodeFolio Snippets: CodeFolio tab on the Project

Window. Provides a directory of code samples,
specific to programming languages, which may be
inserted into the current document. User may add
Snippets to the directory.

Zoom functionality is available on the Print Preview

dialog.

Hex mode for editing binary files, including

inserting and deleting bytes.

Unlimited Undo and Redo of commands (from the

Edit menu).

1- Introduction 19
 Key Editing Features

Category/ Feature
Chapter

Powerful Templates for language constructs,

personalized function headers and more. Any
CodeWright API function that can be executed
interactively can be executed within a template.

You will find buttons on the HTML WYSIWYG

editor/viewer toolbar for Internet Explorerâ,
Netscapeâ and Opera.ä When you are editing an
HTML file in the WYSIWYG editor, press a
browser ’s button to view and test the current file in
that browser. Support for Internet Explorer is built
in; the others are enabled when you load the
corresponding browser on to your system.

Projects, Project New On the Project|Properties|Tools dialog, the

Spaces and Settings For: field allows you to create and save
Workspaces groups of settings as configurations for Build and
Compile commands. Save settings for a Release
configuration, a Debug configuration, a custom
configuration or All Configurations.

Use configurations to execute your Build and

Compile commands by selecting
Build|Configurations, highlighting the
configuration name on the Project Configuration
Settings dialog, and pressing Set Active. To name a
new configuration, press the New button on this
dialog and complete the Create New
Configuration dialog.

To assist in navigating projects and operating on

files, organize the Project tab of the Project Window
by directory and/or project filters (set up filters on
the Project|Properties|Filters dialog). Within this
structure, sort files either by File Sort Mode (from
the Tools|Customize|Envrionment|File Sort Mode
dialog), or by version control state and then File Sort
Mode. Tooltips help you identify the various
version control icons, and you can now operate on a
group of files that spans filters and folders.

20 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

Import Visual Studio 7.0 (.NET) projects (.VCPROJ,

.VBPROJ and .CSPROJ) and solutions (.SLN) by:
n Setting Auto-detect File Type and opening
them directly into CodeWright.
n Dragging and dropping the project file into
CodeWright.
n Creating a CodeWright project or workspace
from the Visual Studio project or solution
using the Read User Makefile or Read External
Workspace dialog, respectively.

Project spaces: Multiple projects may be displayed

at a time within a project space.

Version Control StarTeamâ Integration can be setup for CodeWright

from the Version Control Setup dialog, adding a
StarTeam tab to the Project Window. From the
StarTeam Window, you can browse your StarTeam
projects, viewing information from the Change
Request, Task and File tabs within StarTeam, and
perform standard version control operations on the
selected file(s) within those projects.
You can filter Tasks andChange Requests by User,
View and/or Folder to obtain a more meaningful list.
By selecting All Views you can even see the Tasks
and Change Requests in all the Views to which you
have access at one time.

Synchronization Bi-directional Synchronization with Microsoft

Visual Studio .NET. Synchronize files initially from
either CodeWright or .NET. Then just switch focus
between the applications (such as with [Alt]-[Tab])
to synchronize files automatically.

1- Introduction 21
 Key Editing Features

Category/ Feature
Chapter

Bi-directional Synchronization with Microsoft

Visual Studio and Texas Instruments Code
Composer Studio (files in CodeWright will
automatically open in the other environment using
the bi-directional sync buttons on the MSDevSync
and TICCSync toolbars).

Special synchronization with Compiler

Environments including Microsoft VC++
Workbench, Borland Delphi, Borland C++ Builder,
and Microsoft Visual Basic 6.0.

Search and Use the Color Limited search option to only search
Replace and for text that is ChromaCoded in a particular way
Navigational (e.g. find “foo” only in comments or strings).
Tools Configure your default Color Limited search from
the Search|Options dialog, or change the
restrictions on a case-by-case basis from the Search,
Replace, File Grep or Search and Replac e Multiple
Sources dialog.

Make your search output easier to read and

navigate by adding color! To enable ChromaCoding
in the Search tabs of the Output Window, mark
ChromaCode Matches on the Search Output
Options dialog. Press the Output button on the
Search|Multiple Sources dialog to access.

Omit search matches from binary files and buffers

by marking Text Files Only on the File Grep or
Search and Replace Multiple Sources dialog.

22 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

Use Call Tree and References support to find

information on how C, C++, C# and Java symbols
are used in your project.
n Right-click on a symbol in the Objects Window
or your edit document and choose Show
Symbols Called or Used by (Function or Class
Name) to display a call tree indicating the
function(s) that the selected symbol calls and/or
the other symbol(s) that it uses.
n Right-click on a symbol in either location and
choose Show References to (Selected Symbol)
to locate and define the functions, classes, etc.
that call or use the selected symbol.

In either dialog, mark Preview Current Selection to

display the symbol definition in the source code as
you highlight it. Highlight a symbol and press
E or the Go To button to open the referenced
file at the symbol’s exact location.

Unlimited local, global, named and unnamed

bookmarks. Both named and unnamed bookmarks
may be saved in the Bookmark Database when a file
is closed, either during a session or at the end. To
save unnamed bookmarks, select the option Save
Unnamed Marks in Database for Local and/or
Global bookmarks on the Tools|Customize|
Environment |Bookmarks dialog.

Line and Column information is now provided to

New better identify bookmarks listed on the Mark Name
Database dialog.

1- Introduction 23
 Key Editing Features

Category/ Feature
Chapter

You can have up to five Search tabs visible on the

Output Window (Search 1 is the default). To replace
or append the search results in each visible Search
tab in succession, mark Auto-Increment Output Tab
on the Search Output Options dialog (press the
Output button on Search|Multiple Sources to
access).

Save and restore cursor position when closing and

re-opening CodeWright by marking the options
Save Current Position and Restore Current
Position on the Tools|Customize|Environment|
Boomarks dialog.

Selective Display mode for selecting which lines to

make visible or invisible. Allows selecting lines to
be viewed with grep-like commands, or by
preprocessing #ifdefs – you name it.

You can preserve and restore Selective Display in all

open documents when closing and re-opening
CodeWright.

The Objects tab on the Project Window displays a

hierarchical view of C/C++, C# and Java objects/
symbols that are associated with the name that you
type in the combo box at the top of the window. It
can be used to view and browse code.

The Objects tab on the Project Window has buttons

that toggle whether to Ignore Case or Include
CodeSense Library Databases in a lookup.
Additional buttons access the Filter/Legend dialog
and context menu.

Complete support of regular expressions in

searching and replacement.

Multi-document or file-based search and replace,

including searches across multiple lines and
replacement groups.

24 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

Button Links let you reference and view external

documents, such as diagrams and word processor
files, or organize notes into a To Do list. These Links
appear as graphical buttons within the text file.

Several types of browsing, including Tags, Microsoft

.BSC files, and Outline Symbols.

Checking and New CodeWright Differencing has been enhanced with

Reformatting the following functionality:
Files
n Edit files and undo changes directly in the
Difference Window.
n Elect new Ignore Case and Ignore Whitespace
options to optimize your differencing results.
n Set a Minimum Bytes per Match value for
binary differencing to strike a balance between
speed and differencing quality.

Identify changes and problems faster in your non-

text files (.exe., .gif, .bin, etc.) by differencing on a
byte-by-byte binary basis, rather than line-by-line.
Track and analyze file or directory differences by
generating metrics reports. Differencing
functionality is available from the File|Difference
submenu and Difference Window toolbar. Access
the Side by Side Difference Options dialog to
toggle between View and Edit mode, split the
Difference Window horizontally, save Difference
Window contents between sessions, or change
differencing parameters on the fly.

The Directory Difference Analysis dialog lets you

compare the files in two directories, with or without
subdirectories. A tree directory displays on the
Difference tab of the Output Window; double-click
on any file that exists in both directories to perform
Side-by-Side Differencing on that file.

1- Introduction 25
 Key Editing Features

Category/ Feature
Chapter

After performing Directory Differencing, right-click

on any file in the tree directory and select Copy File
to copy the file from one directory to another.

New Press the down arrow in the To Directory field to

view a list of previous destination directories.

Side-by-side Text Differencing, Difference Editing,

and Merging of files.

For HTML and XML files, use Text|Format Source

to reformat selected code based on standard coding
conventions for these languages. No additional
formatting criteria are defined on the
Tools|Customize|Language|Format dialog.

Expanded spell check dialog and additional

dictionaries for languages other than English.

The spell checker will check the spelling of source

code comments and strings only, if desired. Spell
check the whole buffer, or just the selection.

Tools|Customize New The ability to customize popup menus has been

Interface extended with new support for images. On the
Menu Item dialog, popup menu items can
optionally be set to find an appropriate bitmap
automatically, or to use one that you select.

26 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

New The Tools|Customize|Keyboard (Assign Keys)

dialog has been streamlined to make it more
straightforward and easier to use. Simply:
1. Choose whether the assignment will be made
to a function, API macro, Perl Macro, etc.
2. Enter or select a function or macro-any existing
keystrokes will automatically be listed.
3. Click on the new key combination-any existing
association will be displayed.
4. When the desired key assignment and function
or macro have been entered, press Assign.

Auto-hide toolbars, and auto-hide menus in Full

Screen mode.

New Project and Output Window toolbars have a

pushpin button in the upper right-hand corner that
indicates the auto-hide status for the corresponding
side of the screen. If the push pin is horizontal,
auto-hide is ON; if it is vertical, auto-hide is OFF.
You can toggle the auto-hide setting for a particular
side of the screen (left, right, top or bottom) using
this pushpin, or by toggling the Auto-hide Toolbar
setting on the Tools|Customize|Toolbars|General
dialog.

1- Introduction 27
 Key Editing Features

Category/ Feature
Chapter

New To dock or undock a toolbar or group of Project or

Output Window tabs, simply right-click on a non-
button portion of a regular toolbar (e.g. the
Standard toolbar), or the frame or title bar of the
current tab, and toggle the Docked item.

You can also double-click on the caption of a Project

or Output Window toolbar to dock or undock it if
Toolbar Captions is marked on the
Tools|Customize|Toolbars|General dialog.

To undock a single Project or Output Window tab,

right-click on the frame or title bar and select
Detach tab.

Toolbar docking precedence. Allow toolbars to take

advantage of up to two full horizontal or vertical
edges of the CodeWright window.

Interactively definable Toolbars for quick mouse

access to common commands.

Use Windows features, including resizable

Common Dialogs for familiar operation, Drag and
Drop for convenient file loading, email integration,
and Tabbed Dialogs (property sheets) to simplify
dealing with settings and options.

File Support and New Quickly access all FTP functionality within
Sharing CodeWright from the redesigned and consolidated
FTP Manager tab, located on the Output Window
by default. FTP: Transfer files from within
CodeWright. The FTP feature supports file
structures for UNIX, Tandem Guardian, and VMS
hosts. (continued...)

28 1- Introduction
 Key Editing Features

Category/ Feature
Chapter

New Create a login Profile to save a group of settings for

subsequent connection to a particular remote server
(e.g. Host name/Address, User ID, Password,
transfer mode, etc.). Logging in with a pre-defined
profile saves time and effort each time you launch
an FTP session.

A CodeMeetingä tab is available on the Project

Window. CodeMeeting facilitates code review and
collaboration through the ability to send messages
and remotely edit files with multiple users of
CodeWright, CodeWrightâ for Microsoftâ Visual
Studioâ .NET, and ChatWrightä at other locations.

Auto-save limit: Allows you to limit the size of files

that are auto-saved.

Auto-save features on the Tools|Customize|

Environment|Backup dialog control the directory
and file extension to be used for auto-saved files.

Optional auto-save at scheduled intervals or during

idle periods.

Large Files Line length and file size virtually unlimited.

Extend Enhanced API Macro Language, with support for

CodeWright arrays.

New Visual Studio .NET, CUA, BRIEF, Epsilon, or vi style

key commands.

Completely remappable keyboard – Create your

own command set.

AppBasic and Perl macro language support.

1- Introduction 29
 Key Editing Features

Category/ Feature
Chapter

UNIX If a file in Unicode UTF-8 format can be converted

to the Windows ANSI character set and back again
without loss, CodeWright can use its Unicode and
UTF-8 support to load, edit and save it. This means
that the extended characters used in European
languages are supported (e.g. á, è, ï, û, ñ, æ, ß, ç, Å).
The ability to translate UTF-8 files is especially
important, as evidenced by its use in UNIX, XML,
and Perl.

File Conversion: You can convert UNIXâ files to a

“Macintoshâ Text” or “MS-DOSâ Text” format.
Conversely, other file types may sometimes be
converted to “UNIX Text” format.

On the File|Save As dialog, in the Save File as

Type or Save as Type combo box, look for file
conversion possibilities following the normal filter
entries in the file type list.

You can specify the type of end-of-line characters

that are inserted into a new file (DOS, Unix, or
Mac), and even choose to convert existing
characters to the new type. These EOL options can
be found in the following locations:
n On the Options tab of Tools|Customize|
Language, to specify an EOL style on a file-
type (e.g. .C, .TXT, HTML, etc.) basis.
n On the Options tab of Document/Window|
Manager, to specify an EOL style on a per-
document basis.

30 1- Introduction
2- Run CodeWright for the
First Time
This section describes the way CodeWright looks when it is first loaded, giving some
tips about things to know before getting started. Many of the items described will be
deferred to other chapters in this manual for more information. The descriptions
provided are brief, intended only to familiarize the user with the initial CodeWright
environment.

Registering your Copy of CodeWright

If you have purchased a Software Assurance and Support contract, it is important
that you register your copy of CodeWright to ensure that you are notified of product
updates, and to allow Product Support personnel to easily verify your purchase if
you call for assistance. Registering also puts you on the list to receive special offers
and other timely information.

The first time you run CodeWright, a popup dialog will ask you to register your copy
of CodeWright. The following four options are presented:
n Connect to Website: Click this button to launch the Registration page on
www.codewright.com. A second dialog will also display, with options to
indicate that you have completed the Registration form, or that you will fill out
the form later. If you elect to defer the task, this reminder dialog will continue
to display each time you start up CodeWright until you select a button that
indicates you have completed registration.
n Call Borland: Click this button to see a message containing contact phone
numbers and hours of operation. The reminder dialog will not display again.
n Already Registered: Click this button to indicate that you have already
registered your copy, closing the dialog. The reminder dialog will not display
again.
n Do it Next Time: Click this button to postpone registration. A reminder dialog
will display each time you start up CodeWright until you have selected one of
the preceding options.

2- Run CodeWright for the First Time 31

Configuration Wizards
Access Help|Configuration Wizards for assistance with the following jobs in
CodeWright:
n The Help Index File Wizard: Goes through steps for configuring the help index
file. For more information about configuring help, see the topic Using Help in
CodeWright in the chapter on Editing & Printing.
n The Sync Technology Wizard: Goes through the steps needed to configure
CodeWright to synchronize with selected development environments.
Supported environments are:
3 Borland C++ Builder (V5.0 and V6.0)
3 Borland Delphi (V6.0 and V7.0)
3 Microsoft Visual C++ or Microsoft Visual Studio .NET
3 Microsoft Visual Basic (V6.0)
3 Texas Instruments Code Composer Studio (V1.0 and V1.1)
For more information, see the chapter on Synchronization.

A First Look
After completing any necessary configuration tasks, and accessing needed help tips,
the Configuration Wizard and Tip of the Day dialogs can be closed. The resulting
CodeWright screen displays a menu bar at the top, with the Standard toolbar docked
directly beneath. The window docked on the left is the Project Window, and the
window docked on the bottom is the Output Window. All of these items will be
described briefly in the remainder of this chapter.

32 2- Run CodeWright for the First Time

Initial CodeWright Screen

Document, Menu and Toolbar Styles

By default, CodeWright uses document, menu and toolbar styles similar to those in
Microsoft Visual Studio .NET, as depicted in the following screen:

Microsoft Visual Studio .NET Menu Style

Note: Some aspects of this style are still limited by the operating system
you run (e.g. menu fade is only visible with Windowsâ XPâ).

2- Run CodeWright for the First Time 33

Tabbed Multi-Document View
Documents that are open in CodeWright are accessible from a tab bar across the top
of the Edit window. Refer to the following functionality:
n To make a document current, click on its tab, right-click on its tab and choose
Select, use the regular window navigation keys (e.g. [Ctrl]-[Tab] to the
document), or select the document in the Document/Window Manager dialog.
n To close the current document, click the Close button (“X”) at the right-hand
side of the tab bar, or right-click on the tab and choose Close.
n Hover on a tab to display a tooltip showing the full directory path of the
corresponding document.
n When there are too many open documents for all their tabs to be visible, use the
left and right arrow keys next to the Close button to scroll through the tabs (not
changing which is current). Hold the [Ctrl] key while clicking an arrow to move
one “page” at a time. Hold the [Shift] and [Ctrl] keys while clicking the left
arrow to view the first tab, or while clicking the right arrow to view the last tab.
n If you use a MenuControlMask registry entry (used only in unusual
circumstances), it effectively turns off the tab list. If you want to use the tab list
anyway, create the following DWORD registry entry, giving it a value of 1:
HKEY_CURRENT_USER/Software/Borland/CodeWright/Customize/
AllowTabList
If this is done, the normal MDI buttons will appear on the menu bar. However,
it is expected that documents will remain maximized while using the tab list.
Notes: Each document will be represented by its own tab when you mark
One Document per Window on the Tools|Customize|
Environment|General dialog. If this is not marked, you can select
different documents to view through the current window as before.
If you prefer the traditional view for your documents (in which
documents can be tiled horizontally or vertically, cascaded or
minimized), mark either Standard MDI or Both in the
Tools|Customize|Environment|General dialog.

Operating System Standard Style

If you would like to adopt the standard style for your operating system, create the
following DWORD registry entry, giving it a value of 1:
HKEY_CURRENT_USER/Software/Borland/CodeWright/Customize/
OSStandardStyles
The preceding entry also changes the “flat” tab style for multiple open documents to
the 3-D look found in tabbed dialog boxes.
If you use a value of zero, the effect is the same as if the registry entry did not exist.

34 2- Run CodeWright for the First Time

Visual Styles
To enable Visual Styles for Windows XP, you must turn them on for both Windows
and CodeWright. CodeWright will use Visual Styles by default if you turn them on
for Windows.
To turn on Visual Styles for Windows XP, complete the following steps:
1. Go to the Windows Control Panel.
2. Click on Display to view the Display Properties dialog.
3. Click on the Appearance tab.
4. In the Windows and buttons combo box, select Windows XP Style.
5. Press OK to exit the dialog.
If you wish to use Visual Styles for XP, but not for CodeWright, complete the
following steps:
1. Right-click on the CodeWright program shortcut on your Windows desktop,
and select Properties.
2. Click on the Compatibility tab.
3. Check the option Disable Visual Themes.
4. Press OK to save and exit the dialog.
The Language dialog shown next provides an example of a CodeWright dialog with
Windows XP Visual Styles turned on.

Language Dialog with Windows XP Visual Styles

2- Run CodeWright for the First Time 35

The Menu Bar
The menu bar consists of ten items, described in the following topics.

File Menu
The first menu is the File menu. The File menu is intended for standard file
operations (i.e. New, Open, Save, Print, etc).

On the File|New (Create a Document) dialog, you can create a blank document, or
populate the document with one or more Code Snippets from the CodeFolio
directory to jumpstart your editing session. Include file headers, function headers,
structs and more to help eliminate repetitive typing, ensure consistent code
formatting, and encourage code reuse within your team.

Create New Document Dialog

The CodeFolio directory on the Create New Document dialog mirrors the CodeFolio
tab of the Project Window; you can add, edit or delete Snippets from the CodeFolio
tab.

Additional items are described (or deferred to other chapters for more information)
below:
n Difference and Merge. Operations available from the Difference submenu
and the Merge utility are described in detail in the User’s Guide chapter on
Checking and Reformatting Files.
n The Find menu-item is used for finding files on any storage medium. Standard
DOS wildcard characters can be used when searching for files with this option.
n Send Mail and Reload. Send Mail sends files via MS mail or cc:Mail, and
Reload reloads the current file from disk.

36 2- Run CodeWright for the First Time

n Change Directory accesses a dialog that allows the current directory to be
changed.
n Filters. The Filters dialog defines file specifications or wildcard patterns, such as
*.c, to filter files of interest from otherwise long lists of files. It's a good idea to
set the filters during the initial CodeWright session so that they'll be ready to use
in the future. Here are a few useful filters:

Description Pattern

Text files *.TXT;*.RTF

Initialization files *.INI;*.CFG

Make files *.MAK;*.

To store filter settings with the current project, check the box Save Filename
Filters in project file. If the box is checked but no project is open, the settings
are stored as default settings for use with future projects.
n Print and Print Setup. The last two items on the File menu, Print and Print
Setup, are described in more detail in the chapter entitled Editing & Printing.

Edit Menu
The first two sections of the Edit menu contain standard editing items, such as
Undo, Redo, Cut, Copy and Paste. Three items that may not be familiar are the Scrap
Buffer, Append, and Erase items:
n The Scrap Buffer item selects the Scrap Buffer for cut/paste operations.
n The Append item adds selected text to the end of the selected clipboard/scrap
buffer.
n The Erase item clears the selected clipboard/scrap buffer.
The CodeWright Scrap and Clipboard features are both described in more detail in
the chapter on Editing & Printing.

The third section of the Edit menu has options for inserting items into the current
buffer:
n Insert File brings up a dialog for selecting a file to be inserted into the current
document.
n Insert Literal brings up a dialog for entering characters into the document that
would otherwise trigger a command. The literal may be chosen using ASCII,
Hex, or Decimal values.

2- Run CodeWright for the First Time 37

n Insert Link inserts a button link at the cursor position in the current document.
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 or spreadsheet, run a macro or just to make notes. View Links (the
last item on the Edit menu) is used for viewing the contents of the Button Links
database. Button Links are described in more detail in the chapter on Search and
Replace and Navigational Tools.

In the Macros section of the Edit menu, Record, Playback, Keystroke Macros, and
Run Key Macro are available for making, testing, editing and executing Keystroke
Macros. CodeWright Keystroke Macros are described in greater detail in the chapter
on Custom Interface.

Search Menu
The Search menu contains all the items necessary for performing search and
replacement operations on single or multiple files. CodeWright search features are
described in detail in the chapter on Search and Replace and Navigational Tools. The one
item worth describing here is Options. Search|Options brings up the Default
Search and Replace Settings dialog, where you set up searches to operate the way
you expect.

It is prudent to set search options before editing so that some of the following issues
might be addressed:
n Should the search be case sensitive?
n Should there be a prompt on replacement by default?
n Should searches be limited to text that is ChromaCoded (colored) in certain
ways (e.g. find “foo” in comments or strings only)?
n Should regular expressions be found?
n Should matching text be selected (highlighted)? If so, should it be momentary
or continuous? If continuous, should Restrict to Selection be turned off so that
Search Again will work as expected?
n Should the word that the cursor sits on populate the Search dialog by default,
or should the word be typed?

Project Menu
The Project menu is used for creating, opening, closing and manipulating projects,
project spaces, and workspaces:
n Projects are used to organize and store individual sets of files and configuration
settings. A project, at a minimum, is a list of files that you find it useful to group
together logically.

38 2- Run CodeWright for the First Time

n Project Spaces organize sets of projects. Each project must be part of a project
space. If an existing project is opened without first creating a project space, a
project space will automatically be created to envelop the project.
n Workspaces preserve options and settings for the currently open windows and
documents; this can include project and non-project files. Reload the
workspace to pick up where you left off with those files.

Options on the Project menu include:

n Set Current, for setting a project to be current in the present project space.
n Read Configuration Data… item accesses the Read Configuration Data from a
File dialog. The dialog can be used to read CodeWright configuration settings
from any file that contains them.
n Properties, displays the Project Properties dialog used for configuring default
directories, project members, project tools, error parsers and project filters.
n Project Space, for accessing a submenu to create, open and close project spaces,
and to create, add, and remove projects for the current project space.

Build Menu
The Build menu contains a variety of options related to building and compiling your
files, as well as build and compile configuration.
n Compile, Build, Rebuild, Debug, and Execute, all of which have to be
configured in the Project|Properties dialog in order to use them. More
information about CodeWright projects is provided in the User’s Guide chapters
on Build your First Project and Projects, Project Spaces, and Workspaces.
n Find Next Error, used to locate the next error in the Output tab of the Output
Window.
n Build Tags, generates both the tags hypertext database and the Borland
compiled tags database. A project must be open for this to work.
n Configurations, accesses the Project Configuration Settings dialog. Here you
can select a configuration to be used in executing Build and Compile
commands, or create a new one. Configurations can be more extensively
tailored in the Project|Properties|Tools dialog.

Text Menu
The Text menu has various items for formatting and editing text. Some of these
items, like Selective Display, the Comment items, and Format Source, are discussed
in-depth in various chapters. The other items are fairly self-explanatory and will be
briefly described here.

2- Run CodeWright for the First Time 39

n Word Wrap enables and disables automatic line wrapping. The lines will wrap
at the right-margin mark, which is set on the General tab of the
Tools|Customize|View Themes dialog. On that dialog, if Wrap Display Mode
is selected, but Wrap Column is not, the right-margin will be automatically
adjusted when the window is resized.
n The Upper and Lower menu items will respectively capitalize or un-capitalize
selected text.
n The Slide In and Slide Out menu items will slide the current line or the current
selection right (in) or left (out) the length of a tab stop. The Prompted Slide In/
Out items prompt the user for some text that will be used to slide the current
line or selection in or out.
n The Left Justify, Right Justify, and Center items will position text within a
column or line selection as their names describe.
n The Enumerate menu item inserts line numbers in ascending or descending
order for selected text, and Format Columns aligns columns within a selected
block.

Document Menu
The Document menu has items that access dialogs and perform operations that are
commonly used on documents. The first and second sections contain fairly self-
explanatory items for creating, closing, clearing and maneuvering documents. The
third section has items for inserting bookmarks and moving between them.
Bookmarks are described in detail in the chapter on Search and Replace and
Navigational Tools.

Tools Menu
The Tools menu has a variety of tools for manipulating and extending CodeWright.
Items on this menu are described/referenced below:
n The first five items on the Tools menu, (with the exception of API Command),
are for CodeWright macro languages:
3 The API Macros and Run API Macro menu items are used for making and
running CodeWright API Macros.
3 The AppBasic Macros and Perl Macros menu items have submenus
containing items for loading and working with AppBasic and Perl Macros,
respectively.
Macros are described in greater detail in the chapter on Extend CodeWright.
(The API Command option is described in the chapter on Command Key,
Libraries and General Environment.)

40 2- Run CodeWright for the First Time

n The Version Control item on the Tools menu accesses a submenu containing
items that either run version control operations or that access dialogs used for
running or setting up version control in CodeWright.
When looking at this submenu, it is important to remember that CodeWright
does not come with its own version control utility. Instead, it integrates with
existing version control systems using one of two methods: command line
integration or SCC API integration. More information about using version
control from within CodeWright can be found in the chapter on Version Control.
3 To use CodeWright with StarTeam, you can add a StarTeam tab to the
Project Window. Use the StarTeam Window to browse your StarTeam
projects, viewing information from the Change Request, Task and File tabs
within StarTeam, and to perform standard version control operations on
files within those projects.
3 To set up the StarTeam tab, first obtain the StarTeam SCC Integration from
the Borland website, via a link in your current version of StarTeam. Then
complete setup of CodeWright StarTeam Integration from the CodeWright
Version Control Setup dialog. If prompted for a Version Control Directory,
browse for your Windows system directory (this is where integration
information is stored).
n The Spell Check option on the Tools menu accesses the CodeWright spell
checker. The spell checker is described in more detail in the chapter on Checking
and Reformatting Files.
n The next three items are handy utilities for performing sundry tasks:
3 The Filter option brings up a dialog that lets you perform an external
operation on the current document or a selected portion of it.
3 The Shell option runs a command shell.
3 The Shell Command option brings up a dialog that invokes a Windows/
DOS application.
n The dialogs accessed from the Customize item are used for configuring various
parts of CodeWright.

Note: Right-click on the CodeWright status bar to quickly access

many of the same items that are available on the Tools|Customize
dialog.
Items on the Customize dialog are as follows:
n The Environment item accesses the Environment dialog, which has a
number of tabs for manipulating the CodeWright environment. For
example, you can set backup files and backup specifications on the Backup
tab of the Environment dialog, and you can modify menus on the Menu
tab.

2- Run CodeWright for the First Time 41

 3 Portions of the Environment dialog are discussed in the chapter on
Command Key, Libraries, & Environment. However, since the tabs in the
Environment dialog relate to a wide variety of features in CodeWright,
the items in the dialog will be covered extensively throughout the
User’s Guide.
The General tab of the Environment dialog is used for setting various items
in the CodeWright environment. Concerns addressed by the settings in this
dialog include the following:
3 Whether system prompts (e.g. API Command dialog/prompt) should
pop up in a dialog, or be displayed on the status line. Often, the
preference is the status line prompt, the setting for which is Use
Command Line Prompt.
3 Whether windows and documents operate as a single unit, as they do
in most Windows applications, or independently. The toggle for this
functionality is One Document Per Window. If you mark this option,
you might also want to use the tabbed multi-document view; to do so
mark Tab List (or Both) under Client Window Presentation on the
General tab.
3 Whether to maintain the cursor position and selection in a CodeWright
edit window when you use scrollbars. This is toggled with the
Scrolling Moves Cursor Position option.
3 Whether to use the Tab List (if selected) to control the order of
windows accessed when you press [Ctrl]-[Tab] or [Shift]-[Ctrl]-[Tab].
3 Whether the Vertical/Horizontal Tile options on the Window menu
should truly tile vertically or horizontally, or whether they should tile
in the traditional Windows way. For windows to tile, you must select
either Standard MDI or Both on the General tab.
The File Options tab of the Environment dialog contains a variety of file-
related items, addressing issues that include the following:
3 Whether Unicode and UTF-8 should be automatically detected and
converted when files are opened and closed (mark Auto-detect file
encoding). If a file in Unicode or UTF-8 format can be converted to the
Windows ANSI character set and back again without loss, CodeWright
can load, edit and save it. This means that the extended characters
used in European languages are supported (e.g. á, è, ï, û, ñ, æ, ß, ç,
Å), but files cannot contain Hebrew, Kanji, Hangul or similar
characters.
Note: You can also elect to convert some file types to/from Unicode or
UTF-8 from the File|Save As and File|Open dialogs.

42 2- Run CodeWright for the First Time

 3 Whether a list of recently loaded files should appear at the bottom of
the File menu. This option can be quite handy for reloading files, and
is turned on by marking Show File List on File Menu.
3 Various file loading and file validation concerns.
The State tab of the Environment dialog allows you to save state
information between CodeWright sessions. Ask yourself these questions:
3 Do you want CodeWright to remember and load the last file you were
working on, all files, or no files?
3 Do you want to save Window, Document and Marks state information
in the project or project space file?
n The Keyboard item brings up the Assign Keys dialog. Use this dialog to
create or modify keystroke and mouse-click assignments. Description on
using the Assign Keys dialog is available in the chapter on Custom Interface.
n The Language option accesses a dialog that is used for controlling
language-specific features, such as ChromaCoding (syntax coloring), and
template expansion. Select a file type as necessary, then choose the desired
tab to view/modify Language settings.
Note: View Themes, ChromaCoding Lexers, and Language Support
are described in the chapter on View Themes and Language
Support.
n The Libraries item is used for interactively loading CodeWright DLLs (or
Add-Ons) to extend the functionality of the CodeWright program. A
number of commonly used Add-Ons are contained in this list.
CodeWright Libraries can be quickly and conveniently loaded by placing
checkmarks next to the ones to be loaded. More Add-Ons are available on
our web site at http://www.codewright.com.
n The ChromaCoding Lexers option accesses the ChromaCoding Lexer
Settings dialog. Here you can create or modify lexers to color the various
elements of your programming language “vocabulary ”. The vocabulary of
a language includes identifiers, braces, preprocessors, keywords, operators,
strings and comments.
n The Version Control item accesses the Version Control Setup dialog, on
which you can select and configure a Command Line or SCC Provider for
version control operations in CodeWright.
n The View Themes option accesses a dialog used for viewing and changing
View Themes, which store sets of document and window preferences, such
as colors, fonts, line numbers, and scroll bars.

2- Run CodeWright for the First Time 43

 n The Toolbars item brings up the Toolbar Customization dialog, on which
you can make toolbars visible, set their attributes, customize buttons, and
assign bindings. Refer to the chapter on Custom Interface for more
information.
n The Open Tab|General item accesses a configuration dialog for setting the
organization and functionality of the Open tab on the Project Window.
n The CodeSense option accesses a list of CodeSense libraries and associated
dialogs. When properly configured, the CodeSense feature completes the
names of, and suggests parameters and members for, code elements as they
are being typed. It is available for C/C++, C# and Java files. CodeSense
works by parsing the programming libraries that you add on the
Tools|Customize|CodeSense|General screen, as well as project source
files and files that are open in CodeWright. CodeSense must also be
configured on the Tools|Customize|Language|CodeSense dialog to be
used. For more information on CodeSense, refer to the chapter on Editing
& Printing.
n An additional CobolExt Settings item is available on the Customize dialog
when the COBOL Extensions module is loaded in Tools|Customize|
Libraries. See the topic COBOL Extensions in the chapter Editing and
Printing.
n The last section of the Tools menu is optional. It contains tools that may vary if
CodeWright has been customized. Custom tools are set up in the
Project|Properties dialog on the Tools tab. These are described more
comprehensively in the chapter on Projects, Project Spaces, and Workspaces.

Window Menu
Similar to the Document menu, the Window menu is used for manipulating and
creating windows opened in CodeWright. It is important to understand how
CodeWright differentiates "windows" and "documents". Depending on the
configurations that have been made in CodeWright, the files that are open may not
always be contained in their own windows. The difference between windows and
documents is described next.

The Difference between Windows and Documents

Some confusion may arise when attempting to discern how CodeWright
differentiates "windows" and "documents”. Depending on the keymap being used,
documents open in CodeWright may not all appear in their own windows.
n Most of the keymap emulations that CodeWright provides (e.g. BRIEF, Epsilon,
and vi) use one window for all documents by default. While there may be 10
documents open, only one of them will be seen at a time in the one window that
is open. This characteristic defers to the DOS days of the editors from which the
referenced keymap emulations were derived.

44 2- Run CodeWright for the First Time

n The CUA and Visual Studio .NET keymaps, however, use one window for every
document. Therefore, in CUA and Visual Studio .NET, each window will contain
its own document.
The "document per window…" characteristic can be toggled for any keymap using
One Document per Window in Tools|Customize|Environment |General.
Keymaps are described in the chapter Custom Interface.

Details of the Window Menu

The items on the Window menu are fairly self-explanatory:
n New Window creates a new window. If a document is open, the new window
will contain a second instance of that document.
n Full Screen puts documents into full-screen mode, eliminating the clutter
caused by menus and toolbars and maximizing editing space.
n The Tile and Cascade items are alternate ways to arrange windows on the
screen. Arrange Icons arranges minimized windows at the bottom of the
screen. These options are available if you have marked Standard MDI or Both
on the Tools|Customize|Environment|General dialog.
n The Close All option closes all windows that are open.
n The Output and Project options display submenus on which you can display or
hide individual Output and Project Window tabs. Each tab is treated as an
independent toolbar.
A brief description of these windows is provided in the topic Output and Project
Windows, in this chapter.
n The Windows item on the Window menu accesses the Document/Window
Manager dialog. The Document/Window Manager dialog lists documents and
windows that are currently open in CodeWright. The window's file icons
represent the different document/window states that the files are in (as
described in the online help topic Document/Window Manager Dialog), as well as
their read-only or modified status. This dialog can be used to change the
attributes of the open windows and documents on an individual basis.

2- Run CodeWright for the First Time 45

Document/Window Manager Dialog

Some of the things that can be done in Document/Window Manager include:

n Override a file’s extension. This allows CodeWright to treat the current file as if
it has the selected extension (e.g. for coloring or beautification), rather than its
actual extension. This is especially useful if the file has no extension, or the file's
extension is not commonly used for the language.
n Specify indent options.
n Tile/cascade individually selected documents or windows (if you have marked
Standard MDI or Both on the Tools|Customize|Environment|General dialog).
n Set different View Themes (fonts, colors, etc) for individual documents/
windows.
n Change display modes (e.g. Selective or Hex displays).
n Change window attributes (e.g. scrollbars, line numbers).
n Set soft line Wrap (located on the Display tab) to wrap lines without inserting a
line feed, adjusting the wrap column as the window is resized. Check Column
and enter a number to wrap at a specified column. Check the Words option to
avoid splitting words at the wrap column.
3 Also look for buttons on the Edit Toolbar that will place the current

document into Wrap or Wrap Words mode.

Help Menu
Use the CodeWright Help menu for accessing and configuring online help files,
accessing Configuration Wizards, and finding resources on the CodeWright website.

46 2- Run CodeWright for the First Time

Output and Project Windows
The default CodeWright screen has two system windows, one docked on the
bottom, and one on the left. The window docked on the bottom by default is called
the Output Window. The window docked on the left by default is called the Project
Window. Tabs from these two windows can be "undocked" by dragging them away
from any edge of the CodeWright screen, or by right-clicking on the frame or title bar
and selecting Detach tab. Further information on customizing the Output and
Project Windows can be found in the chapter on Custom Interface.
n The Output Window is described to a greater extent in various chapters of this
manual, as it contains a number of tabs that relate to various features in
CodeWright.
n The Project Window is described in greater detail in the chapter on Projects,
Project Spaces, and Workspaces.

Output Window
There are a number of windows in CodeWright that are not normal edit windows.
They contain such things as output from a compiler or OS command, and require
special treatment. CodeWright has a special Output Window for these purposes.

The Output Window initially has seven tabs and is docked on the bottom edge of the
CodeWright screen. When a tab has focus, its name will display on the title bar of
the Output Window.

The Output Window

The CodeWright Output Window is normally open by default. If it is not open,

individual tabs may be opened explicitly by:
n Selecting them from the Output submenu on the Window Menu.
n Selecting them from the toolbar selection menu. To access, right-click on a non-
button portion of any regular toolbar, or the frame or title bar of a Project or
Output Window toolbar.
n Highlighting them on the Toolbars tab of the Tools|Customize|Toolbars dialog
and marking Visible.

2- Run CodeWright for the First Time 47

Default Tabs
The default tabs of the Output Window are:
n Output tab: Displays the results of builds or compiles.
n File Find tab: Displays the results of file searches produced by File|Find.
n Search 1: Displays the results of string searches produced from search
operations.
n Browse tab: Displays tags or browser database files.
n Difference tab: Displays the differences of two files in a vertically or
horizontally split window. The tab is also used to display directory differences.
n Shell tab: Acts as a virtual DOS shell.
n Symbols tab: Allows you to navigate through files, much like the Browse tab.

Optional Tabs
Up to four additional Search tabs can be made visible on the Toolbars tab of the
Tools|Customize|Toolbars dialog (Search 2, Search 3, Search 4 and Search 5).

The AppBasic Edit, Perl, ClipView and FTP Manager tabs are also tabs that will not
be marked by default. Each of these tabs has an associated DLL that must be loaded
on the Tools|Customize|Libraries dialog before it can be used.

Output, File Find and Search Tabs

Each tab within the Output Window has its own popup menu containing items
applicable to its purpose. From the Output, File Find or Search tabs of the Output
Window, the popup menus have several common items:
n Copy, which copies selected text to the clipboard.
n Append, which adds selected text to the end of the clipboard contents.
n Open all files, which opens each file that is referenced in the current tab.
n Open Explorer with Directory, which launches Windows Explorer and
navigates to the directory containing the selected file.
n Clear Error File or Clear Window, which resets the current tab and updates the
error file on disk, if there is one associated with the tab.
n Horiz. Scrollbar, which toggles a horizontal scrollbar at the bottom of the
current tab.

48 2- Run CodeWright for the First Time

Within the Output, File Find and Search tabs, you also have the following
functionality:

n Double-click or press E on a specific output line to jump to that point in the

referenced document.

n Use the Save button or File|Save menu item to save the contents of the
current Output Window tab.
n Right-click and drag the mouse to make a block selection, or left-click and drag
the mouse to make a stream selection. Stream selections can also be created
using theS key combined with motion keys. Use Cc to copy your
selection to the clipboard.

The Project Window

The Project Window is initially docked on the left edge of the CodeWright screen.

Project Window

Like the Output Window, the Project Window initially contains several tabs. The
tabs are primarily for viewing information about projects and other files. When a tab
has focus, its name will display on the title bar of the Project Window.
The tabs (from left to right) are:
n Project tab: Lists the files in the current project in hierarchical form, and lets you
operate on individual files or groups of files. More information about the Project
tab can be found in the chapter on Projects, Project Spaces, and Workspaces.

2- Run CodeWright for the First Time 49

n Outline tab: Presents a hierarchical view of Symbols in project files and any
other files that are currently loaded. More information about Symbols and the
Outline tab can be found in the chapter on Search and Replace and Navigational
Tools.
n Objects tab: The Objects tab displays a hierarchical view of C/C++, C# and
Java objects/symbols. The objects/symbols displayed are associated with the
name that is typed in the Identifier box at the top of the window. The window
can be used to view and browse code. More information about the Objects tab
can be found in the chapter on Search and Replace and Navigational Tools.
n Bookmarks tab: Gives a view of local and global bookmarks defined in
documents. More information about bookmarks and the Bookmarks tab can be
found in the chapter on Search and Replace and Navigational Tools.
n Open tab: Acts like a persistent File Open dialog and file manager in one. It
presents a list of icons representing valid drives from which to choose, a
directory tree, a place to specify a file filter to limit the files displayed, and a box
where matching files are listed. Double-click on any of the files listed to load it
for viewing or editing. More information on the Open tab is provided in the
next section: More on the Open Tab.
n CodeFolio tab: Presents a directory tree of pre-defined Code Snippets that are
specific to programming languages. You can insert these Snippets into your
current document. Custom and user-defined Snippets can also be added to the
window. The Snippets that are available on the CodeFolio tab may also be
inserted into a new document from the File|New dialog.
Refer to the topic CodeFolio Snippets in the chapter on Editing & Printing for more
information.
n CodeMeeting tab: Facilitates code review and collaboration through the ability
to send messages and share files with multiple CodeWright, CodeWright for
.NET and ChatWrightä users at other locations. To enable the CodeMeeting
tab, check the box for CodeMeeting on the Tools|Customize| Libraries dialog.
Refer to the User’s Guide chapter on File Support and Sharing for more
information.
n StarTeam tab (optional): Allows you to browse your StarTeam projects,
displaying information from the Change Request, Task and File tabs within
StarTeam. Perform standard version control operations on files within those
projects from a right-click menu.

Press to access the StarTeam Filter Options dialog, where you can filter
Tasks and Change Requests by User, View and/or Folder to obtain a
meaningful list. By choosing All Views, you will see the Tasks and Change
Requests in all the Views to which you have access at one time.
Once you have obtained the StarTeam SCC Integration from the Borland
website, via a link in your current version of StarTeam, you can complete setup
of CodeWright StarTeam Integration from the Version Control Setup dialog.

50 2- Run CodeWright for the First Time

Detaching Project Window Tabs
You may detach individual Project Window tabs to create independent toolbars. To
use detachable tabs, refer to the following sections.

Creating a New Toolbar from a Project Window Tab

To detach a tab from the Project Window, simply left-click on the tab and drag it
off the Project Window, or right-click on the frame or title bar and select Detach
tab. The title bar of this new toolbar will now display the name of the selected
tab (e.g. CodeFolio).

CodeFolio Tab of the Project Window (Detached)

If you would like to group multiple Project Window tabs together, simply follow
the preceding instructions, docking the successive tabs on top of the first. You
can rearrange tabs by positioning them in the desired location as you drop
them, or by dragging them to different positions at any time.

Attributes of a Project Window Tab

Whether part of the default Project Window or detached, Project Window tabs
have the attributes of a regular toolbar, including the following:
n Clicking anywhere on the tab activates it.
n To hide a set of tabs, right-click on the frame or title bar and select Hide. To
hide a single tab, right-click on the frame or title bar of that tab and select
Hide tab.

2- Run CodeWright for the First Time 51

 n Each tab is listed on the Tools|Customize|Toolbars dialog, and on the
right-click toolbar selection menu. If you close a tab, you can re-display it by
any of the following methods:
3 Right-click on a non-button portion or frame of any toolbar to view the
toolbar selection menu, and select the name of the tab from the Output
tabs or Project tabs submenu.
3 Mark the tab's name on the Project submenu or Output submenu of
the Window Menu.
3 Go to the Toolbars tab of Tools|Customize|Toolbars and make the tab
Visible.

Toolbars Tab on the Tools|Customize|Toolbars Dialog

n A tab will auto-hide if you dock it on a side of the screen that has auto-hide
turned on. If the push pin button in the upper right-hand corner of the tab
is horizontal, auto-hide is ON; if it is vertical, auto-hide is OFF. You can
toggle the auto-hide setting for a particular side of the screen (left, right, top
or bottom) using this pushpin, or by toggling the Auto-hide Toolbar setting
on the Tools|Customize|Toolbars|General dialog.
n You can quickly dock or undock a dockable window by selecting from the
following methods as appropriate:
3 To dock or undock a set of Project or Output Window tabs together,
right-click on the frame or title bar of the Project or Output Window,
and toggle the Docked item. You can also double-click on the caption
of a Project or Output Window toolbar to undock the tabs together if
Toolbar Captions is marked on the Tools|Customize|Toolbars|
General dialog.
3 To undock a single Project or Output Window tab from a group of tabs
(e.g. the Outline tab), right-click on the frame or title bar of the tab and
select Detach tab.

52 2- Run CodeWright for the First Time

 n To manually dock a floating window, drag it with the mouse over one of the
four edges of the CodeWright window, continuing to hold the mouse
button down:
3 To add a floating window as a tab to an existing window, point to the
title bar of the destination window. You can also drag the floating
window into the tab area of another toolbar to order it in the list of tabs
as desired.
3 The outline of the object you are dragging will indicate what
orientation it will take when dropped.
n If multiple toolbars are docked on the same side of the CodeWright screen
(say the Outline and CodeFolio tabs), a splitter bar between the toolbars is
provided to allow for easy resizing.
n The tab's state will be saved when you close and restart CodeWright.

Incremental Searching in the Project Window

Tree controls are used in various locations throughout CodeWright, including the
tabs of the Project Window (Project, Outline, etc.).

Incremental searching is available to help you quickly navigate tree controls. Give
the tree control focus (e.g. click in the Project tab), then type as many characters as
necessary to find the desired string.
Example: Say that you are in the Project tab of the Project Window, and
would like to search for a file called myproject.c. Complete the
following steps:
1. Click inside the Project tab to give it focus.
2. Type ‘m’. CodeWright will highlight the next item in the Project
tab that begins with 'm'.
3. Type ‘y’. CodeWright will highlight the next item in the Project
tab that begins with ‘my’.
4. Type ‘p’. CodeWright will highlight the next item in the Project
tab that begins with ‘myp’.
5. Continue pressing keys until you have found the item you are
looking for.
If you type a character that is not part of a continuing match, the search is started
over with the next item that begins with that character.

More on the Open Tab

The Project Window’s Open tab is a handy tool for file-operations. Opening files is
just the beginning of what it can do. There are a total of 20 other operations that can
be performed, as represented by a series of icons on the tab’s frame. Tooltips (small
popup messages) describe each of the icons.

2- Run CodeWright for the First Time 53

Open Tab on the Project Window

Use the File Open Tab - Configure dialog to remove, add or reconfigure the icons on
the Open tab. To access this dialog, select Tools|Customize|Open Tab|General or
click on the Configuration Dialog button:

The following displays:

File Open Tab – Configure

54 2- Run CodeWright for the First Time

Two of the icons you can set for the Open tab are for user-defined commands:

and . User-defined commands can be set to perform any operation on files

selected within the window. The user commands must be CodeWright API function
calls, rather than DOS commands or the like. You may, however, execute DOS
commands by specifying the API function ExecUserCmnd (help on ExecUserCmnd
can be found in CodeWright's online help).
Example: ExecUserCmnd “Dir ”
The File Open Tab - Configure dialog is also used to set whether or not to display
hidden files, file timestamps, file sizes and file attributes as Tooltips that display
when the mouse cursor pauses over a file in the window.

The Standard Toolbar

CodeWright has several toolbars, but only the Standard toolbar is turned on by
default. Since the Standard toolbar is part of the default CodeWright screen, it will be
introduced here; all of the toolbars are described in more detail in the chapter on
Custom Interface, and in the online help. A description of the Standard toolbar
follows:

Standard Toolbar

The Standard toolbar consists of the following:

n The first two buttons on the Standard toolbar are Forward and Back buttons.
They allow you to navigate documents and document positions based on a
history of documents and positions that have been accessed during the current
CodeWright session.
3 When you switch to a different file, the last cursor position in the previous
file is recorded in the DOCUMENTVISIT history list on the
Tools|Customize| Environment|History dialog .
3 When you use the GoTo feature in CodeSense, the cursor position in the
current document is also recorded.
Drop-down lists are available for both the Forward and Back buttons. Press the
corresponding down-arrow to access specific documents/document positions
without having to cycle through all the documents in the list.
n The nine buttons that follow the Forward and Back buttons are for editing and
file operations: creating, opening and saving files; printing; cutting, copying
and pasting text; and redo/undo of the last change made.

2- Run CodeWright for the First Time 55

n The next item on the Standard toolbar is the Toolbar Search Box. The Toolbar
Search Box refers to the search capability built into the Standard toolbar in the
form of a drop-down list box control. It provides the most immediate,
convenient way to perform simple searches. The Toolbar Search honors all of
the settings in the Search|Options dialog, and any Word Delimiters defined
on the Tools|Customize|Language|Options dialog.
3 To use the Toolbar Search, type in the string you wish to search for, and
press E.

n The next two buttons on the Standard toolbar are also related to searching:

3 Press to repeat the last search.

3 Press to perform a Quick Search for the word under the cursor in the
current document. Parameters from the Default Search and Replace
Settings dialog are used. Word Delimiters defined on Tools|Customize|
Language|Options also affect this search type.
n The last button on the Standard toolbar (the question mark) is for accessing the
CodeWright online help file.

56 2- Run CodeWright for the First Time

3- Build Your First Project
This chapter provides a quick guide for building CodeWright projects and project
spaces. Projects and project spaces are covered more fully in Projects, Project Spaces,
and Workspaces.

CodeWright projects offer a means for storing related files as a unit. They make
version control operations simpler and more convenient, and they store unique
configuration settings, like compiler commands, with each project.

Project spaces are an extension of the project facility. They store sets of projects,
allowing multiple projects to be displayed at a time. A project space must be open
before a project can be created.

Making CodeWright Projects and

Project Spaces
The appropriate order for making projects is as follows:
1. Create a project space.
2. Make default settings.
3. Create projects and/or add existing projects to project space.
4. Add files to projects.

Creating a Project Space

To create a project space, do the following:
1. Click Project|Project Space|New.
2. Click Browse to set the directory in which the project space will be stored.

3- Build Your First Project 57

3. Name the project space. Project space configuration files use .PSP extensions.
Note: The chapter Projects, Project Spaces, and Workspaces describes the Look
in directory for external workspace option.
4. Click OK. The project space is created, and the Project|Properties dialog
appears, with the Members tab on top. The new project space is displayed in
the list box on the left. Projects may be added to spaces, and files are
subsequently added to projects, in this dialog. The information about creating
projects and adding files is contained in the topics Creating a Project and Adding
Files to a Project. But before the project is created, it is necessary to set the project
defaults, as explained in the next section.

Setting Project Defaults

Configuration settings for new projects are inherited from the <Default Settings>
item in the Project Properties dialog. Changes made to the settings while a project is
selected will be stored with that project only. Closing the project will cause all
settings to revert to the defaults. For this reason, it may be a good idea to set some
configurations for <Default Settings> before the project is created, so that the
settings won't change when the project is closed. For example, it may be wise to set
up the compiler before creating a project so that the settings won't be lost when the
project is closed. (Information for setting up a compiler can be found in the chapter
Set up a Compiler. Information on project settings can be found in the chapter on
Projects, Project Spaces, and Workspaces.)

To make default settings, highlight <Default Settings> in the Project| Properties

dialog, and then make various configuration settings in the different tabs of the
dialog. Once desired <Default Settings> have been established, appropriate
modifications can be made for projects on a per-project basis.

Creating a Project
Once a project space has been created, individual projects can be created for the
space. Projects are created in the Project|Properties|Members dialog. This dialog
should appear immediately after a new project space has been created. To otherwise
access the dialog, select Project|Properties, and then click the Members tab. Carry
out the following steps to create a CodeWright project:
1. Highlight the current project space in the listbox on the left.

2. Click to access the Add New Project to Project Space dialog. (The same
dialog can be accessed using the Add New Project item on the Project|Project
Space menu.)
3. In the Add New Project to Project Space dialog, click Browse to make sure that
the directory the project is being created in is appropriate, then name the
project.

58 3- Build Your First Project

Add New Project to Project Space

4. Click OK. CodeWright creates a new configuration file in the chosen directory
with the name that was typed and a .PJT extension.

Adding Files to a Project

Files can be added once the project has been created. Complete the following:
1. Access the Members tab of the Project|Properties dialog.
2. Highlight the project in the listbox on the left.
3. Add the files using one of the following methods:

n Click to access the Scan Existing Files into Project dialog. Add
individual files by typing in the name or add multiple files using file filters
(e.g.*.C). Paths are optional (e.g. C:\TEST\*.H). Use the […] button to
browse for different directories.
n Multiple filters can be used by separating each filter with semi-colons (e.g.
*.C;*.H;*.CPP). The Include Subdirectories option causes files in
subdirectories of the current directory to be included with files that are
added.

n Click to access the Select One or More Files to Add to Project dialog.
Add individual files by double-clicking or typing the name. Add multiple
files by S or C -clicking.

n Use the External Makefile option to read files from an existing makefile.
See Reading External Makefiles in the chapter Projects, Project Spaces, and
Workspaces.
n Use the VCS Project option to read files from a version control project file
(see Using Version Control in CodeWright, in the Chapter Version Control).

3- Build Your First Project 59

Files that are included in the project are listed in the Files listbox in the center of the
dialog. Files can be deleted from the project by selecting them in the listbox and
pressing the Delete button.

Project Properties Members

Note: You can make it easier to include and work with UNIX or Macintosh
files by converting their EOL types; you can also convert Unicode or
UTF-8 files for editing in CodeWright. Refer to the section Converting
File Type and EOL Characters in the UNIX chapter of this manual.

Project|Properties
The Project|Properties dialog is where all project configurations are set. Most of the
settings made in this dialog can be used without an open project, in which case they
would be global settings and would become the defaults. More information on the
Project|Properties dialog is provided in the chapter on Projects, Project Spaces, and
Workspaces.

Project Tools
Once the necessary files have been added in the Members tab of the Project|
Properties dialog, the project space and projects are basically complete. Before
clicking OK, though, it often desirable to set up some tools in the dialog's Tools tab.
See the topic Tools Tab of Project Properties in the chapter Projects, Project Spaces and
Workspaces for more information.

60 3- Build Your First Project

Project Window: Project Tab
Once the project space has been populated with all the appropriate projects, and the
projects have their necessary files and configurations, press the OK button for the
Project|Properties dialog. The project space is then created.

For a graphical display of the project space, click the Project tab of the Project
Window. The project space and its included projects will be displayed. The projects
can be further expanded to display each project's member files. An example of the
Project tab, expanded to show project space, projects and files, follows:

Project Tab

To load project files for editing, double-click on them in the window, or click on the
Load Files item in the Project menu.

For more information on CodeWright projects, see the chapter on Projects, Project
Spaces, and Workspaces.

3- Build Your First Project 61

62 3- Build Your First Project
4- Command Key,
Libraries, & Environment
The API Command, Libraries, and Environment options on the Tools menu and
Tools|Customize dialog are used and referred to extensively throughout this
manual. For this reason, they are briefly described here. They are necessary tools that
are used for many CodeWright operations.

API Command Dialog/Prompt

Select the API Command item on the Tools menu to bring up a prompt that
interactively runs CodeWright API functions.

API Command

API (Application Program Interface) functions drive the interface between the
operating system and application programs. This includes the way the application
communicates with the services the operating system makes available. For example,
APIs make it possible to open windows, display message boxes, and load dialogs.

CodeWright has numerous API functions, many of which are available for
interactive use from within the CodeWright editor. CodeWright APIs can be used to
change keystrokes, buttons, and menu commands; they can be used in the macros
and DLLs that extend CodeWright; and they can be used interactively from the API
Command prompt.

To run a CodeWright API on the fly, type in the function name and any required
parameters, and press E or OK.

4- Command Key, Libraries, & Environment 63

 Note: User-written functions are available only when registered. The
function LibExport must be used to register a user function, its
parameters and return value before it may be called from the
Command prompt. Conversely, API, Perl, or AppBasic macros may
be called from the Command prompt without being LibExported.
Refer to the online help for information on CodeWright APIs.

In addition to the menu item, the API Command prompt can be accessed with a
special keystroke, appropriately named the Command Key. The API Command Key
is described next.

API Command Key

If you find you want to do something in CodeWright for which there is neither a key
command nor a menu entry, you can probably do it using the Command Key:

n If you are using the Visual Studio .NET command set, the Command Key is @

n If you are using the CUA or the vi keymap command set, the Command Key is
(.
n If you are using the BRIEF-compatible keymap command set, the Command
Key is ), which in BRIEF also provides access to the BRIEF interpreter.

n In keymaps where there is no KeyCommand assignment, selecting API

Command from the Tools menu will always access the prompt.
When you press the Command Key or choose Tools|API Command, a prompt
appears on the status line or in a popup dialog box, depending on which is enabled,
like so:

Command:

You respond to the prompt by entering a CodeWright API function call, for example,
much as you would enter it in CodeWright C source code (available with the
CodeWright SDK). Press E to send the command off for processing.

Note: To specify a status line Command Key, choose the Use Command
Line Prompt option on the Tools|Customize|Environment
|General dialog. Refer to the topic Command Line Response Editing, in
the online help, for command line key sequences.

Tab Completion for Functions and Constants

The API Command prompt has a handy tab completion feature that completes
function names or constants using the first few characters of the function for
reference. This feature is available for both the status line prompt and the popup
dialog.

64 4- Command Key, Libraries, & Environment

With tab completion you can enter as much of a function name or constant as you
can recall and press the T key to receive a list of all commands that begin with the
same characters as the incomplete command.

Rules for Tab Completion

Tab completion works on the last word typed:
n The last word is delimited by a space, an unmatched left parenthesis, a comma,
or a piping symbol (|) that is not within nested parentheses.
n If the word is preceded by no text or a single '?', tab completion provides a list of
functions. Otherwise a list of constants is provided.
n If the word ends with '(', tab completion provides a list of functions. This should
only be needed to expand an embedded function call if you started the
command line with "*" or "?*".

API Tab Completion Example

Complete the following steps to see an example of API function completion:
1. Select Tools|API Command.

2. Enter the word color and press T. The following dialog displays.

Command Completion for "color"

3. Select the desired command from the list to place it on the command line for
you.

If you want a complete list of the commands available just press the T key
without entering anything at the prompt. To filter the list more selectively, you may
use regular expressions. For example, use the characters ‘.* ’ before and after
characters that you know you want to see.

4- Command Key, Libraries, & Environment 65

 Example: If you want to see all commands that contain the word ‘tab’, type
the following in the Command Key:
.*tab.*

Then press T.

More information about using CodeWright's API and the Command Key can be
found in the chapter Extend CodeWright.

Tools|Customize|Libraries: Loading
CodeWright Add-Ons
The Libraries option on the Tools|Customize dialog is used for interactively loading
CodeWright DLLs (or Add-Ons) that extend the functionality of the CodeWright
program. A number of commonly used Add-Ons are contained in the list of
CodeWright Libraries in the Libraries dialog. The CodeWright Libraries can be
quickly and conveniently loaded by placing checkmarks next to the ones to be
loaded. (More Add-Ons are available in the \SUPPORT directory of the CodeWright
CD or from our web site at http://www.codewright.com.)
Note: DLLs (Dynamic Link Libraries) are software used by Microsoft
Windows to provide services to applications. Some DLLs are
automatically loaded when needed by a program, and others must
be loaded at system startup. DLLs can be written in any
programming language used for Windows programming. Three
terms are used when referring to CodeWright DLLs: Add-Ons,
Libraries, and DLLs.
Loading a library in the Tools|Customize|Libraries dialog adds a line similar to the
following in the CWRIGHT.INI file (described in the chapter on Configuration Files &
Command Line Parameters) and loads the DLL into CodeWright:

[LibPreload]
LibPreload=CWHTML.DLL

General Environment Settings

The General tab of the Environment dialog (accessed from the Tools|Customize
dialog) is another item for which some early description is necessary. The
Environment option accesses a dialog that deals with a number of different areas in
CodeWright. For example, the Environment dialog is where backup files are
specified, and it is also where CodeWright menus can be reconfigured. The other
tabs of the Environment dialog are described in various chapters of this manual.

66 4- Command Key, Libraries, & Environment

The General tab of the Environment dialog is used for setting various items in the
CodeWright environment. The settings in this dialog affect keystroke and mouse
behavior, window options, use of the command line prompt and more.

General Tab of the Tools|Customize|Environment Dialog

For example, the option Tile using single row/column in the General tab affects the
Vertical/Horizontal Tile options on the Window menu. When the option is marked
(and you have selected either Standard MDI or Both), CodeWright has 'true' vertical
and horizontal tiling, as displayed.

True Vertical Window Tiling

4- Command Key, Libraries, & Environment 67

It is a good idea to set options in Tools|Customize|Environment|General before
beginning any editing tasks. Other concerns addressed by the settings in the
Environment dialog include the following:
3 Whether system prompts (e.g. API Command dialog/prompt) should pop up in
a dialog, or be displayed on the status line. Often, the preference is the status
line prompt, the setting for which is Use Command Line Prompt.
3 Whether windows and documents operate as a single unit, as they do in most
Windows applications, or independently. The toggle for this functionality is
One Document Per Window. If you mark this option, you might also want to
use the tabbed multi-document view; to do so, mark Tab List or Both.
3 Whether to maintain the cursor position and selection in a CodeWright edit
window when you use scrollbars. This is toggled with the Scrolling Moves
Cursor Position option.

The File Options tab addresses many file-related concerns, such as:
3 Whether a list of recently loaded files should appear at the bottom of the File
menu. This option that can be quite handy for reloading files, and is turned on
by marking Show File List on File Menu.
3 Whether filenames should be case-sensitive.
3 Whether to save files on loss of focus.
3 Whether Unicode and UTF-8 should be automatically detected and converted
when files are opened and closed (mark Auto-detect file encoding). If a file in
Unicode or UTF-8 format can be converted to the Windows ANSI character set
and back again without loss, CodeWright can load, edit and save it. This means
that the extended characters used in European languages are supported (e.g. á,
è, ï, û, ñ, æ, ß, ç, Å), but files cannot contain Hebrew, Kanji, Hangul or similar
characters.
Note: You can also elect to convert some file types to/from Unicode or
UTF-8 from the File|Save As and File|Open dialogs.
The State tab allows you to save state information between CodeWright sessions.
Ask yourself these questions:
3 Do you want CodeWright to remember and load the last file you were working
on, all files, or no files?
3 Do you want to save Window, Document and Marks state information in the
project or project space file?

API Command, Tools|Customize|Libraries, and Tools|Customize|Environment

|General are important items that are referred to frequently throughout this
manual. They have therefore been briefly covered as close to the beginning of the
manual as possible.

68 4- Command Key, Libraries, & Environment

5- View Themes and
Language Support
One of the first things you will likely want to do before beginning any editing in
CodeWright is personalize the basics, like colors and scroll bars. In CodeWright, all
colors, fonts, line numbers, scroll bars, and other window attributes are stored in
View Themes. View Themes are "color schemes" with a kick. They store named sets
of colors with individual fonts, rulers and other window-related features.
Background and foreground colors can be controlled for individual screen elements,
or for the window as a whole. The first part of this chapter talks about View Themes
and the dialog used for setting them.

The second part of this chapter covers CodeWright's main claim to fame, which is
programming language support. Since colors are a primary concern in language
support, and colors are a principal part of View Themes, View Themes seem to be a
natural lead-in to language support. Language support features like ChromaCoding
(lexical coloring for keywords, comments, etc), template expansion, and smart
indenting are essential when editing source code. If those features are not
immediately apparent during editing, it will be necessary to understand the process
for turning them on or creating them.

View Themes: Colors, Window

Attributes, Scrollbars, Fonts, Etc.
All items that pertain to CodeWright's visual environment, such as colors, scroll bars,
line numbers, and window settings, are part of CodeWright View Themes. View
Themes are controlled and manipulated in the View Themes dialog, which is
accessed by clicking on the Tools|Customize|View Themes menu option. There are
four tabs on the View Themes dialog: General, Visibles, Font and Colors.
n Use the General tab to set window attributes like scroll bars (with scrollbars
come 'notches' for window-splitting functionality), line numbers, and margins.
Use the Highlight Current Line option (in combination with the Use
Background Only option on the Colors tab) to maintain font style and
foreground colors.

5- View Themes and Language Support 69

n Use the Visibles tab to manipulate "visibles", a term used to describe the
characters that can be used to make invisible characters, such as spaces and tabs,
appear on the display. To turn visibles on, mark the Visibles option. To give the
Visibles a slightly softer color, mark Use Visibles Color. The main listbox lists
the characters that are currently being used for display. The characters can be
changed using the combo-box just above the list of visibles.
n Use the Font tab to change screen fonts only. The fonts selected in the dialog do
not affect printed documents. The print dialog has separate font settings for
that. Items to note:
3 Font styles can be combined.
3 The font style for individual screen elements can be changed, but only
when the selected font supports the styles.
Note: Many of the View Themes, including “Default”, are set to use the
'Fixedsys' font. This gives two benefits: ChromaCoding font styles
now display when first installed, and users that need the extended
umlaut (European) characters are supported by default.
n Use the Colors tab to change screen colors. Colors can be changed for all text
colors (i.e. the background as a whole) using the Synchronize text background
option, or for individual screen elements only by selecting the element and then
changing the colors.
Background and foreground palette colors can be changed (up to 16-million
colors if your display supports it). Several default View Themes are provided to
illustrate this feature (see the drop-down list in the View Theme field).

View Themes: Colors

70 5- View Themes and Language Support

Any combination of changes (whether the changes are color and font, window and
color, Visibles and color, etc.) made in the View Themes dialog can be saved using
the Save As button. Just click the Save As button, and give the View Theme a new or
existing name. Different View Themes can be selected from the drop-down list
under the View Theme combo box.
Any View Themes can be restored to the settings that were made prior to entering
the dialog, using the Reset button. The Defaults button returns only the “Default”
and “Output Window” View Themes to their defaults. The Test button displays the
latest changes to the current CodeWright screen. The Apply button brings up the
Apply View Theme dialog, which allows the selected View Theme, with any
changes, to be immediately applied to the Current Window or All User Windows, or
to be made the Default View Theme.

CodeWright View Themes

CodeWright supplies several View Themes out-of-the-box. They are listed for
selection in the drop-down list under the View Themes combo box. Many supplied
View Themes have '(16-bit)' as part of their names. This means more than 256 colors
are needed to reproduce the palettes (16-bit color is the same as 65536 colors).

Among the list of View Themes, the Default and “Output Window” items are of
particular interest. Both of these View Themes affect windows in a particular way
and have additional screen elements available for modification.
Note: Screen elements are the elements on the CodeWright screen whose
colors can be changed. Examples of screen elements are functions
and keywords for supported programming languages. Screen
elements are listed in the Screen Element list in the View Themes
dialog.
n If the Default View Theme is selected, additional screen elements are available
for controlling colors and fonts of system elements such as the status bar. The
items are in the System group at the bottom of the list.
n If the “Output Window” View Theme is chosen, additional screen elements are
available for controlling window attributes of the Output Window.

Default View Theme

The Default View Theme is the View Theme that is initially associated with all
CodeWright windows. As with any View Theme, changes made to the Default View
Theme affect all windows associated with that View Theme. All new windows use
the Default View Theme or one chosen in the Tools|Customize|Language|Coloring
dialog. You can also change how View Themes associate with windows using the
Document/Window Manager or Apply View Theme dialogs.

5- View Themes and Language Support 71

If you would like to use settings from another View Theme as the default, use the
Save As button in the View Themes dialog to save the selected View Theme as
“Default”.

View Themes that are not named "Default" can be made the Default by marking
Make Default in the Apply View Theme dialog while the desired View Theme is
selected in the View Themes dialog.

Using View Themes

As mentioned, windows in CodeWright are initially associated with the Default View
Theme. To use any other View Theme, it must be associated with a CodeWright
window and/or file extension. With this in mind, consider or do the following to
change the colors and window attributes of a window, set of windows, or file
extension:
n Change the options for the Default View Theme in the View Themes dialog in
order to change the colors, fonts, and other window attributes of the window(s)
and/or file extension(s) associated with the Default View Theme.
n Associate any View Theme with the current (on top) open window by selecting
the View Theme and then marking Current Window in the Apply View Theme
dialog (accessed by clicking Apply in the View Themes dialog).
n Associate any View Theme with selected open windows by choosing the View
Theme for the selected windows in the Document/Window Manager dialog.
n Associate any View Theme with all open windows by marking All User
Windows in the Apply View Theme dialog (accessed by clicking Apply in the
View Themes dialog).
n Associate any View Theme with windows (open or not) containing files of a
certain file type (i.e. .C, .H, .CPP, etc), by choosing the View Theme for the
selected file type in Tools|Customize|Language|Coloring.

Since much of the language support in CodeWright involves colors, and View
Themes have something to do with color, CodeWright language support is described
next.

CodeWright Language Support

CodeWright's language support can consist of the following elements:
n ChromaCoding
n Template Expansion
n Smart Indenting
n Brace Expansion

72 5- View Themes and Language Support

CodeWright supports an extensive collection of languages out-of-the-box; there are
also some languages for which language support Add-Ons are available but not
loaded. In those cases, a simple procedure for loading the Add-Ons is all that is
required to enable the support. Ultimately, support can be made for any
programming language through the creation of ChromaCoding Lexers and
language Add-Ons. The following topics discuss lexers and Add-Ons, and the
various ways they are configured to provide support for languages that are not
immediately supported by CodeWright out-of-the-box.

Language Support Lexers and DLL’s

The first thing any programmer expects to see when loading source code files into
CodeWright is color, or ChromaCoding, for the syntax elements of the source code's
language. A programmer might also expect other language support features, such as
template expansion, to be immediately available. Depending on the language,
however, this may not always be the case.

Some languages are supported by default in CodeWright. For example, when files
with .C extensions are opened in CodeWright, ChromaCoding is immediately
apparent and template expansion can be enabled and used by marking a single
option in the Tools|Customize|Language dialog. In this sense, files with .C file-type
extensions are supported by CodeWright out-of-the-box. When a language is
supported out-of-the-box it often gets its functionality from CodeWright's
CWSTART.DLL, which loads automatically each time CodeWright is launched.
For language support that is available but not loaded out-of-the-box, there are two
options:
n The support can be obtained from external Add-Ons (DLLs) which must be
loaded manually,
OR
n The support can be obtained from a Lexer, that can be created and/or modified
in the ChromaCoding Lexer Settings dialog.

The topics that follow describe the two methods for adding language support to
CodeWright. CodeWright language DLLs are covered first, followed by a discussion
of CodeWright ChromaCoding Lexers. When reading the following information,
keep in mind that ChromaCoding Lexers are the easiest way to create new language
support for CodeWright. ChromaCoding provided by lexers is also faster, meaning
that color display will be smoother. However, lexers do not support Smart Indenting,
Template Expansion, or Brace Expansion. These features are provided by other
means.

It is possible to use Add-Ons together with lexers. In such cases, the lexer's
ChromaCoding functionality will take precedence, but the Add-On will still provide
other language support features.

5- View Themes and Language Support 73

Language DLLs
When language support is obtained from a DLL, the first thing to do is make sure
that the DLL for the language is in the CodeWright directory. Some language
support DLLs are already in the CodeWright directory. Many more can be found on
CodeWright CDs, or can be downloaded from our web site:
n On our web site (www.codewright.com), the support comes in the form of a zip
file containing the supporting DLL, some source code, perhaps a keyword file
and a README file.
n On CodeWright CDs, you can find the same Add-On files in unzipped format in
the \SUPPORT directory.

Tools|Customize|Libraries
After making sure that the appropriate DLL is in the CodeWright directory, the
library needs to be loaded. CodeWright libraries (including language support) are
loaded using the CodeWright Tools|Customize|Libraries dialog. The DLLs will add
functionality to CodeWright, whether that functionality is language support, or
some other feature.

Some Add-Ons are listed in the Libraries dialog, in the list of CodeWright Libraries.
If a language is not supported out-of-the-box, the first place to look is in the list of
CodeWright Libraries. Loading a library from the list is as simple as putting a
checkmark next to the item to be loaded. If the language is not listed explicitly, it may
be available in the \Support directory of the CodeWright CD, as mentioned. The
library can be loaded by clicking Add and browsing for the appropriate DLL. When
loading an Add-On from the CD, it is a good idea to first copy the Add-On to a
directory on your local hard drive (preferably the CodeWright installation directory)
so that it will be available after the CD has been removed. For more information
about the Libraries dialog, see the topic Tools|Customize|Libraries: Loading CodeWright
Add-Ons in the chapter on Command Key, Libraries and General Environment.

ChromaCoding Lexers
ChromaCoding Lexers provide language support (i.e. ChromaCoding) for
programming languages being edited in CodeWright. They store collections of
settings to color various elements of the programming language's "vocabulary".
Those "vocabulary" elements include identifiers, braces, preprocessors, keywords,
operators, strings and comments.
Lexers are the easiest way to add support for a language that CodeWright did not
previously support. ChromaCoding Lexers can be created or modified in the
ChromaCoding Lexer Settings dialog.

74 5- View Themes and Language Support

ChromaCoding Lexer Settings

There are two ways to access the ChromaCoding Lexer Settings dialog:
n Click the ChromaCoding Lexers item on the Tools|Customize dialog.
n Click the Settings button on the Tools|Customize|Language|Coloring dialog.
Some lexers are provided in the drop-down list under the ChromaCoding Lexer
Settings dialog's Lexer: combo box. Default settings on the tabs of the
ChromaCoding Lexer Settings dialog will vary depending upon the lexer selected.

If a desired lexer does not exist, it can be created.

Creating a Lexer
To create a Lexer, complete the following sections:
n Make a Lexer Name.
n Define Identifier/Brace Characters and Text to Exclude from Coloring.
n Define Keywords.
n Define Comments.
n Define String Delimiters.
n Define Numbers.

Make a Lexer Name

To make a Lexer Name:
1. In the ChromaCoding Lexer Settings dialog click New.
2. Type a descriptive name for the lexer and click OK to exit the dialog. A
new Lexer will appear in the Lexer: combo box.

5- View Themes and Language Support 75

 Define Identifier/Brace Characters and Text to Exclude from Coloring
On the General tab of the ChromaCoding Lexer Settings dialog, define
identifier characters and brace characters for the language, and any text to be
excluded from coloring by this lexer.

After the lexer name has been created, identifier characters must be defined.
Identifier characters are characters that distinguish “identifiers” from other
elements of the language. Identifiers can best be described as a set of characters
used to make up the "words" of the language. Keywords and function names are
identifiers, but operators are not. If identifier characters are not defined,
ChromaCoding for identifiers will not work.

ChromaCoding Lexer Settings|General

Character classes (described under the topic Regular Expressions in the chapter on
Search and Replace and Navigational Tools) can be used when defining identifier
characters.
Example: A-Za-z$
A-Za-z0-9$
Note: Certain regular expression characters must be escaped with a back
slash (\) in order to use them literally. For example, to specify a dash
(-) character as an identifier character, enter it as \-.
There are three fields in the Identifier Characters section:
n The First field is for characters that will normally appear as the first
character of an Identifier.
n The Follow field is for characters that will normally follow the first
character of each Identifier.
n A checkbox that indicates whether Identifiers followed by parentheses are
functions (like C++).

76 5- View Themes and Language Support

 The options in the Brace Characters section apply to certain languages only and
indicate the following:
n If braces are used, which ones should be colored.
n Whether the first two braces defined should delimit keywords, numbers,
and strings for coloring (i.e. elements are only colored when surrounded by
braces, like HTML).
Mark the Exclude Coloring Text with Regex option to allow text that matches
the regular expression you enter to be skipped over by other coloring
definitions. Define the regex expression with the following fields:
n Expression: The regular Expression pattern is used to parse matches from
files that use the corresponding ChromaCoding lexer. The lexer will then
exclude from coloring the parts of the matches designated by the reference
groups within the pattern.

3 Press (the Regex Assistant) to display a menu of the regular

expressions available, with an explanation for each. When you select
an expression from the menu it is appended to the contents of the edit
box.
3 The word [illegal] will appear above the edit box if the pattern in the
box is not a valid regular expression. The word [OK] will appear if the
regular expression is valid.
3 It might be helpful to create the regular expression in the Search dialog
so you can readily see what is matched. Once the pattern has been
created, it can be pasted in the Expression box.
n Groups: Place one or more space-separated numbers in the Groups box to
indicate which reference groups in the Expression box should be used to
match strings that are to be excluded from coloring.
If no reference groups are specified, the whole expression in the Expression
box will be used. If more than one group exists in the pattern, only the
groups that are specified by the numbers in the Groups box will be used.
Note that reference groups in regular expression patterns are counted from
left to right starting at 1.
n Ignore Case: Mark Ignore Case to have any occurrence of a match by the
Expression pattern excluded from coloring, regardless of case (upper, lower
or mixed).
n Maximal Match: Mark this box to indicate that regular expressions should
match the largest possible unit. If this box is not checked, regular
expressions will match the smallest possible unit, which in some cases may
be 0 characters.
n Whole Word: Mark Whole word to have the ChromaCoding lexer exclude
from coloring only matches that are surrounded by whitespace or Word
Delimiters.

5- View Themes and Language Support 77

 Define Keywords
On the Words tab of the ChromaCoding Lexer Settings dialog, add any
keywords, operators (e.g. +,-,*,&), or preprocessor words (if appropriate) that
the ChromaCoding Lexer should color.

ChromaCoding Lexer Settings|Words

Use the following steps to add words:

1. Choose the radio button for the group (i.e. Keywords, Operators, etc)
that the items will be added to.
2. Click the New button on the left.
3. In the resulting Add Words dialog, type the appropriate character(s)
for the word to add.
Notes:
3 Items can be deleted from a list by selecting the item and pressing
Delete.
3 The Get button adds items from a file. Click it to bring up the Get
Words from File dialog. Use the Get Words from File dialog to
browse for the file containing the items to be added. The Get
Words from File dialog can only read whitespace-separated
words. It can not differentiate words from other characters like
parentheses, colons, etc.
3 Added items will display in the center list-box.
3 The Edit button can be used to modify one or more words in a list.
3 "User…" items are for user-defined keywords, which can be
colored differently than the Keywords items. (Colors are set in the
View Themes dialog, described in the previous topic on View
Themes: Colors, Window Attributes, Scrollbars, Fonts, etc.)

78 5- View Themes and Language Support

 3 The option Identify words with regex in ChromaCoding Lexer
Settings|Words is for file types (languages) that allow keywords
to be recognized that may be specific to a document, but are not
part of the language definition.
Since these dynamic keywords may vary from file to file, there is
no way to define a list of them for the ChromaCoding lexer.
Because of this, the lexer will not be able to color them in
CodeWright.
Identify words with regex solves this problem. It enables
controls and an edit box that are used to define and configure a
regular expression; the regular expression parses words from
files that use the corresponding ChromaCoding lexer. The lexer
will then know which words to color.
It might be helpful to create the regular expression in the Search
dialog so you can readily see what is matched. Once the pattern
has been created, it can be pasted in the Expression box.
3 The List Settings section has items that apply to whole lists of
keywords (i.e. if Keywords is chosen, the options apply to the list
of keyword elements, if Operators is chosen, the options apply to
the list of operator elements). Certain items apply only to certain
lists. For example, Allow White After First (which causes
preprocessors to color even if whitespace appears after the first
character) can be used for lists of Preprocessors only.
3 The Item Settings section has options that only apply to
individually selected items.
3 Certain checkboxes on the Words tab apply only to certain sets.
For example, Ignore Remainder of Line is only available for the
list of Preprocessor keywords. This option tells the Lexer not to
ChromaCode any text after the selected preprocessor. It is handy
for languages like C++ that have preprocessor lines like:
#include "exports.h"
where "exports.h" would otherwise be incorrectly colored as a
string.

(Refer to the CodeWright online help for additional information on the options
available on the Words tab.)

Define Comments
On the Comments tab, define all the appropriate comment delimiters for each
comment set. The configurations made in this dialog will tell the
ChromaCoding Lexer when to color comments.

5- View Themes and Language Support 79

 ChromaCoding Lexer Settings|Comments

To define single-line comment delimiters, click the Add Line Comment button.
To define multi-line comment delimiters, click Add Multi-line Comment. Each
time either of the buttons is clicked, the Begin Column or Use Delimiter options
become available, depending on which radio button is chosen at the time.
n If a single-line comment is being added, the right side of the Use Delimiter
section is not available.
n If a multi-line comment is being added, the Begin Column option will not
be available.
Finish setting up the comment support by completing the fields and command
options that apply to the characteristics of the comments for the language in
question.

(See the CodeWright online help for more information on the Comments tab.)

Define String Delimiters

On the Strings tab of the ChromaCoding Lexer Settings dialog, choose the
options necessary to tell the ChromaCoding Lexer how to color quoted strings.
For coloring quoted strings, select Single and mark the appropriate options to
control how coloring for single quoted strings should be handled. Then select
Double and mark the appropriate options to control how coloring for double
quoted strings should be handled.

If the language in question does not use quoted strings, mark the option that
specifies that Quote does not start a string (for Single and/or Double quoted
strings).

80 5- View Themes and Language Support

 ChromaCoding Lexer Settings|Strings

Mark the option Identify strings with regex, and complete the enabled fields, to
more flexibly define which strings to color using regular expressions. These
fields work to identify strings in much the same way as the regex fields defined
previously under Define Identifier/Brace Characters and Text to Exclude from
Coloring.

Define Numbers
On the Numbers tab, define any numbers that should be colored by the
ChromaCoding Lexer for the language in question. The available number types
are:
n Float
n Hexadecimal
n Decimal
n Octal
n Binary
n Regex
n No Type

The number types only serve to identify an entry. They are there for
convenience. When one of the types is chosen, the most appropriate number set
is automatically inserted in the Digits field. The name of the chosen type is also
displayed, for reference purposes, beside the number set in the Numbers List
Box. The other settings in the dialog control how the elements are
ChromaCoded by the lexer.

5- View Themes and Language Support 81

 Note: If you have selected Regex as the number Type, you will see options
in the Characters group that can be used to more flexibly define
which numbers to color using regular expressions. These fields work
to identify numbers in much the same way as the regex fields defined
previously under Define Identifier/Brace Characters and Text to Exclude
from Coloring.

ChromaCoding Lexer Settings|Numbers

Use the following steps to define number elements:

1. Click Add Number, then choose the number type to be applied. A new item
will appear in the list box at the top of the dialog.
2. Add the numbers to the Digits field.
3 Character classes (such as 0-9, indicating all numbers between 0 and 9)
can be used.
3 Commonly used character classes for the selected number type can be
quickly inserted using the popup menu displayed with the right-arrow

button , to the immediate right of the Digits field.

3 For each added set of numbers, beginning and ending characters can
be specified for the ChromaCoding Lexer using the Starts With and
Ends With fields. This is for programming languages that delimit
numbers with specific starting or ending characters.
The Starts With and Ends With fields also have right-arrow buttons to
access popup menus containing commonly used beginning and
ending characters.

82 5- View Themes and Language Support

 3 The Restrict first digit to 0-9 option is available when using the Ends
With field. It restricts the lexer to color numbers that end with specified
characters only if the first digit is numerical.
3 The field labeled Optional end characters specifies that
ChromaCoding include the characters in the box when coloring any
numbers that end with them.

Completing the Lexer

When all the appropriate language characteristics have been added to the Lexer,
click OK for the dialog.
If you want to delete a lexer, choose it from the drop-down list under the Lexer:
combo box at the top of the ChromaCoding Lexer Settings dialog, and click the
Delete button.
Click Cancel to undo any changes made during the current session of the
ChromaCoding Lexer Settings dialog.

Configuring Options in the Language Dialog

Whether language support is obtained from a language DLL or a ChromaCoding
Lexer, the configurations for the language need to be set up. This is done in the
Tools|Customize|Language dialog.

The Language dialog is where all CodeWright's language features are stored and
controlled. CodeWright language features consist of settings and support that are
associated with file type extensions (i.e. .C, .TXT, .ASM, etc). The available features
vary depending on the extension of the file.

Tools|Customize|Language

5- View Themes and Language Support 83

Some of the options in the Language dialog are available for any file type, while
others are only available for file types for which a language support module is
available. If a language support module does not provide support for a particular
feature in the dialog, the feature will not be available.

The Language dialog has seven tabs, which will be described here, along with a few
other elements of the dialog.
Note: The main thing to remember when making changes in the Language
dialog is that the changes are file-type specific. That is, the
customizations that you make in any tab of this dialog will only be
applied to the extension that is selected in the Customize dialog
navigation tree at the time of the change.

File Types
All of the available file types for CodeWright are listed under
Tools|Customize|Language in the Customize dialog navigation tree.
A file type is the extension of a given file (e.g..c). It is used for selecting the file type
whose settings will be viewed or modified. The file type associated with the current
document is selected initially, if it is in the tree. If it is not in the tree, it can be added,
or the default settings (indicated by file type .*) will apply.

Options Tab
The Tools|Customize|Language|Options dialog has options for controlling certain
attributes and functions for files of the selected type. Some of the options available
are as follows:
n Read-only controls whether files of the selected type should be opened as read-
only.
n Make backups controls whether backup files should be made for files of the
selected type.
n EOL options control whether UNIX, DOS, or Mac EOL characters should be
inserted when the E key is pressed in files of the selected type.

n Word Wrap options control whether and how text should be wrapped in files of
the selected type.
n Virtual Space options control whether a cursor can be placed inside a tab, after
the end of a line, and/or after the end of a file for the selected file type.

Many of the features in the Language|Options dialog are also available on a per-
document, non-file-type-specific basis, in the Document/Window Manager dialog.

84 5- View Themes and Language Support

Tabs/Indenting Tab
The Tabs/Indenting tab of the Language dialog has options for controlling and
customizing how CodeWright handles tabs and auto-indenting. It also offers a
choice of several popular forms of block Alignment Styles which are used when
inserting templates and/or when using brace expansion. The available alignment
styles are:
n Unindented Block
n Line Saver
n Indented Block

Most of the features in the Language|Tabs/Indenting dialog are also available on a

per-document, non-file-type-specific basis, in the Document/Window Manager
dialog.

Templates Tab
The Templates tab of the Language dialog is for turning on, examining, deleting and
redefining language templates associated with the selected extension. More
information about templates is available in the chapter on Editing & Printing.

Coloring Tab
The Coloring tab of the Language dialog has options for controlling how
ChromaCoding operates. It is also where CodeWright is configured to provide
ChromaCoding support for languages that are embedded in other languages. The
items in the dialog that are of special interest are the Lexer and DLL options, and the
Embedded Languages and Scripts section.
n Mark the Lexer radio button to make the Lexer options available and to cause
the combo-box to display the currently selected Lexer, as described in the
section on ChromaCoding Lexers. ChromaCoding lexers maintain numerous
settings that add support to and for programming languages edited in
CodeWright. To choose a different lexer, select it from the drop-down list under
the combo. The lexer displayed in the combo box will be associated with the
selected file type in the Customize dialog navigation tree.
The Settings button can be used to access the ChromaCoding Lexer Settings
dialog, used for making new ChromaCoding Lexers. The dialog can also be
accessed by clicking the ChromaCoding Lexers option on the Tools|Customize
dialog.

5- View Themes and Language Support 85

n Mark the DLL radio button to have CodeWright use a DLL, rather than a lexer,
for language support. Marking the DLL option enables two additional buttons.
3 The Keywords button accesses the DLL Extension Keywords dialog, used
for defining and editing a file of keywords to supplement the ones
predefined by the DLL.
3 The Coloring button accesses the DLL Coloring dialog, used for controlling
ChromaCoding color-timing and the number of comment lines that will be
colored. If there is no DLL loaded for the selected file type, the DLL radio
button will be unavailable.
These buttons are not available when the Lexer option is chosen.
n The Embedded Languages and Scripts section has the following components
and rules:
3 The Configure button accesses the Embedded Language Configuration
dialog. The button will not be available if the selected file type does not use
a ChromaCoding lexer for ChromaCoding support.
The Embedded Language Configuration dialog uses regular expressions to
parse programming languages that are embedded in other programming
languages (e.g. JavaScript in an HTML file). It then colors the embedded
language using a designated ChromaCoding lexer. Other language support
features, such as template expansion, are also provided. With the proper
configurations, CodeWright will be able to distinguish the embedded
language from the main language, and provide support for both.
Help for the dialog is available online, under the topic Embedded Language
Configuration. See the topic Regular Expressions in the chapter Search and
Replace and Navigational Tools for help with regular expressions.

Embedded Language Configuration

86 5- View Themes and Language Support

 3 <not defined> will appear if no embedded languages have been defined
for the file type. <n defined> will appear if one or more embedded
languages have been defined, where n is the number of defined languages.
3 There must be an existing ChromaCoding lexer that provides color support
for the embedded language in order for the embedded language
configuration to work. If an appropriate lexer does not exist, it can be
created in the ChromaCoding Lexer Settings dialog.
3 The option Color sections with 'override' color in Tools|Customize|
Language|Coloring allows different color/font style combinations to be set
for blocks of embedded code in the selected parent language. It uses the
screen elements "Override 1", "Override 2" and "Override 3" that are
defined in Tools|Customize|View Themes|Colors. Commonly "Override"
elements are set to Use color: Background. This allows embedded code
blocks to be highlighted with the override color but still show the
foreground colors and font styles for the language that colors the
embedded section.
From the Embedded Language Configuration dialog, add an "Override"

color by selecting a lexer and pressing , or by pressing to add a new

lexer.

CodeSense Tab
The CodeSense tab of the Language dialog is used for selecting and manipulating
the Name Completion, Outline Symbols, and CodeSense features. These features
parse specified text from files being edited, which is then used for editing or
navigational purposes. More information about Name Completion and CodeSense
can be found in the chapter on Editing & Printing. Symbols are described in the
chapter on Search and Replace and Navigational Tools.

Format Tab
The Format tab of the Language dialog contains options for code reformatting or
beautifying. These options are used by the Format Source item on the Text menu.
Format Source is explained in more detail in the chapter on Checking and Reformatting
Files.

Comments Tab
The Comments tab of the Language dialog is for setting the parameters for the
Comment and Comment Box menu items on the Text menu. The Comment features
are explained in more detail in the chapter on Editing & Printing.

5- View Themes and Language Support 87

Adding a New File Type to the Language
Dialog
Before CodeWright can color a file, it has to know the file's type (i.e. .C, .TXT, etc).
Usually the file type will already be defined, but not always. If it isn't defined, it will
need to be added for the Language dialog. Do the following to add a new file type
and then associate it with language support:
1. Go to the Tools|Customize|Language dialog.
2. Select New Type and add the extension for the language (without the '.', which
is automatically added). Once the file type has been added, select it in the list of
file types in the Customize dialog navigation tree.
3. In the same dialog, select the Coloring tab.
n If the file type will be getting its ChromaCoding support from a Lexer, select
the Lexer radio button and choose the appropriate Lexer from the Lexer
combo-box to associate it with the selected file type.
n If the file type will be getting its ChromaCoding support from a DLL, mark
the DLL radio button.
4. Once the language support method has been established, check and configure
the options on Tabs/Indenting tab (these features will be covered in the chapter
on Editing & Printing) and on the Coloring tab to enable language-specific
editing features and coloring for the file type.

When a source file with the new extension is opened, syntax colors (ChromaCoding)
should be visible. Other features that the corresponding Add-On or lexer has been
designed to support should also be available.

Aliasing
If there isn't a language support DLL for a particular file type, you can add support
by creating a lexer (described in the previous section) or creating a DLL. There is
information on creating a language DLL in the appendix on Making and Modifying
CodeWright DLLs.

An alternative way to add language support is to alias the unsupported file type
with a supported one. If the code style of the unsupported language is similar to one
that is supported, all the templates, keywords and coloring for the existing file type
will be used by the unsupported file type. Keywords can be added to the supported
file type's list for additional coloring.

To alias, or map, a file type to one that already exists:

1. Go to the Tools|Customize|Language dialog and press the New Type button.
2. Add the _new_ file type.

88 5- View Themes and Language Support

3. Highlight the _new_ file type in the list of file types on the left.
4. Press the Map Type To button and enter the file type that will be the alias for the
unsupported language.
5. Save and exit the dialog.
When source files of the unsupported extension are opened, they will use the
language support of the file type they are mapped to.

Some of the tabs in the Language dialog will be unavailable for mapped or aliased
files. This is because mapped file types use the language-specific functions of the
type to which they are mapped. In such cases, mapped file types can only be
changed by changing options for the original file type to which the unsupported
language is mapped.
Note: You can override the extension of a selected file, effectively creating
an alias on a per-file basis. To do this, highlight the name of the file
on the Document/Window Manager|General dialog, and choose the
desired file type from the Extension Override drop-down list.

Creating a Language Support DLL

If there is no Add-On available to support the programming language you are
editing, it is possible to make one. In the CodeWright SDK, you can obtain resources
to create new DLLs, and resources to modify existing fundamental DLLs. Refer to
Appendix B - Making and Modifying CodeWright DLLs for more information.
Note: If you need more information about how to obtain the
CodeWright SDK, please contact a Sales Representative at
[email protected].

5- View Themes and Language Support 89

90 5- View Themes and Language Support
6- Editing & Printing
This chapter covers many of the special features in CodeWright that help make
editing easier. Things like Template and Brace Expansion will be covered extensively.
Functions and dialogs used for inserting Comment Boxes, File and Function
Headers, CodeFolio Snippets and completed API functions (CodeSense)will also be
discussed, along with “hex-mode” editing and COBOL, HTML and XML features.
The chapter also describes the Print dialog and explains the process for configuring
the online help to access help from different environments.

Templates and Brace Expansion

Refer to the following discussion of Templates, Template Macros, CodeFolio
Snippets, and Brace Matching and Expansion.

Templates
Templates may be language-specific (i.e. associated with a particular programming
language) or language-independent. They are useful for taking the drudgery out of
repetitive editing tasks. They are designed to insert frequently-used text into files at
the press of a button, or to automatically expand common statements used in
programming languages when appropriate abbreviations are typed.

Language Specific Templates

Language specific template expansion is activated on a per-file-type basis in the
Tools|Customize|Language|Templates dialog.

6- Editing & Printing 91

Tools|Customize|Language|Templates Dialog

To use it, highlight the appropriate file type and mark the Template Expansion
option. Templates work as follows (using C++ "if" statement as an example):
Example: Type if, and then press the space bar.
The appropriate ending statement and any necessary parentheses,
curly braces, etc., will be inserted in the appropriate positions for the
statement, like so:
if ()
CodeWright templates have a macro capability that makes them useful for much
more than just language constructs. The next sections go over the necessary
information for creating templates used for language constructs and describe the
advanced features provided by template macros.

Creating and Modifying Language Specific Templates

Before adding or changing a template, it is a good idea to become familiar with the
templates that are already defined. CodeWright associates templates with the file
type of any given programming language in order to make them language-specific.

Two methods are provided for adding template constructs, or changing existing
ones:
n Templates defined for a particular file type can be viewed, added and changed
on the Tools|Customize|Language|Templates dialog. Use the dialog to see,
create and modify the abbreviations that trigger template expansion and the
string values associated with them.
n Add templates by directly editing the CodeWright configuration file. Use a call
to ExtAssignTemplate under the [Templates] heading of the CWRIGHT.INI
file. ExtAssignTemplate is a CodeWright API.

92 6- Editing & Printing

 There are three string parameters used by ExtAssignTemplate. The first tells
what file extension to associate the template with (e.g., .C, .SC...). The second
specifies a word or abbreviation that is to trigger the template expansion, for
example "if", "else", and so on. The third string is the template itself.
For more information:
3 Help for CodeWright APIs can be found online using the
Help|CodeWright API Library menu item.
3 More information on CWRIGHT.INI is provided in the chapter on
Configuration Files & Command Line Parameters.

There are special characters defined for use in language templates that give
CodeWright useful instructions. The following table defines those characters:

Character Purpose

\n New Line. Simulates pressing E at this

point.

& Specifies cursor position after template insertion.

@ Issues a backspace.

\c Inserts ‘c’ literally, (e.g., \&, \@, \\)

\t Inserts a tab.

Most templates will take up more than one line in the document. There is a need,
therefore, to specify the locations of new lines in the template string. In most
templates, you will also need to specify a location in which the cursor is to be placed
after the template is inserted.

Examples:
Here are some sample template strings that give an idea of how these special
characters are used to construct templates:

"if (&)\n{\n}"
"do \n{\n\t&\n}\n while( );"
"for (&; ; )\n{\n}"

Finally, here is how the complete ExtAssignTemplate line might look in the
configuration file:

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

6- Editing & Printing 93

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

Non-Language-Specific Templates, Function and File

Headers, and Macros in Templates
The templates described up to this point are language-specific. Templates that can be
used independently of a language’s file type extension will be described next.
Template macros (macros that perform specific functions inside templates) will also
be described. Note that template macros can be used in language- specific templates
as well as non-language-specific templates.

Two templates provided with CodeWright are prime examples of non-language-

specific templates. These templates insert C++ function and file headers into the
current document. Even though the headers contain C++ language constructs, they
can be modified, or new ones can be created, that will insert any kind of text,
whether for a programming language or not. The templates are contained in two
files in the CodeWright home directory named FILE.TPL and FUNCT.TPL.

Two buttons on the Edit toolbar are used to insert the contents of FILE.TPL and
FUNCT.TPL into the current document. The buttons use the function
ExtExpandTemplate to insert the templates. The same function can be used to insert
templates with any CodeWright button or keystroke. Details for the
ExtExpandTemplate function can be found in CodeWright's online help.
Note: The Edit toolbar is turned on by marking the Visible option for Edit
in the list of toolbars on the Toolbars tab of the Tools|Customize
|Toolbars dialog.
To see examples of how ExtExpandTemplate is used, take a look at the function
bindings for the function and file header buttons on the Edit toolbar. The function
bindings for the toolbars can be viewed on the Bindings tab of the Tools|Customize
|Toolbars dialog. To view the function bindings, highlight the Edit item in the list of
toolbars and scroll through the toolbar's buttons in the right window. As you scroll
through the buttons, you will see the function binding for each button in the
Function Bindings edit box at the bottom of the dialog. The first two buttons on the
Edit toolbar are the buttons that insert the headers. The function binding for the
function header appears like this:
ExtExpandTemplate %ffunct.tpl$
This command uses the %f template macro to insert the contents of FUNCT.TPL. The
contents of FUNCT.TPL will make up the function header. The trailing $ is used to
delimit the filename string.

94 6- Editing & Printing

The function binding for the file header appears like this:

ExtExpandTemplate %ffile.tpl$

Note that the two function bindings are exactly the same except for the names of the
template files. Template macros are described next.

Template Macros
True to their name, template macros like %f can also be used within templates.
FUNCT.TPL contains the '%q' macro. When it is expanded, it presents a prompt that
queries the user for information, which will be used when the template is inserted.
In the following examples we show before and after shots of FUNCT.TPL after it has
been modified with extra template macros, to illustrate their use.

Example: FUNCT.TPL without modifications:

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

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

Example: FUNCT.TPL with modifications:

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

6- Editing & Printing 95

 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 of a header that was added by the expansion of

the modified template file:

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

These are just a few of the things that can be done with template macros. A table
containing a complete list of the % template macros available follows:

Macros in Templates

% Macro form Description

%colNum Move the cursor to column Num of the current line.

%date Insert a date string at cursor position. (mm/dd/yy format)

%db Delete to the beginning of the line.

%dcNum Delete Num characters at cursor.

96 6- Editing & Printing

 Macros in Templates

% Macro form Description

%de Delete 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.

%lineNum Move the cursor to the line named by Num.

%mdNum Move down Num lines.

%meof Move the cursor to the end of the file.

%meol Move the cursor to the end of the line.

%mlNum Move the cursor left by Num columns.

%mrNum Move the cursor right by Num columns.

%muNum Move up Num lines.

%Num When Num is 0 to 9, it refers to a user-definable string that

may be 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.

%open Open a new line following the current. Similar to going to the
end of the line and pressing E .

%qPrompt$ Query for string to insert, using the string Prompt to prompt
the user.

%repCNum Insert Num repetitions of character C.

6- Editing & Printing 97

 Macros in Templates

% Macro form Description

%response Insert data acquired from %q macro. Allows the data to be

used more than once. More than one response can be used by
adding a number to the end of the macro, e.g. %response1.

%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 position cursor at the first character of the file.

%xFuncCall$ Execute the CodeWright API function call in FuncCall. This

may be any function that could be assigned to a key or
otherwise executed through LibFunctionExec.

%-c Insert a filename, path, or portion thereof as indicated by

character c. This character can be any of the macro characters
used in CompilerAdd, ExecUserCmnd, and other functions
that use filename macros. Here are the characters available:
n b - Basename. The complete current buffer name, less
the extension.
n d - Directory. The directory component of the current
buffer. This component has no filename and no drive
element. It also has no trailing backslash.
n e - Extension. The extension of the current buffer. This
component begins with a dot ( . ) unless the extension is
null.
n f - Root.extension. The filename root and its extension.
No path or drive component are included.
n n - Project name. The name of the project, if one has
been defined and selected. Otherwise, this macro
expands to a null string.
n p - Path. The path component of the current buffer.
This component has no filename and no drive
component. It has a trailing backslash.
n r - Root. The filename of the current buffer, less the
extension.
n v - Volume. The drive component of the current buffer,
a letter and a colon.
n x - Project Path. The path component of the project file
currently in use (usually indicates the project directory).
n y - Project Root. The base filename of the project file
currently in use.

98 6- Editing & Printing

CodeFolio Snippets
CodeFolio Snippets are similar to templates, but more flexible in how they are used.
They are pre-defined portions of code or text that may be inserted into your current
document. The style/structure of code or text following a Snippet is unaffected.

Snippets have a default file extension of .TPL; configuration details for Snippets are
stored in the file CODESNIP.INI.

To see a directory of the Snippets that are shipped with CodeWright, click on the
CodeFolio tab of the Project Window. The directory tree is organized by language
type, as follows:

Project Window: CodeFolio Tab

In addition to using the Snippets that are shipped with CodeWright, you may add
your own Snippets to the existing directory structure, or add whole new directories
to the CodeFolio tab (refer to Adding or Removing Snippets Directories, in this chapter).
Snippets may also be edited to conform to your own needs (see Editing a Snippet, also
in this chapter).
3 The Snippets shown on the CodeFolio tab are also available when you create a
new document from the File|New menu item.

Using an Existing Code Snippet

You can insert a Code Snippet into either a new or existing document.

6- Editing & Printing 99

 Using a Code Snippet in a New Document
In the File|New (Create New Document) dialog, you can include a Snippet in
your document by doing any of the following:
n Double-click on a Snippet in the CodeFolio directory
n Highlight a Snippet in the directory and press Add Template.

n Highlight a Snippet and press .

The Snippet will be listed in the Use Templates area, and thus will be included
in the new document when you press OK.

Create New Document Dialog

If the template has a prompt for a name, an edit box to input that name will
display after the checkbox in the Use Templates group.
To remove a Snippet from the Use Templates group, highlight the Snippet and
press . You can also uncheck the Snippet’s checkbox to exclude it from the
new document.

To reorganize the templates to be inserted, highlight a template and press or

to move the template up or down in the list, respectively.

100 6- Editing & Printing

 Using a Code Snippet in an Existing Document
For an existing document, use File|Open to open the document into the Client
Area. Click on the CodeFolio tab of the Project Window. Execute a Snippet by
doing one of the following:
n Left-click on the desired Snippet and drag it to your file. The Snippet will
be placed where you drop the icon.
n Double-click on the desired Snippet. It will be automatically inserted at
your cursor position in the file.
n Right-click on the desired Snippet and select Insert from the popup menu.
The Snippet will be inserted at your cursor position in the file.

Code Snippet Examples

Following is an example of the CFUNCT.TPL snippet after it has been executed
in a new document:

C Function Header Snippet

/*
* FUNCTION: Test_Function
*
* PARAMETERS:
*
* DESCRIPTION:
*
* RETURNS:
*
*/

Other examples of Snippets include the following:

HTML Document Setup

<HTML>
<HEAD>
<TITLE>Test</TITLE>
</HEAD>
<BODY>
<H1>Test</H1>
</BODY>
</HTML>

6- Editing & Printing 101

 VBFUNCT.TPL
'---------------------------------------------------------------------
'
' ** Test
'
' Parameters:
'
' Description:
'
' Returns:
'
'
'---------------------------------------------------------------------

Creating a New Code Snippet

You may save portions of code that you have written as Snippets for later use.

Saving a .TPL File

To save a new or existing file as a Code Snippet, complete the following steps:
1. Create a new file.
2. Type or paste in the desired code.
3. Save the file with a .TPL extension in the CodeWright Snippets directory.

Creating a Snippet from the Current Document or Clipboard

You can paste selected text from the current document, or text from the
clipboard, and save that text as a new Snippet. Complete the following steps:
1. Copy the desired text to the clipboard, or select the text in your document.
2. Right-click on the Snippet directory in which to save the new Snippet, or
drag the selection to the appropriate Snippet directory folder.
3. The following menu displays:

4. Select Create Snippet from selection or Create Snippet from Clipboard, as

appropriate. The Code Snippet Properties dialog displays.

102 6- Editing & Printing

 Code Snippet Properties

5. Defining the following:

n Display Name: Assign a descriptive name for this Code Snippet. This
name will display on the CodeFolio tab and the File|New dialog.
n File Name: Enter the directory path and file name where the Code
Snippet should be stored on your system. When you drag text onto
the CodeFolio Window to create a Snippet, or create a Snippet from
the clipboard or current selection, you can leave the File Name
unchanged for automatic filename creation.
n Expand Macros: Execute template macros and display the results
upon insertion of the Code Snippet.
n Location: Select from the following options for this Code Snippet:
3 Indented: Insert and indent the Code Snippet based on the
indentation of the line at the insertion location.
3 At the caret position: Insert the Code Snippet exactly where the
cursor currently sits, even if that is mid-line.
3 At the beginning of the line: Insert the Code Snippet at the
beginning of the current line.

Deleting or Renaming a Snippet

You can delete or change the display name of a Snippet from the popup menu.
n To permanently delete a Snippet from your system:
1. Right-click on the name of the Snippet in the CodeFolio tab’s tree directory.
2. Select Delete.

6- Editing & Printing 103

n To reference the Snippet as a different name:
1. Right-click on the name of the Snippet in the CodeFolio tab’s tree directory.
2. Select Rename. The name of the Snippet should now be highlighted.
3. Edit the name directly.
Renaming a Snippet does not change the name of the underlying file; it only
changes the reference to the Snippet on the CodeFolio tab. To determine the
actual name of the Snippet file:
1. Right-click on the name of the Snippet in the tree directory.
2. Select Properties. The Code Snippet Properties dialog displays, with the
actual filename in the File Name field.

Editing a Snippet
If you wish to edit the actual content of a Snippet, complete the following steps:
1. Right-click on the name of the Snippet in the CodeFolio tab’s tree directory.
2. Select Edit Template from the popup menu. The Snippet is displayed in a
separate window.
3. Edit as desired. Select File|Save from the main menu to save your changes.
4. Close the Snippet file.

Adding or Removing Snippets Directories

You can add or remove a root level node from the tree directory on the CodeFolio
tab.
Note: To create or remove a subdirectory of an existing Snippets directory,
you must add/delete the folder outside of the CodeFolio tab (e.g.
from Microsoft Explorer).
To add a root level directory:
1. Right-click on the directory under which the new directory should be placed.
2. Select Add Directory from the popup menu.
3. Browse for and select the desired Snippets directory on your system.
A sample directory tree with a user-added directory named C# Snippets follows:

104 6- Editing & Printing

CodeFolio Snippets with User-Added Directory

To remove a root level directory:

1. Right-click on the directory you wish to remove from view.
2. Select Remove Directory from the popup menu.
When you remove a directory, you are not actually deleting the underlying files; you
are simply removing the directory and files from this view. When you delete the last
root-level directory, the system uses the default Snippets directory.

Brace Matching and Brace Expansion

Brace matching support in CodeWright works several ways:
n The current buffer is checked to see that braces are balanced. This form is useful
for checking syntax.
n The text between a set of braces is highlighted. This form is useful in visualizing
the scope of the block defined by the braces and indenting blocks.
n The matching brace is located and the cursor is moved to it, either momentarily
or permanently.

Brace matching is performed by functions assigned to keys or buttons. Several of

these functions are already available on buttons on the CodeWright Edit toolbar. To
turn on the Edit toolbar, mark the Visible option for the Edit toolbar on the Toolbars
tab of the Tools|Customize|Toolbars dialog. You may wish to customize these
assignments or make new assignments. Information on customizing buttons and
keystrokes is found in the chapter Custom Interface.

6- Editing & Printing 105

Brace Function: Finding Unmatched Braces
There is a function supplied with CodeWright, Brace(), that looks for unmatched
braces in the current buffer. All braces that are to be matched can be specified. One
way to invoke the Brace function is to use the CodeWright API Command Key. The
API Command Key accesses a prompt or dialog from which CodeWright APIs can be
interactively used to perform their associated function. To access the API Command
Key, use one of the following methods:

n Press @ if you are using the Visual Studio .NET keymap.

n Press ( if you are using the CUA keymap.

n Press ) if you are using the BRIEF-compatible keymap.

n Select API Command from the Tools menu.

The Command Key is described in more detail in the chapter Command Key, Libraries,
& Environment.

To match all curly braces within a file, respond to the Command: prompt as follows:

Command: Brace TRUE

3 To ignore braces in comments, just omit the TRUE parameter, or supply FALSE
as a parameter instead.

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

Brace Highlighting
There are two functions that examine or operate on the text between matching
braces:
n The first function is BraceMatchNext, which looks for the next left brace or
parenthesis, locates its mate, and then highlights the text between them. On
subsequent calls, this function will find pairs nested within the highlighted set,
or a pair following the highlighted set.
n The second function is BraceMatch, which operates similarly to
BraceMatchNext, except that it searches for a match to the brace at the cursor
position. If the curly brace at the cursor is a left brace or parenthesis, the
function searches forward for its mate. If it is a right curly brace or parenthesis,
the function instead searches backward for the mate. If neither a left nor a right
parenthesis or brace is at the cursor position, the function searches forward for
the next matching set. If the parameter to BraceMatch is omitted, it will look for
braces only.

106 6- Editing & Printing

 Note: Since BraceMatch looks at the current cursor position, it is not
effective for highlighting a series of blocks in sequence. Subsequent
calls will find the pair that is already highlighted.
Passing a non-zero parameter to either of these two functions will cause it to look for
matching parentheses in addition to curly braces.

Brace Locating
The function BraceFind is provided for locating the brace, parenthesis, or square
bracket that is the mate for the one at the cursor position. It does not create a
highlight, but just positions the cursor at the corresponding object.

The function also has a "kissing" mode that can be activated by giving the function a
TRUE or 1 value as a parameter. In this mode, the cursor moves to the
corresponding object, but only momentarily. After a brief pause, the cursor returns
to its original position. This provides allows you to verify that the appropriate block
or clause is closed.

BraceFindEx
BraceFindEx() is another brace-matching function that can be used from
CodeWright's API Command dialog (API Command on the Tools menu), or bound
to a button or keystroke.

BraceFindEx is an extended brace search and match function. It has a number of

flags that can be used together or individually for more flexible brace matching.
An example of how the BraceFindEx function is used follows:
Example: The following combination of flags works for finding braces within
quotes.
BraceFindEx BRACE_BRACES|BRACE_PARENS|BRACE_FORWARD

Brace functions are documented in CodeWright's online help (Help|CodeWright

API Library).

Language-Specific Brace Matching

What is considered a brace is also language-specific, allowing CodeWright to match
various brace/tag pairs. For Pascal, the keywords Begin and End are treated like
braces; CodeWright looks for Begin and finds the matching End. For HTML/XML,
tags are also included; CodeWright considers the current tag an open brace and
finds the matching tag.

Language-specific brace matching works as follows:

1. Based on the file extension of the current document, CodeWright calls the
appropriate brace matching function, if it exists. (e.g.
_pas_get_brace_search_str for Pascal)

6- Editing & Printing 107

2. These three APIs are called from within the brace matching function (e.g.
_pas_get_brace_search_str) to enable brace matching for your language:
BraceSetBraceSearchStr, BraceSetOpenSearchStr and BraceSetCloseSearchStr.
3. Once these have been called, you can optionally instruct CodeWright to also
match standard braces, parentheses, square brackets and angle brackets using
the API function BraceAugmentSearchStr.
Note: Refer to the online help in Help|CodeWright API Library for
assistance with these functions.

Brace Expansion
Brace Expansion is activated on the Tools|Customize|Language|Tabs/Indenting
dialog and works in the following way:
3 Type a brace. It is automatically positioned. The closing brace is instantly
inserted in the correct position and the cursor is placed between them.
Brace Expansion operates very much like the brace template in template expansion.
The difference between template expansion and brace expansion is that brace
expansion instantly inserts braces whenever the left brace ( { ) key is typed, while
template expansion doesn’t insert braces until the space bar is pressed. The sequence
used by template expansion may be unnatural for some programmers, and
therefore, brace expansion provides an alternative. Brace expansion may also be
useful for users who do not want full template expansion, but who want the benefits
of automatic brace insertion.
Note: When expanding a brace in column one, the template for “^{“ is
used.

Align Beginning and End of Block

Align <begin/end block> is a brace-expansion feature in CodeWright that
automatically positions language constructs that begin and end blocks (such as
braces in C and C++) as you type them.
Example: If the alignment setting on the Tools|Customize|Language|Tabs/
Indenting is set to Unindented Block, the closing block delimiter
will be aligned with the opening block delimiter as it is typed. This
will occur whether the closing delimiter is typed at column 3 or 30.
Align <begin/end block> is similar to Brace Expansion, except that it does not
instantly insert both the closing and opening block delimiters as they are typed. It
just realigns the closing block delimiter as it is typed. The checkboxes for Align
<begin/end block> are located on the Tabs/Indenting tab of the Tools|Customize
|Language dialog and are only available if the language support for the associated
file type supports it. The options for Align <begin/end block> and Brace
Expansion are mutually exclusive.

108 6- Editing & Printing

Indenting
Refer to the following discussions on Setting Spaces and Tabs, Entab and Detab,
Seek Indentation and Smart Indenting, and Block Alignment.

Setting Spaces and Tabs

Before editing a file, it may be necessary to control which characters are inserted
when the T key is pressed. In some cases, it is undesirable to have actual tab
characters inserted in a file. CodeWright has an option for setting the T key to
insert spaces rather than tabs; mark Use Spaces on the Tools|Customize|Language|
Tabs/Indenting dialog. Remember that all changes made in the Language dialog are
language-specific, so be sure to highlight the file type of the language of choice
before making any changes.

The Tools|Customize|Language|Tabs/Indenting tab is also where you set the size

of tab-stops and indention intervals. Refer to the following sections.
3 Tab and indent settings can also be set on a per-document or per-window basis
on the Tabs/Indenting tab of the Document/Window Manager dialog.

Tab Columns
The string placed in the Tab Columns editbox onTools|Customize|Language|
Tabs/Indenting describes where tab stops will occur. Tab stops are placed at the
columns specified in the string. For evenly spaced tab stops, you need not specify
more than two column numbers. CodeWright calculates the interval between the
last two column numbers and repeats that interval between tab stops all the way out
to the number specified in the Maximum Column field. The column count begins
with 1, not 0.
Example: A 4-column tab stop would be set by inserting the following
numbers: 5 9.
It works this way: The cursor starts in column 1. When the tab key is
pressed, 4 columns are added, putting the cursor in the 5th column.
When the tab key is pressed again, 4 columns are added, putting the
cursor in the 9th column, and so on, thus explaining the reason for the
"5" and "9".

Indent Columns
The Indent Columns option onTools|Customize|Language|Tabs/Indenting
controls the amount of indenting that occurs when you press [Tab] in the CUA
keymap (or outdenting that occurs when hitting [Shift]-[Tab]). It can be used in
combination with the Tab Columns option to provide indention levels between
larger tab intervals (but is off by default). The space inserted by the Indent Columns
setting can be a combination of tab characters and/or space characters.

6- Editing & Printing 109

 Example: In a DOS file, you may wish to set the Tab Columns interval to 8
spaces (entered as 9 17) and the Indent Columns interval to 4 spaces
(entered as 5 9). In this example, pressing [Tab] moves the cursor 4
spaces at a time, but a tab character is only visible every 8 spaces.
Successive groups of 8 spaces will be replaced with a tab character.
To see tabs and spaces on your screen, mark Visibles on the Window tab of the
Document/Window Manager dialog, or configure your View Theme to show visibles
on the Tools|Customize|View Themes|Visibles dialog.

EnTab and DeTab

The API functions EnTab and DeTab allow you to replace spaces in a file with tabs,
or tabs with spaces, respectively. When you call the functions from the Edit toolbar
or right-click menu in an edit buffer, or do not specify a flags parameter for either
function, popup dialogs allow you to configure the replacement operation. You can:
n Restrict replacement to tabs or whitespace at the beginning of lines.
n Skip comments
n Skip strings
n Skip single spaces (EnTab only)

Seek Indentation and Smart Indenting

Two indenting features, enabled in Tools|Customize|Language|Tabs/Indenting, are
designed to make editing tasks easier. The features are Seek Indentation and Smart
Indenting.
n The Seek Indentation function searches backward for a line containing
printable characters and duplicates its level of indentation. It has options for the
type of white space to be inserted when the indentation occurs. The white space
options consist of spaces, tabs or virtual space.
n Smart Indenting automatically indents according to common usage for the line
of the language being edited. If the word (or character) being typed is one for
which the following line is commonly indented, the indention occurs after
pressing E.

Example: A line in a .C file might end with an open curly brace, or begin with
while. When you press E to terminate the line after the curly
brace, the next line will automatically be indented.
Smart Indenting may be thought of as an extension of the Seek-Indentation
feature. Smart Indenting may be used with Seek Indentation turned off, but
leaving it on ensures the most consistent appearance.

110 6- Editing & Printing

 True to its name, Smart Indenting will be smart enough not to automatically
indent lines that are being typed in a comment. The languages for which Smart
Indenting is supported include C, C++, C#, Java, Java Server Pages, Assembly
and Pascal.
Note: Smart Indenting is not affected by the alignment style you choose.
The option Indent ‘case’ Statements on the Tools|Customize|Language|Tabs/
Indenting dialog indents 'case' statements one additional tab space based on
the alignment style you have selected. Indent ‘case’ Statements is available
when you have selected the Smart Indenting option, and the language you are
using supports ‘case’ statements.

Example with Indent ’case’ Statements Selected:

switch (arg) // Unindented block
{
case 1:
}

switch (arg) // Indented block

{
case 1:
}
switch (arg){ // Line saver
case 1:
}

Block Alignment
All the editing features that have been discussed in this chapter so far deal with
potentially indenting blocks of code. Since preferences may differ as to how
indenting should occur, CodeWright offers several different indentation styles to
choose from. These styles are set on the Tabs/Indenting tab of the Language dialog.

6- Editing & Printing 111

Tools|Customize|Language|Tabs/Indenting

The Alignment Style option in Tools|Customize|Language|Tabs/Indenting is for

selecting between several popular forms of block indentation to be used for brace
expansion or Align Begin/End Blocks and template expansion. It does not affect the
behavior of Smart Indenting or Paste Indenting. Choose from the following
indentation styles:
n Unindented Alignment: Places the block delimiters ({ and }, BEGIN and END,
for example) at the same level of indent as the controlling statement that
precedes the block. Statements between the block delimiters are indented.
n Line Saver Alignment: Places the opening block delimiter ( { or BEGIN, for
example ) on the same line as the controlling statement that precedes the block.
The closing block delimiter ( } or END, for example ) is at the same level of
indent as the controlling statement. Statements between the block delimiters
are indented.
n Indented Alignment: Indents block delimiters ( { and }, BEGIN and END, for
example), compared to the controlling statement that precedes the block.
Statements between the block delimiters are not indented.

Thus far this chapter has discussed CodeWright features that aid with repetitious
editing tasks. The chapter will continue along these lines by discussing features that
help with editing by offering information and reminders about parts of the file being
edited: Name Completion, CodeSense, and Comments and Comment Boxes. Hex
editing; HTML, XML and COBOL editing; Clipboard and Scrap features, and help
index file configuration are also discussed.

Name Completion
CodeWright Name Completion will automatically complete strings that occur in
either the current document or the CodeSense database, as the strings are typed.

112 6- Editing & Printing

The strings that Name Completion draws from are parsed as follows:
n Strings that occur in the current document are parsed by the Word delimiters
listed in Tools|Customize|Language|Options. The word delimiters are
customizable.
n Strings that are contained in CodeSense databases are parsed by one of the
following:
3 By file-type specific parsers that are listed in the Outline Parsers dialog.
Click Symbol Patterns in Tools|Customize| Language|CodeSense to
access the dialog.
3 By CodeSense (see the following topic CodeSense for more information).

Name Completion is turned on by marking Name Completion in Tools|Customize|

Language|CodeSense. The option is enabled by default. Press to access

additional settings on the Name Completion dialog.
3 To use Name Completion, type the first few characters of the variable, class,
symbol name or other word to be completed and press C -[Space].
3 You can click on a Name Completion window and drag it up or down to reveal
the code behind it.

CodeSense
CodeWright offers a feature called CodeSense that provides advanced "word"
completion for .C, .CPP, .H, .HPP, .CS and .JAVA files. It works by gathering
information about functions, methods, structures, unions, namespaces, packages,
interfaces and other pieces of code in source files, and then using the information for
editing and informational purposes. The following topics describe CodeSense in
detail and offer some troubleshooting tips in the event that the feature does not
work as expected.

Where CodeSense Gets its Information

CodeSense gets its information from databases and from files that are open in
CodeWright. The next topics describe how that information is derived.

Library and Project Databases

The core of the CodeSense feature is composed of databases that store information
gathered from parsed code. The information for the databases is found in the
following places:

6- Editing & Printing 113

n From C/C++, C# and Java source files in any of the library databases listed in
Tools|Customize|CodeSense|General. These databases can reference
directories of individual files or .zip/.jar files.
To display the properties of any scanned library database, highlight the
database name and press the Properties button. If the Properties dialog
indicates that you do not have an optimal version of the library database,
especially if it is a full release different (i.e. 8 vs. 9.2), you may want to rescan the
database.
n From C/C++, C# and Java source files in CodeWright projects. To display the
properties of the current project’s files that have been scanned for CodeSense
use, plus files parsed by the outline parser, select View Symbol DB Properties
from the status line CodeSense popup menu (right-click on the status line icon
to access). If the Properties dialog indicates that you do not have an optimal
version of the project database, you can right-click on again and select
Rescan symbol DB Files. If the project database is a full release different, and
therefore invalid, it will be rescanned automatically.
n From C/C++, C# and Java source files that are listed in the file list on the
CodeWright Symbols Window. Files in projects should already be in the list.
The next topic describes how to add files to this list.

Add a File to Symbols Window File List

Some CodeSense information is gathered from files listed in the Symbols
Window file list. Files that are in the current project will already be in the list. To
add additional files to the list, do the following:
1. Click the Symbols tab of the Output Window (located by default at the
bottom of the CodeWright screen).

Symbols Window

2. Click the File List button to access the Edit Symbol File List dialog and
type in or browse for the file to be added to the list.

114 6- Editing & Printing

 Edit Symbol File List

The following steps will also work to access the Edit Symbol File List dialog:

1. Right-click on the left most status bar icon to access the CodeSense
popup menu.
2. Click Edit Symbol DB File List to access the Edit Symbol File List dialog.
3. Type in or browse for the file to be added to the list.

CodeSense for Files that are Open in CodeWright

In addition to the information that CodeSense gets from library and project
databases, it also gets information from C/C++, C# and Java files that are open in
CodeWright. The scanning process for open files relies on the CodeSense option in
the Tools|Customize|Language|CodeSense dialog. Make sure this option is
selected for the appropriate file types (.C,.CPP, .CS and .JAVA).

CodeSense information that is gathered from open files is stored in memory rather
than in databases. It is specific to the files that are open and will only be available
while the files are open. This feature allows CodeSense to display information from
files that have not yet been saved to disk.

CodeSense Lookups for the Current Document

CodeSense drop-down lists and tooltips will ignore library databases that are
configured for a language other than that of the current document (a library's
language can be defined in the Language field on the Add Library Database or Edit
Library Database dialog). This results in faster lookups if you work in multiple
languages.
Example: If you're working in a C++ file, file lookups will only query
databases that are configured as C, C++ or All languages. If you're
working in a Java file, lookups will only query databases that are
configured for Java or All languages.

6- Editing & Printing 115

 Note: In the Objects Window, CodeSense will use all enabled libraries,
regardless of the libraries' languages or the language of the current
document.

CodeSense Global Configuration Dialog

The bulk of the information for CodeSense is gathered from and stored in
CodeSense library databases. CodeSense library databases are listed in the
CodeSense Global Configuration dialog (accessed from Tools|Customize|
CodeSense|General). They start out as directory locations for C/C++, C# and Java
files. Several default library databases can be installed with the CodeWright
installation. They will appear in the dialog if they were installed. If the appropriate
library database is not available with the CodeWright installation, it can be created.

Regardless of the manner in which a library comes to be listed in the CodeSense

Global Configuration dialog, it must always be scanned at least once in order for a
database to be created. Libraries that are installed with CodeWright have already
been scanned. If a library has not been scanned, a "(missing)" message will appear to
its immediate right, indicating that it does not have an underlying database. Press
Rescan to have CodeSense scan the selected library and create a database. The
rescan process will only work if the necessary source code is available and if the
directory for that library is set to point to the location of the source code.

Tools|Customize|CodeSense|General

The CodeSense Global Configuration dialog can be accessed from three alternate
locations:
n From the Tools|Customize dialog, by clicking CodeSense|General.
n From Tools|Customize|Language|CodeSense, by pressing Global
Configuration.

n From the CodeSense popup menu (right-click on the status bar), by selecting
Global Configuration.

116 6- Editing & Printing

Create CodeSense Library Database
In many cases, it will be necessary to create a new library database pointing to source
code that CodeSense will scan. Do the following to create a CodeSense library
database:
1. Click Tools|Customize|CodeSense|General.
2. Click Add to bring up the Add Library Database dialog.
3. Give the library database a name, and then either type the path to the correct
location of the source files or browse for the correct location (use the Dir button
to browse for a directory, or the File button to browse for a .zip/.jar file). If you
want CodeSense to include subdirectories at the location at which files will be
scanned, put a check in the Include Subfolders when Scanning box.
4. Mark the option Full Source to have CodeSense scan all .C, .CPP, .H, and .HPP
files in the specified CodeSense library database directories. Leave the option
empty to have CodeSense scan only .H and .HPP files in the specified
directories. This option does not apply to C# or Java. All .CS and .JAVA files will
be scanned regardless.
5. To define a language for this library, select one from the Language drop-down.
6. Click OK, then OK again. CodeSense will begin scanning the files in the
specified directory to create a database. Note that the newly-created library
must be checked in the CodeSense Global Configuration dialog in order to
make its database information available to CodeWright.

Edit CodeSense Library Database Location

The default library databases provided with the CodeWright installation may or may
not point to valid directories, depending on a system’s setup. Attempting to scan an
invalid library database will result in a message prompting to change its directory.
Do the following to change the location of a CodeSense library database:
1. Click Tools|Customize|CodeSense|General.
2. Highlight the library to be changed.
3. Click Edit.
4. In the Edit Library Database dialog, either type the path to the correct location
of the source files or browse for the correct location (use the Dir button to
browse for a directory, or the File button to browse for a .zip/.jar file). If you
want CodeSense to include subdirectories at the location at which files will be
scanned, put a check in the Include Subfolders when Scanning box.
5. Mark the option Full Source to have CodeSense scan all .C, .CPP, .H, and .HPP
files in the specified CodeSense library database directories. Leave the option
empty to have CodeSense scan only .H and .HPP files in the specified
directories. This option does not apply to C# or Java; all .CS and .JAVA files will
be scanned regardless.

6- Editing & Printing 117

6. To define a language for this library, select one from the Language drop-down.
7. Click Rescan. CodeSense will begin scanning the files in the specified directory
to create a database.
8. Click OK, then OK again. Note that the newly-edited library must be checked
in the CodeSense Global Configuration dialog in order to make its database
information available to CodeWright.

Delete CodeSense Library Database

As mentioned, default library databases can be placed in the CodeSense Global
Configuration dialog at installation. They are there for convenience only. They may
not be useful for all systems. If inapplicable databases have been installed, it may be
desirable to delete them. Do the following to delete a CodeSense library database:
1. Click Tools|Customize|CodeSense|General.
2. Highlight the library to be deleted.
3. Press Delete. A prompt will ultimately appear asking if the underlying database
should also be deleted. Click Yes to delete the database, then click OK.
Note: Databases that were created from the files in a CodeWright project
must be deleted outside of CodeWright, from Windows Explorer.
CodeWright should be closed before these databases are deleted. See
the topic Database Files to find out what files to delete and where they
are located.

Parser Priority/Resource Use

The CodeSense scanning process works on a background thread. It should not
interfere with other CodeWright processes. It has been known, however, to
occasionally be time and resource intensive. If you find that your CPU usage is high
because of CodeSense, you may want to set the parser priority to low. To do this,
press the Advanced Options button on the Tools|Customize|CodeSense|General
dialog and mark Low in the Parser Priority section.

CodeSense Databases
Once the necessary CodeSense library databases have been established in the
CodeSense Global Configuration dialog, and the Rescan button has been pressed if
necessary, the libraries will be scanned for information that will be stored in
databases for future use. Project and Symbols Window File List databases will be
created automatically given that:
n CodeSense is marked in Tools|Customize|Language|CodeSense (marked by
default for .C, .CPP, .H, .HPP, .CS and .JAVA files).

118 6- Editing & Printing

 Tools|Customize|Language|CodeSense

Note: Mark the option Filter Matches by File Type on the

Tools|Customize|Language|CodeSense dialog to filter lookups for
the file type(s) selected on the Language dialog. To see CodeSense
information that applies to any file type, disable this option.
Example: You may want to see CodeSense information for #defines from
header files that are used within resource (.rc) files. If you disable
the Filter Matches by File Type option for the file type .rc,
CodeSense information for the #defines would be available.
n Auto-update symbol database and Show Definitions in Symbols tab are
marked for the Symbol file option in Project|Properties|Directories.

Project|Properties|Directories

n A CodeWright project containing C/C++, C# or Java files is open and/or .C,

.CPP, .H, .HPP, .CS and .JAVA files are listed in the Symbols Window’s file list.

6- Editing & Printing 119

Database Files
CodeSense databases are comprised of the following files:
FILE.CDX, FILE.DBF, FILE.FPT, SYMBOL.CDX, SYMBOL.DBF and
SYMBOL.FPT
An additional file with a .SBL extension is also included among the database files,
though it is kept separately from the other files. The files can be found at the
following locations:
n Database files that are created for CodeSense library databases are located in the
SENSEDBS\<Library Name> directory of the CodeWright home directory.
n The .SBL file is located in the CodeWright home directory when no project is
open and is called CWRIGHT.SBL.
n If a project is open, the .SBL file is located in the project’s directory and is
named <Project Name>.SBL.
n Database files that are created for CodeWright projects are located in the <.SBL
file path>\<Project Name.cs_> directory.

Database Corruption
Sometimes CodeSense databases can become corrupt. While CodeSense is designed
to detect database corruption, it is not foolproof. If it detects corruption in a database
created from a CodeSense library database, a "(Corrupted)" message will appear in
the CodeSense Global Configuration dialog to the immediate right of the library.

If database corruption is suspected, all database files including CWRIGHT.SBL

should be deleted for that database. CodeSense library databases can be deleted in
one of two ways:
n By pressing the Rescan button for a selected library in the CodeSense Global
Configuration dialog. This will cause the underlying database files to be deleted
and the coinciding source files to be rescanned.
Use the following steps to rescan a CodeSense library database:
1. Go to Tools|Customize|CodeSense|General.
2. Highlight the library database to be rescanned.
3. Press Rescan.
n By pressing the Delete button for a selected library in the CodeSense Global
Configuration dialog. A message will ultimately appear asking if the underlying
databases should also be deleted. Click Yes to delete the database. See the topic
Delete CodeSense Library Database for numbered steps to delete a library database.
Note that you will have to recreate the library database in order to rebuild it.

120 6- Editing & Printing

To rescan databases that are maintained for projects:
1. Right-click on the Symbols tab of the CodeWright Output Window.
2. Select Rescan symbol DB files from the resulting popup menu.

To delete and rescan databases that are maintained for CodeWright projects:
1. Exit CodeWright and go to Windows Explorer.
2. Navigate to the directory containing the project (.PJT) file.
3. Delete the project database. See the topic Database Files earlier in this chapter to
get a list of the files and locations that make up the database. Project files will be
rescanned automatically when the project is open so long as the following
conditions are met:
3 CodeSense is marked in Tools|Customize|Language|CodeSense.
3 Auto-update symbol database and Show Definitions in Symbols tab are
marked for the Symbol file option in Project|Properties|Directories.

CodeSense: Main Features

CodeSense can be used once databases have been created. Before using it, though, it
is necessary to choose options that control its behavior. Some CodeSense options are
found in Tools|Customize|Language|CodeSense and some can be found in the
CodeSense Global Configuration dialog. The main features of CodeSense are
described next.

Name Completion
To have CodeSense complete or show a list of possible matches for symbols when
C -[Space] is pressed, mark Name Completion in Tools|Customize|Language
|CodeSense. Once marked, the option can be used by pressing C-[Space] at
appropriate times while typing. The option is marked by default for .C, .CPP, .H,
.HPP, .CS and .JAVA file types.
Example:

6- Editing & Printing 121

 Notes: When you highlight a definition in the list of possible matches, the
CodeWright status line displays the name of the database and file in
which the definition can be found. If desired, click on the symbol’s
representative (Go To) image to open the identified file with the
cursor positioned on the selected definition.
You can click on a Name Completion window and drag it up or
down to reveal the code behind it.
The following Name Completion options are available in the CodeSense dialog:
n Complete Document: Specifies that CodeWright should look for possible
completions of the name throughout the entire document.
n Symbol Database: Searches through the Symbols database (*.SBL) for a
matching string.
n Cycle Through: If multiple matching strings are found, matches are cycled until
the desired string is found.
n Show List: If multiple matching strings are found, all matches and their
definitions are shown in a drop-down list.
n Even for Single Matches: Matching string(s) are shown in a drop-down list,
even if there is only one match, rather than automatically entering the string
into your document.
n Ignore Case: Turns off case sensitivity when searching for strings that match
what you have typed.

Auto-list Members
To have CodeSense automatically display member lists when appropriately
following symbols such as structs, classes, unions, enums, namespaces, packages or
interfaces with ‘.’, ‘->’, or ‘::’, mark Auto-list Members in
Tools|Customize|Language|CodeSense. The option is marked by default for .C,
.CPP, .H, .HPP, .CS and .JAVA file types. Once the list is displayed, use it by either
selecting the desired symbol and pressing E, or by simply clicking on the
desired symbol. It will insert automatically.
Example:

122 6- Editing & Printing

 Notes: When you highlight a definition in a member list, the CodeWright
status line displays the name of the database and file in which the
definition can be found. If desired, click on the symbol’s
representative (Go To) image to open the identified file with the
cursor positioned on the selected definition.
You can click on a member list and drag it up or down to reveal the
code behind it.

Auto-type Info
To have CodeSense display a Tooltip containing a symbol’s definition as the mouse
cursor hovers over it, mark Auto-type info in Tools|Customize|Language|
CodeSense. The option is marked by default for .C, .CPP, .H, .HPP, .CS and .JAVA file
types.

Mark Shift or control required in Tools|Customize|Language|CodeSense to have

the S or C keys control when the tooltip appears. The Shift or control
required option works with Auto-type Info in the following way:
n If the Auto-type Info option is NOT marked, the Shift or Control required
option is disabled, and tooltips are completely disabled.
n If the Auto-type Info option is marked, but Shift or Control required is not,
tooltips ALWAYS appear when the mouse cursor hovers over a symbol.
n If the Auto-type Info and the Shift or Control required options are both
marked, pressing S or C while the mouse hovers over a valid symbol
causes the tooltip to appear when it otherwise would not.
Example:

Notes: When you highlight a definition in an Auto-type tooltip, the

CodeWright status line displays the name of the database and file in
which the definition can be found. If desired, click on the symbol’s
representative (Go To) image to open the identified file with the
cursor positioned on the selected definition.
To display a CodeSense hover tooltip based on the keyboard cursor
position (rather than the mouse position), press [Shift]-[F1].

6- Editing & Printing 123

Auto-Parameter Info
To have CodeSense display a tooltip of appropriate parameters as a function is being
typed, mark Auto-Parameter Info in Tools|Customize|Language|CodeSense. The
tooltip displays when the function’s left parenthesis is typed. As a parameter is
typed, and commas are entered, successive parameters in the tooltip become bold,
indicating that they are next in line to be entered.
3 Bold type will not appear for systems that use a bold font for tooltips.
Example:

Notes: When you highlight the definition in an Auto-parameter tooltip, the

CodeWright status line displays the name of the database and file in
which the definition can be found. If desired, click on the symbol’s
representative (Go To) image to open the identified file with the
cursor positioned on the selected definition.
You can click on a parameter tooltip and drag it up or down to reveal
the code behind it.
To display a CodeSense function parameter tooltip from the
keyboard, press [Alt]-[F1].

Extending CodeSense Functionality

Consider the following additional options for enhancing your use of the CodeSense
features.

ANSI and Unicode CodeSense Translations

To have CodeSense specifically parse and display ANSI and/or Unicode versions of
the Win32 API, mark Show ANSI and/or Show Unicode in Tools|Customize|
Language|CodeSense. If these options are not marked, ANSI and Unicode versions
of Win32 APIs will not be displayed. See the online help topic CodeSense Tab for more
information.

Disable CodeSense for Sections of Code Only

Two macros can be added to comments in C/C++ files to disable the CodeSense
parser for specific sections of code. This can be handy for pieces of code that are not
handled well by the parser.

The macros are:

n TURN_CODESENSE_OFF
n TURN_CODESENSE_ON

124 6- Editing & Printing

 Example: The CodeSense parser will not parse the following piece of code:
//TURN_CODESENSE_OFF
printf("Don't parse this");
//TURN_CODESENSE_ON

Enable Extended Popup Hotkeys

Check the Enable Extended Popup Hotkeys option on the Tools|Customize|
CodeSense|General|Advanced Options dialog to enable the following
functionality:
n [Ctrl]+[G]: Allows you to access a symbol's definition from the various
information returned by CodeSense or from the Objects Window; this works
the same as clicking a symbol's Go To icon.
n [Up], [Down], [PgUp], [PgDn], [Home], and [End]: Enables you to use these
keys to navigate the list of items returned by the Name Completion feature.
n [Ctrl]+[Up] and [Ctrl]+[Down]: Allows you to select a different definition
when multiple definitions are available in Auto-Parameter Info and Auto-Type
Info tooltips (above or below the definition currently highlighted).
n [Ctrl]+[Shift]+[Up] and [Ctrl]+[Shift]+[Down]: Allows you to move a
member list, parameter tooltip or Name Completion window up or down on
the screen to reveal the code behind it. You can also drag the tooltip up or down
with your mouse.
n [Ctrl]-[PgUp] and [Ctrl]-[PgDn]: Allows you to collapse or expand, respectively,
the current node in a Name Completion list when Consolidate Matching
Lookup Definitions is enabled. These shortcuts are also available in the Show
Symbols Called or Used By (Function or Class Name) dialog, regardless of
whether Enable Extended Popup Hotkeys is selected.
n [Alt]-[F1]: Displays a CodeSense function parameter tooltip without entering
the left parenthesis of a function call.
n [Shift]-[F1]: Displays a CodeSense hover tooltip for a valid symbol based on
keyboard cursor position rather than mouse position.

Consolidate Matching Lookup Definitions

Mark the option Consolidate Matching Lookup Definitions on the CodeSense
Advanced Options dialog to have CodeSense "roll up" multiple matches for symbols
that have the exact same definition, but that come from different locations in the
source files. If this option is marked, only one matching definition will display in the
various CodeSense drop-down lists, but a down-arrow will denote that more
matches exist. Click to expand the list of matches with the same definition.
3 If Consolidate Matching Lookup Definitions is not marked, all matches will be
visible initially. Click on an up-arrow to roll up the identical matches.

6- Editing & Printing 125

 When it Applies
Consolidate Matching Lookup Definitions will consolidate matches found in
all libraries listed in the CodeSense Global Configuration Dialog if any of the
following conditions are met:
n One of the matches is from a current document search, regardless of
whether the consolidate option is on.
n The consolidate option is on, the symbol types are the same, and the
definitions are the same.
n The consolidate option is off, the symbol types are the same, the definitions
are the same, the filenames are the same, and the offsets are the same (this
would happen if two databases both parse the exact same file).

Except in Tooltips
If you have marked the Consolidate Matching Lookup Definitions option, the
checkbox Except in Tooltips is also enabled. This allows you to roll up matching
definitions in the Show Symbols Called or Used by <function/class name>
dialog, and in Name Completion lists, but to automatically show all relevant
definitions in CodeSense tooltips, since the tooltips don’t allow you to expand
or collapse identical definitions.

Project Matches in Non-Project Files

To have CodeSense display project database matches even if the file being edited is
not part of the current project, mark Allow Project Database Matches in Non-
Project Files on Tools|Customize|CodeSense|General|Advanced Options.
Example: Consider that the current CodeWright project and the file being
edited each contain a function named 'foo'. However, the file being
edited does not belong to the current project. CodeSense has
scanned both 'foo' functions and placed them in databases or in
memory-- the project's function having been stored in the project-
database, and the current buffer's function having been stored in
memory.
If Allow Project Database Matches in Non-Project Files is marked,
both 'foo' functions will display in CodeSense drop-down lists. If it is
not convenient to see matches for both functions, leave the option
unmarked.

Maximum Number of Hits

The Maximum Number of Hits slider on the Tools|Customize|CodeSense|
General|Advanced Options dialog allows you to choose a limit for the number of
hits you will receive from any single CodeSense-related lookup. The selected value
displays to the right of the slider; the default value is 1,000 hits.

126 6- Editing & Printing

This setting affects the information provided in CodeSense tooltips and member
lists, Name Completion lists, and the Objects Window.

Maximum Cache Size

On the Tools|Customize|CodeSense|General|Advanced Options dialog, click and
drag the Maximum C ache Size slider to change the number of hits from CodeSense
lookups that are retained in memory. The default setting is 500 hits.

A small cache size will limit memory usage, but will also decrease the likelihood of a
recent lookup remaining in the cache when the same lookup is repeated.
Conversely, if you increase the size of the cache, it is more likely that a lookup will
still be available upon subsequent request, making the lookup faster.

This setting affects the speed of CodeSense tooltips, member lists and Name
Completion lists.

Symbol Lookups
CodeSense symbol lookups are done in a context-sensitive (scope sensitive) manner.
The buffer offset of a symbol is used to determine the context. For example, in the
following pseudo code, the scope of the first "str" would be "global, <foo>, <while
block>, <if block>". Therefore the definition of "str" found in the else block would
not qualify as the definition of the "str" in the if block.

void foo( void )

{
while (TRUE)
{
if (TRUE)
{
printf( str );
}
else
{
LPSTR str = "foo";
}
}
}

The following additional information pertains to symbol lookups:

n When doing a member lookup, CodeSense does not care whether ‘::’, ‘->’, or ‘.’
is typed. It will display the members regardless. For example, typing "Cstring->"
will display the members of Cstring even though a compiler would expect
"Cstring" to be followed by ‘::’.

6- Editing & Printing 127

n CodeSense won’t display member lists for function return values (e.g.
"GetWindow()->).
n Libraries and/or project files that are currently being scanned or parsed are not
available for lookups.
n If a project database is being indexed or compacted, CodeSense will wait for a
few seconds for it to finish. If it does not finish, the whole project database will
be unavailable for lookups (i.e. only library databases will be used).

Troubleshooting
If CodeSense is not performing as expected, refer to the following sections.

My file is not being parsed at all...

If CodeSense returns no information from your files, try the following:
n Make sure that the necessary CodeSense library databases are checked and have
been properly scanned in Tools|Customize|CodeSense|General. To display
the properties of any scanned library database, highlight the database name and
press the Properties button.
n Make sure that CodeSense DLL is marked for the appropriate file type (C/C++,
C# or Java) in Tools|Customize|Language|CodeSense and that desired
configuration options are marked.
n If project files aren't being scanned, make sure that Auto-update Symbols
Database is marked in Project|Properties|Directories. To display the properties
of the current project's files that have been scanned for CodeSense use, select
View Symbol DB Properties from the status line CodeSense popup menu
(right-click on the status line icon to access).
n If the correct symbol is not included in those files scanned from CodeSense
library databases, make sure that the file with the symbol is either included in
the current CodeWright project or the Symbol Window's file list, or is open in
CodeWright.

My file is not being parsed correctly (syntax issues)…

If CodeSense is returning information, but it is not what you expect, try the
following:
n It is possible to create C/C++ code that appears syntactically incorrect but
compiles without errors once #define's are expanded by the compiler's
preprocessor (such as a #define that has an open brace but no close brace).
CodeSense does not preprocess macros, and as a result may not parse such
source code correctly. This can throw the parser sufficiently off track that the
next source code isn't parsed correctly either.

128 6- Editing & Printing

 Such a situation can often be improved by doing one of the following:
3 Use the TURN_CODESENSE_OFF/ON macros to prevent troublesome
blocks of code from being scanned. (Only applies to the C/C++ parser).
3 If a symbol that has #defines in its definition is being parsed incorrectly,
add it to the [CodeSense Definitions] section of the CodeSense
configuration file CWSENSE.INI. See CWSENSE.INI for more information.
(Only applies to the C/C++ parser).
n Because CodeSense does not report syntax errors, make sure that the source file
compiles without errors. Syntax errors that become apparent when compiling
your code can interfere with CodeSense functionality. Examples include:
3 #define is in the wrong place
3 Improper use of a semicolon.
3 Missing a semicolon or brace.

Comments and Comment Boxes

There are two items on theText menu, Comment and Comment Box, which are used
to automatically insert comments into your code. The Comment and Comment Box
menu items draw a user-defined border around selected text. This feature makes it
convenient to write the text of a comment employing word wrap, and then to add
the comment characters later. The border may be a comment block or any decorative
characters you care to use. The strings used for these borders are defined on the
Comments tab of the Language dialog.

Tools|Customize|Language|Comments

6- Editing & Printing 129

Define the look of Comments and Comment Boxes as follows:
n The Comment item adds a purely functional left and right border, which may
serve as the beginning and end of a comment. The default for this item is to add
/* to the beginning of each line or line segment in the selection, and to add */ at
the end of each.
n The Comment Box item does the same, but adds a decorative top and bottom
line. This type of comment is usually used for an eye-catching multi-line
comment at the beginning of a function or file. It is primarily for line selections,
but may also be used for column or stream selections.
The left side of the border is placed at the beginning of the line, or, in the case of
a column selection, in the first column of the selection. The right side of the
border is placed at the first tab stop to the right of the longest line in the
selection.

HTML Editing
With the ever-increasing popularity of the Internet, it has become necessary to own
at least one good HTML editor. CodeWright provides several features that make it
ideal for HTML editing. Those features are described next.

HTML Language Support

When HTML files are opened in CodeWright, ChromaCoding is immediately
available. All HTML keywords, comments, and strings are colored instantly. Use
Text|Format Source to format selected HTML code according to standard HTML
conventions; no additional formatting criteria are defined on the
Tools|Customize|Language|Format dialog.
Template expansion (see the topic Templates and Brace Expansion) is also available for
HTML. Automatic insertion of opening and closing tags with correct cursor
positioning allows for quick completion of code-statements.

HTML Popup Menu

The default right click-popup menu in CodeWright has a handy <tag> attributes
option that displays applicable attributes for the closest open HTML tag. Just
position your cursor close to an opening HTML tag, then press your right mouse
button. The first option on the resulting popup menu will access a submenu
containing a list of applicable tag attributes, if any.
Items on the popup menu can be changed by using the Edit this menu item, or by
editing the HTML.MNU file directly (see the chapter Custom Interface).

130 6- Editing & Printing

WYSIWYG Editor/Viewer
CodeWright has an HTML WYSIWYG (What You See Is What You Get) editor/viewer
that must be turned on in Tools|Customize|Libraries to be used. See the topic
Viewing and Editing Internet Files: Installation Instructions for instructions about
turning on WYSIWYG editing. See the topic Using HTML WYSIWYG for information
about how the feature is used. CodeWright HTML\WYSIWYG requires either
Windows 98, 2000 or XP. WYSIWYG editing is done in Internet Explorer 5 or later,
but you can also view documents in Netscape Navigator and Opera if you have
those browsers installed on your system.

HTML Viewing - Web Browser Interface

In addition (or alternative) to the WYSIWYG editor, CodeWright offers a Web
Browser as Viewer interface that displays files being edited in certain installed web
browser(s). See CodeWright’s online help topic HTML Web Browser Interface for more
information. This viewing method must also be turned on in Tools|Customize|
Libraries.

The process for enabling both of the HTML viewing and editing features is described
next.

Viewing and Editing Internet Files: Installation

Instructions
To install the CodeWright WYSIWYG HTML editor or the web browser interface, do
the following:
n Go to Tools|Customize|Libraries and mark one of the following boxes:
3 Web Browser as Viewer- installs CWWEB.DLL, enabling CodeWright’s
web browser interface. See the online help topic Web Browser Interface.
3 HTML WYSIWYG Editor/Viewer- installs CWHTML.DLL, enabling
CodeWright's WYSIWYG HTML editor.
n If none of the options described above are listed in the Libraries dialog, click the
Add button and select the appropriate DLL(s) from those listed in the
CodeWright directory. Both installation methods cause CodeWright to load the
library into memory. They also add lines to the CWRIGHT.INI file so that the
DLL(s) will automatically load when CodeWright starts up. Examples of the
entries in CWRIGHT.INI follow:

[LibPreLoad]
LibPreLoad=cwweb.dll
LibPreLoad=cwhtml.dll

6- Editing & Printing 131

Using HTML WYSIWYG
Once you have loaded the HTML WYSIWYG Editor/Viewer module, it is used as
follows:
1. Verify that the option Auto-detect File Type is marked on the
Tools|Customize|Environment|File Options dialog.
2. Load an HTML file.
3. Use the splitter control on the vertical scrollbar, or press [F5] in the CUA keymap
to split the window.

HTML WYSIWYG Window

4. Additional buttons available on the built-in HTML toolbar provide the

following functionality:

3 View the current file in a full code window.

3 Display the file in the split window WYSIWYG editor/viewer.

3 View the current file in a full WYSIWYG window.

3 The next several buttons perform various HTML WYSIWYG and code-
editing tasks such as inserting tags, setting colors, and inserting tables and
graphics. They will be alternately available and unavailable as they apply to
the view (code or WYSIWYG) that currently has focus. Refer to the topic
HTML:Toolbar in the online help for details on each toolbar button.

3 Transfer changes one-way, from the current window to the opposite

view.

3 Highlight the element in the opposite view (code or WYSIWYG) that

corresponds to the cursor position in the current view.

132 6- Editing & Printing

 3 You can view/test your document in Internet Explorer, Netscape Navigator
or Opera. If one of those browsers is loaded on your system, the
corresponding button will be enabled on the HTML toolbar (Internet
Explorer is available by default). If your filename or path contains a space,
and you are using Opera, open the file directly from the browser instead
using the File|Open command.

3 Press to display the HTML Configuration Options dialog.

Editing Capabilities
HTML WYSIWYG editing provides the following capabilities:
n Edit HTML files as normal documents. Text cut or copied from the WYSIWYG
window is available on the ClipView tab of the Output Window.
n Quickly insert HTML tables and graphics.
n Resize HTML tables and graphics with mouse drag operations.

Differencing/Merging
By default, changes made in the code window must be saved or undone before
editing in the WYSIWYG window. Conversely, changes made in the WYSIWYG
window must be updated or abandoned before the code window can be edited. The
Update button transfers changes one-way, from the current window to the
opposite view.

If you wish to enable differencing/merging (so the Update button combines changes
from both views and updates both views), press to invoke the HTML
Configuration Options dialog and mark Enable Differencing/Merging. Also on this
dialog:
n Mark Open Viewer in Edit Mode to open the WYSIWYG viewer in editing
mode by default.
n Mark Enable WYSIWYG Editing to enable editing in the WYSIWYG window.
Note: You can also set these flags programatically using the
HTMLConfigFlags API function, described under Help|CodeWright
API Library.
Differencing/merging in the HTML WYSIWYG window will be disabled if any of the
following load errors are encountered:
n Document contains one or more frame sets.
n Document contains server script too complex to be parsed.
n Document contains multiple <BODY>, <HEAD>, <TITLE>, or <HTML> tags.
n Document contains server script inside a <LISTING> tag.

6- Editing & Printing 133

n Document contains server script inside a <LABEL> tag.
n Document contains server script inside a <TEXTAREA> tag.
n Document contains server script inside a <SELECT> tag.

XML Editing
Enjoy robust XML support in CodeWright that includes:
n A variety of XML viewers (Split Window, Source Code, and Browser), and an
XSL Transformation View.
n Enhanced XML editing in the tree hierarchy.
n XML source formatting.
n XML/XSL templates and template expansion.
n XML project filters.

To enable XML support, remember to do both of the following:

n Mark the XML Split Window Viewer module under Tools|Customize|
Libraries.
n Mark Auto-detect File type in Tools|Customize|Environment|File Options (or
in the Open As: field on the File|Open dialog).
For more details on XML support, refer to the following paragraphs.

XML and XSL Viewers

Several viewers have been developed to help you navigate and edit your XML
documents. These are described next.

XML Split Window View

The XML Split Window View provides a horizontally split edit window. The top
portion contains a valid XML document in hierarchy form; the bottom portion of the
window displays the document's XML code. If the window is not already split, it
must be split manually using vertical scrollbars or using the CUA key sequence %.

The Split Window View has a toolbar that allows you to display your XML document
in the various viewers; press to return to the Split Window View.

134 6- Editing & Printing

XML Split Window View

Viewing Code in the Hierarchy

The CodeWright XML Split Window View displays XML code in a collapsible
hierarchy of the elements and element attributes in an XML document, as they
relate to the document's root element.
The individual elements can be collapsed within the Hierarchy, or the Hierarchy
can be collapsed completely so that only the root element displays. You can
also expand or collapse specific columns by pressing the arrow in the
corresponding column header.
Icons that display in the Hierarchy indicate the corresponding type of XML
node. Refer to the following definitions for these icons:

n - indicates an Attribute node

n - indicates a Comment node

n - indicates an Element node

n - indicates a Processing Instruction node

n - indicates a Text node

Editing Code in the Hierarchy

Double-click on any valid XML element or element attribute within the
Hierarchy to directly edit that node. In editing mode, refer to the following
additional functionality:

6- Editing & Printing 135

 n Use cut, copy and paste commands (e.g. [Ctrl]-[X], [Ctrl]-[C] and [Ctrl]-[V]
in CUA) within individual Hierarchy nodes.
n To update the Code View (lower pane) with your changes, press [Enter].
The Code View is also updated with changes made in the Hierarchy
whenever the edit cell loses focus.
n To exit editing mode without updating the node in the Code View, press
[Esc].
n To jump to the corresponding location in the Code View from a node in the
Hierarchy, press the Go To button , press [F6], or right-click and select
Go to Source.
n To update the Hierarchy with changes made in the Code View, press the
Refresh button , or right-click and select Refresh.

n To save changes made in the Hierarchy, press the Save button on the
Standard toolbar, or right-click in the Hierarchy and select Save.
n To delete the currently selected element row from the hierarchy, right-click
and select Delete Row.
n To add an element row to the Hierarchy with the element name derived
from the currently selected row, right-click and select Add Row: [Element].
The node is inserted as a sibling or child, based on the current selection.
n To add an element row to the Hierarchy with a user-defined element item,
right-click and select Add Row. Use the Add Row dialog to give the
element a name, and choose whether to add the element as a child node or
sibling node.

Add Row Dialog

136 6- Editing & Printing

 Working in the Code View
You can edit the XML document in the lower pane of the Split Window View as
you would any CodeWright document.
n Once you have made changes in the Code View, press the Refresh button
to update the Hierarchy in the upper pane. If you attempt to edit the
Hierarchy immediately after editing the Code View, you will be prompted
to refresh.

n Press the Save button on the Standard toolbar to save changes made in
the Code View (refreshing the Hierarchy automatically).
To view or edit the source code in a larger window, bring up the XML Source
Code View, detailed next.

XML Source Code View

From the XML Split Window View, press to display your document in the default
Source Code View, allowing you to edit your XML files in a standard CodeWright
edit document.

XML Source Code View

Expand XML and XSL templates shipped with CodeWright into your document
with a few keystrokes, or add custom, user-defined templates on the
Tools|Customize|Language|Templates dialog. Refer to the following section,
Template Expansion.

6- Editing & Printing 137

XML Browser View
From the XML Split Window View, press to display your XML file in a read-only
web browser. If no XSL stylesheet is referenced, navigate the code using a
collapsible tree format that looks like the following sample:

XML Browser View

If an XSL stylesheet is referenced, the XML Browser View will contain the same
output as the XSL Transformation View, described next.

XSL Transformation View

From the XML Split Window View, press to launch an XML/XSL-enabled browser
(Internet Explorer 5.0 and above). If an XSL stylesheet is properly referenced in your
XML file, the XML data is formatted and displayed according to that stylesheet.

XSL Transformation View

138 6- Editing & Printing

Template Expansion
Template Expansion for XML/XSL allows you to simply type an abbreviation in your
XML document and press the spacebar to expand the corresponding tag(s). Whether
you're just starting to learn XML or are already proficient, typing fewer tags saves
time and results in fewer errors to track down.
Example: When you type:
sort [spacebar]
The following is inserted into your document at the cursor
position:
<xsl:sort> </xsl:sort>
On the Tools|Customize|Language|Templates dialog, select .xml in the FileType
list and mark the option Template Expansion to turn template expansion on for the
XML language. Scroll down in the Abbreviations list to explore the wide variety of
XML/XSL templates available.

Tools|Customize|Language|Templates

Other examples of XML/XSL templates include:

n template [spacebar]
<xsl:template match=””>&</xsl:template>
n elem [spacebar]
<xsl:element name="">&</xsl:element>
n style [spacebar]
<xsl:stylesheet>&</xsl:stylesheet>

6- Editing & Printing 139

Format Source
Use Text|Format Source to format selected XML code according to standard XML
conventions. No additional formatting criteria are defined on the Tools|Customize|
Language|Format dialog.

Project Filters
Two categories of project filters are available for XML Files and Web Files on the
Project|Properties|Filters dialog. Use these categories to group XML-related files
and/or HTML- related files on the Project tab of the Project Window.

Use these project filters to gain quick access to the following file types during web
development:
n XML Files: .XML, .XSL, .DTD, .XHTML, .XDR and .DCD
n Web Files: .HTM, .HTML, .SHTM, .ASP and .CSS
Refer to the following setup on the Filters tab, and the resulting hierarchy on the
Project tab:

Project|Properties|Filters Dialog

140 6- Editing & Printing

Project Tab on the Project Window,
Using XML Project Filters

COBOL Editing
This section describes COBOL language support and editing features in
CodeWright.

COBOL Lexer and DLL

COBOL ChromaCoding support is available via a DLL or a ChromaCoding lexer.
To use the DLL:
1. Mark the option COBOL in Tools|Customize|Libraries.
2. Go to the Tools|Customize|Language dialog.
3. Select ‘.cob’ in the Customize dialog navigation tree. If you do not see the
correct file type, click New Type, and add it.
4. Select the Coloring tab.
5. Mark DLL and click OK.

6- Editing & Printing 141

To use the lexer:
1. Go to the Tools|Customize|Language|Coloring dialog.
2. Select ‘.cob’ in the Customize dialog navigation tree. If you do not see the
correct file type, click New Type, and add it.
3. Mark Lexer.
4. Choose COBOL from the drop-down list and click OK.

Open a COBOL file to see ChromaCoding language support. Note that language
support DLLs and ChromaCoding lexers can be used together. If both exist, it is
advisable to use the lexer for ChromaCoding, and the DLL for other language
support features.

COBOL Extensions
CodeWright has a COBOL Extensions module that provides various COBOL-
specific functions and controls. To turn it on, mark COBOL Extensions in
Tools|Customize|Libraries. The features that are provided by the module are listed
next.
Note: Keep in mind that COBOL reserves everything past column 72 for
comments. If you are typing in the middle of a line, there is a beep
when text at the end of that line reaches column 72 and no further
insertion is allowed. If you are typing at the end of a line, the
character is inserted or overtyped at the start of the next line. If a
clipboard paste, drag and drop, or search and replace operation
pushes text past column 72, that text will be truncated.

Resequence Line Numbers

Cobol Extensions provides a CSr keystroke to resequence line numbers.
This works as follows:
1. Select (highlight) the desired line number sequence.

2. Press CSr. A dialog will appear entitled Enter Sequence Info.

3. Enter the Start number for the line number sequence.

4. Enter the Increment number that the line number sequence will be incremented
by.

142 6- Editing & Printing

5. Press OK. Line numbers will be resequenced according to the dialog's inputs.
Note the following:
3 The Start number will be placed at the top of the file.
3 If numbers did not exist previously in the file, they will be inserted at the
far-left margin of the file, taking up the first 6 columns of the line.
3 Line numbers will not be inserted if the file is not saved.
3 Line numbers will not be inserted if there is not more than one line in the
file.
3 If text already occurs at the position where a line number would be, the
number will not be inserted. However, the number will still be counted.
3 For non-numbered lines that have numbered lines above and below them,
numbers will only insert on the lines between those lines. For non-
numbered lines that have numbered lines below them, numbers will only
insert up to those lines.

Line Number Handling when Lines are Copied or Moved

When Cobol Extensions is loaded, COBOL line numbers will become spaces at the
locations at which they are copied or moved. This will keep the numbers from being
repeated every time text is copied from one part of a file to another. New line
numbers can then be inserted using the 'Resequence' key CSr (mentioned
earlier).

Toggle COBOL Comment

Cobol Extensions provides a Ct keystroke to toggle a COBOL comment
delimiter. Press Ct to have a comment delimiter (*) inserted at column 7 of the
current line. If a comment delimiter already exists in column 7, Press Ct to
remove it.

Automatic Time/Date Stamp on Modified Lines

Time/date stamps are automatically inserted on modified lines at File|Save. Note the
following:
3 The line-modified (time/date) string is inserted at column 73 of the modified
line.
3 The [End] key will move the cursor to the end of the line of code, not to the end
of the line-modified (time/date) string.

6- Editing & Printing 143

3 Entering a new line will not move the line-modified string off of its designated
line.
3 The string that is inserted can be customized by modifying the date macros in
the History Template section of the CobolExt Settings dialog
(Tools|Customize|CobolExt Settings).

String Literals Automatically Continue on New Lines

COBOL Extensions automatically inserts -" (dash-double-quote) on newlines when
the previous line contains an open or continued string literal (no closing quote).

Validate Line Number Sequence

A CSv key sequence is provided to validate a line number sequence. Press
CSv to have CodeWright highlight the first line it finds with an invalid line
number, if the line exists. If it does exist, the following message will display in the
status bar:

Sequence numbers are invalid.

If line numbers are valid, no lines will be highlighted, and the following will display
in CodeWright's status bar:

Sequence numbers are valid.

Patch File Shows Changes in a File

COBOL Extensions provides a CS+ key that creates a ‘patch’ file. The
patch file shows which lines are different between the file that is being edited, and
another version of the file. CodeWright locates the the other version using path and
filename information from the file being edited. The method CodeWright uses to
extract path and filename information can be customized by modifying the filename
component macros in Tools|Customize|CobolExt Settings|General.

For example, to create a COBOL Extensions patch file that will show the differences
between the file being edited and the backup file that CodeWright optionally creates
when the file is saved, set the following filename component macros in
Tools|Customize|CobolExt Settings|General:

Patch File: %v%pPATCH\%r%e

Original Source File: %v%p\%r.bak

144 6- Editing & Printing

In a modified COBOL document press CS+. The above settings will create
a patch file with the same name as the file being edited. The file will be located in the
PATCH subdirectory of the file being edited. The patch file will not be created if the
PATCH directory does not exist. The patch file contains a list of line numbers for any
lines that are different between the edit file and the Original Source File. New text
in the file being edited will also be recorded in the patch file along with the line
numbers. If some of the lines in the file being edited do not have line numbers, a
message will appear, and the patch file will not be created. Press CSr to
resequence the line numbers.

The CS+ key sequence will save the current file while creating the patch
file. The contents of the patch file will be over-written every time the key sequence is
successfully completed.

For a description of filename component macros, see the topic Filename Component
Macros in the chapter Projects, Project Spaces, and Workspaces. For more information
about the CobolExt Settings dialog, see the online help topic CobolExt Settings.

The Cobol Extensions module does not require that COBOL language support be
turned on. However, the module will be more useful if it is.

Hex Editing
A frequently used CodeWright editing feature is Hex-mode editing. Hex mode
allows you to view and edit a file in hexadecimal values. You may edit the file by
entering values for each byte, or by typing the ASCII equivalent.

To enter Hex mode:

n Press CAh in the Visual Studio .NET keymap

n Press CSh in the CUA or the BRIEF keymap,

n Press $ in the vi keymap.

n Use the button on the Edit toolbar (described briefly in the chapter on
Custom Interface) that switches the current document to Hex mode.

When you enter the Hex mode, the T key is redefined. It may be used to switch
from the Hex values to their ASCII equivalent, and back again. To return to Standard
mode from Hex mode, press the X key.

Hex mode displays the document offset at the left, 16 bytes of hex values in the
middle, and their ASCII equivalent to the right. The 16 hex values are divided into
four groups of four. Each value has two digits: a high nibble and a low nibble.

6- Editing & Printing 145

Insert vs. Overtype Mode
Most Hex mode editors cannot change the length of a file, and therefore are always
in overtype mode. CodeWright can insert characters while in hex mode, and it will
be in insert mode if you were in insert mode before entering Hex mode.
Note: If the file or portion of a file you are editing is length-sensitive, you
will probably want to toggle to overtype mode.
When entering text in the ASCII portion of the Hex mode display, insertions appear
as they do when you are in normal text mode, except that the text is in a rather
narrow column. When in the Binary portion of the Hex display, each byte is
displayed as two hexadecimal numbers, the high nibble on the left and the low
nibble on the right. When you type numbers (0 to F) in these positions, it changes or
inserts the character whose numerical equivalent you have typed.

You cannot insert a nibble; you must insert an entire byte. Therefore, when you type
at the high nibble position, both nibbles of the byte are inserted. The low nibble is
initially zero. The cursor is then positioned over the low nibble. The next number
you type replaces the value of the low nibble. So, as you type, you will alternately
see two nibbles inserted, and one nibble overtyped.

Handy Hex-Editing Tips and Features

Keep in mind the following CodeWright features when using Hex mode:
n Highlighting text in Hex mode will highlight the corresponding ASCII side.
n Hex characters can be copied, cut, and pasted in the same manner that ASCII
characters can, but the document to which the hex characters are being pasted
must be in hex mode in order for the pasted text to appear in hex; otherwise,
hex characters are pasted in ASCII.
n When the cursor is in the hex side of the document, a 'black on yellow' color
mark will appear for the character opposite the cursor in the corresponding
ASCII side. The color mark will appear in the same way in the hex side of the
document if the cursor is in the ASCII side. This helps track the hexadecimal
equivalent if in ASCII mode or the ASCII equivalent if in hex mode.
n The cursor will wrap on either editing side to the next/previous line when the
right/left arrow key is used.
n Tips for searching and replacing binary and hex characters can be found in the
Chapter on Search and Replace and Navigational Tools.

Clipboard and Scrap Buffers

In CodeWright, copy/paste operations can be stored in the Windows Clipboard, or in
CodeWright Scrap Buffers. To toggle between Clipboards and Scrap Buffers, select
one or the other from the Edit menu. In both cases, multiple buffers are allowed.

146 6- Editing & Printing

Scrap Buffers
CodeWright offers the option of using Scrap Buffers as the staging area for local cut
and paste operations. Scrap Buffers can be used within or between edit documents
in CodeWright much as the Windows Clipboard is used for cut and paste operations
between applications.

Multiple Clipboard/Scrap Buffers

CodeWright allows the use of multiple Clipboards or Scrap Buffers. The number of
buffers available can be defined on the Clipboard tab of the Tools|Customize|
Environment dialog. The default is one for each.

The following image shows options available when the Clipboard radio button is
selected. If you choose Scrap Buffers instead, another version of the tab displays
that is specific to Scrap Buffer options.

Tools|Customize|Environment|Clipboard

The Clipboard tab also has an Auto-increment Clipboard/Scrap Buffer option. With
either enabled, the clipboard/scrap buffer to use is incremented immediately prior to
copying or cutting new content. If the highest numbered clipboard/scrap buffer is
already the current one, the zeroth one is used next.

Check the option Store Clipboard/Scrap Options in project file to store these
Clipboard/Scrap settings with the project currently open. If the box is checked but
no project is open, options selected on the Clipboard tab are stored as default
settings for use with future projects.

6- Editing & Printing 147

Clipboard/Scrap Viewer
An extra tab for viewing the contents of the current Clipboard or Scrap Buffer can be
turned on for the Output Window. The tab is called ClipView. Make the ClipView
tab of the Output Window visible by marking the Clipboard/Scrap Viewer option in
the Tools|Customize|Libraries dialog.

ClipView Tab (Detailed View)

The ClipView tab provides the following functionality:

n Select button: Selects the currently displayed clip or scrap buffer to be the
default repository for copy/cut operations. The button is not available if the
buffer displayed in the ClipView Window is already the default repository.
n Paste button: Pastes the contents of the ClipView Window.
n Delete button: Deletes the contents of the ClipView Window.
n Overview button: Allows you to view all Clipboard/Scrap buffers available (you
may have to use scroll bars to see additional buffers). When you are in
Overview mode, the Detail button returns you to the current clipboard/buffer
view only.
n Clipboard and Scrap Buffer radio buttons: Allow you to view the contents of
Clipboards or Scrap Buffers, and to select either as the current repository for
copy/cut operations.
n Increment Clipboard/Buffer: Change the number in this field to view the
contents of another Clipboard or Scrap Buffer.
Additional information on the CodeWright ClipView tab is available in the online
help.

Using Help in CodeWright

The CodeWright help system can be configured to support multiple help files for
easy access to help topics from different environments. When CodeWright's help has
been properly configured, position the cursor on a word in the current file, and press
! to show a list of help files in which that word was found. Choose the
appropriate topic from the various files presented.

148 6- Editing & Printing

Indexing and Accessing Help Files
CodeWright ships with its own online help files (CWHELP.HLP, CWAPI.HLP,
CWPERL.HLP and CWAPPBAS.HLP). You can also index or access help files from
other software packages, so that they can be used from within CodeWright.

Help files that can be accessed from within CodeWright must be one of the
following:
n .HLP Windows help files
n Microsoft Visual Studio 6.0 and Visual Studio .NET HTML help files
n .IVT Microsoft Visual C++ 5.0 help files
n .MVB Microsoft C++ 4.0 help files
n .CHM Compiled Microsoft HTML Help Files

Indexing .HLP Help Files

To index your .HLP help files, select Add in the Help|Configure Index dialog, and
then browse for the help file you need. When you have selected it, choose Close.
CodeWright will add this help file to the help index (CWRIGHT.IDX). CodeWright
also has a Help Index File Wizard that will combine selected .IDX files with the
CodeWright .IDX file, thereby creating a more comprehensive help index with
minimal effort. The wizard can be accessed from the Configuration Wizard Choices
dialog on the Help menu.

Once the index has been created, press ! on a word that is contained in the newly-
indexed help file to display the word as a choice in a help window. If no help topic is
found, a popup dialog displays all of the available help files. Select any of the help
files listed to initiate a second search.

CodeWright can also be set up to display help from files other than .HLP files (i.e.
.MVB, .IVT, .CHM and Visual Studio 6.0 or .NET .HTML help files). These processes
will be discussed next.

Accessing Visual Studio 6.0 or Visual Studio .NET Help Files

Microsoft Visual Studio 6.0 and Visual Studio .NET use an online help and
documentation system based on Microsoft HTML Help. CodeWright provides the
ability to access Visual Studio context sensitive HTML help using the ! key.

To set CodeWright up to access HTML help files, go to the Configure Help Index
dialog:
1. Click the MSDN Help Setup button.
2. Check Use HTML Help Viewer as default when keyword not found.

6- Editing & Printing 149

3. Select either MSDN Library Visual Studio 6.0 or MSDN Library Visual Studio
.NET, as appropriate.
3 For Visual Studio .NET, you may also specify the desired Collection
Reference. This refers to a specific MSDN library that you wish to access.
To see which references are available, check the Name field of registry
entries in the following location:
HKEY_LOCAL_MACHINE\Software\Microsoft\MSDN\7.0\Help
For example, to access SDK Documentation, you could specify a Collection
Reference of:
ms-help://MS.NETFrameworkSDK
4. Click the OK button on the MSDN Help Setup dialog.
5. Click the Save button on the Configure Help Index dialog.

When configured, the Search For Help On item in the Help menu (or ! key) will
be connected to Visual Studio 6.0 or Visual Studio .NET help. The first time you
invoke help, the HTML Help Viewer is launched, and a keyword lookup is
performed on the topic of interest. Subsequent help invocations bring the HTML
Help Viewer to the foreground and perform the lookup.

Accessing Compiled Microsoft HTML (.CHM) Help Files

Compiled Microsoft HTML files can be viewed with an HTML Help Viewer that
comes with Visual Studio. Windows must have a file association for .CHM files to
the executable hh.exe for CodeWright's help system to display a .CHM file.

To set CodeWright up to access .CHM help files, go to the Configure Help Index
dialog:
1. Press Add. The Add Helpfile Keywords dialog displays.
2. Browse for the desired .CHM file. You will probably need to select All Files in
the Files of Type drop-down list to see .CHM files.
3. Select the .CHM file and press Open. The file will now display in the Filename
window on the Configure Help Index dialog.
4. With the file still highlighted, press Edit.
5. On the Edit File Information dialog, type a Description to identify the .CHM
help file in your list.
6. Press OK to exit back to the Configure Help Index dialog, and Save to retain
your changes.
To access information from the indexed .CHM file, select Help|Search for Help On.
Type the Keyword to search for, select the desired entry from the .CHM file, and
press OK.

150 6- Editing & Printing

Accessing MSVC 5.0 (.IVT) Help Files
MSVC 5.0's Help format uses .IVT files known as InfoViewer Titles (formerly .MVB
files). These are read by the online MSVC system known as InfoViewer. InfoViewer
is built in to MSDEV.EXE, and is available stand-alone on the MSDN Library-Visual
Studio 97 CD, as IV5.EXE. If you have not installed the entire MSDN Library on
your drive, then you will need the MSDN CD in your CD drive when accessing help.

Complete the following steps in CodeWright:

1. In the Tools|Customize|Libraries dialog, under CodeWright Libraries, you will
find InfoViewer Titles. Check the box, and click OK.
2. Go to Help|Configure Index File.
3. Click the IVT Setup button, which allows you to set up InfoViewer as your
default help engine. If the button is disabled, then you need to de-select your
MVB viewer (click MVB Setup, uncheck Use as default when keyword not
found, and click OK). CodeWright can't use both .MVB and .IVT help files
concurrently.
4. On the InfoViewer Title Setup dialog, enter the name of the program used to
view the .IVT files (msdev.exe, or iv5.exe).
5. Check Use as default when keyword not found.
6. Select the search method you would like to employ (index, or full-text search).
7. Click OK, and finally click Close.
Now when you bring up the Find Help dialog via Help|Search for Help On, you’ll
see Use Installed InfoViewer Titles in the dialog listbox. Click OK, and CodeWright
will switch to InfoViewer and bring up the Search dialog with the appropriate
keyword. InfoViewer needs to be running to receive messages from CodeWright.
CodeWright will launch the InfoViewer program if it is not running.

Accessing MSVC 4.0 (.MVB) Help Files

To set CodeWright up to use MSVC 4.0 help files, complete the following:
1. Go to Help|Configure Index File and click MBV Setup.
2. In this dialog:
n Uncheck the Use Default Help box.
n Uncheck the Use DDE box.
n Remove the filename for the default .MVB file from the Topic field.
n Enter the following macro in the Topic field: $(MVBFILE).

6- Editing & Printing 151

3. Return to the Help|Configure Index File dialog.
4. Press the Add button. You will see that CodeWright now allows you to index
multiple .HLP and .MVB files. Add any necessary .MVB files.

Once the .MVB help integration setup is complete, position the cursor on a keyword
and press !, or enter the keyword in the Search for Help On dialog, to access all
the help (.HLP and .MVB) files listed in the index. A dialog box displays the help
files found; choose the help file to be viewed.

The next section talks about some of the more unique print features in CodeWright.

Printing
The CodeWright Print dialog has options that make printing more flexible and
efficient. Documents can be printed in color (if a color printer is available), line
numbers can be added, long lines can be wrapped or not wrapped (whatever the
choice may be), and sets of configurations can be created and stored with individual
print configuration names. A quick description of some of the features available in
the CodeWright Print dialog is available below, along with an explanation of the
Side-by-Side Difference Printing feature.

Print Dialog

Print Configurations
CodeWright has the ability to save named print configurations. The Configurations
tab of the Print dialog has a listbox that contains existing configuration names.

152 6- Editing & Printing

Create a configuration by choosing some options to be stored, typing a New
Configuration name, and then clicking Create.

Selected Print Configurations can be deleted, updated, or loaded. Both the Load and
Update operations modify the 'current configuration'.

Paper Selection Override

On the Page Setup tab of the Print dialog, there are three checkboxes available that
allow you to override the default paper size, source tray and orientation settings for
your printer. If not supplied, the default settings will be used.

Color Printing
The Options tab of the Print dialog has options for printing in color. The colors
printed will be those that are seen on the screen. It is also possible to distinguish
colors using font styles (bold, italics, underlined). Font styles and colors can be used
separately or together when printing.

Do not confuse font-style printing with the printed font. Documents printed in
CodeWright will always display the fonts that are set up in the Print dialog, not the
fonts that are displayed on the screen. The font styles are only for bolding, italicizing,
or underlining text being printed. Font styles can be specified in the Font Style
group of the Tools|Customize|View Themes|Colors dialog.

Print Preview
CodeWright has a Preview button in its Print dialog that allows you to see what the
document will look like before printing. The Print Preview has buttons for zooming
and for moving between pages in the document .

Multi-Copy Printing
The CodeWright multi-copy printing feature can use the multi-copy capabilities of a
printer, if present, in non-collated mode. The configuration options are on the Scope
tab of the Print dialog.

Printing Line Numbers

The numbering option on the Options tab of the Print dialog has a line-numbering
checkbox. Unmark the checkbox to turn off the number increment.

6- Editing & Printing 153

Wrapping Long Lines in Printed Documents
Two checkboxes pertain to line wrapping on the Options tab of the Print dialog:
Wrap Long Lines and Mark Wrapped Lines (dependent on Wrap Long Lines). The
first enables wrapping while the second controls the printing of a wrapping
indicator on each line continuation.

Print Headers and Footers

The header and footer groups on the Print|Page Setup dialog permit header and
footer text to be defined for each printed page. Next to the Header and Footer edit
boxes are buttons with right-pointing triangles. Press a button to display a menu
showing macros available for headers or footers, respectively. Selected macros are
inserted at the cursor position within the header or footer edit box automatically.

Available print macros refer, in a generalized way, to the page number (%p), current
date (%d), current time (%t), and name of the file you are printing (%f). Place these
keywords at the location within the header or footer string where you want the
corresponding information to appear.

Formatting Headers and Footers

You may define up to three fields within each header and footer: left-justified,
centered and right-justified. These fields are defined by the placement of
semicolons. The first portion or field is left-justified. The field following the first
semicolon is centered, and the portion following the second semicolon is right-
justified.

See the format diagram below:

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

Any field in this format may be empty.

Example: If you wanted to left-justify the filename but right-justify the date,
your format would look like this:
%f;;%d

Based on a filename C:\CW32\FOO.C printed on 1\1\1999, the printed

results of the above header/footer macros would look like:

C:\CW32\FOO.C 1\1\1999

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

;%P

154 6- Editing & Printing

Macros for Headers and Footers
Macros to be used in headers and footers are listed in the following table:

Macro Expansion Value

%d or %D date

%t or %T time

%f or %F filename

%v or %V volume

%r or %R root

%e or %E extension

%b or %B basename

%p page n of m

%P page number

%x or %X project path

%y or %Y project root

Side-by-Side Difference Printing

A Print button is available from the Side-by-Side Difference Window (on the
Difference tab of the Output Window) when the following conditions are true:
n The window is in View Mode.
n Both sides of the Window are in the same mode (i.e. normal, compressed), and
neither is in hex mode.

Modified Print Dialog

When you press the Print button from the Side-by-Side Difference Window, a
modified Print dialog entitled Print - Side by Side Difference displays. This dialog
operates much the same as the standard CodeWright Print dialog, with the
following differences:

6- Editing & Printing 155

n The Documents tab is disabled.
n The Selection Only radio button on the Scope tab is disabled.
n The Print Two Up, Wrap Long Lines and Mark Wrapped Lines checkboxes on
the Options tab are disabled.

Functionality
Printing the contents of the Side-by-Side Difference Window is similar to printing a
regular document in two-up mode, except that the left side will contain the
Reference document/file, while the right side will contain the Target document/file.
Differences between the documents are shown as follows:
n Lines that are "deleted" in one side will display as a minus sign only.
n Lines that are "added" on one side will print, preceded by a plus sign.
n Lines that are modified will be preceded by an asterisk.

156 6- Editing & Printing

7- Projects, Project
Spaces, and Workspaces
This chapter describes how to use the CodeWright project, project space, and
workspace facility. The complex relationships between files and groups of files that
are routine in program development demand the type of organization that can be
achieved with CodeWright projects.

Definitions
Projects, project spaces, and workspaces are defined as follows:

What is a Project?
A CodeWright project is a single file containing a list of filenames and settings that
are intended to make up the project. The contents of a CodeWright project are at the
discretion of the person making it. The configuration file containing the project files
and settings is stored in the directory in which the project was created, and is given
the name of the project with a .PJT extension.

Language, compiler, version control, clipboard and scrap, and other options can all
be stored in projects. Storing settings with CodeWright projects allows for unlimited
feature variation when going from project to project. With projects, the user can
create mini-environments for sets of files that, for example, use different compiler
options, have different promotion groups for version control, or use different
languages. Closing one project and opening another automatically sets the options
to that of the open project.

Overall, CodeWright projects allow the user to organize a group of files as a unit,
giving quick access to the configurations necessary for using and working with those
files more efficiently.

7- Projects, Project Spaces, and Workspaces 157

What is a Project Space?
Project spaces store and display sets of projects. Before a project can be made, a
project space has to be set up. The New, Open, and Close items on the
Project|Project Space submenu are for creating, opening and closing project spaces.
The Project Space submenu also has the Add New, Add Existing, and Remove
Project(s) menu items for adding new or existing projects, or for removing projects
from the current project space. The Project tab of the Project Window displays a
hierarchy of project spaces, the projects they contain, and each project’s member
files and their version control status.

What is a Workspace?
A workspace can be thought of as a separate instance of CodeWright. It is a "mini-
project" within a project. When you change workspaces, you have the ability to pick
up where you left off with a group of files. It doesn't matter if you worked on that
group of files a half-hour before or three months ago. It is as if an instance of
CodeWright were frozen in time containing these files.

A workspace differs from a project in that it does not store the system-wide options
normally stored in a configuration file. In a sense, the workspace is like a
CodeWright state file that is swapped on the fly.
3 For additional discussion of workspaces, refer to the topic Creating, Selecting and
Saving Workspaces, in this chapter.

Creating a Project Space

Before projects can be created, it is necessary to create a project space that will
contain them. Multiple project spaces can also be created, but only one can be open
at a time. To create a project space, do the following:
1. Click Project|Project Space|New.
2. Click Browse to make sure that the project space is being created in an
appropriate directory.
3. Type in a name for the project space in the Filename box. Keep in mind the
following:
n The Close existing documents/windows option causes all open windows
to be closed when the project is created.
n The Look in same directory for external workspace option automatically
inserts the name of any similarly-titled Visual Studio Workspace (.DSW or
.SLN) file that may reside in the same directory in which the project space
is being created in.

158 7- Projects, Project Spaces, and Workspaces

 3 A .PSP (CodeWright project space) file type extension is automatically
appended to the inserted name.
3 The contents of the corresponding .DSW or .SLN file will be read to
create the project space.
3 The option supports Visual Studio 5.0, 6.0 and 7.0 (.NET) only. Turn off
the option if none of those versions of Visual Studio is being used, or if
it is undesirable to have .DSW/.SLN files converted to CodeWright
project spaces.
3 For more information on what the Look in same directory for external
workspace option does, read the topic Reading External Makefiles and
Workspaces, in this chapter.
n CodeWright assumes the filename extension .PSP for project space
configuration files if one is not supplied. You may specify another
extension, if desired.
4. Click OK. The project space is created, and the Project|Properties dialog
appears, with the Members tab on top. The new project space is displayed in
the list box on the left, as shown in the following dialog.

Project|Properties|Members

Projects are added to project spaces, and then files to projects, in the Project|
Properties|Members dialog. The information for creating and adding files to
projects is contained in the section on Creating a Project and the Members tab of Project
Properties. Before covering that topic, however, it is necessary to have some
understanding of the Project Properties List and the process for setting project
configurations. Those topics will be covered next.

7- Projects, Project Spaces, and Workspaces 159

The Project Properties List and Project
Settings
The Project|Properties dialog is where many necessary CodeWright configuration
settings are made. One item in the dialog, the Project Properties List, is important to
all tabs of the dialog. The next few paragraphs talk about the Project Properties List,
and how the items in the box affect the rest of the dialog.

Project Properties List

The Project Properties List is available from all tabs of the Project|Properties dialog.
It lists the current project space and any projects that the space contains. It also lists a
special item called <Default Settings> that is used for setting global configurations
within the dialog. Configuration settings can be manipulated for any item selected in
the list box, but not all settings are available for all items. This is reflected by the fact
that the Project|Properties dialog changes depending on the item selected.

Project Properties List

Default Settings
The <Default Settings> item in the Project Properties List of the Project Properties
dialog is available at all times, regardless of whether or not there is a project or
project space open. Settings made in the Project Properties dialog while the
<Default Settings> item is selected will apply to all projects until those settings
have been changed for the projects individually. Settings made while a project is
selected are called "project-specific settings" and are stored with that project only.

160 7- Projects, Project Spaces, and Workspaces

Certain items and tabs in the Project|Properties dialog are only available when the
<Default Settings> item is selected; others are only available when projects or
project spaces are selected. The Members tab of the Project|Properties dialog, for
example, is used for adding projects to spaces and/or files to projects. It is therefore
not available when the <Default Settings> item is selected, since the <Default
Settings> item does not store projects or files. The Members tab is the only tab that
is not used for configuration settings, however. It is therefore the only tab that is
available at the project-space level, since project spaces do not store configuration
settings.

The other tabs in the dialog are available for the <Default Settings> item, as well as
for selected projects because they are used for making configuration changes that
can be either global (i.e. <Default Settings>) or specific to individual projects.

Working Directory
One important item to consider when setting project defaults is the project's
working directory. It is set in the Project|Properties|Directories dialog. The
working directory is the directory from which all tool commands (configured in the
Project|Properties|Tools dialog) are run.

The default-working directory is set to %x, a filename component macro that

expands to the directory containing the project's configuration file. You can select
Working Directory in the Directories list and press Browse to change the working
directory on the Project Working Directory dialog. (More information on the Tools
tab and filename component macros can be found under the topic Tools Tab of Project
Properties, in this chapter.)

Once the project's desired default settings have been established, appropriate
modifications can be made on a per-project basis. The information for setting project
configurations, and the tabs of the Project|Properties dialog, will be covered
throughout the remainder of this chapter.

Creating a Project and the Members

Tab of Project Properties
Once a project space has been created, you can add new or existing projects to it.
This can be done from the Project|Project Space menu, or the Project|Properties
|Members dialog. Project|Properties|Members should appear immediately after a
new project space has been created. Otherwise the dialog can be accessed via the
Project menu.

7- Projects, Project Spaces, and Workspaces 161

Creating a New Project
To create a CodeWright project in Project|Properties|Members, complete the
following steps:
1. Highlight the current project space in the Project Properties List on the left.

2. Click to access the Add New Project to Project Space dialog. (The same
dialog can be accessed using Add New Project on the Project|Project Space
submenu.) In the Add New Project to Project Space dialog, click Browse to
make sure that the directory in which the project is being created is appropriate.

Add New Project

3. Give the project a name. Keep in mind the following:

n The Look in same directory for external makefile option will automatically
insert the name of any similarly titled makefile that resides in the same
directory. Turn off the option if you don’t want makefile names inserted in
the Filename box. For more information on what this option does, read the
topic Reading External Makefiles and Workspaces.
n The Auto sync makefile option tells CodeWright to synchronize any
selected external makefile with the project being created, so that files that
are added to the makefile are automatically added to the CodeWright
project.
n CodeWright automatically uses a .PJT extension for project files.
4. Click OK. CodeWright creates a new project configuration file in the chosen
directory. The new project is listed in the Project Properties List, under the
current project space.

162 7- Projects, Project Spaces, and Workspaces

Adding Files to a Project
Files can be added once the project has been created. Files are added in the
Project|Properties|Members dialog. To add files do the following:
1. Highlight a project to which the files will be added in the Project Properties List.
2. Add the files using one of the following methods:

n Click to add a new file to the project.

n Click . Add individual files by typing in their names, or add multiple

files using file filters (e.g. *.C). Use the […] button to browse for different
directories.
Note: Semicolon delimited series of file specifications can be specified
when adding files. These file specifications would normally
include DOS wild-card characters. Paths are optional. (e.g.
*.C;*.H;*.CPP;C:\TEST\*.C;C:\TEST\*.H).
The Include Subdirectories checkbox causes matching files in
subdirectories to also be included.

n Use to browse for files. Add individual files by double-clicking or by

typing in the names. Add multiple files by S or C -clicking.

n Use the External Makefile option to read files from an existing makefile
into the project being created (see the topic on Reading External Makefiles
and Workspaces).
n Use the VCS Project option to 'read' a version-control project file (see Using
Version Control in CodeWright, in the chapter Version Control).
3. Click OK. Any matched files should be immediately added to the project.
Files that are included in the project are listed in the Files list box in the center of the
dialog. To delete files from the project, select them in the box and press the Delete
button.

Adding Existing Projects to a Space

Thus far we have discussed adding new projects to a project space, but we have not
covered the process for adding projects that already exist. That process will be
described here. To add existing projects to the current project space, access the
Project|Properties|Members dialog.

Complete the following steps:

1. Highlight the current project space in the Project Properties List.

7- Projects, Project Spaces, and Workspaces 163

Project|Properties|Members

2. Add projects using one of the following methods:

n Click to access the Select One or More Projects to Add to Project Space
dialog (also accessed using the Add Project… item on the Project|Project
Space menu). Browse for individual project files or use extended selection
listbox rules (i.e. SHIFT/CTRL keys with mouse clicks) to add multiple
projects from the same directory at a time.
n From the Read External Workspace dialog (accessed in the Project|
Properties|Members dialog) select an external Visual Studio workspace

that CodeWright will use to Read projects from. The projects will be
read from the Visual Studio workspace into the current CodeWright project
space. See the topic Reading External Makefiles and Workspaces for more
information.
3. Click OK. Appropriate projects should be immediately added to the project
space. The projects are shown below the current project space in the Project
Properties List.

Auto-detect File Type

The option Auto-detect file type in the CodeWright Tools|Customize|
Environment|File Options dialog allows CodeWright projects and project spaces to
be opened in any way that any file can be opened in CodeWright (e.g. File|Open,
drag and drop, opening from Project Window, opening from FTP dialog, etc). When
the option is marked, the following will occur when opening designated files with
any allowable file-open method:

164 7- Projects, Project Spaces, and Workspaces

n Files with .PSP file type extensions (CodeWright project space) will load as
CodeWright project spaces.
n Files with .DSW or .SLN file type extensions (Visual Studio workspace/solution)
will create CodeWright project spaces with autosync enabled (see Synchronize
Makefile/Workspace with Project/Project Space).
n Files with .PJT file type extensions (CodeWright project) will load as
CodeWright projects.
n Files with .DSP, .VCPROJ, .VBPROJ or .CSPROJ file type extensions (Visual
Studio project) will create CodeWright projects with autosync enabled (see
Synchronize Makefile/Workspace with Project/Project Space).
3 Any supported makefile will create a CodeWright project. See the drop-
down list under Makefile Type in the External Makefile dialog for a list of
supported makefiles.
3 Do not mark Auto-detect file type if you want CodeWright to load these
files for editing only.
n CodeWright will always override Auto-detect file type if a project file is opened
from the Output Window's Output or Search tabs (Search 1, Search 2, etc.).
Project files will always be opened as text files from these windows.

If the option Auto-detect file type is not marked, the files listed above will open as
normal edit buffers in CodeWright.

Reading External Makefiles and Visual Studio Workspaces

CodeWright can extract the names of projects or files from either Microsoft Visual
Studio workspaces or specified makefiles, adding them to the list of project space or
project members, respectively. This little bit of automation helps keep the
CodeWright project spaces and projects synchronized with the IDE. CodeWright
does not use the workspaces and makefiles directly, but adds the extracted filenames
to CodeWright project spaces (.PSP files) and projects (.PJT files).

To have CodeWright automatically use this capability, mark the Look in directory for
external makefile/workspace option in the Create a New Project Space dialog, or in
the Add New Project to Project Space dialog. CodeWright automatically searches
the directory in which the project/project space is being created for any makefiles or
workspace files whose names match the project/project space name specified. If the
files are found, CodeWright automatically inserts the name of the file into the Create
a New Project Space dialog, or the Add New Project to Project Space dialog. The
projects or files that are part of the workspace or makefile are subsequently read into
the CodeWright project or project space.

To have CodeWright manually read files or projects from selected makefiles or

workspaces into CodeWright projects or project spaces, do the following:

7- Projects, Project Spaces, and Workspaces 165

1. To read a workspace, select the current project space in the CodeWright Project
Properties List. To read a makefile, select a project from the same list box.

2. Select to bring up either the Read User Makefile or Read External

Workspace dialog.
Note: By default, CodeWright knows how to read Visual Studio 5.0, 6.0 and
7.0 (.NET) workspaces/solutions (.DSW or .SLN) and project files
(.DSP, .VCPROJ, .VBPROJ or .CSPROJ), and Microsoft Visual C++,
Borland, and CodeWright makefiles. These are listed in the drop-
down list box under the Makefile or Workspace Type combos.
3. Select the type of parser from the Makefile/Workspace type combo drop-downs
to use for parsing the filenames from the respective file. Keep in mind the
following:
n A parser is composed of a regular expression pattern used to search for
filenames and other pertinent strings in the makefile.
n If none of the predefined workspace or makefile types match the makefile
being used, a custom parser can be defined that will "understand" the
workspace/makefile type.
n Existing parsers can be used as references for building custom parsers. (For
detailed steps on making parsers, see the next topic on Steps for Setting up
New Makefile/Workspace Parsers.)
4. For makefiles only:
n Check the option Filenames can contain spaces if the makefile you are
reading contains filenames that have spaces, but are not quoted.
n Check the option Remove surrounding braces to treat the match inside
supported types of braces ("<>", "( )", "{}" and "[ ]") as a single filename.
The first matched character after the "\c" in the Regular Expresssion Parser
value is checked for the opening brace.
5. Press OK.

6. In the Project|Properties|Members dialog, press . The project or project

space will then be populated with files or projects that correspond to files or
projects contained in the associated makefile or workspace.

Steps for Setting up New Makefile/Workspace Parsers

Use the following steps to set up a new makefile/workspace parser:
1. In the Project Properties List, highlight a project or a project space.

2. Click in the External Workspace/Makefile section.

166 7- Projects, Project Spaces, and Workspaces

3. Browse for the appropriate makefile or workspace file using the Browse button
next to the Workspace/Makefile Name edit box in the Read External
Workspace/Makefile dialog.
4. In the Makefile/Workspace Type edit box, give the parser a descriptive name.
5. Enter an applicable regular expression for the Regular Expression Parser.
6. If you want to synchronize the makefile or workspace with the CodeWright
project or project space (i.e. update the CodeWright project/project space with a
new file/project when a new file or project is added to the makefile or
workspace), mark Auto Sync Workspace/Makefile (described next).
7. For makefiles only:
n Check the option Filenames can contain spaces if the makefile you are
reading contains filenames that have spaces, but are not quoted.
n Check the option Remove surrounding braces to treat the match inside
supported types of braces ("<>", "( )", "{}" and "[ ]") as a single filename.
The first matched character after the "\c" in the Regular Expresssion Parser
value is checked for the opening brace.
8. Click OK.

9. Click Read .
10. Click OK. Files or projects in the makefile or workspace are added to the project
or project space.

Creating a new makefile or workspace parser requires some knowledge of regular

expressions. See Regular Expressions in the chapter Search and Replace and Navigational
Tools.

Synchronize Makefile/Workspace with Project/Project Space

The CodeWright makefile/workspace reader provides an auto-synchronize feature
that will synchronize the projects and project spaces with associated external
makefiles and workspaces. The option is called Auto Sync, and is available in the
Create a New Project Space, Add New Project to Project Space, Read External
Workspace and Read User Makefile dialogs. When enabled, Auto Sync Makefile/
Workspace will automatically add new files and projects to CodeWright projects and
project spaces when corresponding makefiles or workspaces have been updated
with those files. The makefile or workspace can be any of the predefined types in the
Makefile/Workspace Type drop-down lists.
When Auto Sync is enabled for either makefiles or workspaces, all the items in the

Project|Properties|Members dialog are disabled except for . The ability to

manually add files or projects is not allowed because the files are taken from the
makefile or workspace. Any manually added or deleted files or projects are
eliminated from the project when the sync occurs.
Note: Version Control Management items are not affected.

7- Projects, Project Spaces, and Workspaces 167

Characteristics of the Project Tab
The Project Window’s Project tab displays projects and project spaces. By default,
the Project Window is displayed on the left-hand side of the CodeWright screen.

To open a file for editing, double-click on the file in the Project tab.

Organizing the Hierarchy

Projects, project spaces, and files will only show in the Project tab of the Project
Window when a project space containing those projects and files has been opened in
CodeWright. Projects are displayed under the project space, and project member-
files are then grouped under each individual project, based on the buttons that you
have enabled at the top of the dialog:

n Use Filters to Group Files: Press to use and show project file filters on the
Project tab. When the button is in the raised position, the filters are not used
and do not display. You can define filters on the Project|Propeties|Filters tab.
For more information, refer to the topic Filters Tab of Project Properties, later in
this chapter.

n Use Directory Tree to Group Files: Press to group files by their path under
folder nodes. The folder nodes that group the files can contain multiple path
components. File nodes do not show the full path since it is shown in the
preceding folder nodes.

n File Sorting: Press to sort by filename, according to the settings you have
made on the Tools|Customize|Environment|File Sort Mode dialog.
When the File Sorting button is not selected (in the raised position), the tooltip
says File sorting (Currently by State then File Sort Mode). In this mode, the file
state (indicated by the version control file icon) is used for the primary sort, and
the filename is used for a secondary sort. The following rules apply:
3 Deleted files show before read/write files.
3 Read-only files are last.
3 Files in the same version control state (e.g. checkin in) are grouped
together, with the archived type being last.

The state of whether each node is expanded or not will be saved in the project space
(.psp) file, and restored when you start CodeWright or change project spaces.

168 7- Projects, Project Spaces, and Workspaces

Project Window: Project Tab

Version Control
The primary purpose of the Project tab is to open files and facilitate version control
operations. Right-click on a file, or on a selected group of files, in the Project tab to
bring up a menu listing various operations that can be performed on the file(s). If
the selection of files includes filters and folder items, these are simply removed
before the file operation is performed.

When files are under version control, file icons depict different states of the file:

n When the files are checked-in (or read-only) the icons that represent the
files are grayed out.

n When the files are checked out, CodeWright conveniently places a red
checkmark to the upper right of the file icons.

n If another user has a lock on a file that is part of the project being worked
on, CodeWright will display the file with a gray checkmark in the Project tab.

n Some Version Control projects are set to delete work files when they are
checked in. CodeWright displays files not found at the specified location
(usually archived) with an exclamation point.

7- Projects, Project Spaces, and Workspaces 169

n When the current edit buffer differs from the latest revision in version
control, CodeWright gives the corresponding file icon a slightly different color.

Note: Press the Refresh button from time to time when using the
Project tab to see the most current status of the files. Hover over any
icon to display its meaning in a helpful tooltip.

Directories Tab of Project Properties

The Directories tab of the Project|Properties dialog is used to display and set the
project's working directory as well as other directories for various system files used
in CodeWright. Complete the following steps to access/edit the appropriate version
of the Directories tab:
1. Access the Project|Properties dialog.
2. In the Project Properties List:
n Select a project if the directories being viewed or modified are intended to
be specific to the selected project only.
n Select <Default Settings> if the directories being viewed or modified are
intended to be global.
3. Click on the Directories tab. Most of the directories and filenames listed in this
dialog can be made project-specific, but only if the System Options checkbox is
marked. Once System Options is marked, the names of most of the listed files
will be available for editing. They can then be made project-specific by giving
them unique names for the selected project.

Project|Properties|Directories

170 7- Projects, Project Spaces, and Workspaces

A brief description of each of the directory and file listings in Project|
Properties|Directories follows:
n The Working Directory is the directory from which commands set on the Tools
tab of the Project|Properties dialog will be run. By default, the working
directory is set to %x, a filename component macro that expands to the
directory in which the project file resides.
n The Browser Database indicates the name and location of the Microsoft
Browser Database (.BSC) or the compiled tags database (.PTG). More
information about tags can be found in the chapter on Search and Replace and
Navigational Tools.
n The Tag Database indicates the name and location of the file that contains tags
information. More information about tags can be found in the chapter on Search
and Replace and Navigational Tools.
n The Text Link DB indicates the name and location of the file that stores Button
Link information. More information about Button Links can be found in the
chapter on Search and Replace and Navigational Tools.
n The Mark Database indicates the name and location of the file that stores
bookmark information. More information about bookmarks can be found in the
chapter on Search and Replace and Navigational Tools.
n The Extension File indicates the name and location of the file that stores
extension-specific information. In the Settings area, specify a User Named File,
the Configuration file, or the Project File.
n The Button File indicates the name and location of the file that stores toolbar
resources and default button descriptions. Refer to the online topic Dockable
Windows and Toolbars in CodeWright’s online help.
n The Macro File indicates the name and location of the file that stores API and
keystroke macros. More information about API macros can be found in the
chapter on Extend CodeWright.
n The Symbol File indicates the name and location of the file that stores
information about symbols. If you create a project within a project space, the
default symbol file name is the name of the project with a .SBL extension (i.e.
<project_name>.SBL). If an existing project’s symbol file is CWRIGHT.SBL (the
non-project default name), you will be prompted to change the symbol file
name. It is advantageous to have project-specific symbol files in order to limit
the size of the files, thereby optimizing CodeWright's performance.
Selecting the Symbol File option in the Directories tab makes two options
available: Auto-Update Symbol Database and Show Definitions in Symbols
Tab. These options control whether or not symbols information is automatically
computed when projects are made current. Unmarking these options can speed
up the process of opening projects. More information on Symbols can be found
in the chapter Search and Replace and Navigational Tools.

7- Projects, Project Spaces, and Workspaces 171

n The Edit Search Path specifies the order of directories to be searched when
opening files without specifying the directory in which the file resides. The Edit
Search Path is primarily useful when using the CodeWright status line prompt
for opening files, instead of common dialogs. To define more than one directory
in the Edit Search Path, separate the directories with semicolons. Add an
asterisk to the end of a component of the EditPath to specify an entire directory
sub-tree.
Example: The EditPath C:\INCLUDE\MSVC;C:\CW\* will cause CodeWright
to first look in C:\INCLUDE\MSVC and then in C:\CW and then in
all subdirectories of C:\CW.
The traversal of the sub-tree is done depth-first, meaning that a sub-tree is
traversed all the way down to its leaves before moving on to the next sub-tree.
Note: The backslash prior to the asterisk is optional; the two forms are
entirely equivalent.

Storing Configuration Options with a Project

CodeWright projects can store configuration settings individually, making them a
convenient way to have multiple sets of configurations in one editor. Some settings
are stored automatically, when changes are made to the Project|Properties dialog
while a project is selected. Others will only be stored with the project if certain
options are marked in various CodeWright dialogs. The settings that may be stored
with projects are listed next:
n System Options: Mark Store System Options in Project File for selected
projects in Project|Properties|Directories. The following settings are affected:
3 All options on the DLL Coloring Dialog.
3 Options in the CodeWright Key Repeat group on the Tools|Customize|
Environment|Keymap dialog.
3 The Global Backup Spec on the Tools|Customize|Environment|Backup
dialog.
3 All settings on the Bookmarks, File Options and General tabs of the
Tools|Customize|Environment dialog.
n Auto-save options: Mark Store Auto-save Options in the project file in
Tools|Customize|Environment|Backup while the desired project is open.
n Language options: Select the Project File radio button when the Extension File
option is chosen from the list in Project |Properties|Directories, for selected
projects.
n Filename Filters: Mark Save Filename Filters in project file in File|Filters while
the desired project is open.

172 7- Projects, Project Spaces, and Workspaces

n Clipboard/Scrap options: Mark Store Clipboard/Scrap in project file in
Tools|Customize|Environment|Clipboard while the desired project is open.
n Compiler and Command Line Version Control settings: Make the desired
configurations in Project|Properties|Tools while the desired project is selected.

In addition to indicating that certain system options be stored with the project, the
Store System Options in Project File checkbox in Project|Properties|Directories
allows the listed configuration file names to be edited. Changing the names of those
files on a per-project basis allows them to be made project-specific so that the
settings they store will also be project specific. To set the Store System Options in
Project File checkbox on the appropriate version of the Directories tab, complete the
following steps:
1. Access the Project|Properties dialog.
2. In the Project Properties List:
n Select a project if the options being viewed or modified are intended to be
specific to the selected project only, OR
n Choose <Default Settings> if the options being viewed or modified are
intended to be global.
3. Click the Directories tab.
4. Check the Systems Options checkbox, and press OK.

Reading Configuration Settings from Other

Files
In addition to storing configuration settings with projects, it may sometimes be
desirable to read specified configuration settings from designated configuration files
into a project or into the global configuration settings. It is possible to have
CodeWright read configuration settings from a configuration file using an option on
the Project menu called Read Configuration Data .... The configuration information
gathered will be placed in the main configuration file in CodeWright, or in a
CodeWright project or project space file, depending on the data being read and
whether a project is open or not.

The series of checkboxes in the Read Configuration Data dialog limit what settings
are read from the file. When marked, the Update Configuration Files checkbox
immediately updates the project and/or configuration files with the specified
information.

7- Projects, Project Spaces, and Workspaces 173

Tools Tab of Project Properties
The Tools tab of the Project|Properties dialog is used for setting up various tools,
such as command line compilers and version control utilities, needed to perform
various jobs on files being edited in CodeWright. These tools can be made project-
specific or global.

To access/edit the appropriate version of the Tools tab, complete the following:
1. Access the Project|Properties dialog.
2. In the Project Properties List:
n Select a project if the tools being viewed or modified are intended to be
specific to the selected project only.
n Choose <Default Settings> if the tools being viewed or modified are
intended to be global.
3. Click on the Tools tab.

Tool Categories
The items in the Tools tab change depending on the tool category. Different tool
categories can be selected from the drop-down list under the Category combo box.
Project tools include command line entries for compile utilities, make or build
utilities, executables that may be run on a regular basis, and command line version
control utilities. CodeWright doesn't come with the utilities (e.g. compilers and
version control); these must be purchased separately. CodeWright simply provides a
way to use the utilities in a more practical and efficient way.
The tools in the various categories correspond to menu items and buttons in
CodeWright that are used to run the utilities. When one of the menu items or
buttons is clicked, CodeWright runs the tool by shelling to DOS and running the
tool’s command. Any output generated is captured for display in designated tabs of
the CodeWright Output Window. The specific tool categories are:
n Build
n Compile
n Custom
n VCS
The following sections describe the tool categories in Project| Properties|Tools.

174 7- Projects, Project Spaces, and Workspaces

Build Tools
The Build category of tools in Project|Properties|Tools consists of the following:
n Build
n Rebuild
n Debug
n Execute
n Build Tags

Project|Properties|Tools - Build Category

These tools (with the exception of Build Tags) should be set with any make and
execute utilities necessary for building or running the files being edited in
CodeWright.

Settings For: Field

The Settings For: field is available for the Build category on the
Project|Properties|Tools dialog. Select the Debug configuration, Release
configuration, a custom configuration, or All Configurations, then complete the
remainder of the dialog for that configuration.
Configurations allow you additional flexibility in setting options for your Build
and Compile commands. By default, CodeWright provides a Release
configuration and a Debug configuration. You can modify these, and add any
number of custom configurations, minimizing changes after the initial setup
phase.
3 To select a configuration shown in the Settings For: field for use in
executing Build and Compile commands, select it from the
Build|Configurations dialog and press Set Active.

7- Projects, Project Spaces, and Workspaces 175

 3 To name a new configuration to be further configured on the
Project|Properties|Tools dialog, select Build|Configurations, press New,
and complete the Create New Configuration dialog.

Build Command Line

A good starting point for the Build field on the Tools tab is to enter whatever
would be typed at a DOS prompt for the intended purpose. Filename
component macros can be used as placeholders for specific file paths or path
components, project names or directories. (Refer to the table under the topic
Filename Component Macros in the previous chapter on Projects, Project Spaces, and
Workspaces for a list of the macros.)
Example: If you use Microsoft’s Visual C++, a good general-purpose Make
command might be:
${FTEE} nmake -f %y.MAK

If the current project is MYPROJ,CodeWright will transform this line

to

C:\CW32\FTEE.EXE nmake -f myproj.MAK

3 When you move from CodeWright 7.0 to 7.5, any Debug Build command
that you had set up becomes part of the initial Debug configuration; the
Release configuration will initially use the regular Build command you had
defined. Created configurations also use regular Build commands.

Filename Component and Symbolic Macros

Filename component and symbolic macros can be used as placeholders that will
insert or transform filenames and filename components (directories, filenames,
etc) that need to be used with the utilities. This eliminates the need to manually
insert filenames every time a new file is opened in CodeWright for editing or
compiling. More information on filename component macros is provided in the
section on Filename Component Macros.

Build Tags Tool

The Build Tags tool in the Build category does not need to be configured like
the other tools. It comes pre-set with the appropriate command needed to run
the Tags utility provided with CodeWright.

Compile Tools
The Compile category of tools in Project|Properties|Tools is displayed in the
following image:

176 7- Projects, Project Spaces, and Workspaces

Project|Properties|Tools – Compile Category

The Compile tools should be set with any compile utilities necessary for compiling
the files being edited in CodeWright.

Filename Component and Symbolic Macros

Filename component and symbolic macros can be used as placeholders that will
insert or transform filenames and filename components (directories, filenames,
etc.) that need to be used with the utilities. This eliminates the need to manually
insert filenames every time a new file is opened in CodeWright for editing or
compiling. More information on filename component and symbolic macros can
be found in the sections on Filename Component Macros and Symbolic Macros.

Response File Contents

The Response File Contents edit box in the Compile category of tools is used
for commands that may be too long or that may be better used in a batch file. It
only comes into play if the %Q macro is being used on one or both of the
compile command lines. See the topic Response File for more information.

Compiler Command Line

A good starting point for the compiler fields on the Project|Properties|Tools tab
is to enter whatever would be typed at a DOS prompt for launching a compile.
1. In Project|Properties|Tools, under the Compile category, choose the
File Type of the language that the compiler will be used for (see
Compiler Definition above).
2. In the Settings For: field, select the configuration under which the
current settings should be saved (Debug, Release, a custom
configuration, or All Configurations).
3. Enter the compile command line in the Command: field.

7- Projects, Project Spaces, and Workspaces 177

 3 Use the Macro Assistant to add filename component macros to
expand the name of the current CodeWright edit buffer. Use the
macros, as desired, within and at the end of the command.
3 When you move from CodeWright 7.0 to 7.5, any Debug Compile
command that you had set up becomes part of the initial Debug
configuration; the Release configuration will initially use the
regular Compile command you had defined. Created
configurations also use regular Compile commands.
3 If you want to set up a custom configuration that has a Debug
compile command line and a Release compile command line, you
must do the following:
a. Temporarily select the Debug configuration in the Settings
For: field.
b. Select the compiler definition in the Name field that you will
also use for your custom configuration.
Note: You may want to create a new compiler definition for
your custom configuration, since the compile and
debug compile settings for a given definition are shared
by all extensions and configurations with which it is
associated.
c. Save the Debug configuration.
Once you have completed the custom configuration and saved it,
you will likely want to go back to the Debug configuration and
change the compiler definition back to what you had before.
4. Choose appropriate Command Options for saving files, capturing
output, and specifying command shell-window size.
5. Click OK.

More Information
The Compile tools are the most commonly used tools in the Project|
Properties|Tools dialog. Therefore, the instructions for setting them up are
given their own chapter, called Set up a Compiler. Many of the concepts described
therein apply to the other tool-categories as well. Refer to it for more detailed
information on setting up Compile and other project tools.

178 7- Projects, Project Spaces, and Workspaces

Custom Tools
The Custom category of tools is provided for running any DOS program from
within CodeWright. Adding a custom tool in Project|Properties|Tools will add it to
a list at the bottom of the CodeWright Tools menu. Clicking on a tool's name in the
menu will then run the tool’s associated program. One custom tool is already set up
in CodeWright: the Windows Paint program.

Project|Properties|Tools – Custom Category

To make a new custom tool:

1. Select Project|Properties|Tools.
2. Choose Custom from the list of categories in the list under the Categories
combo box.
3. Click on Add.
4. Give the custom tool a name.
5. Click OK.
6. Highlight the new custom tool in the listbox.
7. In the Command: edit box, type the appropriate command for running the
intended program. (To make a tool that runs a CodeWright API, type the API in
the Command box, and precede it with a !.)
8. Choose any necessary command options. For descriptions on the command
options, see the topic Command Options on the Tools Tab, in this chapter.

7- Projects, Project Spaces, and Workspaces 179

VCS Tools
The VCS category of tools in the Project|Properties|Tools dialog consists of a
number of tools associated with various version control operations; these operations
are available on different menus, buttons and dialogs in CodeWright. Set the tools
with the commands that will run any command-line version control utilities used to
perform version control operations (e.g. GET.EXE or PUT.EXE).

Project|Properties|Tools – VCS Category

You will notice that the VCS tools come pre-configured with commands for some of
the more popular version control systems. The pre-configured commands change
depending on the provider-name chosen in the Command Line Provider list box in
the Tools|Version Control|Setup (or Tools|Customize|Version Control|General)
dialog.

You can use filename component and symbolic macros as placeholders to insert or
transform filenames and filename components (directories, filenames, etc) used with
the version control utilities. This eliminates the need to manually insert filenames
every time a new file is opened in CodeWright for editing or compiling. More
information on filename component and symbolic macros can be found in the
sections on Filename Component Macros and Symbolic Macros.

You should only be concerned with the VCS tools if you use command line (DOS)
version control utilities, such as PVCS GET.EXE or MS VSS SS.EXE, to carry out your
version control operations. You should also be aware that the VCS category of tools
is not the only method for using version control in CodeWright. Version control
operations can also be performed via SCC API integration. More information about
using either of the Version Control integration methods can be found in the chapter
on Version Control.

180 7- Projects, Project Spaces, and Workspaces

Setting up Project Tools
Setting up most of the project tools is a fairly straightforward process. In their
simplest form, the steps for configuring project tools are as follows:
1. Choose the appropriate tool-category (i.e. Build, Compile, Custom, etc).
2. Highlight or choose the tool to be configured.
3. Groups of settings are saved as configurations. For the Build or Compile
categories, select a configuration name from the Settings For: field (i.e. Release,
Debug, a custom configuration, or All Configurations).
3 To name a new configuration to be further configured on the
Project|Properties|Tools dialog, select Build|Configurations, press New,
and complete the Create New Configuration dialog.
4. Enter the appropriate command in the Command: edit box at the bottom of the
dialog. (To make a tool that runs a CodeWright API, type the API in the
Command box, and precede it with a !.)
Note: The preceding steps are based on the assumption that the utility
being launched will run successfully from any directory in the
operating system. This means that the proper environment variables
and PATH statements must be set according to the instructions
provided with the utility in question. Otherwise, the full path and
filename of any utilities being used must be inserted with the
command when performing step number 3.
For more detailed information about setting and configuring project tools, see the
chapter Set up a Compiler. Although the chapter specifically talks about setting up
tools in the Compile category, the concepts generally apply to all categories of
project tools.

You may notice that many of the project tools in the Tools tab are already
configured. These pre-set commands may not apply to the utilities actually being
used. In such cases, the tools will need to be reconfigured.
Example: Highlighting the Build tool for the first time shows the following
command in the Command: edit box:
${FTEE} nmake CFG="%x - Win32 Release"
Nmake is Microsoft's make utility, which may not be the utility of
choice for the files being edited. If that is the case, it will be necessary
to change the command to apply the obligatory utilities for the files
being edited.
The ${FTEE} macro expands the full path and filename of FTEE.EXE,
a utility that pipes output to a running DOS window. A detailed
description of FTEE can be found in the chapter on Set up a Compiler.

7- Projects, Project Spaces, and Workspaces 181

Command Options on the Tools Tab
Each category of tools in the Project|Properties|Tools dialog has a number of
options that affect what happens when any of the various tools are run.
Example: To control how CodeWright redirects the output generated by any
of the utilities associated with the tool being used, one would mark
or unmark the Redirect Output option in the list of command
options displayed underneath the Command edit box.
The command options should be set individually for each tool being used, regardless
of the tool’s category. Descriptions of the command options follow:
n Redirect Output appends the following items to the end of the command that
runs the tool's program:
3 A DOS redirection operator.
3 The Error Filename listed on the Errors tab.

With this option marked, any output that normally displays in a DOS
window will be redirected into the error file. CodeWright then uses an
FTEE program to display that information in the Output tab of the Output
Window. (More information about FTEE can be found in the in the chapter
on Set up a Compiler.)
n No Command Shell causes the command not to be run in a command shell
(COMMAND.COM or CMD.EXE). If you select this option, redirection and
other services will not be available. If you are executing a Windows program,
there is no need for a command shell.
n Save Current File causes the current file to be saved before the corresponding
tool runs.
n Save All Files causes all files opened in CodeWright to be saved before the
corresponding tool runs.
n Background determines if the program is executed in the foreground or the
background. If you elect to execute the program in the background, a message
will appear in CodeWright's status bar, and a beep sounds to indicate that the
program has been completed.
n Use VDOS causes from the compile or build to be sent to the VDOS window.
This is convenient for cutting and pasting from the output, and for re-executing
commands, but you may not be able to see a prompt if the program prompts for
a response.
n Prompt for Arguments causes a prompt to come up before the tool executes,
allowing the user to insert extra parameters to be used by the associated
program.

182 7- Projects, Project Spaces, and Workspaces

Filename Component Macros
When compiling or building projects, it is usually necessary to have a source or
make-file for the target of the build or compile. When setting up target files for
project tools, it isn't convenient to use literal filenames, since filenames will vary as
files are opened and closed. For this reason, CodeWright provides a number of
Filename Component Macros to be used on the various project-tool command lines.
These macros will expand the names, or portions of names, of current files or
projects in CodeWright.

Each category of tools has one or more macro assistants that can be used to quickly
insert appropriate filename component macros at the cursor-position of any one of
the tools' command lines. The macro assistant provides a popup menu listing
available macros. To access the popup menu, click the black right-arrow on the gray
portion of the Command edit box.

A sample Macro Assistant popup menu is provided:

Macro Assistant

7- Projects, Project Spaces, and Workspaces 183

A list of these macros and the filename specs they represent are listed in the
following table. An example of how each macro looks when expanded is also
provided. The examples are based on a file named FOO.C residing in the directory
"C:\TEST" with the CodeWright project "FOOPROJ.PJT" open (also residing in
C:\TEST). A version control project "VCSproj" is open as well, with its project file also
in C:\TEST.

Filename Component Macros

Components Description

%% Percent sign Since component macros begin with a

percent sign, you must use two percent signs to represent
a literal % in your command.

%b Basename The complete workfile name, less the

extension. (e.g. C:\TEST\FOO)

%d Directory The directory component of the workfile. This

component has no filename and no drive component. It
also has no trailing backslash. (e.g. \TEST)

%e Extension The extension of the workfile. This component

begins with a dot ( . ) unless the extension is null. (e.g. .C)

%n Project Name The name of the version control project, if

one has been defined and selected. If a project file is in
use, this will expand to the path of the project file.
Otherwise, this macro expands to a null string. (e.g.
C:\TEST\VCSPROJ)

%p Path The path component of the workfile. This

component has no filename and no drive component. It
has a trailing backslash. (e.g. \TEST\)

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

FOO)

%v Volume The drive component of the workfile, consisting

of a letter and a colon. (e.g. C:)

%x Project Path The path component of the project file

currently in use (usually indicates the project directory).
(e.g. C:\TEST)

184 7- Projects, Project Spaces, and Workspaces

 Filename Component Macros

Components Description

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

in use. (e.g. FOOPROJ)

%Q Response File A temporary response file containing text

that will be used with or for the command being
configured. This macro is case sensitive; you must use an
upper case Q. See the default check-in command for an
example of its use.

Uppercase Macros
You can enable uppercase versions of these macros to support short (8.3) filenames,
while the lowercase macros support long filenames. To do so, complete the
following steps:
1. Go to Tools|API Command to display the command line prompt.
2. Type the following command:
SysFlagsEx=1,SYSFLAG1_ENABLE_SHORT_FILENAMES, SET_FLAGS

3. Press E to execute the command.

4. Go to the Tools|Customize|Environment|General dialog.

5. Toggle any checkbox and hit the OK button.

Response File
The %Q macro and the Response File Contents edit box (on the Project| Properties|
Tools dialog) work together to automate response files and avoid command line
length limits. The Response File Contents edit box only comes into play if you have
used the %Q macro on one or both of your compile command lines.
Note: This macro is case sensitive. An uppercase Q must be used.
When the %Q macro is used in a compile command, the name of a temporary file is
substituted at that position in the command line. Before execution of the command,
the contents of the Response File Contents edit box are written to that temporary
file.
Example: cl /c @%Q

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

7- Projects, Project Spaces, and Workspaces 185

This syntax will cause the temporary file to be a batch file that can be executed alone.
Most of the filename component macros can be used in other tabs of the Project|
Properties dialog as well.
Example: %x is used to specify the project's working directory in
Project|Properties|Directories.
%b is used to specify the base name of the error file listed in
Project|Properties|Errors.

Symbolic Macros
Symbolic macros are another form of macro that can be used with many of the
commands in the Project|Properties|Tools dialog. CodeWright Symbolic macros are
meant to make the process of constructing command lines more flexible and
convenient.

Symbolic macros take the form ${NAME} or $(NAME). At the time the command
line is evaluated or run, the dollar sign and braces are removed and the symbolic
NAME is replaced in accordance with the table on the following page.
Note: As a special case, if the first character of NAME is a question mark, the
rest of the NAME string is treated as an executable macro. The result
returned by the macro is converted to a string, if necessary, and
substituted for the macro occurrence. If the executed macro returns a
type other than integer or string, it is treated as if it returned an
empty string.
Example: A symbolic macro that is commonly used with some of the default
commands is ${FTEE}, which expands the full path and filename
of FTEE.EXE, a utility that pipes output to the CodeWright Output
Window (described in the chapter on Set up a Compiler).
A list of Symbolic Macros and their descriptions appear next.

Symbolic Macros

Macro Description

$(BROWSEFILE) Browser file as defined in the Directories tab of the

Project|Properties dialog.

$(FTEE) The Borland command for splitting output so that it goes

to a file and to the screen. This command varies
according to platform.

$(HOME) The CodeWright home directory.

186 7- Projects, Project Spaces, and Workspaces

 Symbolic Macros

Macro Description

$(KEYWORD) The word at the cursor when a context-sensitive help

function is invoked. This is used in the Default Help file
settings. (Help menu, Configure Index… item)

$(TAGFILE) Tag file name as defined in Project|Properties.

$(USER) User ID defined in Tools|Version Control|Setup.

$(VCSLABEL) Revision label as defined in Tools|Version Control|

Maintenance.

$(WTAGS) The Borland command for generating a tags database.

This command varies according to platform.

Note: Braces {} may be used instead of parentheses ().

Additional symbolic names can be defined with the SetStringMacro function (help
for the SetStringMacro function and other CodeWright APIs can be found in the
online help; go to Help|CodeWright API Library). Any names not defined are
taken as environment variables.

Errors tab of Project Properties

The Errors tab of the Project|Properties dialog is used for specifying the name of the
file used to capture output produced from a Build or Compile. It is also where
appropriate error parsers are specified for accessing the errors displayed in the
Output tab on the CodeWright Output Window.

CodeWright uses two methods for capturing and displaying output from a compile.
These methods, called FTEE and VDOS, are described in the next chapter on Set up a
Compiler. Once the output has been captured, CodeWright uses Error Parsers to
access the files that contain the errors in that output.

An error parser is a function that takes error messages from a compiler, assembler, or
linker and extracts the name, line number and error message for the file in which the
error occurs. CodeWright uses that extracted information for error navigation. The
error parsers allow you to double-click on an error or warning in the Output
Window in order to bring up the source file(s) containing the error(s). The cursor will
be positioned at the line where the error or warning occurs.

7- Projects, Project Spaces, and Workspaces 187

To access/edit the appropriate version of the Errors tab, complete the following steps:
1. Access the Project|Properties dialog.
2. In the Project Properties List:
n Select a project if the error configurations being viewed or modified are
intended to be specific to the selected project only, OR
n Select <Default Settings> if the error configurations being viewed or
modified are intended to be global.
3. Click on the Errors tab.

Project|Properties|Errors

There are three combo-boxes in Project|Properties|Errors and one edit box for the
Error File. Complete the boxes as outlined next.
n In the edit box Error Filename: specify the file needed to capture any output
produced by a compile or build. The error file is the name of the file that is used
to capture the output of commands that have the Redirect Output command
option checked (see the topic Command Options on the Tools Tab, in this chapter,
for more information).
3 Error files are created in the current directory.
3 The error file is set to PROJ.ERR by default, but can be changed to any
filename desired.
3 Filename component macros can be used for the filename, but it's usually
best to leave it as it is.
The output captured by the error file will be used to display in the Output tab of
the CodeWright Output Window.

188 7- Projects, Project Spaces, and Workspaces

n Use the next three combo-boxes to specify any error parsers necessary for
accessing the errors in the Output tab of the Output Window. Only one parser is
necessary, but up to three may be used.
Example: The output of a build or rebuild might contain output from
a compiler, linker and assembler. If so, three error parsers
will process the errors more efficiently than one.
Note: Don't be too concerned if an error parser for your compiler isn't
listed. When in doubt, try the Default parser
(DefaultErrorInfo).
n The drop-down lists under the error parser combos contain the names of
various error parsers available to CodeWright. More parsers can be added by
marking the Error Parsers options in Tools|Customize|Libraries.
n Choose the appropriate error parser for the compiler being used. Usually the
correct parser contains the compiler's name or the compiler's company name.
n If there are no parsers for a particular compiler, it is possible to make a custom
error parser. Press the Custom Error Parsers… button to access a dialog in
which custom error parsers can be built, as described in the next section on
Custom Error Parsers.

Custom Error Parsers

The error parsers available for CodeWright are listed in the drop-down lists under
each of the three error parser combo boxes in Project|Properties|Errors. More error
parsers can be added to the list by clicking the Error Parsers options in the list of
CodeWright Libraries in the Tools|Customize|Libraries dialog. If the appropriate
error parser is not available, it is possible to make one using the Custom Error
Parsers dialog, accessed by clicking the Custom Error Parsers button in the Project|
Properties|Errors dialog.

Custom Error Parser

7- Projects, Project Spaces, and Workspaces 189

All error parsers are made up of regular expression patterns. These patterns are
used for searching error output for the filename, line number and error message of
the errors that were produced by the compiler. To make a custom error parser, you
must create a regular expression that will find the output strings that make up the
errors. Use regular expression grouping and alternation patterns to group the
expression pattern in a way that the filename, line number, and error message of the
matching strings are each made into separate entities.

A sample regular expression for making an error parser for the Microsoft J++ Java
compiler follows. Instructions for making the parser are also provided.

Description Regex Pattern Groups

Microsoft J++ Java ^(.+):([0-9]+):[ \t]*(.+)$ Filename: 1

Line Number: 2

Message: 3

To make a custom error parser using the above example, do the following:
1. Go to the Custom Error Parser dialog and copy the name of the above parser
into the Parser Name field.
2. Copy the regex pattern into the Pattern field.
3. Fill in the appropriate group information.
4. Select OK in the dialog. The parser will then be listed as _ErrorInfoParser
MicrosoftJ++Java in the Project|Properties|Errors dialog.
5. Choose _ErrorInfoParser MicrosoftJ++Java from the drop-down lists under
the Error Parser combos.
6. Click OK in the Project|Properties|Errors dialog.

It is important to remember that syntax elements of strings that make up error

output for any compiler vary depending on the compiler being used. A unique
regular expression must usually be made for the output of each compiler.

Navigating Build and Rebuild Command

Output
The Build and Rebuild commands (on the Build menu) are treated differently from
the Compile and Debug commands when it comes to error output navigation. In all
cases the following occurs with error output in CodeWright:
n A list of errors displays in the Output tab of the Output Window.
n The error parser is applied to the error output file.

190 7- Projects, Project Spaces, and Workspaces

n The parser allows you to access an error by double-clicking on a line, or by using
the up and down arrow keys to highlight a line and hitting E. The
appropriate piece of source code then displays.
n You can right-click in the Output tab to give focus to a line and the file that
contains it. Then select Open Explorer with Directory from the popup menu to
launch Windows Explorer and automatically navigate to the directory
containing the file you selected.

The following differences occur with the output produced by Build and Rebuild as
opposed to the output produced by the Compile and Debug commands:
n A Build or Rebuild command just places the output in the Output Window, as
described above.
n A Compile or Debug Compile command automatically positions the cursor on
the correct line in the source file and places the error message text on the
CodeWright status line when the source is open.

This behavior can be configured to your own taste. A CodeWright API call
determines whether to show a list of errors, or whether to jump directly to the first
flagged file after a compile. These options are only available when using FTEE and
the Redirect Output command option to capture and use output. Examples follow.
Example: To cause the error list to be displayed after each compile, add this
line to the appropriate [Extension] section, or to the [Editor]
section, of your CWRIGHT.INI file:
ExecShowCompileErrors=TRUE
There is an analogous call for Build and Rebuild commands. To have
CodeWright jump to the first error after such a command, add this
line to the [Editor] section of CWRIGHT.INI:
ExecShowBuildErrors=FALSE
Note: For more information on ExecShowCompileErrors and
ExecShowBuildErrors, see the online help (Help|CodeWright API
Library).
More information on FTEE can be found in the chapter Set up a
Compiler. Information on the command options is available in this
chapter under the topic Command Options on the Tools Tab.

Traversing the Output

You can use Search|Find Next Error to go on to the next error in the Output
Window. Some keymaps have keystroke equivalents to these commands. There is

also a button available on the Build toolbar to go to the next error .

7- Projects, Project Spaces, and Workspaces 191

Listed below are some keystrokes in the CUA keymap that facilitate movement in
the Output Window.

CUA Keystrokes

Keystroke Action

SCZ Bring up the Output Window.

X Return to current document.

SCY Parse next error.

C [Home] Go to first line.

C [End] Go to last line.

CT Go to next tab stop.

SCT Go to previous tab stop.

Filters tab of Project Properties

The Filters tab of the Project|Properties dialog is used to specify how files should be

grouped and displayed when the button is selected in the Project tab of the
Project Window (the Project tab is described in the topic on Characteristics of the
Project Tab, in this chapter). The grouping is accomplished using wildcard characters
and filename extensions.

To access/edit the appropriate version of the Filters tab, complete the following:
1. Select Project|Properties.
2. In the Project Properties List:
n Select a project if the filters being viewed or modified are intended to be
specific to the selected project only, OR
n Select <Default Settings> if the filters being viewed or modified are
intended to be global.
3. Click on the Filters tab.

192 7- Projects, Project Spaces, and Workspaces

Project|Properties|Filters

The default file filters for project files are Source Files, Header Files, Web Files, XML
Files, Resources, and Other Files. Use the Filters dialog to add, remove or rearrange
filters in the list.

To add a new filter:

1. Give the new filter a Description and a Pattern, for example "Text Files" and
*.txt.
2. Click on Add. The new filter will be added to the top of the list.
Note: Be careful not to put all-encompassing filters, such as *.*, at the top of
the list. The filters sift through the files in the order that they appear
in the Project|Properties|Filters dialog. Any files filtered by the first
filter won't show up under subsequent filters. Therefore, if *.* is
listed as the first filter, none of the other filters will appear to work.

Project Setup Checklist

Now that you have created your project and you are familiar with the various tabs of
the Project|Properties dialog, it is a good idea to review the settings to make sure
they are appropriate for the project. A quick once-over will avoid surprises later.
There are several dialogs to revisit.
1. The Project|Properties|Directories dialog.
Check the Working Directory. Be sure to define a working directory for your
project. An explicit directory or %x (the path of the project file) are usually the
best choices. Remember that the items on the Directories tab are only available
if a project or the <Default Settings> item is chosen in the Project Properties
List.

7- Projects, Project Spaces, and Workspaces 193

2. The Project|Properties|Tools tab:
Check the Project Command Lines. Make sure the major project-wide command
lines you will be using (other than the command to compile the current file)
have been defined.
Example: Your Make command might be
${FTEE} nmake -f %y.MAK. (where %y indicates the path
and root of your project file)

If you already have a makefile, just name it explicitly instead

of using %y. If you will be using VDOS instead of FTEE to
watch the progress of the command, mark Use VDOS in the
command options, and omit FTEE from the command.
Remember that the items on the Tools tab are only available if a project or the
<Default Settings> item is chosen in the Project Properties List.
3. The Project|Properties|Tools-Compile category:
Select Compile from the drop-down list of tool categories under the Category
combo box on the Project|Properties|Tools tab. Select the appropriate
configuration (e.g. Debug) from the Settings For: field.
Compiler Command Lines: The compiler to use is first associated with the file
type extension and then associated with the project. Make sure the right
extension and project are selected. If you don't want the compiler to be
associated with a project, choose <Default Settings> from the Project
Properties List.

Using Project Spaces

Project spaces organize and house sets of projects. Once a project space is defined, its
primary uses include selecting or changing projects, and selecting or changing
project spaces. Refer to the next topics.

Selecting or Changing Projects

You can open or change a project in one of the following ways:
n Choose a project from the Set Current submenu of the Project menu. The Set
Current menu lists all the projects contained by the current project space. The
active project will have a checkmark next to it. You may select from this list to
reload any of the projects listed. Choosing a project in the Set Current menu is
the same as opening the project.

194 7- Projects, Project Spaces, and Workspaces

n Choose a project from the list at the bottom of the Project menu.
n Choose Project|Project Space|Open, choose the filter .PJT, and navigate the
directory structure for the project file. When you select the project file, a project
space is opened as well, even if the project was not previously associated with a
project space.

Selecting or Changing Project Spaces

You can select a project space by choosing Open from the Project|Project Space
submenu. Navigate your directory structure as you would when using the
File|Open dialog and select the project space (.PSP) file you wish to load.

Recently-selected project spaces will be listed at the bottom of the Project Space
submenu, numbered from one to nine. You may select from this list to reload any of
the project spaces listed.

Using Projects
Read on to find out about the following primary uses for a project that has been
defined in a project space:
n Loading Files for Editing.
n Creating, Selecting and Saving Workspaces.
n Searching Project Files.
n Selecting files for version control Checkin or Checkout.

Loading Files for Editing

One of the best things about projects is the convenience it provides when loading
files. Just choose Load Files from the Project menu to choose from a list of the files in
the current project.
n If you find that some files aren't listed, select the Members tab of
Project|Properties to add them (refer to the topic Adding Files to a Project).
n Select Open from the File menu to load files that are not part of the project. The
rules for extended selection list boxes apply to the Load Files dialog.
Alternately, you may wish to use the Project tab of the Project Window to operate on
files in a project. As with the Load Files dialog, you just select the desired files from
the list and press E to load the files. The Project tab has the advantage of
showing which files are actually on disk (some may currently be archived), and
whether they are read/write (see the topic Characteristics of the Project Tab). In
addition, you may organize the list based on a combination of filters (set on the
Project|Properties|Filters dialog), directories, File Sort Mode (set on the
Tools|Customize|Environment|File Sort Mode dialog), and version control status.

7- Projects, Project Spaces, and Workspaces 195

Creating, Selecting and Saving Workspaces
One of the most powerful aspects of projects is the workspace. At any time while
working on a project, you can select Save Workspace from the Project menu and
create a new workspace. Just give your workspace a name -- a descriptive name this
time, rather than just a file name -- and you are done.
Note: You must select a project from the Set Current submenu on the
Project menu before the workspace items on the Project menu will
be available for use.
A workspace name may contain any printable characters (including spaces), but no
apostrophe ( ' ), backslash ( \ ), quote ( " ), or square brackets ( [ ] ).

Creating a New Workspace

Suppose that you have a number of files open, and want to create a new workspace
that doesn't include any of the files currently open:
1. Select the project to which the workspace should be saved using the Set
Current submenu on the Project menu, and then select Load Workspace. The
Select Workspace to Load dialog displays.

Select Workspace to Load

2. You will see a workspace that is always available called <none>. Select that
workspace to wipe the slate clean.
3. Set the Close Windows/Delete Documents option to All to close all your buffers
and windows and start afresh, and click OK. Of course, if any of the buffers
contain changes that have not been saved to disk you will be given an
opportunity to do so.

Now that you have your clean slate, open the files that you want to have open in
your workspace. At any point, you can save your workspace under whatever
descriptive name you wish, by clicking Save Workspace on the Project menu.

Remember that workspaces are specific to the projects in which they are created.

196 7- Projects, Project Spaces, and Workspaces

Automatic Saving
Selecting Save Workspace from the Project menu is usually only necessary when
creating a new workspace. CodeWright automatically updates the active workspace
whenever you close or change projects, exit CodeWright, or (optionally) when you
change workspaces.

Loading an Existing Workspace

Once you have created more than one workspace, you will find it easy to switch
between them. Select Project | Load Workspace. You will notice a couple of options
are available, as described below.

Update Current Workspace

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

Close Windows/Delete Buffers

Choose one of the following options when closing a workspace, with respect to
the next workspace. Keep in mind that the saving of windows and buffers in
the workspace you are leaving is unaffected by your selection.
n Choose None to close all windows and buffers after leaving one workspace
and before the next is loaded. In this event, no buffers or windows are
carried over from one workspace to the next.
n Choose Current Workspace Components Only to close only the files that
are members of the workspace. This means that any files you opened
during the session, such as a special header file, will carry over to the next
workspace.
n Choose All to have all files carry over into the next workspace. If you do
this, we recommend that you either delete the carry-over buffers before
saving the workspace, or save the workspace under a new name.
Otherwise, workspaces will become less distinct, and therefore less useful,
entities.

Searching Project Space and Project Files

You can search the entire group of files that are members of the current project space
or project, or you can select a subset of the member projects or files on which to
perform a search. This feature is available in the Search and Replace Multiple
Sources dialog and is described in detail in the Chapter on Search and Replace and
Navigational Tools.

7- Projects, Project Spaces, and Workspaces 197

Selecting files for Check-in or Check-out
The CodeWright version control interface (Checkin, Checkout and related
commands) can operate independently of, or in conjunction with Projects. The
Tools|Version Control|Maintenance dialog allows you to select from files in the
project or the current directory.

Project Files
A project file (.PJT) is essentially a configuration file and state file all in one.
Workspaces are stored as additional "state files" within the project file. Once you
understand the format of a CodeWright configuration file, you understand a
CodeWright project file. These files look just like standard Windows .INI files with
headings enclosed in square brackets, and statements on lines following these
headings. Statements take the form of <keyword>=<value>.

The primary difference between a CodeWright configuration or project file and a

Windows .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. This is possible because CodeWright processes these files directly, without
going though Windows. For more information on the format of configuration and
related files, refer to the topic Configuration and State in the chapter on Configuration
Files & Command Line Parameters of this manual.

Configuration and State Hierarchy

When you have no projects in use, CodeWright stores its configuration information
in its configuration file (CWRIGHT.INI). Between sessions, CodeWright stores the
more transient information about the files you are working on in its state file. When
you are using a project, however, some configuration information is kept in the
project file, and state information for Windows, Documents and Marks is stored in
either the project (.pjt) or project space (.psp) file. The state file then serves largely to
identify which project file you were using last.

You determine the amount of configuration information kept in the project file by
selecting either the <Default Settings> item or a project from the Project Properties
List, and then setting options in the various tabs of the Project|Properties dialog.
Various CodeWright dialogs also have options for specifying that dialog settings be
stored with the project. Additionally, the Directories tab in the Project|Properties
dialog has an option to Store System Options in project file. See the topic Storing
Configuration Settings with a Project.

198 7- Projects, Project Spaces, and Workspaces

Choosing to set configurations as either <Default Settings> or project-specific
settings gives you the option of storing as much or as little information with projects
as you like, and allows each project to have its own, unique configurations. These
configurations change as projects change. Also, storing more information in the
project file means storing less information in the Configuration file, thereby
minimizing the time it takes to load CodeWright.

If you are using one or more workspaces within your project, document and
window state information is stored with the active workspace section of the project/
project space file when you exit, rather than in the state section of the project. For
more information about the main configuration files in CodeWright, see the chapter
on Configuration Files & Command Line Parameters.

7- Projects, Project Spaces, and Workspaces 199

200 7- Projects, Project Spaces, and Workspaces
8- Set up a Compiler
CodeWright allows you to execute your compiles, assemblies, builds, etc. from
within the editor. With proper configuration, the results of the operation will be
placed in the Output tab on the Output Window. Double-click on the errors and
warnings listed in the Output Window to bring up the source file with the cursor
positioned at the line in which the error occurs.

All compiler configurations are done through the Project|Properties dialog. You do
not have to use CodeWright projects in order to set up any compilers. However, if
you do plan on creating and using projects, it is best to set up some default
configurations (including compiler configurations) prior to creating the projects so
that CodeWright will use them as defaults when additional projects are created. See
the previous chapter on Projects, Project Spaces, and Workspaces for more information
on CodeWright projects and setting project defaults.

Categories of Command Line Tools

As we have learned, CodeWright offers access to four kinds of command line tools in
the Project|Properties|Tools dialog.
n The Compile command tools are tied to the filename extension as well as the
project and act on the current open buffer. These commands are discussed in
the next section.
n The Build command tools are not tied to the filename extension and an open
buffer is not required. They send their output to an error file. After they run,
CodeWright analyzes the error file to determine the location of errors that your
compiler or linker has found.
n The Custom tools are run in whatever way you specify, and error parsers are
not involved.
n The VCS tools are also run in any way specified, without involving error
parsers.

8- Set up a Compiler 201

Compiler Definition
The command lines for a compiler definition are set up on the
Project|Properties|Tools dialog under the Compile category of tools. To choose the
Compile category, select it from the drop-down list under the Category combo.

In the Settings For: field, select the Debug configuration, Release configuration, a
custom configuration, or All Configurations, then complete the remainder of the
dialog for that configuration. This allows you to save a group of settings under the
selected configuration name. To use the configuration in executing Compile
commands, select it on the Build|Configurations dialog, and press Set Active.

Compiler commands are defined for the selected file type. Please ensure that you
also have the desired file type(s) selected from the list of file types before modifying
settings.

Project Properties Tools - Compile

The default compiler for the extension you selected is displayed in the Name box:
n If the box is empty, or the wrong compiler is displayed, select the down arrow to
the right of the box to display the list of other compiler names.

n If the compiler you seek is not listed, press the New button , type in a
descriptive string for it, and enter an appropriate command.
n If the list is cluttered with compilers that you will never use, you can delete

those you don’t want (highlight the compiler and press ).

202 8- Set up a Compiler

Response File Contents
The Response File Contents edit box in the Compile category of tools is used for
commands that may be too long or that may be better used in a batch file. It only
comes into play if the %Q macro is being used on one or both of the compile
command lines. See the topic Response File in the chapter Projects, Project Spaces and
Workspaces for more information.

Compiler Command Line

A good starting point for the compiler Command field on the Tools tab is to enter
whatever would be typed at a DOS prompt for launching a compile.

Use the Macro Assistant to add filename component macros to expand the name of
the current CodeWright edit buffer. Use the macros, as desired, within and at the
end of the command.
If you want to set up a custom configuration that has a Debug compile Command
line and a Release compile Command line, you must do the following:
1. Temporarily select the Debug configuration in the Settings For: field.
2. Select the compiler definition in the Name field that you will also use for your
custom configuration.
Note: You may want to create a new compiler definition for your
custom configuration, since the compile and debug compile
settings for a given definition are shared by all extensions and
configurations with which it is associated.
3. Save the Debug configuration.
Once you have completed the custom configuration and saved it, you will likely
want to go back to the Debug configuration and change the compiler definition back
to what you had before.
Example: If you use Microsoft’s Visual C++, a good general-purpose
Compile command might be:
${FTEE} cl -DSTRICT -c -W3 -G3 -D_X86_=1 -DWIN32
%r%e
n The ${FTEE} is a command macro which calls the CodeWright
FTEE.EXE program to capture the output of the compile. Refer to
the topic FTEE, later in this chapter.
n The %r and %e are Filename Component Macros that expand to
the current file and extension. Refer to the listing of Filename
Component Macros in the previous chapter on Projects, Project
Spaces, and Workspaces.
n The remainder of the above example is specific to each compiler.

8- Set up a Compiler 203

Special Considerations
If you organize your files in a unique directory structure, there are some special
considerations for the compiler to find the files needed.

As discussed in the topic Working Directory in the chapter Projects, Project Spaces, and
Workspaces, CodeWright will shell out to DOS in the directory you have specified in
Project|Properties|Directories to execute your commands. If you have designed a
directory structure where your files are not all in the same directory, problems can
arise.
Example: You might have a root application directory containing .exe's, a
subdirectory containing object code, another subdirectory
containing headers and include files, and another subdirectory
containing your source files. Making the Compiler aware of where
the necessary files for compiling are becomes tricky.
One solution would be to use a Make ‘Description’ file instead of the
standard Compile line. To compile a specified target you might use
the following command:
nmake -f MYPROJ.MAK %r.OBJ
This is basically a Compile, with the details supplied by the
Description file rather than the command line or the environment.

Modifying the Command Line

Environment
When setting up compilers in CodeWright it is usually necessary to set up custom
environments, so that the operating system knows how to run the external
command or utility. For example, it may be necessary to set the utility's directory
using the PATH environment variable. These custom environments may include (or
cause) the need for additional environment space. There are several ways in which
to expand environment space. For the Windows 98 environment:
n Create more environment space by modifying the CONFIG.SYS file and
adding:
SHELL=C:\WINDOWS\COMMAND.COM /E:4096
n From the DOS command line, enter the following as the first thing on the line,
prior to the compile or make command:
C:\WINDOWS\COMMAND.COM /E:4096 /C
n You could also complete the following steps:
1. On your ‘Start’ bar, click Start|Run.

2. On the Open: line, type command.com, and press E.

204 8- Set up a Compiler

 3. Click on the Properties button and select the Memory tab.
4. Select a larger Initial environment size, and click OK to close the DOS
window.

Displaying Output in CodeWright

(FTEE and VDOS)
Most of the utilities that CodeWright project tools will run will generate some sort of
output. In most cases it will be necessary to use the output from within CodeWright
(e.g. to access the errors generated by a compiler). There are two methods available
for capturing and displaying output within CodeWright: FTEE and VDOS.

FTEE
If you want the output of your command to display in the DOS window while it is
being redirected to the error output file, you can use our FTEE command:
Example: ${FTEE} nmake -f %y.MAK
The ${FTEE} command macro calls the appropriate version of FTEE, a program that
is located in the CodeWright directory. In the above example, the output of nmake
will be split so that it goes to both the output file and the screen.

The FTEE32 utility is supplied along with CodeWright. The ${FTEE} macro expands
the name and path of the FTEE utility. FTEE 'splits' generated output so that it can
be placed in the error file as well as in the running DOS window. Just place the
${FTEE} command at the beginning of the command lines using the Redirect
output option. Since FTEE32 executes a command by creating a separate process for
the command and capturing its output, it will only work for executable commands.
If your CodeWright directory is not on the path, ensure the file FTEE.EXE is in a
directory that is.

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

Before using FTEE, make sure that your application does not do any redirection on
its own. Nothing useful can result from both your program and FTEE trying to
redirect the same output.
Note: If you are calling a Windows executable, such as Borlandâ C++
Builderâ, do not try to redirect output with FTEE. The program will
be treated as a DOS application if you do.

8- Set up a Compiler 205

Use VDOS
VDOS is a command shell that runs in a DOS window. Its output is automatically
captured. When Use VDOS is checked for any of the tools in Project|Properties|
Tools, VDOS will intercept output from Compile, Build, Rebuild and other project
commands, and put it in the Output tab of the Output Window. Because it runs in
the background, you can continue editing while your compile is executing.

Sending output to the Output tab is convenient for seeing the output as a process is
executed, for cutting and pasting from the output, and for re-executing commands.
If you are prompted for input, however, you must press Cc to access the
console application for data input.
Note: Although you will not see anything in the console window, this is
where your application is expecting input to come from.

Project|Properties|Tools

Remove references to other redirectors from your command lines when you use
VDOS. Programs such as FTEE are not compatible with VDOS. Checking the No
Command Shell box in Project| Properties|Tools for any of the project tools will
disable the use of VDOS or FTEE for that command. For troubleshooting
information, refer to the topic VDOS Shell Window (indexed under VDOS) in the
online help.

206 8- Set up a Compiler

Version Control Commands
We have learned from the previous and current chapters on projects and setting up
compilers that in order to use various utilities in CodeWright, they need to be
configured in the Project|Properties|Tools dialog. One of the tool categories in the
dialog is for version control commands. The version control tools are one of the
methods used for integrating version control in CodeWright. There are two ways to
use version control systems with CodeWright, but only one method can be used at a
time. The methods are:
n To set up the tools with the appropriate command line version control utilities in
Project|Properties|Tools under the VCS category.
n To use the SCC API (Source Code Control Application Programming Interface).

No matter which version control integration method is used, it is important to

remember that CodeWright does not come with its own version control, but is
configured to use external version control programs. To understand how to use
version control in CodeWright, read the following chapter on Version Control.

8- Set up a Compiler 207

208 8- Set up a Compiler
9- Version Control
CodeWright does not come with its own version control system but it can be
configured to integrate with an existing version control system. Once version control
integration has been set up, there are a number of features in CodeWright that make
performing version control operations easier.

This chapter is composed of three main topics. Using Version Control in CodeWright
deals with the user interface for version control (i.e. menu items, windows, and
popup menus, etc.). The next two topics, Using a Command Line Version Control
Provider and CodeWright SCC Integration with Version Control Systems, describe two
alternative methods for CodeWright-version control integration.

Using Version Control in CodeWright

The items discussed in this section deal specifically with the CodeWright user-
interface for version control (i.e. menu items, windows, and popup menus, etc.). The
information is based on the assumption that an existing version control system has
been successfully integrated with CodeWright using one of the two methods
described in the two ensuing topics on CodeWright-version control integration.
Which integration method to use depends on the type of version control system
available.

Version Control Menu

Most version control operations in CodeWright can be carried out on the document
you are editing from the Tools|Version Control submenu. The following capabilities
are available from this menu:
n Perform standard put, get, get-with-lock, lock, and unlock commands.
n See the properties and histories of any files under version control using the
Properties and History items.
n Add or remove the current file from the version control project by clicking on
Add or Remove.
n Access the Version Control Manager for the version control provider using the
Manager item.

9- Version Control 209

Source Code Revision Control - Maintenance
While most of the items on the Version Control submenu are self-explanatory, an
item that requires deeper explanation is “Maintenance…” which accesses the Source
Code Revision Control Maintenance dialog. The Source Code Revision Control
Maintenance dialog is a multi-purpose dialog that works for either the command
line integration or the SCC Provider integration.
3 You can also access this dialog from the Project tab of the Project Window by
right-clicking on a file and selecting Version Control|Maintenance from the
popup menu.

Source Code Revision Control Maintenance

The Maintenance dialog is useful for:

n Applying labels to revisions.
n Locking and unlocking revisions without checking them in or out.
n Reviewing the revision history and properties of an archive.
n Performing other version control tasks.
Some of these services, such as history and properties, are very specific to the
version control system or SCC provider you are using.
Note: Any file opened in CodeWright that you wish to perform version
control operations on must already be part of a version control
project. In the case of the SCC interface, it must be a part of the
version control project that you have opened under Tools|Version
Control|Setup. The file does not have to be part of a CodeWright
project, although there are advantages to using CodeWright projects
in conjunction with existing version control projects.

210 9- Version Control

Version Control and CodeWright Projects
Refer to this section to:
n Associate Version Control projects with CodeWright projects.
n Add version control project filenames to your CodeWright project.
n Add CodeWright project files to an SCC Provider Project.

Associate Version Control Projects with CodeWright Projects

It is possible to associate version control projects with CodeWright projects when
using SCC API version control integration (see the topic CodeWright SCC Integration
with Version Control Systems). Doing so offers the following advantages:
n When a CodeWright project is opened, the associated version control project is
also automatically opened, thus making version control facilities readily
available to be used from within CodeWright. Checkin and Checkout (among
other version control commands) are immediately available, allowing for quick
preparation of files for editing.
n Closing the CodeWright project automatically closes the associated version
control project.
n Files in the associated version control project can be “read” into the CodeWright
project, providing a more convenient way to add appropriate files to the
CodeWright project.

A version control project can be associated with a CodeWright project from one of
two different dialogs: the Tools|Version Control|Setup dialog or the
Project|Properties|Members dialog. To associate the two projects in the
Tools|Version Control|Setup dialog, do the following:
1. Create a new project space with at least one member project (or open an
existing one). For information about how to do this, see the chapter on Projects,
Project Spaces, and Workspaces.
2. Set a current CodeWright project using the Set Current menu item on the
Project menu.
3. Go to Tools|Version Control|Setup.
4. Choose the SCC Provider radio button.
5. Assuming that the version control provider has already been initialized, click
Open Project.
6. Choose the version control project that you want to associate with the current
CodeWright project.

9- Version Control 211

7. Verify that the working directory listed is that of the version control project, not
the CodeWright project (or any other) directory. If the directory is not the one
that was specified for the version control project, make it so by browsing for, or
typing in, the correct directory name.
8. Click OK, and then OK again.

To associate the two projects in the Project|Properties|Members dialog, do the

following:
1. Assuming that a project space has been created with at least one member
project, go to the Project|Properties|Members dialog.
2. Highlight the CodeWright project that you want to associate with the version
control project.
3. In the VCS Project group, click the Setup button (the group will not be available
if a version control provider has not been installed and initialized).
4. Choose the version control project that you want to associate.
5. Verify that the working directory listed is that of the version control project, not
the CodeWright project (or any other) directory. If the directory is not the one
that was specified for the version control project, make it so by browsing for, or
typing in, the correct directory name.
6. Click OK and OK again.

Add Version Control Project Files to a CodeWright Project

Filenames that make up version control projects can easily be added to CodeWright
projects when using the SCC service provider version control integration.

To add version control files to a CodeWright project, use the VCS Project Read
feature. This feature will read or scan a version control project or configuration file
for files, in order to incorporate those files into a CodeWright project. The version
control “Read” feature can be found in the Project |Properties|Members dialog.

Address the following items that have to do with CodeWright’s version control
“Read” feature:
n VCS Project: - Lists the name of the current version control project.

n Setup button – Allows you to associate an SCC Project, or change the

association. Complete the dialog that displays.

n Read button – Allows you to populate the project files listbox.

212 9- Version Control

Project|Properties|Members

Having CodeWright automatically read the filenames of a version control project

into a CodeWright project saves the time needed to manually add files, one by one,
to a CodeWright project.

Add CodeWright Project Files to an SCC Provider Project

The Project|Properties|Members dialog also has a feature for adding filenames
from a CodeWright project file to an SCC Provider Project:
1. Make an SCC Project association using the Setup button (as described in the
preceding topic Associate Version Control Projects with CodeWright Projects).
2. Verify that a checkbox at the bottom of the tab becomes enabled, which will Add
Project Files to VCS Project.
3. Click OK to close the Project|Properties dialog; each CodeWright project file
will be added to the SCC Provider Project. A prompt will most likely come up
asking for optional comments for the files to be newly checked in to version
control.
CodeWright projects make version control more visual in CodeWright. When files
are a part of a CodeWright project they will be displayed in the Project tab of the
Project Window. The icons that represent files are displayed differently depending
on their status:

n When the files are checked-in (or read-only) the icons that represent the
files will be gray with horizontal lines in them.

n When the files are checked out CodeWright conveniently places a red
checkmark to the upper right of the file icons.

n If another user has a lock on a file that is part of the project being worked
on, CodeWright represents the file with a gray checkmark in the Project tab.

9- Version Control 213

n Some Version Control projects are set to delete work files when they are
checked in. CodeWright represents files not found at the specified location
(usually archived) with an exclamation point.

n If the file currently being edited (as it is stored on disk) differs from the
latest revision in version control, CodeWright will display the file’s
representative icon in a pale yellow color, indicating that it is an old version.
Notes: To perform version control operations on the file(s) selected in the
Project Window, access the right-click menu from the Project or
StarTeam tab. When using the Project Window to carry out version
control operations or view version control status, it is a good idea to
press the Refresh button from time to time to see the most current
status of the files.
To access version control operations for the document you are editing
instead, use the Tools|Version Control submenu or VCS toolbar, or
right-click within the document.

Current Project Tree List

CodeWright projects make the Current Project tree list in the Source Code Revision
Control- Maintenance dialog available. The Current Project tree list displays the
files in the current CodeWright project and allows the dialog’s version control
operations to be performed on one or more of those files. It eliminates the confusion
of having to sort through unnecessary and unrelated files that may not be part of the
project.

Project Tree List

214 9- Version Control

VCS and the User-Defined Popup Menu
CodeWright features a variety of customizable popup menus. You may already be
familiar with one of these: the menu that appears when you click the right mouse
button in an edit document. The right-mouse-click popup menu is context-sensitive.
That is, it changes depending on where the pointer is when the mouse is being
clicked. The popup menu discussed in the following paragraphs comes up when
the right-mouse button is clicked while the pointer is in the current document with
nothing highlighted.
Note: Version control functionality for the current document can also be
accessed from the Tools|Version Control submenu or the VCS
Toolbar.

Modifying the Standard Popup: A Simple Example

The right mouse popup menu can be changed using the CodeWright popup menu
editor. The popup menu editor modifies menu description files that contain
functions that form CodeWright popup menus. The main menu description file for
CodeWright is called CWRIGHT.MNU. The Edit this menu option available on most
standard popup menus will access the popup menu editor. More information about
the popup menu editor is available in the chapter on Custom Interface.

The main popup menu already contains two commonly used VCS commands:
checkin and checkout. The checkout command in the menu uses the Check Out w/
Lock command, as defined in the Version Control Setup dialog (Tools|Customize|
Version Control|General). Here is how to add an item in the popup menu to
perform a non-locking checkout.
1. Right-click in an un-highlighted, non-HTML document to access the popup
menu, then click Edit this menu.
2. Using the existing Check out line as a frame of reference, make a new menu
item by first highlighting the Check out line and then clicking Insert|Menu
Item.
3. In the Menu Item dialog, type Check out--no lock in the Menu Item Text field.
4. In the Execute Function field type
MenuCommand IDM_TOOLS_VCS_GET.
5. You can choose to have your new menu item inserted before the Checkout line
by checking Insert Before.
6. Click OK, and then save the changes in the popup menu editor by clicking
File|Save.
7. Click OK to close the dialog.

The right-mouse button popup menu should now contain three VCS commands.
Note: The preceding example works with command line or SCC VCS
integration.

9- Version Control 215

Making Your Own Version Control Popup Menu
A custom popup menu can be made in CodeWright with the popup menu editor.
Use the default menu description file for CodeWright to store the new menu, or
make a new one.
Example: To create a popup menu entitled “PVCS”, click File|New Menu in
the popup menu editor, then type the name PVCS in the New
Menu dialog. This will add a [PVCS] section to the CodeWright
menu file, CWRIGHT.MNU.
The command to show a menu defined in CWRIGHT.MNU is DlgMenuPopup. Its
syntax is described in the online help. This command may be assigned to a
keystroke, a button, another menu item, or a mouse click.
Example: If you use the Key Bindings dialog to assign <shift-
mouse_right_click> to DlgMenuPopup=“[Pvcs]”, you can
call up your custom command menu by holding down the S
key and clicking the right mouse button.

Using Multiple Configuration/Project Files

(DOS VCS Utilities Only)
PVCS and many other version control systems use configuration/project files that
maintain workfile and archive locations and other version control configuration
information. When using DOS version control utilities, it is sometimes desirable to
use more than one version control configuration/project file at a time. It may also be
necessary to select the configuration/project file at the time a file is checked in or out.
For example, one of your work files may be used in multiple projects.

The following examples give an idea of how multiple version control configuration/
project files can be used.
Examples: Suppose you need access to two separate checkin commands
without changing projects. You can set up each command with its
own keystroke, button, or menu item.
1. The first thing to do is to create a section in your CWRIGHT.INI
file for each checkin command. Here is a sample pair:

[VCSCheckIn1]
CheckInSetCmd=’put -cvcs1.cfg -M%Q %r%e’
CheckInBuffer
[VCSCheckIn2]
CheckInSetCmd=’put -cvcs2.cfg -M%Q %r%e’
CheckInBuffer

The CodeWright command ConfigFileRead can be used to

execute the CodeWright commands contained in these sections.

216 9- Version Control

 2. To bind the first checkin command to a button or menu item,
use this function:
ConfigFileRead=’’,VCSCheckIn1
3. For the second checkin command, use:
ConfigFileRead=’’,VCSCheckIn2

If you’re binding to a keystroke, use double quotes instead of

the single quotes shown above.

The same method works for checkout commands. Sample

CWRIGHT.INI file entries for checkout commands, with and
without locks are displayed next:

[VCSCheckOut1]
CheckOutSetCmd=0,’get -cvcs1.cfg %r%e’
CheckOutBuffer=0
[VCSCheckOutLock1]
CheckOutSetCmd=1,’get -cvcs1.cfg -l %r%e’
CheckOutBuffer=1
[VCSCheckOut2]
CheckOutSetCmd=0,’get -cvcs2.cfg %r%e’
CheckOutBuffer=0
[VCSCheckOutLock2]
CheckOutSetCmd=1,’get -cvcs2.cfg -l %r%e’
CheckOutBuffer=1

Version Control Integration

Configuration
CodeWright can work with version control software either through command line
integration or the SCC Application Programming Interface (API). The command line
integration works specifically with DOS command line utilities that perform version
control operations (i.e. PVCS GET.EXE and PUT.EXE, or MS SS.EXE). The SCC API is
for integrating GUI version control systems with the CodeWright GUI.

The version control capabilities that CodeWright provides will vary depending on
which integration method is used and which Version Control Provider is used. The
integration method is specified by selecting either the Command Line Provider, or
the SCC Service Provider option in the CodeWright Tools|Version Control|Setup
dialog. Descriptions of the two integration methods follow. It is only necessary to
use one integration method in order to access version control from within
CodeWright. Choose the method that applies to the type of version control system
you have (SCC for GUI, or Command Line for DOS).

9- Version Control 217

Using a Command Line Version Control
Provider
CodeWright is capable of supporting any version control system that can be run
from a DOS command line. It comes with predefined commands for several version
control systems, including Merant PVCS, and various versions of the RCS utility,
ported from UNIX.

CodeWright integrates with command line version control utilities by shelling to

DOS to run the utility and then returning to CodeWright once the deed is done.
There are ways to cause the operation to be performed on the file that is currently
open in CodeWright. It is also possible to have the operation performed on multiple
files at once.

In order to use the command-line Version Control Interface, the Source Code
Control System must be properly installed according to the instructions provided by
the Version Control Vendor.
3 The following information is based on the assumption that command-line
version control operations can be successfully performed from any directory in
DOS according to the instructions provided by the Version Control Vendor.

To set up the version control command lines, complete the following steps:
1. Select the CodeWright Tools menu.
2. Find the Version Control submenu.
3. Select the Setup item.
4. Make sure that the Command Line Provider radio button is selected.
5. Choose a command set from the list. You are now ready to use the commands
on the Tools|Version Control menu.

Adding a New Command Line Provider

If you do not see your provider listed in the Command Line Provider section of the
Version Control|Setup dialog, you will need to create your own command lines. If
you know that one of the command sets listed is similar to yours, you may want to
select that one, and use its commands as a starting point for your own. To start from
scratch, select Other from the list and set up your own commands. If you don’t see
Other in the list, you can add it by adding Other to the line that looks like:

_StateHistory=XVCS,RCS,TLIB,PVCS,SourceSafe

in the [Editor] section of the CodeWright configuration file, CWRIGHT.INI. The

CWRIGHT.INI file can be found in the CodeWright home directory.

218 9- Version Control

Customizing Version Control Commands
Whether you use existing version control command lines in CodeWright or make
your own, you will need to pay a visit to the Project|Properties dialog if you want to
define or modify them. Complete the following steps:
1. In the Tools|Version Control|Setup dialog, choose the Configure button. The
Project |Properties|Tools dialog will be activated.
2. Select the entry VCS in the Category field.

Project|Properties|Tools

3. Select the entry labeled External VCS Check In in the Description field.
4. View the command sequence displayed in the Command edit control. This is
the command that will be executed whenever you select Check In from any of
the various menus and toolbars that provide the Check In item. The command
includes CodeWright filename component macros.

5. To see exactly how the command will run, select the Test button . Note that,
when you have a dummy file such as FOO.C opened in CodeWright, the
macros resolve and the command is displayed for operation on the current
document, FOO.C.

A description of some of the default commands listed in Project|Properties|Tools

for version control are explained below.

Default Command-Line Version Control Commands

The examples contained in this section use PVCS version control commands, but the
concepts apply to any command-line version control provider.

9- Version Control 219

 Check-in Command
The Check-in command is the command line needed to check a file into your
version control system or archive. If possible, this command should work
whether or not an archive currently exists for the workfile.
n If the check-in command is empty the following command will be used:
Put %b%e
n The initial check-in command defined in your CWRIGHT.INI file is as
follows:
Put –t@%Q –m@%Q %b%e
The @ sign precedes the name of a message file that contains the
change description you want to use. This can be any text file up to 64K
in size.
%Q is a CodeWright filename component macro that expands out the
name of a temporary response file containing the text from the
Comment String (check-in) or Additional Options (check-out) edit
box. This macro is case sensitive; you must use an upper case Q.
%b is a CodeWright filename component macro that expands out the
complete workfile name, less the extension.
%e is a CodeWright filename component macro that expands out the
extension of the workfile. This component begins with a dot ( . ) unless
the extension is null.
The additional flags and %Q macro enable you to supply a description
of the changes or of the archive itself, when creating a new archive, to
the check-in command. This is done through prompting, or through
the Comment String edit box in the Check-in dialog. The text is placed
in a temporary response file.
n If you want to supply all parameters to the command, including filenames,
from within the temporary response file the %Q macro creates, use the
form:
Put @%Q

Check-out Command
The Checkout command is the command line to execute when you are checking
out a revision from a version control system or other archive. If your version
control system offers revision locking, this command should not lock the
revision. This is the command to be used when you are browsing or compiling
the file, rather than planning to change it.
n If you don’t define a command for check-out, the following command will
be used:
Get %b%e

220 9- Version Control

 n If you wish to be prompted for additional options, or to supply them
through the Additional Options edit box in the Check-out dialog, use a
command like the one below:
Get @%Q %b%e
n Use the Checkout with locking command to check out a revision for the
purpose of changing it. If your version control system does not offer
revision locking, you may either make this command the same as the
Checkout command or leave it blank.
If you don’t define a command for Checkout with locking, the following
command will be used:
Get –l %b%e
n If you want check-out with locking, and wish to be prompted for additional
options (or to supply them through the Additional Options edit box in the
Check-out dialog) use a command like the one below:
Get –l @Q %b%e

Lock Command
The lock command is the command that your version control system uses to
lock a revision without checking it out. This is useful when you already have a
modified version of the source file that you want to check in, but you discover
that the file was not locked.

Review each of the External VCS commands on the Project|Properties|Tools dialog.

Note the commands as provided are designed to minimize response required from
the user during command execution. Revise the commands as necessary to
accommodate your company’s source code control operation standards.
Note: Predefined command lines are provided for several version control
vendors. You select between these in the Tools|Version
Control|Setup dialog.
At this point you should be completely set and ready to use DOS version control
utilities in CodeWright. However, if any of the above steps didn’t go as planned, the
following explanations and tips may be of assistance.

Additional Tips
Refer to the following tips regarding command line Version Control integration:
n The version control command runs in a DOS shell. Once the command is
executed, the shell exits and any output that would normally be displayed in
DOS is lost. In order to see the output, mark Use VDOS for each of the Version
Control commands on the Project|Properties|Tools dialog. The output will
then be displayed in the Output tab of the CodeWright Output Window.

9- Version Control 221

n One of the most commonly reported errors is “Bad Command or Filename.”
Placing your version control provider in your path should eliminate this error.
n The command line provider names displayed in the Version Control Setup
dialog are read from the following line in your CodeWright configuration file,
CWRIGHT.INI. This line is typically placed in the [Editor] section in
CWRIGHT.INI:
StateHistory=XVCS,RCS,TLIB,PVCS,SourceSafe
XVCS is the name of the list internal to CodeWright. This key is required. The
names in the list follow the XVCS keyword on the line. Add to or edit this line
as appropriate.

CodeWright SCC Integration with Version

Control Systems
CodeWright provides a configurable interface for use with your Source Code
Control System. CodeWright does not come with a source code control system of its
own. You must have a working source code control system to successfully use the
interface.

All of the CodeWright SCC Provider support is based on the Microsoft Common
Source Code Control (SCC) Specification. This spec describes a dozen or so entry-
points that cover various version control operations (checkin, checkout, etc). For
SCC Providers to comply, they must provide an SCC Server DLL that contains these
entry-points. When this SCC Server DLL is properly installed and configured, IDEs
such as CodeWright can hook up their dialog boxes to these entry-points and get
more or less the same functionality, independent of SCC Provider.

To find out whether a particular Version Control Provider offers Common Source
Code Control (SCC) Integration, check with the vendor.

Version Control for Use with a Source Code Provider DLL

Make sure you have a properly installed Source Code Control System on your
computer. Then complete the following steps to configure your SCC Provider:
1. Select SCC Service Provider in Tools|Customize|Version Control|General.

222 9- Version Control

 Version Control Setup

2. Select your version control system from the list in the dialog.
Note: If StarTeam is installed on your system, and you have obtained
the StarTeam SCC Integration from the Borland website (via a
link in your current version of StarTeam), select CodeWright
StarTeam Integration to enable a StarTeam tab on the
CodeWright Project Window. The StarTeam tab provides a
browse window for your StarTeam projects, displaying
information from the StarTeam Change Request, Task and File
tabs, and provides version control functionality on a right-click
menu.
3. Press the Initialize Provider button in the Version Control Setup dialog.
4. Press the Open Project button in the Version Control Setup dialog.
5. Select the version control project you wish to use (the project should already
exist in your version control system).

At this point you should be completely set and ready to perform check-ins, check-
outs, and other version control operations from within CodeWright. If any of the
above steps didn't go as planned, however, read the following paragraphs.

Location of the SCC Provider DLLs

System information for SCC Version Control integration (the name and path of
installed source code control systems accessible to your computer) is placed in the
Registration Database.

9- Version Control 223

If the Registry entries have not been made, or have been made incorrectly, it will not
be possible to initialize the Version Control Provider in the CodeWright
Tools|Customize|Version Control|General dialog. The most common message that
comes up when the initialization fails is System or Project Initialization Failed. If this
message occurs, there are a couple of courses of action:
n Make sure all version control integration modules provided by the version
control vendor are properly installed. Many of the integration modules are not
installed with regular installations of the version control system, and some
integration modules don’t even come on the same CD. The version control
vendor should provide the necessary information for where to get version
control integration modules and how to install them.
n If the necessary version control integration components have been properly
installed, but CodeWright integration initialization still fails, it may be necessary
to check the registration information for the integration modules in the
Registration Database. Examples of some typical registry entries for version
control integration can be found in the CodeWright online help, under the topic
Troubleshooting Version Control SCC API Registry Settings. Compare these entries
with similar entries in your Registration Database, and then verify that the
paths to the various indicated DLLs or other modules are correct, and that the
DLLs or modules do exist.
Note: The source code control vendor should make the appropriate system
entries for SCC integration during the installation of the version
control system. If the Source Code Control System is installed on a
network server, it is possible that the proper entries will not have
been placed in the Registration Database of client machines.
Sometimes VCS vendors provide network setup options in
anticipation of such situations.

224 9- Version Control

10- Synchronization
CodeWright has made a ground breaking effort to "synchronize" with alternate
development environments. We now synchronize with the following environments:
n Borlandâ C++ Builderâ (V5.0 and V6.0)
n Borlandâ Delphiä (V6.0 and V7.0)
n Microsoftâ Visual Studioâ (V5.x, V6.x and .NET)
n Microsoft Visual Basicâ (V6.0)
n Texas Instrumentsâ Code Composer Studioâ (V1.0 and V1.1)

CodeWright's Sync Technology allows the stand-alone editor to be used along with
development environments without concern for extra loading and reloading, or
losing features or edits. Editing can be done in both environments with changes
instantly updated in the alternate environment. In addition, keystrokes are available
that will access menu commands in the alternate environment.

Initial CodeWright Setup

To use synchronization for any of the development environments listed above, the
respective synchronization modules must have been chosen during the initial
CodeWright installation. If the development environments for synchronization were
not chosen at that time, it will be necessary to do a custom CodeWright installation
in order to install them.

Once the necessary sync modules have been installed, there are some setup
procedures to follow for each individual development environment. The sections
that follow provide that setup information.

10- Synchronization 225

The CodeWright Synchronization Wizard, and
Loading CWSync.DLL
There are two procedures that can always be performed if problems arise during
synchronization setup. These procedures are provided below, and are valid
regardless of the development environment being used. Additional troubleshooting
steps, specific to the individual development environment, are provided in
respective sync topics in the CodeWright online help. Just search for the keyword
'synchronization' then look up the help topic for your environment.

If problems arise when setting up CodeWright synchronization for any of the

supported environments, do the following:
n Run the CodeWright Synchronization Wizard from the Wizard Choices dialog,
accessed by clicking Configuration Wizards on the Help menu. The Wizard will
copy the files needed for the respective environment, and make the registry
entries necessary for synchronization.
If an item in the list is grayed out, it means that the respective IDE was not
chosen for synchronization during the CodeWright installation. It will be
necessary to custom reinstall CodeWright in order to make those items
available.
n Make sure that the Synchronization checkbox is enabled in Tools|Customize|
Libraries dialog.
The Synchronization checkmark in this dialog causes CodeWright to load the
selected library into memory. It also adds the following line to CWRIGHT.INI,
CodeWright’s configuration file, so that the DLL will automatically load when
CodeWright starts up:

[LibPreLoad]
LibPreLoad=CWSYNC.DLL

Synchronization Setup Within the

Development Environments
After verifying that the CodeWright synchronization module has been loaded in
Tools|Customize|Libraries, it will be necessary to configure the respective
development environment to use that synchronization. The setup procedure for
each environment is slightly different, and will be described individually in the next
sections.

226 10- Synchronization

After setting up synchronization you may want to access menu items in the
synchronized environment using keystrokes, buttons, or menu items in CodeWright.
The last section of this chapter, Accessing Menu Items via Synchronization, talks about
setting up keystrokes (and the like) in CodeWright to access menu items in the
various synchronized development environments. The process for setting them up
is similar for each environment, so it is explained in its own section at the end of the
chapter.

Microsoft Visual Studio .NET File

Synchronization
Synchronization between CodeWright 7.0 and above, and Microsoft Visual Studio
.NET, requires the following initial setup steps:
1. In CodeWright:
n Go to Tools|Customize|Libraries and verify that the Synchronization
module is marked.
n If you did not choose to synchronize with Visual Studio .NET during
installation, run Help|Configuration Wizards|Sync Technology, select the
Microsoft Visual C++ wizard, and identify the location of Visual Studio
.NET on your system.
2. In Visual Studio, go to Tools|Add-in Manager and mark the item
CWVS7Addin.

Configure Synchronization Options

Before you use the synchronization feature, you will probably want to run the
program VCSYNC.EXE to configure the way CodeWright synchronizes with .NET.
To access the program, complete the following steps:
1. In Windows, access the CodeWright program group by going to
Start|Programs|CodeWright.
2. Click the item CodeWright MS Sync to invoke VCSync. An icon for the VCSync
Configuration dialog is placed in your systray.
3. Right-click on the icon and select Configure. The following dialog displays:

10- Synchronization 227

VCSync Configuration

4. Perform the following steps to configure VCSync:

n Enter the full path to the CodeWright executable (CW32.EXE) in the
CodeWright command line edit field (if it is not already in your PATH), or
use the Get Command Line button to automatically insert the command
line for you.
n The dialog’s options provide runtime functionality between Microsoft
Visual Studio .NET and CodeWright. They are set by default. Configure
them as desired, according to the descriptions provided in the topic Sync
Configuration Options later in this chapter.
Once you have set options on the VCSync Configuration dialog, you should not
need to run it again.

A First View
Once you have set up VCSync appropriately, start Visual Studio .NET (if it is not
already running). There should be a new Tools|Synchronize with CodeWright
menu item. Click on this item to start CodeWright with all the same files that were
loaded in the Visual Studio text editor.

On the CodeWright side, you can enable the MSDevSync toolbar in the
Tools|Customize|Toolbars dialog. This toolbar has buttons to synchronize the
current file or all open files. The toolbar buttons allow you to update files in Visual
Studio .NET without giving it focus.

228 10- Synchronization

A switch between the two programs (e.g. using [Alt]-[Tab]) will automatically reload
files that were changed in the other program. When synchronizing CodeWright and
Visual Studio .NET, changes to files are detected at three different times during
normal editing:
n When either Visual Studio .NET or CodeWright is first invoked.
n When either Visual Studio .NET or CodeWright becomes the active application.
n When either Visual Studio .NET or CodeWright edits an existing file on disk.

When you switch tasks between the two programs, each will automatically reload
any source files that were changed in the other, maintaining the cursor position in
both directions.

MSVC++ File Synchronization (5.x

and 6.x)
The CodeWright synchronization setup with Microsoft Visual C++ requires a
separate application called VCSync. VCSYNC.EXE provides a user interface to
configure the file synchronization utility and it serves as a loader for
VCSYNCIN.EXE. It runs continuously, trying to detect the presence of MSVC. Once
it does, it invokes VCSYNCIN.EXE, the program that actually does the
synchronization. VCSync provides file synchronization between CodeWright and
32-bit MSVC++ versions 5.x or 6.x.

VCSync Setup
Perform the following steps to run and setup VCSync:
1. Run VCSync. This can be done in one of two ways.
n Run VCSYNC.EXE using the CodeWright MSVC Sync program item in the
CodeWright program group. Access the CodeWright program group by
going to Start|Programs|CodeWright. Click the program item to invoke
VCSync and run it minimized. As long as it is running, it will periodically
check to see if MSVC++ has been invoked. When it has, it will start
VCSYNCIN.EXE, a background task. OR
n Run VCSYNC.EXE to invoke MSVC so that only one program invocation is
necessary, rather than two. Just specify the MSVC application name as a
parameter to VCSYNC.EXE using a –u option. The -u option will cause
VCSYNC.EXE to invoke VCSYNCIN.EXE and then exit. The following
steps describe how to do this:
1. In Windows, right-click on the Start button, then click Open.
2. Open the Programs folder.
3. Open the CodeWright folder.

10- Synchronization 229

 4. Right-click on the CodeWright MSVC Sync icon and click on
Properties.
5. Click on the Shortcut tab and type something similar to the following
in the Target field:
Example: VCSYNC.EXE -u "C:\Program
Files\DevStudio\SharedIDE\bin\MSDEV.EXE"
(all on one line)
This command runs MSDEV.EXE, installs
VCSYNCIN.EXE, and then closes VCSYNC.EXE.
VCSync initially runs minimized, as an icon in the Windows Systray. To
make configurations in the following dialog, double-click the icon to
maximize the application.

VCSync Configuration

2. Perform the following steps to configure VCSync:

n Enter the full path to the CodeWright executable (CW32.EXE) in the
CodeWright command line edit field (if it is not already in your PATH), or
use the Get Command Line button to automatically insert the command
line for you.
n The dialog’s options provide runtime functionality between MSVC++ and
CodeWright. They are set by default. Configure them as desired, according
to the descriptions provided in the online help topic Synchronization:
Configuration Options.
3. After VCSync has been loaded and configured, re-minimize it.

230 10- Synchronization

4. Now go to Visual C++ and click Tools|Customize... and select Addins and
Macro Files.
5. If the CodeWright Add-in is not already listed:
a. Select Browse. Set Files of Type to Add-ins (.DLL). Add
CWADDVC.DLL from the CodeWright home directory.
b. Open CWADDVC.DLL in your CodeWright home directory.
6. Check the selection box for CodeWright MSDev 5.x (6.x) Synchronization and
close the Customize dialog.

Once the above steps are performed, a CodeWright toolbar button appears in Visual
C++. The button can be moved, docked, or attached to any visible toolbars.

A First View
Once you have set up VCSync appropriately, start Visual C++ (if it is not already
running). There should be a new button. Click on this button to start CodeWright
with all the same files that were loaded in the Visual C++ text editor. A switch
between the two programs will automatically reload files that were changed in the
other.

When synchronizing CodeWright and Visual C++, changes to files are detected at
three different times during normal editing:
n When either Visual C++ or CodeWright is first invoked.
n When either Visual C++ or CodeWright becomes the active application.
n When either Visual C++ or CodeWright edits an existing file on disk.

Read the topic Bi-directional Synchronization, later in this chapter, to find out about the
MSDevSync toolbar that synchronizes backwards, from CodeWright to Visual C++.
Also see Accessing Menu Items via Synchronization to access Visual C++ menu items
from CodeWright.

Delphi File Synchronization

The DPRSync utility manages file synchronization between Borland Delphi and
CodeWright. This utility requires Delphi 6.0 or 7.0 and 32-bit CodeWright 4.0c or
later. The utility consists of two files: DPRSYNC.BPL, a Delphi expert, and
CWSYNC.DLL, a CodeWright Add-On DLL.
n For Delphi 7.0 users, the Delphi expert file is DPRSYNC7.BPL.
n For Delphi 6.0 users, the Delphi expert file is DPRSYNC6.BPL

10- Synchronization 231

 Note: If the correct options were selected during the CodeWright
installation, the required modules will have been installed in their
necessary locations for use by Delphi-CodeWright synchronization.
If problems arise, see the Troubleshooting topic for Delphi
Synchronization in CodeWright's online help.

DPRSync Setup
Perform the following steps to configure DPRSync:
1. Start the Borland Delphi IDE.
2. In the Component|Install Package… dialog, select the Add button.
3. If it is not already there, add the DPRSYNCx.BPL file found in the CodeWright
directory (DPRSYNC7.BPL for Delphi 7, or DPRSYNC6.BPL for Delphi 6) . You
will see CodeWright - Delphi Sync Package show up in the list of loaded packages.
4. After completing the above steps, you will see two new menu items:
n CodeWright! (found on the right side of the menu bar).
n An About CodeWright item on the Help Menu that accesses a
Configuration dialog for the Synchronization program.
5. From the Delphi Help menu, choose About CodeWright.
6. Select the Settings button to access the Delphi Integration Configuration
dialog:

Delphi Integration Configuration

232 10- Synchronization

7. Enter the full path to the CodeWright executable (CW32.EXE) in the
CodeWright command line edit field (if it is not already in your PATH), or use
the Get Command Line button to automatically insert the command line for
you.
8. The dialog’s options provide runtime functionality between Delphi and
CodeWright. They are set by default. Configure them as desired, according to
the descriptions provided in the topic Sync Configuration Options.

A First View
Open a sample project in Delphi. Select CodeWright! from the Delphi main menu,
or use the keyboard shortcut [Alt]-[i]. CodeWright should activate. The files that
were open in Delphi should automatically open in CodeWright.
Note: Synchronization happens when going from Delphi to CodeWright
by clicking on the CodeWright! menu item or by executing an
[Alt]-[i] shortcut. Synchronization going from CodeWright to Delphi
happens when CodeWright loses focus and Delphi gains it.

Known Problems
The following are known issues with Borland Delphi synchronization:
n Automatic Generation of Event Handlers: One problem may occur immediately
after returning to Delphi from editing a form in CodeWright. If the first
operation you perform is to double-click on a control to insert an event handler,
the handler may not get inserted into the correct position within the form’s
source file. A workaround is to place the form into a modified state first. For
example, insert a space, then delete the space.
n Forms inheritance: A problem exists when editing dependent forms in
CodeWright. Once the child has been modified in CodeWright, Delphi will be
unable to reload the parent until Delphi has been restarted.

Borland C++ Builder File

Synchronization
The BCBSync utility will manage file synchronization between CodeWright and
Borland C++ Builder. This utility makes it easy to switch back and forth between the
two applications, and makes sure that documents are kept up to date when you
switch. This utility requires C++ Builder 5.0 or 6.0 and 32-bit CodeWright. The
utility consists of two files: BCBSYNCx.BPL and CWSYNC.DLL.
n For C++ Builder 6.0 users, the name of the expert file is BCBSYNC6.BPL.
n For C++ Builder 5.0 users, the name of the expert file is BCBSYNC5.BPL.

10- Synchronization 233

 Note: If the correct options were selected during the CodeWright
installation, the required modules will have been installed in their
necessary locations for use by C++ Builder-CodeWright
synchronization. If problems arise, see the Troubleshooting topic for
C++ Builder Synchronization in CodeWright's online help.

BCBSync Setup
Complete the following steps to setup synchronization for Borland C++ Builder 5.0
or 6.0:
1. Start the Borland C++ Builder IDE.you will see two additional menu items in :
n CodeWright! (found on the right side of the menu bar).
n An About CodeWright item on the Help Menu that accesses a
Configuration dialog for the Synchronization program.
2. Go to the C++ Builder Component|Install Package… dialog.
3. Verify that the CodeWright - C++ Builder x Sync Package is loaded (where 'x' is
the Builder version). If not, click Add and load BCBSYNCx.BPL from the
CodeWright directory.
4. Click OK.
5. From the Builder Help menu, choose About CodeWright.
6. Select the Settings button to access the C++ Builder Configuration dialog:

C++ Builder Configuration

234 10- Synchronization

7. Enter the full path to the CodeWright executable (CW32.EXE) in the
CodeWright command line edit field (if it is not already in your PATH), or use
the Get Command Line button to automatically insert the command line for
you.
8. The dialog’s options provide runtime functionality between Borland C++
Builder and CodeWright. They are set by default. Configure them as desired,
according to the descriptions provided in the topic Sync Configuration Options.

A First View
Open a sample project into C++ Builder. Select CodeWright from the C++ Builder
main menu, or use the keyboard shortcut [Alt]-[i]. CodeWright should activate.
Press [Ctrl]-[P]. The Builder Project Info will display, if you made the key bindings
described in the section Accessing Menu Items via Synchronization.
Notes:
n Synchronization happens when going from C++ Builder to CodeWright
by clicking on the CodeWright menu item or by executing an [Alt]-[i]
shortcut.
n Synchronization going from CodeWright to C++ Builder happens when
CodeWright loses focus and Builder gains it.
n This synchronization can only be reliably achieved if the C++ Builder
BCBSYNC.BPL expert file is loaded as described above and the CodeWright
CWSYNC.DLL file was loaded during CodeWright installation.
n When synchronizing C++ Builder units, the .CPP file and the .H file are
both opened. Cursor positions are only set on the .CPP file. The .H file's
cursor position will remain in the position CodeWright had it last. When
changes are made to the C++ Builder Open Tools interface to access the .H
file, an update will be made to sync the cursor position for the unit's .H
files.

Visual Basic File Synchronization

The VBSync utility manages file synchronization between CodeWright and
Microsoft Visual Basic 6.0. This utility makes it easy to switch back and forth
between the two applications, and makes sure that documents are kept up to date
when you switch. This utility requires Visual Basic 6.0 and 32-bit CodeWright. The
VBSYNC utility consists of 4 files:
n VBSYNC.DLL: A Visual Basic 6.0 Add-in, Syncing VB to CW
n CWVBSYNC.DLL: A DLL called by VBSync.DLL
n CWSYNC.DLL: CodeWright Add-On DLL, Syncing from CW to VB
n BAS.DLL: Updated version of the CodeWright Add-on for Basic language
support. The DLL now offers language support for the following file types:
.CLS, .DSR, .DOB, .FRM, .CTL, and .PAG.

10- Synchronization 235

This program will NOT sync components with the following extensions:
.FRX,.DOX,.RES
These extensions will be saved when the CodeWright toolbar button is clicked, but
they will not be opened up into CodeWright. These files are in a proprietary binary
format and are not good candidates for editing in CodeWright as text files.
Note: If the correct options were selected during the CodeWright
installation, the required modules will have been installed in their
necessary locations for use by Visual Basic-CodeWright
synchronization. If problems arise, see the Troubleshooting topic for
Visual Basic Synchronization in CodeWright's online help.

VBSync Setup
Do the following to setup Visual Basic Synchronization with CodeWright:
1. Start the Visual Basic IDE. You will see three additional menu items:
n A CodeWright - VB Sync toolbar button to SYNC between VB 6.0 and
CodeWright.
n The VBSync command menu item, CodeWright!, in the Add-Ins menu. It
does the same thing that the toolbar button does.
n The VBSync configuration menu item CodeWright Sync... in the Add-Ins
menu.
2. From the Add-Ins menu, choose CodeWright Sync… to access the VB-
CodeWright Synchronization dialog:

VB-CodeWright Synchronization

236 10- Synchronization

3. Enter the full path to the CodeWright executable (CW32.EXE) in the
CodeWright command line edit field (if it is not already in your PATH), or use
the Get Command Line button to automatically insert the command line for
you.
4. The dialog’s options provide runtime functionality between Visual Basic and
CodeWright. They are set by default. Configure them as desired, according to
the descriptions provided in the topic Sync Configuration Options.

A First View
Open a sample project into Visual Basic 6.0. Select the CodeWright toolbar button.
CodeWright should activate and any files loaded in Visual Basic will subsequently be
loaded in CodeWright.
n Synchronization happens when going from Visual Basic to CodeWright by
clicking on the CodeWright - VB Sync toolbar button or the CodeWright! menu
item. Synchronization going from CodeWright to Visual Basic happens when
CodeWright loses focus and Visual Basic gains it.
n This synchronization can only be achieved reliably if the VBSYNC.DLL Add-In
and the CodeWright CWSYNC.DLL Add-On files are both loaded as described
above.

TI Code Composer Studio File

Synchronization
The TICCSync utility manages file synchronization between CodeWright and Texas
Instruments Code Composer Studio. It only works with Code Composer Studio
from Texas Instruments. The utility makes it easy to switch back and forth between
the two applications, and makes sure that documents are kept up to date when you
switch. It requires TI Code Composer Studio (v1.x) and 32-bit CodeWright 6.5 or
later.

The TICCSYNC utility consists of 3 files:

n CWSYNC.DLL: A CodeWright Add-On DLL that provides the sync from
CodeWright to TI Code Composer Studio.
n TICCSYNC.DLL - A TI Code Composer Studio plug-in that synchronizes TI
Code Composer Studio with CodeWright.
n TICCSYNC.EXE - A stand-alone program that provides automatic loading of
the synchronization utility and a user interface for its configuration.

10- Synchronization 237

 Note: If the correct options were selected during the CodeWright
installation, the required modules will have been installed in their
necessary locations for use by TI Code Composer Studio-CodeWright
synchronization. If problems arise, see the Troubleshooting topic for TI
Code Composer Synchronization in CodeWright's online help.

TICCSync Setup
Do the following to setup TI Code Composer Studio synchronization with
CodeWright:
1. Start the TI Code Composer Studio IDE. You will see two additional menu
items:
n A CodeWright! menu item on the Tools menu in Code Composer Studio.
Select it to launch CodeWright and synchronize files.
n A CodeWright Settings... menu item on the Tools menu in Code Composer
Studio. Select it to launch a sync configuration dialog box.
2. From the Tools menu, choose CodeWright Settings… to access the TI Code
Composer Studio Sync Configuration dialog:

Code Composer Sync Configuration

3. The dialog’s options provide runtime functionality between TI Code Composer

Studio and CodeWright. They are set by default. Configure them as desired,
according to the descriptions provided in the topic Sync Configuration Options.
4. Activate the TICCSYNC.DLL plug-in (this step may have already been
completed from actions performed in step 2). To do this either:

238 10- Synchronization

 n Select CodeWright! or CodeWright Settings... from the Code Composer
Tools menu. Once started the TICCSYNC plug-in will remain active until
Code Composer Studio shuts down. OR
n Run TICCSYNC.EXE from the CodeWright home directory. The program
runs minimized in the operating system's Systray. TICCSYNC.EXE
periodically attempts to detect the presence of Code Composer Studio.
When detected, TICCSYNC.EXE activates the TICCSYNC.DLL plug-in.
TICCSYNC.EXE runs continuously in the Systray until it is turned off.

A First View
Once you have set TICCSync up appropriately, start Code Composer Studio. Select
CodeWright! from the Tools menu. CodeWright will be activated with all the same
files loaded that were loaded in the Code Composer Studio text editor. When you
switch tasks between the two programs, each will automatically reload any source
files that were changed in the other, with the cursor position maintained. Changes to
files are detected at three different times during normal editing:
n When either Code Composer Studio or CodeWright is first invoked.
n When either Code Composer Studio or CodeWright becomes the active
application.
n When either Code Composer Studio or CodeWright edits a file on disk.
Notes:
n Synchronization happens when going from Code Composer to
CodeWright by clicking on the CodeWright! menu item.
n This synchronization can only be achieved reliably if TICCSYNC.DLL
and CodeWright CWSYNC.DLL are both loaded as described above.

Read the following topic Bi-directional Synchronization to find out about the
TICCSync toolbar that synchronizes backwards, from CodeWright to Code
Composer Studio. Also see Accessing Menu Items via Synchronization to access Code
Composer Studio menu items from CodeWright.

Bi-directional Synchronization
The synchronization modules for Visual Studio 98, .NET and TI Code Composer
Studio each have toolbars that make VCSync and TICCSync bi-directional. This
means that, when the appropriate button is pressed, files in CodeWright will
automatically load in Visual Studio or Code Composer Studio, with the cursor
position intact. The MSDevSync and TICCSync toolbars can be enabled in the
CodeWright Tools|Customize|Toolbars dialog. They have buttons for syncing
either the current file or all files open in CodeWright with the other development
environment.

10- Synchronization 239

The toolbars can also set breakpoints in Visual Studio 98, one at a time, and can build
and compile the appropriate files for both Visual Studio 98 and Code Composer
Studio.

Sync Configuration Options

The following configuration options are available in CodeWright Sync Configuration
dialogs. Use them according to the descriptions provided.
n The CodeWright Command line edit box is for the location (path) and
command for CW32.EXE. The full, correct directory path and name of the
CodeWright executable are needed if CW32.EXE is not set in the PATH
environment.
n The Get Command Line button retrieves the path to the CodeWright executable
file (CW32.EXE) from the registration database and inserts it in the CodeWright
Command Line edit box.
n The Browse button accesses a dialog that allows you to browse for the location
of the CodeWright executable (CW32.EXE). The file selected from this dialog
will be inserted in the CodeWright command line box.
n The Automatic reload of changed files check box causes an automatic 'Yes'
response to occur for any prompts regarding file reloading in the synchronized
environment. This will override dialog boxes that warn if files have been
changed or overwritten externally.
n The Load all files in CodeWright check box causes all files being edited in the
synchronized environment, along with their line and column numbers, to be
sent to CodeWright for editing. The operation occurs after an automatic
File|Save All has occurred in the synchronized environment. If this box is NOT
checked, a File|Save will only be performed on the current file in the sync'd
environment. Then the file and its line and column numbers will be sent to
CodeWright.
n The Automatic file synchronization check box causes both the synchronized
environment and CodeWright to detect changes to a file in the other's
application. If checked, changes to files in one application will be detected, but
the user will NOT be prompted to save them before reloading the file in the
other application. The save and reload will be done automatically. If NOT
checked, changes to a file in one application will be detected, but the user will
be prompted to save the file before reloading it in the other application.
n The Reset button resets the original settings to those in effect when you entered
the dialog.
n The Cancel button cancels out of the dialog without saving the changed
settings.
n The OK or Apply buttons save changes to the registration database.
n The About button displays an About dialog containing version information.

240 10- Synchronization

Note that the behaviors of the settings in the Configuration dialogs only occur when
the CodeWright! menu item is invoked from the synchronized environment, or
when switching between CodeWright and the synchronized environment using any
of the designated key combinations.

Accessing Menu Items via

Synchronization
Each of the synchronization utilities described in the previous sections have
functions that allow menu commands for the respective synchronized environment
to be called from within CodeWright (this is not yet available for the Microsoft Visual
Studio .NET synchronization). This allows tasks that are commonly performed in the
development environment, (e.g. builds and compiles) to be performed from within
CodeWright.
For example, the following function accesses the Open option on the File menu in
Microsoft Developer Studio 5.x/6.x: cwsyncvc_menustr 'FileOpen'
Functions such as the one above have been configured in different sections of a
CodeWright configuration file called CWSYNC.INI, located in the CodeWright home
directory. As stated, the functions are intended to provide more convenient access to
commonly used menu items in the synchronized environment.
The sections in CWSYNC.INI can be accessed by uncommenting some entries in the
[KmapAssign] section of the main CodeWright configuration file CWRIGHT.INI
(also located in CodeWright’s installation directory). The entries in CWRIGHT.INI
are:

; Uncomment for Visual Studio 97 (MSDev 5.0 or MSDev 6.0) Menu commands:
;ConfigFileRead( CWSYNC.INI, KmapAssign_MSVC50, FALSE )

; Uncomment for VBSync MS Visual Basic 6.0 Menu commands:

;ConfigFileRead( CWSYNC.INI, KmapAssign_VB60, FALSE )

; Uncomment for CWSync Delphi 7.0 Menu commands:

;ConfigFileRead( CWSYNC.INI, KmapAssign_DPR70, FALSE )

; Uncomment for CWSync Delphi 6.0 Menu commands:

;ConfigFileRead( CWSYNC.INI, KmapAssign_DPR60, FALSE )

; Uncomment for CWSync Borland C++ Builder 6.0 Menu commands:

;ConfigFileRead( CWSYNC.INI, KmapAssign_BCB60, FALSE )

; Uncomment for CWSync Borland C++ Builder 5.0 Menu commands:

;ConfigFileRead( CWSYNC.INI, KmapAssign_BCB50, FALSE )

; Uncomment for CWSync TI Code Composer Menu commands:

;ConfigFileRead( CWSYNC.INI, KmapAssign_TICC1x, FALSE )

10- Synchronization 241

Each of the preceding entries corresponds to a separate section in CWSYNC.INI that
lists key assignments for the appropriate synchronized environment. To enable the
appropriate keystrokes, uncomment the entry in CWRIGHT.INI that matches the
development environment being used. Remove the semicolon at the beginning of
the line to uncomment an entry.
Example: To set up the keystrokes for Delphi 6.0 menu commands,
uncomment the line that looks like:
;ConfigFileRead( CWSYNC.INI, KmapAssign_DPR60,
FALSE )

See the topic Assigning Menu Items to Keystrokes under the Synchronization topic in
CodeWright’s online help for a list of key assignments in CWSYNC.INI.

242 10- Synchronization

11- Search and Replace
and Navigational Tools
This chapter covers the many tools CodeWright has for navigating code. It starts by
talking about the unsurpassed Search and Replace features, including a discussion of
regular expressions. It goes on to describe Tags and Symbols, browsing tools,
Bookmarks and Button Links.

Search and Replace and Regular

Expressions
CodeWright offers a relatively large number of methods for performing search and
replace operations. Each has its own advantages under differing circumstances.
Some work on a single file and others work directly on the files on disk. Some are
meant to be quick and simple while others are designed for power. To help you
review your alternatives, the description of these methods are collected together in
this section.

The topics covered in this chapter regarding search and replace are listed below:
n Search and Replace dialogs
n Incremental Search
n Toolbar Search
n Quick Search
n Multi-source Search and Replace
n Search Options (Default Search and Replace Settings) dialog
n Fast Find on Edit and Search Window Popup Menus
n Stop a long search
n Regular Expressions

11- Search and Replace and Navigational Tools 243

Search and Replace Dialog
Many of the search features can be accessed from the Search menu. Clicking on the
Replace option on the Search menu accesses the Replace dialog. The Search dialog
has the same fields as the Replace dialog, excluding the replacement options. Refer
to the following picture of the Replace dialog:

Replace

Search and Replacement Edit Boxes

The Find What and Replace With edit boxes allow you to enter the pattern you
want to match and the replacement string. Both of these edit boxes maintain a
history of previous responses, which you may select by pressing the down arrow to
the right of the edit box.

Save Settings
The Save Settings check box is provided to save you from editing the Default
Search and Replace Settings dialog whenever you want to make a change to the
search values. Settings are not immediately written to disk, however. Checking the
box makes the current settings the default for that search session.

Multiple Sources Search Dialog

The Search and Replace Multiple Sources dialog allows you to define a search or
replace operation that is not confined to a single document. You may elect to search
through all loaded documents, through files that are members of the current project
space or project, or through any arbitrary set of files. To access the Search and
Replace Multiple Sources dialog, click Multiple Sources… on the Search menu.

244 11- Search and Replace and Navigational Tools

Search and Replace Multiple Sources

Search and Replacement Edit Boxes

The Find What and Replace With string edit boxes in the Search and Replace
Multiple Sources dialog allow you to enter the pattern you want to match and the
replacement string, just as you would in a single document search. Replace is
disabled until the Replace With option is checked. Both of these edit boxes maintain
a history of previous responses, which you may select by pressing the down arrow
to the right of the edit box.

If you elect only to search a series of files, rather than selecting the Replace action,
you are actually performing a File Grep. This can also be done from the File Grep
dialog (Search|File Grep). A list of matches in the specified files will appear in a
Search tab of the Output Window (Search 1, Search 2, etc.):
n The Search tab also displays the line numbers and the line containing the
matching text.
n To move to any of the matches listed in the Search tab, double-click on it with
the mouse, or select the matching line from the list and press E.

n Right-click within a Search tab to give a file focus. Then select Open Explorer
with Directory from the popup menu to launch Windows Explorer and
automatically navigate to the directory containing the file you selected.

Several features exclusive to the Search and Replace Multiple Sources dialog make
it one of the more convenient navigating tools in CodeWright. Descriptions of some
of these features are provided next.

Current Directory
The directory defined for the search is displayed at the lower left of the Search and
Replace Multiple Sources dialog, under the checkbox labeled Set as CWD. Items to
consider with regard to the current directory are:

11- Search and Replace and Navigational Tools 245

n The Browse Button: If you are not in the desired directory, press the Browse
button to select a new working directory for CodeWright.
n Set As CWD: After changing the directory, you may want that directory to
remain in effect after you finish searching and return to editing. If this is so,
check the Set As CWD box. If you just want the directory in effect for the
current search, ensure that this box is not checked.

Multiple Source Options

CodeWright has the following options in the Multiple Sources group in the Search
and Replace Multiple Sources dialog:
n Project Space: Use this option to search the members of the current project
space. A list box displaying all projects in the project space will appear when the
option is selected. All projects are initially selected for searching. Choose only
those that you wish to search.
n Project: Use this option to search through members of the current project.
n Documents only: Use this option to search the list of currently loaded
documents only.
n Files and folders: Use this option to search an arbitrary group of files in any
series of folders. Enter a name for your search set in the edit box associated with
this radio button, or select from the list of previously created search sets.

File Pattern
You may use the File Pattern edit box in the Search and Replace Multiple Sources
dialog for quick, ad hoc searches that you are not apt to repeat. It lets you specify a
file type or series of file types to search without associating it with 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 a semicolon.

The File Pattern supplements the selected items on the Search list, if any. You may
add it to the Search list by pressing the Add button.
Note: The File Pattern, when specified, does not override the list of files in
the Search list. If both are defined, the files in both the File Pattern
and any selected members of the Search list are searched.

246 11- Search and Replace and Navigational Tools

Search List
The initial contents of the Search list box in the Search and Replace Multiple
Sources dialog depend on which mode of search is selected.
n If Project space is selected, the box lists all files in all selected projects.
n If Project Files is selected, the box lists the files in the current project.
n If Documents is selected, the box lists the documents currently open in
CodeWright.
n If Files /Folders is selected, the box reflects the search set shown in the Files/
Folders combo box.

The Search List is usually a series of wildcard patterns. To edit the list, press the Edit
button to bring up the Edit Files/Folders dialog, described under the topic Edit
Search List.

When you first select your desired mode, you will see that the entire contents of the
listbox are 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 Search List

Click on a filename or wildcard pattern in the Search and Replace Multiple
Sources dialog’s Search list to select it for the search operation. Use the
following selection options:

n Select or deselect additional files or patterns by holding down the C

button and clicking on those members of the list.
n If the list of documents you don't want to search is shorter than the list of
documents you do want to search, select the documents you want to leave
out and then press the Invert button. All of the documents that were
previously selected become unselected, while the unselected documents
become selected.

Search Text Files Only

From either the File Grep or Search and Replace Multiple Sources dialog you can
elect to search Text Files Only. This excludes matches in binary files and buffers
from your search results.

Search Subdirectories
Check the Subdirectories box in the Search and Replace Multiple Sources dialog if
you want the search to encompass files in subdirectories of the path searched.

11- Search and Replace and Navigational Tools 247

Edit Modified Files
If you are performing a replace operation, you may wish to review the changes
made, or at least to know which files were changed. Select the Edit Modified Files
option in the Search and Replace Multiple Sources dialog to do this. Modified files
are loaded in CodeWright for viewing and possible editing. This is very convenient
if you plan to check the modified files into version control.

Threaded
The Search and Replace Multiple Sources dialog’s Use Thread option allows the
search or replace operation to proceed as a separate process, so that other tasks can
be performed as the search continues. If the operation is a search only (File Grep),
the Output Window updates as matches are found. Otherwise, matches are listed
after the operation completes.

Send Listing to Output Window

The Search and Replace Multiple Sources dialog’s List to Output Window option
controls whether and what information is sent to the tabbed Output Window. Its
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. Press the Output
button to display the following options in the Search Output Options dialog:
n List Filenames Only: Normally, search output contains the file and line
numbers of matches, and the line of text in which the match was found. For a
list only of filenames in which matches were found, check this box.
n Append to Listing: To add to the information in the Output Window rather
than replace what was there from previous searches, check this box. Otherwise,
the contents of the current Search tab will be reinitialized.
n Auto-increment Output Tab: Check this box to have CodeWright remember
the tab used for a search operation. When you perform another search
operation, results are output to the next non-hidden Search tab to the right
(Search 1, Search 2, etc.). Note that:
3 Search 1 is the default Search tab. To show additional Search tabs, mark
them as Visible on the Toolbars tab of the Tools|Customize|Toolbars
dialog.
3 The tab number will not increment if no matches were found on the
previous search.
3 If all the visible Search tabs contain output, the next search will wrap
around and be output to the first visible Search tab.

248 11- Search and Replace and Navigational Tools

 Example: Say you have the tabs Search 1, Search 2, Search 3 and Search 4
visible. You have performed four searches, and have output in each
of these tabs. Your 5th search will wrap around and replace or
append the results in the Search 1 tab.
n ChromaCode Matches: Enables ChromaCoding (coloring) for search output
displayed in the Search tabs of the Output Window, as depicted in the
following example:

ChromaCoded Search Output

n Save Window Contents between Sessions: Check this box to save the contents
of each active Search tab of the Output Window between CodeWright sessions.
Text and color attributes in these tabs will be restored on your next use of
CodeWright.
n List to File: You may specify that the information about the matches found be
stored in a file; you may also specify the name of that file. The default name is
CWFGREP.___, which is created in the current directory. You may specify
another name if the default causes a conflict, or if you wish to save the output
from the previous or current operation, rather than allowing it to be
overwritten. You may also redisplay the results of a previous search by
specifying the name of the file in which the results were saved.

Edit Search List

The Edit button in the Search and Replace Multiple Sources dialog brings up the
Edit File/Folders dialog used for editing the Search List more specifically. The
dialog’s options are described next.

11- Search and Replace and Navigational Tools 249

 Search Pattern
For the Edit File/Folders dialog’s Search pattern edit box:
1. Enter the file specification you wish to add to the current Search Set.
2. Press Add to add the file pattern to the Patterns list. Standard wildcard
characters ? and * are allowed. Your pattern may be anything from *.c to
k:\src\cw????.??v. You can enter several patterns at once by
separating them with semicolons. When you do so, each pattern is given a
separate line in the list of patterns for the Search Set.

Patterns List
The Edit Files/Folders dialog’s File Pattern listbox contains the patterns already
defined for this Search Set. The Search Set is composed of the union of these
patterns, rather than the intersection. Files are only searched once, even if they
match several of the Search Set’s patterns. Therefore, if the Search Set contains
the pattern *.*, other patterns are superfluous unless they contain a path
element. Source patterns that do not contain a path element will apply to the
current directory.

Drive and Directory Lists

The drive listbox and the Directories tree list in the Edit Files/Folders dialog
allow you to select the path you want to apply to the search set. This is only
meaningful if the Include Directory checkbox is checked when the Search
Pattern is added to the Patterns list.

Include Directory
When Include Directory is checked in the Edit Files/Folders dialog, the drive
and directory selected in the adjacent list boxes are automatically added to the
pattern specified in the Search Pattern edit box as you press the Add button.

List Editing Buttons

The List Edit buttons in the Edit Files/Folders dialog work as follows:
n Use Add, or Delete to add or remove members of the Search Patterns list.
n Use Invert to reverse the current selection; those items that were selected
become deselected and vice versa.
n Use Clear to deselect all the patterns on the list so that you can start
selecting from scratch.

250 11- Search and Replace and Navigational Tools

Default Options
All of the search dialogs (with the exception of File Grep) have a Default Options…
button that accesses the Default Search and Replace Settings dialog.

This dialog is used to set default options for search and replace activities.

Default Search and Replace Settings

To access the Default Search and Replace Settings dialog, do one of the following:
n Click Options on the Search menu.
n Click Default Options in the Search dialog.
n Click Default Options in the Replace dialog.
n Click Default Options in the Search and Replace Multiple Sources dialog.

The items in the Default Search and Replace Settings dialog are listed next.

Search Direction
The search Direction section of the Default Search and Replace Settings dialog
allows you to search forward from the cursor position or backward. In a multiple
source search, CodeWright searches forward from the beginning of each requested
file.

Replacement
The Replacement group of options in the Default Search and Replace Settings
dialog is specific to the replacement operation. They are listed next.

11- Search and Replace and Navigational Tools 251

n Prompted replacement. When the Prompted radio button is selected, you will
be prompted each time text matching the search pattern is found. You may
elect at that time to make or skip the replacement, or to cancel the search. The
search continues until no more matches are found in the defined scope of the
search, or until you select cancel. Enabling this option consequently makes
available the Modeless dialog option.
3 Modeless dialog. This option works with single documents only. It works
in conjunction with a prompted replacement. When CodeWright prompts
with options to Replace Current, Find Next, Replace Global, etc, the
Modeless option eliminates the necessity of canceling the prompt in order
to edit the document. With the Modeless option turned on, the prompt can
be left running at any point that direct editing of the current file becomes
necessary. When one is ready to proceed with the search/replace, the
prompt can be re-accessed without restarting the search.
n Single replacement: When you select the Single radio button, the first
occurrence of matching text is replaced without prompting.
n Global replacement: Select the Global radio button to cause all occurrences of
matching text within the scope of the search to be replaced without further
prompting.
n Preserve Case (applies to Search/Replace): The Preserve Case option sets the
case of the replacement string to match the case of the search string. The text
must follow any of the following patterns:
3 All upper case.
3 All lowercase.
3 Capitalized (First character upper case with the rest in lower case).
(If the matching text is found to be in mixed case, the matching text will be
replaced with the same case as the string that was entered in the Search/
Replace dialog.)

Prompt
The options in the Prompt section of the Default Search and Replace Settings dialog
control what word appears in the Find What field by default. Definitions of the
options are as follows:
n Current word: Uses the word at the cursor as the default search string.
n Selection/Word: Uses the contents of the selection as the default search string.
If there is no selection, uses the word at the cursor.
n History: Uses the most recent response in the history list.

252 11- Search and Replace and Navigational Tools

For Current word and Selection/Word, word delimiters can be used to determine
the word for the prompt. Define Word Delimiters on Tools|Customize|Language|
Options, then click the Browse button and mark the option Search Prompt and
Search Quick on the Word Delimiter Options dialog. (Refer to the online help topic
on Word Delimiters for information on how to define what a “word” is for files of an
extension.)

Search Options
The Options group of check boxes is also available in the Search, the Replace, the
Default Search and Replace Settings, the Search and Replace Multiple Sources,
and the File Grep dialogs. The options allow you to turn various search attributes on
or off. They include:
n Ignore case: When checked, uppercase characters or lower case characters will
be matched. When it is not checked, the case of the characters in the specified
search string is significant.
n Regular expression: When checked, the search pattern is viewed as a regular
expression. Some of the characters in regular expressions are given a different
meaning than they would have in an ordinary string search. This allows for
more powerful searches.
n Maximal match: A check in this check box indicates that regular expressions
should match the largest possible unit. If this box is not checked, regular
expressions will match the smallest possible unit, which in some cases may be 0
characters. For example, if the regular expression specifies matching 2 or more
A's in a row (AA+), and the search encounters 5 in a row (AAAAA), what does it
match? If maximal match is on, it matches five. If it is not, the search matches
the first two.
n Whole word: When the whole word box is checked, the pattern you are
searching will not match strings that begin or end with only partial words. That
is, the pattern must be preceded and followed by one of the following:
3 Beginning of file or end of file
3 Beginning of line or end of line
3 Spaces or tabs
3 Word delimiters
Refer to the online help topic on Word Delimiters for information on how to
define what a "word" is for files of an extension.
n Color Limited: Restricts your search to text that is ChromaCoded in a particular
way (e.g. find "foo" only in comments or strings). Press to display the Color
Limited Search Settings dialog on which you can indicate the ChromaCoded
elements that should be included in your search. (The dialog is named Default
Color Limited Search Settings if you access it from the Search|Options dialog.)

11- Search and Replace and Navigational Tools 253

 To review or modify how ChromaCoding is defined for a particular element, go
to Tools|Customize|ChromaCoding Lexers, select the Lexer for the applicable
language, and find the element.
The following table indicates where to look for each of the ChromaCoded
elements:

Color Limited ChromaCoding Lexer

Search Setting Settings Tab
Element

Text General

Comments Comments

Keywords Words

Strings Strings

Numbers Numbers

Braces General

Preprocess Words

Functions Words

Operators Words

User 1, User 2, etc. Words

Review color settings for these same elements by selecting the appropriate View
Theme on the Tools|Customize|View Themes|Colors dialog.

Matches
The following settings are under the heading Matches in the Default Search and
Replace Settings dialog:
n Select string: The Select String check box specifies whether the text that
matches the search will be highlighted in a selection at the end of the search.
n Retain selection: When the Select String box is checked, the Retain Selection
box indicates whether the selection that encompasses matching text is
momentary or retained so that you may operate on it (copy, cut, or replace).

254 11- Search and Replace and Navigational Tools

Start
The following options are listed under the heading Start in the Default Search and
Replace Settings dialog:
n Document Beginning/end: When enabled, the Document Beginning/end
option causes the search to go through the whole document regardless of cursor
position.
n Current Position: When enabled, the Current Position option causes the search
to go from the cursor position to the end of the document. Choosing this option
enables the Wrap at beginning/end and Exclude Start Position options:
3 Wrap at beginning/end: A check in the Wrap at beginning/end check box
indicates that you want to search the entire document. When the
document extremity is reached (the beginning or end of the document,
depending upon the direction of search), the search is continued from the
other document extreme. The search concludes at the point at which the
search began.
3 Exclude Start Position: The Exclude Start Position option tells CodeWright
that if there is text matching your search at the current cursor position to
ignore it. Presumably, you are not searching for this text, and perhaps have
just finished editing it.
n Restrict to selection: The Restrict to Selection check box allows you to indicate
whether you want the search to be restricted to the selection or marked block of
text. If the box is not checked, the scope of the search is global. This option will
be disabled if no selection is defined. Enabling this option consequently enables
the Multi-line Only option.
3 Multi-Line Only: This option is a modifier for the Restrict to Selection
option. When enabled, the search will only be restricted to the selection if
the selection spans more than one line. This eliminates incidental
selections of a single word, and most selections resulting from a search.

Example: Multi-Source Search

An example of one of the ways CodeWright's Multiple Source Search dialog can be
used to save valuable time follows.

Suppose you want to look for the string version in two directories, C:\DOCS\*.TXT
and D:\PROJECT\*.C. Here’s what to do:
1. Select Search|Multiple Sources to get to the Search and Replace Multiple
Sources dialog.
2. Select the Files/Folders radio button in the upper-right corner of the dialog.
3. In the accompanying combo box, select All Files.

11- Search and Replace and Navigational Tools 255

4. Click on the Edit button to bring up the Edit Files/Folders dialog. (If you just
want to do a search through files in the current directory, you can skip this step,
and just type in the file spec, with wildcards, into the File pattern box.)
5. Use the Directories, Drives, and Files lists to select the C: drive and the \DOCS
directory.
6. A list of files in that directory will appear in the Files list. You can restrict the
number of items in this list by selecting the appropriate entry in the Filters list.
7. Highlight the files you want to search, then hit the Add button in the lower
portion of the dialog.
8. Repeat steps 5-7 for the D:\PROJECT directory. The search list should now
show the files you want to search.
9. Click on the Invert button to highlight the list, or select just the specific files you
wish to search.
10. Click on the OK button. The Output Window will appear, and you will see
results of the search as the search pattern is found in the target files.
Note: The List to Output Window box has no effect on search-only
operations. The results will appear regardless. You would check this
box if you were doing a search/replace and wanted to see a report of
what replacements were made.
This may seem like a lot of mouse clicks. But often you will find that the last settings
you used are the ones you want, so most of these steps can often be skipped.

3 Often it becomes necessary to stop a long search. To do this, press C -[Break].

Fast Find on Edit and Search Window Popup

A Find item for performing quick multi-source searches is located on both the
standard right-click popup menu, and on the right-click menu for Search tabs of the
Output Window. The menu item only appears when a right-click is performed
while the document cursor is positioned at the beginning, middle, or end of a word.
The search will be performed on that word.
To use Fast Find, do the following:
1. Right-click in the current document on a word to be searched for.
2. Select the Find <word> in item in the popup menu. A submenu will appear.
3. From the submenu, select one of the following sets of documents.
n Files/Folders (searches files in the current directory)
n Documents (searches documents that are open in CodeWright)
n Project Files (searches files in the current project, if one is open)
n Project Space (searches files in the current project space, if one is open)
4. Use a Search tab on the Output Window (e.g. Search 1) to see the search results.

256 11- Search and Replace and Navigational Tools

Parameters for the search are defined as follows:
n The search will be conducted in the current working directory.
n Settings will be taken from the Search|Options (Default Search and Replace
Settings) dialog, along with the following options contained in the Multiple
Sources group of the Search and Replace Multiple Sources dialog:
3 Search Set. By default, the set of documents chosen will include all files for
Files/Folders (*.*), all documents for Documents, all project files for Project
Files, or all project space files for Project Space. If changes are made to the
search set in the Search and Replace Multiple Sources dialog, those
changes will be reflected in the Fast Find search.
3 File Pattern.
3 Search List.
3 Checkboxes for Text Files Only, Subdirectories, Edit Modified Files, Use
Thread and List to Output Window.

Incremental Searching
Incremental searches can save time and typing within both edit windows and tree
controls. This is because the string is matched as the word is typed, instead of being
matched after the word is typed. Many times the search function finds the string
you are looking for before it is all typed in.

Edit Windows
Begin an incremental search by invoking ISearch. This can be done from Tools|API
Command, or by pressing CBi in the CUA keymap. ISearch may already be
bound to a key in your keymap, but if not, you can easily add such a binding with
the Keyboard dialog on the Tools|Customize dialog.

ISearch prompts you for the search string, and you begin typing. Keep in mind that
ISearch always searches in a case-sensitive fashion. The case of the characters you
type 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
character and highlights it. ISearch performs a search after each character you type,
looking for the sequence of characters you have typed thus far. If it doesn't find a
match, it issues a beep, 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 that first matched the characters that remain. Delete the entire search
string and you will find yourself at the position where the search began.

11- Search and Replace and Navigational Tools 257

You cancel ISearch by pressing X twice. At that time, the string you typed into
ISearch is added to the search response history to make searching for that string
again more convenient.

Tree Controls
Tree controls are used in various locations throughout CodeWright. Examples
include the tabs of the Project Window (Project, Outline, etc.), the left pane of the
Directory Difference Window, and some dialogs (such as the Document/Window
Manager).

Incremental searching works basically the same in a tree control as an edit window,
except that you don't need to execute a command or keystroke shortcut. Just give the
tree control focus, then type as many characters as necessary to quickly navigate to
the desired string. If you type a character that is not part of a continuing match, the
search is started over with the next item that begins with that character.

Quick Search
The Quick Search facility is a function you can use to do an immediate search for the
word at the cursor. It uses settings from the Default Search and Replace Settings
dialog.

In the default configuration, you will find this function assigned to the button
on the Standard Toolbar, and assigned to the CBq key combination in the
CUA keymap. There is also a Quick Search option in the right-click popup menu.
Other assignments may be made, or readily changed.

To apply word delimiters to these Quick Search mechanisms:

1. Enter the appropriate characters in the Word Delimiters field on
Tools|Customize|Language|Options. (Refer to the online help topic on Word
Delimiters for information on how to define what a "word" is for files of an
extension.)
2. Press the Browse button (...) next to that field and select Search Prompt and
Search Quick on the Word Delimiter Options dialog.

Toolbar Search
"Toolbar Search" refers to the search capability built into the Standard toolbar in the

form of a drop-down listbox control . The Toolbar Search

provides the most immediate, convenient way to perform simple searches.

258 11- Search and Replace and Navigational Tools

To use the Toolbar Search, click in the Toolbar Search edit box (in the Standard
toolbar) and type in the string you wish to search for. This may be a regular
expression pattern, if you have regular expressions turned on in the Default Search
and Replace Settings dialog. The Toolbar Search box honors all of the settings in the
Default Search and Replace Settings dialog. As soon as you press E, the search
commences.

If CodeWright finds a match, the Toolbar Search will retain the focus. This gives you
the opportunity to search again just by pressing E again. Pressing anything else
will cause the Toolbar Search to lose the focus, and you are then able to edit at the
position where the match was found.

The Toolbar Search maintains its own response history, to allow you to recall strings
or patterns you previously typed. These are available when you select the down
arrow to the right of the edit box, causing the history list to drop down.

Regular Expressions
Regular Expressions are powerful notations for matching string patterns.
CodeWright makes UNIX-style Regular Expressions available for its search feature.
CodeWright also uses Regular Expressions for interactively customizing CodeWright
Symbols, embedded language configurations, user-defined keywords parser,
makefile reader, and Visual Studio workspace reader.
Note: For more information on Symbols, review the topic on Outline
Symbols later in this chapter. For more information on the makefile
and workspace readers, read the chapter on Projects, Project Spaces,
and Workspaces.
Investing a relatively small amount of time to gain some knowledge of Regular
Expressions will pay back in the long run with the amount of time you can save
searching for string patterns.

A Regular Expression can be as simple as a single, literal character, like "a". You could
search for the character "a" from the CodeWright Search dialog, with Regular
Expression marked, and you would be searching using Regular Expressions. Such
simple expressions are usually a sub-expression of more complex regular
expressions. When reading the descriptions that follow, remember that an
"expression" may mean a single character, a group of characters, or a class of
characters.

Special Characters
Regular Expressions give special meaning to certain characters. Some are operators
and some show grouping. There is also a method of representing non-printing
characters, such as a tab, within Regular Expressions. All other characters just
represent themselves, as they would in an ordinary string search.

11- Search and Replace and Navigational Tools 259

The characters to which Regular Expressions give special meaning are called
metacharacters. These characters and their meaning are shown below:

Character Meaning

. Matches any single character, except a

new line

* Matches zero or more occurrences 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 larger units and
dictates precedence. Each group is
also a Reference Group, which may
be pasted into a replacement string.

| Alternation. Allows matching the

expression on the left or on the right
of the operator.

$ Matches the end of a line.

^ Two meanings: Matches the

beginning of a line. Complement
operator when the first character in a
character class.

\ Used for escaping metacharacters and

non-printing characters.

\c The position in the pattern at which

the cursor is placed at the end of a
successful search.

260 11- Search and Replace and Navigational Tools

Escape Sequences
There are times that you want to use a metacharacter as itself -- without the special
meaning that Regular Expressions give it. For example, you may wish to match a
dollar sign, rather than look for the end of a line. To match a dollar sign you must
escape or quote it. This is done by preceding the character with a backslash. This is
true of all the metacharacters. To match a dollar sign, for example, you use \$ in your
Regular Expression, rather than just $.
Example: cat$ matches the word cat only when immediately followed by a
newline character; cat\$ matches the word cat only when
immediately followed by the character $.
Below is a list of other escape sequences supported by our Regular Expressions:

Escape Meaning

\n New line (<CR><LF> or <LF>,

depending on how it is defined for
the document).

\t Tab.

\b C -H (backspace).
\r Carriage return.

\f Form feed.

\nnn Octal value between 0 and 0377.

\xnn Hexadecimal digit between 0x00 and

0xFF.

\m The literal character m.

Matching a Character
The basic unit of a regular expression is matching a single character. You can match
a single character in one of three ways:
n Literally, by using the character itself or the appropriate escape sequence. (e.g.
‘cat’)
n Ambiguously, by using the dot ( . ) metacharacter, if matching a character
literally is too limiting. (e.g. ‘..t’)
n With a Character Class. If a literal character is too narrow a match and the dot is
too broad a match, a character class can be used for anything in between. (e.g.
[A-Za-z])

11- Search and Replace and Navigational Tools 261

Character Classes
A character class is a series of characters enclosed in square brackets. It specifies a set
of characters, any one of which may match. For example, the character class:
[AEIOUYaeiouy]

matches any vowel, whether upper or lowercase.

Ranges of characters may also be specified within a character class. This is done by
placing a dash between the character that begins the range and the character that
ends the range. The following character class [0-9]will match any character
between 0 and 9.

How do you match a DASH (-), then? If it is not in the character range you specified,
just place it at the beginning or end of the character class where it is not between two
characters of the class. If you precede the dash with a backslash ( \ ) you can put it
anywhere within the class.

The CARET ( ^ ) has a special meaning when it appears as the first character of a
character class. It complements the class. When it appears at any other position
within the character class, it just adds the up-caret to that class. You may use it as a
shorthand method of saying "match any characters except for the following:", rather
than specifying a large character class.
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
characters that must be escaped are as follows:

] " \ and sometimes - and ^ depending on the position within the class.
n Escape the - when you use it in the middle of a class but don't intend it to signify
a range.
n Escape the ^ when it would otherwise be at the beginning of a class but you do
not intend for it to signify complement.

When in doubt, escape the character. It can't do any harm. The above characters
look like this when escaped:

\] \" \\ \- \^

262 11- Search and Replace and Navigational Tools

Iteration Qualifiers
Iteration qualifiers are metacharacters that are not regular expressions by
themselves. Instead, they state how many iterations of the preceding expression
there must be or can be, in order to match.

These metacharacters are: *, + and ?.

n The * matches any number of occurrences
n The + matches one or more
n The ? matches zero or one.

Without these qualifiers, a regular expression will match exactly one occurrence in
the text.

Examples
Let us consider some specific examples of how these qualifiers might be used in the
task of matching white space:
n \t*
This example will match any number of consecutive tabs, including none. By
itself, it is not very useful to match none of something. As part of a larger
regular expression, it could be quite useful.

For our purposes here, the following might be preferable:

n \t+
This example matches one or more consecutive tabs. The tab is represented as
\t, and the plus sign says "one or more of the previous". To match white space,
we need to match spaces too. We don't know what order the spaces and tabs
will come in, and we don't know how many there will be. These are signs that
we need a character class.
n [ \t]+
This example uses a character class containing a space and a tab. The + sign
following it means that this Regular Expression will match any combination of
spaces and tabs, so long as there is at least one space or tab.

If you wanted to match the white space within a function call, where you knew
there might be one space or tab, or there might be none, your expression could look
like this:
n \([ \t]?

11- Search and Replace and Navigational Tools 263

 This example searches for a left parenthesis followed by zero or one spaces or
tabs. Since the left parenthesis is a metacharacter it is necessary to escape or
quote it with a preceding backslash. The \t we have used before to represent a
tab character. The question mark says "zero or one of the preceding".

Regular Expressions: Positioning at Beginning/End of Line

You may use the metacharacters ^ and $ to qualify your Regular Expression further.
We have already seen how the ^ may be used to complement a character class, but
it has another quite different use outside of a character class. These metacharacters
specify that, in order to match your Regular Expression, the text must appear at the
beginning or end of a line, respectively. Unlike the iteration qualifiers, however,
these metacharacters can stand alone as Regular Expressions. That is, you can search
for just the end of the line or just the beginning of the line. Examples are provided
next.
Examples:
n ^PUBLIC matches the word "PUBLIC" when it occurs at the beginning of a
line.
n \)$ matches a right parenthesis, a character which must be escaped, when it
is found at the end of a line.
n ^\)$ matches a right parenthesis when it is the only thing on the line.

Alternation and Grouping

Alternation and grouping go hand in hand. Alternation often relies on grouping
and is the primary need for grouping.

Alternation uses the metacharacter | to denote that a match has been found if the
text matches either of two Regular Expressions. This operator may be repeated to
indicate that the text may match any one of several expressions.

Because of the typical order of precedence, the alternation applies to the entire
expression, if not limited by grouping. Grouping occurs when you place
parentheses around one or more expressions that are part of a larger expression.
Examples:
n PUBLIC|PRIVATE matches either the word "PUBLIC" or "PRIVATE".
n PUBLIC (void|DWORD) matches the word "PUBLIC", when followed by a
single space, and then followed by either the word "void" or "DWORD".
n ^PUBLIC[ \t]+(void|int|long|DWORD) matches, at the beginning of a
line, the word "PUBLIC", followed by one or more spaces or tabs, followed
by any one of the following words: "void", "int", "long" or "DWORD".

These examples begin to show the power of regular expressions.

264 11- Search and Replace and Navigational Tools

Reference Groups and Replacement Strings
In addition to showing association and precedence, grouping allows the use of
Reference Groups. A reference group is one or more expressions that have been
placed between parentheses and then pasted into a replacement string by
referencing its number.

CodeWright assigns a reference number, from 1 to 9, to the text matching each

group defined. Reference numbers are assigned from left to right. You may paste
the associated text into a replacement string by using this number, preceded by a
backslash.

The following demonstrates how reference groups may be used:

Example: Search string in document:
GotoXY(cat,dog)

Search pattern:
GotoXY\((.*),(.*)\)

Replacement pattern:
move_cursor(\2,\1)

Replacement result in document:

Move_cursor(dog, cat)

Note that in replacement patterns you do not need to escape metacharacters, such as
the left parenthesis, with a backslash. There are a few escape sequences that are
meaningful in a replacement string, such as those used by reference groups, but
such sequences are not themselves regular expressions. An operation using
reference groups, such as that depicted above, could be used to reverse the
parameter order used by one function when converting to a similar function.

There is an implicit reference group that you can use in replacement strings to
represent the matching text in its entirety. You reference this group in the
replacement string with an & at the desired location. This means that you must use
\& to specify an ampersand in a replacement string, when regular expressions are
enabled.

Placing the Cursor

When you search for a piece of text, it is usually because you are going to do
something with it or to it. After a successful search operation, CodeWright positions
the cursor at the beginning of the matching text -- at least, that is the default action.
What if you want to edit the other end of the matching text, or perhaps the middle?

11- Search and Replace and Navigational Tools 265

When using CodeWright's regular expressions, you have a special escape sequence
available that allows you to indicate where in the matching text the cursor should be
positioned. You should note that this is available only for search operations. It is not
for use in replacement text.

The escape sequence that specifies cursor position is \c. An example of its use
follows:

singletons\[\c.*\]

This example places the cursor at the beginning of whatever text is contained
between the left and right square brackets. The square brackets are metacharacters
and are therefore escaped. This cursor positioning facilitates editing the contents of
the square brackets.

Examples
The following examples are intended to inspire your own use of regular expressions:

Regular Expression Examples

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 white space)
[^ \t]+\c([ \t]|$) End of word (simple white space)
([^A-Za-z0-9]|^)[A-Za-z0-9]+ Beginning of word (Non-alphanumeric)
[A-Za-z0-9]+\c([^A-Za-z0-9]|$) End of word (Non-alphanumeric)
/\*.*\*/ Single-line comment (C language)
/\*.*\n([ \t]*\*.*\n)*.*\*/ Multi-line comment (C language)

Searching for Spaces, Tabs and other Blank

Characters
One of the longstanding Search/Replace features in CodeWright is its ability to find
and replace invisible characters. Parts of the topics below have been generally
covered in the previous discussion on regular expressions, but they will be discussed
more specifically here with regards to spaces, tabs and new lines.

266 11- Search and Replace and Navigational Tools

Searching for Spaces or Tabs
To find tabs or spaces, complete the following steps:
1. Go to the Search menu and click Search.
2. In the Find What field press the space bar to insert a space, or type \t to insert a
tab.
3. Mark Regular Expression and Save Settings.
4. Click OK.

Searching for New lines

To find new-line characters, complete the following steps:
1. Go to the Search pull-down and click on Search.
2. Type \n in the Find What field.
3. Mark Regular Expression and Save Settings.
4. Click OK.

The procedure for replacing characters with tabs, new lines, and spaces is the same
as the procedure for finding them, only the space, \t, and \n characters are typed into
the Replace With field of the Replace dialog, instead of the Find What field of the
Search dialog.

Searching for control characters (binary/hex

data)
You can use control characters in both search and replacement patterns. You can
specify any byte (hex) value as part of a pattern.

First, turn on Regular Expressions from the appropriate dialog. Then use the \x
notation to specify hexadecimal values. For example, to search for the form feed
character, you can use this string:

\x0C

(That’s backslash x zero c.) Make sure there are two digits following the x. If you want
to search for two consecutive bytes by hexadecimal value, string them together like
this:
\x0C\x0D

11- Search and Replace and Navigational Tools 267

Searching for New lines: Issues
Generally, '\n' is the suggested method for matching or replacing line ends in
CodeWright , as described in the previous topic on Searching for New lines (the '\' must
be doubled when used in code). In some cases, however, it is more desirable to
search for new lines using their respective hexadecimal notations (0D0A, 0A, 0D,
etc). Since hexadecimal 0D and 0A characters make up ends of lines in one form or
another, an exception has to be made when searching for and replacing them, to
avoid disrupting partial line-end sequences. Therefore, when searching for 0D and
0A hex characters, keep the following in mind:
n \x0A will match a solo (without a preceeding 0x0D) 0x0A but not the pair.
n \x0D will match a solo (without a following 0x0A) 0x0D but not the pair.
n \n will match a solo 0x0A or a 0x0D, 0x0A pair.

More information on setting and using UNIX EOLs can be found in the chapter
UNIX.

Selective Display
The Text menu has an option for Selective Display. Selective Display is a feature
that "collapses" or "folds" text in the current document so that only desired text is
displayed, and the remainder is hidden. The Selective Display menu item accesses
a dialog that has options for controlling which lines of the document are visible.

Selective Display

268 11- Search and Replace and Navigational Tools

Selective Display Options
Selective Display options include the following:
n Search text: Displays or hides text matching a pattern.
n Multi-level: Hides text based on braces or indentation levels.
n Preprocessor directives: Hides text based on C/C++ language preprocessor
directives.
n Lines: Displays or hides a selected group of lines.
n Paragraphs: Displays only the first line of each paragraph. A paragraph is
defined as text separated from other text by one or more blank lines.
n Routine Definitions: Displays lines containing function definitions for the
language indicated by the file type. In CUA, CSg also controls
Routines selective display.
Note: Display on the right-mouse popup menu accesses many
Selective Display options.

Pre-processed View
The Preprocessor directives option in the Selective Display dialog is a special
option for C/C++ users that find their source files cluttered with #ifdefs. The option
allows source code to be displayed exactly as the compiler will see it, while it is being
edited.

Applications that are written to run on more than one platform, or custom software
written for more than one company often use #ifdefs to avoid redundant
maintenance. If separate versions of a file are maintained for each of several
platforms or customers, each version needs to be changed whenever an
improvement is made to code that is common to all of them. #ifdefs are used to
maintain different versions in a single file. Then changes to common code only need
to be made once.

If code becomes confused with many preprocessor directives, whatever time is

saved on redundant maintenance could be lost just trying to figure out confusing
source code. CodeWright allows full benefit from the use of pre-processor
conditionals by letting the code be seen more clearly for what is being worked on.
Thanks to Selective Display Mode, the whole file is still there, but the parts that don't
apply can be hidden.

Adding "defines" to the Preprocessor directives- Defined Constants field allows

specified defines to remain visible in preprocessed view. Multiple “defines” can be
specified by separating them with semi-colons. Once the necessary “defines” have
been added, and desired options have been chosen, clicking the dialog’s OK button
will hide specified preprocess code.

11- Search and Replace and Navigational Tools 269

Viewing/Hiding Lines
Once a document is in selective mode, lines are preceded with a small button or
icon. When the button contains a plus sign, it indicates that there is hidden text
following that line.

n To view hidden text, double-click on the plus sign or press SE on that

line. The plus sign then turns to a minus sign, to indicate that the section has
been expanded to show the "invisible" lines.
n To collapse the section again, double-click on the minus sign or press
SE again.
n Double-clicking with the right mouse button also expands or collapses hidden
text.

Selective Mode

Just press X when you want to restore the invisible lines. When you want to see
just the lines you have selected again, you can complete one of the following:

n Press CSc in the CUA or the BRIEF keymap, press Cm and Ch in

the Visual Studio .NET keymap, or press # in the vi emulation.

n Mark Selective Display on the Document/Window Manager|Display dialog.

n Choose Display Mode|Selective Display from the right-click menu in a
CodeWright edit buffer.
Note: When you insert a line, the visibility attributes for the new line are
taken from the preceding line. If you return to Selective Display
mode directly, the new line may display differently than if you
reprocessed the document by using the Selective Display dialog.

270 11- Search and Replace and Navigational Tools

CodeWright will save the current selective display view between sessions if the
option Visible Lines is marked in Tools|Customize|Environment|State.

Saving Visible Lines

Use the CodeWright API function CopyVisibleLines( ) to save the visible lines to a
new buffer named “untitled” in the current working directory. You can then save
the resulting file. On the CodeWright web site, refer to the CodeWright Macro
Library document API Macros: Write Selective Display Contents to a Buffer for a detailed
explanation.

Browse, Tags, Symbols and Objects

Whether working on someone else's code, with a long line of inheritance, or working
on code you wrote last week, you can spend a lot of time navigating it. CodeWright
provides the following text and source code tools for finding and navigating code:
n Browser
n Tags
n Outline Symbols
n Objects Window

Each of the above tools has advantages and disadvantages when used for
navigational purposes. The next few paragraphs describe reasons why one might
choose one over another.

Which Navigational Tool Should I Use?

Choose one or all of the navigation methods described in the following topics:
Browser, Tags, Outline Symbols, and Objects Window.

Browser
The CodeWright Browser uses Microsoft .BSC files that are produced when
compiling source code in Microsoft Developer Studio. It also uses compiled tags
databases produced by the TAGSW32 utility shipped with CodeWright. The browser
uses a graphical tree in a special tab of the Output Window to demonstrate
relationships and simplify locating necessary files or other pertinent information. If
you are compiling with Microsoft tools this method gives you the 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.

11- Search and Replace and Navigational Tools 271

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

Outline Symbols
The CodeWright Outline/Symbols feature has its own graphical tree interface in the
Outline tab (on the Project Window by default). It also uses the Symbols tab (on the
Output Window by default) and background parsing to let you view the most up-to-
date information about your project. Furthermore, Symbols support a large number
of languages and can be readily modified to add to or expand the browse capabilities
for new or existing languages supported by CodeWright.

Objects Window
The CodeWright Objects Window is a tab on the Project Window by default. It
displays a hierarchical view of C/C++, C# and Java symbols that are associated with
the name typed in the Identifier box at the top of the window. The Objects Window
can be used to view and browse code.

Click on a symbol in the Object Window to access the position in the source file at
which the symbol is defined.

Call Tree and References

Right-click on a symbol in the Objects Window (or your edit document) and
choose Show Symbols Called or Used by (Function or Class Name) to display a
call tree indicating the function(s) that the selected symbol calls and/or the other
symbol(s) that it uses. You can also select Show References to (Selected
Symbol) to locate and define the functions, classes, etc., that refer to (call or use)
the selected symbol.

Browser Support
The CodeWright Browser supports two kinds of browser databases:
n Microsoft format .BSC databases These are the databases generated by Microsoft
C/C++ 7.0 and later.
n Borland Compiled Tags databases These are the databases produced by the
TAGSW32 utility shipped with CodeWright. The Tags databases are given the
extension .PTG by convention.

272 11- Search and Replace and Navigational Tools

Browse Tab of the Output Window

The Browser is one of the windows available for viewing in the tabbed Output
Window (by default). It appears when you select Browse from the Project menu or
when you select the Browse tab on the Output Window. The Browser is actually
two windows side by side with its own toolbar at the top. The Tree window appears
on the left and the Inspect window appears on the right.
Press ! in the Browse window to receive help, press X at any time to leave the
window and return to the current edit window.

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

Traversing the Tree

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

the (expand/collapse) button on the browser toolbar.

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

11- Search and Replace and Navigational Tools 273

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

Bitmap Description
Root 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.

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

Browser Toolbar
Here is how the Browser toolbar appears:

Refer to this diagram as you read the following descriptions.

274 11- Search and Replace and Navigational Tools

 Jump to Code
After traversing the tree, you will usually want to go to the corresponding
source. There are two Go to buttons on the Browser toolbar that allow you to
do this.
n If you wish to go to the source code represented by the selected tree node

(usually a point of definition), you can press the (Go to) button on the
left of the toolbar. Simply pressing the g key will also take you to
whatever is selected in the Tree window.
n If you have selected a reference, a calling or called function in the Inspect

window, you may wish to press the key (Go to from Inspect) to go to
that reference or function.

String Search

The String Search feature of the browser works like a grep or

filter of information in the database. Use it to filter out extraneous information.
It is one of the most useful features of the browser.
To use the String Search feature, enter a string into the combo box on the
Browser toolbar. Unlike some other browsers, the string you enter will not be
treated in a case sensitive manner, and a trailing wildcard will be assumed. That
is to say, if you enter "dump", it will match strings like "Dump" and "dumpFile".
Each matching identifier is displayed as a node on the tree. All other nodes
disappear. You can then traverse this "filtered" tree.

Query Button
The first button to the right of the Search String combo box on the browser

toolbar is the Query button. You can initiate a query by pressing the button,
or by pressing the q key. Depending on the context, one of six query dialogs
will appear. An example dialog is shown below:

Tags Function Query

11- Search and Replace and Navigational Tools 275

 Each query dialog has a set of action buttons and filter check boxes. The filter
check boxes apply only to the action buttons that are enclosed in the same
group box. Therefore, in the example above, the check boxes apply only to the
Used By and Uses buttons. The other action buttons operate independently of
the filters.
With all the filters enabled (all the check boxes checked), you may find that you
have too much information to sift through to find what you are after. It is
probably best to check the minimum number of boxes that fill your needs.
The six Query Dialogs are as follows:

Button Purpose

General General inquiries about the terminals (leaves) on

the tree.

Class OOP class inquiries.

Function Inquiries about functions.

Friend Class (Fclass) OOP friend class inquiries.

Database Inquiries from the root of the database.

Module Inquiries related to a module.

Quick Search

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

Called By / Calls To
When you have selected a function in the Tree window, you may view either a
list of functions that call it, or a list of functions it calls by pressing one of the

Called By/Calls to buttons . These functions do not work with

CodeWright generated databases; only with .BSC files generated by Visual
Studio or with other supported databases generated by more sophisticated,
third party browser utilities.

276 11- Search and Replace and Navigational Tools

 Search After Go To

The Search After Go To button is a toggle that determines what action is

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

Filter Toggle Buttons

The Filter Toggle buttons allow you to focus in on specific categories of objects
by turning filters on and off. Each of the lettered buttons at the right of the
Browser toolbar has an on and off position. When depressed the button is on,
and objects associated with that button will show up in the tree. When the
button is up it is off, and related objects will not show up in the tree. You can
reverse the condition of any of these buttons by clicking on it with the mouse or
by pressing the corresponding letter on your keyboard (i.e., ftmvc ).

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

Letter Filter Objects

F Function references and definitions.
T Type references and definitions.
M Preprocessor macro references and definitions.
V Variable references and definitions.
C OOP Class references and definitions.

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

Tags Support
CodeWright has support for CTags and other Tags-generating programs whose
databases conform to the standard Tags format. The file TAGS.C (in the CodeWright
SDK) contains the functions that support this capability, and also defines the
standard Tags file format.

11- Search and Replace and Navigational Tools 277

In addition, CodeWright comes with a built-in Tags database generation capability.
This program produces both a standard Tags database and a compiled database. As
mentioned, the resulting compiled database (.PTG file) may be used with the
CodeWright Browser in a similar fashion to a browser database. You can search the
database and traverse its contents via a graphical tree.

A standard Tags database adds browse-like capabilities to an editor that knows how
to read and use the database. If you see the name of a function on the screen and
need to know what that function does, CodeWright Tags functions allow you to
jump directly to the original location in the original buffer.

CodeWright is known to be compatible with the PCTags program from Moderne

Software. PCTags.zip is available for download from the Borland FTP site at ftp://
209.164.41.49/codewright/addons/archives.

Tags Setup
To get CodeWright to generate and use Tags databases automatically requires the
following steps:
1. Create a project whose members are the files you want to scan for your Tags
database. Refer to the chapter on Projects, Project Spaces, and Workspaces for
information on creating a CodeWright project.
2. Define which files will hold your Tags data -- your standard Tags database and
your compiled database for use with the Browser. There are two entries on the
Directories tab of the Project Properties dialog that store the name and location
of these database files. The entries are listed as Browser Database, and Tag
Database. If you are using the CodeWright compiled tags utility, be sure to
enter a filename in the Browser Database field that employs the .PTG extension
rather than .BSC to avoid having the .BSC file overwritten by the browser
database generator.
3. Select Build Tags from the Build menu.
4. Use the Browser or TagFind function.

Using the Tags Database

To use the standard Tags (not compiled) database, you need to have the function
TagFind assigned to a key. The TagFind function looks at the word at the cursor
and tries to find a match for it in the database. You can assign this function along
with TagNext and TagPrev to keystrokes, if they are not already assigned. You do
this through the Keyboard dialog on the Tools|Customize dialog For more
information on the TagFind API, refer to CodeWright’s online help. For more
information on custom keystrokes, refer to the chapter on Custom Interface.

278 11- Search and Replace and Navigational Tools

To use the compiled Tags database with the Browser, load the .PTG file by pressing

the Browser File Open button and browsing for the file. You will then be able to
traverse a tree of your Tags database, search the database, and do queries for
functions and other objects (barring friend classes). You will only be able to query
definitions, however. References (caller/calling trees) are not stored in the Tags
database. For more information about the TagsW32 utility provided with
CodeWright, see Appendix A at the end of this manual.

Outline Symbols: Overview

Outline Symbols are a type of browser for navigating and investigating code. They
are named Outline Symbols because they use two system windows: one called the
Outline Window (a tab on the Project Window by default) and the other called the
Symbols Window (a tab on the Output Window by default). Outline Symbols
constantly update in the background (there is no compiling required) and they have
broad application, that is, they will work with virtually all languages for which
CodeWright provides support (C++, C#, Java, Delphi/Pascal – even .INI files).

What are Symbols?

Symbols are any element of code for which a parser has been written. Parsers are
regular expression patterns used to find and separate designated string patterns
from code. The strings are subsequently displayed in either the Symbols Window,
the Outline Window, or both. Typically, symbols include functions, classes, macros
and the like. New parsers can be added by creating the proper regular expression
parser. Files are scanned using these parsers, and the locations where symbols are
defined are collected and placed in the symbols database.
CodeWright symbols parsing starts with the member list of the current project.
Other files can then be added as part of the list to be scanned in the CodeWright Edit
Symbol File List dialog. For example, you might want to scan MFC symbols, but
don’t care to include the MFC source files in each project. You just add them to the
Edit Symbol File List dialog. To access the Edit Symbol File List, press the File List
button in the Symbols Window. It’s as easy as adding files to a project.

Symbols Window

11- Search and Replace and Navigational Tools 279

The Symbols Window is normally used in conjunction with the Outline Window, to
which it has a special link. This link allows the Outline Window to pass symbol
names to the Symbols Window for lookup, thereby automating the process of
viewing symbols in the Symbols Window. Together, the Outline and Symbols
Windows provide Browser-like capabilities for a variety of file types without any
need to compile to keep current with code changes. The Symbols Window allows
you to list the location or locations where a symbol is defined.

The Symbol box at the top of the Symbol Window

normally reflects the symbol selected in the Outline Window. A history list is
maintained in the drop-down list under the Symbol box, recording the recent
entries in this box. Also, when the cursor is positioned in the edit buffer,
CodeWright will pick up whatever the cursor is sitting on and display it in the
Symbol box. Then a background search is done through the symbols database to see
if there are any other occurrences of this symbol.

If CodeWright doesn’t display anything in the Symbols Window it is likely that the
symbol is not contained in the database. There are two reasons that a symbol may
not be stored in the database:
n The symbols parser(s) (regular expression) does not match the string.
n It is not the Definition of the symbol (CodeWright doesn’t display References or
other uses of the symbol).

If the symbol being displayed is only located in one file, the associated code is
displayed in the window. If there is more than one symbol in several locations, a list
of files containing those locations will be displayed in the Symbols Window. The
locations can be selected from the list by double-clicking on a filename in order to
open the file in the buffer editing area. The cursor will be positioned at the indicated
location.

Symbol Scanning
The Symbols Window conducts a detect scan on listed files after a 3 second idle
period for several reasons:
n To determine if any of the time/date stamps on the files in the database have
changed.
n To determine if any newly-created functions need to be added to the database.
n To determine if any newly-added project files need to be added to the database.

Only if it detects these changes, does it go ahead and start updating the database. If
the symbols scan detects a keystroke, it will interrupt its detect scanning and begin
again where it left off on the next scan. The symbols scanning and updating can be
disabled (see Symbols Database below).

280 11- Search and Replace and Navigational Tools

Outline Window
The CodeWright Outline Window displays symbols in a graphical tree, with each
loaded file displayed as a root. As files are loaded, or edit windows are changed, the
symbols found in that file are displayed beneath the file’s name in the Outline
Window.

Outline Window

The symbol parser icons that might display in the Outline Window are identified in
the following list:

Icon Symbol Parser

Function

C Function

C++ Function

Prototype

Include

Procedure

Class

11- Search and Replace and Navigational Tools 281

 Icon Symbol Parser
Macro

String

Variable

Constant

Definition

Preprocessor

Struct

Unknown

A single mouse-click on the symbol of interest displays information for that symbol
in the Symbols Window. A double-click also moves the edit window to the defining
location. When you single-click on a symbol listed in the Outline Window, as
described above, the view in your current edit window is not modified. This allows
you to browse symbol references without losing your place. If you double-click on a
symbol listed under one of the loaded files, your view in the current edit window
moves to that location, in addition to listing references in the Symbol Window.

As you load files or change edit windows, the Outline Window lists all open buffers
as folders, and if the Auto Expand/Collapse button is depressed (described below),
automatically expands the view of the current buffer to show its matches. Double-
clicking on any of the listed folder icons will always expand the outline view, if there
are symbols to be displayed for the file.

The symbols displayed in the Outline Window are listed in the order in which they
appear in the source file. They can also be displayed in alphabetical order, by
clicking the Sort button, as described below.

There are two buttons at the top of this Outline Window tab:

n Auto-Expand/Collapse turns on the automatic expansion of the symbols

matches. When this button is enabled (depressed), changing from one
document to another will close one list of symbols and open another for the
newly current document. When the button is not depressed, you control when
the symbol lists open and close.

n Sort alphabetically sorts the list of symbols in the window when the button
is depressed.

282 11- Search and Replace and Navigational Tools

Outline Scanning
The Outline Window has a threaded background scanning process that runs after
one second of idle time. It scans the opened source files to detect new symbols to be
added to the view. The updating only occurs when changes have been made, but
the detect scan is almost always running. Available parsers can be enabled in the
Outline Parsers dialog, accessed by clicking the Symbol Patterns button in the
Tools|Customize|Language|CodeSense dialog. A check box to indicate if the
symbol type should be displayed precedes each parser name. When you select a
parser name, the settings in the dialog reflect those for that particular parser name.
More marked checkboxes mean more displayed symbols (assuming the parsers are
legitimate), and more background scanning.

If you have all the parser check boxes for a particular file type marked, you might
experience a delay when opening or closing files because of the scan process. If you
do, try disabling the Auto-Expand/Collapse button in the Outline Window, or
disabling some of the parser types (see configuration section below).

Symbol Parsers
Symbols, as you recall, are any element of the code for which a parser has been
written. Typically, these are Functions, Classes, Macros and the like. Symbol Parsers
are Regular Expression patterns that parse code-elements matching an expression.
Patterns can be developed using the CodeWright's Search mechanism.

You can add Symbol Parsers by creating the proper Regular Expression pattern, and
inserting it in the Outline Parsers dialog (access by pressing the Symbol Patterns
button in Tools|Customize|Language|CodeSense). The online help in the Outline
Parsers dialog provides information on configuring each of the items in this dialog,
and provides some tips on creating Regular Expressions. Regular Expressions are
also described, under the topic Regular Expressions in this chapter. Files are scanned
using these parsers.

Use the following steps to make a Symbol Parser:

1. In the Tools|Customize|Language|CodeSense dialog, highlight the file type of
the file for which the parser is being made or viewed.
2. Click the Symbol Patterns button.
3. View the box that lists the parser names or types of symbols recognized by the
current symbol parser. If the box is empty, there is no parser for the selected file
type extension.
Example: If .CPP is selected as the file type, there should be three parser
name entries in the Parser Type list box: Function, Define, and
Class.
4. Click Add. The Add Parser Name dialog comes up.

11- Search and Replace and Navigational Tools 283

5. Give the new parser a name and choose a type (i.e. function, prototype,
procedure, etc.) from the Type drop-down list. The type determines what icon
CodeWright uses in the Outline Window.
6. Click OK.
7. Back in the Outline Parsers dialog, highlight the new parser.
8. Type or paste an appropriate regular expression in the Pattern box. (The string
provides feedback, indicating whether the selected regular expression is OK or
Illegal.)
9. Choose or enter the characters that should be found by the parser in the
Keyword Characters section.
10. Use the Keyword Position options to indicate whether characters to the left or
right of the indicated cursor position (\c in the regular expression pattern)
should be displayed in the Outline and Symbols Windows.
11. Click OK.

The new symbols should appear in the Outline Window when files of the
appropriate file type are opened in CodeWright.

Symbols Database
As mentioned, parsers used to match and display symbols are defined in the Outline
Parser dialog accessed by clicking the Symbol Patterns button in the
Tools|Customize|Language|CodeSense dialog. They are specific to the selected file
type extension. Any symbols that are parsed are subsequently stored in the symbols
database.

The symbols database location is defined in the Project|Properties|Directories

dialog. By default this database is located in the main CodeWright directory. More
than one symbols database can be used by changing the name/location of the file. To
maintain separate symbols databases for individual projects, put the full project path
for each Symbols database in the Symbol file field of the Directories dialog.

There are two check boxes that apply to the symbols database file defined in the
Project|Properties|Directories dialog. The check boxes are available when the
Symbol File field is selected. The check boxes have the following functions:

284 11- Search and Replace and Navigational Tools

n When the option Auto-Update Symbol Database is selected, CodeWright
automatically scans open files and files that are members of the current project
for symbols using the rules defined for that extension.
This is done as a background task. If you cannot spare the processor time for
this task, even with the Parser Priority set to Low on the Tools|Customize|
CodeSense|General|Advanced Options dialog, take the check out of the box. If
you do this, you should note that the information in the Symbols tab of the
Output Window will likely be out of date.
If this option is not marked, you may still update libraries via the Rescan and
Update buttons on the CodeSense Global Configuration dialog
(Tools|Customize|CodeSense|General).
n When the option Show Definitions in Symbols Tab is selected, automatic
detection and scanning takes place for updating the Outline/Symbols Windows
and the symbols database.

Popup Symbols Menu

Right-click on the Symbols tab of the Output Window, or on a filename in the
Outline tab of the Project Window, to display a popup menu with the following
choices:
n Rescan Outline Symbols updates the information in the symbols database for
the file currently selected in the Outline Window.
n Rescan Symbols DB deletes the database and rebuilds it. This is performed as a
background task.
n Compact Symbols DB selection optimizes the symbol database for the current
project by deleting unused records. This is performed as a background task.

Objects Window
The Objects Window is a tab on CodeWright Project Window by default. It is used to
view and browse code. It displays a hierarchical view of C/C++, C# and Java
objects/symbols that are associated with the name you typed in the window’s
Identifier box. The objects in the hierarchy can consist of C/C++, C# and Java
classes, functions, data, macros, types, etc. as they apply to the language being used.
Each object-type has its own image, as displayed in the Filter/Legend dialog (see the
topic Filter/Legend Dialog in this chapter).

11- Search and Replace and Navigational Tools 285

Display an Object Hierarchy
The Objects Window gets its information from CodeSense, so the same information
sources that are used for CodeSense must be available for the Objects Window
before it will work (see the topic Objects Window and CodeSense in this chapter). With
that in mind, there are two ways to display an object hierarchy in the Objects
Window: by typing an identifier in the Identifier box, or by using the standard
popup menu. Those methods are described in the next topics.
Note: To control the quantity of hits returned in the Objects Window,
adjust the Maximum Number of Hits slider on the
Tools|Customize|CodeSense|General|Advanced Options dialog.

Type an Identifier to Display an Object Hierarchy

To display an object hierarchy by typing in an identifier, do the following:
1. Type the name of an object/symbol in the Identifier box at the top of the
Objects Window. Use the asterisk (*) wildcard character to match any
characters to the right of the asterisk (e.g., CMain* will match all symbols
that begin with 'CMain'). If necessary, click the Ignore Case button to
make the window case insensitive to the characters in the Identifier box
(the button will appear depressed).
Note: Typing only an asterisk (*) will result in a search for all symbols,
but will be restricted to the project database. If you want to
restrict a large search (e.g. C*) to the project database and open
documents, click the Include CodeSense Library Databases
button to turn it off (button will no longer appear depressed).

2. Press E. A hierarchy will display.

Use the Right-Click Popup Menu to Display an Object Hierarchy

To display an object hierarchy by using the CodeWright right-click popup
menu, do the following:
1. Open a .C, .CPP, .CS or .JAVA file.
2. Right-click on, or select and right-click on, a symbol (class name, function
name, struct, etc.) in the open file. Depending on whether a selection was
made, you will see the following in the resulting popup menu:
n If a selection was made you will have the choice to Browse for
<selection> (exact match) or Browse for <selection>* (wildcard
match).
n If no selection was made you will have the option to Browse for
<symbol name> where <symbol name> is the name of the symbol
that the cursor is on.

286 11- Search and Replace and Navigational Tools

 Click on any of the above options to display an object hierarchy.

Objects Window

Using the Objects Window

The Objects Window can be used to view and browse C/C++, C# and Java objects/
symbols:
n Click on an object/symbol in the window to access the position in the source file
at which the symbol is defined.
n Right-click on a symbol in the Objects Window and choose Show References to
(Selected Symbol) to locate and define the functions, classes, etc. that call or use
the selected symbol.
n Right-click on a symbol and choose Show Symbols Called or Used by (Function
or Class Name) to display a call tree indicating the function(s) that the selected
symbol calls and/or the other symbol(s) that it uses.
n Hover the mouse cursor over an object/symbol's representative icon to display a
tooltip providing additional information about the object/symbol in question.
n Note that the Identifier box in the Objects Window will be case-sensitive if the
Ignore Case button is off (button is not depressed). Click the button on
(appears depressed) to make the window case-insensitive to the string that is
typed in the Identifier box.

11- Search and Replace and Navigational Tools 287

Objects Window and CodeSense
The Objects Window gets its hierarchy information from CodeSense. Therefore, one
or more of the following must be true before any information will display:
n One or more C/C++, C# and/or Java files must be open in CodeWright.
n A project containing C/C++, C# and/or Java files must be open in CodeWright.
n One or more legitimate CodeSense library databases must be listed and checked
in the CodeSense Global Configuration dialog (Tools|Customize|CodeSense|
General). If the correct library is not listed in the dialog, it can be added.
n One or more C/C++, C# and/or Java files must be listed in the Symbols
Window Edit Symbol File List dialog.

See the topic CodeSense in the chapter Editing and Printing for more information.

Objects Window Popup Menu

If you right click on an object in the Objects Window you will get a popup menu
with the following options:
n Copy Symbol to Clipboard - Copies the name of the selected symbol from the
Objects Window to the clipboard or scrap buffer (e.g. CUAFLAG_LINE_ENDS).
n Copy Definition to Clipboard - Finds and copies the definition of the selected
symbol to the clipboard or scrap buffer. (e.g. For the symbol
CUAFLAG_LINE_ENDS, the definition #define CUAFLAG_LINE_ENDS
0X00000200L would be copied.)
n Show References to (Selected Symbol) - Displays all references to the selected
C, C++, C# or Java symbol in a popup dialog. Allows you to preview each
reference by highlighting it on the dialog, and to go to the selected reference in
the source code.
n Show Symbols Called or Used by (Function or Class Name) - Displays a call
tree that lists and defines the function(s) that the selected C, C++, C# or Java
symbol calls and/or the other symbol(s) that it uses. This is also available from
the right-click menu in an Edit window.
n Sort Alphabetically - Sorts the objects/symbols alphabetically.
n Sort by Character Set - Sorts the objects/symbols by the ASCII values of the
characters in the name and according to the code page currently in use. This
allows the sort to respect locale-specific information (i.e. international
characters).
n Sort by Objects - Sorts by objects/symbol type.

288 11- Search and Replace and Navigational Tools

n Display by Definition - Displays objects/symbols by their definition. For
example:
MsgPopupPromptHistory(LPXSTR histName, LPXSTR prompt,
LPXSTR response)
n Display by Symbol name - Displays objects/symbols by name. For example
MsgPopupPromptHistory
n Filter/Legend - Accesses the Filter/Legend popup menu (described next).
n Show Members in Root - Shows both class detail and function detail if class and
function names are the same.
n Ignore Case - Toggles the Ignore Case setting on/off, telling CodeSense whether
or not to consider case when lookups are performed.
n Include CodeSense Library Databases - Forces the Objects Window to include
information in CodeSense Library databases when displaying a hierarchy. If
this is toggled off, searches are restricted to the project database and open
documents, speeding up the process of displaying hierarchies.
n CodeSense Editing Options - Accesses Tools|Customize|Language|
CodeSense.
n CodeSense Global Configuration - Accesses the CodeSense Global
Configuration dialog.
n Refresh Display - Displays the most current list of applicable objects/symbols
(refreshes the current query, maintaining tree expansion).

Choose the item Filter/Legend on the Objects popup menu to access the Filter/
Legend popup menu:

Filter/Legend Popup

11- Search and Replace and Navigational Tools 289

The Filter/Legend popup menu lists a set of object filters. Object filters control which
objects/symbols will display in the Objects Window. Unmark any filter to prevent
objects of that type from displaying. When filters are thus applied, the Filter/Legend
dialog button appears depressed.

Filter/Legend Dialog
One of the items on the Filter/Legend popup menu is Filter/Legend. It accesses
the Filter/Legend dialog.

Filter/Legend

The Filter/Legend dialog serves some of the same purpose as the Filter/Legend
popup menu, providing the same list of Objects filters. The dialog also provides
another set of filters labeled Access, that provide additional control over
Objects filters in the following ways:
n By filtering objects according to public, private, and protected access
attributes.
n By filtering objects that are non-members.
For example, if one wanted to see only public classes in the Objects Window,
they would mark the item Classes in the list of Objects filters, then mark the
item Public in the list of Access filters.
When using Objects and Access filters in the Filter/Legend dialog, keep in
mind the following:
n Marking or unmarking any of the Objects filters in the Filter/Legend dialog
will mark or unmark the same filter on the Filter/Legend submenu.
n At least one Access filter must be marked in order for any marked Objects
filters to display in the Objects Window.
n At least one Objects filter must be marked for any marked Access filters.
Otherwise the Access filters are meaningless, and objects will not display.

290 11- Search and Replace and Navigational Tools

 n When one or more Objects or Access filters are not selected on the Filter/
Legend dialog, filters have been applied and the Filter/Legend Dialog
button appears depressed.
n Use the buttons Select All or Clear All to select or clear selections for all
filters.

Symbols vs. Objects vs. Tags

CodeWright offers four browsing features (Symbols, the Objects Window, Tags and
Browse), all of which have been discussed up to this point. Each browsing method
offers its own advantages, some of which are listed next.

Pros and Cons of CodeWright Browsing Tools

The following items describe some pros and cons of the different browsing tools
available in CodeWright:
n The CodeWright Browser can use Microsoft .BSC files that are produced when
code is compiled in Microsoft's development environments.
n The CodeWright compiled Tags databases (.PTG files) provide more limited
code-information, but can be built from within CodeWright.
n Both the .BSC and .PTG files are displayed in the Browse tab of the Output
Window. The files are displayed in a graphical tree format with mouse-click
access.
n Symbols do not have to be compiled. They are created in real-time, instantly
displaying symbols as changes are made to edit-buffers.
n The Objects Window contains more extensive C/C++, C# and Java
information, as provided by the CodeSense library databases that are listed in
Tools|Customize|CodeSense|General.
n Symbols are displayed in graphical tree -format with mouse-click access to their
respective file locations.
n Symbols are interactively customizable, offering the ability to display more than
just the pre-defined elements in the Outline and Symbols Windows.
n Symbols are available for a wide variety of programming languages, and again,
they are customizable so that more can be added for new languages if
necessary.

11- Search and Replace and Navigational Tools 291

Bookmarks
CodeWright bookmarks are handy for navigating code. Like any bookmark, they
reserve current positions in documents so that it is easy to return to those positions
when necessary. The following paragraphs talk about using the Bookmarks feature.

Global and Local Bookmarks

Bookmarks are used to facilitate movement from one position to another, within and
between documents. There are both local and global bookmarks. Local bookmarks
are known only within the document in which they were defined. Global
bookmarks, on the other hand, are recognized from any document. Global and local
bookmarks can be given names, as well as numbers, to help remember what the
purpose of the bookmark was.

Graphical Bookmark Images

If Show visible bookmarks is turned on in Tools|Customize|Environment|
Bookmarks (described below), graphical images representing bookmarks are placed
in the left margin of the document in which the bookmarks were placed. There are
two separate bitmaps: one for global bookmarks and one for local bookmarks .

Setting and Removing Bookmarks

Bookmarks can be set and removed in a number of ways:
n The Document menu has a Mark option that sets a global mark at the cursor
position. The graphical mark is placed in the left margin of the document.
n The various keymaps available in CodeWright each have respective keystrokes
for setting bookmarks. For example, in CUA and Visual Studio .NET, the
keystroke for setting a global mark is [Ctrl]-[0-9]; in BRIEF it is [Alt]-[0-9].
n Right-clicking the mouse at the far left margin of a document displays a popup
menu with the following options, two of which are used for setting marks:
3 Set a Global Mark: Sets a global bookmark.
3 Set a Local Mark: Sets a local bookmark.
3 Go to Bookmark Dialog: Accesses the Define a Marked Location dialog,
where you can define new bookmarks for the current document or modify
the name and/or location of existing ones.

292 11- Search and Replace and Navigational Tools

Bookmarks Tab
On the Bookmarks tab of the Tools|Customize|Environment dialog you can set the
visibility and naming attributes for local and global bookmarks. Press the View
Database Content button to view and delete bookmarks from the Bookmarks
Database.

The desired attributes for both local and global bookmarks are selected in the
Bookmarks tab:
n When bookmarks are visible (i.e. Show visible bookmarks options are turned
on), a marker appears in the left margin of each line that has a bookmark. (As
described in the section Graphical Bookmark Images.)
n When prompting is selected, a prompt for an optional bookmark name appears
when a bookmark is dropped. This option only applies for bookmarks that are
dropped using the applicable key combination for the current keymap.
n If you want to save both named and unnamed bookmarks in the Bookmark
Database when a file is closed (during a session or at the end), be sure to mark
Save named marks in database and Save unnamed marks in database in the
Local Bookmarks and/or Global Bookmarks group.
n The options in the Mark Database section control how saved bookmarks are
maintained in a database for future sessions.
n The Save Current Position and Restore Current Position options save and
restore the cursor position as it was when the bookmark information was last
saved in the database. These positions are maintained in the Bookmark
Database. The 'current position' entries in the database are never deleted unless
Delete entries older than threshold is checked, in which case the current age
specification applies.

Bookmarks Window
The Bookmarks Window is a tab on the Project Window (by default). It gives a view
of local and global bookmarks defined in your documents. Clicking on a bookmark
in the window moves you to the bookmark's document and location. Right-click on
a bookmark in the Bookmars Window to change its name and/or location on the
Modify Mark Attributes dialog.

The contents of the bookmarks database, and other bookmark options are found/
accessed on the Bookmarks tab of the Tools|Customize|Environment dialog (refer
to the previous section).

11- Search and Replace and Navigational Tools 293

Bookmarks Window

Global Bookmarks
Global bookmarks are listed on the Bookmarks Window under the Global
Bookmarks heading, regardless of the document they are located in. The entry for
the global bookmark shows:
n The bookmark number,
n The bookmark name, if one was given,
n The name of the document in which the bookmark is found.

Local Bookmarks
Local bookmarks are listed in the Bookmarks Window under the name of the
document in which they are found. The entry shows:
n The bookmark number,
n The bookmark name, if one was given.
Double-click on the document heading to make it the active edit buffer.

"Other Documents" Node

The Other Documents (not loaded) heading at the bottom of the Bookmarks
Window lists files that are not loaded but have entries in the Bookmark Database.
Each file under the Other Documents heading lists individual marks associated with
the file and the datestamp of the mark. Double-clicking on one of the files loads it.
The file will be grayed if it does not exist (and the double-click action described will
not occur).

294 11- Search and Replace and Navigational Tools

Auto-Expand/Collapse
When the Auto-Expand/Collapse button at the top of the Bookmarks Window is
depressed, changing from one document to another will automatically close one list
of bookmarks and open another for the newly current document. This saves a step
when you want to view a list of bookmarks. When the button is not selected, you
control when the bookmark lists open and close.

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 related documents or
spreadsheets, run macros or just to make notes. To any other editor, it is still just a
straight text file, and because the buttons are placed in comments, source code files
compile as they normally would. Button Links are a navigational tool in that they
maintain the current position of the file while the link goes to a different position or
file.

How it Works
You select the type of link and the text that will appear in the button. CodeWright
uses this information to create an index entry for that text, and places it into the text
file with a special 3-character prefix and suffix. Comment prefixes and suffixes are
used as you indicate. The index entry refers to an entry in a database that indicates
what the button link does.

What you See

When you have turned on the View Links option in Tools|Customize|View
Themes, you will see a 3D-style button containing the text you specified, and a
notation indicating what type of link it represents. Click on the button and the
associated action is performed.

Defining Buttons
Button Links are defined in the Insert Link dialog, which is accessed by clicking
Insert Link on the Edit menu. Enter your button’s text (which must be unique),
select the link type, and enter the appropriate text to be associated with the button.
The nature of the associated text depends on which link type you select.

Using buttons you can perform six different categories of actions:

n Templates -- Templates allow you to insert text, prompt, move the cursor, or
execute a series of actions. For Templates, the associated text is the contents of a
template to execute, such as those supplied to the ExtExpandTemplate
function. (For more information about CodeWright templates, see the chapter
on Editing & Printing.)

11- Search and Replace and Navigational Tools 295

n Macros -- Macros allow you to execute any API command that is available
interactively. The text associated with a Macro Link is the function call. It is
limited to a single function.
n Document – The Document Link allows you to run the program associated with
a file type, to view or modify that document. The document might be a
bitmapped diagram or a word processor file. In this case, the text associated
with the button is just the filename of the document.
n Application – The Application Link lets you define any arbitrary command line
to be executed when the button is pressed.
n URL -- URL Button Links jump to a specified Web Address (URL) by issuing a
shell command. The web page comes up in your default browser. This type of
link could also be used for other shell commands.
n Note -- Popup Note Links come in two flavors: standard notes and “to do”
notes. These two types of notes are essentially the same. Providing two link
types for notes, however, gives the buttons a different appearance and allows
you to sort “to do” notes separately from other notes, when viewing the list of
defined links.

296 11- Search and Replace and Navigational Tools

12- Checking and
Reformatting Files
When you are finished editing a difference, it may be necessary to check and
reformat the file. You might also wish to compare and/or merge the finished file
with previous versions. For these purposes, this chapter covers the following
formatting and file-checking tools:
n Differencing
n Merging
n Format Source
n Spell Check

Differencing
CodeWright has a fairly sophisticated differencing feature that can be used directly
from within the editor; it is not an external application. The CodeWright
Differencing feature offers several advantages over other differencing utilities:
3 You can edit text files and undo changes in Difference Window documents
much as you would in a regular edit window by enabling Edit mode . Edit
mode also has additional toolbar buttons for moving text between and within
windows. When you edit a document, the edited part of the document is
automatically re-compared.

3 From View mode, press to open the file that has focus and jump to the cursor
position.
3 You can identify changes and problems faster in your non-text files (.exe., .gif,
.bin, etc.) by differencing on a byte-by-byte binary basis, rather than line-by-line.
3 The Difference Controls allow for easy navigation between differences.
3 Entire directories can be differenced at one time.
3 You can generate metrics reports summarizing the Text File, Binary File or
Directory differences.

12- Checking and Reformatting Files 297

If your editing requirements include frequent comparisons of files, the CodeWright
Differencing feature offers an ideal solution.

CodeWright differencing can be done either side-by-side or interleaved. The

following sections describe these two differencing methods.

Interleaved Differencing
The CodeWright Interleaved comparison merges two documents and places them
into a new, separate document that can be edited and saved apart from the original
documents.

Text Difference Analysis Dialog for Interleaved Differencing

All differencing in CodeWright can be initiated from the File|Difference submenu.
To do an interleaved difference for two text files, choose the Text Files menu item,
then select the Interleaved option.

Text Difference Analysis (Interleaved)

Note: When the Interleaved option is marked, the Show Sections, Copy
Sections, Intraline, and Words options in the dialog will become
disabled (those options are specifically related to Side-by-Side
Differencing).
Do the following in preparation for using Interleaved differencing:
Note: These options also apply to Side-by-Side Differencing, described later
in this chapter.

298 12- Checking and Reformatting Files

1. Set the desired differencing options. The Compressed, Ignore Case and Ignore
Whitespace options are available, and provide the following functionality:
n Compressed—displays only the parts of the files that are different.
n Ignore Case—disregards any differences in case between the documents.
n Ignore Whitespace: Leading/trailing—ignores tabs and spaces at the start
and end of a line.
n Ignore Whitespace: Between words—ignores tabs and spaces between
characters inside the line.
n Ignore Whitespace: EOLs—ignores end-of-line character changes. This
includes EOL type changes (e.g. DOS to Unix EOL) and well as EOLs
inserted or deleted inside lines. (For Side-by-Side Differencing, deleted
lines will display in the Difference Window, but the Next/Previous buttons
will ignore them.)
2. Select from the File and Document radio buttons to determine what files will be
displayed when the Browse button is pressed. (The Browse button is used to
browse for files to be compared.)
n If the File radio button is on, the files displayed will be files that reside
anywhere on your system.
n If the Document radio button is on, the files displayed will be those that are
loaded in CodeWright. You may even choose to difference untitled buffers
by selecting them from the document list.
3. Choose the files to be compared. Two files are needed when doing a difference,
a Reference and a Target file.
n The Reference file is normally used as the basis of comparison. It is usually
the older of the two files. If comparing the current file with the same file on
disk, just press the Original File button and its name will be inserted into
the Reference field.
n The Target file is the file to which the Reference file is compared. It is
usually the newer of the two files being compared. If comparing the
current document with the reference, just press the Current Document
button, and the appropriate filename will be inserted in the Target field.
4. The Default Names section offers two features that help reduce the number of
steps needed to browse for the files that will be differenced. Choose from the
following:
n When the Current Document radio button is selected, the files displayed in
the Reference and Target fields will default to the document that is
currently loaded in CodeWright.
n When History Entries is chosen, the files in the Reference and Target fields
will default to the last files chosen in the Text Difference Analysis dialog.
5. Press OK to initiate the differencing.

12- Checking and Reformatting Files 299

The differences will be displayed in a separate, interleaved document in
CodeWright. The interleaved document is described next.

Interleaved Document
The title displayed in the interleaved document will be a combination of the names
of the Target and Reference files.
Example: If two files, FOO1.C and FOO2.C, are being compared using the
Interleaved option, the title of the resulting interleaved window
would look something like: FOO1.C->FOO2.C
The resulting interleaved document contains lines from both documents:
n The lines that are the same in both documents will have normal coloring in the
interleaved document.
n Lines that have been added to the Target file will be preceded by plus signs (+).
Lines that have been deleted will be preceded by minus signs (-). The added
and deleted lines will also be displayed in different colors from each other and
the rest of the text.
n An exclamation point (!) will precede those lines that differ in white space only,
if options to ignore white space have been chosen.

Side-by-Side Differencing
The Side-by-Side Difference is shown in a separate tab of the CodeWright Output
Window (labeled Difference). Editing is allowed in the Side-by-Side Difference
Window (in Edit mode), with buttons provided for navigating differences.

Text Difference Analysis Dialog for Side-by-Side Differencing

To compare two text files using CodeWright Side-by-Side differencing, go to the
File|Difference|Text Files dialog and mark the Side-by-Side radio button.

Text Difference Analysis (Side-by-Side)

300 12- Checking and Reformatting Files

To perform Side-by-Side Differencing, complete the following steps:
1. When Side-by-Side is marked, four options will be made available that were not
available for the Interleaved difference: Show Sections, Copy Sections,
Intraline, and Words. These options are specifically related to the Side-by-Side
Differencing. Mark desired options according to the descriptions provided:
n Mark Show Sections to have differing sections of the two files being
compared completely highlight. ChromaCoding will still display in the
foreground based on current settings. If Show Sections is not marked, only
left margins of the portions that are different are highlighted.
n Mark Copy Sections to control how lines can be edited on either side of the
Difference Window. If it is marked, whole sections can be deleted or copied
from one side to the other. If it isn't marked, only one line at a time can be
copied.
n Mark Intraline to show the parts of the lines that are different, rather than
just flagging the whole line as being different.
n Mark Words to keep the Intraline option from displaying every single
character that differs in either document. It limits the display to show only
the whole words that differ.
2. Complete the Compressed, Ignore and Restore on Startup options in the same
way as for an Interleaved Difference operation (refer to the previous topic
Interleaved Differencing).
3. Choose the files to be compared for a Side-by-Side Difference using the same
process used for Interleaved Differencing. The Browse buttons are controlled by
the File and Document radio buttons, and the default Reference and Target
filenames are controlled by Current Document and History Entries radio
buttons in the Default Names section of the dialog.
4. When you have set the File|Difference|Text Files dialog with the desired files
and settings, click OK to display the files, side by side, in the Difference tab of
the CodeWright Output Window.

Side-By-Side Difference Window

The Side-by-Side Difference Window shares common vertical and horizontal
scrollbars to facilitate synchronized scrolling between the two documents. Note the
following characteristics of the Side-by-Side comparison:

12- Checking and Reformatting Files 301

n The Side-by-Side Difference Window uses colors in the left margin to mark the
points where the two files differ (if the Show Sections option has been marked,
the background of differing text-sections will also be highlighted).
3 With the standard color scheme, inserted lines will be marked with red,
modified lines are marked with blue, and deleted lines are marked with
black in the left margin.
3 When Intraline Differencing is turned on, you will also see the differences
within the line marked as blue or modified.
3 Lines that are common to both documents receive normal text colors. This
includes lines that you have copied from one file to the other.
3 You can set colors in the side-by-side comparison to suit your preferences
on the Colors tab of the Tools|Customize|View Themes dialog. Select
“Output Window” in the Customize dialog navigation tree. In the Screen
Element list, scroll down to the Difference section. For each element,
choose Foreground, Background or Both in the Use Color group and make
the desired color settings.
n You will see these three patterns of text in the two windows:
3 Normal text in both windows.
3 Text in one window, blank line in the other.
3 Marked text in both windows.

Side-by-Side Difference Window

View Mode
When you are presented with the Side-by-Side Difference Window, it is initially
in "view only" mode. This mode allows you to see the differences, but not to
change the contents of either document. You may go to a location in either
document and edit the file in the normal editing window, but this will not be
reflected in the Differencing window. The window can be changed to "Edit"
mode by clicking on in the Side-by-Side Difference Window's toolbar.

302 12- Checking and Reformatting Files

 View Mode Toolbar

There are several additional buttons on the "View mode" toolbar that are worth
describing. The buttons are described next (in order, from left to right).

n The Question Mark accesses Help for the Difference Window.

n The Print Side-by-Side Difference button displays a modified Print

dialog that allows you to print the Reference and Target files side-by-side,
in a manner similar to “two-up” mode. Refer to the topic Side-by-Side
Difference Printing, later in this chapter.

n The Create Difference Metrics Report button displays the Create

Difference Metrics Report dialog, where you can track and analyze file or
directory differences by generating metrics reports. Refer to the topic
Metrics Reports, later in this chapter.

n The Recompute Differences button prompts to save the files contained

in the Difference Window, saves them if desired, then recomputes the
differences between the two files with the latest changes.

n The Previous Changed File and Next Changed File buttons

display a Side-by-Side Difference on the previous/next file with differences
in the directory tree. They are enabled once a Directory Differencing
operation has been performed (from the File|Difference|Directories
menu item). All different files are included regardless of whether filtering
causes them to appear in the tree on the Tree Difference Window.

n The Go To File and Position of Text Cursor button loads the file from
the window in which the cursor sits into a CodeWright buffer. The cursor is
positioned at the corresponding location, preparing the file for direct
editing.

n The Change to Edit Mode…button changes the Side-by-Side Difference

Window to editing mode (for Text files). The side-by-side Edit mode is
described in the next section.

n The Side-by-Side Difference Options button displays an Options

dialog that allows you to modify differencing settings on the fly; complete
fields in the Text Files, Binary Files or Directories group as appropriate.

12- Checking and Reformatting Files 303

 Changing these options will also affect the state of the corresponding
options in the Text Difference Analysis, Binary Difference Analysis and
Directory Difference Analysis dialogs.
The Side-by-Side Difference Options dialog also lets you toggle between
View and Edit mode (for Text files), save Difference Window contents
between sessions, or split the Difference Window horizontally, with the
Reference file on top and the Target file beneath.

Side-by-Side Difference Window (Split Horizontally)

n The Difference Control (triangular arrow) buttons are are used to

view the various areas of difference between the two documents:

3 Press the far right arrow to jump to the last difference in the two
files. Double-click this arrow to move to the bottom of the files.

3 Press the far-left arrow to jump to the first difference. Double-

click this arrow to move to the top of the files.

3 The left and right arrows in between go to the immediate next

and previous differences, if there are any.

Edit Mode
Toggle to Edit mode to edit text files directly in the Side-by-Side Difference
Window. Edit mode allows you to edit and undo changes in Difference
Window documents much as you would in a regular edit window. Edit mode
also has additional toolbar buttons for moving text between and within
windows.
Note: When you edit a document, the edited part of the document is
automatically re-compared. When you insert lines into one side
of the Difference Window, "deleted" lines are inserted into the
other side to keep both views synchronized.

304 12- Checking and Reformatting Files

 Once you are in Edit mode, you will see the following toolbar:

Edit Mode Toolbar

The Edit mode buttons are described next (in order, from left to right).

n The Question Mark button brings up Help for the Side-by-Side

Difference Window.

n The Save Changes button saves the changes made to the current
compared document.

When you give focus to the document on the left in Edit Mode, the status
line message File: Reference will display; for the document on the right, the
message is File: Target. If this message is followed by an asterisk (e.g. File:
Reference*), you have unsaved changes (e.g. you copied lines from one file
to the other).

To save those changes, give focus to the appropriate file (in the example

given, this is the Reference file) and press on the Difference Window
toolbar. Note that lines marked as deleted are not present in the saved file.

n The Copy Changes to Document button copies the edits in the current
Difference Window to the corresponding document.

n The Copy Selected Lines to Left/Top Window button copies inserted,

modified or deleted lines or sections from the right pane of the Difference
Window to the left (or such lines from the bottom pane to the top pane if
the window is horizontally split).
3 If “deleted” lines in the right-hand pane or bottom pane are selected,
the lines are removed from both documents.
3 If no lines are selected, the current line is copied.
3 If the Copy Sections option was selected when the difference
operation was invoked, the current section is copied.
After the copy, the selected lines are part of the text common to both files
and receive normal text colors. If all the lines are already part of the text
common to both, the operation fails.

12- Checking and Reformatting Files 305

 n The Copy Selected Lines to Right/Bottom Window button copies
inserted, modified or deleted lines or sections from the left pane of the
Difference Window to the right (or such lines from the top pane to the
bottom pane if the window is horizontally split).
3 If “deleted” lines in the left-hand pane or top pane are selected, the
lines are removed from both documents.
3 If no lines are selected, the current line is copied.
3 If the Copy Sections option was selected when the difference
operation was invoked, the current section is copied.
After the copy, the selected lines are part of the text common to both files
and receive normal text colors. If all the lines are already part of the text
common to both, the operation fails.

n The Delete Selected Lines button deletes the selected lines in a

window. The deleted lines are not removed, but rather are marked
“deleted” and left empty. You may wish to do this in preparation to moving
lines in the adjacent window. Add as many deleted lines as you like. They
will not show up in the saved file.

n The New Deleted Line button inserts newly "deleted" blank lines in
both windows. You may wish to do this in preparation to shifting lines up
or down. Once again, add as many deleted lines as necessary. They will not
show up in the saved file.

n The Move Selected Lines Up button moves the selected line up one
line. If no lines are selected, the current line is moved. To use this button,
there must be a deleted line above, or the line shifted must be a deleted
line.

n The Move Selected Lines Down button moves the selected line down
one line. If no lines are selected, the current line is moved. To use this
button, there must be a deleted line below, or the line shifted must be a
deleted line.

n The Change to View Mode button toggles the window back to View
mode, as described in the topic View Mode, in this chapter.

n The Side-by-Side Difference Options button displays an Options

dialog that allows you to modify differencing settings on the fly, toggle
between View and Edit mode (for Text files), save Difference Window
content between sesions, or split the Difference Window horizontally, with
the Reference file on top and the Target file beneath.

306 12- Checking and Reformatting Files

 n The Difference Control buttons are are displayed on the top of the Side-
by-Side Difference Window as 4 triangular black arrows that point to the

left and right . They are used to view the various areas of difference
between the two documents.

3 Press the far right arrow to jump to the last difference in the two
files. Double-click this arrow to move to the bottom of the files.

3 Press the far-left arrow to jump to the first difference. Double-

click this arrow to move to the top of the files.

3 The left and right arrows in between go to the immediate next

and previous differences, if there are any.

Keystroke Shortcuts
There are three key sequences for moving back and forth between the two
panes of the Side-by-Side Difference Windows:

n CSn, moves to right window (next).

n CSp, moves to left window (previous).
n CSo, moves to other window (next & wrap).
You can also press C/ to toggle between View and Edit mode (for Text
files).
Key sequences for the Difference Window can be customized using the function
CWDiffKmapAssign in the [KmapAssign] section of CWRIGHT.INI.

Side-by-Side Difference Printing

A Print button is available from the View mode of the Side-by-Side Difference
Window when both sides of the Window are in the same mode.
A modified Print dialog entitled Print - Side by Side Difference displays. Printing
the contents of the Side-by-Side Difference Window is similar to printing a regular
document in two-up mode, except that the left side will contain the Reference
document/file, while the right side will contain the Target document/file.
Differences between the documents are shown as follows:
n Lines that are "deleted" in one side will display as a minus sign only.
n Lines that are "added" on one side will print, preceded by a plus sign.
n Lines that are modified will be preceded by an asterisk.

12- Checking and Reformatting Files 307

Binary File Differencing
CodeWright also supports file differencing on a byte-by-byte binary basis, rather
than line-by-line. This is especially useful for finding changes and problems in non-
text files, such as .exe., .gif, and .bin files.

To set this up, select Binary from the File|Difference submenu. The Binary
Difference Analysis dialog displays:

Binary Difference Analysis Dialog

Choose the files to be differenced as you would Text files. Unique settings include
the following:
n Min. Bytes per Match: Select a value in the Minimum Bytes per Match field to
ignore between 3 and 16 matching sequences of bytes. Since some files have the
same small sequence of bytes thousands of times, the algorithm might have to
test millions of possible matches between those small sequences.
Pick a larger size to allow the difference operation to run faster, or a smaller size
for higher differencing quality.
n Columns per Line and Bytes per Column: These fields allow you to control the
format and width of the output lines on the Binary Difference Window. The
following image uses the settings shown above of 4 columns per line and 4 bytes
per column.

308 12- Checking and Reformatting Files

 Binary Difference Window

The functionality on the Binary Difference Window mirrors that of the standard
Side-by-Side Difference Window, except that Edit mode is not available.

Directory Differencing
Directory Differencing (also referred to as "tree differencing") allows you to specify
two directories for comparison. Use the Directory Difference Analysis dialog to
request directory differencing. To access the dialog, select File|Difference|
Directories, or right-click on the Difference tab of the Output Window and select
Difference Directories.

CodeWright takes each file in the Reference directory and searches for the same file
in the Target directory. Check the box Include Subdirectories to include all
subdirectories of the Reference Path and Target Path in the directory comparison.

Results from the Directory Difference Analysis dialog are displayed on the Tree
Difference Window (found on the Difference tab of the Output Window). You can
also run a Directory Difference Report that describes the results. Refer to the
following sections.

Directory Difference Analysis Dialog

The Directory Difference Analysis dialog appears as follows:
Directory Difference Analysis Dialog

12- Checking and Reformatting Files 309

The following settings determine which files and directories are included in the tree
directory in the Tree Difference Window:
n Reference Path: Enter the path of the first directory of files to be compared, or
press Browse to look for a directory on the Select the Reference Directory
dialog. Typically the Reference directory will contain older, unchanged versions
of a set of files.
n Target Path: Enter the path of the second directory of files to be compared, or
press Browse to look for a directory on the Select the Target Directory dialog.
Typically the Target directory may contain newer, edited versions of a set of
files.
n Include Subdirectories: Check this box to include all subdirectories of the
Reference Path and Target Path in the directory comparison.
n Scope: In the Scope field, enter a semicolon-delimited list of wildcard patterns
to define which files are included in the directory differencing. If no Scope is
entered, all files are included.
3 Check the option Exclude files matching scope to exclude files matching
the Scope from Directory Differencing instead. If the option is unchecked,
files matching the Scope will be included.
n Ignore: Case: Check this box to eliminate directory difference results due to
differences in text case only.
n Ignore: Whitespace: Check this box to eliminate directory difference results due
to differences in whitespace only. This includes leading/trailing whitespace,
whitespace between words, and whitespace found at the end of lines.
n Clear Current File Differences: Mark this option to remove existing
differencing results from the Output Window when a Directory Difference
operation is performed. If there are unsaved changes to the file differences, you
will be prompted to save them.
n Show Identical Files with Changed Time: Check the option Show Identical
Files with Changed Time to include files on the Tree DIfference Window that
are the same in both directories in all respects but their timestamp. Filenames
will be gray and preceded by the icon . Since the files are the same, you
cannot double-click to difference them.
n Show Identical Files: Check the option Show Identical Files to include files on
the Tree Difference Window that are the same in both directories. Filenames of
identical files will be gray and preceded by the icon . Since the files are the
same, you cannot double-click to difference them.

310 12- Checking and Reformatting Files

n Show Reference-only Files: Check the Show Reference-Only Files option to
include files on the Tree Difference Window that only exist in the Reference
directory. Reference-only files will display in boldface, preceded by the icon .
Since there is no file in the Target directory to compare it to, the file cannot be
differenced.
n Show Target-only Files: Check the Show Target-Only Files option to include
files on the Tree Difference Window that only exist in the Target directory.
Target-only files will display in boldface, preceded by the icon . Since there is
no file in the Reference directory to compare it to, the file cannot be differenced.
n Show Different Files: Check the Show Different Files option to include files
on the Tree Difference Window whose Reference and Target directory versions
are different. Files with differences are shown in boldface, and preceded by one
of the following icons:

3 The Reference File (on the left) has been revised more recently than the
Target File.

3 The Target File (on the right) has been revised more recently than the
Reference File.
n Show Directories with No Files: Check the Show Directories with No Files
option to display subdirectories of the Reference or Target directory on the Tree
Difference Window, even if the subdirectory contains no files. This option is
disabled if you have elected not to Include Subdirectories in the directory
comparison.

Tree Difference Window

The Tree Difference Window shows the results of comparing the files in two entire
directories, as requested on the Directory Difference Analysis dialog. A tree
directory that integrates the Reference and Target directories is provided; click on
any file in the tree that exists in both directories to show the specific differences in
that file in Side-by-Side Differencing format.

Right-click on any file in the tree to see a file-level context menu. Select the menu
option Copy File to copy the selected file from one directory to another.

A sample Directory Differencing in the Tree Difference Window is shown next.

12- Checking and Reformatting Files 311

Tree Difference Window (Difference Tab of Output Window)

Tree Differencing Toolbar

Press at the top of the Tree Difference Window to show or hide the directory
tree you generated on the Directory Difference Analysis dialog. When the
directory tree is hidden (the button appears raised), the files currently being
compared will expand to fill the Difference Window, revealing more of each file.

Use the Previous Changed File or Next Changed File button to display a
Side-by-Side Difference on the previous/next file with differences in the
directory tree.
All other toolbar buttons are the same as used for Side-by-Side Differencing.

Context Menus

When you right-click on the root node image at the top of a directory tree on
the Tree Difference Window, a context menu presents various options for
manipulating the tree directory display (Rescan Directories, Expand/Collapse
Subdirectories, etc.). You can also select/deselect the various “Show” options to
change the types of matches that are included in the tree.
When you right-click on a file within the directory tree, file-level options are
displayed on a context menu. You can Show Text Differences or Show Binary
Differences for the highlighted file pair, rescan the selected file(s), edit the
Target or Reference file, or copy the selected file to another directory.

Tree Directory Icons

The various file icons in the tree directory are defined as follows:

n This small tree image indicates the root node. The text shows the
Reference and Target directories used in the Directory Difference. Right-
click on this tree icon to display a directory-level context menu.

n or The subdirectory exists in both the Reference and Target

directories.

312 12- Checking and Reformatting Files

 n or The subdirectory exists only in the Reference directory.

n or The subdirectory exists only in the Target directory.

n The files are identical, except for their timestamp.

n The files are identical.

n The file exists in both directories, with the file in the Reference
directory being newer. Double-click on the item, or highlight and press
E, to run a Side-by-Side Difference on the file pair.
n The file exists in both directories, with the file in the Target directory
being newer. Double-click on the item, or highlight and press E, to
run a Side-by-Side Difference on the file pair.

n The file exists only in the Reference directory.

n The file exists only in the Target directory.

Metrics Reports
There are two dialogs that allow you to run reports reflecting various metrics for files
or directories being compared:
n Create Difference Metrics Report Dialog - Based on the last differencing
operation performed, run a metrics report for Text, Binary and/or Directory
differences.
n File Difference Metrics Dialog - Select files to difference, or specify a list of
directories to search, comparing any matching file(s) to the Target file. Use
additional settings to filter the report results.

Create Difference Metrics Report Dialog

You can use the Create Difference Metrics Report dialog to generate a report on Text
File, Binary File or Directory differences. Access the dialog as follows:

n Right-click on the smaller tree icon in the Tree Difference Window and select
Create Report from the popup menu.

n Press on the Difference Window toolbar.

n Press Cr with focus on either the tree directory or one of the files being
differenced.
The Create Difference Metrics Report dialog displays.

12- Checking and Reformatting Files 313

 Create Difference Report Dialog

You can generate reports in ASCII text (by default), or in HTML format. If you mark
Send to Browser, a temporary file is loaded into the browser; if you leave it
unchecked, you may view the report in the CodeWright HTML WYSIWYG editor.

Each report shows the filters used and summarizes the Text File, Binary File or
Directory differences found.
3 The Text File Difference Report includes the number of modified, inserted and
deleted lines, and summaries of section, line and character changes.
Note that the Modified (before) row indicates the number of modified lines in
the Reference file that contain code, comments or blanks, while the Modfied
(after) row indicates the number of modified lines in the Target file that contain
code, comments or blanks.
3 The Binary File Difference report quantifies sections that have been modified,
inserted or deleted, gives the size of each file in bytes, and indicates the number
of bytes that have been unchanged, modified or inserted.
3 The Directory Difference Report provides a summary count of changed files,
then details which files have changed between the Reference and Target
directories.
The reports are created by the API macros DiffTextReport, DiffBinaryReport, and
DiffDirReport, respectively, and can be modified by making changes to the macros
on the Tools|API Macros dialog.

Sample reports on Text Differences, Binary Differences, and Directory Differences

are provided next.

314 12- Checking and Reformatting Files

Text Difference Report Sample

Binary Difference Report Sample

12- Checking and Reformatting Files 315

Directory Difference Report Sample

File Difference Metrics Dialog

If you select Metrics from the File|Difference submenu instead, the File Difference
Metrics Dialog displays.

File Difference Metrics Dialog

This dialog allows you run the same metrics reports described previously, but adds
the following functionality:
n Reference/Target File: Allows you to enter or browse for Reference and Target
files to be compared in the difference report, rather than automatically using the
files compared in the last differencing operation. Also choose whether the
default names should come from the Current Document or History Entries.

316 12- Checking and Reformatting Files

n Reference Search Path: Allows you to specify a list of directories in lieu of a
reference file. Within those directories, CodeWright searches for the file with
the same root and extension name as the file targeted for comparison.
n Ignore options: Allow you to tailor your reports to ignore differences due to
Leading/trailing Whitespace; Whitespace Between words; EOL type changes
or EOLs inserted or deleted inside lines; and/or Case.

Using Difference Utilities

CodeWright has several difference APIs that allow the user to access the difference
features without using the mouse to go to the differencing dialogs. A list of these
functions can be found by doing a search for the keyword Differencing from
Help|CodeWright API Library. These functions are available for use from the
Tools|API Command key; for binding to custom keystrokes, buttons or menu items;
or for use in custom macros.

Merging
The Merge Files dialog allows you to specify three files for merge/comparison, and
the name of the file that is to contain the merged changes.

The Merge process is typically used to compare/merge the original (Base) file with
two modified versions of the file (Revision 1 and Revision 2), probably made by
different people. The new file that results (the Output File) will combine the
changes made in both revisions.
Note: You must specify all four filenames to enable the OK button. If you
only have an original file and one revision, the filename specified for
Base and Revision 1 can be the same; only the changes made in
Revision 2 would then be taken into account.

Using the Merge Files Dialog

To use the Merge Files dialog, select Merge on the File menu. The Merge Files
dialog displays.

12- Checking and Reformatting Files 317

Merge Files

Complete the following fields:

n Base File: The first filename you must enter is the name of the Base File. This is
the file from which the two revisions were derived. (Usually this is the oldest of
the three files.)
n Revision 1 and Revision 2: These files are both revisions of the Base File. It
does not matter which revision you specify as Revision 1 and which you specify
as Revision 2; the outcome of the merge is not materially affected. You may,
however, wish to establish a convention for your own use that Revision 1 is
"mine" and Revision 2 is "theirs", or that Revision 1 is older than Revision 2.
Note: For the Base File, Revision 1 and Revision 2 fields:
3 You may type in the name of the file, select the Browse button to
locate the desired file on disk, or select from the document list.
3 You may place the name of the file, from which the current
document was read, into this field by pressing the Original File
button (for the Base File) or the Current Document button (for the
Revision files).
3 The File and Document radio buttons allow you to specify
whether CodeWright should look for this file on disk, or whether
it has already been loaded into a document.
n Output File: In this box, specify the name of the file to contain the output
from the Merge. You may type in the name of the file or select the Browse
button to locate a file on disk. This merge file is always written to disk,
rather than just being placed into a document as the Differencing function
does. (Refer to the topic Differencing, in this chapter.)

318 12- Checking and Reformatting Files

 n Overwrite File: Check this box to tell CodeWright to overwrite a like-
named file when creating the output file.
If you do not check the Overwrite File option, and a like-named file exists,
CodeWright will prompt you for permission to overwrite the file. If you
don't give this permission, CodeWright aborts the merge.
n Edit File: Check this box to load the output file for viewing and editing at
the end of the operation.
n Synchronize Histories: Select this option to have CodeWright try to
anticipate selections from the history lists. When you select the Base file
from the history list, it automatically selects the Revision 1 and Revision 2
files that you used with that Base file last time.

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

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

The Merge function provides the following information:

n The first message from Merge identifies the conflict by number, names the Base
File, and indicates that the Base File was read from disk (file).
n The next message introduces the section of the Revision 1 file that conflicts with
Revision 2. It also gives the filename and indicates the origin of the file (File or
Document).
n The line or lines between this message and the next message from Merge are
taken from the Revision 1 file.
n After the lines from Revision 1 there is a message from the Merge function
introducing the corresponding section from Revision 2. Again Merge indicates
the filename and origin.
n Between this message and the "End Conflict" message are lines that need to be
compared with those from the Revision 1 file to see how the conflict should be
resolved.

12- Checking and Reformatting Files 319

On occasion, you may find that the section of conflicting lines from one revision or
the other contains zero lines. This is an indication that the lines were deleted in one
revision and changed in the other. (An empty conflict section will represent the
revision from which the lines were deleted.)

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

Removing Changes with Merge

Merge can also be useful when your development has been a linear progression,
rather than simultaneous revisions (branching).
Example: A bug may have been introduced from changes made at some point
in the past. Merge allows those changes to be removed without
abandoning the changes made since.
Usually, the Base File is the oldest of the files used in a Merge comparison, but it
need not be. When removing changes, the Base File is a middle revision that looks
backward at changes to be removed and looks forward at changes to be retained:
1. When selecting the Base File, select the first revision following the changes you
want to remove.
2. Next select the most recent revision of your file as Revision 1.
3. For Revision 2, choose the revision just before the change you want to remove
was introduced.

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

Format Source
For your C, C++, C#, Java, HTML and XML source files, CodeWright provides
functionality called Format Source (available from the Text menu). This allows you
to select a block of code and reformat it (this is also known as beautifying the code).
n For C, C++, C# and Java, selected code is reformatted based on a set of criteria
you have pre-defined on the Tools|Customize|Language|Format dialog.
n For HTML and XML files, selected code is reformatted based on standard
coding conventions for these languages. No additional formatting criteria are
defined on the Tools|Customize|Language|Format dialog.

320 12- Checking and Reformatting Files

Setting up Your Formatting Criteria
Before you can use the formatting capabilities within CodeWright, you must
establish certain criteria for CodeWright to use. This is done on the Format tab of the
Language dialog.

To access this dialog:

1. Select the Tools|Customize|Language dialog.
2. Highlight .C, .CPP, .CS or .JAVA in the Customize dialog navigation tree. The
criteria you set will only apply to the file type you have chosen here.
3. Click on the Format tab. The following dialog displays:

Tools|Customize|Language|Format

Complete fields in the following groups:

n Indentation: The settings in this group modify how many tab stops to
indent each item:
3 Broken expression – When an expression spans more than one line,
indicate how much additional indentation to give to the continuation
line or lines.
3 Broken parameter list – When a parameter list spans more than one
line, indicate how much additional indentation to give to the
continuation line or lines.
3 Other broken lines – When a statement other than an expression or
parameter list spans more than one line, indicate how much additional
indentation to give to the continuation line or lines.
3 Switch labels – Indicate how much additional indentation to give case
items (labels) within a switch statement. When using the Indented
block alignment style, the indent level for these case items is based on
the indent level of the closing curly brace.

12- Checking and Reformatting Files 321

 n Modify Space: These choices, when enabled, indicate how many spaces
you want surrounding certain items:
3 After Keyword – Indicate how many spaces you want after keywords
that are followed by a left parenthesis (e.g. "if", "while", "for", "switch",
"return" and the exception keywords).
3 Around Expression - Indicate how many spaces you want
surrounding an expression.
3 After Function – Indicate how many spaces you wish to have
following the end of a function name, preceding the opening
parenthesis.
3 Around Parameter List –Indicate how many spaces you want
surrounding a function call's parameter list.
n Enable block alignment: Tell CodeWright whether or not you want it to re-
align code blocks during reformatting. If enabled, you can select which
type of alignment to use. If disabled, CodeWright leaves block indentation
alone. (Refer to the online help topic Align Tab for a schematic of the
alignment options and popup help descriptions for each.)
3 Cuddle Else – Tell CodeWright whether or not to put the "else" portion
of an "If..else" construct on a line by itself or to "cuddle" it up next to the
closing brace it follows.
3 Align Function - Often, the braces that begin and end a function
definition do not conform to the same alignment rules as the braces
within a function. When that is the case, leave this checkbox
unchecked, and CodeWright will not alter their location. Check this
box to cause them to conform to the Unindented block alignment
style.

Using the Format Feature

Once you have set the criteria for the type of file you are using (C, C++, C# or Java),
you are ready to reformat. Complete the following steps:
1. Open the file to be formatted.
2. Select the block of code to format. If you wish to format the entire file, choose
Select All from the Edit menu.
3. Once the desired section is highlighted, select the Format Source option from
the Text menu. The formatting should now occur automatically, based on the
settings in the Tools|Customize|Language|Format dialog.
Note: For HTML and XML files, no additional formatting criteria are
defined. Use Text|Format Source to reformat selected code based on
standard conventions for HTML or XML, respectively.

322 12- Checking and Reformatting Files

Spell Check
CodeWright uses Wintertree Software's Sentry Spelling Checker Engine for its spell-
checking operations. The spell-checker is language-specific and supports languages
such as C, C++, C#, Java, Pascal, Basic, and x86 assembly language out-of-the-box.
Additional language support can be added with intermediate programming skills in
the implementation language of choice and a thorough understanding of the
CodeWright API extension mechanism. The spell-checker's language variability is
limited, by default, to recognizing comment and string components when spell
checking is requested to be restricted to those components.

In addition to being language-specific, CodeWright spell checking includes multiple

dictionaries, and options for suggesting alternate spellings, replicating capitalization,
suggesting split words when accidentally omitting spaces, and suggesting alternate
words based on the current word's phonetics. The purpose of this section is to
describe the CodeWright spell-checking dialog. For more information on extending
the spell checker ’s capabilities, see the online help (Help|Contents and Index).

Check Spelling
Click the Spell Check… option on the Tools pull-down menu to access the Check
Spelling dialog. Extensive online help is available for specific Spell Check options;
search for the online topic Spell Check. The dialog has four tabs, which are described
below.

General Tab of Check Spelling

The General tab allows you to set the basic rules for your Spell Check operation.

Tools|Spell Check|General

12- Checking and Reformatting Files 323

n The Scope section of the General tab offers the option of checking the Current
Word only, or the Entire Document. If the choice is to check the Entire
Document, there are additional options for restricting the scope to a Selection
only, Strings only, or Comments only.
n The Suggest Alternate Spellings option determines whether similarly spelled
words should be listed if the word being checked is not found in the dictionary.
When this option is enabled, the Replicate Capitalization, Suggest Split Words,
and Phonetic Suggestions options become available.
n The Allow Auto-correction option enables/disables the auto-correction feature.
(If turned off, an auto-correct entry in the dictionary will be treated as if it is a
conditional replacement.)
n The Case Insensitive option retains the case of the word being replaced.
n The Detect Repeated Words option allows for detecting accidentally repeated
words such as 'the the' and suggesting 'the' as a replacement. The detection will
occur only if there are no characters other than space and tab between the
words.

Word Format Tab of Check Spelling

The Word Format tab lets you control what characters are accepted when words are
being retrieved for checking. The options chosen here, along with options chosen in
the Scope section of the General tab, govern how the spell checker retrieves a word
for checking. They do not affect the decision the spell checker makes to ignore a
word (i.e. to consider a word correctly spelled). Characters that qualify for inclusion
are collected based on these options. The character collection continues until a non-
qualifying character is encountered.

Tools|Spell Check|Word Format

324 12- Checking and Reformatting Files

The options are:
n Possessive Forms ('s and s') - When enabled, the indicated sequences ('s and s')
are included as parts of words to be checked, but only if they occur at the end of
the word and are preceded by a letter. Use this option if you only want
apostrophes to be considered parts of words when they are immediately before
or after an 's'.
n Embedded Apostrophe - When enabled, apostrophes are included as parts of
words to be checked, but only when the apostrophes occur between two letters.
n Trailing Apostrophe - When enabled, apostrophes are included as parts of
words to be checked, but only when the apostrophes occur at the end of words.
This option differs from Possessive Forms in that it considers apostrophes
viable word-characters even if the character that precedes them is NOT an 's'.
n Embedded Hyphen - When enabled, hyphens are included as parts of words to
be checked, but only when the hyphens occur between two letters.
n Embedded Period - When enabled, embedded periods are included as parts of
words to be checked, but only when the periods occur between two letters.
n Underscore - When enabled, underscores are included as parts of the word to
be checked. They are therefore included in the set of characters that the spell
checker considers when discerning what words need to be checked.
n Leading Digit - When enabled, words that begin with a digit are included as
parts of words to be checked.
n Non-leading Digit - When enabled, words with embedded digits (i.e. digits that
appear anywhere other than in the word's first position) are included as parts of
words to be checked.
n European Character Set - When enabled, alphabetic characters above 0x7f
(European character sets) are included as letters for the spell checker to check,
additionally 0x92 may serve as an apostrophe.

There is also an API that allows the specification of additional characters that should
be considered alphabetic and therefore allowed in words. The API is
void SpellWordChars(LPSTR charSet);
For more information on CodeWright APIs, consult Help|CodeWright API Library.

12- Checking and Reformatting Files 325

Advanced Tab of Check Spelling
The Advanced tab has options to specify that words containing certain character
sequences should be considered correctly spelled. Note that some of the options in
the Advanced dialog will only work if corresponding options on the Word Format
tab are also enabled. The options on the Word Format tab tell the spell checker to
include certain characters when deciding what characters are parts of words. If the
spell checker does not know that those characters are words, it won't use the options
on the Advanced tab to spell check them.

For example, marking With Digits tells the spell checker to check the spelling of
words containing digits. However, it will only work if digits are first known to be
parts of words. Therefore, when With Digits is marked, either or both Leading
Digit and/or Non-leading Digit must also be marked on the Word Format tab.

Tools|Spell Check|Advanced

The options in the Ignore Words section are:

n words With Digits
n words With All Letters Capitalized
n words with unusual capitalization, or With Mixed Case Letters (e.g. BlueSky)
n words with Initial Capital Letters (first letter capitalized)

The Language Options section controls how the spell-checker processes words
when searching for them in the dictionaries. The options are:

326 12- Checking and Reformatting Files

n Allow Hyphenation - When enabled, the spell checker will check the spelling of
all parts of words containing hyphens. If all the parts are correct, the whole
word is considered correctly spelled, and is therefore ignored by the spell
checker. This option will only work if Embedded Hyphen is also marked on the
Word Format tab.
n Allow Contraction - When enabled, the spell checker will spell all parts of
words containing apostrophes. If all the parts are correct, the whole word is
considered correctly spelled, and is therefore ignored by the spell checker. This
option will only work if Embedded Apostrophe is also marked on the Word
Format tab.
n Allow Concatenation - When enabled, the spell checker will look for
component words within a word. For example, braveheart would be
considered correctly spelled because it consists of two correctly spelled words.
This is most useful with languages such as German that allow ad hoc
concatenation of words to form new words.
n Strip Possessives - When enabled, the spell checker will remove 's and s' from
the ends of words before checking them. This is most useful with English and
should be used in conjunction with the necessary word format options.

Possessives are stripped from words with forms similar to the following:
Example: Bordeaux' = Bordeaux
Lions' = Lion
Children's = Children
Strip Possessives will only work if the following option or combination of
options is enabled on the Word Format tab:
3 Possessive Forms, or
3 Both Embedded Apostrophe and Trailing Apostrophe, or
3 Possessive Forms, Embedded Apostrophe, and Trailing Apostrophe.

Documents Tab of Check Spelling

The Documents tab of the Check Spelling dialog displays a list of the files currently
open in CodeWright. Files can be selected from the list for spell checking. Press
Invert to reverse the current selection, highlighting only the documents that are not
currently selected. Selections can be cleared using the Clear button. An asterisk (*)
preceding the file name indicates that language-dependent comment/string
checking is available.

12- Checking and Reformatting Files 327

Tools|Spell Check|Documents

Dictionaries Dialog
Clicking the Edit Dictionaries button in the Check Spelling Dialog accesses the
Dictionaries dialog. The Dictionaries dialog is used for adding and editing
dictionaries that will be used by the spell-checker. The Dictionaries dialog imparts
the ability to do the following:
n Designate which dictionary to use for certain documents.
n Transfer words between the currently selected dictionary and a text file using
the Import and Export buttons.
n Create new spell-checker dictionaries on the fly in the New Dictionary dialog
(accessed by clicking the New File button in the Dictionaries dialog).

Dictionaries
The Sentry Spelling Checker engine uses both text and compressed dictionaries.
Some dictionaries are contained in the \SPELLCHK subdirectory of the CodeWright
home directory. The text dictionaries are faster to access but they use disk space less
efficiently for the amount of words they hold. For the standard language
dictionaries, the text dictionary contains hundreds of short and commonly used
words. The compressed dictionaries contain 100,000 or more other words. Text
dictionary entries should be in alphabetical order and are editable using any text
editor.

328 12- Checking and Reformatting Files

These are the dictionaries that are currently available for the CodeWright spell
checker:
n ACCENT.TLX is a dictionary for English words containing accented characters.
n CORRECT.TLX is an optional dictionary containing several hundred common
misspellings and their auto-correct replacements.
n HTML.TLX is an optional dictionary that gives HTML keywords.
n SSCEAM.TLX and SSCEAM2.CLX are text and compressed dictionaries,
respectively, for American English.
n SSCEBR.TLX and SSCEBR2.CLX are text and compressed dictionaries,
respectively, for British English.
n SSCEFI.TLX and SSCEFI2.CLX are text and compressed dictionaries,
respectively, for the Finnish language.
n SSCEFR.TLX and SSCEFR2.CLX are text and compressed dictionaries,
respectively, for the French language.
n SSCEGE.TLX and SSCEGE2.CLX are text and compressed dictionaries,
respectively, for the German language.
n SSCEIT.TLX and SSCEIT2.CLX are text and compressed dictionaries,
respectively, for the Italian language.
n SSCESP.TLX and SSCESP2.CLX are text and compressed dictionaries,
respectively, for the Spanish language.
n SSCESW.TLX and SSCESW2.CLX are text and compressed dictionaries,
respectively, for the Swedish language.
n USERDIC.TLX is a sample user dictionary.

For more information on CodeWright dictionaries and their use, refer to subtopics
under the index heading Spell Check in the online help.

12- Checking and Reformatting Files 329

330 12- Checking and Reformatting Files
13- Custom Interface
This chapter discusses:
n Dockable toolbars and windows.
n Customizing and manipulating CodeWright toolbars, buttons and menus.
n Choosing and using keymap command sets.
n Using and customizing mouse commands.
n Reassigning keystrokes and mouse actions.
n Recording keystroke macros.

Dockable Toolbars and Windows

CodeWright has a number of standard toolbars, and allows more to be defined. All
toolbars can be modified through a simple drag and drop interface and used in a
variety of ways. For example, toolbars can be docked or free-floating, always visible
or auto-hidden. The Tools|Customize|Toolbars dialog is where toolbars can be
turned on, created or modified, or otherwise manipulated.

Toolbars
Several default toolbars are available in Tools|Customize|Toolbars dialog. Marking
the Visible option for any highlighted toolbar on the Toolbars tab turns the toolbar
on. Other toolbar options on the Toolbars tab are:
n Hide when application is inactive: The toolbar is only visible when CodeWright
is the active application. This is usually desirable for free-floating toolbars.
n Always on top: Specifies that, when free floating, the selected toolbar or
window will not allow itself to be covered up by other applications or windows.
n Allow Docking: When unmarked, the selected toolbar or window is prevented
from docking. If you have decided to use a toolbar or window exclusively in
free-floating mode, this will prevent accidental docking.

A brief description of the toolbars and windows in the Toolbars dialog is provided
next.

13- Custom Interface 331

n Standard Toolbar: The Standard toolbar is turned on in CodeWright by default
and docked at the top of the CodeWright screen, under the main menu. A
description of the Standard toolbar is provided in the Overview chapter towards
the beginning of the manual, under the section entitled A First Look.
n Build Toolbar: The Build toolbar has buttons that can be used to run some of the
commands like Compile and Build that you have set up in Project|
Properties|Tools.
n Edit Toolbar: The Edit toolbar has buttons that perform common editing tasks.
When it is turned on, it is positioned vertically with two buttons from left to
right and eight buttons down.
n Tools Toolbar: The Tools toolbar has several buttons that perform various tasks,
like File Find, Differencing, Merging, etc.
n VCS Toolbar: The VCS toolbar has buttons for performing various operations
with your defined version control program on the document you are editing.
n AppBasic Toolbar: The AppBasic toolbar has buttons that perform operations
that specifically apply to CodeWright's AppBasic macro language, described in
the chapter Extend CodeWright.
n FTP Toolbar: The FTP toolbar is available if you have loaded the FTP File
Transfer module on Tools|Customize|Libraries. It provides options to log in to
a remote host, and Put/Get the document currently being edited in CodeWright.
n Project Window: The Project Window tabs are turned on and initially docked
on the left-hand side of the CodeWright screen. The Project Window has seven
tabs by default (Project, Outline, Objects, Bookmarks, File Open, CodeFolio
and CodeMeeting); and an optional StarTeam tab that is available if you set up
the CodeWright StarTeam Interface on the Tools|Customize|Version
Control|General dialog.
You may detach an individual tab of the Project Window by left-clicking on the
tab and dragging it off the window, or by right-clicking on the frame or title bar
and selecting Detach tab. Project Window tabs are treated as toolbars, and may
be free-floating or docked, set to auto-hide, etc.. As such they are listed
individually on the Toolbars tab of the Tools|Customize|Toolbars dialog.

332 13- Custom Interface

 Tools|Customize|Toolbars Dialog

Refer to the section Detaching Project Window Tabs in the chapter Run CodeWright
for the First Time for more information.
n Output Window: The Output Window tabs are turned on and initially docked
on the bottom of the CodeWright screen. The Output Window has seven tabs by
default (Output, File Find, Search 1, Browse, Difference, Shell, and Symbols);
these tabs display such things as compiler output and results from various
search operations.
3 You may detach an individual tab of the Output Window by left-clicking on
the tab and dragging it off the window, or by right-clicking on the frame or
title bar and selecting Detach tab. Output Window tabs are treated as
toolbars, and may be free-floating or docked, set to auto-hide, etc.. As such
they are listed individually on the Toolbars tab of the Tools|Customize|
Toolbars dialog.
3 Within Output Window tabs, you have the ability to double-click or [Enter]
on a specific output line to jump to that point in the referenced document.
3 In addition to the default tabs, look for additional Search tabs (Search 2,
Search 3, etc.), and options for the Perl, AppBasic Edit, ClipView and FTP
Manager tabs once they have been loaded on the Tools|Customize|
Libraries dialog.
3 You may also show or hide individual Output Window tabs by right-
clicking on the frame of the Output Window (outside of any tabs), and
marking/unmarking tabs on the Output tabs submenu. From the
submenu, you will again only see optional tabs if their DLLs have been
loaded on the Tools|Customize|Libraries dialog.
3 To determine the ID of an Output Window tab at any given time, use the
API function OutputQTitleID.
The Output Window is described in various chapters of this manual.

13- Custom Interface 333

n MSDevSync: The MSDevSync Toolbar has buttons that aid synchronization
between CodeWright and Visual C++ 6.0 or Visual Studio .NET. For either of
the Microsoft IDEs, you can synchronize the current file or all open files with
CodeWright from the toolbar. For Visual C++ 6.0, toolbar buttons will also
execute the Visual Studio Compile, Build, and Toggle Breakpoint commands.
More information on the toolbar can be found in the CodeWright online help.
CodeWright Sync technology is described in the chapter on Synchronization.
n TICCSync: The TICCSync Toolbar has buttons that aid the Texas Instruments
Code Composer Studio synchronization program. The buttons will execute the
Code Composer Studio Compile and Build commands, and will synchronize
the files open in CodeWright with the Code Composer Studio IDE. More
information on this toolbar can be found in CodeWright online help.
CodeWright Sync technology is described in the chapter on Synchronization.

Auto-hide Toolbars
CodeWright toolbars can be optionally set to auto-hide when they are docked. When
auto-hide is turned on, toolbars appear only when the mouse hovers over the area at
which they are hidden.

Project and Output Window toolbars have a pushpin button in the upper right-hand
corner that indicates the auto-hide status for the corresponding side of the screen. If
the push pin is horizontal, auto-hide is ON; if it is vertical, auto-hide is OFF. You can
toggle the auto-hide setting for a particular side of the screen (left, right, top or
bottom) using this pushpin, or by toggling the Auto-hide Toolbar setting on the
Tools|Customize|Toolbars|General dialog.

When a toolbar is hidden, a border with a small black arrow appears where the
toolbar should be. Running the mouse over any part of the border causes the mouse
cursor to change to an image of a hand. If the mouse cursor is allowed to maintain
that shape for a brief moment, the toolbar will appear. The size of the hidden
toolbar ’s border can be changed by modifying the number for Auto-hide window
size in Tools|Customize|Toolbars|General. Mark Display Docked Toolbar Titles to
have the names of auto-hidden toolbars display in the hidden toolbar ’s border.

What Does Dockable Mean?

A dockable window or toolbar can either be attached to one of the edges of the
CodeWright client area, or it can be “free-floating”. When the window or toolbar is
docked, it reduces the client area, and does not overlay other objects. When free-
floating, the window or toolbar may be placed anywhere on the screen and may be
resized to almost any shape, but can partially obscure other objects.

334 13- Custom Interface

Toolbar Docking Precedence
The General tab of the Toolbars Customization dialog (Tools|Customize|Toolbars)
displays a conceptual image of the four CodeWright window-edges that allow
toolbar-docking. The overlapping edges in the image indicate toolbar-docking
precedence. Toolbars that are docked on edges with precedence will 'push over', or
overlap toolbars that are docked on edges without precedence. Toolbar docking
precedence allows toolbars to take full advantage of the horizontal or vertical
expanse of a preferred edge.

Enabling and Disabling Toolbars

Once any dockable toolbars or windows are enabled (visible), a shortcut is available
for setting the visibility status of such toolbars or windows:
1. Click with the right mouse button on any non-button part of a regular toolbar or
on the frame or title bar of a Project or Output Window toolbar. Select the
Button bars, Output tabs or Project tabs submenu. The items preceded by
checkmarks are toolbars or dockable windows that are currently visible.
2. To change the status of any of toolbar or dockable window, select it from the list.

If no toolbars or dockable windows are currently visible, do the following:

1. Select the Tools|Customize|Toolbars.
2. Open the Toolbars tab.
3. Select the desired toolbar from the list.
4. Check the Visible checkbox and press OK. The toolbar will become visible.

Docking and Moving Toolbars and Windows

You can quickly dock or undock a dockable toolbar or window by selecting from the
following methods as appropriate:
n For a regular toolbar (e.g. the Standard toolbar), simply right-click on a non-
button portion of the frame and toggle the Docked item.
n To dock or undock a set of Project or Output Window tabs together, right-click
on the frame or title bar of the Project or Output Window, and toggle the
Docked item. You can also double-click on the caption of a Project or Output
Window toolbar to undock the tabs together if Toolbar Captions is marked on
the Tools|Customize|Toolbars|General dialog.
n To undock a single Project or Output Window tab from a group of tabs (e.g. the
Outline tab), right-click on the frame or title bar of the tab and select Detach tab.

13- Custom Interface 335

The exception is when the toolbar or window has never been docked before, and has
no default docking location. In this case it won’t know where to dock, and you will
need to dock it manually. To do this, drag it with the mouse over one of the four
edges of the CodeWright window, continuing to hold the mouse button down:
n Grab a non-button portion of a regular toolbar, or the title bar caption of a
Project or Output Window toolbar.
n To add a floating window as a tab to an existing window, point to the title bar of
the destination window. You can also drag the floating window into the tab area
of another toolbar to order it in the list of tabs as desired.
n The outline of the object you are dragging will indicate what orientation it will
take when dropped.

Customizing Toolbars and Buttons

CodeWright has a number of regular button toolbars that can be modified through a
simple drag and drop interface. You can also:
n Create your own toolbar with your selection of buttons.
n Modify the functions bound to each button (that will be executed when the
button is pressed).
n Customize the buttons with your own bitmaps.

Adding New Toolbars

To add a new toolbar, complete the following steps:
1. Select Tools|Customize|Toolbars. The Toolbar Customization dialog displays.
2. Click on the Toolbars tab.
3. Press the New button. The New Toolbar dialog displays.
4. Enter the name of your new toolbar and press OK.

CodeWright then creates a new toolbar for you. At this point the toolbar is empty.
You will need to move it, dock it, etc. You will also need to add buttons to it. The
latter is covered in the next topic, Adding and Changing Toolbar Buttons. The toolbar
information is stored in the CWRIGHT.INI file.

Adding and Changing Toolbar Buttons

To add or change a toolbar button:
1. Go to Tools|Customize|Toolbars, or right click on any visible toolbar button, to
access the Toolbar Customization dialog.
2. Click on the Toolbars tab.

336 13- Custom Interface

3. Select the toolbar you wish to modify; the toolbar will be displayed in a separate
window.
4. Click on the Select buttons tab. On the Select buttons tab of the Toolbar
Customization dialog, CodeWright enters a special mode where the toolbars are
temporarily inoperative.

Toolbar Customization: Select Buttons

5. From this dialog you can:

n Drag and drop buttons from the dialog to any toolbar.
n Drag buttons from one toolbar to another.
n Rearrange buttons within a toolbar, dragging them into the desired
position.
n Remove a button simply by dragging it off the toolbar.

There are several categories of buttons in the dialog, listed in the Category window.
The category User-Defined Tools includes buttons with no pre-defined function
bindings, to which you can quickly bind your function.

Binding a Function to a Button

To bind a function to a toolbar button:
1. Go to Tools|Customize|Toolbars, or right-click on any visible toolbar button, to
access the Toolbar Customization dialog.
2. Click on the Bindings tab.

13- Custom Interface 337

 Toolbar Customization: Bindings Screen

3. Select a toolbar from the list box.

4. Cycle through the buttons on that toolbar until you get to the one you want to
change.
5. Make necessary entries in the following edit boxes for each button:
n The Button text field only applies to buttons that contain text, not bitmaps.
n The Function binding field contains the function call to be executed when
the button is pressed. This function must be available to CodeWright and
follow the rules of LibFunctionExec.
n The Tool Tip field contains the message that pops up when the mouse
cursor pauses over the button.
Notes:
The button information, such as the toolbar it belongs to, its position on the
toolbar, the source of the bitmap image and the function bindings, is stored in a
file called CWRIGHT.BTN in the main CodeWright directory. CodeWright takes
care of updating this file, much like an .INI file, as buttons are customized.

All bitmaps that are available in the dialog for the buttons come from the
CWDLL32.DLL. If you have your own bitmaps you would like to add, you will
need to go to the Tools|Customize|Libraries dialog and load your DLL
containing the images.

338 13- Custom Interface

Combo Box History Lists
Many of the prompts in CodeWright have combo box history lists that store previous
responses made at the prompt. Most notably, the Command Key prompt, the Search
and Replace prompts, and the prompt at which you enter the name of a file to edit,
have prompt histories. The lists can be accessed by either bringing down the drop-
down list under the combo, or by pressing the up arrow or the down arrow.
n Press the up arrow to reuse the most recently entered response.
n Press the down arrow to reuse the oldest response.
n Press the up arrow repeatedly to view earlier responses.
n Press the down arrow repeatedly to view more recent responses.

n Press E to accept the response displayed.

As each historical response is displayed, you will note that it is highlighted. If you
issue an editing command, such as [Home], [Ins] or [End], the highlighting
disappears and you are permitted to continue editing the response. Press E to
accept the edited response at anytime. 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.

Editing Combo box History Lists

CodeWright has a History tab in the Tools|Customize|Environment dialog that
allows you to view and remove members of the prompt histories. It also lets you
adjust the size of the lists.

Many prompt histories are saved between CodeWright sessions by default. The
information is saved in the State file. For more information about CodeWright State
files, refer to the Configuration Files & Command Line Parameters chapter of this
manual.

Customizing Menus
This section describes how to edit standard menus, submenus, menu items and
popup menus.

Menu Editor
You can change, delete and add menus and menu items through the Menu Editor on
the Tools|Customize| Environment|Menu dialog.

13- Custom Interface 339

Menu Editor

The dialog lists Menus and Menu Items, as described in the following topics.

Menus
Menus are the top-most selections on the Menu bar. They contain items and
submenus. You begin your modification of the menu by selecting a menu from the
list on the left.
n Up/Down: These buttons allow you to change the position of the menu relative
to other menus. Up and Down refer to the position in the list box. Up moves
the selected menu to the left on the menu bar, while Down moves the menu to
the right.
n Add Menu: The Add Menu button/dialog lets you add a menu to the
CodeWright menu bar. You must provide a name for the menu, a helpful
message to display when the menu is selected, and, optionally, one or more
functions to initialize the menu. The initialization functions are responsible for
disabling or checkmarking menu items as necessary.
n Change Menu Attributes: The Change Menu Attributes button/dialog is like
the Add Menu dialog, except that the attributes for the selected menu are
displayed for editing. You cannot change the ID of a menu.
n Delete: The Delete button deletes the selected menu. You could delete all
menus, if you wish. You would then find that you are unable to add them back
interactively, once you leave this dialog. (You couldn't get the dialog back.) If
the worst happens, you can restore the original menu by editing the
CodeWright configuration file, CWRIGHT.INI. Locate the [Menu] section of
the file and rename the section, or delete all lines under that section heading.

340 13- Custom Interface

Menu Items and Submenus
Menu Items and Submenus are the entries listed on a menu. After selecting a menu,
the items on that menu will appear in the list box on the right. Any submenus on the
menu will also be listed in order, preceded by a + sign. You may then select a menu
item or submenu from the list on which to operate.
n Up/Down: These buttons allow you to change the position of the item or
submenu on the menu. You may also move separator lines with these buttons.
n Add Item: The Add Item button/dialog lets you add an item to one of the
CodeWright menus. You must provide a name for the item (Menu Item Text), a
helpful message to display when the menu is selected (Help String), and a
function to execute when that item is selected (Handler Function). If there is a
shortcut keystroke that performs the same function, you may enter that
keystroke for display on the menu (Key String).
n Add Popup: This button brings up a dialog similar to the Add Menu dialog.
Enter a name for the submenu, a help message, and any functions to initialize
the submenu.
n Change Item Attributes: The operation of this button depends on whether you
have selected a submenu or a normal menu item. If you have selected a normal
menu item, the Change Item Attributes dialog is like the Add Item dialog,
except that the attributes for the selected item are displayed for editing. If you
have selected a submenu, the dialog is like the Add Popup dialog.
n Delete: The Delete button deletes the selected item. You could delete all items
in a menu, if you wish. You can also delete separators with this button.
n Add Separator: The Add Separator button allows you to add a separator line at
the selected position within the menu.
n Add List: There are five lists which may be added to the bottom of a menu:
recent files, scrap buffers, edit buffers, recent projects, and windows. If you are
using One-document-per-window mode, the list of edit buffers is not available.
Each of these lists may only appear on one menu. Therefore, you must first
delete a list from a menu before you can add it to another. This button is
disabled if there are no unassigned lists.

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

13- Custom Interface 341

 Whenever you are through operating on a submenu, you may move it back to
the list on the right by double-clicking on the name again. The minus sign will
change back to a plus when the submenu arrives in the list on the right.
This system allows you to have any level of nesting of submenus that you like.
Just keep adding them on the right and moving them over to the left.

Changing the Functionality of a Menu Item

To change the function associated with a particular menu item, complete the
following steps:
1. Select the Tools|Customize|Environment dialog.
2. Click on the Menu tab.
3. Click on a menu, and corresponding menu item to change.
4. Press the Change Item Attributes button.

Change Menu Item Attributes

This dialog shows you information about the selected menu item such as its ID in
Hex, the function bound to it, etc. Before you start customizing, you will find that
the existing menu items are bound to functions that begin with a lowercase letter.
You cannot access these functions directly. They require special menu handlers and
can only be called from a DLL.
To successfully change the functionality of a menu item, you must:
n Bind the menu item to a function that begins with an uppercase letter. Any of
the CodeWright API functions should work, or your own functions (or macros),
provided they have met the criteria to be recognized by CodeWright (see the
topic Exporting Functions in the appendix Making and Modifying CodeWright
DLLs).
n Check the small checkbox labeled Non-standard handler when binding
functions that do not have a menu handler. You must check this box, or
CodeWright won’t handle your customization, and your menu items won’t
work.

342 13- Custom Interface

Adding a Menu Item
To add a new menu item, complete the following steps:
1. Select the Tools|Customize|Environment dialog.
2. Click on the Menu tab.
3. Select the menu to which the item should be added.
4. Press the Add Item button. The New Menu Item Attributes dialog displays.
This dialog is the same as the Change Item Attributes dialog.

New Menu Item Attributes

5. In the Menu Item Text field, enter the desired text for the menu item.
6. In the Help String field, enter text for the menu item’s tool tip.
7. In the Key String field, enter a keyboard shortcut for this menu item.
Note: Entering a key string in the New Menu Item Attributes dialog does
not make the key string work. It must first be defined in the
Tools|Customize|Keyboard dialog. To learn more about customizing
keystrokes, see the topic Reassigning Keys and Mouse Actions.
8. In the Handler Function field, enter the function binding, beginning with an
uppercase letter.
9. Check the box labeled Non-standard handler.
10. Press OK. CodeWright assigns the menu ID in hex to the new item.
Note: If you prefer to use keystrokes instead of menus, any menu item can
be bound to a keystroke. Refer to the topic Reassigning Keys and
Mouse Actions, in this chapter.

13- Custom Interface 343

Customizing External Operations within
CodeWright
As described in the chapter on Projects, Project Spaces, and Workspaces, CodeWright
provides the ability to use external operations from within the editor. Any program
can be added as menu items to the bottom of the Tools menu. The added items will
be numbered. This is a quick and handy way to add links to your favorite
applications, or execute custom compiles or other external operations.

To add a custom item to the Tools Menu:

1. Select the Project|Properties dialog.
2. Click on the Tools tab.
3. Choose the Custom option from the drop down under the Category combo box.

Project|Properties|Tools - Custom Category

4. In the Command: edit box, enter the command or executable file that the menu
item should launch. Press the right arrow for a list of pre-defined macros; press
the Browse (…) button to search for executable files. Remember that
CodeWright will shell to DOS in the directory specified on
Project|Properties|Directories|Working Directory when executing your
command line, so you may need to provide the complete path.

User-Definable Popup Menus

Positioning the mouse in certain areas within CodeWright and right-clicking will
bring up a popup menu. You can change the way the popup menus work or add
your own sections to them using the CodeWright Popup Menu Editor. The
following paragraphs describe the Popup Menu Editor and provide steps for
creating and editing popup menus.

344 13- Custom Interface

Click the Edit this menu… item on most CodeWright popup menus to access the
Popup Menu Editor. You can also use the function DlgEditPopupMenu from the
CodeWright API Command dialog, a keystroke, a button, or a menu item to access
the editor.

Editing or Creating a Popup Menu

Do the following to edit or create a popup menu in CodeWright:
1. Either access Edit this menu from any CodeWright popup menu, or type:
DlgEditPopupMenu
from the Tools|API Command dialog.
2. The Popup Menu Editor should appear with the CodeWright default menu
definition file CWRIGHT.MNU open.

Popup Menu Editor

3. In the Popup Menu Editor, click File|New to create a new menu, or click
File|Open Menu File to open an existing menu. If a new menu is being created,
a new, empty menu will be opened in the editor. If an existing menu is opened,
the existing menu will appear in the editor.
Note: When opening an existing popup menu for editing, the Open Menu
or Menu File dialog appears. The name of the menu description file
has to be specified in the File box, and the name of the menu (for
example [Utilities]) has to be specified in the Menu box.

Adding or Modifying a Popup Menu Item

Do the following to add or modify a menu item in the popup menu.
1. In the Popup Menu Editor, click Insert|Menu Item to add a menu item. Click
Edit|Modify to modify a selected menu item. In both cases, the Menu Item
dialog appears.

13- Custom Interface 345

 Menu Item

2. Fill in the necessary fields in the Menu Item dialog. They are defined as follows:
n Menu Item Text: This is the text that is seen on the popup menu. Any
character in the text that is preceded by the ampersand (&) acts as a key
accelerator for the item. Press the key for that character while the menu is
visible to access the item.
Example: In the preceding image, the string Hexidecimal is used to label
the menu item.
n Execute Function: This is the function that will be used for normal menu
items. The functions are called when the menu item is clicked. Most
exported CodeWright functions can be used.
Example: In the preceding image, the function WinDisplayMode is
used to execute the menu item command, placing the current
document in hex mode.
n Gray Function: Indicates availability of the menu item’s function. When
the menu item is gray, the function is not available.
Example: The Hexidecimal menu item does not require a Gray Function.
An example of a Gray Function would be the Terminate item
on the Perl popup menu; it is gray when a Perl macro is not
running. When a Perl macro is running, the menu item is used
to forcibly terminate the macro. The following function is
entered in the Gray Function field:

346 13- Custom Interface

 !_PerlCtrl –1
3 If the function returns 0 (false), the Terminate menu item
will be gray.
3 If the function returns 1 (true), the Terminate menu item
is enabled.
3 The exclamation point (!) before the _PerlCtrl-1 function
indicates that the complement of the function's return
value should be used when the function is called.
n Check Function: These correspond to enabled menu items. A checkmark
to the left of the menu item indicates that the item is enabled.
Example: The Hexadecimal menu item is checked when the document
is in hex mode and the following Check Function returns the
value for hex mode (0x0001):
(WinDisplayMode(-1) & WDM_HEX)
n Image Selection: Add an image next to the popup menu item. Choose
from the following options in the new Image Selection group:
3 Auto: Instructs CodeWright to search for an appropriate bitmap. This
will work if the Menu Item Text on this dialog matches that of a main
menu item, or the Execute Function matches a function bound to a
toolbar button.
Example: Auto does not locate a bitmap for the Hex Mode item.
If you typed Quick Search for the Menu Item Text and
selected Auto, a preview of the Quick Search button

would display .

3 File: Press to browse for and specify a bitmap on the Select a

Bitmap dialog.
3 Main Menu ID: Specify the ID of a main menu item. You can locate
an ID by completing the following steps:
1. Go to the Tools|Customize|Environment|Menu dialog.
2. Highlight the menu, and then the menu item, whose bitmap you
wish to use.
3. Press the Change Item Attributes button.
4. On the Change Menu Item Attributes dialog, note the value in
the ID: (hex) field.

13- Custom Interface 347

 Example: There is no main menu item for Hex mode.

Another example would be the ID value for

File|Open:
1006
5. Press Cancel twice to exit and return to the Menu Item dialog.
6. Highlight the Main Menu ID radio button and enter the ID noted.
3 Main Menu String: Specify the string of a main menu item. Like the
ID, the string can be found on the Change Menu Item
Attributes dialog:
1. Locate the value in the Menu Item Text field.
Example: There is no main menu item for Hex mode.
Another example would be the Menu Item Text
value for File|Open:
&Open...
2. Press Cancel twice to exit and return to the Menu Item dialog.
3. Highlight the Main Menu String radio button and enter the string
noted.
3 Toolbar Function: Specify the function assigned to a toolbar button
whose bitmap you wish to use. To determine the appropriate function:
1. Go to the Tools|Customize|Toolbars|Bindings dialog.
2. Highlight the name of the toolbar that contains the desired
button.
3. In the ID box, use the scrollbar to locate the desired button.
4. Note the value in the Function binding field, and press Close to
exit the dialog.
Example: The Function Binding value for the Hex mode

button on the Edit Toolbar is:

WinDisplayMode WDM_TOGGLE|WDM_HEX
5. Return to the Menu Item dialog and enter the noted value in the
Toolbar Function edit box.
n Comment: Comments can be inserted for each menu item added. They are
not displayed on the menu. They can be used as reminders or notes for the
menu item.

348 13- Custom Interface

Popup Menu Semantics
Changes made in the Popup Menu Editor are applied to specified menu description
files. If no menu file is specified, the CodeWright default menu file CWRIGHT.MNU
is used. CWRIGHT.MNU is stored in the CodeWright installation directory. It
contains sections as a normal .INI file does, except that the contents are menu
descriptors. Each section begins with a Section Heading, a word or label enclosed in
square brackets. The lines that follow the section heading (Item Definition Lines)
describe the menu items that will appear on the popup menu, and what happens
when you select each item from the menu. As with .INI files, lines beginning with a
semicolon and blank lines are ignored.

Before creating or modifying popup menus in CodeWright, there are some things to
know about the semantics of the information contained in popup menu description
files. Refer to the following paragraphs for information about popup menu
semantics. Note that all of the items that follow are valid when used from within the
Popup Menu Editor.

Creating a Menu Item

Keep in mind the following when creating a new menu item in the Popup
Menu Editor's Menu Item dialog:
n Beginning a Check Function or Gray Function with an exclamation mark
(!) complements the value returned by the function being used. This can be
useful when it becomes necessary to access the opposite of the function’s
return value.
n If a semicolon is required in any of the function strings it must be escaped
by preceding it with a backslash. The two character sequence '\;' will be
replaced by a semicolon prior to execution of the function string.

Terminating Menu Sections

If you look at the CWRIGHT.MNU file, you will notice that individual popup
menus are contained in menu sections (designated by headings that are
contained in square brackets ' [] '), each of which ends with a special line
containing
[###]
The [###] allows the menu editor to delete a menu description and write a
new one without also deleting comments that may precede the menu
description that immediately follows the one being modified. Because this
special line looks like a section name it terminates the process that's looking for
the end of a section.

13- Custom Interface 349

 Conditionals
A conditional mechanism similar to the C/C++ #if/#else/#endif is possible
when creating new popup menu items. There is a Conditional item on the
Popup Menu Editor's Insert menu that allows conditional items to be created.
The general form for popup menu conditionals is:

#if testFunction
menu description lines
#elseif testFunction
menu description lines
#else
menu description lines
#endif
The <test function> element is a function, similar to a Check Function or a
Gray Function, whose return value is used to determine whether or not to
include the following <menu description lines> in the popup. The
conditionals may be nested to an arbitrary depth.
As a shorthand notation, if the <test function> begins with a left parenthesis,
the entire <test function> string is passed to MacroEvaluate. (This shortcut
applies to all entries requiring a function spec: Execute Functions, Gray
Functions and Check Functions.)

'Include' mechanism
Sometimes different popup menus have common elements and it is useful to be
able to define those elements once and use that description many times. This is
possible using a special menu item in one of three forms:

@file
@file[menuName]
@[menuName]

The first form specifies a file to be included in its entirety. The second form
indicates a specific menu description contained in the specified file. The third
form specifies only the name of a menu; it assumes that the menu is in the file
containing the menu description line.

Dynamic Menu Generation

It is possible to specify, directly in a menu description, the name of a function to call
to generate a menu description string (the string that is seen on the menu). The
returned string, which should be an allocated string, is then used as if it had been
placed in the menu description at that point. The syntax for specifying this action is:

*functionName

350 13- Custom Interface

The entire line beyond the introductory asterisk is taken to be a function name and
its arguments. As with other menu functions, if the generation function begins with
a left parenthesis, the entire line is passed to MacroEvaluate. Note that this item
may be used on menus that have other explicitly defined entries, or it may be the
only item in the menu definition.

Supporting Popup Menu Functions

There are two functions that support the operation of popup menus. They are as
follows:
n DlgMenuPopup -- Use this function to assign a popup menu to a key or mouse
click. The function is formatted as:
DlgMenuPopup <menu>
n DlgMenuExec -- Use this function to execute other sections within the
CWRIGHT.MNU file. The function is formatted as:

DlgMenuExec <section>

Where:
<menu> - If the name starts with ‘[’, it is assumed to be a section in the .MNU
file, otherwise it is the name of the file to use (no sections in file).
<section> - A normal CodeWright section to execute out of the .MNU file. Use
ConfigFileRead() to read out of other files.
Refer to the following example:
Example: The [Utilities] section of CWRIGHT.MNU can be bound to
S-right-mouse click through the following key binding
command:
KmapAssign=’<Shift-Mouse_right_click>’
‘DlgMenuPopup [utilities]’

Using Keymaps
The CodeWright editor is several editors in one. In its "standard" mode, the
CodeWright keymap uses the Common User Access (CUA) key-command set. If you
have ever used a Windows editor before, such as NotePad or SysEdit, you will find
that you can guess many of the basic key commands. This command set offers a
number of shortcut keystrokes to bypass menus and perform various other tasks.

13- Custom Interface 351

CodeWright offers alternate keymap command sets as well. These command sets
may be more to the liking of users whose roots are embedded in Visual Studio, or for
users of DOS, UNIX and other non-Windows platforms. These command sets have
been supplemented with a number of CUA commands.

In all, CodeWright ships with six keymaps. The command sets are usually chosen at
the time of installation, but they can also be switched on the fly in the
Tools|Customize|Environment|Keymap dialog. Command sets may be selected
from the following choices.
n Microsoftâ Visual Studioâ .NET
n IBMâ CUAâ command set
n CUA (CodeWright 4.0)
n Borlandâ BRIEFâ command set (emulates the BRIEF editor, from Underware)
n vi command set (emulates the vi editor found on UNIX systems)
n Lugaruâ Epsilonä command set (emulates the Emacs-derived Epsilon editor
from Lugaru)

You can modify the functions that are executed when a keystroke is pressed using
the Tools|Customize|Keyboard dialog (see Binding Keystrokes to Functions or Macros).
Further discussion of the CUA and BRIEF command sets follow.

CUA Key Commands

The CUA keymap has many more assignments in it than are covered by the
Common User Access standard. 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 the commands easier to learn
and remember.

If you are familiar with CUA commands, you may doubt that CUA commands would
be easy to associate, and some commands are not. (It's hard to associate anything
with H$, you just have to memorize it.) You will find, however, that most
commands of this variety have a more memorable equivalent.

Example: To search again you have your choice of # or CSs. To

find, press Cf.

BRIEF Key Commands

BRIEF emulates the BRIEF editor that is popular in the DOS environment. BRIEF
key commands are not CUA compliant. This means that they conflict with the way
Windows commands normally work.

352 13- Custom Interface

 Example: The BRIEF commands make extensive use of A key
combinations. CUA rules reserve most of these for standard
commands, such as accessing menus. For instance, Af is
usually reserved for bringing down the File menu. In BRIEF, this is
used for displaying the output file's name on the status line.
For this reason, when using the BRIEF command set, you must press
and release the H key to access the menu. To access the File menu,
for example, you press and release the H key and then press f.
Similarly, to access other menus, you press and release H and then
press the underlined letter in the menu's name.

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 guess you could do with a mouse, and other things that you might
suspect you could do but do not know how. It is those things that are covered in this
section.

Mouse Scrolling Speed

If you begin selections with the mouse and then move the mouse outside the visible
window, the window will begin scrolling. Depending on how far out of the window
the mouse is, CodeWright will vary the scroll rate, specifically, the farther out the
mouse is, the faster the scrolling.

In some cases, the space available to move the mouse beyond the window edge is
limited, e.g. full screen mode. CodeWright provides some methods for gaining
control over scrolling speed in these cases. Control is gained via the C, S, and
A keys, under the following conditions:
n If none of the keys are pressed, scrolling speed is the default.
n If one of the keys is pressed, scrolling speed is twice as fast.
n If two keys are pressed, scrolling speed is four times as fast.
n If three keys are pressed, scrolling speed is 8 times as fast.

Inclusive or Exclusive Selection

In the standard keymaps CUA, BRIEF and vi, you can select text by clicking with the
left mouse button and dragging the mouse across the area you want to select. When
the character at the cursor is included in the block, the block is considered inclusive.

13- Custom Interface 353

Default settings are as follows:
n In the vi keymap, inclusive block selection is the default.
n In the CUA and BRIEF keymaps, exclusive block selection is the default (the
character at the cursor is not included in the block).

Closed Selections
You may elect to have selections that you make with the mouse be either closed or
open when you release the mouse button. A closed selection means you will not
change the selection size or shape when you move the cursor. Your keymap dictates
the initial setting for this option; you can change the initial setting with the Leave
Mouse Selections Open option on the Tools|Customize|Environment |Keymap
dialog.

Selections made with key commands are usually open; one end of the selection is
defined by the cursor position, and the selection moves with the cursor. Your
keymap may have a command to toggle a mouse or other selection open or closed.
Example: In the BRIEF-compatible keymap, toggle the selection open or
closed using the Fa command.

In the CUA keymap, toggle the selection open or closed using the
F. command.
To expand a closed selection, move the cursor to the new endpoint desired, and use
the applicable key command to toggle the selection open.
Note: The distinction between closed and open selections is not
meaningful in the CUA keymap unless you have turned on
persistent selections. Otherwise, CUA removes the selection,
whether closed or open, whenever you execute a cursor motion
command.

Column Marking
To make a column selection with the mouse, just click and drag with the right mouse
button instead of the left. Column blocks are always inclusive, regardless of which
keymap you are using.

Line Selections
There is an adjustable margin between the left edge of the buffer and the window
border. You can use this area for making line selections:
n Click with the mouse in this space to select the line to the right.
n Click and drag the mouse to select a series of lines -- even if the mouse happens
to stray from the margin.

354 13- Custom Interface

Word Selections
As with many Windows editors, double-clicking on a word makes a selection
encompassing that word. If you continue to hold down the button on the second
click and drag it around, you can select in units of words. You may be familiar with
this method of selection from one of several word processors.

Status Line Actions

There are a number of functions or popup menus that can be accessed just by
clicking with the right mouse button on hotspots on the status line. These actions
are listed below:

Action Description

Insert/Overtype Toggle between insert and overtype mode by right-

Toggle clicking on the Ins or Ovr designation on the status line.

Read-only / Toggle between Read-only and Read-write status by right-

Read-write clicking in the box to the left of the line number. The box
Toggle may be blank or have a “RO” designation in it. This
toggles both file and buffer status.

Go to line Bring up the Go to Line dialog by right-clicking in the Line

number box.

Next Message Have CodeWright process the next Build error message by
right-clicking in the message box at the left of the status
line.

Right-Click Bring up a customization popup menu with options for

accessing various screens on the Tools|Customize dialog.

Right-Click Bring up a Word Wrap Options menu to quickly toggle

wrap mode and customize wrap options.

Right-Click Bring up a CodeSense customization menu to quickly turn

on and customize The CodeWright CodeSense and
Outline Symbols features, as described in the chapters on
Editing & Printing and Search and Replace and Navigational
Tools.

You can also display a progress indicator on the status line to show the progress of
CodeWright operations. Use the SYSPROG_STATUSBAR flag within the API function
SysProgressStartEx to enable this functionality. More information on this function is
indexed under SysProgressStartEx in Help|CodeWright API Library.

13- Custom Interface 355

A related command is the right mouse click on the Toolbar Search combo box,
located on the Standard toolbar instead of the status line. Right-click here to bring
up the Default Search and Replace Settings dialog, allowing you to check or change
the settings in preparation for using the Toolbar Search or other search mechanism.

Text Drag and Drop

After you have selected a block, you can move or copy the block by dragging the
block to its new location. Text can even be moved between open windows.

Use the following drag and drop operations:

n To move the block:
1. Place the mouse cursor in the selection's highlighted area.
2. Press the left mouse button. The cursor will change shape to indicate that a
drag and drop operation has commenced.
3. Continue to press the mouse button, moving the mouse cursor to the
intended destination.
4. The text cursor follows the mouse cursor, indicating where the destination
will be. Place the caret at the intended destination and release the mouse
button to move the selected text.

n To move text between windows, complete the steps above but press S as
you drag. Be sure to click and hold the mouse button before pressing the S
key. Then drag and release the text.

n To perform a copy operation, complete the steps above, but press the F key
when you initiate the operation.
n To cancel a drag and drop operation after it has been commenced, move the
mouse cursor back over the selection and release the mouse button. A selection
cannot be copied or moved onto itself. The operation is then cancelled and the
selection removed.
n To disable text drag and drop, deselect the Drag and drop text with mouse
option on the Tools|Customize|Environment|General dialog.

Mouse Copy and Move

In addition to Text Drag and Drop, CodeWright supports another method of copying
and moving text with the mouse:

356 13- Custom Interface

1. Select the text you want to copy or move.
2. Point the mouse at the place you want it to go.
3. Issue the proper mouse command. The command for moving the selected text
is F . The copy command is FS .
Sometimes, when you are moving or copying text, the source and destination of the
text are too far apart to be viewed in the same window at the same time. You can still
use the mouse move and copy commands, by opening up another window, or
scrolling between source and destination:
n You might have several sections of text that you want to copy or move, all from
the same source location to a single destination. In this case, viewing the source
in one window and the destination in another is the best approach.
n If you have just one copy or move operation in mind, you can select the desired
text and then scroll to the destination. The selection will scroll off the screen,
but so long as you are using closed selections for mouse operations, it won't
change. Refer to the topic Closed Selections in this chapter.

Creating Windows with a Mouse

It is very easy to create windows of an arbitrary size and position when you are
working with a mouse. This is the quickest way to open up a second window onto
your current buffer, so that you can view two different sections of the buffer at the
same time. To create a window:
1. Point to any part of the CodeWright Client Area that is not currently occupied.
2. Click with the left button and drag the mouse cursor to any other part of the
Client Area.
Whatever buffer was current prior to creating the window is also made visible in the
new window. This means you will have at least two windows in which to view the
current buffer. This use of the left mouse button can be turned off in
Tools|Customize|Environment|General. Just deselect Create Window Using
Mouse.

Drag-and-Drop File Loading

The Drag and Drop feature allows you to load files into CodeWright from Windows
Explorer. Select one or more files listed in the File Manager and drag them with the
mouse to a minimized application. When the mouse button is released, the
application is restored, and the file or files are loaded or processed.

13- Custom Interface 357

Drag and drop file loading can also be used to load or create projects and project
spaces in CodeWright. The feature works when files with the filetype extensions
.PSP, .PJT, .DSW, .SLN, .DSP, .VCPROJ, .VBPROJ or .CSPROJ, or any supported
makefile, are dropped from Windows Explorer onto CodeWright. Auto-detect file
type must be marked in Tools|Customize|Environment|File Options.

If you already have files loaded in CodeWright, the files you drag and drop onto
CodeWright will be added to those already being edited:
n A window is created for each of the files dropped onto CodeWright if you have
checked the box One document per window on the Tools|Customize|
Environment|General dialog.
n If windows are not created, the window that was current will contain the first
file of those dropped.

Expand / Collapse Selective Display

When you are using selective display mode, you can use a mouse for expanding and
collapsing sections of text as you might the sections of an outline. Refer to the topic
Selective Display in the chapter on Search and Replace and Navigational Tools for more
information about this use of the mouse.

Reassigning Keys and Mouse

Actions
Refer to the following discussion of macros and keybindings.

Keymap-Specific Assignments
Now that you learned about CodeWright keymaps and mouse commands, you are
ready to make assignments specific to your keymap. Your main tool for doing this
will be the Assign Keys dialog. Keys can be modified using CodeWright API
functions, keystroke macros, AppBasic, Perl, or API Macros, or your own functions
from custom DLLs. Remember that custom functions need to be exported with a
LibExport call in the DLL’s _init function in order for the key assignment to work.
Otherwise, a “function not found” message will appear in the CodeWright status bar
when the keystroke is pressed. Refer to the appendix on Making and Modifying
CodeWright DLLs for more information on custom DLLs or Add-Ons.

358 13- Custom Interface

Customizing with Keybindings
As mentioned in the section on Using Keymaps, CodeWright ships with six unique
keymaps. These are Visual Studio .NET, CUA (current version and CodeWright 4.0
version), BRIEF, Epsilon, and vi. The functions that will be executed when you press
a key will depend upon which of these keymaps you are in. We have additional
keymaps available in our Technical Support Add-Ons collection, or you can create
your own.

If you are not happy with the way a certain operation is performed within a
keymap, you may want to try that operation in another keymap. (Select
Tools|Customize|Environment|Keymap and change the keymap selection for
testing purposes.) If you find that another keymap has a function that works more
appropriately, you can use it to replace the original keymap’s function. The change
is made in the Tools|Customize|Keyboard dialog. See Binding Keystrokes to
Functions or Macros, later in this chapter.

Keystroke Recording/Playback
Keystroke macros consist of a series of keystrokes that can be run sequentially as a
unit. The following sections describe how to make keystroke macros in CodeWright.
Note that keystroke macros are limited to actual keystrokes (mouse clicks won't be
accepted) and keystrokes entered into Windows dialog boxes cannot be recorded.

Recording a Keystroke Macro

You can record a keystroke macro in any of the following ways:

n Press & (or Cx in BRIEF) to begin and end a recording.

n Select Edit|Record to begin and end a recording.

n Type the ASCII representations for a series of keystrokes directly into the
Keystroke Macros dialog (accessed by choosing Edit|Keystroke Macros).

Saving a Macro
The Keystroke Macros dialog is used to create, edit, save, and delete named
keystroke macros.

13- Custom Interface 359

Keystroke Macros Editor

To make a named keystroke macro, complete the following steps:

1. Record a series of keystrokes using the methods described in the preceding
topic, Recording a Keystroke Macro.
2. Load the recorded macro into the Keystroke Macros Editor by clicking New
and then Get Current on the Keystroke Macros dialog. The keystroke macro
that was just recorded will be displayed in the editor.
3. Type a name into the Name combo-box.
4. Click Save.

Once the keystroke macro has been saved with a name, it can be used from the
CodeWright Tools|API Command dialog, or bound to a keystroke, button, or menu-
item simply by typing the name of the macro in the appropriate place. Named
keystroke macros can also be used in CodeWright AppBasic macros, Perl macros,
and API macros. For more information on macros, see the chapter on Extend
CodeWright.

Binding Keystrokes to Functions or Macros

To bind a keystroke to a function or macro, complete the following steps:
1. Go to the Tools|Customize|Keyboard|Main Keyboard dialog.

360 13- Custom Interface

 Assign Keys Dialog

2. Click the Functions Assistant arrow (just beneath the keyboard graphic) and
select the desired category of functions or macros. The selected category will
now display on the Assign Keys dialog. For example, select Functions.
3. If desired, use the Filter Combobox to further reduce the list of functions
displayed in the Functions combobox. Use either of the following methods:
n Enter characters, such as buf, to show only functions beginning with those
characters (e.g. BufEditFile, BufInsertChar).

n Use the Filter Assistant arrow to select a specific category of functions

(BRIEF, CUA, vi, Epsilon, Visual Studio, Debug or All Functions). If you
wish to use one of the keymap categories as a filter, you must have already
selected that keymap (during installation, or from the Tools|Customize|
Environment|Keymap dialog).
For the example, press the arrow and select CUA.
4. Enter or select a function from the Functions combobox. For example, choose
CUA_drop_bookmark. If there are already keys assigned to this function, they
will be listed in the Current Keys box.
5. Place the cursor focus in the Press new shortcut key field. Click on the desired
keys from the keyboard graphic, or press the key combination on your
keyboard. For example, click on [Alt]-[F10]. If there is an existing key
assignment for this key combination, it will display in the Currently Assigned
to field.
Note: You must check the option Allow alt-key combinations on the
Tools|Customize|Environment|General dialog if you wish to
assign [Alt] key combinations.
With the values noted, the Assign Keys dialog would appear as follows:

13- Custom Interface 361

 Assign Keys with Sample Entries

6. Press the Assign button to complete the key assignment shown, and press OK
to exit the Assign Keys dialog.

362 13- Custom Interface

14- File Support and
Sharing
This chapter discusses options and strategies for file loading and validation, and for
file backup and auto-save. It includes a brief run-down of the CodeWright FTP
utility, which can be used for transferring files to and from remote systems from
within the editor. The final section describes the CodeMeeting tab on the Project
Window, which facilitates code review and collaboration through the ability to send
messages and share files between CodeWright users at other locations.

File Loading, Reloading and

Validation
CodeWright has options for preloading and auto-validating local and non-local files.
Read on to find out what these terms mean, and how to use the features that enable
them.
n A file is preloaded in CodeWright if it is fully loaded into virtual memory,
without relying on pointers to the actual file on disk. This method for loading
files is optional and must be turned on manually. It takes longer, and uses more
temporary disk storage, but does not rely on the presence of the original file. If a
network connection is lost or if the file is somehow deleted, you will still be able
to continue.
n A file is validated in CodeWright when periodic checks are made to see if the file
being edited has been altered by another process. Auto-validation can be a
process on some remote media, in which case, it may be more efficient to turn it
off.

14- File Support and Sharing 363

To set file loading and validation options:
1. Access the Tools|Customize|Environment|File Options dialog.

Tools|Customize|Environment|File Options

2. The following options in the File Loading/Reloading group can be enabled as

precautionary measures to maintain the integrity of files loaded in CodeWright:
n Auto-detect File Type: Mark Auto-detect file type in Tools|Customize|
Environment|File Options if you want CodeWright to automatically open
files according to their file type. This option works for files with the
following file type extensions: .PSP, .PJT, .DSW, .SLN, .DSP, .VCPROJ,
.VBPROJ, .CSPROJ, or any supported makefile. The following will occur
when appropriate files are opened in CodeWright while Auto-detect file
type is marked:
3 Files with .PSP file type extensions (CodeWright project space) will
load as CodeWright project spaces.
3 Files with .DSW or .SLN file type extensions (Visual Studio Workspace/
Solution) will create CodeWright project spaces.
3 Files with .PJT file type extensions (CodeWright project) will load as
CodeWright projects.
3 Files with .DSP, .VCPROJ, .VBPROJ or .CSPROJ file type extensions
(Visual Studio Project) will create CodeWright projects.
3 Any supported makefile will create a CodeWright project. See the drop
down list under Makefile Type in the External Makefile Dialog for a
list of supported makefiles.

364 14- File Support and Sharing

 Do not mark this option if you want CodeWright to load these files for
editing only.
The Auto-detect file type option works for designated files when they are
opened in most allowable ways (i.e. when they are opened using
File|Open, from the CodeWright Project or Output Windows, from the
CodeWright command line, from the CodeWright FTP Manager, via drag
and drop, etc). For CodeWright project files that are opened from the
Output Window's Output or Search tabs (Search 1, Search 2, etc.),
CodeWright overrides the Auto-detect File Type option, opening the
project files as text files.
n Auto-detect File Encoding: Mark Auto-detect File Encoding in
Tools|Customize|Environment|File Options to turn on auto-detection
and bi-directional conversion of code that follows the Unicode or UTF-8
standard. UTF-8 and Unicode are supported for Windows 98, 2000 and XP.
If a file in Unicode or UTF-8 format can be converted to the Windows ANSI
character set and back again without loss, CodeWright can load, edit and
save it. This means that the extended characters used in European
languages are supported (e.g. á, è, ï, û, ñ, æ, ß, ç, Å), but files cannot contain
Hebrew, Kanji, Hangul or similar characters.
When this option is marked, the first portion of the file (512 bytes by
default) is examined when the file is opened. If it exists, the DWORD
registry entry HKCU\Software\Borland\CodeWright\Customize\
EncodingCheckLimit specifies the maximum offset to examine. Set the
value to hex ffffffff to cause the entire file to be examined.
3 If the “little endian” Unicode signature is detected (0xff 0xfe), the file is
converted to ANSI Code Page characters. The Windows API
WideChartoMultiByte() is used to convert the file to ANSI Code Page
Characters when a file is loaded, and then MultiByteToWideChar() is
used to convert back to Unicode when the file is written out.
3 If the UTF-8 signature is detected (0xef 0xbb 0xbf), the Windows API
function MultiByteToWideChar() converts the file to Unicode, and
then WideCharToMultiByte() converts the Unicode to ANSI. When
the file is written to disk, MultiByteToWideChar() is used first to
convert ANSI to Unicode, and then WideCharToMultiByte() is used to
convert the Unicode to UTF-8.
If you have enabled Auto-detect File Encoding, you may convert
individual Unicode or UTF-8 files from the File|Save As or File|Open
dialogs. Find the desired format in the Save File as Type or Open As
combo box, respectively.

14- File Support and Sharing 365

 n Auto-sense file EOL: When this box is checked, CodeWright will look for
line terminations when it first loads a file. It can detect DOS (cr/lf), UNIX
(lf), and Macintosh (cr) line terminations. If the file has UNIX-style line
terminations, the E key is made to insert only a line feed (lf).
Macintosh translations for both input and output are done at a low level
and seem like DOS files to the user (i.e. If you search through a Macintosh
file in hex mode, you will therefore find UNIX style 0x0a characters instead
of Mac style 0x0d characters.).
Note: It is advisable to use the Auto-sense file type EOL option when
editing UNIX files in CodeWright.
n Suppress reload prompt: If another process alters a file that you have
loaded into CodeWright, it will prompt you, asking if you wish to reload
the file. If you wish to always reload the file without being prompted,
check this box.
n Preload file on open: When checked, this box indicates that all edit files
should be completely loaded into virtual memory. The alternative just
loads as much as necessary for editing, and retains pointers into the
original file. Preloading takes longer, and uses more temporary disk
storage, but then you no longer rely on the original file. If you lose your
network connection or if the file is somehow deleted, you can still continue.
n Preload non-local files: When checked, this box indicates that you want to
load files on non-permanent media completely into virtual memory. Non-
permanent media includes floppy disks and network drives.
n Auto-validate preloaded files: When checked, CodeWright verifies at
critical junctures that the preloaded file you are working on has not been
altered by another process.
n Auto-validate non-local files: When checked, CodeWright ensures at
critical junctures that the file you are working on has not been altered by
another process, if that file is on non-permanent media. Non-permanent
media includes floppy disks, and network drives. Auto validating can be a
slow process on some remote media. In this case, you may wish to turn off
validation.
3. The following options in the File and File System group can be enabled for
quick access to files being loaded in CodeWright and as precautionary measures
to maintain the integrity of files being edited:
n Show file list on File menu: When this box is checked, CodeWright
maintains a list of up to 9 recently viewed files at the end of the File menu.
The most recently loaded file appears at the top of the list. To reload one of
these files, select the filename from the list.

366 14- File Support and Sharing

 n Save file on loss of focus: You may wish to have files saved whenever you
switch away from CodeWright to another application. If so, check this box.
This adds an extra level of security when you are testing programs that
might deprive you of the opportunity to save later.
n Use file rewrite save method: When this option is off, CodeWright uses the
traditional method of saving a file. This involves renaming files (write to a
temporary filename, rename the old file to the backup file, and then
rename the temporary file). Renaming can cause problems on some
systems where special file attributes or links exist. When this option is on,
CodeWright avoids these problems by working on the original file, and
making a copy of it when it creates the backup file.
The File Rewrite Save Method is also recommended for saving large files;
refer to the Chapter on Large Files for more information.

File Backups and Auto-save

This section discusses how to set up file backup and auto-save options in
CodeWright. The options can be set globally, for all files being edited, per file type
(e.g. .CPP, .C, .TXT), or per individual file.

Global Backup and Auto-Save Settings

The global backup and auto-save settings can be made on the Backup tab of the
Tools|Customize|Environment dialog. To access this tab:
1. Select Tools|Customize|Environment|Backup.

Tools|Customize|Environment|Backup

14- File Support and Sharing 367

2. Address the following fields:
n Global Backup Spec: The global backup specification dictates how the
name of a backup file is derived from the original filename. This is the most
common method of specifying the name of the backup file, though backup
specifications may be set for each document. The backup specification can
indicate the directory in which backups are made, the extension used, and/
or formatting strings that transform the filenames into other names.

The default backup specification, %b.bak dictates that the backup file be
made in the same directory as the original file, but bearing the extension

.BAK. Press the arrow at the end of the Global Backup Spec field for a
drop-down list of additional specification options; click on an item in the
list to automatically insert it in this field. The backup specification is only
used when backups are enabled. Refer to the topic Formatting the Backup
Specification, in this chapter, for more information.
n Auto-save Enable: Check this box to access options related to the auto-save
feature. This feature periodically saves changes to disk to avoid the
substantial loss of data that could otherwise result from a power outage or
other minor catastrophe. Normally these saves are performed using a
filename other than the original. This allows you to determine when you
are ready to overwrite the original file. You can have the auto-save feature
make saves based on elapsed time, keyboard inactivity, or both.
n Overwrite auto-save files without prompting: If Auto-save detects a file of
the same name as it wants to use, it checks to see if it is a file that it created
during the current session. If it is not, CodeWright prompts you before
overwriting. The file may not be an auto-save file at all, or it may be an
auto-save file from a session that terminated abnormally. In these cases,
you may wish to retain the file. On the downside, if you are not present to
respond to the prompt, the file will not be auto-saved. This checkbox
allows you to specify that the file be overwritten regardless of its origin
without prompting.
n Store Auto-save Options in Project File: Check this box to store auto-save
settings with the project that is currently open. If the box is checked but no
project is open, the selected options are stored as default settings for use
with future projects.
n The Destination section offers four options for controlling the directory
and file extension to be used for auto-saved files. Descriptions of the
options are as follows:
3 Use file's directory, save file.x as 'file.x_~' : Auto-saved files are saved
to the same directory as the file being edited. A tilde is used as the third
character of the extension. If the file being edited has only one
character in its extension, an underscore is used as the second
character of the auto-save filename.

368 14- File Support and Sharing

 3 Use directory specified below, save file.x as 'file.x_~’: Auto-saved files
are saved to the directory specified in the Auto-save Directory field. A
tilde is used as the third character of the extension. If the file being
edited has only one character in its extension, an underscore is used as
the second character of the auto-save filename.
3 Use transformation or filename specified below: Auto-saved files are
saved with the directory and filename or equivalent transformation
pattern specified in the Auto-save file specification field. (The field is
only enabled when this box is checked.)
3 Write to original file (i.e. File|Save): Auto-saved files are saved to the
file currently being edited.
n Auto-save Directory: Enter here the name of the directory, if you want auto-
save files created in a central location. If you don't name a directory for auto-
save files, they will be created in the same directory as the original file.
The filename used will be the same as that used on the original file, except that
the third character of the extension will be a tilde (~). If the extension is less
than two characters, it will be filled with underscores ( _ ). (See the topic
Transformation Patterns.)
Examples:
3 The file FOO.C would be auto-saved under the name FOO.C_~.
3 A file whose name already has three characters, such as FOO.PAS, is auto-
saved under the name FOO.PA~. In this case the S was replaced with a
tilde.
3 A file with no extension, such as README, would be saved with the
extension .__~ (e.g. README.__~).
n The Auto Save limit listbox is used to limit the size of files that are auto-saved.
Files that exceed the specified size will not be auto-saved.
n Force time: This entry sets the absolute time interval that is allowed to pass
without saving to disk. This type of auto-save is performed without regard to
keyboard or other activity. Enter the number of minutes you want to allow
before auto-save interrupts editing to save the file. A value of zero has the effect
of turning this kind of auto-save off.
n Idle time: This entry sets the interval of inactivity that will trigger an auto save.
Inactivity means no key has been pressed and no button has been pushed.
Enter here the number of seconds of inactivity you want to allow. A value of
zero has the effect of turning this kind of auto-save off.

14- File Support and Sharing 369

Backup Settings for Specific File Types
To make a backup specification for a specific file type (that overrides any global
specification), access the Options tab on the Language dialog:
1. Select Tools|Customize|Language|Options.

Tools|Customize|Language|Options

2. In the Customize dialog navigation tree, highlight the extension of the desired
file type.
3. In the Backup spec field, enter a string that dictates how the name of a backup
file should be derived from the original filename. The default backup
specification, %b.bak dictates that the backup file be made in the same directory
as the original file, but bearing the extension .BAK. The backup specification is
only used when backups are enabled (the Make backups box is checked).
Refer to the topic Formatting the Backup Specification.

Backup Settings for Individual Files

To make a backup specification for an individual file (that overrides any global or file
type specifications), access the General tab of the Document/Window Manager
dialog.
1. Select the Window|Windows menu item.
2. Choose the General tab.

370 14- File Support and Sharing

 Document/Window Manager|General

3. In the Document List box, select the document whose settings you wish to edit.
4. Check the box Make backups.
5. In the Spec field, enter a string that dictates how the name of a backup file
should be derived from the original filename. The default backup specification,
%b.bak dictates that the backup file be made in the same directory as the original
file, but bearing the extension .BAK. (Refer to the following topic, Formatting the
Backup Specification.)

Formatting the Backup Specification

CodeWright allows you to specify where and under what name you wish to store
backup files. It even allows you to define how to derive the root or extension of the
backup filename from the file being backed up.

Backup locations and the filenames used are controlled with formatting strings.
Formatting strings contain format controls and transformation patterns that tell
CodeWright how to deal with file names that are as yet unknown. Format controls
begin with a single percent sign ( % ). Any other text is treated literally.
Important: It is possible to specify a format that will result in an illegal filename.
CodeWright does not attempt to ensure that the resulting filename
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.

14- File Support and Sharing 371

To turn backups off, leave formatting strings empty at the global and local levels.
3 The global string is located on the Tools|Customize|Environment|Backup
dialog; the local strings are located on the Tools|Customize|Language|Options
and Document/Window Manager|General dialogs.

Format Controls
The format controls available for use in backup formatting strings are listed in the
table below. Note that optional portions of these format controls are enclosed in
italicized square brackets. Examples are based on the output file C:\SRC\FOO.BAR:

Backup String Format Controls

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. Ends with a backslash
only if describing the root directory. (e.g., \SRC)

%[{...}]e extension Includes the dot that separates basename from

extension, unless the name of the output file has
no extension. May optionally contain a
transformation pattern, described below. (e.g.,
.BAR if no transformation pattern supplied)

%f filename The root name and extension.

%p path Does not include the drive (volume) or

filename. Ends with backslash. (e.g., \SRC\)

%[{...}]r root Does not include extension, drive (volume) or

path. May contain an optional transformation
pattern, as described below. (e.g., FOO if no
transformation pattern supplied)

%v volume The drive letter and the colon. (e.g., C:)

%% percent A single percent sign is represented by two

consecutive percent signs (%%).

Example: The formatting string, which represents the initial default, is

%b.bak. You would set this default using a function call like:
BufSetGlobalBackupSpec="%b.bak"

372 14- File Support and Sharing

Transformation Patterns
The root and extension format controls, described above, may contain
transformation patterns. 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 the control character, r or e respectively.

You supply the pattern in two parts: the override pattern and the fill pattern:
n The override pattern specifies characters, each of which replaces characters at
the same position within the original root or extension string. The override
pattern also may limit the length of the resulting string.
n The fill pattern specifies characters to fill empty positions within the root or
extension string.

A single vertical bar ( | ) separates the override pattern from the fill pattern. If you
are supplying only the override pattern, you may omit the vertical bar. Supplying
only the fill pattern is pointless, since the resulting string will be empty.

The rules are the same for using transformation patterns, whether you are using
them on the 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 extension is 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 Pattern
There is a character in the override pattern for each character in the resulting
string. The character at each position may be either a valid filename character,
or a question mark ( ? ).
n If a filename character is specified, the specified character replaces the
character in the original string.
n If a question mark appears at a given position in the string, the character in
the original string is used.
n If no character appears in the override pattern for a given position (i.e., the
root is shorter than 8 characters or the extension is shorter than 3), the
resulting string is truncated at that position, even if you have supplied a fill
pattern.

Fill Pattern
The fill pattern may contain only valid filename characters. The character at a
given position in the pattern is used in the resulting string if that position in the
original string is empty (i.e., the original string is shorter than the fill pattern)
and a question mark is specified by the override pattern.

14- File Support and Sharing 373

 The following examples demonstrate the effects of various override and fill
patterns:

Transformation Pattern

Pattern Original Name Backup

Name

%r%{??~|___}e FOO.CPP FOO.CP~

FOO.C FOO.C_~

%r%{??~}e FOO.CPP FOO.CP~

FOO.C FOO.C

%r%{~??}e FOO.CPP FOO.~PP

FOO.C FOO.~

%r%{~}e FOO.CPP FOO.~

FOO.C FOO.~

%r%{?}e FOO.CPP FOO.C

FOO.C FOO.C

%{???????~|~~~~~~~~}r%e FOO FOO~~~~~

FOO.C FOO~~~~~.C
TESTFILE.C TESTFIL~.C

%{?????}r%{???|bak}e FOO FOO.BAK

FOO.C FOO.CAK
TESTFILE.C TESTF.CAK

Making Files Read-only

Files can be assigned a read-only (non-editable) status at several locations within
CodeWright, much like backup specifications. The hierarchy of these locations is
indicated below, and details of each location follow.

àTools|Customize|Language|Options dialog –Allows you to make all files of a

specified type read-only (e.g. You could make all .INI files read-only).

àDocument/Window Manager|General—Allows you to specify that an

individual file will be read-only, overriding the setting for its file type.
Access from the Windows item on the Window menu.

àFile|Open – Directs CodeWright to open this file as read-only,

overriding all prior settings.

374 14- File Support and Sharing

File Types
To make files of a certain type read-only, access the Options tab of the Language
dialog:
1. Select Tools|Customize|Language|Options.

Tools|Customize|Language|Options

2. In the Customize dialog navigation tree, click and highlight the extension for
the desired file type.
3. In the Document Options group, check the box Read-only. Files of the specified
type may not be edited, unless this setting is overridden on the Document/
Window Manager|General dialog, or the File|Open dialog.

Individual Files
To make an individual file read-only, complete the following steps.
1. Select the Windows item on the Window menu.
2. Choose the General tab.

14- File Support and Sharing 375

 Document/Window Manager|General

3. Click on a document in the document List field to edit its settings.

4. Check the box Read-only file to prevent editing of this file, regardless of what
has been previously specified for files of this type.

Individual File upon Opening

To make a file read-only upon opening it, regardless of prior settings for the
individual file or the file type, complete the following steps:
1. Select File|Open. The Win 98 version of the File|Open dialog is shown.

File|Open

2. Browse to find the file you wish to open and click on the filename.
3. Check the box Open as read-only.

376 14- File Support and Sharing

FTP: File Transfer in CodeWright
The FTP Manager is available as an optional tab on the CodeWright Output
Window. As with all Project and Output Window tabs, the FTP Manager tab is a
dockable toolbar that can be detached and placed anywhere on your screen.

Enabling the FTP Manager

To initially display the FTP Manager tab:
1. Enable the FTP File Transfer module in Tools|Customize| Libraries.
2. Go the Window|Output submenu and check the FTP Manager item.

Creating Profiles
Profiles allow you to save a group of settings for subsequent connection to a
particular remote server. Logging in with a pre-defined profile saves time and effort
each time you launch an FTP session.

To create a new FTP profile, press the Connect button on the FTP Manager tab to
display the FTP Login dialog.

FTP Login Dialog

To create a profile:

1. Press the New Profile button .

2. If you have any existing profiles, you will be asked whether or not the current
data displayed should be used as the basis for the new profile. Select Yes or No
as appropriate.

14- File Support and Sharing 377

3. Add/modify information on the FTP Login dialog for connections to the
specified remote host.

4. When you are satisfied with the profile, press the Save Changes button to
add it to the Profiles list for future use.

Logging in to a Remote Server

If you wish to log in to the remote server using an existing profile, complete one of
the following:

n Press the Quick Connect button and select the desired profile from the drop-
down list. Your current profile will be checked.
3 If you checked Save Password when creating this profile, the system will
now attempt to log you into the remote host.
3 If you did not check Save Password, the FTP Login dialog will display with
the profile selected. Fill in the appropriate password and press Connect.

n Press the Connect button to display the FTP Login dialog. Select an existing
profile, make necessary changes (if any), and press Connect.

If you wish to log in to a remote server without using a profile, complete the
following:

1. Press the Connect button on the FTP Manager tab to display the FTP Login
dialog.

2. Press the New Profile button and answer No to the prompt to clear the fields
of any existing information.
3. Complete the FTP Login dialog as desired, and press Connect.

Using the FTP Manager

In the FTP Manager tab, your local directory structure is shown on the left, and the
remote host directory structure is displayed on the right. Files in the selected folder
are displayed in the pane below the respective directory, and may be sorted on any
of the column headers. Right-click menus from the directory and file lists provide
additional functionality. A message log at the bottom of the tab details all activity
between the local machine and remote host during the current session.

378 14- File Support and Sharing

FTP Manager Tab on the Output Window

Directory Trees vs. Base Directories

On the FTP Manager's built-in toolbar, the Upload button and Download buttons
are used to Put and Get what is shown in the tree directories. Selected files are
transferred to selected directories. To complete an upload to the remote host (Put) or
download to your local machine (Get), do the following:
1. Navigate to the desired directories on the Local and Remote machines.
2. Select the files to Put or Get.

3. Use the Test Upload (Test Put) or Test Download (Test Get) buttons to
quickly preview what will happen when you begin the Put or Get operation.

4. When satisfied, proceed with the Upload (Put) or Download (Get). If you
wish to open downloaded files in CodeWright automatically, press to
download instead.

5. When the desired transfers are complete, press to disconnect from the
remote host, ending the FTP session.

Put or Get using Base Directories from your Profile

To transfer selected files with their paths, right-click within the Local Files list and
choose from the following options:

n Put file(s) using base path: Transform the filename of each selected file in the
Local Files list using both the Local Base Directory and the Remote Base
Directory from the current profile, sending the file (using the resulting filename
and path) to the remote server.

14- File Support and Sharing 379

n Get file(s) using base path: Transform the filename of each selected file in the
Local Files list using both the Local Base Directory and the Remote Base
Directory from the current profile, receiving the file (using the resulting
filename and path) on your local machine.
n Test file(s) using base path: Test the transformation of filenames for a Put or Get
files using base path to see what you would send or receive using the preceding
right-click options.

Transferring Open Documents or Project Files

You can view all Open Documents or Project Files from your current project
by double-clicking on the corresponding item at the bottom of the Local Directories
list on the FTP Manager tab. If you do not have open files or an open project, no
files will display.

Displaying the FTP Toolbar

In addition to functionality found on the FTP Manager tab, the FTP toolbar allows
you to login to a remote host, and Get or Put the file currently being edited.
To make the FTP toolbar visible:
n Go to the Toolbars tab on the Tools|Customize|Toolbars dialog, highlight FTP
in the list, and mark Visible, or
n Right-click on a non-button portion of a regular toolbar, or the frame or title bar
of a Project or Output Window tab. Click on the Button Bars submenu and
select FTP.
FTP toolbar buttons are defined as follows:

n Receive Current Document: Press this button to get the latest copy of the
current file being edited from the Remote Base Directory specified in your
profile for this FTP server, if it exists. You will be prompted to log in first if you
are not connected.

n Send Current Document: Press this button to send the current file being
edited to the Remote Base Directory specified in your profile for this FTP
server, or to the root directory of the remote server if no Remote Base Directory
has been defined. You will be prompted to log in first if you are not connected.

n Receive Current Document with Path: Press this button to transform the
filename of the current file being edited, using both the Local Base Directory
and the Remote Base Directory specified in your profile for this FTP server. You
will Get the latest copy of the file you are editing from the remote server, using
the resulting filename and path. If you are not connected, you will be prompted
to log in.

380 14- File Support and Sharing

n Send Current Document with Path: Press this button to transform the
filename of the current file being edited, using both the Local Base Directory
and the Remote Base Directory specified in your profile for this FTP server. The
file will be sent to the remote server, using the resulting filename and path. You
will be prompted to log in first if you are not connected.

n Login to Host: Press this button to display the FTP Login dialog.
For more information on specific buttons and fields, refer to the topics FTP: Manager
and FTP: Login in the CodeWright online help index (Help|Contents and Index).

CodeMeeting: Messaging and File

Sharing
The CodeMeeting tab on the Project Window facilitates code review and
collaboration through the ability to send messages and share files between users of
CodeWright, CodeWrightâ for Microsoftâ Visual Studioâ .NET and ChatWrightä at
other locations.

The CodeMeeting tab is divided into four sections: a non-dockable toolbar, a Buddy
List, a Chat Window and a Chat Input box.

CodeMeeting Tab on the Project Window

There are splitter bars between the Buddy List and Chat Window, and between the
Chat Window and Chat Input box, that become active when you move the mouse
cursor over them. These splitters allow you to resize the three windows.

14- File Support and Sharing 381

You can also split the Chat Window into two panes by giving the window focus and
pressing [F5], or by clicking on the splitter button in the upper right-hand corner of
the window. Press [F5] again to restore its original appearance.

Preparing for Initial Use

Press on the built-in CodeMeeting toolbar to display the CodeMeeting

Configuration dialog.

CodeMeeting Configuration Dialog

Refer to the following options on the CodeMeeting Configuration dialog:

n Prompt before connecting users: Mark this option to activate a dialog prompt
when another user requests a connection with you (this is the default). The
dialog will appear for 30 seconds, allowing you to accept or decline the
connection. Uncheck the option to allow connections to your machine upon
request without approval.
n Prompt before allowing remote editing: Check this option to display a dialog
prompt when a connected user requests control of a document. If unchecked,
the control change is granted without approval. The option is checked by
default.
n Share all documents made current: Check this option to automatically share
each document as you make it current in the CodeWright Edit Window (when

you are in control). When the option is unchecked (default), you must press
each time you wish to start sharing a document.
n Show remote presence changes: Check this option if you want to know when
other users become available during your session (their names will be displayed
in boldface in the Buddy List).
n Beep when chat messages arrive: Check this option to have an audible
indication that a chat message has arrived from a connected user (if CodeWright
is active).

382 14- File Support and Sharing

n Beep in locked documents: Select this option to have CodeMeeting beep when
you attempt to edit, change position in, or change display attributes for a locked
document.
n Chat Window options:
3 Horizontal Scrollbar: Show a horizontal scrollbar in the Chat Window.
3 Vertical Scrollbar: Show a vertical scrollbar in the Chat Window.
3 Wrap long lines: Use Wrap display mode in the Chat Window, wrapping
lines at word boundaries.
Note: Right-click in the Chat Window to access these options from a popup
menu. Select Clear Window from the popup menu to erase all text
from the Chat Window.
3 View Theme: Choose a View Theme to change the appearance of the
various elements in the Chat Window, based on the corresponding
elements in that View Theme. To modify the View Theme, press Edit to
access the View Themes dialog.

Chat Definition View Theme

Window Color
Element

Chat Messages Text messages sent between Text color

the connected users.

Other User ‘s The line preceding each chat String color

Name message from another user
displays that user ’s name.

My User Name The line preceding each chat Keyword color

message that you send
displays your user name.

Status Messages Messages showing changes Comments color

in connection, control, etc.

User Maintenance
Press the User Options button or right-click within the Buddy List to display a
popup menu of user-related items.

Adding a User or Modifying User Settings

The user who initiates a chat or file sharing session must first add the other user(s)
for CodeMeeting purposes. When you receive a call from a new user, the user is
automatically added to your Buddy List.

14- File Support and Sharing 383

To add a user to your Buddy List or modify a user ’s settings, refer to the following:
n To add a new user on your system, right-click in the Buddy List and select Add
New User.
n To modify an existing user ’s settings, double-click on the corresponding user
name, or right-click on the name and select User Settings.
The following dialog displays:

CodeMeeting User Settings

n For a user on your local area network, the Computer Name and Port Number
are usually sufficient information to make a connection. The Port Number you
enter for a remote user must match the one he has selected for his own in order
for you to initiate a connection with him. The default Port Number is 55555.
n If the other user is not on the local area network, enter the IP address of that
person’s machine (e.g. 192.111.111.11), along with the Port Number that person
has chosen for his own.
Note: If two users are on different local area networks (LANs), they will
probably need to take one of the following measures to establish a
connection, due to the fact that LANs are usually connected to the
Internet through a firewall:
3 Have the computer that receives the request for connection be
connected directly to the Internet (with no firewall).
3 Before making a CodeMeeting connection, have the computer
outside the LAN establish a virtual private network (VPN)
connection to the LAN of the other user.
n The Screen Name is the name that identifies a user in the Buddy List and Chat
Window on other connected users’ systems.

384 14- File Support and Sharing

Updating Your Own User Settings
User settings that you have configured for your own user name are transmitted to
other users each time a connection is established, updating the connected users’
settings for you automatically. Your records for other users are similarly updated.

Deleting a User
To delete a user from your Buddy List, right-click on the user name and select Delete
User, confirming your decision at the prompt.

Connecting to Other Users

Press to make yourself available for connection. When users are available, their
names appear in a bold font in the Buddy List. The state of this button is saved
between sessions to allow users to automatically be available whenever CodeWright
is running.
Notes: To have CodeMeeting update the status of other users when they
become available during a session (making their user name bold in
the Buddy List), select the option Show remote presence changes on
the CodeMeeting Configuration dialog.

Creating a Connection
To create a connection, complete one of the following:

n Press to create a connection with the selected user.

n Highlight the user ’s name in your Buddy List. Right-click, or press , and
select Make Connection.

When the button is depressed , the selected user is connected and the word
(Connected) follows their user name in the Buddy List.

If CodeWright is not the active application when a connection request (or chat
message) arrives, the CodeWright title bar and Windows Taskbar will flash, and a
balloon will pop up at the lower-right hand portion of your monitor. Click on the
balloon to dismiss it and activate CodeMeeting.

Posting Away from Desk Message

Press to indicate that you are away from your desk for CodeMeeting purposes.
The message “Away from desk” will be appended to your user name in the Buddy
List of each connected user.

14- File Support and Sharing 385

Ending a Connection
The connection can be ended at any time by either user. To end a connection,
complete one of the following:

n Highlight the user ’s name in the Buddy List and press .

n Highlight the user ’s name in the Buddy List. Right-click on the name, or press

, and select Close Connection.

Sending Messages
Once you have connected to one or more users, use the CodeMeeting “chat”
functionality to carry on an interactive, real-time conversation online. Note the
following:
1. Type each message in the Chat Input box at the bottom of the CodeMeeting tab,

and press or [Enter] to send the message. Your user name and the text of the
message will then display in the Chat Window.
2. Look for responses in the Chat Window, preceded by the sender ’s user name.
Note: Remember that the color of chat messages, user names, etc. is
controlled by the View Theme you select on the CodeMeeting
Configuration dialog.

Broadcast vs. Private Chat

If you wish to send your message to a single user, select the user's name in the Buddy

List and de-select the Broadcast button . The word "private" and the selected
user's name will display after your user name for each transmission to indicate that
you are having a private conversation.
3 If you do not have a user selected when you initiate a private chat, or the
selected user is not available, you will be prompted to choose a user name on
the Pick a Connected User popup dialog.

If the Broadcast button is depressed (the default), your message will be broadcast to
all connected users.

Notification of Incoming Message

To hear an audible beep when you receive a chat message (and CodeWright is
active), mark Beep when Chat Messages Arrive on the CodeMeeting Configuration
dialog.

386 14- File Support and Sharing

If CodeWright is not the active application and you receive an incoming Chat
message (or connection request):
n The CodeWright title bar and the Windows Taskbar will flash.
n A balloon will pop up at the lower-right hand portion of your monitor.
Click on the balloon to dismiss it and activate CodeMeeting.

Sharing Documents
CodeMeeting gives you the power to share documents with multiple CodeWright
users. Grant other users the ability to view or edit the current document in your
CodeWright edit window, or review their files on your machine. Document sharing
works for any remote or local user to whom you can make a successful connection.

If you are sharing another user ’s document, note that its title is followed by
“CodeMeeting” and the name of the document’s owner to remind you that the
document is being shared.

Document Sharing with CodeMeeting

The following paragraphs describe the document sharing functionality of

CodeMeeting.

Begin or End Document Sharing

Press to begin or end sharing for the current document. If the button is
depressed, it indicates that the current document is shared; the document name is
shown beneath your user name in the Buddy List of all connected users.
Another user ’s document name can be preceded by one of the following icons:

14- File Support and Sharing 387

3 The icon indicates that the shared document is currently open.

3 The icon indicates that the shared document is available, but not currently
open.

Press again to end sharing; the document remains open only on your machine.
A non-owner can begin sharing a document by clicking on it in the Buddy List. The

non-owner presses to end sharing for the current document on their own
machine. The document will still be listed in the Buddy List, but closes on the non-
owner ’s machine.

Editing Control
Press to request/grant editing control of the document you are sharing.

When you request control, a dialog may appear on the other user ’s machine
allowing him to accept or decline releasing control (provided the other user has
marked Prompt before allowing remote editing on the CodeMeeting Configuration
dialog).

If the button is depressed, you have editing control. You can then press again to
grant control to a remote user (they will be notified by a message in the Chat
Window).
3 If you do not have a user selected when you attempt to grant control of the
current shared document, or the selected user is not available, you will be
prompted to choose a user name on the Pick a Connected User popup
dialog.

Per-Document Basis
Control over editing is on a per-document basis. The document owner has
initial control. To the user who has control, shared editing is just like normal
editing. Changes will be reflected on the systems of all users who are sharing
the document.

Reloading a Document
The document owner can invoke File|Reload to reload their file and abandon
another user ’s changes. Conversely, a non-owner who has made changes to a
file cannot reload the file to abandon their own changes.

388 14- File Support and Sharing

Following Along when Switching between Documents

Press to follow along when the selected user shares documents and switches
between them.

If you do not have a user selected when you press this button, or the selected user is
not available, you will be prompted to choose a user name on the Pick a Connected
User popup dialog.

Following Along in the Current Document

Press to follow along within the current document when you are not in control
of editing. The document and its attributes will change to match those of the user
who has the control. All users who have locked the document see the same display
mode (i.e. normal, hex, wrapped, and selective display), invisible lines, current
position and any selection within the document.

Select Beep in locked documents on the CodeMeeting Configuration dialog to have

CodeMeeting beep when you attempt to edit, change position in, or change display
attributes for a locked document.

If the button appears unlocked , you are free to view the shared document as
you wish.

14- File Support and Sharing 389

390 14- File Support and Sharing
15- Large Files
CodeWright can accommodate files as large as 2 Gigabytes. Any file over 1 MB is
considered a large file. There are several ways to configure CodeWright to make it
more stable and efficient when working with large files. Among these are:
n Manipulating swap blocks.
n Turning off backup files.
n Turning off scroll bars.
n Preloading files.
n Turning off ChromaCoding.
n Using the File Rewrite Save Method for saving files.

Swap Blocks
CodeWright uses swap blocks to manage the memory allocated for an open, active
file. CodeWright is fairly conservative about the amount of memory it initially
allocates (100 8K blocks). When all of the swap blocks initially allocated are used up,
CodeWright starts swapping to disk. If you regularly work with large files, and you
have plenty of memory available, you should consider increasing the number of
swap blocks used by CodeWright.
Example: The default for swap blocks is 100 8K-swap blocks. You may want
to try increasing this (the maximum is 8192).

How to Change the Number of Swap Blocks

Set the number of swap blocks in your configuration file (CWRIGHT.INI) located in
the CodeWright home directory. Find the [Editor] section of this file and insert a
line under that heading similar to the one shown below, then restart CodeWright for
the changes to take effect:
[Editor]
SysSwapBlocks=200

15- Large Files 391

Block Size
The size of the swap block (discussed above) can be increased using the command
line switch:
-BlockSize=
When the size of the block is increased, fewer blocks are needed, expanding
CodeWright's capacity for handling longer lines and larger files. The default block
size is 0x2000 (8192) but the range can be from 0x1000 to 0xf000 (4096 to 61440
decimal).
n The default block size (0x2000) allows a single 500-Mb file to be opened and
edited in CodeWright.
n Increasing the block size to 0x8000 will allow a single 2G file to be opened and
edited, or two 1G files.
n Increasing the block size more will allow additional large files to be loaded, but
2G will still be the individual limit.

As block sizes increase, the speed of some edit operations may change somewhat.

The -BlockSize= parameter should be used from the CodeWright shortcut

command line, a DOS command line, or any of the Sync program command lines.
n To modify the command line for the CodeWright shortcut:
1. Right-click on the shortcut and choose Properties.
2. Click on the Shortcut tab.
3. In the Target edit box, add -BlockSize=0x8000 after the CW32.EXE.
Example: C:\CW32\CW32.EXE -BlockSize=0x8000
n Do the following to run the "-BlockSize=" from any of the synchronization
configuration dialogs:
1. Run the Synchronization Configuration dialog for a synchronized
environment. The synchronization configuration settings are accessed
in VCSync.exe for MSVC, and under the About CodeWright Help
menu item in the synchronized environment associated with other
sync programs. See the chapter Synchronization.
2. After the full path name for CodeWright, e.g., "C:\CW\CW32.EXE", add
the -BlockSize= parameter.
Example: C:\CW32\CW32.EXE -BlockSize=0X8000
The 0x8000 setting can be any setting within the limits described
above.

392 15- Large Files

Consider Your Resources
You should consider how much memory is available on your system and how big
your block size is before changing the number of swap blocks. You will know that
you have made the number too high if you begin to see degradation in the
performance of Windows itself. Short of that, if CodeWright is the only application
you are using, you can be pretty generous with swap blocks.

Backup Files
You may not wish to have CodeWright make backup copies when working with very
large files. In most cases this can be both a waste of time and disk space.

To turn off backups for a specific file type, complete the following steps:
1. Choose the Tools|Customize|Language|Options dialog

Tools|Customize|Language|Options

2. In the Customize dialog navigation tree, select the file type(s) for which to turn
off backups.
3. Unmark the box labeled Make backups in the Document Options group.

Scroll Bars
To edit large files as soon as you load them, turn off scroll bars. It is too late to turn off
scroll bars after you have loaded the file, so you will want to make No Scrollbars the
default. To do this:
1. Select Tools|Customize|View Themes|General.

15- Large Files 393

 Tools|Customize|View Themes|General

2. In the Window Attributes group, make sure that the Vertical Scrollbar and
Horizontal Scrollbar boxes are unchecked.
3. Click OK.

Pre-loading Files
When CodeWright pre-loads files, it loads the file completely into virtual memory,
which can slow things down if the file being loaded is fairly large. There are two
options that enable the CodeWright feature for pre-loading files. Make sure the
options are not marked if you want CodeWright to handle large files more efficiently.
To disable the preloading options:
1. Select the Tools|Customize|Environment|File Options dialog.

Tools|Customize|Environment|File Options

2. In the File Loading/Reloading section, make sure the options Preload file on
open and Preload non-local files on open are unchecked.

394 15- Large Files

When the options are turned off, instead of loading the whole file into memory,
CodeWright only loads as much of the file as necessary for editing and maintains
pointers to the original file. See the chapter on File Support and Sharing for more
information.

Turn off ChromaCoding

If speed is of the utmost importance when loading large files, you could optionally
turn off ChromaCoding, the feature that colors programming language syntax
structures.

To turn off ChromaCoding:

1. Select the Tools|Customize|Language dialog.
2. Select the file type being edited in the Customize dialog navigation tree.
3. Click on the Coloring tab.

Tools|Customize|Language|Coloring

4. Uncheck the following features in the ChromaCoding section:

n Changed Lines, which causes CodeWright to color lines that have been
changed.
n Language Dependent, which causes CodeWright to color files according to
the syntax of a particular programming language.

Saving Large Files

The default file saving method in CodeWright is not the preferred method for saving
large files. For large files, use the File Rewrite Save Method. Both saving methods
are described in this section.

15- Large Files 395

Default File Saving Method
The default method CodeWright uses to open and save files works in the following
way:

Given a file, FOO.C

n Open FOO.C into CodeWright.
n CodeWright creates FOO.000 as a temporary file.
(the .000 extension will be .001 if .000 already exists, .002 if .000 and .001 already
exists, and so on.)
n If CodeWright is set to make backups, FOO.C is renamed to FOO.BAK. If the
option to make backups is not turned on, FOO.C is deleted.
n When the file is saved, FOO.000 is renamed to FOO.C.

File Rewrite Save Method (for Files over 1MB)

The File Rewrite Save Method is simpler than the default saving method. It works in
the following way:
Example: Given a file, FOO.C
n Open FOO.C into CodeWright.
n If backups are turned on, FOO.C is copied to FOO.BAK. If not,
nothing happens.
n When the file is saved, the changes are written back to the
original file.

The File Rewrite Save Method offers the following advantages when saving large
files:
n Space normally needed for the temporary file (foo.000) is no longer required.
This minimizes the amount of memory needed when opening the file.
n Since the File Rewrite Save Method only writes out the changes made to the file
(as opposed to rewriting the whole file), the portions of the file that haven't
been modified won't be rewritten, reducing the time needed to save the file.

To turn on the File Rewrite Save Method:

1. Select the Tools|Customize|Environment|File Options dialog.
2. In the File and File System section, put a checkmark in the Use file rewrite save
method option.

396 15- Large Files

16- Extend CodeWright
CodeWright is a fairly complete product. There is not much that it lacks.
Nevertheless, there always seems to be one job for which necessary tools just can't be
found. If this is the case, CodeWright has some tools for extending the CodeWright
program.

CodeWright extensibility tools consist of three macro languages (Perl, AppBasic, and
API Macros), and CodeWright DLLs that can be loaded interactively from the
Tools|Customize|Libraries dialog. The tools are provided in the event that
CodeWright doesn't already have the necessary functions for handling the task at
hand. They can be used together (i.e. a macro that uses a function from a DLL or
another macro, or vice versa), or on their own.
3 The advantage of using macros is that they can be used on the fly, without the
added complexity of compiling.
3 The advantage of using DLL Add-Ons is that they are more flexible, and can be
written in any programming language that is capable of creating DLLs.

This chapter first describes some of the more technical aspects of using the
CodeWright API from the Command Key. It then goes into detail about Perl,
AppBasic, and, API Macros. Finally, it provides some details on creating a keymap
command set. For information on DLLs, refer to Appendix B - Making and Modifying
CodeWright DLLs.

The assumption going into this chapter is that the user has some familiarity with
CodeWright. In particular, it is assumed that there is some familiarity with the
CodeWright API, and the methods used to assign API functions to keystrokes,
buttons, and/or menu items.

CodeWright API
CodeWright has a multitude of API functions that can be used interactively from
within the interface (i.e. from Tools|API Command, or attached to menu items,
buttons, or keystrokes). APIs can also be used in custom macros and DLLs designed
for extending CodeWright. Various chapters in this manual have discussed the
process of using APIs from within the CodeWright interface.

16- Extend CodeWright 397

The remainder of this section discusses the use of CodeWright APIs from the
Command Key (Tools|API Command) more extensively. Help and examples for
most CodeWright APIs can be accessed in CodeWright online help
(Help|CodeWright API Library).

Using the API from the Command Key

The CodeWright Command Key was described earlier in this manual, in the chapter
on Command Key, Libraries, & Environment. This section will describe some of the
more technical aspects of using the Command Key. Remember that the Command
Key is [F9] if you are using the CUA or vi keymap command set, [F2] for the Visual
Studio .NET command set, and [F10] for BRIEF. In keymaps where there is no Key
Command assignment, selecting Tools|API Command will always access the
prompt.

To use the CodeWright API, you need to at least know the name of a function you
want to execute. The online help (Help|CodeWright API Library) is the place to
learn more about the CodeWright API and specific functions.

If you are trying to avoid learning any more about the CodeWright API than you
have to, make sure you have checked various dialogs and menu entries to see if what
you are trying to do can be done through a menu.

Displaying Return Values With the Command Key

Many CodeWright APIs that have return values are much more useful if the return
value can be accessed or viewed. To get the Command Key prompt to display the
return value of a function, begin the command with a question mark.

Here is an example of how such a command might look, just before sending the
command off for processing:

?BufQModifiedCount

When the return type is a numeric value, CodeWright displays that number on the
status line in both decimal and hexadecimal notation. If the return type is a pointer
to a string, CodeWright displays the contents of that string.

Running Multiple Commands

It is possible to use the Command Key to execute multiple functions and expressions
at once. The functions and expressions can be nested or separated by commas. They
must be preceded by an asterisk (*) and surrounded by parentheses.

398 16- Extend CodeWright

 Example: When run from the Command Key, the following nested functions
will find and attach the buffer 'test' to the current window, if ‘test’
exists.
*(WinAttachBuf(WinQCurrentWindow(),
BufFindBuffer("test")))
The asterisk causes functions and expressions that are inside the parentheses to be
passed to the CodeWright API MacroExecMultiple.
If the asterisk is also preceded by a question mark (?), the results of the expression
will be displayed on the CodeWright status bar.

Examples of Command Key Usage

All three of the examples below do the same thing. They put CodeWright in the Hex
Editing mode, with the cursor located in the "binary" portion of the display:
n BufSetHexBinary
BufSetHexBinary()
bufsethexbinary

The examples below advance the cursor position by two characters:

n MovNextChar( 2 )
Movnextchar 2

The commands below will open a document for C:\PROJECTA\DEBUG.C.:

n BufEditFile( "c:\projecta\debug.c" )
bufEditFile "c:\projecta\debug.c"
BufEditfile=c:\projecta\debug.c

The following example assigns the function BufSetHexAscii to the keystroke

[Ctrl]-[A].
n kmapAssign( "<ctrl-a>", "BufSetHexAscii" )

The example below begins an inclusive selection, using one of the labels listed in the
online help:
n MarkBeginSel( SELECTION_INCLUSIVE )

Command Key Evaluation of Expressions or Constants

You may begin your command with two question marks '??' to return the value of a
constant or arithmetic expression. With expression evaluating, a numeric expression
that uses C language operators and grouping can be evaluated, or calculated, from
within the Command Key prompt and the Command Key will in turn display the
results. CodeWright identifiers can be used in these expressions. Here are examples
of expressions to be evaluated:

16- Extend CodeWright 399

??SELECTION_INCLUSIVE
??0xcf54-3*4
??MARK_GLOBAL+1
The following operators are supported in expressions, grouped by precedence, and
listed in order of decreasing precedence:

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

400 16- Extend CodeWright

For many users, using CodeWright API functions from the API Command Key is the
first step toward truly customizing and extending CodeWright. Once users see how
quickly they become comfortable with the CodeWright API, they want more. Soon
they start using them in CodeWright macros and custom DLLs and subsequently
delving into the DLL source code for more (supplied in the CodeWright SDK). Read
on to find out how to get the most out of the CodeWright API by using API functions
in CodeWright macro languages and DLLs.

Macros, Macro Languages and DLL’s

The most powerful way to customize CodeWright is through the use of its three
macro languages, and by creating and customizing its DLLs. The following sections
discuss and compare these methods for expanding the CodeWright program.

Macros and Macro Languages

A macro might be defined as something simple that represents something bigger or
more complex. Under this definition, macros include everything from keystroke
recordings that are assigned to keys, and the % macros CodeWright uses in
command lines, up to more sophisticated things written in programming languages.

A Macro Language provides a method for creating macro source code, which may
contain control structures and variables. Macros are normally interpreted at
runtime. CodeWright has three macro languages for extending its program.
The following table describes some pros and cons for the languages. The languages
themselves are discussed in the sections Perl, AppBasic, and API (C-like) Macros.

16- Extend CodeWright 401

Read on to determine which language is best for you.

Macro Strengths and Weaknesses

Language

Perl Macros Perl, along with JavaScript, is perhaps the most popular
language for writing extensions to web pages. The
syntax is similar to C or AWK, but it has many built-in
features for the Internet.
Perl is least suitable for writing simple functions for
assignment to keys because of the time it takes for the
interpreter to initially load. It does, however, allow Perl
programmers to program in a familiar language, using
familiar extensions and libraries. The CodeWright
version of Perl is based on the Gnu-released Perl
interpreter. You'll find it on a tab of the Output
Window (by default) once you have loaded the
appropriate library.

AppBasic Macros AppBasic is the CodeWright macro language that is

similar to Microsoft Visual Basic for Applications. It has
its own editor, debugger, and basic functions. You'll find
it on a tab of the Output Window (by default) once you
have loaded the appropriate library.
Using this macro language, you can access functions in
the following locations:
n The Microsoft Windows API.
n All of the CodeWright API functions, except those
designated as non-interactive.
n Functions in most any external DLL.
For those who are familiar with Basic in any of its
various forms, this is an attractive option for both simple
and complex macros.

API (C-like) The CodeWright API Macro language is the simplest of

Macros the available macro languages. Using C-like structure
and syntax, it allows you to quickly create functions
suitable for assigning to keys and other simple uses.
When writing an API Macro, you can use any function
that is available from the API command line.
You can write API Macros in the Tools|API Macros
dialog, or you can write them in a standard CodeWright
edit windows.

402 16- Extend CodeWright

DLL Extensions
You can write extensions for CodeWright using any compiler that can produce DLLs.
We refer to this capability as DLL Extensibility. Many sophisticated extensions can be
written using DLL Extensibility. This method of extending CodeWright has the
following benefits:
n Familiar compiling, and debugging tools,
n Unbeatable speed, and
n Access to functions in other DLLs and libraries.

DLL Extensibility, however, may not be as convenient as other methods of extending

CodeWright:
n It is not as convenient for simple jobs, or single-use programs.
n It provides little protection against user error, which could cause a system crash.
n It needs its own, separate compiler, which doesn’t come with CodeWright.
Note: In CodeWright version 7.5 and above, source code modules
previously distributed with CodeWright are sold separately as the
CodeWright SDK. If you would like to obtain these modules for
further customization or extensibility, please contact a Sales
Representative at [email protected]. For more details on DLL
Extensibility, refer to Appendix B - Making and Modifying CodeWright
DLLs, in this manual.
Keep these things in mind as you consider extending CodeWright using DLLs or one
of the supplied macro languages (Perl, AppBasic, and API).

Where is it Defined?
Once an extension has been created (whether the extension is a macro or a DLL),
there is an opportunity for confusion as to exactly where the function being executed
is coming from. It could be a CodeWright built-in function, a CodeWright DLL
function, an AppBasic macro, a Perl sub, a keystroke macro or an API macro. The
command LibFunctionExistsWhere() helps resolve the ambiguity.

The LibFunctionExistsWhere command returns an allocated string identifying the

location of the function name that is supplied as its argument (0 is returned if it
doesn't claim the function).

16- Extend CodeWright 403

Listed below are a few sample responses:

Function Response

BufQCurrentLine Built-Ins:BufQCurrentLine

DlgPrint cwdialog:DlgPrint

MyPerlFunc cwPerli:myPerl!MyPerlFunc

_jav_init _jav_init->cwstart:_java_init

The last example shows the response where a replacement function exists. The Perl
example shows that both the Perl script filename and the sub name are given. For
non-LibExported functions, i.e. those connected by responding to
EVENT_LIB_EXISTS_FAILED and EVENT_LIB_EXEC_FAILED, the 'where' string
is supplied by the responder to a new event EVENT_LIB_EXISTS_WHERE.

Perl
This section describes the CodeWright Perl macro language.

There are two useful ways of looking at a Perl script. One is to look at Perl as an
entity that may be executed in its entirety to perform the task specified by the
operations of the script. Another way of looking at the script is as a collection of
macros, each subroutine being a macro in its own right. Using Perl with
CodeWright, you can make use of CodeWright custom facilities that reinforce these
views as needed. They are described under the topic Loading and Running Scripts.

If you have not already installed a command line version of Perl, we have included a
copy of the ActiveWare 3.15 build of Perl 5.0 for Win32, PW32I315.EXE in the
\PERLW32 directory on the CodeWright CD.

Getting Started with Perl

There are two loadable DLLs necessary to use Perl with CodeWright: the Perl
interpreter and the Perl language support DLL. To enable these modules, go to
Tools|Customize|Libraries and select two checkboxes: Perl Extension Language
Interpreter and Perl Language.
Note: Updating your version of Perl should not pose any problems, nor
have any effect on the CodeWright Perl interpreter. The CodeWright
Perl interpreter has been modified for use with CodeWright, and is
completely independent of any other Perl interpreter that may be
installed on your system.

404 16- Extend CodeWright

If the Output Window is not already showing, select Perl from the Window|Output
submenu. You should then see a Perl tab on the Output Window.
3 Even if you have Perl already installed on your system, you must make the Perl
tab visible on Tools|Customize|Libraries to enable the Output Window's Perl
tab.

The CWP.DLL is a Perl extension module that provides access to CodeWright API
functions from within Perl scripts. In general, you can use any of the CodeWright
API functions listed in the online help, except for those whose data types are
incompatible with Perl. For a list of available CodeWright API functions, see the
contents of the CWP.PM file.

Creating and Editing Perl Scripts

Perl scripts can be created and edited in standard CodeWright edit windows. There
are some sample Perl script source files in the CodeWright \MACROS subdirectory.
Load a few of these and have a look.

Perl scripts are usually packaged in text files bearing a .PL extension. A Perl script
consists of a 'main' section, and zero or more subroutine definitions. The main
section is defined as any code not contained within subroutine definitions.
Example: The following Perl macro contains everything in its main section:
use CWP;
$filename = CWP::BufQFilename;
$filespec = "%p%r%e";
$newname = CWP::TransformFilename($filename,
$filespec);
$newname =~ tr/\\/\//;
$newname =~ tr/A-Z/a-z/;
CWP::LibFunctionExec "SetStringMacro(UNIXFILE,
$newname, 0)";

Supplied Perl Macros

CodeWright comes with a number of sample Perl macros that can be used as starting
points for creating custom macros. The macros are contained in files with .PL
extensions. They are located in the \MACROS subdirectory of the CodeWright
installation directory.

Perl Window
The Perl tab on the Output Window acts as a virtual console for the Perl interpreter.
That is, it replaces the stdin, stdout, and stderr devices. You can scroll through the
output of Perl scripts in this window. There is a limit on how many lines of output
will be retained in this window. The default is 100 lines. You will find this setting in
the Tools|Perl Macros|Properties dialog.

16- Extend CodeWright 405

To help distinguish stdin, stdout, and stderr elements of the Output Window,
CWPerl uses three different colors.
n stdout is displayed using the output color.
n stdin is displayed using the color defined for line numbers.
n stderr is displayed using the color designated for comments.

You can find the settings for these colors on the Tools|Customize|View
Themes|Colors dialog, for the View Theme labeled “Output Window”.

Popup Menu and Options

When you right-click on the Perl tab of the Output Window, a popup menu provides
a number of additional options. If you don't find what you are looking for on the
Tools menu, check out this menu.

The Properties item on the popup menu brings up a dialog that lets you control how
Perl interacts with CodeWright. This is where you specify options you would
otherwise provide to Perl on its command line, when invoking it from the shell
prompt.

There are a variety of choices from which to select an input source and output
destination including the Perl Window, the current buffer, the clipboard, the current
scrap buffer, and the current selection.

Different combinations of source and destination can produce interesting effects.

Example: If Current Document is selected for both source and destination, a
Perl script will see the entire content of the current document as its
stdin and the buffer will be replaced with stdout.

You can accomplish a similar operation on the contents of a selection choosing

Selection for both source and destination.

Input source and output destination can also be set from within a Perl Script. See the
file UPCASE.PL in the \MACROS subdirectory of the CodeWright installation
directory for an example of how this is done.

Online Help
The Perl Manual by Larry Wall is supplied in online form, in the help file PERL.HLP.
The topics in this file are part of the CodeWright standard help system. This means
that you can get Perl function help by placing the cursor on the name of the function
and pressing C!. You can also press ! with the cursor in the Perl Window to
get other Perl help.

406 16- Extend CodeWright

Loading and Running Scripts
There are two different ways to run a Perl script in the Perl tab of the Output
Window. You can load the script directly on an as-needed basis, or you can load a
Perl macro and run it any time you wish.

Running a Script Directly

You can load and execute a Perl script from the CodeWright API Command Line by
using the command PerlExec or PerlExecSub. Note that both commands require
you to either specify a fully qualified path to the script, or to run scripts that reside in
the CodeWright current working directory. You can set the working directory to that
in which the script resides from the File|Change Directory dialog.
To load and execute the script filename.pl:
PerlExec filename.pl

If you only want to execute a specific subroutine in a script use:

PerlExecSub filename.pl subname

In both of these cases, you may include additional 'command line' parameters. All
text following the syntactical elements shown in the two commands is broken down
into 'parameters' using normal CodeWright command line parsing rules, with
respect to spaces, quotes, escapes, etc.

If you just want to execute a simple Perl script that can be typed in one line use:
PerlExecStr 'Perl-string'

These commands will load the script, execute it, and unload it automatically.

Loading a Perl Macro

Loading a Perl macro is much the same as running a Perl script directly, with the
added advantage of being able to invoke the subroutines of the script individually
by simply typing them at the command line.

There are three ways to load a macro:

n Go to the Tools menu and select Perl Macros... and then select Load macros.
3 Select Perl macros supplied by Borland by checking the appropriate box in
the top of the dialog in the area called CodeWright macros.
3 Any Perl macros stored in the CW32\MACROS directory will show up in
the CodeWright macros list.
3 Add user-defined macros from here by pressing the Add button.

16- Extend CodeWright 407

n Another way to load Perl macros is by right-clicking the Perl tab in the Output
Window and selecting Interpreters. This brings up the CodeWright Perl
Interpreters dialog. Load the macro by pressing the Load... key. All subroutines
for the loaded macro (including <main>) are automatically displayed when you
select a macro from the list. You may select an individual subroutine from the
list to run.
n Use the CodeWright API command PerlLoad. Note that PerlLoad requires you
to either specify a fully qualified path to the macro, or to run macros that reside
in the CodeWright current working directory. Run the command:
PerlLoad <filename>

Running a Perl Macro

Once the macro is loaded, you can invoke it by going to the CodeWright API
Command Line and entering the name of the subroutine. As previously mentioned,
you may also run the subroutine as follows:
1. Right click the Perl tab and select Interpreters.
2. Select the macro from the list.
3. Select the desired subroutine and press Run.
4. Enter parameters at the resulting prompt, or hit return to run without them.
You can also run a macro using the command PerlRun. Note that PerlRun requires
you to either specify a fully qualified path to the macro, or to run macros that reside
in the CodeWright current working directory.
Examples: If the macro gotoline.pl resides in the current working directory,
you could run the macro using the command:
PerlRun gotoline.pl
If this command is issued as shown, the 'main' of the script will be
executed. Alternately, you can give a subroutine name thusly:
PerlRun gotoline.pl subname
As with previous commands, parameters may be supplied following
either form, however, the first form will need an extra empty string
("") to represent the 'main' function.
If gotoline.pl does not reside in the current working directory, you
would need to include its directory path. If the path contains spaces,
enclose the path in double quotes.
For example:
PerlRun C:\cw32\Macros\gotoline.pl

PerlRun “C:\Program Files\Borland\CodeWright\

Macros\gotoline.pl"

408 16- Extend CodeWright

Accessing CodeWright Functions from Perl Scripts
Over 1000 CodeWright functions can be directly accessed from within Perl scripts in
CodeWright. To do so, the following line must be placed at the top of the script:
use CWP;
This tells Perl to load CWP.PM, which contains descriptions of functions contained in
the compiled Perl extension module CWP.DLL. The CWP.DLL consists of small C
functions that call the CodeWright functions after first preparing the parameters and
then make the return value, if any, available to Perl.

You'll need to use the CWP:: prefix on CodeWright functions to reference them,
unless you take further steps (described later). This prefix tells Perl that the
following function name is present in the CWP module. As an example, to find out
where the cursor is on in the current document, you could use the CodeWright
BufQCurrentLine API in the following manner:

$line = CWP::BufQCurrentLine();

Constants that are held in the CodeWright lookup table can be accessed using a
special function. For example, to see if there is a column selection present you could
use:
if (CWP::MarkQSelType() ==
CWP::CWConst("SELECTION_COLUMN"))
{
}
A special function is also provided to execute any built-in or any function made
available through LibExport. This function is similar to the CodeWright API function
LibFunctionExec. An example follows:
CWP::CWExec("ConfigFileRead", "[Editor]", 0);
This is equivalent to:
CWP::LibFunctionExec("ConfigFileRead [Editor] 0");
The primary difference is that in the latter example, the string will be parsed to
separate it into parameters to be passed to the function. In the former, the
parameters are explicitly segregated.

Importing Names into the Perl Namespace

If you have CodeWright functions that you access frequently and their names don't
conflict with standard names, you can save some typing by telling Perl that you want
certain names imported into the Perl namespace.

16- Extend CodeWright 409

To import names into the Perl namespace, modify the use command as follows:
use CWP ("LibFunctionExec", "CWConst",
"BufQCurrentLine");
or, equivalently:
use CWP qw(LibFunctionExec CWConst BufQCurrentLine);
The latter 'quoted word' shorthand obviates the need to type so many quotes. After
doing this, the named function may be invoked without the CWP:: qualifier.
$line = BufQCurrentLine();

Unloading a Perl macro

When you no longer need an interpreter it can be deleted with:
PerlUnload filename.pl

Using Perl Debug Mode

There is a debugger supplied for Perl scripts. The debugger is itself a Perl script
(PERL5DB.PL). When invoking Perl from a prompt, this script is automatically
loaded if you use the -d flag. In CodeWright, you accomplish the same thing by
checking the Debug Mode checkbox in the Perl Properties dialog (right-click the Perl
tab).

When running a script in debug mode, there are three important requirements:
n You should only use debug mode when invoking scripts with PerlExec on the
API command line.
n The script must not already have been loaded by CodeWright prior to using the
PerlExec command (meaning the script cannot be loaded from the Interpreters
box or by the Tools|Perl macros...|Load macros... popup dialog). If it is loaded,
unload it before attempting debug mode.
n Ensure that you have completed executing the script in debug mode before
attempting to run the script again.

Accessing Perl Functions

You can also execute the subs of loaded Perl interpreters merely by typing their
names on the CodeWright API Command Line. CodeWright has a mechanism to
allow Add-Ons to respond to indicate their recognition of otherwise unknown (to
CodeWright) function names. The AppBasic interpreter and the Perl interpreter
alike respond to these queries.

410 16- Extend CodeWright

This means that if you have a Perl script loaded that contains a sub called
MyPerlFunc, you can execute that function simply by typing MyPerlFunc at the
CodeWright API Command Line. Perl will check all the loaded Perl scripts to see if at
least one of them has the named subroutine.

Avoiding Ambiguity
The same subroutine name may appear in several Perl scripts. CodeWright therefore
provides a mechanism to specify which Perl script you're referencing.
Example: Suppose that both SCRIPT1.PL and SCRIPT2.PL have a sub
MyPerlFunc. You don’t know which subroutine will be executed if
you simply invoke MyPerlFunc.
One way to avoid this problem is to right-click the Perl tab and bring up the
Interpreters dialog. Select the script you intend to call, and click its subroutine in the
subroutine list.

Another way to specify that you wish MyPerlFunc in SCRIPT2.PL to be executed, is

to invoke it as follows:
script2.pl!MyPerlFunc
(Note that the extension .PL used in this example is optional.)

Without this specific invocation, the loading order usually determines which
function will be executed if both an AppBasic script and a Perl script contain a given
function name.
3 Generally, the first macro loaded will be the one to execute.

Special API Functions for Perl

In addition to the 1000 or more functions available from the CodeWright API, there
are three additional functions available when the Perl Extension Language (CWP) is
loaded.
n DWORD CWConst(LPSTR cw_expr);
This function provides access to CodeWright constants (predefined values), and
any "constants" you have defined with EvalAddStr, in Perl scripts. For example,
you may want to begin a line selection. To do this you would use the constant
SELECTION_LINE in a call to MarkBeginSel.
A more specific example follows:
CWP::MarkBeginSel(CWP::CWConst("SELECTION_LINE"));
The argument string to CWConst can take any form that is acceptable to the
CodeWright function EvalExpression.

16- Extend CodeWright 411

n DWORD CWExec(LPSTR cw_funcname, ...);
This function provides an alternate form of executing a CodeWright function
that has been made available via LibExport(), i.e. all functions provided by
DLLs, both standard and Add-On. The advantage to using this form, rather
than LibFunctionExec(), is that you needn't compile the arguments that you
wish to pass into a string as is required by LibFunctionExec().
You could, for example, issue either of the following commands with the same
effect:
CWP::LibFunctionExec("BufQOffsetEx", $line . " " .
$column); OR
CWP::CWExec("BufQOffsetEx", $line, $column);
n int CWPerlIO(int mode);
This function is used to query or set the current Perl I/O mode. You may recall
from the Perl Properties entry of the Perl popup menu that you can set the Perl
input source and output destination using the radio buttons. This function
serves the same purpose.
The mode argument has two components:
3 Input source: occupies the least significant 8 bits of the mode value.
3 Output destination: occupies the next most significant 8 bits.
The semantics of the components are as follows:
// Perl I/O source/destinations
#define PERL_IN_CON 0x0000 // input from 'console'
#define PERL_IN_BUF0x0001 // input from current buffer
#define PERL_IN_SEL0x0002 // input from selection
#define PERL_IN_CLIP0x0003 // input from clipboard
#define PERL_IN_SCRAP0x0004 // input from scrap buffer
#define PERL_OUT_CON0x0000 // output to 'console'
#define PERL_OUT_BUF0x0001 // output to current buffer
#define PERL_OUT_SEL0x0002 // output to selection
#define PERL_OUT_CLIP0x0003 // output to clipboard
#define PERL_OUT_SCRAP0x0004 // output to scrap buffer

To determine the current I/O mode, simply call CWPerlIO with a mode value of
-1. In all cases, the return value is the prevailing 'mode' immediately prior to the
call. This function is useful to make a Perl script that responds differently
depending on certain prevailing conditions.

412 16- Extend CodeWright

 3 The call to CWPerlIO should be made before any output operations are
performed, since changing the output destination causes all previous
output to be discarded.

Files used by Perl for CodeWright

These files are found in the CodeWright home directory after installation:

Filename Purpose

CWPERL.DLL Provides language support for Perl source scripts (*.PL).

CWPERLI.DLL Adds the Perl tab in the Output Window.

CWPERLI.MNU Menu file that holds the menus for the right mouse click in
the Perl tab of the Output Window.

These files are found in the CodeWright \PerlLib subdirectory after installation:

Filename Purpose

CWP.DLL Allows access to CodeWright APIs in the Perl script.

CWP.PM Exporter for CodeWright APIs.

CARP.PM Error routines.

CONFIG.PM Win32 Perl configuration.

CWP.XS Source Perl script used to rebuild CWP.DLL

(CodeWright SDK only).

DYNALOADER.PM Dynamically loads C libraries into Perl code.

EXPORTER.PM Default import method for modules.

PERL5DB.PL Perl 5.0 Debugger.

TYPEMAP CodeWright variable types (for use with CWP.XS -

CodeWright SDK only).

XSUBPP.PL Converts Perl XS code into C code (for use with

CWP.XS - CodeWright SDK only).

TERM\CAP.PM Perl termcap interface (CodeWright SDK only).

16- Extend CodeWright 413

 Filename Purpose

TERM\COMPLETE.PM Perl word completion module (CodeWright SDK

only).

TERM\READLINE.PM Perl interface to various C<readline> packages

(CodeWright SDK only).

Other Perl Resources

Much useful information can be derived from your nearest CPAN (Comprehensive
Perl Archive Network) web site, or some of the Perl books by O'Reilly Press, namely
Programming Perl, and Learning Perl for Win32 Systems. Some useful URLs would
include http://www.perl.org for general Perl information and http://
www.activestate.com for Perl for Win32 systems.

If you want certain .PL files to be accessible to CodeWright (e.g. a math library), put
them in the \PERLIB subdirectory of the CodeWright home directory, or specify a
path to them on the Tools|Perl Macros|Properties dialog. For the latter, make sure
the path you specify does not contain .PLL files needed by the CodeWright Perl
Interpreter.

AppBasic
This section explains how to use the AppBasic Macro Language in CodeWright to
create your own macro functions.

The CodeWright AppBasic Macro Language is an interpreted language that is similar

in definition and structure to Microsoft Visual Basic. Through it, you have access to
the Windows API, CodeWright's API, and functions in independent DLLs. Example
files are supplied in the CodeWright \MACROS subdirectory to aid you in getting
started. When you press the File Open button on the AppBasic Edit Window toolbar
for the first time, you will see a list of these sample AppBasic Macros. Several of
these macros are covered in this section as well.

The advantage of an interpreted language is that no compiling is required. You can

write your macros and use them immediately. By using the AppBasic Edit Window,
a tab on the CodeWright Output Window, you can add break points and debug your
macro as well.

414 16- Extend CodeWright

Getting Started
To enable the AppBasic Macro Language, go to the Tools|Customize|Libraries
dialog. You will see a list of optional packages or modules you can use with
CodeWright. Select the checkbox for AppBasic Macro Language. There is also a
Basic module listed that provides template expansion and language coloring
support for the Basic programming language in general. We suggest you enable this
option as well.

AppBasic Environment

Two Editors
You can select one of two editors for editing your AppBasic source code:
CodeWright, or the Rich Text Editor.
n If you use CodeWright, you get the benefits of standard keystrokes and
advanced features. If you use the Rich Text Editor, you get a very close
emulation of the Visual Basic editor, including automatic case correction.
n You can select which editor appears in the AppBasic Edit Window by enabling
or disabling the Rich Text Editor. You will find this setting on the
Tools|AppBasic Macros|View menu.

Special Keybindings
The following keybindings are in effect in the Rich Text Editor and cannot be
changed. When using the CodeWright Editor in AppBasic these keybindings are
only valid when you have a .CWB file current. Otherwise, they revert to your
original keybinding for your default keymap.

Keystroke Operation

C+ A View Macro

C+E View Immediate Tab Window

C+W View Watch Tab Window

16- Extend CodeWright 415

 Keystroke Operation

C+T View Stack Tab Window

C+L View Loaded Tab Window

% Debug Run

S+% Debug Stop

X Debug Pause

* Debug Step Into

S+* Debug Step Over

C+* Debug Step Out

& Debug Step To

C+S+ ( Debug Clear All Breakpoints

C+( Debug Add Watch

S +( Debug Quick Watch

( Debug Toggle Breakpoint

C+N File New

C+O File Open

C+ - File Close

C+S File Save

C+P File Print

416 16- Extend CodeWright

Two Toolbars
AppBasic has two nearly identical toolbars that you can use with it. One toolbar, the
one you see depicted in the preceding AppBasic Environment graphic, has a fixed
location at the top of the AppBasic Edit Window. We will refer to this toolbar as the
AppBasic Edit Window toolbar.

The other toolbar is one of the CodeWright dockable toolbars. You can position it
anywhere on your screen, or dock it against any edge of the CodeWright Client Area.
We refer to this as the AppBasic toolbar, to avoid confusion. You can enable this
toolbar via the Tools|Customize|Toolbars dialog.

Popup Menu
When you right-click in the AppBasic Edit Window, a popup menu offers a number
of additional options. If you don't find what you are looking for on a toolbar, or the
Tools menu, check out this menu.

Online Help
Online help is available for the AppBasic Edit Window, the AppBasic Language, and
its built-in functions:
n For help on using the AppBasic Edit Window, or language syntax, press the
Help button on the AppBasic Edit Window toolbar.

n For help on functions or subroutines, press the ! key anytime the cursor is in
the AppBasic Edit Window. CodeWright will attempt to bring up help for the
word at the cursor. If there is no word at the cursor, you can still browse a list of
available functions and subroutines.

UserDialog Editor
AppBasic comes with its own dialog editor. A UserDialog is a dialog defined in a
macro program. It is described within a Begin Dialog...End Dialog block. To
create or edit a UserDialog graphically, place the cursor in a UserDialog block and

press the Edit UserDialog button .

Object Browser
The Object Browser shows information about all the available special data types,
particularly for OLE Automation. Select the label that you wish to look up, and click

the Browse Object button .

If no label is selected, or the label is not found in the known libraries, the edit box at
the top of the dialog will be empty. You may still browse the existing data types and
methods.

16- Extend CodeWright 417

Creating a Macro
To create an AppBasic macro, complete the following steps:
1. Select the AppBasic Edit tab on the Output Window.
2. Right-click in the window and select Properties. In the Module Properties
dialog, you can provide the names of the AppBasic functions you want to call
from LibFunctionExec, call from the CodeWright API Command, or bind to a
CodeWright button.
AppBasic refers to the functions as Handlers. A Handler exports the function
for use by defining its return value, along with parameters and types. For those
who are familiar with writing DLL extensions for CodeWright, Handlers serve
the same purpose as calling LibExport. Once made available to CodeWright in
this way, Handlers can be assigned to keys, run from menus and the like.

You can define and create Functions or Subs in the Module Properties dialog
before or after creating a Handler. The handler must be added at some point,
however, for the function to be called from CodeWright.
3. When you have finished adding your functions, select OK. Then, on the
Modules Properties dialog, select Add. The Add Handler dialog displays.

Add Handler Dialog

Creating a Handler
To create a Handler:
n In the Add Handlers dialog, name your function and declare its type.
Note: Functions and Subroutines must start with a letter and can then
be followed by an underscore or letter.
n Type in any parameters you wish.
Note: At this time, parameters cannot be added later, to do this you
must delete the function and add it again.

418 16- Extend CodeWright

 Example:
From the Add Handlers dialog:
1. Enter DoThis as the name of the subroutine
2. Use a ‘void’ return type and empty parameter list.
3. Press OK to return to the Module Properties dialog.
4. Press OK again.
5. When you are back in the AppBasic Edit tab, use the Proc list to
select
DoThis. The DoThis subroutine will be inserted as follows:
Private Sub DoThis()
End Sub
6. Now add the following line inside the DoThis Sub.
MsgNotify "This is a test"
MsgNotify is a CodeWright API function that notifies the user
with a message.

The DoThis subroutine will now look as follows:

Private Sub DoThis()
MsgNotify "This is a test"
End Sub
7. You should now save the macro to a file. By convention, the .CWB
extension is used for AppBasic macros.
8. Now run the macro. You may do this in any one of the following
ways:
n Press the Start/Resume button on the AppBasic Edit Window

toolbar .
n Press the Run Current Macro button on the AppBasic toolbar

.
n Right-click the mouse in the AppBasic Edit Window and
select Run.
9. After running the macro, go to the CodeWright menu Tools|API
Command and type:

DoThis
10. Click OK. A message box should appear with the words “This is a
test” in it.

16- Extend CodeWright 419

 Note: It is not always expedient to load a macro by
"starting" it in the AppBasic Edit window. When the
macro is no longer in need of editing, it can be loaded
using the Load AppBasic Extension Macros dialog,
accessed by selecting Tools|AppBasic Macros|Load
Macros.

Object and Proc Drop-down Lists

The Object list shows all the objects for the current module. The object named
(general) groups together all of the procedures that are not part of any specific object.

The Proc list shows all the procedures for the current object. Selecting a procedure
that is not bold inserts the proper procedure definition for that procedure.

The Object and Proc Drop-downs

Handlers you added in the Properties dialog will appear in the Object and Proc list.
Example: You create a function named Srch_Backwards(), then the Object
list contains Srch and the Proc list contains Backwards.
The underscore divides the function name between the Object and
Proc lists.

Private Sub Main

Any initialization can be done in a special subroutine named Private Sub Main(). An
example is provided next.
Example:
Private Sub Main()
Dim firstTime As Boolean
Dim i As Integer

firstTime = True

If (firstTime = True) Then

'no LibExports() needed here, use Modules Property
'Dialog And add handler as a replacement.
firstTime = False

Set SaveEvent = EventRegister(EVENT_SAVE_BUFFER, EVENT_NORMAL,

"Buffer_Saved")

End If

End Sub

420 16- Extend CodeWright

Tips on Creating Macros
Consider the following tips:
n You may only edit macros that are not currently loaded for execution. To unload
a macro, right-click on the AppBasic Edit tab of the Output Window to bring up
the Show Loaded Modules dialog. Remove the check from the checkbox in
front of the filename to unload the macro. Calling cwbUnloadFile (filename)
through the API Command prompt will also unload it. If you try to edit a macro
that is currently loaded, an error message asking you to unload the module will
appear.
n When your cursor leaves a line of source code, it is automatically processed.
You may note that capitalization has consequently changed, if you are using the
Rich Text Editor.
n A dot in the left margin of the line indicates a break point. Break points may be

toggled on/off, using the button on the AppBasic Edit Window toolbar .

Creating a Modal User Dialog

To create a modal user dialog:
1. Place the cursor in the subroutine or function in which to place the dialog.
2. Then either:

n Select the AppBasic Edit Window toolbar button Edit UserDialog , OR

n Select the AppBasic toolbar button Edit/Insert User Dialog .

The UserDialog Editor displays:

UserDialog Editor

16- Extend CodeWright 421

3. Select the Edit Item Properties toolbar button (or right mouse click on the
dialog that you are creating). The Edit UserDialog Properties screen displays.

Edit UserDialog Properties

4. Name your dialog in the Caption box.

5. Enter the name of the function that will be used to process the dialog in the
Dialog Function box.
Note: This is a very important step in the process. A question about
creating the skeleton will not show up upon exiting the screen if
you have not filled in the Dialog Function box.
6. Hit the Close button to re-display the dialog in the UserDialog Editor.
7. Using the OK and Can tools on the vertical toolbar, add an OK and/or a Cancel
button to the dialog.
Note: A Cancel button is needed to activate the “X” system menu in
the top right hand corner of the dialog.
8. Perform additional editing as desired.
9. Save and exit the User Dialog Editor by clicking on the Save and Exit button. A
dialog will appear that asks: Create the skeleton dialog function?
10. Answer YES to this question. Your code should now look similar to the
following:
Private Sub DoThis()
MsgNotify "This is a test"
Begin Dialog UserDialog 400,91,"DoThis Test
dialog",.DoThisTest
Text 30,28,330,28,"This is a test
dialog.",.Text1
OKButton 40,63,90,21
CancelButton 160,63,90,21
End Dialog (continued...)

422 16- Extend CodeWright

 Dim dlg As UserDialog
Dialog dlg

End Sub
Rem See DialogFunc help topic for more information.
Private Function DoThisTest(DlgItem$, Action%, SuppValue%)
As Boolean
Select Case Action%
Case 1 ' Dialog box initialization
Case 2 ' Value changing or button pressed
Rem DoThisTest = True ' Prevent button press from
closing dialog
Case 3 ' TextBox or ComboBox text changed
Case 4 ' Focus changed
Case 5 ' Idle
Rem DoThisTest = True ' Continue getting idle actions
End Select
End Function

11. Change the following line of code from:

Dialog dlg
To:
bButtonPushed = Dialog(dlg)

The final sample is listed below:

Private Sub DoThis()
MsgNotify "This is a test"
Begin Dialog UserDialog 400,91,"DoThis Test
dialog",.DoThisTest
Text 30,28,330,28,"This is a test
dialog.",.Text1
OKButton 40,63,90,21
CancelButton 160,63,90,21
End Dialog
Dim dlg As UserDialog
bButtonPushed = Dialog(dlg)
End Sub
Rem See DialogFunc help topic for more information.
Private Function DoThisTest(DlgItem$, Action%, SuppValue%) As
Boolean
Select Case Action%
Case 1 ' Dialog box initialization
Case 2 ' Value changing or button pressed
Rem DoThisTest = True ' Prevent button press from
closing dialog
Case 3 ' TextBox or ComboBox text changed
Case 4 ' Focus changed
Case 5 ' Idle
Rem DoThisTest = True ' Continue getting idle actions
End Select
End Function

16- Extend CodeWright 423

Running the Macro
Run the macro to see if you have any syntax errors. After editing any syntax errors,
go to the Tools|API Command and execute DoThis. You will see a message box and
then a dialog box show up.

The code within this subroutine will be run when the module is put into Run mode.
Once a module is debugged, it can be loaded without being in AppBasic. The
CodeWright API command cwbLoadFile “FileName” will load the module and put
it in run mode without being shown in AppBasic. You can bind the command
cwbLoadFile “FileName” to a key, or add it to the [Editor] section of your
CWRIGHT.INI configuration file to load it during start up.

Creating an EventHandler in AppBasic

Events provide a method of interrupting program flow to allow a function or
functions to have a timely effect. A number of events have been built into AppBasic
using CodeWright event handlers in order to add flexibility. One reason for this
flexibility is that the number and names of the functions the event executes need not
be known to the function that triggers the event.

The functions that are executed when a specified event occurs are called Event
Handlers. Since most events originate with CodeWright API functions, writing your
own event handler gives you access to the CodeWright core. You can change the
way critical functions work without rewriting CodeWright.

You can use events by following the three steps listed below:
1. Select the event that represents the action in which you wish to intervene.
An event handler list can be found in the online help; select Help|CodeWright
API Library and search in the index under Event: Using Events. The sample
event handler program ties itself to the event that occurs when a character is
entered into a CodeWright buffer.
2. Write an appropriate event handler function for that event. (The EventHandler
definition must be “Global” or the event handler will become unregistered.)
3. Register the function for execution at the event with EventRegister.
Set X=EventRegister(EVENT_CHAR_INSERTED, EVENT_NORMAL,
"EventTestHandler")

Note: De-registration of the event is handled automatically when the

macro file is unloaded in CodeWright. To stop an event handler
before terminating the program (module), set the returned
EventHandler Object to “Nothing”.
Refer to the sample file EHTEST.CWB that follows.

424 16- Extend CodeWright

Sample EHTEST.CWB
*************************************************************
' * EhTest.cwb
' * Sample Event handler EVENT_CHAR_INSERTED, Message box
' * pops up and displays the character that was pressed.
' * Usage: occurs automatically when the macro is loaded
' * because the event is registered in Private Sub Main().
'************************************************************
' Note!!!! EventHandler must be Global or event handler will
' become unregistered.
Dim X As EventHandler
' This function needs to be executed for the handler to take
' effect. You can put the EventRegister in a main()
' subroutine if you want it to be available every time the
' macro is executed.
Private Sub Main()
Set X=EventRegister(EVENT_CHAR_INSERTED,EVENT_NORMAL,
"EventTestHandler")
End Sub
Private Function EventTestHandler(ID As Long, Datap As Long) As Integer
MsgBox StringFromPointer(Datap)
EventTestHandler = 0
End Function

Private Sub EventTestRemove()

' The event will be automatically deregistered when the
' macrois unloaded.If however you would like to deregister
' before the macro is unloaded, simply set the returned
' EventHandler object to "Nothing".
Set X = Nothing
End Sub

'{{CWBASIC_LOADERINFO
' cwbAddHandler 'Private Function EventTestHandler(ID As Long,
' Datap As Long) As Integer', '%F'
' cwbAddHandler 'Private Sub EventTestRemove()', '%F'
'}}CWBASIC_LOADERINFO

Debugging Your AppBasic Macro

When you are ready to begin debugging an AppBasic macro, the following steps will
help you get started:
n Open the macro file for modification, if you have not already done so (load it
into the AppBasic Edit Window).
n Set a Break point, perhaps at the first line of the Sub or Function you are

debugging, by pressing ( or clicking the Toggle Breakpoint button . (A

dot should appear in the margin to the left of the line.)

16- Extend CodeWright 425

n Enter Run mode by clicking on the Start/Resume , Step Over or Step

Into button. The Immediate, Watch, Stack and Loaded tabs will then
appear above the Edit Window. You can also press * to enter this mode if you
are using the RTF editor, instead of the default CodeWright edit window (Tools
|AppBasic Macros|View|Rich Text Editor).
n Call the Sub or Function so that you reach the Breakpoint you have set. You can
do this by selecting API Command from the Tools menu and entering the name
of the Sub or Function.

Break Points
Toggle a break point on the current line by pressing .
Note: When you are debugging the macro and have hit a break point,
notifications will be disabled in the other tabs in the Output Window.
For example, if you have hit a break point in the macro and then you
do a multiple source search, double-clicking in the current Search
Window (e.g. Search 1) will be disabled until you have stopped the
macro.

Evaluate Expression and Add Watch

You may evaluate an expression, assign a value to a variable, or call a subroutine by
typing commands in the Immediate tab when AppBasic is running a macro.

Command Results when you press [Enter]

?<expr> Shows the value of "expr".

<var> = <expr> Changes the value of "var".

Set <var> = <expr> Changes the reference of "var".

<subname> <args> Calls a subroutine or built-in instruction.

Trace Toggles trace mode. Trace mode prints each statement

in the Immediate Window when a macro/module is
running.

The Watch Window displays the variables, functions and expressions that are
calculated. Each time execution pauses, the value of each line in the Watch Window
is updated.

426 16- Extend CodeWright

In addition, the following actions are available to you:
n The expression to the left of the "->" may be edited.

n Press E to update all of the values displayed, to reflect any changes you
have made.

n Press Cy to delete the line.

Object Browser
The Object Browser shows information about all the special data types that are
available.

OLE Automation Members

You can get to the Object Browser by pressing any of the following:

n The Browse Object button on the AppBasic Edit Window toolbar.

n The right mouse button, when over the AppBasic Edit Window. Select Object
Browser from the popup menu.

Load Macros Dialog

When you choose the Tools|AppBasic Macros|Load Macros menu item, you will be
presented with the following dialog, which allows sample macros or user defined
macros to be loaded.

16- Extend CodeWright 427

Load AppBasic Extension Macros

AppBasic Sample Macros

AppBasic macros are files that end with .CWB extensions.
Example: BASKEYWD.CWB
A number of sample macros are supplied in the \MACROS subdirectory of the
CodeWright installation directory. Most of these macros are not intended to perform
necessarily useful tasks, but rather are intended to show how features of
CodeWright are accessed through AppBasic. The comments in the macros describe
their functionality.

AppBasic-related API Commands

The following useful API commands are available from the CodeWright API
Command prompt (Tools | API Command):
n cwbLoadFile(<moduleName>)
Once an AppBasic module contains no syntax errors, it can be loaded for
execution. It can then be run without the use of the AppBasic Edit Window.
n cwbLoadFile “FileName”
Will load the module and make its exported functions (handlers) available for
running. You can also bind keys and buttons to the handlers in the loaded
Macro file.
n cwbUnloadFile (<moduleName>)
An AppBasic module cannot be modified while it is loaded for execution. If you
have loaded the file using cwbLoadFile() from your CWRIGHT.INI file or a
button, and you want to now edit the file in AppBasic, you will need to unload
the file using cwbUnloadFile().

428 16- Extend CodeWright

AppBasic Edit Window Configuration
Most users will find the standard configuration of the AppBasic Edit Window
satisfactory. If desired, however, you can turn off the AppBasic Edit Window toolbar
and the AppBasic Object and Proc drop-down lists that appear at the top of the
AppBasic Edit Window.

To change the appearance of the AppBasic Edit Window, go to the Tools|AppBasic

Macros|View menu. Here you can enable or disable the AppBasic Edit Window
toolbar, the AppBasic Object and Proc drop down list, or change from a CodeWright
Edit window to the WinWrapâ Rich Text Editor.

This configuration can also be set by right-clicking over the AppBasic Edit Window,
and then selecting View from the popup menu.

If you wish to change the configuration of the window programmatically, the

following CodeWright API commands will assist you. These commands may be
issued via the API Command dialog (Command Key) on the Tools menu. If you
find them useful, you may make your settings more permanent by modifying similar
commands in the CWRIGHT.INI configuration file.
n cwbShowToolbar(int nShow)
This function will hide/show the AppBasic Edit Window toolbar.
Example:
cwbShowToolbar(0)
cwbShowToolbar(1)

The first example will cause the toolbar to be hidden. The second example
will show the toolbar. Any positive integer value for the parameter will
display the toolbar.
n cwbShowProcDisplay(int nShow)
This function will hide/show the Object and Proc dropdown lists.
Example:
cwbShowProcDisplay(0)
cwbShowProcDisplay(1)

The first example will cause the Object and Proc dropdown lists to be hidden.
The second example displays them. Any positive integer value for the
parameter will display the Object and Proc dropdown Lists.

16- Extend CodeWright 429

n cwbCreateCWWindow( int bCWWindow )
This function is used to change the Editor in AppBasic. There are two choices:
one is to make it a CodeWright Editor and the other is a Rich Text Editor.
Example: To change to a CodeWright Editor call:
cwbCreateCWWindow(1) or cwbCreateCWWindow( TRUE )
Example: To change to Rich Text Editor call:
cwbCreateCWWindow(0) or cwbCreateCWWindow( FALSE )

Example Configuration File Settings

The AppBasic Edit Window's configuration is stored in the CWRIGHT.INI file, in the
[AppBasic Setup] section as shown below:
[AppBasic Setup]
cwbShowProcDisplay=2
cwbShowToolbar=1

Exported Functions in CWBASIC.DLL

Refer to the following functions:
n cwbAddHandler(LPSTR lpszHandlerDef, LPSTR lpszModule)
Adds a callable Sub/Function to AppBasic module - equivalent to LibExport
lpdzHandlerDef - Sub/Function Prototype ex: Private Sub
CallMe(FName As String)
lpszmodule - cwb file containing this Sub/Function
(Full Path) ex: c:\cw32\colsum.cwb.
n cwbToggleBreakPoint(void)
Toggles a break point in currently edited module at the current line.
n cwbEditFile(LPSTR lpszFile)
Loads a .CWB file into the AppBasic editor.
n cwbLoadFile(LPSTR lpszFile)
Loads and runs an AppBasic file.
n cwbUnloadFile (LPSTR lpszFile)
Unloads File from Engine (Stop Run)

430 16- Extend CodeWright

n cwbExecuteCommand(long cmd)
Executes an AppBasic Operational Command.

Commands
cmdFileNew = 0 cmdFileOpen = 1 cmdFileSave = 2

cmdFileSaveAs = 3 cmdFilePrint = 4 cmdFilePrintSetup = 5

cmdMacroRun = 6 cmdMacroPause = 7 cmdMacroEnd = 8

cmdDebugStepInto = 9 cmdDebugStepOver = 10 cmdDebugStepTo = 11

cmdDebugBreak = 12 cmdDebugQuickWatch = 13 cmdDebugAddWatch = 14

cmdDebugBrowse = 15 cmdDebugSetNext = 16 cmdDebugShowNext = 17

cmdHelpApp = 18 cmdHelpLanguage = 19 cmdHelpTopic = 20

cmdHelpAbout = 21 cmdEditUndo = 22 cmdEditCut = 23

cmdEditCopy = 24 cmdEditPaste = 25 cmdEditFind = 26

cmdEditReplace = 27 cmdEditAgain = 28 cmdEditFont = 29

cmdEditDelete = 30 cmdEditSelectAll = 31 cmdEditUserDialog = 32

cmdFileClose = 33 cmdFileSaveAll = 34 cmdDebugStepOut = 35

cmdSheetOpenUses = 36 cmdSheetCloseAll = 37 cmdSheet1 = 38

cmdSheet2 = 39 cmdSheet3 = 40 cmdSheet4 = 41

cmdSheet5 = 42 cmdSheet6 = 43 cmdSheet7 = 44

cmdSheet8 = 45 cmdSheet9 = 46 cmdEditProperties = 50

CmdFileNewObjectModule cmdFileNewClassModule = 49 cmdFileNewCodeModule =

= 48 47

n cwbShowToolbar(int nShow)
Hide/Show AppBasic Edit Window toolbar.
n cwbShowProcDisplay(int nShow)
Hide/Show Object and Proc drop-down lists.

16- Extend CodeWright 431

API (C-like) Macros
This section covers CodeWright API macros.

CodeWright API Commands are function calls that can be made interactively. This
means that they may be assigned to keys, menu items, buttons, popup context
menus, and issued from the API command line. CodeWright API Macros build upon
this capability to provide a quick and simple way to write extensions for
CodeWright.

If you have previously used, or read about using API Commands interactively, a few
differences should be noted if they are being used from API macros:
n You can nest API Commands as parameters to other API Commands in macros.
n All functions must be followed by opening and closing parentheses around the
parameter list, if any.
n Commas must separate parameters.

API Macros Defined

API Macros are one or more sequential, iterative, or conditional statements that are
given a name. These statements often contain CodeWright API function calls. They
are stored in a file, CWRIGHT.MAC, and may be recalled by name for execution
within CodeWright.

A number of API macros are supplied with CodeWright. The supplied macros can be
viewed in one of the following ways:
n Select the appropriate macro from the drop-down list under the Name edit box
in Tools|API Macros. The macro is then displayed in the dialog for viewing or
editing purposes.
n Open the file CWRIGHT.MAC into CodeWright, then locate a desired macro for
viewing or editing.

A ChromaCoding lexer called API Macro has been developed to make working with
the language easier. Without any special changes you should be able to:
n Load the CWRIGHT.MAC file into CodeWright.
n See it correctly ChromaCoded.
n Compile it with the menu or button.
n Parse errors from the Output tab of the Output Window.

For more information on Lexers, refer to the topic ChromaCoding Lexers in the chapter
View Themes and Language Support.

432 16- Extend CodeWright

Getting Started with API Macros
The Tools|API Macros dialog lets you create, edit and test API Macros.

API Macros

Creating a Macro
To create an API macro in the API Macros dialog:
1. Give the macro a name in the Name edit box.
2. Type in the API commands you wish to execute into the Edit box.
3. Press the Save button. Press the Run button to send away the dialog and
execute the current macro at the cursor position of the current document. Any
unsaved edits are automatically saved by default.

Editing a Macro
To edit a macro previously created, select its name from the Name listbox. The text of
the macro will appear in the Edit box and you can proceed to make your changes.
Press either Run or Save to save your changes to disk; Run will also run the macro.

Each time a macro is saved, it is checked for errors. If there are errors, use the four
buttons at the lower left of the dialog to parse the position and text for each error.

Special Editing Keystrokes

In addition to the buttons, the next error can be parsed by using SCY . To
insert a [Tab] character use CT. As in a CodeWright window, hit ! to bring
up help for the function under the cursor.

16- Extend CodeWright 433

Creating and Editing API Macros in a CodeWright Window
You can also create and edit API Macros in a standard CodeWright edit window.
This gives you access to advanced editing capabilities in CodeWright.
To create a macro:
1. Open the file CWRIGHT.MAC into CodeWright.
2. Create a new macro using the following syntax:
[API Macro:<macro_name>]
To edit a macro:
1. Find the location of the macro to edit by searching for [API
Macro:<macro_name>]. The macro is contained in the lines following its
name <macro_name>, but before the next bracketed section, if any.
2. Make any necessary edits.
3. Save before running the macro, since macros are always read from the file.

Running a Macro
The obvious way to run a macro is from the menu or dialog. Macros can also be
executed from within CodeWright in as many ways as API functions can be. Just use
the macro’s name, and optionally its parameters, like CodeWright API functions.

Language Definition
For more information on the API Macro language, see the following discussions on:
n Comments
n Identifier Naming Rules
n Data Types for Variables
n Declaring Variables and Arrays
n Literal Values
n Array Initializers
n Automatic Type Conversion
n Expressions
n Statements and Statement Blocks
n Program Flow Control Structures
n Run-time Error Handling
n CodeWright Event Handling
n Special API Macro Functions
n Difference between API Macros and C
n String Functions

434 16- Extend CodeWright

Comments
Comments can be used almost anywhere, including within statements.
n C style multi-line comments may be used in API Macros. The comment starts
with the forward slash and asterisk, ‘/*’, and ends with the asterisk and forward
slash, ‘*/’. This kind of comment can cover a partial line, or many lines. Nested
comments are not supported.
n C++ style comments may be used in API Macros. When two forward slashes,
' //', appear on a line, the remainder of the line is ignored.

Identifier Naming Rules

Identifiers include macro and variable names. The first character must be an
alphabetical or underscore ( _ ) character. The remaining characters can be
alphanumeric or the underscore character.

Data Types for Variables

There are two types of variables available, ‘int’ and ‘string’:
n ‘int’ type variables are long signed integer numbers. You can use the ‘int’ type
for accessing most of the parameter and return types of CodeWright API
commands. These include ‘char ’, ‘int’, ‘long’, ‘UINT’, ‘WORD’, ‘DWORD’,
‘BOOL’, ‘HBUFFER’, ‘HWINDOW’, etc.
n ‘string’ type variables are NULL terminated character arrays. They are
automatically allocated and freed as needed. Use the ‘string’ type when
accessing parameter and return types of LPSTR and LPMSTR. Strings must
start and end with the quote character (").

Arrays of either type (‘int’ or ‘string’) are also supported. An array is a variable
capable of storing one or more values. All of the values in the array must be of the
same type. The values stored in the array are called ‘array elements’.

Declaring Variables and Arrays

Variables must be declared before they can be used. They can be assigned a value in
the same statement they are declared in. Here are some example declarations:
int i;
int j = 1;
string s;
string a = "abc";
Two of these examples include initialization. Macro variables are never un-
initialized. If they haven't had a value assigned to them, their value will be zero or
NULL.

16- Extend CodeWright 435

Arrays can be declared using one of the following forms:
n <arr_name> is the name of the array and must conform to identifier naming
rules.
n <arr_size> is optional. If given, <arr_size> must be a constant
expression that evaluates to a non-negative integer value.
3 If <arr_size> is given and the declaration does not include an
assignment, all array elements are initially set to 0 (NULL for string arrays).
3 If <arr_size> is not given, the size is initially zero. Omitting
<arr_size> is allowed because array size is dynamic and will change as
elements are assigned to the array.

static
Use the 'static' keyword directly before the 'int' or 'string' type keyword. Static
variables maintain their values between macro calls.

If you wish the initialized value of the variable to be non-zero, be sure to follow
it with an assignment expression. This expression cannot contain any macro or
function calls.

global
Use the 'global' keyword directly before the 'int' or 'string' type keyword. Like
static variables, global variables maintain their values between macro calls.
They have the additional benefit of being available in more than one macro.

Each macro that uses a ‘global’ type variable must declare it. For each
declaration, use the same assignment value for initialization. Otherwise the
starting value may be undetermined, since it would depend on which macro is
compiled (used) first.

Parameters and Return Types

Declare parameter variables and return types at the beginning of a macro. Use
the following format for the macro declaration:

<ret_type> <macro_name>(<type> <param1_name>,

<type><param2_name>, ... )
{
<statement>;
// more lines here
return <expression>;
}

436 16- Extend CodeWright

 The following formatting guidelines apply when defining parameter variables
and return types:
n For backward compatibility, the parameters line and the outside braces
enclosing the macro are optional.
n The <ret_type> part of the parameters line is required. If the macro
returns no value, use the special type 'void'. Otherwise use either 'int’ or
'string' here.
n The <macro_name> part is optional since it serves no functional purpose.
However to maintain good C style form, use the same name here as the
macro name shown in the dialog's combo box.
n The left and right parentheses frequently contain one or more comma-
separated formal parameters. Each formal parameter variable begins with
either 'int' or 'string', and ends with the identifier naming it. If no
parameters are used, use the special 'void' type alone between the left and
right parentheses.
n Arrays defined for parameter and return types must be automatically sized
(use no number within the brackets for the array size).
n If the return type is not 'void':
3 Use the return statement at the end of the macro.
3 Include an expression in the return statement to use for the return
value.

Literal Values
Literal values can include numbers, characters and strings.

Number Literal Formats

Decimal, hexadecimal and octal number formats are supported. Hexadecimal
numbers must start with '0x'. Octal numbers must start with '0'. All other
numbers are considered decimal.

Character Literals
Character literals are just an alternate method of specifying a literal number.
Delimit character literals at the beginning and end with a single quote (').

Character literals usually contain one character but will have two or three if the
first one is the backslash (\) escape character. Use the backslash before a single
quote if you wish the single quote to represent the character literal value.

String Literals
String literals are sequences of characters that are delimited at the beginning
and end by the double quote (") character. To include the quote in the string,
precede it with the backslash (\) escape character.

16- Extend CodeWright 437

 String literals can continue onto following lines if the last character in the line is
a backslash. The word NULL can be used for functions that require string
parameters, if needed. The NULL constant is useful when calling functions like
FGrepFile that treat NULL strings differently than empty strings. The
difference between NULL and empty strings is this:
n NULLs are string pointers that are 0 (invalid memory locations).
n Empty strings are valid pointers that point to strings with zero length ("").
When strings are compared in API Macro code, NULL strings are equivalent to
empty strings. This is because API Macros compare strings by content, not
pointers.
Example: string s = FGrepFile( NULL ); // return previous filename
string t = FGrepFile(""); //set the filename to "" (empty string)
if (s_empty == NULL)
MsgMessage("'s_null' could be NULL or empty);
If (s_null == "")
MsgMessage("'s_null' could be NULL or empty);
To determine whether a specified string is NULL but not empty, use the API
macro function isNull(<string>).

Escape Sequences
The following are escape sequences for both string and character literals:

Literal Escape Sequence Value

\0 NULL 0x00

\a Alert (bell) 0x07

\b Backspace 0x08

\f Form Feed 0x0c

\n New Line 0x0a

\r Carriage Return 0x0d

\t Horizontal Tab 0x09

\v Vertical Tab 0x0b

\xhh Hexidecimal Value (00-ff)

\\ Backslash

438 16- Extend CodeWright

 Note: If you want to use the backslash in function calls that expect a single
backslash in the string, be sure to double it in the literal string.

Array Initializers
Array initializers for API Macros take the form:
{<element_0>,<element_1,…<element_n}
n For arrays that have many elements, the '…' represents the repetition of the
pattern ‘<element_1>, <element_2>’ up to <element_n>. The ellipsis
cannot be used explicitly.
n There may be zero or more elements in an array initializer.
n Any valid expression can be used as an element in an array initializer. However,
character, number or string literals are commonly used.
n Array element types need not match the array variable that the array initializer
is used with. Types are converted as needed.

Array literals are valid operands and can be used in expressions with other
operands.
Example: The following is an example of combining an array declaration with
an array initializer:
int iArr[10] = {1,2,3}
In special cases like the previous example, where the array initializer has fewer
elements than the declaration size, the remaining elements are initialized to 0 (NULL
for string arrays). Otherwise, when an array type is assigned to an array variable, the
array variable takes the size of the array being assigned to it.

Automatic Type Conversion

Values are automatically converted to another type when used where that type is
expected.

Type Conversion Rules

Expected Given type Rule

type

‘int’ ‘string’ If the ‘string’ begins with decimal,

octal or hexadecimal characters, they
are converted for the number. If not,
the value will be one if the string
contains at least one character, and
zero if it is empty or NULL.

16- Extend CodeWright 439

 Type Conversion Rules

Expected Given type Rule

type

‘string’ ‘int’ Convert value to decimal characters.

‘int’ array ‘string’ array Convert ‘string’ elements to ‘int’

elements.

‘int’ array ‘int’ Make an array of size one with the ‘int’
at index zero.

‘int’ array string Make an array with the same length as

the string using each character from
the string for array elements.

‘string’ array ‘int’ array Convert ‘int’ elements to ‘string’

elements.

‘string’ array ‘string’ Make an array of size one with the

‘string’ at index zero.

‘string’ array ‘int’ Make an array of size one with the ‘int’
converted to a ‘string’ at index zero.

‘int’ ‘int’ array Sum all elements.

‘int’ ‘string’ array Convert to ‘int’ array, then sum all

elements.

‘string’ ‘string’ array Working from first to last, append each

element onto the ‘string’ made from
the preceding elements.

‘string’ ‘int’ array Make a ‘string’ with the same length as

the array using a character from each
array element.

The last two conversion rules have a special option that allows the appended string
elements to be separated by a given string.

Use the API macro built-in function joinStr to specify and/or query this string.
Examples:
n Use a single space between each joined (appended) string element.
joinStr(" ");
n Query the current string used to join elements.
retStr = joinStr();

440 16- Extend CodeWright

Expressions
Expressions are made up of operands and operators.
n Support is provided for all C operators.
n Operands can be variables (including arrays), array initializers, literals, and
function or macro calls. Numeric, logical and string expressions are also
allowed as operands within larger expressions. Expressions can be used as
function call parameters.

Accessing Array Elements within Expressions

Use this format to access an individual element within an array:
<arr_name>[<index_expression>]
n <arr_name> must be the name of an array or string variable.
n <index_expression> is an expression used to specify the index of the
element.
n The first element of an array has the index of zero.
n When <arr_name> is of type ‘string’, the element accessed will be the
character at the given index. Accessed ‘string’ elements are converted to
type ‘int’.
Example: The following shows how array elements can be accessed:
// define 2 int arrays, one of size 0 and one
// size 10
int iArr1[], iArr2[10];
// assign iArr2 to iArr1. iArr1 now has 10
// elements (all zero values)
iArr1 = iArr2;
// assign 2 to the first element of iArr1
iArr1[ 0 ] = 2;
// assign 1 to the second element (index 1) of
// iArr2
iArr2[ iArr1[ 0 ] - 1 ] = iArr1[ "" ] - 1;
// assign 1 to the third element of iArr2
iArr2[ { 2, 1, -1 } ] = { 1, 0 };
// Note the last example involves array type
// conversions. See the topic Automatic
// Type Conversion.

Assignments and Operators

Assignments take the form:
<variable> <assign_op> <expression>

16- Extend CodeWright 441

 Assignments are allowed to begin at three places in a statement: at the
beginning of the statement, directly following a left parenthesis, or directly
following a comma. Multiple assignments are allowed in the same expression.
Example: a = b = c = 0;
The assignment operators available are:

Assignment Operators

Operator Description

= Simple assignment

+= Add and assign

-= Subtract and assign

*= Multiply and assign

/= Divide and assign

%= Modulo and assign

<<= Shift bits left and assign

>>= Shift bits right and assign

The numerical operators available are:

Numerical Operators

Operator Description

+ Addition

- Subtraction

* Multiplication

/ Division

% Modulo (remainder)

<< Shift bits left

>> Shift bits right

& Bitwise AND

| Bitwise OR

442 16- Extend CodeWright

 Numerical Operators

Operator Description

^ Bitwise Exclusive OR

~ Bitwise Complement

Logical expressions evaluate to a one or zero, TRUE or FALSE, respectively.

Logical operators available are:

Logical Operators

Operator Description

== Equivalence

!= Non-equivalence

< Less than

> Greater than

<= Less than or equal

>= Greater than or equal

&& AND

|| OR

! Negation

Special Operator Rules for Strings

Some operators have special meaning when their operands are strings.

Use ‘+’ to Concatenate; use ’+=’ to concatenate and assign.

String concatenation is the joining of two strings where the string following the
operator is appended to the string before the operator. If the left operand is of
type ‘string’, string concatenation is done; otherwise numerical addition is
done. The right operand is converted as needed for either form. This capability
makes it easy to compose output strings containing the descriptions and values
of variables.

16- Extend CodeWright 443

 The following are logical comparison operations:
== TRUE if string1 and string2 match
!= TRUE if string1 and string2 don't match
> TRUE if string1 is alphabetically after string2
< TRUE if string1 is alphabetically before string2
>= TRUE if string1 is alphabetically after string2 or matches
<= TRUE if string1 is alphabetically before string2 or matches
String comparison operations require that both operands be strings. Otherwise
the numerical comparison is done. The single string operand is converted to
type 'int' if needed.

By default, string comparisons are case insensitive (ignore case is on).

n To change case sensitivity for the current invocation of a macro, put this call
in your macro:
MacroIgcase(FALSE);
n To query the current state use:
MacroIgcase(-1)or MacroIgcase()

Special Operator Rules for Arrays

The following operator rules apply to API Macro arrays.

For the + and += operators these steps are used:

1. Convert the right operand to the type of the left.
2. Create a larger array by appending right operand elements to left operand.

For the logical comparison operators (>,<,>=,<=,!=,==) these steps are used:
1. Convert the operand with the more complex type to the one with simpler
type. (An array is more complex than an ‘int’ or ‘string’, a ‘string’ is more
complex than an ‘int’.)
2. Then if both operands are arrays:
a. Compare each element with the same index, from first to last, until the
elements do not match or no elements remain in one or both arrays.
b. If all elements match but one array has more elements, it is taken as
having the greater value.

Determine the Size of an Array or String within a Macro

Use the API Macro built-in function dim(<arr_name>) to find the length of an
array or string.

444 16- Extend CodeWright

 Other Operators
Refer to the following descriptions of other available operators.

Other API Macro Operators

Operator Description

, Comma operator. This operator is used to:

n Separate parameters in the calls to other macros or
functions (most commonly).
n Separate sub-expressions within a larger
expression. This use is often seen in the ‘for ’
statement, where it allows multiple sub-expressions
in any of the three semicolon-separated sections
that control the ‘for ’ statement. The value taken for
a sequence of comma-delimited sub-expressions is
that of the right-most sub-expression.

?: Conditional operator. This operator takes the form:

<test_expr> ? <true_expr> : <false_expr>
If <test_expr> evaluates as non-zero, the
<true_expr> is executed and its value is taken.
Otherwise the <false_expr> is executed and its value
is taken. Although this operator can be used without
restriction within expressions, it is commonly used as
the right part of assignment statements.
bValue = bTest ? bVal1 : bVal2;

++ Pre-increment or post-increment operator. This operator

can only be used directly preceding or trailing an 'int'
type variable:
n When used before the variable, the variable's value
is increased by one before it is used within an
expression, if any.
n When used after the variable, the variable's value is
taken first for use in an expression, then the
variable's value has one added to it.

16- Extend CodeWright 445

 Other API Macro Operators

Operator Description

-- Pre-decrement or post-decrement operator. This

operator can only be used directly preceding or trailing
an 'int' type variable:
n When used before the variable, the variable's value
is decreased by one before it is used within an
expression, if any.
n When used after the variable, the variable's value is
taken first for use in an expression, then the
variable's value has one subtracted from it.

Operator Precedence Rules

Operators with the highest precedence are evaluated first. These operators are
binary (requiring left and right operands) unless otherwise indicated.

Associativity indicates the order of evaluation when two operators have the
same precedence. For example, most operators evaluate starting at the left in an
expression, processing right.

Operators (from high to low precedence) Associativity

()[] none

+- ~ ! ++ -- (all unary) R to L

* / % L to R

<< >> L to R

+ - L to R

< > <= >= L to R

== != L to R

& L to R

^ L to R

| L to R

&& L to R

|| L to R

446 16- Extend CodeWright

 Operators (from high to low precedence) Associativity

? : (trinary operator) L to R

= *= /= %= += -= <<= >>= &= |= R to L

^=

, (comma operator) L to R

Parentheses in Expressions
Left and right parentheses, '(' and ')', may be used to group expression parts to
set evaluation precedence.

Short Circuiting
The '&&' and the '||' operators have special evaluation rules. The idea of short-
circuiting is that often only the left operand needs to be executed and evaluated.
n For the '&&' operator, if the left operand evaluates as zero, the value of the
operation must be zero (FALSE) so the right operand can be ignored.
n For the '||' operator, if the left operand evaluates as non-zero, the value of
the operation must be one (TRUE), so the right operand can be ignored.

Function calls
Function calls, including those to CodeWright API functions and macros, take
the form:
<macro_name> (<parameter1>,<parameter2>,...<parameterN>)
The following rules apply:
n Spaces and tabs are allowed after the macro name and between parameters.
n Commas must separate parameters.
n You may supply fewer parameters than a function is defined to use. The
remaining parameters will be supplied for you as zeros or NULLs.
n Pass-by-value is the only way that parameters are passed to function calls
within an API macro; there is no pass-by-reference support at this time.
This means that parameters that would indirectly return a value by using a
pointer, such as the length parameter in the function SrchFind, are not
supported within API macros. To use SrchFind, for example, you must
either omit the length parameter or give it a NULL value.
See the discussion on Expressions, in this chapter, for more information on what
can be used as parameters. Macro recursion is supported.

16- Extend CodeWright 447

 Exiting and Macro Return Values
Use the return statement to exit a macro before the last line and if the macro has
a return type, return a value. End the return statement with a semicolon.

For backward compatibility, if there is no specified macro return type, the return
value is optional. For what is allowed, see the section Expressions in this chapter.
If the expression does not evaluate to the type expected by the macro's defined
return type, the value is automatically converted. See the preceding discussion
on Automatic Type Conversion, in this chapter.

Statements and Statement Blocks

Statements are expressions including optional preceding assignments, ended by a
semicolon. Statements can span multiple lines if needed. More than one statement
can share a line, but it is better form to have them on separate lines. A statement
needn't contain anything more than just a semicolon.

Statement blocks are a series of statements. They are normally used in conjunction
with control structures. Use curly braces '{' and '}', to begin and end statement
blocks, respectively. A statement block can be used anywhere a single statement can
be used.

Program Flow Control Structures

The available program flow control structures are of conditional and iterative types.
Both conditional and iterative statements can be used anywhere statements might
be used.

Conditional statements
Examples of conditional statements include:
n ‘if ’ statement
if (<expression>)
<statement>;
n ‘if-else’ statement
if (<expression>)
<statement>;
else
<statement>;

448 16- Extend CodeWright

 n ‘if-else’ statement (several conditions)
if (<expression one>)
{
<statement>;
<statement>;
}
else if (<expression two>)
<statement>;
else if (<expression three>)
<statement>;
else
<statement>;
Testing for several conditions can be done by using the ‘if-else’ statement in
place of the statement following the 'else'. The preceding does this and also
uses a statement block.
n ‘switch’ statement
switch (<test_expression>)
{
case <constant_expression1>:
<statement>;
<statement>;
break;
case <constant_expression2>:
break;
default:
<statement>;
break;
}

The 'switch' statement executes specific statements based on the value of a

test expression. Specify which statements to execute for given values via
the 'case' lines. There can be many 'case' lines, but each must have a unique
value from the constant expression.

These constant expressions must be able to be evaluated at compile time.

They must not contain function or macro calls. They must not contain
variables or string literals.

The 'break' statement line following each 'case' section is optional. Without
a ‘break’, execution continues into the following 'case' or 'default' section.
The optional 'default' section is executed if none of the cases are matched by
the test expression. The braces are required.

16- Extend CodeWright 449

 Iterative statements
Refer to the following types of iterative statements:
n ‘while’ statement
while (<expression>)
<statement>;

The 'while' statement allows you to execute a statement repeatedly.

The <expression> is evaluated before each iteration:
3 If non-zero, the contained statement is executed.
3 If zero, execution proceeds with the statement following the 'while'
statement.
n ‘do-while’ statement
do
{
<statement>;
} while (<expression>);

The 'do-while' statement also allows you to execute a statement repeatedly.

The <expression> is evaluated after each iteration. The 'do-while'
statement will execute its contained <statement> at least once. The braces
are required.
n ‘for ’ statement
for (<init_expression>; <test_expression>;
incr_expression>)
<statement>;

The 'for' statement contains three parts within the parenthesis:

3 The first part, <init_expression>, only executes once, but before
any other part of the ‘for ’ statement.
3 The second part, <test_expression>, is executed before each
iteration of the loop. If its value is non-zero, the contained
<statement> is executed. If <test_expression> is missing, the
contained <statement> always executes.
3 The third part, the <incr_expression>, is executed after each loop
iteration.
Each of the three parts is optional. If you leave out the <test
expression>, it is common to end the loop from within the contained
statement section using the 'break' statement.

450 16- Extend CodeWright

 n ‘break’ statement
break;
The 'break' statement causes execution to resume immediately following
the innermost containing 'switch', 'while', 'do-while' or 'for' statement.
n ‘continue’ statement

continue;
The 'continue' statement causes execution to not finish the current iteration
of the innermost-containing loop; instead, the next iteration is begun. In
the 'while' and 'do-while' statements, the next evaluated is the <test
expression>. In the 'for' statement, the <incr_expression> is
evaluated next.

Run-time Error Handling

API macros protect against several kinds of run-time errors:

Ctrl-break stop
If you've written a locked loop in your macro, use the C -[Break] keystroke to
terminate it.

Divide by zero error

If the macro attempts a divide or modulo by zero, you will get this error.

Runaway recursion protection

Recursion macro code can sometimes have the problem of not ending the
recursion correctly. This can lead to an ever-expanding stack. Each time an API
macro is called from another, the level of call is checked to see if it is greater than
the allowed maximum (default is 50). This maximum level can be adjusted with
the function MacroMaxRecursion.

Illegal Array Access

An attempted access of an illegal array index will generate a runtime error. An
illegal index is one that is negative or greater than or equal to the size of the
array.

CodeWright Event Handling

Three special macros have been added to CWRIGHT.MAC to facilitate event
handling by API macros:
n _Init_API_Macro -- This macro is automatically called when CodeWright starts
up. To register events you want to handle, put calls to EventRegister here. You
can also put other code here you want run at startup.

16- Extend CodeWright 451

n _API_Macro_int_handler -- This macro is an example handler for when the
event data is known not to be type ‘LPSTR’. Use this macro for most events.
n _API_Macro_string_handler -- This macro is an example handler for when the
event data is known to be the type ‘LPSTR’.

On events where the data is a pointer of type other than ‘LPSTR’, you can still trap
the event but will not be able to access the data.

Special API Macro Functions

The following functions can only be called from inside API macros. Some of these
functions affect the way the macro performs (e.g. MacroIgcase and joinStr); others
return information about a variable (e.g. dim and isNull). Refer to the following
descriptions:
n dim - To find the length of an array or string, use the special function
dim(<arr_name>), where <arr_name> is the name of the array or string.
n isNull - Use isNull(<string>) to determine whether the specified string
variable is a NULL pointer. This is useful since the operator '==' does not
distinguish NULL from empty string ("") (i.e. '(NULL == "")' evaluates to TRUE
or 1).
3 You can also use isNull( ) to check for empty 'int' or 'string' arrays.
n joinStr - Use joinStr( ) to specify and/or query the string used when appending
string elements. This string is used internally when an array of strings is
converted to a single string.
Example:
3 Use a single space between each joined (appended) string element.
joinStr(" ");
3 Query the current string used to join elements.
retStr = joinStr();
n MacroIgcase - By default, string comparisons are case insensitive (ignore case is
on). You can use MacroIgcase( ) to change or query this case sensitivity:
3 To change case sensitivity for the current invocation of a macro, put this call
in your macro:
MacroIgcase(FALSE);
3 To query the current state use:
MacroIgcase(-1)

452 16- Extend CodeWright

Differences between API Macros and C
In C, but not in API macros:
n Types ‘char ’, ‘short’, ‘float’, ‘double’, ‘unsigned’.
n Pointers.
n Typedefs, enums, structs and unions.
n Variable scope limited to statement blocks.
n Preprocessor capability.
n “…” parameter type (printf).
n ‘goto’ statement and labels.
n Link phase and libraries.
n Arrays can have multiple dimensions.
n Arrays can have a defined size for a parameter variable.
n Pointers can be used to access array elements.

In API macros, but not in C:

n Variables needn’t be declared at function top (like C++).
n Lesser number of parameters in calls allowed (like C++).
n String type and special operator capability.
n Automatic memory management (for ‘string’ type).
n Compile on demand (first time run).
n Run-time error handling.
n Global variables are declared within macros.
n Automatic type conversion from arrays to expected types.
n Automatic memory management for arrays.
n Array types can be assigned to arrays (the resulting array sized to match).
n Array initializers can be used in expressions (not just for assignment in an array
declaration).

String functions
Since library functions are not available in API Macros, a number of string functions
are made available through the CodeWright API for building and comparing strings.
n LPMSTR StringApnd( LPSTR str1, LPSTR str2 );
Appends str2 onto str1. Neither string is freed.

16- Extend CodeWright 453

n LPMSTR StringNApnd( LPSTR str1, LPSTR str2, int len2 );
Appends len2 bytes of str2 onto str1. Neither string is freed.
n int StringLength( LPSTR str );
Returns the length of str.
n int StringCompare( LPSTR str1, LPSTR str2 );
Returns < 0 if str1 is alphabetically before str2. Returns > 0 if str1 is
alphabetically after str2. Returns 0 if str1 matches str2.
n int StringICompare( LPSTR str1, LPSTR str2 );
Like StringCompare but ignores case.
n int StringNCompare( LPSTR str1, LPSTR str2, int len2 );
Like StringCompare but only compares len2 bytes.
n int StringNICompare( LPSTR str1, LPSTR str2, int len2 );
Like StringCompare but ignores case and only compares len2 bytes.
n UINT StringChar(LPXSTR str, int idx);
Gets a character at idx from the string.
n LPMSTR StrAscii( int ch );
Converts a character into a single character length string.
n LPMSTR StrItoA( long value, int radix );
Converts a number into a string. Use a radix of 10 for decimal string.
n LPMSTR StrLtrim( LPSTR string, LPSTR cset );
Trims characters in cset off the left of string.
n LPMSTR StrTrim( LPSTR string, LPSTR cset );
Trims characters in cset off the right of string.
n LPMSTR StrSubStr( LPSTR string, int start, int end );
Returns a substring out of string.
n LPMSTR StrFormatDate( long t, LPSTR fmtStr);
Formats a time/date value into a string.
n LPMSTR TransformFilename( LPSTR filename, LPSTR spec);
Transforms the supplied filename as indicated by the accompanying format
controls and transformation patterns.
n BOOL StrFileMatch( LPSTR fpattern, LPSTR fname, BOOL igcase );
Determines if a filename is matched by a pattern.

454 16- Extend CodeWright

Creating New Keymap Command
Sets
Refer to the following section for the basic outline of a keymap and how to create a
new one.

Keymap _init Function

Like the _init function for any other CodeWright DLL, the Keymap's _init function
typically contains a series of LibExport calls that make functions available to
CodeWright. 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 load the DLL to have access to its functions without loading the keymap.

Keymap Function
The keymap function is the function that creates and installs the new keymap. To be
compatible with the DefaultKeymap function, this function must have the same
name as the root of the DLL in which it resides. For example, the CUA keymap is in
the file CUA.DLL and is installed with the CUA function.

Flag Initialization
One of the first things you will want to do in your keymap function is to set options
the way users of your keymap will expect to find them. For example, the BRIEF
keymap needs to allow assignments to [Alt] keys, and doesn't create a new window
for each new file that is loaded. If the users 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:
n Use SysSetFlags to set options you might otherwise set from various
CodeWright dialogs.
n Use SysSetDefault to set up window and buffer settings the way you want,
even before any buffers or windows have been created.
n Use SrchSetFlags to set the default search settings.

You are not dictating with these settings how a user must operate. The settings you
create here may be overridden by settings stored in the configuration file or state file.

16- Extend CodeWright 455

Basic Assignments
When you create a new keymap, it is empty -- and we mean really empty. The only
keys or mouse actions that will work are those that CodeWright lets Windows
process. This includes menus, HT, HX, H$ and such. If you want
pressing the a key to produce an “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
difference between these two functions is that the first makes assumptions about
what you want the keys to do, whereas the second allows you to specify the function
that is assigned to each key.

Keymap-Specific Assignments
Now you are ready to make assignments specific to your keymap. Your main tool in
doing this will be the function KmapAssign. Use the CodeWright API functions, or
create your own supporting functions to assign to keys. Remember that when you
create your own functions, you will need to export them with a LibExport call in the
DLL's _init function in order for the key assignment to work. Otherwise, you will
get a "function not found" message when you press the keystroke.

Menu Accelerators
The last step in creating your own keymap is to put strings indicating any "short cut"
keys or accelerators on the menu. You will rely on the MenuAddKeyString function
to do this.

Installing the Keymap DLL

When you are ready to use your keymap DLL, you need only reference it in the
proper section of your configuration file to install it. For instructions, refer to the
section Installing Your DLL in the chapter Appendix B- Making and Modifying
CodeWright DLLs.

Notes: The CodeWright SDK includes the C source code files and makefiles
for each of the keymap DLLs, allowing for further customization. If
you need more information on how to obtain the CodeWright SDK,
please contact a Sales Representative at [email protected].

456 16- Extend CodeWright

17- UNIX
At this time, CodeWright runs on the Intel platform under Windows 98, 2000 and XP.
A version that runs under the UNIX environment is not offered, but CodeWright
does have some options that make it possible to edit UNIX files within the program.
Before the files can be edited, however, there must be a way to load them from the
UNIX system into the Windows system. Some options for loading UNIX files are:
n Via NFS (Network File Systems) networking. CodeWright does not provide the
tools for networking UNIX and Windows systems via NFS. They must be
obtained elsewhere.
n Via FTP (File Transfer Protocol). CodeWright provides a built in FTP program for
transferring files via FTP. (For more information on the CodeWright FTP
program, see the chapter on File Support and Sharing.)

Once the file-loading method has been established, there are some things that can be
done, and things to be aware of, when using CodeWright to edit UNIX files. The
following topics cover these issues:
n Converting File Type and EOL Characters
n Compiling UNIX Programs from CodeWright
n Preserving Filename Case, File Securities and File Links between UNIX and
Windows Environments

Converting File Type and EOL

Characters
The primary difference between files that reside on Windows systems and files that
reside on UNIX systems is the end of line characters. For this reason, CodeWright
provides various means for EOL character conversion.

17- UNIX 457

Save File as New Type
The File|Save As dialog allows you to convert UNIX files to a “Macintosh Text” or
“MS-DOS Text” format. Conversely, other file types may sometimes be converted to
“UNIX Text” format. In the Save File as Type or Save as Type combo box, look for
file conversion possibilities following the normal filter entries.

Original File Type Possible Conversions

Unicode (supported for Windows 98, “Normal Text”

2000, and XP)

UTF-8 (supported for Windows 98, “Normal Text”

2000, and XP)

UNIX “Macintosh Text”

“MS-DOS Text”

Macintosh “UNIX Text”

“MS-DOS Text”

Otherwise “Unicode Text”

“UTF-8 Text”
“UNIX Text”
“Macintosh Text”

Notes: Only one type of conversion is allowed (e.g. you can't save a Mac file
as Unicode).
Macintosh, Unix and DOS option are only available if Auto-Sense
File EOL is marked in Tools|Customize|Environment|File Options;
Unicode and UTF-8 are only available if Auto-Detect File Encoding is
marked on the same dialog.
You can also open a file as Unicode or UTF-8 (among others) from the
File|Open dialog.

Enable Auto-sense File EOL Option

To ensure that the correct end of line characters are being inserted for the file being
edited, CodeWright offers an Auto-sense File EOL option that automatically detects
and turns on the correct end of lines when a file is loaded. When selected,
CodeWright will look for line terminators when it first loads a file. It can detect DOS
(cr/lf), UNIX (lf), and Macintosh (cr) line terminators. If the file has UNIX style line
terminators, the E key is made to insert only a line feed (lf).

458 17- UNIX

Macintosh translations for both input and output are done at a low level and seem
like Unix files to the user (i.e. if you search through a Macintosh file in hex mode,
you will therefore find Unix style 0x0a characters instead of Mac style 0x0d
characters).

To select Auto-sense File EOL:

1. Select the Tools|Customize|Environment|File Options dialog.
2. In the File Loading/Reloading group, check the box Auto-sense File EOL.

Specify UNIX EOL Characters on a File Type or

Per File Basis
You can also specify the type of end-of-line characters that are inserted into a new
file (DOS, Unix, or Mac), and even choose to convert existing characters to the new
type. These EOL options can be found in the following locations:
n On the Options tab of Tools|Customize|Language, to specify an EOL style on a
file-type (e.g. .C, .TXT, HTML, etc.) basis.
n On the Options tab of Document/Window|Manager, to specify an EOL style on
a per-document basis.
After making the setting change for the EOL type, each file that belongs to the file
type selected for the Tools|Customize|Language|Options dialog, or each file that is
selected in the Document/Window Manager, is scanned to see if it contains
inappropriate EOL characters. If found, a dialog prompts you with the opportunity
to change the EOLs.
EOL characters are converted as follows:

File Type Characters “C” Escape Hex Regex

Characters Chars Chars

DOS CR (carriage \r\n 0x0d,0x0a \x0d\x0a

return), LF
(line feed)

UNIX LF \n 0x0a \x0a

Mac (file) CR \r 0x0d \x0d

Mac (document) LF \n 0x0a \x0a

For the Macintosh file type, the EOL characters will appear just the same as for UNIX
(just a line feed); CodeWright converts the CR to the LF as it reads the file, and
converts the LF to the CR as it writes the file. If you search through a Macintosh file
in hex mode, you will therefore find UNIX style 0x0a characters instead of Mac style
0x0d characters.

17- UNIX 459

Also, saving a UNIX file as MS-DOS Text or Macintosh Text has the same effect as
converting the EOL characters within the file, except that the file is also saved under
a new name. Refer to the preceding topic on Save File as New Type, in this chapter.

Search/Replace EOLs in the Source File

Besides changing the EOL characters for a selected file(s) or file type, you can easily
change existing EOL characters in your source file with a simple Search/Replace
operation. Do this by searching for one type of EOL character and replacing it with
another.

The Hexadecimal Values for End of Line Characters are:

0D = Macintosh
0A = UNIX
0D0A = DOS

Although you can search for a hexadecimal value (\x0A), it is better to use a regular
expression for this operation. See the topic Searching for control characters (binary/hex
data) in the chapter on Search and Replace and Navigational Tools for more information.
Example:
If you wanted to change your DOS EOL’s to UNIX EOL’s:
1. Mark the UNIX radio button in the EOL group for the appropriate file
type in Tools|Customize|Language|Options.
2. Go to the Search|Replace dialog.
3. Make sure you have the Regular Expression box checked.
4. Search for \n and Replace with \n. The meaning of the \n is a new line
(cr/lf or a lf).
Because the Macintosh EOL is a (cr) only, it is better to use \r when searching or
replacing it. To change your DOS EOL’s to Macintosh EOL’s:
1. Go to the Search|Replace dialog.
2. Make sure you have the Regular Expression box checked.
3. Search for \n and Replace with \r.

Macro for Automating Search/Replace Conversion

CodeWright offers an API macro that will do the UNIX EOL search/replace
automatically. API macros are described in the chapter on Extend CodeWright. To use
the macro, do the following:

460 17- UNIX

1. Click API Macros on the Tools menu.
2. In the API Macros Edit dialog, choose the UNIXEOLs macro from the drop-
down list under the Name edit box.
3. Run the macro using one of the following methods:
n Click Run in the API Macros Edit dialog.
n Click Close, and then click Run API Macro <UNIXEOLs> on the Tools
menu.
4. The macro will search the current document for all EOLs, and replace them
with UNIX EOLs.

Compiling UNIX Programs from

CodeWright
CodeWright executes compile commands by shelling to DOS and executing the
command, as though it was being run at a DOS prompt. The output of the compile/
build is then captured and presented in the CodeWright Output Window.

If you compile UNIX programs, you will need to do this outside of CodeWright, or
find a way to access your UNIX system from within CodeWright.

One possible solution is to use a Telnet implementation to issue commands

automatically from a file.
Example: Set up a file with necessary commands to do a build. Then use the
Build tool in CodeWright to launch a Telnet session to process the
file. CodeWright will parse the resulting output and step through
the errors.
Although Borland cannot assist in setting up access to UNIX systems, we can help
make the necessary customizations to the Build command, given that the Build or
Compile command can already be performed successfully from a DOS prompt.

Preserving Filename Case, File

Securities and File Links between
UNIX and Windows Environments
Filename case can be lost when saving files to UNIX systems from CodeWright. To
have UNIX system case-sensitivity in CodeWright, check Allow Case Sensitive
Filenames in Tools|Customize|Environment|File Options.

17- UNIX 461

The loss of filename securities and links between UNIX files can also be an issue
using the traditional file-saving method in CodeWright. To preserve file securities on
UNIX files, use the File Rewrite Save Method to save files (also on the File Options
tab).

To select these options, complete the following steps:

1. Select Tools|Customize|Environment|File Options dialog.
2. Mark Use file rewrite save method, and Allow Case Sensitive Filenames.
3. Click OK to save and exit the dialog.

462 17- UNIX

18- Configuration Files &
Command Line Parameters
This chapter gives an overview of the main configuration files used by CodeWright.
In most cases it will not be necessary to edit CodeWright configuration files, but in
the event that this becomes necessary, the information in this chapter gives an idea
of what those files do. This chapter also talks about command line options that can
be used from the CodeWright shortcut or other command lines to control the way
CodeWright loads.

Configuration and State

The following sections discuss the location and contents of configuration and state
files within CodeWright.

Location of the Configuration File

CodeWright configuration data is kept in a separate file. During initial installation,
the configuration file CWRIGHT.INI is placed in the same directory as your
CodeWright executable file. You may move it to another location, if you like, or you
may have several configuration files in different work areas. You may even specify
another name for the file.

If your CodeWright executables are installed on a network, you will almost certainly
want to place your configuration file somewhere else. By placing your configuration
file in a private or local directory, you ensure that you will not be using or changing
someone else's configuration.

CodeWright looks in several places to determine what configuration file to use.

When it finds a place where you have indicated the location of the configuration file,
or the file itself, it looks no further and proceeds to read the file.

Here are the places that CodeWright looks, in the order of searching:
1. It looks on the command line to see if you specified the /c parameter.
2. It looks in your environment for a variable named CWINI.

18- Configuration Files & Command Line Parameters 463

3. It looks in your working directory for a file named CWRIGHT.INI.
4. It looks in the directory containing CW.EXE or CW32.EXE, for the file
CWRIGHT.INI.
5. It looks in the Windows directory for the file CWRIGHT.INI.

The command line parameter, 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 which the configuration file resides. It may also name the file itself.
Example: The string may 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
working directory when it needs one. CodeWright has no problem running without
a configuration file, but it does notify you if one could not be found.

Introduction to Configuration and State

To properly understand CodeWright projects and workspaces, you need to have
some knowledge of how CodeWright maintains its configuration and how it
preserves its state between sessions. This will help you intelligently choose which
information to keep in which file. In addition, you may find it expedient to modify
the CodeWright configuration file 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 set up
CodeWright. This information may be put there during installation, through
modifying the settings in dialog boxes, or by directly editing the configuration file.
In the latter case, the configuration file might contain almost any CodeWright
commands. The configuration file is named CWRIGHT.INI.

464 18- Configuration Files & Command Line Parameters

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 by configuration statements.
n Headings that appear in a CodeWright configuration file include: [Editor],
[LibPreload], [Colors], [DefaultKeymap], [KmapAssign],
[RunOnce], [Printer], [Compiler], [VersionControl],
[Definitions] and [Fmatch].
n The configuration statements contain keywords with string assignments. For
the lines containing keywords, the format is as follows:
<function>=<param 1>[,<param 2>,...<param n>]
The following criteria apply:
3 Keywords are actually the names of functions in the CodeWright API.
3 The string assigned to the keyword contains the parameters required by
that function.
3 The assigned string may contain white space.
3 Parameters may be numbers, strings, constant identifiers and operators.
3 Variables and nested function calls may not be used as parameters.

State File
The State file contains information about the buffers and windows you had open the
last time you exited CodeWright. It also contains the more transient information
about your CodeWright settings, such as your search options and responses to
prompts. It follows the same rules as a configuration file, but it is normally limited to
one section named [State]. This file is named CWRIGHT.PST.

Other Files Containing Configuration Data

Project files also contain configuration information. These files are intended to be
swapped on the fly, whereas the configuration file remains constant throughout a
session. Note that the project file overrides any information duplicated in the
configuration file.

As you change settings in the various dialog boxes, you are automatically updating
your configuration. You may select which file the dialogs use to update
configuration information: the configuration file or the project file. You may further
select which categories of information are kept in which file. For more information
on how to store configuration information with your project see Storing Configuration
Options with a Project in the chapter Projects, Project Spaces and Workspaces.

18- Configuration Files & Command Line Parameters 465

The main question you need to ask yourself when deciding where to store
configuration settings is "Do I want these settings to travel with the project, or have
them apply to multiple projects?"
n To have settings travel with a project, store them in the project file.
n To apply settings to multiple projects, store them 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=1200
KeyRepeat=5
Autosave=20
SysSetFileLocking=30

[Colors]
ColorError=0xe0
ColorWarning=0xd4
SysSetDefault=DEFAULT_COLOR_TEXT,0x1f
SysSetDefault=DEFAULT_COLOR_SELECTION,0x9e

[Printer]
PrintFooter="-Page %p-"
PrintHeader="%f %d %t"
PrintFlags=145
PrintMarginBottom=0
PrintMarginRight=0
PrintMarginLeft=0
PrintMarginTop=0

[Definitions]
EvalStrAdd=DEBUG,1

[Compiler]
CompilerAssign='Borland C++','.c'

466 18- Configuration Files & Command Line Parameters

Example Interpretation
Here is an interpretation of the contents of the preceding example configuration file.
The analysis proceeds section by section:

[DefaultKeymap] Section
The default key command is set to BRIEF. This will cause BRIEF.DLL to be
loaded and its function brief to be called.

[KmapAssign] Section
In the [KmapAssign] section, a key assignment is added to the default keymap.
The Preprocess function is assigned to the C Backquote (`) keystroke.

[LibPreload]
One of the supplemental language support DLLs is loaded for use.

[Editor] Section
The [Editor] section of the example configuration file sets the keyboard delay
and repeat rate. Auto-save is set to occur after 20 seconds of keyboard inactivity.
File locking is enabled for 30 file handles.

[Colors] Section
The [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. The next two color settings may be set differently for each edit
window. For this reason, we do not use the functions ColorText and
ColorSelection to set the colors, but rather set what the default color will be.
You use the SysSetDefault functions when setting defaults for things that are
specific to individual buffers or windows. In this case, the color of text is set to
white on blue, and the highlight for the selection is set to yellow on light blue.

[Printer] Section
The [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 are not encouraged to modify the [Printer]
section.

[Definitions] Section
This section defines the label DEBUG and gives it a value of one. This label may
be used in numeric expressions processed by CodeWright, including those
given through the Command Key and the Preprocess function (#ifdefs).

If a project is loaded, CodeWright will look for calls such as EvalStrAdd in the
[Definitions] section of your *.pjt file instead.

18- Configuration Files & Command Line Parameters 467

 [Compiler] Section
In this section, the Borland C++ compiler is assigned for use on files that have
the .C file extension.

All of the sections discussed above contain configurations that can normally be
set from within CodeWright. In most cases, it is not necessary to directly edit
CWRIGHT.INI.

Processing At Startup
When CodeWright is launched, the command line is processed before the
configuration file or the state file. This gives the command line the opportunity to
specify the location of these files. It also means there is some potential for the
configuration file to reverse the effects of a parameter specified on the command
line.

Order of Processing
The following sections of the configuration file are automatically read at startup in
the order given:
n [Menu]
n [DefaultKeymap]
n [KmapAssign]
n [LibPreload]
n [Editor]
n [VersionControl]
n [Template]
n [Colors]
n [Ribbon]

After the portions of the configuration file that are automatically read have been
processed, the state file is processed. This gives settings in the state file priority over
similar commands in the configuration file.

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
always executed in the same order. The [Printer], [Compiler],
[Definitions] and other sections are processed as needed.

468 18- Configuration Files & Command Line Parameters

Descriptions of Sections
Each section heading represents a logical grouping of functions, as shown in the
following list:

Heading Functions

Colors Functions to set the colors for text, messages and so on.
This is done with the SysSetDefault function.

Compiler Used primarily by CodeWright for saving associations

between file extensions and compilers.

DefaultKeymap The function that sets the initial key command set, such
as BRIEF or CUA. For example, the statement
DefaultKeymap=BRIEF will cause CodeWright to
load BRIEF.DLL and call its keymap function, which it
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 Makes key assignments that are additions or

modifications to the default keymap.

LibPreload Loads 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.

Register Displays the CodeWright Registration dialog the first

time you run CodeWright. Depending upon user
response, this dialog may or may not be displayed
again.

Toolbar Defines modifications to the default toolbar and sidebar

configuration after using Tools|Customize|Toolbars
dialog.

18- Configuration Files & Command Line Parameters 469

 Heading Functions

Template Contains user-defined Language Template definitions.

VersionControl For defining command lines for Checkin, Checkout and

several other related commands. The section is
duplicated for each version control system defined, so
that you may have separate commands for each.

You may place any CodeWright function under any of the section headings, but
grouping functions logically under section headings will help ensure that the
functions are executed in their proper order. For example, you could place the
default keymap in the [Editor] section, but then the modifications and additions
made in the [KmapAssign] section would be lost when the keymap is loaded over
top of them.

User-Defined Sections
You may define other section headings and place other editor commands under
those sections. These commands will not be processed automatically at startup,
however.

Many functions you might want to create for assignment to a keystroke are a simple
sequence of functions to execute consecutively. Return values are not examined, and
no control structures are required. In most cases such tasks can more easily be
accomplished with the creation of a macro. However, they can also be done with
user-defined sections in the CWRIGHT.INI. A section can subsequently be assigned
to a keystroke in CodeWright.

Several examples of user-defined sections follow.

Change Search Direction

[ISearchBack]
SrchSetFwd=FALSE
ISearch=
SrchSetFwd=TRUE
This example simplifies the process of performing an incremental search
backward in the buffer. Usually, the search options are set to search forward.
You could bring down the menu, change the options, and then change them
back, after performing your incremental 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
key assignment like the one below, also in your configuration file:

470 18- Configuration Files & Command Line Parameters

 [KmapAssign]
KmapAssign="<F12>","ConfigFileRead '' 'ISearchBack'"
The previous key assignment causes CodeWright to do a backwards
incremental search when + is pressed. You can use similar key assignments to
implement other examples or sections of your own. Most key assignments can
be made more easily using the CodeWright Tools|Customize| Keyboards
dialog. For more information about assigning keys through the CodeWright
interface, see the chapter on Custom Interface.

Save and Restore Position

The following example can be used in place of the standard save and restore
position commands:
[RotateMarks]
MarkRestorePos=
MarkSavePos=
MarkRotatePos=

[StackMarks]
MarkSavePos=
MarkRotatePos=
n By using [RotateMarks] instead of the restore position command,
restored positions are not lost, but rather moved to the other end of the list.
You can then continuously cycle through your saved positions.
n If you use [StackMarks] to save your current position, you will restore
positions in the same order you saved them instead of the reverse order in
which you saved them.
Together, these two sections give a functionality similar to that of Microsoft
PWB.

Scrap Buffers
This next example makes good use of the multiple scrap buffers in CodeWright.
For it to be useful, you must first define more than one scrap buffer. To do this,
enter a value of 2 or higher in the Number of Scrap Buffers field on the
Tools|Customize|Environment|Clipboard dialog.

Use these sections instead of Cut, Copy and Paste:

[RingCopy]
BlockCopy=
ScrapNext=
MsgMessage="Copied to current scrap"

18- Configuration Files & Command Line Parameters 471

 [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-out ring of scrap buffers. Successive Copy or Cut operations (without an
intervening Paste) do not overwrite each other until you run out of scrap buffers.
Successive Paste operations let you paste the contents of each scrap buffer in the
reverse order they were used. The same functionality can more easily be achieved
using the Auto-increment scrap buffer option in the
Tools|Customize|Environment|Clipboard dialog.

Relating Checkboxes to Functions

There is a System Options checkbox in the Directories tab of the Project|Properties
dialog, and several more checkboxes in the Read Configuration Data from a File
dialog (to access the latter, click Read Configuration Data on the Project menu.) The
following list will help you relate those checkboxes to the contents of your
configuration file or project file:

Checkbox Option Related Configuration Function

View Themes Reads the [Colors] section of a configuration file

which contains one or more _RestoreViewSetup
lines. Each _RestoreViewSetup line defines a View
Theme.

System Options BookmarkAttr

ConfigSetBtnIniFilename
ConfigSetLinkDBFilename
ConfigSetMacroFilename
ConfigSetMarkDBFilename
ConfigSetSymbolDBFilename
EditSetPath
BufSetGlobalBackupSpec
ExtCommentSearchLimit
ExtDelayedColoring
ExtSetUpdateDelay
NameMarkFlags
NameMarkThreshold
KeyDelay
KeyRepeat

472 18- Configuration Files & Command Line Parameters

 Checkbox Option Related Configuration Function

Auto-save Options Autosave

AutosaveDir

Compiler Settings BrowseSetFile

CompilerAddBuild
CompilerAssign
CompilerNewExt
TagSetFile
CompilerAdd

Language Options ExtColors

ExtColorsAssoc
ExtIndentEnable
ExtIndentEnableAssoc

Version Control Setup CheckInSetCmd

CheckOustSetCmd

Filename Filters FilterAdd

FilterDeleteList

Clipboard/Scrap Options ClipboardEnableSepStr

ClipboardEnableTermStr
ClipboardSetSepStr
ClipboardSetTermStr
ScrapSetCount

State File
Another important CodeWright configuration file is the state file. The state file is
stored by default in the CodeWright home directory and is called CWRIGHT.PST.
CWRIGHT.PST records the condition of CodeWright at the time of exit.

Storing state information is turned on by default, but can be turned off in the
Tools|Customize|Environment|State dialog.

When a project is open, Window, Document and Mark information will be stored
with either the project (.pjt) or project space (.psp) file, as defined on the
Tools|Customize|Environment|State dialog. Other types of state information are
stored in the default state file CWRIGHT.PST.

If no project is open, all information is stored in CWRIGHT.PST.

18- Configuration Files & Command Line Parameters 473

Location of the State File
You may specify the location and name of your state file in your CodeWright
configuration file. If your configuration file does 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 to locate the configuration
file. The differences are as follows:
n The command line parameter for specifying the state file is /S. (See the section
on Command Line Parameters for more information.)
n The environment variable that points to the state file is CWPST.
n Instead of looking for CWRIGHT.INI it will look for CWRIGHT.PST.

Once again, if no location is dictated for the state file, and no existing file is found,
the file is created in the working directory. CodeWright can operate just fine without
a state file. In fact, you may turn off the saving of state information, and CodeWright
will ignore any state file and the information it contains.

Similar to the configuration file, the strings that give the location of the state file may
also dictate a name for the file. If the string names only a directory, the name
CWRIGHT.PST will be used. The following methods for setting the location of the
state file are all valid:
n Using the environment variable:
set CWPST=D:\BORLAND
n On the command line:
CW /sD:\BORLAND\CWRIGHT.PST
n 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:

Category Types of Data in State File

Windows Visible attributes

Colors
Coordinates and extents
System flags
Attached buffer, if any
Default Window Properties for the above

474 18- Configuration Files & Command Line Parameters

 Category Types of Data in State File

Buffers File name

Output file name
Tab settings
Backup file specification
Line and column
Maximum 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

Window frame coordinates and extents

Command Line Parameters

In the previous sections on configuration files, some command line parameters were
mentioned that could optionally be used with the CodeWright command line to
specify certain conditions to apply when CodeWright is launched. This section
describes those and other CodeWright command line parameters.

CodeWright supports a number of command line parameters. You may add these
parameters to the command line by editing the file’s shortcut, or through the File
Properties selection in the Program Manager's menu. If you have multiple
CodeWright shortcuts or program items, the command line may be used to have
each operate differently.

To edit the properties of a CodeWright shortcut, do the following:

1. Right-click on the CodeWright shortcut (wherever the shortcut appears).
2. Select Properties from the popup menu.
3. Click on the Shortcut tab.
4. The path and executable file are listed In the Target field. You can add a
command line parameter at the end of this string to tell CodeWright to use
specific settings when being launched.

18- Configuration Files & Command Line Parameters 475

CodeWright allows three types of command line parameters:
n Names of files to edit.
n Parameters or switches.
n The command file, which contains command line parameters.

The command line is processed before the configuration or state files have been
read. This has the following effects:
n It allows the command line to specify configuration and state file locations.
n It allows configuration and state files to override command line specifications.
This is not normally a problem, but possible conflicts are noted in the
descriptions below.

Filenames
You may specify any number of files to edit on the command line, limited only by
the command line length. You may use wildcards to specify multiple files. These
files are loaded in addition to, rather than in place of, any named in the state file.

Parameters
Consider whether you wish to allow the configuration file to be read before or after
each parameter that you specify. The configuration file may in some cases cause a
command line parameter to be ineffective if the parameter is processed first.

There are upper case and lower case versions of each of the command line
parameters, wherever applicable.
n Parameters specified with a lower case character will be processed before the
configuration file is read.
n Parameters that use an upper case character will be processed after the
configuration file is read.

Some parameters require additional information in the form of an argument. In the

descriptions that follow, the arguments appear in italics following the parameter.
When supplying an argument to a parameter, CodeWright permits the argument to
immediately follow the parameter, with no intervening white space, or to be
separated from the parameter by white space.

476 18- Configuration Files & Command Line Parameters

The parameters listed in the table on the next few pages are depicted as preceded by
a minus or dash character ( - ). While a slash will also work in most instances, these
can be mistaken for filename paths and should be avoided.

Sample Command Line Parameters

Type Format Description

Configuration -C<configLoc> Allows you to specify the

Location CW32 -c directory or file in which
Parameter c:\source\proj1 configuration information is to
be found. The <configLoc>
argument names that directory
or file.
n If <configLoc> names
only a directory,
CodeWright looks for a file
named CWRIGHT.INI in
that directory from which
configuration is read.
n If <configloc> names a
complete path, including
filename, CodeWright will
attempt to read
configuration information
from that file.
For additional location
information, refer to the topic
Location of the Configuration File,
in this chapter.

Variation of -C- Instructs CodeWright not to

Configuration CW32 -c- read a configuration file.
Location
Parameter

18- Configuration Files & Command Line Parameters 477

 Sample Command Line Parameters

Type Format Description

Go to Line -G <lineNumber> Tells CodeWright to go to the

Number line number indicated by the
CW32 -g215 argument. It should follow the
name of the file to which it
refers, and it may be specified
following each file named on
the command line.
This parameter will be
overridden if you attempt to
position the cursor in a file
loaded as part of the state
restoration.

Heap -heapalloc Instructs CodeWright to use

Allocation global allocation of memory.
Parameter CW32 -heapalloc This makes it easier to detect
allocation errors. Use this if you
suspect your DLL has this type
of memory error.

Keymap -K <keymap> Names a default keymap to be

Parameter used by CodeWright. If this
CW32 -k mycua parameter is used, the
[DefaultKeymap] section of
the CodeWright configuration
file (CWRIGHT.INI) will not be
read.
The <keymap> argument to this
parameter names a DLL (less
the .DLL extension) containing
the default keymap. The
argument at the same time
names the function (contained
in the DLL) which initializes the
keymap and makes the key
assignments.

478 18- Configuration Files & Command Line Parameters

 Sample Command Line Parameters

Type Format Description

Library -L <library> Designates a dynamically linked

Parameter CW32 -Lmyutils library to be loaded at startup
time. This parameter is useful
for testing user-created or
modified DLLs before a more
permanent installation. It can,
however, significantly increase
the amount of time it takes
CodeWright to start up.
The<library> argument is the
name of the library to be loaded.
If this argument does not name
a path to the DLL, CodeWright
will attempt to locate the DLL in
the current directory, in the
Windows directory, and on the
PATH.

Multi-Instance -M Allows you to run more than

Parameter CW32 -M one instance of CodeWright at a
time.

No Files -N Indicates that the state file is to

Parameter be processed, except that no
CW32 -N files from the previous session
are to be restored.

No Splash -NOSPLASH Suppresses the display of the

Parameter CodeWright opening splash
screen. This can save a small
amount of loading time.

18- Configuration Files & Command Line Parameters 479

 Sample Command Line Parameters

Type Format Description

Paragraph -P <section> Tells CodeWright to read the

Parameter CW32 -p "Windows named section of the
driver" configuration file. The section
will be read after all of the
standard portions of the
configuration file have been
read, to give it priority over the
other contents of the
configuration file.
The <section> argument to this
parameter is the name of the
section of the configuration file
to be processed. If you name a
section that is automatically
read at startup, it will be
processed twice. This section
name may contain white space.
If it does, however, it must be
enclosed in either single or
double quotes.

Limit -Processor = d This argument can be useful for

CodeWright avoiding thread-related
(d is a decimal number bit
CPU usage on problems that appear only on
mask for the allowed
multi- multi-processor machines. It can
CPUs used by CodeWright
processor also limit CodeWright CPU
on startup.)
machines usage, allowing more for other
processes.

Examples:
n '-Processor=1' limits
CodeWright to CPU 0.
n '-Processor=2' limits
CodeWright to CPU 1.
n '-Processor=3' limits
CodeWright to CPU 0 and
CPU 1.

480 18- Configuration Files & Command Line Parameters

 Sample Command Line Parameters

Type Format Description

State Location -S <stateLoc> Allows you to specify the

Parameter directory or file in which state
CW32 -s information is to be found.
h:\home\ericj
The <stateLoc> argument
names that directory or file. If
<stateLoc> names only a
directory, CodeWright looks for
a file named CWRIGHT.PST in
that 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 parameter does not
appear on the command line,
CodeWright looks for a state
information file in a series of
places, unless the saving and
restoring of state information
has been turned off. These
places include:
n A directory or file named
by the CWPST
environment variable.
n In CWRIGHT.PST in the
Working Directory.
n In CWRIGHT.PST in the
directory in which the
CW.EXE or CW32.EXE file
is located.
n In a location named in
CWRIGHT.INI.

18- Configuration Files & Command Line Parameters 481

 Sample Command Line Parameters

Type Format Description

Variation of -S- Instructs CodeWright not to

State Location read a state file. State
Parameter CW32 -s- information, however, is not
automatically reinitialized, and
may be used subsequently.

Execute -X <function> Names a function to be invoked

Function as part of CodeWright startup.
Parameter This function should not
attempt to perform any
configuration, since such
configuration may be
overridden or reversed by the
subsequent processing of the
configuration and state files.
The <function> argument to
this parameter contains the
function call. If the call contains
any parameters to the function,
the entire function call must be
enclosed in single or double
quotes. In addition, it must
conform to the syntax required
by LibFunctionExec.

Command Files
A command file is a file that may contain any valid command line parameters,
including additional command files. CodeWright identifies filenames preceded by
an @ sign as command files. Command files are formatted in the following way:
@<commandFile>
Command files are useful for overcoming command line length limits and also for
creating reusable, logical groupings of filenames and parameters.

White space or new lines may separate parameters within a command file. New
lines are often used to promote readability.

482 18- Configuration Files & Command Line Parameters

A- TagsWnn Utility
TAGSW32 is the Tags program supplied with CodeWright to automatically generate
a tags database and compile it into a format that can be used by the built-in browser.
The program is called when you select Build Tags from the Build menu. You may
not ever need to run the program from the command line, but in the event that you
do, or if you just wish to know more about the program, its options are briefly
described here.

TAGSW32 is based on the GNU Tags program written by John Kerchival. The
primary changes made to it are to allow output in the Borland Compiled Tags
format. This is the -p option, which is the only option we have added. Other
options are as described in the TAGS.DOC file supplied with the GNU Tags program
and provided with CodeWright.
Example: TAGSW32 {[OPTIONS] [SOURCEFILE|@LISTFILE]}

TagsWnn Command Line Options

An option summary follows, with the description following each option:

-h,-?
Obtain a detailed help screen directed to standard output.

@LISTFILE
Use LISTFILE as a "response" file. This file lists input filenames (with or without
wildcards) one at a time. Filenames may be separated by a plus sign (+), a comma (,),
a semicolon (;), or by whitespace.
In addition, comments are allowed within the LISTFILE. Comments are delimited
by placing a pound sign '#' before the comment. This is very similar to comments
allowed in a makefile, except that comments are allowed on any line or at the end of
any line, start at the '#' and go to the end of the current line. There must be at least
one character between the filename and the comment character [i.e. a plus sign (+),
a comma (,), a semicolon (;), or whitespace] to differentiate between the beginning of
a comment and a filename character (since '#' is a valid element of a filename).

A- TagsWnn Utility 483

-x{EXCLUDEFILE|@LISTFILE}
Exclude the files specified by EXCLUDEFILE or exclude all files listed in LISTFILE
using the same syntax described previously.

-tTAGFILE
Add new generated tags to TAGFILE. This file may or may not exist. All tags from
TAGFILE that were derived from files currently being parsed will be removed
during the merge phase. This tagfile is assumed to be in one of this utility's output
formats. If sorting is specified, then new tags will be merged in correct order with
current case sensitivity. Otherwise, tags will be placed at the beginning of the new
resulting tag file (this will result in quicker responses during tag searches while
editing). If -m or -s are used, this switch is ignored (all output is to stdout). The
behavior regarding existing files is determined by the case of the switch as follows:
-t (lower case) creates and outputs to a file overwriting any currently existing
file.
-T (upper case) merges all output to the tagfile if there is an already existing file.

-pCOMPILEFILE
Convert output tag file (specified by -t) into a compiled file suitable for use with
CodeWright. The output flag (-t) and the CodeWright output format flags (-oc) must
be specified for this flag, otherwise it is ignored.

-lLOGFILE
Output 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
is determined 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 be one of the following:
e Epsilon (>= V6.0) tag format
( tokenString {tab} fileName {tab} characterOffset {tab} lineText )
This format is used by the Epsilon editor (V6.x) created by Lugaru Software and
specifies the token identifier, the file name (including full path, normally), the
character offset of the beginning character (starting at character 0) and the text
of the line on which that offset is located.

484 A- TagsWnn Utility

 Epsilon (<= V5.03) tag format
( tokenString;fileName;characterOffset )
This format is used by the Epsilon editor (V4.x and V5.x) created by Lugaru
Software and specifies the token identifier, the file name (including full path,
normally) and the character offset of the beginning character (starting at
character 0).
g GNU tag format
( tokenString {tab} fileName {tab} /^lineText$/ )
This format is used by GNU's EMACS editor, originally written by Richard
Stallman and widely used in the UNIX community. This is also the format
created by its companion utility "ctags" which does very simple function header
tagging.
s Space-Delimited format
( tokenString fileName lineNumber )
This format is the simplest format available and requires very little parsing and
is very 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
a fair amount of effort has been expended to parse this format and move to the
location in the source specified during compilation stages. Many macros may
be modified 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 in
conjunction with a compiled database file format (see -p above). This is the
format used by the CodeWright editor.

-a[options]
This switch is used to specify the types of tokens for which tags are generated for
tagging of assembly files. All token types are tagged as the default ( -afdlmsu ).
Source modules are expected in 80x86 assembly using MASM/TASM syntax. The
location of the -a switch on the command line is important. All files (and files found
in LISTFILEs) will be tagged using assembly tagging (and the options specified on
that switch) until another -a or -c switch is found. Order is not important for the
options to this switch. Possible values for [options] follow:

A- TagsWnn Utility 485

 f procedure labels
( token proc )( proc token )
This is a mnemonic for function (which has nothing to do with a procedure call
in assembly, but does well for frail human memory). This option specifies
tagging 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). This
includes 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]
This switch is used to detail the token types to tag in C and C++ source files. All
token types are tagged by default ( -cdmstekuvcfpxi ). Source files are expected in
standard ANSI 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 options specified on that switch) until another -a or -c switch is
found. Order is not important for the options to this switch. Possible values for
[options] follow:

486 A- TagsWnn Utility

 d defines
( #define token statement )
This option specifies that defines are to be tagged (preprocessor defines). This
does not include macros which are an extended use of the #define preprocessor
directive.
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 of 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, ...} )
Note the cute spelling of constants with a 'k' to justify the assignment of this
letter. This option specifies tagging of enumeration constants within declared
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.

A- TagsWnn Utility 487

 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 be
output. The x option is a modifier and will only be effective when other options
are used (i.e. -cpx must be specified to obtain extern prototypes, -cx alone yields
nothing). Note also that the -cx modifier has no effect for function, define and
macro tags which are tagged only according to the f, d and m options
respectively. This modifier may be placed anywhere within the options list.
i static declarations
( static declaration )
This option will specify that tags that have internal static storage class are to be
output. The i option is a modifier and will only be effective when other options
are used (i.e. -cvi must be specified to obtain static variable declarations, -ci
alone yields nothing). Note also that the -ci modifier has no effect for define
and macro tags that are tagged only according only to the d and m options
respectively. This modifier may be placed anywhere within the options list.

-d
This flag specifies that all input listfiles and exclude response files should be deleted
once parsed. This allows an automated list file generation that is cleaned up by the
tags package. See description of LISTFILE that follows.

488 A- TagsWnn Utility

-j
This is the junk filter switch to allow the filtering of functions and declarations that
are overloaded operators in C++. For example, if the junk filters are enabled then
the declaration "inline myType operator+(MyType m1, MyType m2);" would not be
tagged for "+" which is normally a standard C delimiter token and operator. The
junk filter, if enabled, will filter all standard C delimiters from the output.

-q
This is the quiet switch and will suppress normal status output to stderr and
program version information.

-r
This switch will suppress the default output of the full file path name and will
specify the use of relative pathnames in the generated output.

-n
This switch will suppress sorting of the tag output (often used in conjunction with
GNU or Epsilon style tags).

-i
This switch specifies the use of a case sensitive sort (normally a case insensitive sort
is used). Although the character 'i' is normally used for switching to a case
insensitive behavior, it differs in this instance.

A- TagsWnn Utility 489

490 A- TagsWnn Utility
B- Making and Modifying
CodeWright DLLs
You can load DLLs, or Add-Ons, interactively from the Tools|Customize| Libraries
dialog to add functionality to CodeWright. In the CodeWright SDK, you can obtain
resources to create new DLLs, and resources to modify existing fundamental DLLs.

This chapter describes some of the CodeWright architecture as it pertains to the

construction or modification of CodeWright DLLs, as well as the preliminary
components of a CodeWright DLL. Also look for tips on compiling the DLLs.
Note: If you need more information about how to obtain the
CodeWright SDK, please contact a Sales Representative at
[email protected].
Consider modifying or creating a CodeWright DLL only if the following is true:
n CodeWright can not perform a particular function.
n There is no existing Add-On or macro that will add that function.
n Creating a macro is out of the question.

Source code for most CodeWright DLLs is provided with purchase of the
CodeWright SDK. The SDK also installs a \SAMPLE subdirectory that contains
source code for an essentially empty DLL, which can easily be modified to add any
function desired.

This section has three major provisions for changing or adding capabilities to
CodeWright through DLLs:
n It provides direction to the source code to be changed or added to.
n It provides some assistance for making the changes or additions.
n It provides tips on how to compile and make use of the changes or additions
that have been made.

B- Making and Modifying CodeWright DLLs 491

The first step to changing CodeWright is to understand its anatomy. The primary
executable, CW32.EXE, contains the CodeWright Application Programming Interface
(API). These are the functions and capabilities that are basic to CodeWright
operation. Although you cannot rewrite the functions in the API, you can replace
them, in a limited fashion. We will discuss function replacement later. The point is
that the source code for the main executable is not supplied.

External to the primary executable are several Dynamically Linked Libraries (DLLs)
which provide services in several areas:
n Core services.
n Supplemental language support.
n Keyboard command sets
n Auxiliary services.

The following illustration depicts the organization of the CodeWright software

system. The auxiliary and language supplements are not complete. CodeWright
offers more in these areas than would fit on a page. However, the picture gives an
accurate idea of the architecture in CodeWright.

492 B- Making and Modifying CodeWright DLLs

Core Services
The core services are those that CodeWright always expects to have available. Some
of these services are so essential that CodeWright is unable to properly initialize
without them. For example, you could use CodeWright if no keyboard command
sets were available -- you could even build or find a keyboard command set. If the
core services were missing, however, the keyboard commands would be of no use.

CWSTART DLL
The main DLL that starts CodeWright is named CWSTART.DLL. It performs
numerous initialization tasks, such as loading other DLLs and reading the
configuration file. The source code to CWSTART.DLL is provided in the CodeWright
SDK. Many of the extension functions are defined in this DLL. To utilize them in
your own source code you will need to include the header file CWSTART.H, which is
in CodeWright's \CWSTART subdirectory.

The file descriptions below will help you locate the functions provided in the various
source files for CWSTART.

Language Features

File Description

LANGUAGE.C The file that contains the engine for language specific
features, such as ChromaCoding, Template Expansion, and
Language Indenting. It relies on a series of functions being
defined elsewhere that incorporate the corresponding
filename extension into the function name (e.g., _c_indent(),
_pas_indent() ).

ASM.C This file contains the functions that support language

specific features for assembly language source files (.ASM
files).

C.C This file contains the functions that support language

specific features for C language source files (.C files).

CPP.C This file contains the functions that support language

specific features for C++ language source files (.CPP files).

CS.C This file contains the functions that support language

specific features for C# language source files (.CS files).

HTML.C This file contains the functions that support language

specific features for HTML source files (.HTML files).

B- Making and Modifying CodeWright DLLs 493

 Language Features

File Description

JAVA.C This file contains the functions that support language

specific features for Java language source files (.JAVA files).

PAS.C This file contains the functions that support language

specific features for Pascal language source files (.PAS files).

Utilities

File Description

AUTOSAVE.C Contains the functions in support of the Auto-save feature.

BKPT.C Provides support for setting breakpoints during

debugging.

BLOCK.C Provides support for block and column operations such as

changing to upper/lower case, and left/right column
justification.

BROWSE.C Provides support for use of CodeSense data on the Objects

tab in the Project Window and the Browse tab in the
Output Window.

COLLAPSE.C Contains the functions that support the CodeWright

Selective Display feature.

COMPILE.C Contains the functions for the Compile, Build, and

Rebuild selections on the Build menu.

CONFIG.C Contains the functions that read, write and process the
configuration file.

CWSTART.C Contains the functions that initialize the CWSTART DLL.

DLGMENU.C Contains the supporting functions for the Popup Menu

defined by CWRIGHT.MNU.

DLGUTIL.C Contains functions for enhancing CodeWright dialogs.

FILTER.C Contains the functions that support the Filter selection on

the Project Properties dialog.

NAMEMARK.C Contains functions for naming CodeWright bookmarks.

OUTLINE.C Contains functions for the CodeWright Outline Symbols

feature.

494 B- Making and Modifying CodeWright DLLs

 Utilities

File Description

OUTPUT.C Contains the supporting functions for the tabbed Output

Window.

PROJECT.C Contains certain functions relating to CodeWright

projects.

PROJVIEW.C Provides support for the Project tab of the Project

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 Word Wrap and

related features.

Error Parsing

File Description

ERRORFIX.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 Description

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

B- Making and Modifying CodeWright DLLs 495

 Macros

File Description

ENTAB.C The functions that support entabbing and detabbing the

current buffer are contained in this file.

EXECMAC.C Contains source code for CodeWright API Macros.

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.

REPEAT.C Contains the source code for the function Repeat, which
repeats a command a specified 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
Many of the CodeWright dialog functions are contained in the file
CWDIALOG.DLL. This library contains the dialog functions that support the
menuing and other interactive operations. The source code for the CWDIALOG
DLL is supplied with CodeWright.

There are a number of functions in this DLL that allow you to access the dialogs on
the menu directly. It is sometimes useful to assign these functions directly to keys, or
to call them from your own source code. These functions are the functions
beginning with Dlg... and Print. To use these functions, just include the file
CWDIALOG.H into your C source code. You will find this file in the CodeWright
CWDIALOG subdirectory.

CWHELP DLL
The CWHELP.DLL contains the functions that access the various Help libraries used
by CodeWright. 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 is CWHELP.DLL.

496 B- Making and Modifying CodeWright DLLs

If you want to call the function cwhelp from your C source code, you will need to
include the file CWHELP.H in your file. This header file is located in the CodeWright
\CWHELP subdirectory.

Keyboard Command Sets

CodeWright is supplied with six keyboard command sets, also called keymaps.
They are: Visual Studio .NET emulation, CUA (Common User Access), CUA
(CodeWright 4.0), BRIEF emulation, Epsilon emulation, and vi emulation. Each is
contained in a separate DLL. The CodeWright SDK includes the C source code files
and makefiles for each of these DLLs, with each set of source code installed in its
own subdirectory. (For more information on the CodeWright keymaps, refer to the
topic Using Keymaps in the chapter Custom Interface and the topic Creating New
Keymap Command Sets in the chapter entitled Extending CodeWright.)

Supplemental Language Support

Most ChromaCoding language support for CodeWright is now provided through
the use of ChromaCoding lexers. CodeWright comes with a large number of lexers
for a multitude of languages. A list of the lexers available can be viewed in the
Tools|Customize|ChromaCoding Lexers dialog. While it is possible to alternatively
get ChromaCoding support from DLLs, it is usually preferable to get ChromaCoding
from lexers.

DLLs continue to provide other language support features such as brace expansion,
smart indenting, and so on. For C/C++, C#, Java, Pascal, HTML, and Assembly, this
type of support is built into the CodeWright CWSTART DLL, and is therefore
available by default when CodeWright loads. Additional DLLs are also available to
provide this kind of support for other languages. Unlike CWSTART, however, these
DLLs are not loaded in CodeWright automatically when it loads. If they are needed,
you can load them manually by placing a checkmark next to the appropriate item in
Tools|Customize|Libraries. Here is a description of the language support DLLs that
can be loaded manually:

DLL Description

BAS.DLL This DLL contains functions that support language specific

features for Visual Basic for Windows (.BAS files).

COB.DLL This DLL contains functions that support language specific

features for COBOL source files (.COB files).

CWHTML.DLL This DLL contains functions that support language specific

features for HTML source files (.HTML files).

B- Making and Modifying CodeWright DLLs 497

 DLL Description

CWPERL.DLL This DLL contains functions that support language specific

features for Perl (.PL files).

CWXML.DLL This DLL contains functions that support language specific

features for XML (.XML files).

PRG.DLL This DLL contains functions that support language specific

features for dBASE and Clipper language source files (.PRG
files).

SC.DLL This DLL contains functions that support language specific

features for Paradox PAL source files (.SC files).

The source code for the above DLLs is provided is provided with the CodeWright
SDK. Additional language DLLs and source code are also available on the
CodeWright CD (in the Add-Ons directory), and on our website at
http://www.codewright.com.

When you enable a DLL, it adds a statement to your CodeWright configuration file
(CWRIGHT.INI). Here are example load statements for these DLLs:
[LibPreload]
LibPreload=PRG.DLL
LibPreload=SC.DLL
LibPreload=COB.DLL
LibPreload=BAS.DLL
LibPreload=CWPERL.DLL
LibPreload=CWHTML.DLL
LibPreload=CWXML.DLL
The preceding statements load the DLLs and make the functions in them
immediately available for use. This does have the effect of slowing the initial loading
of CodeWright. An alternative is to use LibAutoLoad rather than LibPreload. This
will cause the DLLs to be loaded only on demand. It does, however, require listing
all of the functions in the DLL in the statement. See the description of this function
for details under Help|CodeWright API Library.

Auxiliary Services
The Auxiliary Services or DLLs provide support for supplemental features. These
features or groups of features are generally provided in separate DLLs. The source
code for each DLL, if provided, is in a subdirectory within the CodeWright home
directory. Each subdirectory is given a name that is the same as the root name of the
DLL.

498 B- Making and Modifying CodeWright DLLs

These features or DLLs are Add-On packages that may not be required by every
user. Like the additional language support DLLs, they may require a little setup to
use. They are generally not loaded automatically.

DLL Description

CODEMEET.DLL This DLL contains the functions that support

CodeMeeting functionality within CodeWright. It is
loaded automatically.

CWBROWSE.DLL This DLL contains the main support for CodeWright's

Browser (the Browse tab on the Output Window). This
DLL is loaded automatically, when needed.

CWBSC7.DLL This DLL supports the use of Microsoft Browser

databases (C/C++ V7.0+) with the Browser. It is loaded
as needed.

CWDDE.DLL This DLL contains the functions that turn CodeWright

into a DDE server. Other applications can then operate
CodeWright remotely to perform syntax checking, Lint,
and Tags database updating. The DLL is not loaded
automatically.

CWLDRAW.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 using OEMfixed, 8514oem,
terminal, or similar font. If not, these lines will be
displayed as international characters. It is not loaded
automatically.

CWTAGS.DLL This DLL supports the use of the Borland compiled Tags
databases with the Browser. It is loaded as needed.

CWWEB.DLL This DLL supports loading files edited in CodeWright

into various Web browsers. It is not loaded automatically.

Sample DLL
As mentioned, the source code for creating an essentially empty sample DLL is
included with the CodeWright SDK. You will find it in the SAMPLE subdirectory
installed by the SDK. You can put some flesh on this skeleton, or you may use it as
an example of what elements go in to a CodeWright DLL.

The source code contained in SAMPLE.DLL is a skeleton of comments and a

function stub or two. The comments show you where to insert additions or changes
that you want to make to CodeWright.

B- Making and Modifying CodeWright DLLs 499

These insertions might include:
n Loading other DLLs, possibly written in a programming language other than C.
n Adding event handlers.
n Setting defaults, much as you would in the configuration file.
n Adding key commands.
n Writing and installing replacement functions.

A makefile is also included for this DLL.

Dissecting a CodeWright DLL

Your compiler imposes certain requirements in order to correctly produce a
Microsoft Windows-compatible DLL. In addition to those requirements, there are a
few essentials required by CodeWright. This section will help you understand what
CodeWright requires 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 DLL’s _init function, if the
library has one. This is the function you use for initializing the DLL and letting
CodeWright know what functions the library has to contribute. Generally, this
function consists of a series of LibExport function calls, 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 before you can make full use of them. If you don't register them with
CodeWright, you will not be able to assign them to a key or call them from the API
Command Key. You register or export the functions with the LibExport function.
This is in addition to any export declarations required by the programming
language.

500 B- Making and Modifying CodeWright DLLs

This requirement is a result of the use of Pascal calling conventions. When using
Pascal calling conventions, the program stack would become unbalanced if any
function parameters were omitted. Yet, the function LibFunctionExec, which
services the API Command Key and the key assignments, has no way of knowing
the type and number of parameters required unless you tell it. The LibExport
function does this.
Note: If you change the number or type of parameters in a DLL function,
you must remember to change the corresponding LibExport call that
registers that function.

Making Changes and Additions

When you have determined that you are going to modify the CodeWright source
code, you have two approaches available to you. You can change existing functions
or add new functions to the system.

Changing Existing Functions

If your change is small, and you want the change to be reflected whenever a certain
function is called, changing an existing function is often the best way to go. This
usually avoids the need to create or change a LibExport call.

For example, you might want to change the function that moves the cursor ahead in
increments of a word. You can be relatively certain that this function is going to be
called as the result of some key command.

If you were less certain about what other routines might be using the function, you
would need to consider the effects of your changes on those other routines. If you
are in serious doubt about what routines may be relying upon the function, it is best
not to change it. Instead, create a new function that is called when you want it, and
leave the old function in place for the routines that use it.

Adding Your Own Functions

When adding your own functions, you must be sure that they are declared in the
same manner as other CodeWright functions. You won't be able to assign your
functions to keys, call them from the API Command Key, and other useful things,
unless you properly export your functions to CodeWright. This means using
LibExport.

If you create a new file for your functions, you will have to be sure it uses the
necessary header files (CWSTART.H, CWDIALOG.H, CWHELP.H...), and that it is
included in the compile and link.

B- Making and Modifying CodeWright DLLs 501

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 as Pascal calling conventions, exported, and so forth. Here is
an example of its use:
void DLL
KeyNotInUse( void ) {
SysBeep();
MsgWarning( "Unassigned key" );
}
Note that 2000 and XP are case-sensitive in function names, whereas Windows 98 is
not.

Recompiling a DLL
Once you have installed the CodeWright SDK, part of the CodeWright directory
structure is a miniature of that used by most C compilers. There is 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 can do this manually, or through the use of a MAKE utility
or Project file, if your compiler supports these things.

Using and Modifying the Makefiles

There are two types of makefiles supplied for each of the CodeWright DLLs that can
be modified. Only one type is installed for each subdirectory containing DLL source
code. The type installed depends on the choice made between Microsoft or Borland
when installing the CodeWright SDK.
As mentioned, once the makefiles are installed, they can be found in the same
directory as the source code for the DLL that is being built. Microsoft makefiles have
the same root name as the DLL they make, with no extension. Borland makefiles use
the same root name as the DLL, but their extension is .MAK.
The makefiles that CodeWright supplies are specific to one compiler or another
because of the compile and link command lines that they employ. Adapting them to
a compiler other than Borland or Microsoft should be a fairly straightforward task.
The compiler needs to know that you intend to create a 32-bit DLL. Defining the
environment variable CPU is normally sufficient to cause the Microsoft makefile to
generate a 32-bit DLL. Alternatively, you may generate a 32- bit DLL for Borland or
Microsoft by defining a macro named WIN32 at the beginning of the makefile:
WIN32=TRUE

502 B- Making and Modifying CodeWright DLLs

The DLLs themselves are generated in a subdirectory of the source file directory. The
name of the directory varies depending on source type (Borland or Microsoft) being
compiled. Usually it will be something like “Release” or “Rel”. Once the DLL has
been compiled, it is advisable to move it up to the CodeWright executable directory,
although this is not required.
The Borland compiler often relies on configuration files and command line switches
to locate include files and libraries, rather than environment variables. As a result, it
may be necessary to modify a macro definition in the Borland makefile to indicate
the location of these files, unless you have installed the Borland compiler in the
default directory. If you have installed your Borland compiler in another location,
modify the value assigned to BORPATH toward the beginning of the makefile.
For example, if you installed the compiler in the directory D:\BC, change the
assignment to read as follows:
BORPATH=D:\BC

Adding Files
Groups of related files have been defined as macros toward the beginning of each
makefile. This facilitates operating on the filenames as a group. Also, if you choose
to place the source code for some extensions to CodeWright in a separate file, you
can readily add those filenames to the macro definitions. If the makefile employs a
linker response file, such as CWSTART.LNK, don't forget to 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 would use for compiling any Microsoft Windows DLL. CodeWright DLLs
must be compiled using Large Memory Model. If you specify your include
directories on the command line, be sure to include the CodeWright \CWSTART and
\INCLUDE subdirectories in your command. You will find that this has been done
for you in the makefile.

Similar requirements apply to your Link command. Begin with your basic Link
command line for producing a Windows DLL. The libraries in the CodeWright \LIB
subdirectory must be linked with the other objects. A standard .DEF file has been
supplied for each DLL.

Link Libraries
The makefiles provided make reference to certain libraries in the linker command.
You may find it useful to know the purpose of each of these libraries in case you
have a different version of the same compiler or would like to construct a similar
command line for a compiler not supported.

B- Making and Modifying CodeWright DLLs 503

Microsoft Link
The command line for invoking the linker is defined in the CWMAKE.INC file that is
included at compile time. CWMAKE.INC is stored in the \INCLUDE directory of the
CodeWright installation directory.

The libraries used in this link command usually include LIBW.LIB, OLDNAMES,
LDLLCEW.LIB and CWRIGHT.LIB. The files LIBW.LIB and CWRIGHT.LIB are
import libraries. They don't contain any object code themselves, but rather tell
where the routines may be accessed at runtime:
n LIBW.LIB points to addresses in USER.EXE, GDI.EXE and other executables that
provide the Windows API.
n CWRIGHT.LIB points to addresses in the CodeWright kernel that support the
CodeWright API.

You may need to link in other import libraries at times, for example, if you are
making direct calls to routines in CWSTART.DLL, CWMATCH.DLL or a DLL of your
own creation. If you don't have an import library (.LIB) file corresponding to the
DLL you are using, you can create one with the ILIB utility supplied.

LDLLCEW.LIB
The library LDLLCEW.LIB contains object code to use when creating Large
Memory Model Windows DLLs. Depending on your installation of Microsoft C,
you may find that your Large Memory Model library is named LDLLCAW.LIB
instead. Alternately, you may find that you have not installed any large model
library at all. If so, you can run the setup program that came with your compiler
to add to your installation. If you use a library intended for any other memory
model, you are guaranteed to have a program that doesn't work right and will
probably crash Windows.

OLDNAMES.LIB
The library OLDNAMES.LIB is included to avoid unresolved externals. This is
because Microsoft changed the names of some of their library routines. See
your MSC 7.0 README file for details. If you are using an older version of the
Microsoft compiler, you should remove this library from your command line.

Borland Link
Below is a portion of the input script for TLINK that is included at compile time for
Borland C/C++:

..\lib\cwright.lib+
import.lib+
cwl.lib

504 B- Making and Modifying CodeWright DLLs

The purpose of these libraries follows closely the libraries described above for
Microsoft. The libraries CWRIGHT.LIB and IMPORT.LIB are import libraries.
Borland supplies IMPORT.LIB to you for the Windows API, and CWRIGHT.LIB for
the CodeWright API.

You may need to link in other import libraries at times, for example, if you are
making direct calls to routines in CWSTART.DLL, or a DLL of your own creation. If
you don't have an import library (.LIB) file corresponding to the DLL you are using,
you can create one with the ILIB utility supplied.

The third library CWL.LIB contains object code to use when creating Large Memory
Model Windows DLLs. This library was named CWINL.LIB in versions prior to 3.0.
Use only a Large Memory 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 on your own, rather than modifying one of those supplied. It is expected
that if you write a new command set for the keys that you will place it in a separate
DLL. You can then use the DefaultKeymap function to facilitate loading the DLL
and calling the keymap subroutine that makes the key assignments.

Your DLL will need all of the same parts described in the preceding section
Dissecting a CodeWright DLL, regardless of what language you use to produce it. Be
sure to compile using a Large Memory 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 your configuration file. If your DLL is a keymap and supporting
functions, just change the name assigned to DefaultKeymap to the basename of the
DLL file; if your DLL is named MYKEYS.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 a couple of options:
n Always load the functions at startup-time, OR
n Tell CodeWright to load them when needed.

The following examples assume that you have put your DLL in the CodeWright
home directory, or in a directory to which your CWLIB environment variable points.

B- Making and Modifying CodeWright DLLs 505

Load Functions at Startup
Loading functions at startup may slow down the initial loading of CodeWright, but if
you have a fast CPU and hard disk, you probably won't notice much difference in
daily use. This is set automatically when the library is loaded in the CodeWright
Tools|Customize|Libraries dialog. Loading the library in this dialog adds the
following line to the [LibPreLoad] section of the CodeWright configuration file
(CWRIGHT.INI).
LibPreLoad=myDLL

Load DLL as Needed

The second option, loading the DLL only as needed, can cause a short pause when
the function is first called. It must be done manually by placing the following
commands in the configuration file under the [Editor] section.
LibAutoLoad=”myDLL func1 func2”

This option requires that you supply the names of the functions in the DLL, which
may be called. For more information on configuration files, refer to the chapter
Configuration Files and Command Line Flags, in this manual.

506 B- Making and Modifying CodeWright DLLs

Index Command Key 398
Expression Evaluator 399
Return Values 398
API Macros 171, 397
CodeWright Event Handling 451
Symbols Comments 435
Conditional and Iterative Control
${FTEE} 181, 203, 205 Structures 448
% macros 96 Creating and Editing Macros 433
%Q macro 185 Differences between API Macros
.CHM Help Files 150 and C 453
.HLP Help Files 149 Expressions 441
.INI Files Identifier Naming Rules 435
ChromaCoding 74 Language Definition 434
.IVT Help Files 151 Literal Values 437
.MVB Help Files 151 Run-time Error Handling 451
_init 500 Statements and Statement Blocks
Function 455 448
String Functions 453
A Variables 435
AppBasic Edit Tab on the Output
Window 48
Accessing AppBasic Macro Language 397, 414
CodeWright Functions from Perl AppBasic Edit Window 429
Scripts 409 AppBasic Edit Window
Errors 191 Configuration 429
Perl functions 410 AppBasic Edit Window Toolbar 429
activestate 414 AppBasic macros 419
Adding Your Own Functions 501 AppBasic-related API Commands
Add-Ons/DLLs/Libraries 428
Additional Add Ons on the CD 43, Choosing an Editor 415
66 Choosing Toolbars 417
Add-Ons 397 Creating a Handler 418
Language DLLs 74 Creating a Macro 418
Loading 43, 66 Creating an Event Handler 424
Alternation and Grouping 264 Debugging Macros 425
ANSI Dialog Editor 417
CodeSense translation 124 Environment 415
API 63 Exported Functions in
API (C-like) Macros 432 CWBASIC.DLL 430
API Command 106, 410, 429, 432 Initialization Subroutine 420
API Command Prompt Load Macros Dialog 427
API Command Key/Prompt 64 Modal User Dialog 421
Command Completion 64 Object and Proc Lists 420
Command Key/Prompt 64 Object Browser 417
using 64 Pop-up Menu 417
API Functions 397 Related API Commands 428

Index 507
 Running the Macro 424 Borland C++ Builder File
Special Keybindings 415 Synchronization 233
User Dialog Editor 421 Borland Link 504
Window Configuration 429 Brace 106
assemblies 201 Align 108
Assign Keys dialog 358 automatic positioning 108
Auto Sync Makefile/ Visual Studio Brace 106
Workspace 167 Brace Expansion 108
Auto-hide BraceFindEx 107
Toolbars 334 BraceMatch 106
auto-list members BraceMatchNext 106
CodeSense 122 Expansion 91, 108
Auto-parameter Info highlighting 106
CodeSense 124 kissing 107
Auto-Save Settings 367 locating 107
Auxiliary Services 498 locating square brackets 107
matching 105
B matching parentheses 107
parenthesis locating 107
back to previous document position BraceFind 107
55 BraceMatch 106, 107
Backup Files 371, 475 BraceMatchNext 106
Backups break
Format Controls 372 a long search 256
Formatting the Backup Specifica- Break Points 425
tion 371 AppBasic 426
Global 367 BRIEF 64, 354, 398
Individual Files 370 Command Set 352
Specific File Types 370 Keymap 352
Turning off 393 Browse
Balloon C++, C# and Java 285
CodeMeeting Notification 387 Object 417, 427
Beautifying Code 320 Browser
Format Source 87 Database 171
Bi-directional synchronization 239 Filter Toggle Buttons 277
Binary Files Inspect window 273
Omit Matches from Search Results Jump to Code 275
247 Objects Window 272
Binding Keystrokes to Functions or Query Buttons 275
Macros 360 Selecting a Database 273
Block Alignment 111 String Search 275
Bookmarks 171 Support 272
Current Position 293 Toolbar 273, 274
Global 292 Traversing the Tree 273
Local 292 Tree window 273
Saving Unnamed and. Named 293 Tree, expand or collapse 273
Window 293 Window 273

508 Index
Browsing Matching 261
using Microsoft .BSC files 271 Chat
BSC file 273 With other CodeWright Users 50
Bufsethexascii 399 ChromaCoding 434, 493
Build 190, 191, 201, 206 .INI Files 74
Command Line 176 Adding a New File Type 88
Tool 181 COBOL 141
Utilities 174 color-timing 86
Build Menu 39 enable coloring 88
builds 201 for embedded languages 86
Button File 171 maximum number of
Button Links 171 comment-lines 86
Comment prefixes 295 Numbers 81
Defining buttons 295 Regular Expressions 81, 82
How it works 295 Search Output 249
Insert Link 38 Side-by-Side Difference Window
What you see 295 302
Buttons 38, 295 Strings 80
action 38, 295 Use to Restrict Searches 22, 253
Adding and Changing Toolbar ChromaCoding Lexer Settings
Buttons 336 Default 75
Binding a Function to a Button 337 Dialog 75
Information File 338 Dialog (Comments tab) 79
Dialog (Numbers tab) 81
C Dialog (Strings tab) 80
Dialog (Words tab) 78
C Item Settings 79
CodeSense Support 113 List Settings 79
Language Operators 399 ChromaCoding Lexers 43, 74, 85
Language Support 84 add keywords 78
C# add operators 78
CodeSense Support 113 Adding Comment Delimiters 79
Language Support 84 adding keywords from a file 78
C++ Adding Numbers 81
Browse 285 Delete keywords 78
CodeSense Support 113 Deleting Lexers 83
Language Support 84 Digits field 82
Call Tree 287 Exclude Text from Coloring 77
Called By 276 Identifier Characters 76
Calls To 276 Identifiers 76
CARP.PM 413 Lexer names 75
Case Multi-line Comment 80
Changing Upper, Lower 40 Regular Expressions 13
Centering text 40 Single Line Comments 80
Changing Existing Functions 501 user-defined keywords 78
Character Class browser 285
Classes 76, 82, 262 Clipboard 147

Index 509
 Multiple 147 ANSI translation 124
Tab 147 Auto-list Members 122
Viewer 148 Auto-parameter Info 124
ClipView Tab on the Output Window Auto-type information 123
48, 148 C, C++, C# and Java 113
Closed Selections 354 Create library database 117
COBOL 142 Current Document Lookups 115
Automatic Time/Date Stamp 143 database files 120
Automatically Continue Strings 144 delete library database 118
ChromaCoding support 141 edit library database 117
Column 72 142 Extended Functionality 124
Comments only after column 72 Filter Lookups by File Type 119
142 from files that are open in
DLL 141 CodeWright 115
Line Number Handling 143 libraries 116
Resequence Line Numbers 142 Library Database Properties 114
Toggle comment 143 Main Features 121
Validate Line Number Sequence Maximum Cache Size for Lookups
144 127
Code Name Completion 121
Beautification 320 parser priority 118
Reformatting 87 Project Database Properties 114
Review from Different Locations 50 Symbol Lookups 127
Code Composer Troubleshooting 128
Bi-directional synchronization 239 Unicode translation 124
synchronization 237 CodeWright
CodeFolio Snippets 50, 91, 99 Registering 31
adding 102 Source Code Modules in SDK 89,
Adding or Removing Directories 491
104 CodeWright API 398
Code Snippet Properties Dialog 103 Functions 63, 405
Creating a Snippet from Clipboard Use functions interactively 63
or Document Selection 102 CodeWright Event Handling 451
Deleting or Renaming 103 CodeWright Libraries 66, 74
directories 99 CodeWright SDK 89, 491
Directory on File|New Dialog 36 Collapse text 268
Editing 104 Colors 69
Executing 101 changing colors 70
Properties Dialog 103 changing individual screen
Tab on Project Window 50 elements 70
using 99 changing whole background only
CodeMeeting 70
Chat Window 50 ChromaCoding Lexers 74
File Sharing 50 for embedded languages 86
Notification Balloon 387 Restrict searches based on
Tab on Project Window 50 ChromaCoding 22, 253
CodeSense 44, 113

510 Index
 Side-by-Side Difference Commands 202
Window 302 directory structure 204
Synchronize text background 70 Name 202
Columns Name (creating, deleting) 202
Formatting 40 setting up 201
Marking 354 Conditional statements
Selection 354 API Macros 448
Combo Box History Lists 339 CONFIG.PM 413
Combo box lists 339 Configuration
Command Files 482 Hierarchy 198
Command Key 64, 106, 269, 398, 475 Project Files 465
API Command Prompt 64 Reading settings from other
BRIEF keymap 64 files 173
CUA keymap 64 Wizards 32
examples 399 Configuration and State
using 64 Command Line Parameters 475
VI keymap 64 introduction to 464
command line length limits 185 Configuration File 4, 477, 478, 480
Command Line Parameters 4, 475 Command Line Parameter 464
Command Files 482 Contents and Purpose 464
Order of Processing 476 Example 466
Samples 477 Location 463
Types 476 Options (Dialogs and Functions)
Command Options 182 472
Commands Processing at Startup 468
Build, Rebuild, Debug, Execute, User-Defined Sections 470
Compile 39 Constants
Find Next Error 39 Return Value 399
Comments 129 Tab Completion at the Command
API Macros 435 Prompt 64
Comment Box 129 Control Structures
Comment Boxes 91 API Macros 448
comments and comment boxes 87 Convert Files to Supported File Types
inserting 39 458
Restrict searches to 22, 253 Copy 146, 356
Common User Access 351 Core Services 493
Compact Mode 269 CPAN 414
Compile 201, 206 Create a Document Dialog 36
command line compilers 174 Create New Document Dialog 36
Specified Target 204 Creating
Tools 178, 202 API Macros 433
Utilities 174 ChromaCoding Lexer 75
Compile and Link Options 503 Perl Scripts 405
compiled tags database (.ptg) 171 Project 161
Compiler 191, 202, 203 Windows With A Mouse 357
command line 203 Ctags Support 277
command line length limits 185 CUA 64, 351, 352, 354, 398

Index 511
 Keymap 352 CWRIGHT.PST 481
CUA Keymap 352 CWSTART.DLL 493
Cursor CWSTART.H 493, 501
Placement After Search 265
Custom Error Parsers 189 D
making 190
Custom tools 44, 179, 201 -d flag 410
creating 179 data types 417, 427
Customization 401 Debug 201
Using your own DLL 505 Compile 191, 201
Customization Button Debugging
CodeWright Status Bar 41 Your AppBasic Macro 425
Customize Dialog Default
Environment option 66 Backup Specification 372
Customize|Language 84, 85, 110, 112, Keymap 478
370, 372, 374 default 333
Customize|Libraries Dialog 74 DefaultKeymap 505
Customizing the CodeWright Delphi File Synchronization 231
Interface DeTab 110
Dockable Toolbars and Windows Detachable Tabs
331 Project Window 332, 333
Keymaps 351 Differencing
Menus 339 Advantages 297
Mouse Commands 353 Analysis Dialog (Interleaved) 298
Toolbars and Buttons 336 Difference Analysis Dialog
cwbLoadFile 424, 428 (Side-by-Side) 300
cwbShowProcDisplay 429, 431 Directories 309
cwbShowToolbar 429, 431 Directory Difference Analysis
cwbUnloadFile 428 Dialog 309
CWConst 411 Directory Differencing Output 311
CWD 246 Ignore Whitespace 299
CWDDE.DLL 499 Interleaved 298
CWDIALOG DLL 496 Interleaved Document 300
CWDIALOG.H 496, 501 Interleaved Options 299
CWExec 412 Print from Side-by-Side Difference
CWHELP.H 501 Window 155, 307
CWLDRAW.DLL 499 Reference vs. Target File 299
CWP.DLL 409, 413 Side-by-Side 300
cwp.dll 405 Side-by-Side Difference Window
CWP.PM 405, 409, 413 301
CWP.XS 413 Side-by-Side Edit Mode 304
CWPERL.DLL 413 Side-by-Side Options 301
CWPERLI.DLL 413 Side-by-Side View Only Mode 302
CWPERLI.MNU 413 directories
CWPerlIO 412 differencing 309
CWRIGHT.INI 424, 429, 498 differencing output 311
CWRIGHT.MAC 432 Edit Search Path 172

512 Index
 system files 170 DYNALOADER.PM 413
using to organize the Project Tab of
the Project Window 168 E
Displaying Return Values 398
Dissecting a CodeWright DLL 500 Edit
DLL Extensions 403 API Macros 433
DLLs 397 Menu 37
Compile and Link Options 503 Search Path 172
CWDIALOG.DLL 496 UserDialog 421
CWHELP.DLL 496 Elision 269
CWSTART 493 Email 8
Dynamic Link Libraries 66 embedded language support 86
Installing your DLL 505 EnTab 110
Link Libraries 503 Environment 69
Makefiles 502 Dialog and options 66
Organization of DLLs within Setting up the 204
CodeWright 492 Space 204
Recompiling 502 EOF
Source Code 401 Virtual Lines After 84
Supplemental Features 498 EOL
Supplemental Language Support Virtual Space After 84
497 Epsilon command set 352
Typical Contents 500 Error
Using your Own Custom DLLs 505 Find Next 39
DLLs/Libraries/ Add-Ons Error File 188
loading 43, 66 Error Handling
Dockable API Macros 451
Toolbars 417 error output 187, 190
Toolbars and Windows 331 accessing compiler, linker and as-
Document sembler 189
Difference between windows and Error Parsers 189, 190
documents 44 Error Parsing
Menu 40 Supporting Files 495
move forward and back 55 errors
Document/Window Manager Dialog accessing 187, 191
46 EvalExpression 411
DOS Evaluate Expression and Add Watch
Changing EOL 84 AppBasic 426
Save File as New Type 458 event handler 424
Drag and Drop EventHandler in AppBasic 424
Copy 356 Example Configuration File Settings
File Loading 357 AppBasic 430
Move 356 Exclusive Selection 353
Projects and Project Spaces 358 Execute 201
Text 356 Exiting and Macro return values
Visual Studio workspaces and API Macros 448
projects 358 Expand / Collapse 358

Index 513
Expanding And Collapsing Text 358 Type defined 84
EXPORTER.PM 413 File Sort Mode on the Project Tab of
Expression Evaluator 399 the Project Window 168
Expressions FILE.TPL 95
API Macros 441 Filename Component Macros 183, 184
ExtAssignTemplate 93 Uppercase vs. Lowercase 185
Extending CodeWright Filename Transformation 371, 372,
API Functions 397 373
Changing and Adding Functions Filenames 476
501 Short vs. Long 185
Core Services 493 Files
Creating New Keymap Command Auto-Save 367
Sets 455 Backups for Individual Files 370
Keyboard Command Sets 497 Backups for Specific File Types 370
Macro Languages and DLL Source Conversion to Supported File
Code 397, 491 Types 458
Macros, Macro Languages and delays when opening/closing 283
DLLs 401 File Manager 50
Supplemental Language Support File Open dialog functionality 50
497 Finding 36
Using your Own DLL 505 Formatting the Backup
Extensibility 401 Specification 371
Extension Global Backups and Auto-Save 367
File 171 loading 172
Override on Per-File Basis 46, 89 Loading and Validation 364
External documents/ programs- Open tab -- Project Window 55
accessing opening 172
Button Links 295 Opening as Read-only 376
ExtExpandTemplate 94 Organize by Directory on the
ExtSetTemplateMacro 97 Project Tab of the Project Window
168
F Organize by File Sort Mode 168
Organize by version control status
F1 key 168
Configuring MSVC HTML help 150 Override Extension 46, 89
Fast Find 256 Read-only Files for Specified File
Fax number 9 Types 375
feature 108 Read-only for Individual Files 375
File Reloading current file from disk 36
Alias Type 89 Saving Large Files 395
Grep 248 Sending via Email 36
Headers 91, 94, 101 Sharing 50
Icons in Project Tab of the Project Show File List on File Menu 43, 68
Window 213 Used by Perl for CodeWright 413
Menu 36 Working with Large Files 391
New 36 File-Validation 3
Override Extension 46 Fill Pattern 373

514 Index
Filter 290 Changing and Adding 501
Filters 37, 41
File|Filters dialog 37 G
project filters 168, 193
Find Fast 256 Get
Finding Files Files using Base Directories from
File Find tab 48 FTP Profile 379
first error 191 Files Using Directory Trees on FTP
Flag Initialization 455 Manager 379
Flags 476 Getting Started
Fmatch 469 API Macros 433
Fold text 268 Perl 404
Fonts 69 Grep
print fonts 70 Search and Replacement Edit Boxes
screen fonts 70 245
Format Selective Display 24
Controls 372
Source 39, 87, 320
Source Code on Language Dialog
H
321
forward to next document position 55 Handlers 418, 420
FTEE 205 Help
FTEE.EXE 203 accessing from other environments
FTP 28 148
FTP Manager Tab on the Output Compiled Microsoft HTML (.CHM)
Window 48, 378 Help Files 150
Get or Put from Directory Trees 379 configuring 148
Get or Put using Base Directories DLL 496
379 Index File Wizard 32
Login Dialog 377 InfoViewer 151
Profiles 377 Integrating with MSVC 5.0 (.IVT)
Put and Get 377 help 151
Toolbar 380 Menu 46
Full Screen MSVC 4.0 (.MVB) Help Files 151
Window menu 45 MSVC 6.0 HTML help integration
FUNCT.TPL 95 149
Function Visual Studio .NET HTML Help
Assign to Keystroke Combinations Integration 150
360 Hex
Tooltip with Parameters 124 Editing 145, 146
Function calls Mode 145
API Macros 447 Searching for hexadecimal values
Function Completion 267
at Command Prompt 64 Values 145
CodeSense 113 Hidden Characters
Function Headers 91, 94 making visible 70
Functions

Index 515
Hidden files Case Statements 111
Open tab-- Project Window 55 Prompted Slide In/Out 40
Hide Seek Indentation 110
text 268 Slide In 40
Highlight Slide Out 40
Current Parameter in Function Smart Indenting 110
Prototype Tooltip 124 indentation styles 111
Definition in Symbol’s Member List Insert
for Location 122 Braces 108
History Button Links 38
of document positions 55 Comment 129
of Responses 339 File 37
History of Document Positions 55 Function and File Headers 94, 101
Hotspots on the Status Line 355 functions 99
Hover Line Numbers 40
Tooltip with Function Prototype Link 295
124 Literal (Hex, Decimal, ASCII) 37
Tooltip with Symbol Definition 123 Insert/Edit User Dialog 421
HTML Installing Your DLL 505
Edit Mode by Default 133 Interleaved Differencing 298
Editing 130, 132 Internet Mail 8
Enable Editing in WYSIWYG Interpreters dialog 411
Window 133 Introduction 397, 491
language support 130 Iteration Qualifiers 263
popup menu 130 Iterative statements
Project Filter 140 API Macros 450
toolbar 130
turn on WYSIWYG 131 J
Using MSVC 6.0 Help Files 149
View 131 Java
WYSIWYG 132 Browse 285
WYSIWYG editor/viewer 131 CodeSense Support 113
jump to first error 191
I
K
Icons
Outline Window 281 Key Assignments 469, 478
Identifier Characters Key Command
First Field and Follow Field 76 Command Completion 64
Identifiers 76 Keyboard
if-else statement 448 Assign Keys 360
Importing names into Perl’s Command Sets 497
namespace 409 Keymap Function 455
Inclusive or Exclusive Selection 353 Keymaps 497
Incremental Searching 53, 257 Binding Keystrokes to Functions or
Indent 109 Macros 360
Alignment 111, 112

516 Index
 BRIEF Key Commands 352 Creating a ChromaCoding Lexer 75
Creating New Keymap Command Creating a Language Support DLL
Sets 455 89
CUA Key Commands 352 enable coloring 88
Customizing 351 Language DLLs 74, 88
Customizing Keybindings 359 loading 74
Specific Assignments 456 setting configurations 83
Specific Keymap Assignments 358 user-defined keywords 78
Visual Studio .NET 3, 352 Large Files 391
Keystroke Macros 38, 171 Changing Block Size 392
Editor 360 Changing the Number of Swap
Keystrokes Blocks 391
modifying 358 Disabling File Pre-loading 394
keywords File Rewrite Save Method 396
from file 86 Saving 395
restrict searches to 22, 253 Swap Blocks Allotting Memory to
KmapAssign 456 Swap Blocks 391
Turning off Backups 393
L Turning Off Scroll Bars 393
Left Justify 40
Language Lexers 85
coloring 73 COBOL 142
coloring embedded 85, 86 Default Settings 75
Creating a Language Support LibExport 409, 418, 500
DLL 89 LibFunctionExec 98, 409, 418
Defining API Macros 434 LibFunctionExistsWhere 403
DLL 74, 88 Libraries/ Add-Ons/DLLs
Features, Supporting Files 493 loading 43, 66
Indenting 493 Line
Tools|Customize Dialog 43 Numbering 40
Language Dialog 92 Saver Alignment 112
ChromaCoding 85 Selections 354
Comments Tab 87 Link
DLL radio button 86 insert 295
Format Tab 87 Insert Button Link 38
Lexer radio button 85 Preserve between UNIX Files 462
Options Tab 84 Link Libraries 503
Symbols Tab 87 Borland Link 504
Tabs/Indenting Tab 85 Microsoft Link 504
Templates Tab 85 Literal
language support 73, 497 Insert Hex, Decimal, or ASCII
Adding a New File Type 88 Literal 37
additional language support 74 Load
Alias or map non-supported and Validate Files 363
languages to supported ones 88 Load Macros Dialog
ChromaCoding Lexers 74, 85 AppBasic 427
COBOL 141 loaded for execution 421

Index 517
Loading and running scripts Making Changes and Additions 501
Perl 407 Mark Database 171
Login Dialog MarkBeginSel 411
FTP 377 Maximum Cache Size, CodeSense
look 333 Lookups 127
Members tab of Project Properties
M Dialog 60, 164
Memory
Macintosh Block Size 392
Changing EOL 84 Cache to Speed CodeSense
Save File as New Type 458 Lookups 127
Macro File 171 Pre-loading Files 394
Macro Languages Swap Blocks 391
API (C-like) Macros 432 Menu Accelerators 456
AppBasic 414 Menu items 341
Comparison of Supported adding 341
Languages 402 deleting 341
Perl 404 separator 341
Macros MenuAddKeyString 456
Binding Keystrokes to Functions or Menus
Macros 360 adding 340
Creating a Macro in AppBasic 418 Adding a Menu Item 343
Debugging in AppBasic 425 Adding External Operations 344
Defined 401 Build Menu 39
In templates 94 changing position 340
Keystroke Macro Editor 360 Changing the Functionality of a
Loading a Perl Macro 407 Menu Item 342
Recording a Keystroke Macro 359 Customizing 339
run from Button Links 296 Defining a Popup Menu 344
Running AppBasic Macros 424 deleting 340
Supporting Files 495 Document Menu 40
Tools Menu options 40 Edit Menu 37
Using Macros vs. DLL Extensions Editing Menu Items and Submenus
403 341
MACROS subdirectory 405 Editing Top-Level Menus 340
Mail file lists 341
Sending Email to Support 8 File Menu 36
Sending files 36 Project Menu 38
make utilities 174 Search Menu 38
Makefiles 502, 503 Sending Menu Commands to
adding files to CodeWright projects Synchronized Environments 241
165 Text Menu 39
Auto-Sync 167 Tools Menu 40
Parsers 166 Merging Files 317
reading into projects 167 Output 319
Synchronize with CodeWright Removing Changes 320
projects 167 Messaging 50

518 Index
Metacharacters 262, 263, 264, 265, 266
Microsoft Browser Database (.BSC) N
171
Microsoft Link 504 Name Completion 112, 121
Microsoft Visual Studio Structs, Classes, Unions, Enums,
Bi-directional synchronization 239 Namespaces, Packages, Interfaces
Drag and drop workspaces and 122
projects 358 Symbol Members 122
Synchronization 229 name confusion 403
Microsoft Visual Studio Workspace Navigate
Auto Synchronize 167 move between documents 55
drag and drop to create project Newline Character 93, 261
space 164 Next Error 191
opening as project space 164 Nmake 181
Parsing 166 No Command Shell 182
Reading 166 note links 296
Modal User Dialog in AppBasic 421 NotePad 351
Modules Properties dialog 418, 419
Mouse 354, 357
Copying Text 357
O
Creating Windows With 357
Moving Text 357 O'Reilly Press 414
Mouse Commands 353 Object and Proc Drop Down Lists 420
Block Selection 353, 354 Object Browser 417, 427
Column Marking 354 Objects Window 272, 285
Copy and Move 356 Filter/Legend dialog 290
Creating Windows 357 OLE Automation 417
Expand/Collapse Sections of Text One Document per Window 45
358 Online Help
File Loading 357 AppBasic 417
Go to Symbol Definition 121, 122 Perl 406
Hover for Function Prototype 124 Open projects and project spaces 164
Hover for Symbol Definition 123 Open tab
scrolling speed 353 Project Window 53
Selecting Lines 354 option 41
Selecting Words 355 options 333
Status Line Actions 355 Outline Symbols 281
Text Drag and Drop 356 Auto-Expand Collapse 282
Move 356 Icons 281
MsgNotify 419 sorting 282
MSVC workspaces and projects Outline Window 272, 279, 281
Drag and drop 358 output
MSVC++ File Synchronization 229 capturing 182, 187, 205, 206
Multiple Sources Search Dialog 244 Output Window 47, 191, 248, 272, 273,
Multi-source search 405, 407, 418
Fast Find 256 AppBasic Edit tab 48, 414
Browse tab 48

Index 519
 ClipView tab 48, 148 Perl.HLP 406
Difference tab 48 perl.org 414
File Find tab 48 PERL_IN_ 412
FTP Manager tab 48, 378 PERL5DB.PL 413
Output tab 48, 190, 206 PerlExec 407, 410
Perl tab 48, 405 PerlExecStr 407
Search tab 48 PerlExecSub 407
Shell tab 48 PerlRun 408
Symbols tab 48 PerlUnload 410
Override Pattern 373 Phone Number 9
PL extension 405
P Popup
Function Prototype 124
Parameters 476 Member List for Symbol 122
Function Prototype Tooltip 124 Name Completion or Go to
Parentheses Definition for Symbols 121
in Expressions (API Macros) 447 Symbol Definition 123
Locating 107 Popup Menu 344
Matching 107 AppBasic 417
paste 146 Perl 406
Pctags 278 Supporting Functions 351
Perl 397, 404 Version Control 215
books 414 Pre-loading Files 394
Options dialog 410 Preprocessor coloring
Popup menu 412 Ignore Remainder of Line 79
Tab on the Output Window 48 Preprocessor directives
Window 405 selective display 269
Perl Macro Language 404 PRG.DLL 498
Accessing CodeWright Functions Printing 152
409 color 153
Accessing Perl Functions 410 Configurations 152
already installed 405 date, timestamps, page number,
Creating and Editing Scripts 405 filename 154
Debug Mode 410 header and footer macros 154
Files used within CodeWright 413 Headers and Footers 154
help 406 line numbers 153
Importing Names into Perl's multi copy 153
Namespace 409 Paper Selection Override 153
Loading a Macro 407 Preview 153
Loading and Running Scripts 407 Side-by-Side Difference Window
Other Resources 414 155, 307
Perl Tab on Output Window 405 Wrap Long Lines 154
Pop-up Menu and Options 406 wrapping long lines 153
Special API Functions 411 Processing At Startup 468
Specifying the Intended Profiles
Subroutine 411 FTP 377
Unloading a Perl Macro 410 Project and Output Windows 47

520 Index
Project Files 198 Command lines 194
format 465 Command Options 182
loading 195 Compile commands 194
Options 472 Compiling 194
Project Menu 38 Compute Document Symbols 171
Project Properties Dialog 273 creating 161
Directories tab 170, 171 Custom tools 179
Errors tab 187 defined 157
Filter tab 192 Directories 193
Members tab 59, 163 Drag and drop 358
Tools tab 174, 179 drag and drop 164
Project Spaces 157, 158 filters 168, 192, 193, 195
creating 57, 58, 158 loading member files 195
Defined 158 opening or loading 164
Drag and Drop 164 Project Properties Dialog 60
Drag and drop 358 Properties for CodeSense Use 114
opening or loading 164 setting project configurations 60
selecting or changing 195 setting up project tools 181
Project Tools 174 Setup Checklist 193
Command Options 182 storing configuration settings with
Running in the Background 182 172
Project Window 49, 169, 272 synchronize with external
Bookmarks tab 50 makefiles/Workspaces 167
CodeFolio tab 50 use with version control 198
CodeMeeting tab 50 Working Directory 170, 171, 193
Detaching Tabs 332 Prompt for Arguments 182
Files tab 168 Prompts
Incremental Searching 53 System 42, 68
Objects tab 50, 272, 285 PTG file 273
Open tab 50, 53 Put
Outline tab 50 Files using Base Directories from
Project tab 49 FTP Profile 379
refresh 170, 214 Files using Directory Trees on FTP
StarTeam Tab (optional) 50, 223 Manager 379
version control 169 PWB 471
Version Control Icons 213
version control operations 169 Q
viewing version control status 170,
214 Quick Search 258, 276
Projects 157 quit
add files 59, 163 a long search 256
adding files from external make- Quoting 264, 265, 266
files/Workspaces 165
Associating Version Control
Projects with 211
R
Auto-Update Symbol Database 171,
285 Read User Makefile 166

Index 521
Read Visual Studio Workspace 166 Right Justify 40
README.TXT 8 Run mode 426
Read-Only Files 374 Running The Macro
By File 375 AppBasic 424
By Type 375
Set upon Opening 376 S
Rebuild 190, 191, 206
Recompiling a DLL 502 Sample EHTEST.CWB 425
Recording a Keystroke Macro 359 SAMPLE.DLL 499
Redirect Output 182 Save
Reference Groups and Replacement All Files automatically 182
Strings 265 Current File automatically 182
Registering CodeWright 31 Current Position 293
Regular Expressions 259, 263, 264, 265, Files with Auto-Save 367
266 Large Files 395
Alternation and Grouping 264 SC.DLL 498
Character Classes 262 Scrap Buffers 146, 147
ChromaCoding 13, 81, 82 Clipboard Tab 147
Escape Sequences 261 multiple 471
Escaping Characters in a Class 262 Viewer 148
Examples 266 scripting language
Iteration Qualifiers 263 coloring 86
Matching End Of Line 264 Scrollbars 69
metacharacters 260 Turning Off 393
Placing the Cursor 265 SDK for CodeWright 89, 491
positioning at Beginning/End of Search
Line 264 After Go To 277
Reference Groups and and Replace Dialog 244
Replacement Strings 265 ChromaCode Output 249
searching for more than one char- Color Limited 22, 253
acter 263 Editing Pattern List 249
special characters 259 for word at cursor 258
Reload 36 Ignore case 253
Replace Incremental 53, 257
Global replacement 252 Maximal match 253
Multiple Sources/files 245 Menu 38
Prompt options 252 Multiple Sources/ Files 245
Prompted replacement 252 Omit Binary File and Buffer
Single replacement 252 Matches 247
Replacement Options 251 on toolbar 259
resolve name ambiguity 403 Quick Search 258
resources Regular expression 253
CodeSense parser priority 118 Restrict to selection 255
Response File 185 Results in Output Window 245
Contents 185 Retain selection 254
Restore Current Position 293 Save Output between Sessions 249
Rich Text Editor 415, 429 Select matching string 254

522 Index
 stopping or quitting 256 Send Mail 36
Subdirectories 247 Set As CWD 246
Text Files Only 247 SetStringMacro 187
Whole word 253 Setting Project Defaults 160
Search List 247 Shell Command
creating/modifying 250 Tools Menu option 41
Drive and Directory Lists 250 Show Loaded Modules dialog 421
File Pattern 250 Side-by-Side Differencing 300
Include Directory 250 Foreground and Background
List Editing Buttons 250 Colors 302
Patterns List 250 Printing 155, 307
Search multi-source Smart Indenting 110
Documents only 246 Snippets
Edit Modified Files 248 Add to New Document 36
Files and folders 246 Adding a Snippet to CodeFolio tree
Output Window 248 directory 102
Project 246 Adding or Removing a CodeFolio
Search Options 56, 244, 259 Snippet Directory 104
Case Sensitivity 38 Code Snippet Properties Dialog 103
Dialog 38, 244, 356 CodeFolio Tab on Project Window
Prompt On Replacement 38 50, 99
Regular Expressions 38 Creating a Snippet from Clipboard
Searching or Document Selection 102
background Thread 248 Deleting or Renaming CodeFolio
Binary/ hexadecimal data 267 Snippet 103
CWFGREP 249 Directories 99
direction 251 Editing a CodeFolio Snippet 104
Displaying and controlling Output Executing a Snippet into your
248 Document 99
Exclude Start Position 255 Sorting
incremental 257 Files on the Project Tab of the
listbox control 258 Project Window 168
newlines 267 Source Code Revision Control
Project Files 197 Maintenance Dialog 210
Regular Expressions 259 Source Files
sets of files 247 Code Review from Different
spaces/tabs 266 Locations 50
Subdirectories 247 Spaces
Wrap at beginning/end 255 Replace with Tabs 110
SELECTION_LINE 411 setting 109
Selections Special Characters 93
by Word 355 Special Keybindings
Closed 354 Appbasic 415
Line 354 speed
Selective Display 39, 268, 269 auto validating 366
preprocessor directives 269 CodeSense parser priority 118
save between CW sessions 271 increasing 171

Index 523
Spell Check 323 StrSubStr 454
Tools Menu option 41 StrTrim 454
Spell Check Dialog Submenus 341
Advanced Tab 326 adding 341
Documents Tab 328 Swap Blocks
General Tab 323 Changing the Number Allotted 391
Word Format Tab 324 Symbol
split window 69 File 171
SrchSetFlags 455 Hover for Tooltip Definition 123
Standard Toolbar 55 Lookups (CodeSense) 124
repeat last search button 56 Name Completion from Popup Di-
search for word under cursor alog 121
button 56 Parser Icons 281
StarTeam Parsers (making/creating) 283
Filter Options Dialog 50 Scanning 280
Integration in CodeWright 50 Symbolic macros 186
Setting Up CodeWright Integration Symbols 272, 279
223 Auto-Expand Collapse 282
Tab on the Project Window 50, 223 Auto-Update Symbol Database 171,
State File 339, 473, 476, 482 285
Contents 465, 474 Compute Document Symbols 171
Location 474 Configuring 283
Statements and Statement Blocks Displayed in Symbols Window 280
API Macros 448 making/creating 283
Status Bar Navigating and Using 282
Customization Shortcut 41 Parser 279
Status Line Sorting 282
Actions 355 Window 272, 279
Progress Indicator 355 Synchronization
stderr 405 Borland C++ Builder File Setup
stdin 405 233
stdout 405 Delphi Setup 231
Stop a long search 256 Initial Setup in CodeWright 225
StrAscii 454 Microsoft Visual Studio 229
StrFileMatch 454 MSVC++ Setup 229
StrFormatDate 454 Sending Menu Commands to
String functions Synchronized Environments 241
API Macros 453 Supported Environments 225
StringApnd 453 TI Code Composer Setup 237
StringCompare 454 Visual Basic Setup 235
StringICompare 454 Wizard 32
StringLength 454 syntax coloring
StringNApnd 454 Adding a New File Type 88
StringNCompare 454 adding keywords from a file 78
StringNICompare 454 Comments 79
StrItoA 454 Creating a ChromaCoding Lexer 75
StrLtrim 454

524 Index
 Creating a Language Support non-language-specific 94
DLL 89 run from Button Links 295
enable coloring 88 special characters in 93
keywords 78 Special Chars In 93
Numbers 81 using macros in 94
operators 78 viewing 92
preprocessors 78 TERM.PM 413, 414
stop coloring certain items 78 Texas Instruments Code Composer
user-defined keywords 78 Bi-directional synchronization 239
SysEdit 351 synchronization 237
SysSetDefault 455 Text
SysSetFileLocking 466 Copy and Move 356
SysSetFlags 455 Drag and Drop 356
system files Expand/Collapse Sections of Text
directories 170 358
Link DB 171
T Menu 39
Restrict searches to 22, 253
Tab Completion for Functions and through 55
Constants 64 TI Code Composer Synchronization
Tabs 263, 264 237
controlling/customizing 85 Bi-directional synchronization 239
Replace with Spaces 110 Timestamps
setting 109 Open tab-- Project Window 55
showing tabs 70 Toolbar Search 56, 258, 356
Virtual Space Inside 84 Toolbars
Tags 4, 278, 483 Adding and Changing Buttons 336
Database 171, 278 Adding New Toolbars 336
Setup 278 Appbasic 417
Support 272, 277 Auto-hide 334
Tagfind Function 278 Binding a Function to a Button 337
TagNext 278 Buttons 171
TagPrev 278 Customization 44
Using Database 278 Customizing 336
TagsW32 272, 483 Default Toolbars 331
Technical Support 8 Docking and moving 335
Telephone Number 9 Enabling and Disabling 335
Template Expansion 85, 91, 493 forward and back button 55
Template macros FTP 380
list of 96 Options 331
Templates Standard toolbar 55
abbreviations that trigger 92 Tools
Add to New Document 36 Custom 44
creating and modifying 92 Tools Menu 40
example 94 Adding External Program/
ExtAssignTemplate 93 Operation Links 344
for language constructs 92 API Command 63, 398

Index 525
Tooltip Converting Individual Files 458
Function Parameters 124 Utilities
Hover for Symbol Definition 123 Supporting Files 494
Transformation Tools Menu options 41
Fill Pattern 373
Override Pattern 373 V
TransformFilename 454
Tree Control Variables
Incremental Searching 53 API Macros 435
Tree Differencing 309 VCS tool 180
Output Window 311 VDOS 182
Window 311 capturing output 206
Troubleshooting Version Control 169, 174, 209
CodeSense Lookups 128 Adding CodeWright Project Files to
TYPEMAP 413 an SCC Provider Project 213
Adding Version Control Files to a
U CodeWright Project 212
Associating Version Control
Undo 37, 55 Projects with CodeWright Projects
Unicode 211
Auto-detect 42, 68, 365 Configuring SCC Provider Support
CodeSense translation 124 222
Converting Individual Files 458 Current Project Tree List 214
Unindented Alignment 112 Customizing Version Control Com-
UNIX mands 219
Changing EOL 84, 460 File Icons 213
Compiling from CodeWright 461 Integration Methods 217
Enabling Auto-Sense File Type Location of the SCC Provider DLLs
EOL 458 223
File Conversion 458 Maintenance Dialog 210
File Securities 461 Making Your Own Popup Menu
File Transfer using FTP 377 216
Filename Case 461 Menu 209
Preserve Links between UNIX Files Modifying the Standard Popup
462 Menu 215
Recommendations for Running Project Tab of the Project Window
CodeWright with UNIX 457 214
Update Configuration Files checkbox Sorting on the Project Tab of the
173 Project Window 168
User-defined commands Source Code Control Provider 222
Open tab--Project Window 55 StarTeam Integration in Code-
user-defined keywords 78 Wright 223
UserDialog 417 Toolbar 214
Editor 417, 421 Tools Menu option 41
Using the Tags Database 278 User-defined Popup Menu 215
UTF-8 Using Command Line Version
Auto-detect 42, 68, 365 Control Provider 218

526 Index
 Using Multiple Configuration/ Whitespace
Project Files 216 Ignore during Differencing 299
Utilities 174 Wild Cards
vi command set 352 File Filters 37
View Themes Wildcard Patterns 37
Defaults 71 Win32 systems 414
Synchronize text background 70 Window Menu 44
View Themes Dialog 70 Windows
Colors tab 70 Attributes 69
Font tab 70 Creating with a Mouse 357
General tab 69 Difference between windows and
Visibles tab 70 documents 44
Virtual Space Docking and Moving 335
After End of File 84 move forward and back 55
After EOLs 84 One Document Per window 42, 68
Inside Tabs 84 split into multiple panes 69
visibles Windows Explorer 357
making visible 70 Windows XP
Visual Basic Synchronization 235 Enable Visual Styles 35
Visual Studio Wizards
Bi-directional synchronization 239 configuration 32
Synchronization 229 Word
Visual Studio .NET Completion 113
HTML Help Integration 150 Selections 355
Keymap 3, 352 Wrap 40
Visual Studio Workspaces Working Directory 170, 171, 464, 481
creating CodeWright projects from Workspaces 157, 158
165 Closing Windows 197
drag and drop to create project creating 196
space 164, 358 defined 158
open or load to create project space Deleting Buffers 197
164 loading 197
Visual Styles saving 196
Enable for Windows XP and Code- saving automatically 197
Wright 35 updating current 197
WYSIWYG HTML
W Editing 131
turn on 131
Web browser interface
turn on 131 X
Web Page 8
Editing 132 XML
turn on editing 131 Browser View 138
turn on viewing 131 Format Source 140
Viewing 131 Project Filter 140
WYSIWYG editor 131 Source Code View 137
Where is it Defined? 403 Split Window View 134

Index 527
 Split Window Viewer module 135
Template Expansion 139
XSL Transformation View 138
XP
Enable Visual Styles for Windows
and CodeWright 35
XSL
Template Expansion 139
Transformation View 138
XSUBPP.PL 413

528 Index