Contents
Visual Workbench

How to Use Visual Workbench

   Creating Applications with Wizards

   Using the Editor

   Managing Projects

   Compiling Files or Building Projects

   Debugging Your Application

   Examining Symbols with the Browser

   Profiling Your Application

   Managing Your Environment with Workspaces

   Changing Preferences

   Modifying the Tools Menu

Other Help Topics

   Using Search Plus

   Toolbar and Keyboard Shortcuts

   Help in Brief


Copyright Notice
Copyright Notice for Visual Workbench Help

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without express written permission of Microsoft Corporation.

© 1993 Microsoft Corporation. All rights reserved.

Microsoft is a registered trademark and Windows and Windows NT are trademarks of Microsoft Corporation.


Editor Topics

How Do I?	Brief	Click
Learn about the editor	What you should know about the editor
See a list of shortcut keys	List of buttons and shortcut keys for the editor
Create a file	Creating a new source file
Open a file	Opening any ASCII, project, or resource file; setting open options
Save a file or files	Saving files, changing save options, and saving a file under a new name.
Print	Printing selected text or complete files
Navigate through files	Moving to a specific line in a source file or setting and using bookmarks
Cut and paste	Cutting, copying, deleting and pasting text
Find or replace	Finding or replacing search strings; using regular expressions to find or replace.
Undo or redo editing actions	Changing the size of the undo buffer that controls the number of undo and redo actions you can perform
Set tabs or fonts	Changing tabs or fonts
Change syntax coloring	Changing the color of programming elements, such as comments for quick identification and debugging clues, in source files.
Manage windows	Creating multiple views of windows, making windows read only, or closing windows
Use your own editor	Using the Add Tool command to add your editor to the Tools menu.


Visual Workbench Editor Basics

The Visual Workbench editor is an integrated text editor with powerful programming options:

Advanced find and replace capabilities. You can search for literal text or use regular expressions to find words or characters in the source window. You can also use the Find in Files command to search across files. The Find Matching Brace command ( CTRL+M ) locates a matching brace in a block or determines if a brace is lacking to enclose a block.

Syntax highlighting. You can highlight language keywords, identifiers, comments, and strings in different colors. This feature is useful when learning a language or when viewing lengthy and complex source files. For example, if you are editing a file with a .CPP extension, all C++ keywords are highlighted.

Tab stops in a source file. You can set the number of spaces a tab consists of, then save them as either tabs or spaces when you save the file.

Toolbar shortcuts. You can open project files, save files, and begin text searches from the toolbar.

Context-sensitivity in source files. Pressing F1 while any language element in a source file is highlighted opens a help topic on that element. You can get help on language keywords, run-time functions, class library member functions, and Windows 3.1 functions, data types, structures, and messages.

Option-specific help for dialog boxes. The Help button in a dialog opens a help topic that covers the options for the dialog box and offers tips and troubleshooting information.

Undo and redo features. You can allocate as much memory as you want to support extended undo and redo actions.

Multiple windows. You can open multiple files or multiple views of the same file. Each source window can retain its own fonts, sizing, and other window attributes.

Bookmarks. You can set a "bookmark" at a file location, then move to that location with a keystroke or menu command.

Ease-of-use features, such as listing recently opened files from the button of the File menu, parsing text around the insertion point as the initial search string in a Find operation, and shortcuts from the toolbar or keyboard.

The maximum number of characters in a line is 253; the maximum number of lines in a file is 32,000.


Editor Shortcuts

Toolbar Shortcuts

To:	Click on this Tool:
Begin a search
Find next occurrence of search string
Open a source file
Save a source file
Open a project file
Keyboard Shortcuts

Action	To:	Press
Move insertion point	Move one character left	LEFT ARROW
	Move one character right	RIGHT ARROW
	Move one word left	CTRL+LEFT ARROW
	Move one word right	CTRL+RIGHT ARROW
	Move one line up	UP ARROW
	Move one line down	DOWN ARROW
	Move to the first indentation of current line	HOME
	Move to the beginning of current line	HOME, HOME
	Move to the first indentation of next line	CTRL+ENTER
	Move to the end of line	END
	Move to the beginning of the file	CTRL+HOME
	Move to the end of file	CTRL+END
Delete, insert, copy	Delete one character to the left	BKSP
	Delete one word to the left	CTRL+BKSP
	Delete one character to the right	DEL
	Delete to the end of the word	CTRL+T
	Delete selected text and copy to Clipboard	CTRL+X, SHIFT+DEL
	Turn keyboard insert mode on or off	INS
	Copy selected text to Clipboard, keeping it	CTRL+C, CTRL+INS
	Insert contents of Clipboard	CTRL+V, SHIFT+INS
	Copy current line to Clipboard, deleting it	CTRL+Y
	Undo the last edit	CTRL+Z, ALT+BACKSPACE
	Redo the last edit	CTRL+A
	Insert carriage return but don't move the cursor	CTRL+SHIFT+N
Tabs	Toggle tabs on and off (display in a file)	CTRL+ALT+T
	With multiple lines selected, move lines one tab stop to the right	TAB
	With multiple lines selected, move lines one tab stop to the left	SHIFT+TAB
Scroll text	Scroll up one line at a time	CTRL+UP ARROW
	Scroll down one line at a time	CTRL+DOWN ARROW
	Scroll right one screen	CTRL+PAGE UP
	Scroll left one screen	CTRL+PAGE DOWN
Select text	Select character to the left	SHIFT+LEFT ARROW
	Select character to the right	SHIFT+RIGHT ARROW
	Select one word to the left	SHIFT+CTRL+LEFT ARROW
	Select one word to the right	SHIFT+CTRL+RIGHT ARROW
	Select current line if insertion point is home	SHIFT+DOWN ARROW
	Select line above if insertion point is home	SHIFT+UP ARROW
	Select to end of the line	SHIFT+END
	Select to beginning of line	SHIFT+HOME
	Select one screen up	SHIFT+PGUP
	Select one screen down	SHIFT+PGDN
	Select block	SHIFT+CTRL+M
	Select to beginning of file	SHIFT+CTRL+HOME
	Select to end of file	SHIFT+CTRL+END
Change case	Change selection to uppercase	CTRL+U
	Change selection to lowercase	CTRL+u
Find	Open the Find dialog box	ALT+F3
	Select text string in Find box	CTRL+F or ALT+A
	Find the selected text	CTRL+F3
	Find next, forward	F3
	Find next, backward	SHIFT+F3
	Next find in files tag	F4
	Previous find in files tag	SHIFT+F4
	Find the next error	F4
	Find the previous error	SHIFT+F4
	Find matching brace	CTRL+M
Bookmarks	Find next bookmark	F2
	Find previous bookmark	SHIFT+F2
	Toggle bookmark	CTRL+F2
Files	Create a new source file	CTRL+N
	Open a source file	CTRL+O
	Save a source file	CRTL+S
Window management	Switch to next document window	CTRL+F6
	Switch to previous document window	SHIFT+CTRL+F6
	Switch to next window (includes all windows)	F6
	Switch to previous window (includes all windows)	SHIFT+F6
	Switch to previously active window	CTRL+TAB
	Close active window	CTRL+F4


Creating and Opening Files
Creating a File

The New command creates a new source file. Creating a source file does not affect other source files you may have open.

 To create a new source file:

1.	From the File menu, choose New. A new source window is opened.

2.	Type your source code in the new window.

3.	From the File menu, choose Save.

The Save As dialog box appears.

Toolbar shortcut:

Shortcut: CTRL+S

4.	In the Directories box, double-click a directory where you want to store the source file (or down a directories path to the appropriate directory.)

5.	Type a filename in the File Name box, then choose OK. The default extension given to a file is the last extension used when you saved a file. You can type in another extension or select one from the List Files of Type box.

New files are labeled UNTITLED.n until they are saved. The n is a sequential number.

The maximum number of characters in a line is 253; the maximum number of lines in a file is 32,000.

Before you can save or close a window it must be active. To make a window active, either switch to the window (by clicking anywhere in it) or choose the window name or number from the Window menu.


Opening Files
  Opening a Source File

  Opening a Project File

  Opening a Resource File


  Opening a Source File

When you open a source file, its name is added to the Window menu. You cannot use the File menu's Open command to open another copy of an open source file.

 To open a file:

1.	From the File menu, choose Open.

The Open File dialog box appears.

Shortcut: CTRL+O

Toolbar shortcut:

2.	Select the drive and directory where the file is stored. The default is the current drive and directory.

3.	Set the types of files to display in the List Files of Type box. Files with the chosen extension are displayed in the File Name box.

This box serves as a filter to display all files with a given extension. For example, C++ Source (*.CPP) displays all files with the .CPP extension. The drop-down box lists commonly-used file extensions. The default is a combination of .C, .CPP, and .CXX.

4.	 In the File Name box, click a filename, then choose OK.

Shortcut:  Double-clicking a filename

The names of the four most recently opened files are displayed at the end of the File menu. To open one of these files, choose its name from the menu.

Tip  You can also open a file by using the File Manager to display the file icon, then dragging and dropping the file icon into Visual Workbench.

 To set open options:

1.	From the Options menu, choose Editor.

The Editor dialog box appears.

2.	Check Open New Source Window to cause a new source window to appear whenever any new source file is opened in the editor.

Or uncheck it to cause any new source file to appear in the active source window.  If no source window is active a new source window is always opened.

3.	Check Open .RC Using App Studio to cause Visual Workbench to invoke App Studio on any resource file you choose using the Open dialog box or the Project Files toolbar button.

Or uncheck this option to open resource files as ordinary text files in Visual Workbench.

4.	Choose OK.

Opening a File as Read Only

To open a file as read only, select the Read Only check box in the Open File dialog box. To make a file read only after opening it, choose the Read Only command on the Edit menu. If you open a read only disk file, the Read Only command is automatically checked. To edit a version of the file, clear the Read Only command, make your edits, and then save the file under a different name (Save As command).

Opening a New Window with the Same Contents as the Active Window

You can use the Duplicate command in the Window menu to open a second view of a source file. If more than one copy of the file appears, the title bar will display filename:n, where n is a unique window number.

Using File Filters

Instead of setting a file type in the Files of Type box, you can use wildcard patterns in the File Name box to display file types. For example, entering "*.INC" displays files only with the .INC extension. The new wildcard pattern is retained in a session until changed. You can also use any combination of wildcard patterns, delimited by semicolons. For example, entering "*.INC; *.H; *.CPP" displays all files with these extensions.


  Opening a Project File

After opening a project, you can easily open any project file with the Project Files button on the toolbar.

Project Files button:

 To open any source file in the current project:

1.	Click the Project Files button on the toolbar. A list box with all files in the current project drops down.

Shortcut:  CTRL+P

2.	Click a file from the list.

Note  You can also open a project file by choosing the Open command on the File menu.


Opening a Resource File
  Opening Resource Files

Resource files (files with an extension of .RC) are source files that define resources such as menus and dialog-box controls and are compiled by the resource compiler as part of building an application for Windows. Although these are ASCII-based source files, they are also the primary information files used by App Studio.

When you open a resource file from either the Open File dialog box or the Project Files button on the toolbar, Visual Workbench does one of two things, based on the state of the Open .RC File Using App Studio check box in the Editor dialog box (accessed from the Options menu):

If this check box is disabled (the default), opening a resource file is like opening any text file as a source window in Visual Workbench.

If this check box is enabled, opening a resource file from Visual Workbench automatically invokes App Studio on that resource file.

When the option is enabled, Visual Workbench invokes App Studio and passes it the filename you selected. App Studio can open any resource file that the resource compiler can compile without errors, so you can use it with any existing resource files simply by opening the resource file from Visual Workbench or from App Studio.

Note  You can use the Windows File Manager to display a list of resource files and then drag and drop any resource file icon into Visual Workbench. The state of the Open .RC File Using App Studio check box in the Editor dialog box determines whether Visual Workbench or App Studio opens the file.

App Studio is installed on the Tools menu with the $RC macro argument, which automatically opens the first resource file in the project list. Since you can open App Studio with your resource file from the Tools menu, the default action in the Open File dialog box (or Project Files toolbar button) is not to invoke App Studio on resource files. However, when you learn to use App Studio, you may decide you no longer need to hand-edit resource files and want the advantage of opening App Studio directly on files you select.

  For more information on Using Macro Arguments

 To open App Studio on a resource file:

1.	From the Options menu, choose Editor.

2.	Select the Open .RC Files Using App Studio check box so that it is checked.

3.	Choose OK to close the dialog box.

4.	Open the resource file as you would a source or project file.


Using Argument Macros
More Information on Using Argument Macros

You can specify arguments for any program added to the Tools menu by entering the arguments in the Arguments box. To help you integrate your tools with the current status of the Visual Workbench environment, Visual Workbench provides a set of 11 argument macros.

Macro Name	Expands to a String Containing:
$File	The complete filename of the current source (defined as drive+path+filename). Blank if non-source window is active.
$FileName	The filename or the current source (defined as filename). Blank if non-source window is active.
$FileDir	The directory of the current source (defined as drive+path). Blank if non-source window is active.
$Proj	The current project base name (defined as filename). Blank if no project is currently open.
$ProjDir	The directory of the current project (defined as drive+path). Blank if no project is currently open.
$Cmdline	The command-line arguments passed to the application (obtained from the debug dialog in the Options menu).
$Line	The current cursor line position within the active window.
$Col	The current cursor column position within the active window.
$Dir	The current working directory (defined as drive+path).
$Target	The current project target name (defined as drive+path+filename).
$RC	A resource file (*.RC). For Visual Workbench projects, this is the first resource file in the project list. For external projects, it is $Target.Rc. If there is no resource file or there is no active project, $Rc is blank.
Macro recognition is case-insensitive. All path macros end in a backslash (\).

To use a macro as an argument, type the macro name in the Arguments box. For macros that expand to a directory, you can type the macro name in the Initial Directory box.

For example, the following procedure demonstrates how to add the $File argument macro to Notepad (NOTEPAD.EXE) as a tool.

  To add the $File macro, then run it:

1.	From the Options menu, choose Tools.

2.	Under Menu Contents, select the command you want to edit [image] in this case, Notepad.

3.	In the Arguments box, type $File.

4.	Choose OK to close the Tools dialog box.

5.	Open any source file or make an open source file active by clicking in it.

6.	From the Tools menu, choose Notepad.

The Windows Notepad editor opens with the active Visual Workbench source file as its text file.


  Saving Files

  Saving a File under a New Name


  Saving Files

Each source window associated with a source file can retain its own fonts, sizing, and other window attributes. Whe you make changes to a source window, the Save button on the toolbar becomes available (not dimmed) to indicate that the information in the source window and source file differs.

 To save a file:

1.	Switch to the source window.

2.	From the File menu, choose Save.

Shortcut: CTRL+S

Toolbar shortcut:

2.	If your file is unnamed, the environment displays the Save As dialog box. In the File Name box, type the filename.

3.	In the Drives and Directories boxes, select a drive and directory.

4.	Choose OK.

If the file has already been named, the Save command saves any changes without displaying the Save As dialog box.

 To save all open files, choose Save All from the File menu.

Setting Save Preferences

You can set save preferences  such as whether to be prompted before saving a file  in the Editor dialog box. As a default, Visual Workbench saves all changed files before you build an application.

 To change the default:

1.	From the Options menu, choose the Editor command.

The Editor dialog box appears.

2.	To change the default, clear the Save Before Running Tools check box, then choose OK.

3.	To be prompted to save files before a build, select Prompt Before Saving Files, then choose OK.

You can set other save preferences in the Editor dialog box.


  Saving a File under a New Name

You can also rename an existing file. This procedure is useful for maintaining revised copies of a file while keeping the original unchanged.

 To save a new file or rename an existing file:

1.	Make the file active by clicking the source window.

2.	From the File menu, choose Save As.

The Save As dialog box appears.

3.	Type a filename and extension in the File Name box.

4.	Choose the drive and the directory where you want to save the file.

5.	If you want to keep the existing window open and continue to display the current file under its current name, select the Open New Window For This File check box. This opens a new window for the new file.

When the check box is cleared, the new file is displayed in the current window.

6.	Choose OK.


Printing

You can

Print highlighted text or the contents of a source window.

Print a complete file

Customize your print job

Print help topics

 To print highlighted text

1.	Select the text you want to print.

2.	From the File menu, choose Print.

The Print dialog box appears.

Shortcut: SHIFT+CTRL+F12

3	.Choose OK.

Text is printed in the default font for the printer.

The Print command also prints the contents of an active window, such as the Output window. An active window is the window with the current focus.

 To print the contents of an active window:

1.	Choose All from the Print Range box.

2.	Choose OK.

 To print a complete file

1.	From the File menu, choose Print.

The Print dialog box appears.

Shortcut: SHIFT+CTRL+F12

2.	Select All from the Print Range box.

3.	Choose OK.

To customize your print jobs, use the Page Setup command from the File menu. You can:

Add headers

Add footers

Adjust margins

 To customize:

From the File menu, choose Page Setup.

a.	Type the header or footer text, codes, or both, then choose OK.

b.	Under Margins, enter a measurement.

Tip  Choose the Help button in the Page Setup dialog for information on header and footer codes for special formatting.

To print the contents of the current help topic, choose Print Topic from the File menu in the Help window.

Note  Only one help topic can be printed at a time.


Moving Through a File
  Moving to a Specific Line in a File

  Using Bookmarks to Move in a File

  Moving to a Matching Brace

  Table of Shortcut Keys for Moving in a File


  Moving to a Specific Line in a File

You can move to any line number in a source file.

 To move to a line:

1.	From the View menu, choose Line.

The Line dialog box appears.

2.	In the Number box, type a line number.

3.	Choose OK.

If you type a line number greater than the last line in your source file, the editor moves to the end of the file.


  Using Bookmarks to Move in a File

You can set a "bookmark" to mark frequently accessed lines in your source file. Once a bookmark has been set at a line, you can use menu or keyboard commands to move to the bookmark. You can clear a bookmark when you no longer need it.

 To set a bookmark:

1.	Move the insertion point to the line where you want to set a bookmark.

2.	From the View menu, choose Toggle Bookmark. The line is highlighted.

Shortcut: CTRL+F2

 To move to the next bookmark after the insertion point, choose Next Bookmark from the View menu.

Shortcut: F2

 To move to the previous bookmark before the insertion point, choose Previous Bookmark from the View menu.

Shortcut: SHIFT+F2

 To clear a bookmark:

1.	Move the insertion point to the bookmark.

2.	From the View menu, choose Toggle Bookmark.

Shortcut: CTRL+F2

To remove all bookmarks in a source file, choose Clear All Bookmarks from the View menu.


  Moving to a Matching Brace

You can move to the matching brace in a block or determine if you have a matching brace to enclose a block with the Find Matching Brace command.

 To move to a matching brace:

1.	Place the insertion point immediately in front of a brace.

2.	From the Edit menu, choose Find Matching Brace.

The insertion point moves forward or backward to the matching brace. Choosing the command again returns the insertion point. If a matching brace cannot be found, the editor beeps. This also works for parentheses and brackets.

Shortcut:	CTRL+ M


  Table of Shortcut Keys for Moving in a File

The editor includes a number of special keystrokes for editing and moving around in a source file. These are in addition to the familiar ARROW keys, the SPACEBAR, and the ENTER key:

To move to:	Press:
Word to left	CTRL+LEFT
Word to right	CTRL+RIGHT
First indentation of current line	HOME
Beginning of current line	HOME, HOME
First indentation of next line	CTRL+ENTER
Beginning of file	CTRL+HOME
End of file	CTRL+END


Cutting, Copying, Deleting and Pasting Text
Cutting, Copying, Pasting, and Deleting Text

The Cut command "deletes" selected text from the active window and copies it to the Clipboard. The Copy command "copies" selected text from the active window to the Clipboard. With each command, you can then paste the text to another location, file, or application. The Delete command deletes text without copying it to the clipboard. As with all editing actions however, you can "undo" a delete with the Undo command on the Edit menu.

 To cut or copy, then paste text:

1.	Select the text you want to paste.

2.	From the Edit menu, choose the Cut or Copy command.

Command	Shortcut
Cut	CTRL+X or SHIFT+DEL
Copy	CTRL+C or CTRL+INS
Paste	CTRL+V or SHIFT+INS
Note  To cut the current line, press CTRL+Y.

3.	Place the insertion point in any source window where you want to insert the text.

4.	From the Edit menu, choose the Paste command.

The Delete command in the Edit menu deletes selected text. The deleted text is not placed in the Clipboard and cannot be pasted.

Shortcut: DEL

Tip  To undo the last edit, press CTRL+Z or ALT+BACKSPACE. To redo the last edit, press CTRL+A.


Finding and Replacing Text
  Finding Text in a Single File

  Finding Text in Multiple Files

  Finding Matching Braces

  Replacing Text

  Using Regular Expressions


  Finding Text in a Single File

The Find command searches the active window for a text string. You can:

Find a whole word match. This "find" matches all occurrences of a text string not preceded or followed by an alphanumeric character or the underscore (_).

Find a case-sensitive match. This "find" searches for text that matches the capitalization of the text string.

Use a general-pattern search using regular expressions. This "find" uses special character sequences [image] regular expressions [image] to search for text.

 To find a text string:

1.	Position the insertion point where you want to start your search.

The editor uses the location of the insertion point to select a default search string.

2.	From the Edit menu, choose Find.

The Find Dialog appears.

Shortcut: ALT+F3.

3.	Type the search text or a regular expression in the Find What box.

4.	Select any of the Find options. If you choose Find Next, an abbreviated version of the Find dialog box is displayed. This dialog box allows you to choose selectively the Find Next or Set Bookmarks on All command.

Note  You can choose to use a modeless dialog box for Find by selecting the Modeless Dialog for Searches check box in the Editor dialog box under the Editor command on the Options menu. The modeless dialog box remains on the display, so you can continue with searches, but allows you to modify the files without dismissing it.

Find Next shortcut, forward: F3

Find Next shortcut, backward: SHIFT+F3

The Set Bookmarks on All command sets a bookmark at each occurence of the text string or regular expression. You can then choose the Next Bookmark command on the View menu to move to each bookmark in your file.

The drop-down list box connected to the Find What text box records the last 16 text items you searched for. Select the drop-down arrow to the right of the text box or press ALT+DOWN ARROW to open the list. To begin a search, select a text item from the list, then choose Find Next or Set Bookmarks on All.

 To find a text string with the Find button:

The Find button also features a drop-down list containing the previous 16 search strings. The list is maintained throughout your editing session. When you begin a search from the toolbar, the search is confined to the active window.

Find button:

Find Next button:

The shortcut CTRL+F moves the insertion point to the Find box.

 To begin a find with the Find button, either:

Enter a search string in list box, then press ENTER, or click the Find Next button

Select a text string in the list box, then press ENTER

Select a text string in a source file, then press CTRL+F3.

Note  You can use regular expressions with a find from the toolbar, if you have previously checked the Regular Expression check box in the Find dialog box.

Keyboard shortcuts for the Find box:

Action	Shortcut
Enter text in source file to Find text box	CTRL+F3
Select text string in Find text box	CTRL+F or ALT+A
Search forward	RETURN or F3
Search backward	SHIFT+RETURN or SHIFT+F3
Help on selected keyword	F1
Go to definition	F11
Go to reference	SHIFT+F11


  Finding Text in Multiple Files

The Find in Files command on the Edit menu searches multiple text files for a text string. You can:

Find a whole word match. This "find" matches all occurrences of a text string not preceded or followed by an alphanumeric character or the underscore (_).

Find a case-sensitive match. This "find" searches for text that matches the capitalization of the text string.

Use a general-pattern search using regular expressions. This "find" uses special character sequences [image] regular expressions [image] to search for text.

 To find a text string in multiple source files:

1	.From the Edit menu, select the Find in Files command.

The Find in Files dialog box appears.

2.	Select the files that you want to search. You can use the controls in the dialog box to change drives and directories, and you can select files from multiple drives and directories.

To add a file to the Selected Files list to be searched, you can select it in the File Name list and click Add. Alternatively, you can double-click it.

To remove a file from the Selected Files list, you can select it and then click Remove. Alternatively, you can double-click it. The Remove All button removes all the file names from the Selected Files list.

Visual Workbench retains the contents of the Selected Files list between uses of the Find in Files command in any single session.

3.	Type the search text or a regular expression in the Find What box.

Visual Workbench retains up to 16 previous search strings in any single session. Select the drop-down arrow to the right of the text box or press ALT+DOWN ARROW to open the list. You can select any entry from the list by double-clicking it.

4.	If necessary, select one or more options in the Options group. If you typed a regular expression in the Find What text box, you must select Regular expression.

5.	Click Find to begin the search.

The Find in Files command displays the number of matches in the status line at the bottom of the Visual Workbench window, and it displays the occurrences found in the Output window. Each occurrence has the fully qualified file name, followed by the line number of the occurrence and then the lind containing the match.

6.	To open a file containing a match, double-click the entry in the Output window, or move the insertion point to the entry and press Enter.

Keyboard shortcuts:

Action	Shortcut
Next find in files tag	F4
Previous find in files tag	SHIFT+F4
An editor window containing the file opens, and the line containing the selected match is highlighted.

The drop-down list box connected to the Find What text box records the last 16 text items you searched for.

  For more information on Find in Files


More Information on Find in Files

When you perform a multiple-file search, the Output window displays the list of file locations where the text string was located. You can then jump to other occurrences of the text string by using the Next Find in Files Tag (F4) or Previous Find in Files Tag (SHIFT+F4) commands on the View menu or by double-clicking on the specific entries in the Output window.

When you jump to a found string location specified in the Output window, the corresponding source file is loaded, if it is not already open in the editor, and the insertion point is placed at the correct location in the file. A source file opened as a result of a jump to a found string location will either open in a new window, or open in the currently active window, depending on the status of the Open New Source Window check box in the Editor dialog box (accessed from the Options menu).

The Find in Files Output window is a virtual window that is maintained even when not displayed. You can display the output from the last multiple-file search done during the current Visual Workbench session by choosing the Output command in the View menu and choosing Find in Files from the popup menu.


  Finding Matching Braces

You can find matching braces in a block or determine if you have matching braces to enclose a block with the Find Matching Brace command.

 To find a matching brace:

1.	Place the insertion point immediately in front of a brace.

2.	From the Edit menu, choose Find Matching Brace.

The insertion point moves forward or backward to the matching brace. Choosing the command again returns the insertion point. If a matching brace cannot be found, the editor beeps. This also works for parentheses and brackets.

Shortcut:	CTRL+M


  Replacing Text

The Replace command searches the active window for a text string and replaces it with another text string. You can specify:

Find a whole word match. This "find" matches all occurrences of a text string not preceded or followed by an alphanumeric character or the underscore (_).

Find a case-sensitive match. This "find" searches for text that matches the capitalization of the text string.

Use a general-pattern search using regular expressions. This "find" uses special character sequences [image] regular expressions [image] to search for text.

 To replace text:

1.	Position the insertion point where you want to start your search.

The editor uses the location of the insertion point to select a default search string.

2.	From the Edit menu, choose Replace.

The Replace dialog box appears.

3.	Type the search text or a regular expression in the Replace With box, if you have previously checked the Regular Expression check box in the Replace dialog box.

4.	Select any of the Replace options. If you choose Find Next, an abbreviated version of the Replace dialog box is displayed. This dialog box allows you to choose selectively the Find Next, Replace, or Replace All command.

The drop-down list box connected to the Find What text box on the toolbar records the last 16 text items you searched for. Click the drop-down arrow to the right of the text box or press ALT+DOWN to open the list. To begin replacing text, select a text item from the list, then choose Find Next or Replace All.


  Using Regular Expressions

A regular expression is a search string that uses special characters to match a text pattern in a file.

 To use a regular expression, type a regular expression in the Find What text box.

 More on regular expressions

Note  You can use regular expressions with a search in a single source file with the Find button on the toolbar if you have previously checked the Regular Expression in the Find or Replace dialog boxes.


period
Period (.)

Matches any single character.


Caret
Caret (^)

Matches the beginning of a line.


Dollar Sign
Dollar Sign ($)

Matches the end of a line.


Asterisk
Asterisk (*)

Matches zero or more occurrences of the regular expression(s) or character(s) preceding the asterisk.


Plus sign
Plus sign (+)

Matches one or more occurrences of the regular expression(s) or character(s) preceding the plus sign.


brackets
Brackets ([...])

Matches sets of the characters specified within the brackets.


braces
Braces (\{...\})

Matches any sequence of characters between the escaped braces. For instance, \{ju\}+fruit finds jufruit, jujufruit, ..., jujujujufruit, and so on. Note that it will not find jfruit, ufruit or ujfruit because the sequence ju is not in any of those strings.


Backslash
Backslash (\)

Interprets the next character as a literal character [image] with no special meaning.


Undoing and Redoing Editing Actions

The Undo command on the Edit menu allows you to "undo" previous editing actions. The number of editing actions you can undo is determined by the size of the Undo buffer. The default size for the buffer is 4K (kilobytes). You can set the buffer from 0 to 64K.

 To set the size of the buffer:

1.	From the Options menu, choose Editor.

2.	In the Undo Buffer Size box, enter a number from 0 to 64. The number represents the size in kilobytes for the buffer.

3.	Choose OK.

If the buffer is set to 10K and you have deleted 2K of text four times in an editing session, you can undo all four editing actions. Undoing Replace All actions is determined by the buffer size.

 To undo an editing action

From the Edit menu, choose Undo.

Shortcut: ALT+BKSP or CTRL+Z

The Redo command "undoes" the action of an Undo command. Redo is unavailable unless an Undo command has been chosen.

 To redo an undo action:

From the Edit menu, choose Redo.

Shortcut: CTRL+A or CTRL+BKSP

Note  The number of Redo commands is limited by the size of the buffer.


Tabs and Fonts
  Setting Tabs

  Setting the Font and Font Size


  Setting Tabs

The editor supports tab stops in a source file. You can set the number of spaces a tab consists of, then either save them as tabs or spaces when you save the file.You can also toggle the display of tab symbols in a source file.

 To change tab settings:

1.	From the Options menu, choose Editor .

The Editor dialog box appears.

2.	In the Tab Stops box, type the number of spaces to be used as a tab stop. The default is four spaces.

3.	Under Tab Settings, choose the Keep Tabs option to treat tabs as a single tab character when the file is saved.

Or select Insert Spaces to convert tabs to the number of spaces set in the Tab Stops box.

4.	Choose OK.

Even with the Keep Tab options checked, the editor converts tabs to multiple spaces when the file is open. You may notice that deleting a tab requires removing spaces rather than a single tab. The spaces are converted to tabs only when the file is saved to disk.

 To display or hide tab symbols:

Press CTRL+ALT+T

Tab symbols are displayed as >> whenever there is a tab in a source file. The CTRL+ALT+T keyboard shortcut is the only means of toggling the display of tab symbols.

You can press the TAB key to insert a single tab anywhere in your source file. You can also move a block of lines one tab to the right or left.

 To insert tabs in front of a group of lines:

1.	 Select the group of lines.

2. 	Press TAB.

 To delete tabs preceding a group of lines:

1.	 Select the group of lines.

2.	 Press SHIFT+TAB.


  Setting the Font and Font Size

You can change the text font and font size with the Fonts command. You can change the font for a window or make a font the default for all windows. You may find different fonts in various windows give visual clues about the function of the windows [image] the default setting for source windows, a different font for the watch window, and so on. You can use fonts and font size to better manage your window display.

 To change a font type and font size:

1.	From the Options menu, choose Font.

The Font dialog box appears.

2.	Select the font from the Font box. The text sample in the Sample box will change to the font you selected.

3.	Select the size in points from the Size box. The text sample in the Sample box will change to the font size you selected.

4.	Choose OK.

The currently used default font for all your editor windows is indicated below the Use as Default Font button. You can change the default font by selecting a font and a point size from the Font and Size list boxes and then choosing the Use as Default Font button.

Text within the source window can be only one font and size. Multiple fonts cannot be displayed in the same source window. However, each source window can contain a different font and size, even when source windows with different fonts are attached to the same source file.


Changing Syntax Colors

Using different colors for various language elements such as functions and variables gives you immediate visual cues about the structure of your source code. You can change the default colors of these elements as well as the color of other text such as reserved words, breakpoints, errors, and bookmarks. You can also turn off syntax coloring for all source files. These changes are global and affect all source files with extensions recognized by Visual Workbench.

 More Information on syntax coloring

 To change syntax coloring in an individual source file:

1.	Click on the source file window or use the Window menu to make the source window active.

If there are multiple windows open on the source file, select one of them. Syntax coloring changes will appear in all windows opened on the source file.

2.	From the View menu, select Syntax Coloring. A cascading menu appears on the right with three choices: C, C++, and None.

3.	Click C or C++ to determine syntax coloring for that source file. Or click None to turn syntax coloring off.

Note  Global syntax coloring must be enabled before you can use the Syntax Coloring command on the View menu on any specific file. To enable global syntax coloring, choose Color from the Options menu and then select the Syntax Coloring check box in the Color dialog box.


More Information on Syntax Coloring

Visual Workbench performs syntax coloring based on file extensions. You can override the default coloring for a file by choosing Syntax coloring in the View menu. This allows you to specify C, C++, or no syntax coloring for any individual file.

For any source file in Visual Workbench, you can specify which syntax coloring to apply [image] C or C++ [image] or whether to turn off syntax coloring all together. This is especially useful if you have C++ code in a header file with an .H extension (to which the development environment automatically attaches C syntax coloring), or if you have C or C++ source code with filename extensions that the development environment doesn't recognize. You should be cautious when using nonstandard extensions, however. The file extensions of some source files (.CPP,.CXX, and .C) are used by the development environment to determine whether the C++ or C compiler is used during the build.


Managing Windows
  Creating a New Window for a Source file

  Making a Window Read Only

  Switching to a Source Window

  Closing the Active Window


Source Window Topics
  Creating a New Window for a Source File

Since an opened file cannot be "reopened," you cannot use the Open command to display the same file in another window. To open a new window to view the same contents as the active window, use the Duplicate command. This procedure is helpful if you want to simultaneously view two parts of the same file.

 To create a new window for an open source file:

1.	If necessary, make the source window active by clicking it.

2.	Choose the Duplicate command from the Window menu.

Optionally, choose the Cascade or Tile command from the Window menu to arrange the two files.

You can scroll each window independently. You can make changes to the source file from any window. Each copy of the file is titled with its filename and given a number to identify it (1, 2, and so on).

Note  To keep the insertion point from jumping to where you click, use the right mouse button when making another window active.


  Making a Source Window Read Only

The Read Only command makes the current window [image] or any duplicates of the window [image] read only. When you choose this command, the file cannot be edited.

 To make a source window read only:

1.	Switch to the source window containing the file.

2.	From the Edit menu, choose Read Only.

To undo the command, choose it again.

A check mark next to the menu command and READ in the Status Bar indicate that a source file is read only.

This command is useful when you are viewing a source file and want to avoid making accidental changes to the file.

If you open a read only disk file, the Read Only command is automatically checked. To edit a version of the file, clear the Read Only command, make your edits, and then save the file under a different name.


  Switching to a Source Window

There are a number of ways to switch to a source window when more than one window is open during an editing session.

 To switch to a source window, either:

Click anywhere in the window (use the right mouse button to keep the insertion point from jumping to where you click).

Choose the window from the Window menu.

Use the shortcut key listed on the title bar (ALT+<window number>).

Use CRTL+F6 to cycle through all active source windows.

Use F6 to cycle through all active windows (includes source windows and all other windows).

Use CTRL+TAB to swith to the last active window (release the CTRL key to switch to the window).


  Closing the Active Window

All files are automatically closed when you quit Visual Workbench (you are prompted to save any altered files). You can also close any individual source file without exiting. If you have more than one window open on a source file, the file is not closed until all windows associated with it are closed.

 To close a source file:

1	. Switch to the source window.

2	. Then, either:

Choose Close from the File menu. This action closes the active window and any additional views of the window.

Double-click the window's Control-menu box if the window is not maximized, . When you double-click the Control-menu box, the window is closed but additional views of the window remain open.

Shortcut: CTRL+F4.

If the window is maximized, either:

Choose the Close command in the File menu

Choose the Close command in the Control menu

Press CTRL+F4.

Before you can close a window, it must be active. To make the window active, either click the window or select the window name or number from the Window menu.


Using Your Own Editor

You can add any editor to the Tools menu and open it from within the Visual Workbench. However, you cannot debug a source file from your own editor.

 To add an editor to the Tools menu:

1.	From the Options menu, choose Tools.

The Tools dialog box appears.

2.	From the Tools dialog, choose Add.

The Add Tool dialog box appears.

3.	Select the drive and directory to locate your editor. You can specify the file extension to focus your search in the List Files of Type box.

4.	Select the executable file.

5.	Choose OK to close the Add Tool dialog box.

6.	Optionally, give a name for the application in the Menu Text box. The filename base is given as a default.

You can assign a mnemonic to a tool (a mnemonic is the letter used to run a command on a menu). An ampersand (&) before a letter in the name marks the letter as the mnemonic. For example, the entry Notepa&d designates D as the mnemonic to open the application. By default, the first letter in the name is used.

7.	In the Arguments box, add any arguments for the application at startup.

A check in the Ask for Arguments box displays the Tool Arguments dialog box that prompts you for arguments on startup of the tool. Any arguments defined in the Arguments box are also listed in the Tool Arguments dialog box.

8.	In the Initial Directory box, optionally specify the directory you want to be current when the editor is opened. The default is the current directory for Visual Workbench when the editor is opened.

9.	Choose OK.


Project Topics

How Do I?	Brief	Click
Learn about projects	What you should know about projects
Create a project	Creating a project in the current, new or different directory
Choose a project type	What kind of application do you want to create? Windows NT application? Windows dynamic-link library? Console application? Static library?
Change a project type	Changing your project type (same project name)
Add files to a project	Adding files to a project
Delete files from a project	Deleting files from a project
Open or close an existing project	Opening and closing an existing project
Open an external project	Opening an external project (.MAK file) and letting Visual Workbench manage your files
Open a project from Program Manager	Adding the project file name and source file names to the properties of a Visual C++ icon
Open project files	Opening a project file in the current project with the Project Files button
Troubleshoot	Speeding up your work and clearing up problems


Project Basics

Projects are the cornerstone of Visual Workbench. A project keeps track of the various files and libraries that are needed to build a program or a library. It also contains information about compiler and linker options. Projects also contain information saved in workspaces, such as window sizes and positions.

Projects are stored on disk as two files: a makefile (.MAK extension), a workspace file, (.WSP extension), and a status file (.VCW extension). The makefile, which is compatible with the NMAKE utility, specifies the rules for the compilers and linker to build the target file. Visual Workbench calls this file the project file. When you open the project file from within Visual Workbench, the status file is automatically loaded.

To create a project, you add the filenames associated with the project to the project list, which Visual Workbench then uses to construct the project file. When you open a project, all source filenames in the project list are made available in the toolbars Project Files drop-down list. This gives you quick access to the main source files.

Projects also speed development time by recompiling only files that have changed since the programs last compilation or build.  You also have the option to rebuild all files from the start if you want.

Project Types

The project type specifies the kind of target file to be generated by a build. You choose a project type when you create the project using the New Project dialog box (accessed from the Project menu).  If you use AppWizard to create a project, AppWizard chooses the project type when it creates the project.

When you select a project type, the appropriate compiler and linker options are automatically set to generate the target file. These default options, which are sufficient for most needs, can be editied in the C/C++ Compiler Options and Linker Options dialog boxes.

You can use the following four project types for targeting 32-bit applications:

Windows application

Windows dynamic-link library

Console application

Static library

You can use the Microsoft Foundation Class Library with any of these types if you select the Use Microsoft Foundation Classes check box in the New Project or Project Options dialog box. Selecting Use Microsoft Foundation Classes links an extra library during the build and sets the library as a default linker option.

Windows Application

Applications written for Windows have a full graphical interface and are developed using NT Win32 API functions, or using the Microsoft Foundation Class Library. A Windows-based application filename has an .EXE extension.

Windows Dynamic-Link Library

Dynamic-link libraries are written using  Win32 API functions and contain functions that are called at run time by 32-bit Windows-based programs. A Windows-based DLL application filename has a .DLL extension.

Console Application

Console Applications use the Console APIs, which provide character-mode support for applications that run in a Console window in NT. The Visual C++ run-time libraries also provide output and input from the Console window with standard I/O functions, such as printf() and scanf(); however, the Console APIs provide additional flexibility.

Static Library

Static libraries are standard libraries that can be created directly from the build using object files that belong to the project. To create a static library (.LIB), create a project with normal project files and/or other object (.OBJ) files in the project file list, then build the project.

The generated library file is composed of all the object files in the project list and/or all object files generated by the build. This is a quick way to develop your own libraries from within Visual Workbench.

Include Dependencies

Visual Workbench creates an include dependency list whenever you create or edit a project. It does this by recursively searching all project files for the #include directives and adding each included filename to the project list. It scans both source files (.C, .CPP and .CXX) and resource files (.RC). Include files in the dependency list can have extensions of .H, .HXX, .HPP, .INC, .FON, .ICO, .CUR, .BMP, or .DLG. Since Visual Workbench automatically adds these file types to the project list, you cannot add them manually. These files do appear when you click the Project Files button on the toolbar.

  More information on Include Dependencies


Creating Projects
  Creating a Project

  Entering the Project Type

  Changing the Project Type


Creating a Project in a New or the Current Directory
   Creating a Project

Before creating a program, you need to create a project for it. A project may comprise several files including source files, resource files, and library files. Everything that applies to projects for programs also applies to projects for libraries.

You can become more familiar with the steps in building a project by using the files located in the \MSVCNT\MFC\SAMPLES\HELLO directory (HELLO.CPP, HELLO.DEF, and HELLO.RC) to create a multifile C++ project. Although there is already a project called HELLO.MAK in the directory, you can create a second project with a different name in that directory. This example assumes that you have installed the Microsoft Foundation Class Library sample programs.

The directory listed above is the default directory created by the Setup program. If you changed the default directory names during installation, the location of the required files will be different.

 To create a project in a new or the current directory:

1.	From the Project menu, choose New.

The New Project dialog box appears.

If you know the directory for the project, you can simply type the project name, including the complete path, in the Project Name box and skip to step 6. For example, if you installed Visual C++ on drive C, enter the following in the Project Name box:

C:\MSVCNT\MFC\SAMPLES\HELLO\MYHELLO.MAK.

If you would rather browse the directory, continue with step 2.

2.	Choose the Browse button to browse and change directories.

The Browse dialog box appears. This dialog box allows you to change directories and look at filenames. The purpose of browsing your directories is to make sure you use a unique name for the project and to change to the correct directory for the project.

3.	Use the Directories and Drives list boxes to change to the drive and directory containing the example files (\MSVCNT\MFC\SAMPLES\HELLO if youve installed into the default directory).

You should see the name of the existing project file (HELLO.MAK) already there.

4.	In the File Name box, type the new project filename.

For example, type MYHELLO.

All project files have a .MAK extension. The .MAK extension is automatically added when you choose OK.

5.	Choose OK.

The Browse dialog box disappears, and the project name you specified appears in the Project Name box preceded by its path. You must now specify a project type.

6.	From the drop-down list in the Project Type box, select a project type.

For this example, select Windows application (.EXE).

7.	Check the Use Microsoft Foundation Classes check box if your application uses the foundation classes (the HELLO sample does).

8.	Choose OK. The Edit    Projectname dialog box appears.

9.	Add the necessary filenames in the project to the project list.

In this example, you need to add HELLO.CPP, HELLO.DEF, and HELLO.RC. (HELLO.H cannot be added now since all include files are automatically found and added when the dialog box is closed.).

10.	Choose the Close button to save the project and scan all the source files for include files.

Whenever you close (not cancel) the Edit     Projectname dialog box, Visual Workbench recursively scans all files in the project list for #include directives and automatically adds any include files it finds to the project list.

  More information on Include Dependencies

Note  If your program consists of only one file, you can build and run it without creating a project. However, it is a good idea to create a project if you have unique compiler or linker settings, since these will be lost if another project is loaded or Visual Workbench is restarted.


   Entering a Project Type

The project type specifies the kind of target file to be generated by a build. You choose a project type when you create the project using the New Project dialog box (accessed from the Project menu).  If you use AppWizard to create a project, AppWizard chooses the project type when it creates the project.

When you select a project type, the appropriate compiler and linker options are automatically set to generate the target file. These default options, which are sufficient for most needs, can be editied in the C/C++ Compiler Options and Linker Options dialog boxes.

You can use the following four project types for targeting 32-bit applications:

Windows application

Windows dynamic-link library

Console application

Static library

You can use the Microsoft Foundation Class Library with any of these types if you select the Use Microsoft Foundation Classes check box in the New Project or Project Options dialog box. Selecting Use Microsoft Foundation Classes links an extra library during the build and sets the library as a default linker option.

 To enter a project type:

1.	From the Project menu, choose New. The New Project dialog box appears.

2.	In the Project Type box, select a project type. For example, select Windows application (.EXE).

3. If your project includes C++ source files and you are going to use the Microsoft Foundation Class Library in the C++ source, select the Use Microsoft Foundation Classes check box.

Note  If you are building an MFC application for Windows NT, you should create a new project using AppWizard on the Project menu instead. AppWizard creates a project with skeleton source code for an application.

4.	Choose OK. The Edit Project dialog box appears. Now you can add files to the project.

5.	Set the type of files to choose with the List Files of Type box.

6.	From the file list, select the file to add to the project and choose Add or double-click the filename. Repeat until all files are added. If you want to add all the files of the selected type in the selected directory, click Add All. Added files appear in the Files in Project box.

You can also type the names for files that do not yet exist and add them to the project by pressing ENTER or clicking Add. When you open the file using the Project File button on the toolbar, Visual Workbench asks if you want to create the file.

You cannot add certain included files (.H, .HPP, and .HXX, among others) directly. Visual Workbench adds these files automatically when it scans the list of files for dependencies.

  More information on Include Dependencies

7.	Choose OK.


   Changing a Project Type

Every project must contain a "project type." A project type specifies the kind of target file generated by a build. You determine a project type when first creating the project. To change the project type of an existing project, use the Project dialog box on the Options menu.

 To change a project type:

1.	From the Options menu, select Project.

2.	From the Project Type list, select the type for the project that you want to build.

3.	If you are using the Microsoft Foundation Class Library to build a Windows program, select Use Microsoft Foundation Classes.

Note  If you are building an MFC application for Windows, you should create a new project using AppWizard on the Project menu instead. AppWizard creates skeleton code for an application.

4.	Click OK.


Adding or Deleting Files from a Project

When you create a project, you can add files to the project. As projects grow and change, however, you may need to add files to or delete files from the project. When you delete a file from the project, only the reference to that file is removed. The actual file is not deleted from the hard disk.

Choose the Edit command from the Project menu to open a dialog box where you can add or delete project files. This dialog box is identical to the dialog box used to add files to a new project.

 To add a file to the project:

1.	From the Project menu, choose Edit.

The Edit    Projectname dialog box appears.

2.	Use the List Files of Type drop-down list box to set the type of files that appear in the File Name box.

3.	From the file list in the File Name box, select the file to add to the project and choose Add.

Or

Double-click the file in the file list.

Choose Add All to add every file that appears in the file list to the project list. This can save steps if you have several source files you want to add.

4.	Repeat steps 2 and 3 for each file (or set of files) you want to add to the project.

5.	Choose Close when you finish editing the list of project files.

  More information on Include Dependencies

 To delete a file from the project:

1.	From the Project menu, choose Edit.

The Edit    Projectname dialog box appears.

2.	Select the file from the Files in Project box and choose Delete.

Or

Double-click the file in the Files in Project box.

3.	Repeat step 2 for each file you want to delete from the project.

4.	Choose Close when you finish editing the list of project files.

An include dependency scan now takes place.

  More information on Include Dependencies


Opening Projects
  Opening or Closing an Existing Project

  Opening an External Project (Makefile)

  Opening a Project from Program Manager


Opening or Closing Projects
  Opening or Closing an Existing Project

Although you can maintain many projects on your disk, Visual Workbench can work with only one project at a time. You can recall any previously created project by opening it. When you open an existing project, the current project is automatically closed, or you can close it manually.

  To open an existing project:

1.	From the Project menu, choose Open.

2.	From the file list, select a project file (.MAK extension).

3.	Choose OK.

Tip  You can also open a project by using the Windows File Manager to display the project file icon and then dragging and dropping the project file icon into Visual Workbench.

  To close a project, either:

From the Project menu, choose Close.

Open another project.

Create another project.

Note  Open project files are not closed when a project is closed.


  Opening an External Project (Makefile)

If you have existing makefiles you want to use in place of Visual Workbenchs project makefiles, you can run them from within Visual Workbench. These makefiles are called external projects because they are external to the normal mode of selecting project options from within Visual Workbench.

When you use an external makefile, you are responsible for the contents and actions of that makefile, since Visual Workbench does not read or alter the file. You can, however, build an external project and run any resulting program from within Visual Workbench. If your external makefile generates a CodeView-compatible debug version of the executable file, you can also debug the target from within Visual Workbench.

To use an external project, open it as you would any Visual Workbench project but select the Use as an External Makefile check box in the Open Project dialog box, accessed from the Open command on the Project menu.

 To open an external project:

1.	From the Project menu, choose Open.

The Open Project dialog box appears.

2.	In the File Name box, type the name of the external makefile.

3.	Select the Use as an External Makefile check box.

If you miss this step, Visual Workbench prompts you when it attempts to open the project as a Visual Workbench project and cannot. You can specify at that time that it is an external project.

4.	Choose OK.

Once the external makefile is loaded, you can set build options by choosing the Project command from the Options menu. This opens the External Project Options dialog box where you can set build options.

 For more information on the External Project Options Dialog Box

Importing Microsoft Programmers Workbench (PWB) makefiles into Visual Workbench is straightforward since PWB makefiles use the default NMAKE command line in the Debug Build, Release Build, and Rebuild All Options text boxes. If you want the ability to build both Release and Debug versions, you can use the same makefile for both and add DEBUG=1 as a command-line option in the Debug Build text box and DEBUG=0 as a command-line option in the Release Build text box.


More Information on External Project Options Dialog Box
More Information on the External Project Options Dialog Box

The build options you can set in the External Project Options dialog box are:

Debug Target Name

Visual Workbench uses the name of the executable target file in this box to determine what file to use when you use the debugger. This name also appears on the Project menu following Build, Rebuild All, and Execute. Visual Workbench assumes the name of the executable file to have the same base name as the project. If you change the name in the Debug Target Name box, you are responsible for making sure your external makefile generates an executable file with this same name.

Project Type

This is the target file type (Executable, DLL, or other). Depending on the project type specified here, the Debug dialog box, accessed from the Options menu, presents slightly different options. If the project type is specified as Executable, the upper text box in the Debug dialog box is labeled Program Arguments and lets you enter any parameters to pass to the program. If the project type is specified here as DLL, the upper text box in the Debug dialog box is labeled Calling Program and lets you enter the executable filename that calls the DLL.

Debug Build

This is the program maintenance utility, such as NMAKE, along with any command-line options it requires to build a debug version of the project type. The command in this box is invoked when you choose Build Targetname from the Project menu or click the Build button on the toolbar if you have Debug selected under Build Mode in the External Project Options dialog box.

Release Build

This is the program maintenance utility, such as NMAKE, along with any command-line options it requires to build a release version of the project type. The command is this box is invoked when you choose Build Targetname from the Project menu or click the Build button on the toolbar if you have Release selected under Build Mode in the External Project Options dialog box.

Rebuild All Options

This is the command-line option required by the program maintenance utility to generate a complete rebuild. The command line specified in either the Debug Build or Release Build text box (depending on which mode you are building) and the command-line option in this text box are combined and invoked when you choose Rebuild All Targetname from the Project menu or click the Rebuild All button on the toolbar.


  Opening a Project from Program Manager

You can automatically open a project and any of its associated files by creating an icon in Program Manager and modifying the icon's properties to include the project file and the source files on the command line.

 To open a specific project from Program Manager:

1.	Create a new Visual C++ icon in the appropriate program group.

You can create a new icon by holding down the control key and dragging the installed icon to its new location with the mouse.

2.	Select the new icon, open the File menu and choose Properties.

3.	In the Command Line box, add the project file name (.MAK extension) and any source file names after the name of the executable file.

4.	If necessary, change the directory in the Working Directory box to the project directory.

When you double-click this icon, it opens the named project and opens the specified source files in editor windows.


Opening Files in a Project
Opening a Project File

After opening a project, you can easily open any project file with the Project Files button on the toolbar.

Project Files button:

 To open any source file in the current project:

1.	Click the Project Files button on the toolbar. A list box with all files in the current project drops down.

Shortcut:  CTRL+P

2.	Click a file from the list.

Note  You can also open a project file by choosing the Open command on the File menu.


More Information on Include Dependencies

Visual Workbench creates include dependency lists whenever you create or edit a project. It does this by recursively scanning all the project files for #include directives and adding each included filename to the project list. Both source files (.C, .CPP, or .CXX) and resource files (.RC) are scanned, so the include files in the dependency list can have extensions of .H, .HXX, .HPP, .INC, .FON, .CUR, .BMP, .ICO, or .DLG. Since these file types are automatically added to the project list, you cannot add them manually. These files are part of the project list and are available in the Project Files drop-down list, accessed from the toolbars Project Files button.

Toolbar shortcut:

An include dependency list associates each included file with the files that include it and are therefore dependent upon it. This allows Visual Workbench to generate the correct build dependencies. For example, when you edit a header file and perform a build, the build compiles only the files that include the modified header file.

An include dependency scan takes place automatically when you close the Edit [image] Projectname dialog box, after you have either created or edited the project list. If you subsequently include a new file in any file in the project list, you should regenerate the include dependencies for the project.

 To regenerate include file dependencies for the entire project:

From the Project menu, choose Scan All Dependencies.

 To regenerate include file dependencies for the active file:

From the Project menu, choose Scan Dependencies Filename (Filename appears on the menu as the name of the active source file).

Whenever a dependency scan occurs, a status window appears showing the status of the include dependency scan as it searches files. You can cancel this scan at any time by choosing the Cancel button, in which case the previous include dependency list remains in effect.

Visual Workbench scans both bracketed include files (<includefile.h>) and user include files ("includefile.h"). There are a large number of system include files shipped with Visual C++ that are unlikely to be changed. Since it would be inefficient to scan these include files when they are included by a project file, Visual Workbench uses an exclusion file called SYSINCL.DAT that contains a list of these include files. Whenever Visual Workbench scans for include dependencies, it uses this list to exclude any filenames it finds that match those in this list.

The exclusion file is an editable file, and you can use it to fine-tune your build dependencies. For example, if you have a large header file that you never change, you could add it to the list in the exclusion file. Then, whenever you generate include dependencies, that file will not be scanned. As another example, you may want a Microsoft system include file scanned because you are altering it, in which case you could remove that include filename from the exclusion file. Visual Workbench never overwrites this file, but it does build a new file containing all system include files shipped with Visual C++ whenever it doesnt find a SYSINCL.DAT file at startup. So you can easily regenerate the original file at any time simply by deleting or renaming the current exclusion file.


Tips and Troubleshooting

Using One Source File

If you are building a program that has only one source file, creating a new project is optional.

Adding Include Files

You cannot add certain included files to your project using the Edit Project dialog box. These files (with extensions .H, .HXX, .HPP, .INC, .FON, .ICO, .CUR, .BMP, or .DLG) are added to the project automatically when Visual C++ scans the project files for file dependencies.

Setting Tools Options Strings

You set default values for the Debug and Release option strings when you choose a project type. These sets of strings specify the behavior of the tools used by Visual C++ to create your project's target. You can view or modify these option strings by selecting Project on the Options menu and then opening the C/C++ Compiler Options or Linker Options dialog box. In the Project dialog box, you also specify whether to build a debug or a release version of your project by selecting either the Debug or Release option button.

Changing Project Types

If you create a project initially with a certain project type and set custom options for that type using the Project Options dialog box, but later change to another project type (from a type not using p-code to a type using p-code, for example), Visual Workbench changes all the options for the compilers and the linker to the defaults for the new type. It displays a message indicating that it is going to make this change. If you choose Cancel, it reverts to the original project type, and makes no changes to the option strings. You can then examine and record your option selections and retype the desired ones after making the change to the project type.

Changing Project Options Changes Target Type

If you choose a project type, but subsequently use the Project Options dialog box to set options that represent a different project type, the Build command builds the program using the options that you subsequently set. For instance, when you choose an executable program for Windows, the default options string includes /GA. Later, if you open the Compiler Options dialog box and set /GD, for DLLs for Windows, this option replaces /GA, because these two options are exclusive. The Build command then builds a DLL instead of an executable program.

Including a Toolbar

If you choose the option to include a toolbar with your application when creating a skeleton application with AppWizard, you need to edit the bitmap that is added to your suite of files. Use App Studio to edit the bitmap.


Building

How Do I?	Brief	Click
Learn about compiling and building	What you should know about compiling and building
See a list of shortcuts	List of toolbar and keyboard shortcuts for compiling and building
Compile or build	Compiling files or building projects; rebuilding a program
Run a program	Starting or restarting program execution; executing a program outside of the debugger
Build a Windows-based application	Building a Windows-hosted application with the C run-time or Microsoft Foundation Class Library
Build a C++ application	Building a Windows-hosted application using the Microsoft Foundation Classes
Build a Console application	Building a Console application to run in an MS-DOS virtual machine
Build a static library	Building a static library, a collection of routines or data compiled into object code by the compiler.
Build DLLs	Compiling files into a dynamic-link library for Windows.
Set build options	Setting options for the debugger; compiler and linker options; resource compiler; external projects
Build with precompiled headers	Decreasing compile time by using precompiled headers; using precompiled headers for projects with both C and C++ source files
Set default directories	Customizing directory settings for different projects
Troubleshoot	Speeding up your work and clearing up problems


Building and Compiling
  Compiling a File

  Building a Program

  Rebuilding a Program


Compiling a Program
   Compiling a File

The Compile File command creates an object file (.OBJ) from the active source file.

 To compile a file:

From the Options menu, choose Project to set the compiler options.

From the Project menu, choose Compile File.

Toolbar shortcut:

Shortcut:  CTRL+F8

The Output window shows the progress of the compile.

The new object file has the same name as the original source file, but with an .OBJ extension. Object files are placed in the same directory as the project file. If there is only one source file and no project file, the object file is placed in the same directory as the source file.

An object file contains intermediate code that must be linked to form an executable file. The Build command links the .OBJ file into an EXE, a DLL, or a LIB file.

Tip  Use the Ctrl+Break key combination to stop the current compile.


   Building a Program

The Build command compiles and links all out-of-date files to create an EXE, a DLL, or a LIB file. The command also opens and runs the Resource Compiler if resource files are in the project.

 To build a program for an existing project:

1.	From the Project menu, choose Open.

The Open Project dialog box appears.

2.	Select a project file.

3.	Choose OK.

4.	From the Options menu, choose Project.

The Project Options dialog box appears.

5.	Under the Build Mode options, select either Debug or Release.

6.	Choose OK.

7.	From the Project menu, choose Build.

Toolbar shortcut:

Shortcut:  SHFT+F8

The Output window displays information about the progress of the build, which the NMAKE utility manages.

When the build has completed, Visual Workbench gives an audible signal and displays the final results on its status bar. If the program built successfully, the status bar should indicate 0 errors and 0 warnings. If there are any errors, the status is colored. If there are link or include file errors, make sure that the library and include-file paths are correct in the Directories dialog box (opened from the Options menu).

Tip  Use the Ctrl+Break key combination to stop the current build.


   Rebuilding a Program

The Rebuild All command compiles and links all files to create an EXE, a DLL, or a LIB file, even if they are not out-of-date.

 To rebuild a program:

1.	Create or open a project.

2.	From the Project menu, choose Rebuild All.

Toolbar shortcut:

Shortcut:  ALT+F8

If no errors are reported, the program is compiled and linked. The Output window reports the progress of the build.

Multimodule programs cannot be built unless the corresponding project is open. If you do not open a project, the development environment assumes that the current file is the only module in the program.

Tip  Use the Ctrl+Break key combination to stop the current build.


Running a Program
  Running a Program Using Go

  Running a Program Using Restart

  Running a Program Using Execute


  Running a Program Using Go

The Go command starts or continues program execution.

 To run a program, either:

From the Debug menu, choose Go.

From the toolbar:  .

Press F5.

Execution proceeds from the current statement until one of the following occurs:

The program reaches a breakpoint

The program ends

If the source files have changed since the last build, you are asked if you want to rebuild the project.

Tip  When execution begins, variables retain any prior values.


  Running a Program Using Restart

The Restart command reloads the program into memory and discards any current variable values. It starts program execution, but halts execution at the main( ) or WinMain( ) function if the program was built with the Debug build option.

 To restart a program:

From the Debug menu, choose Restart, or

Press SHIFT+F5.

You can use Restart whenever execution has stopped:

At a breakpoint

While single-stepping

When normal execution is complete

If you set the Debug build option and program execution halts, you can use the Go, Step Into, Step Over, or Step to Cursor command to resume execution.

If the source files have changed since the last build, before the program restarts, you are asked if you want to rebuild the project.

Tip  Breakpoints and watch expressions still apply after a Restart command.


  Running a Program Using Execute

The Execute command executes the program built by the project outside the debugger. The menu command specifies the program or, in the case of external projects, the target.

 To execute a program:

From the Project menu, choose Execute

or

Press CTRL+F5.


Building an Application for Windows

A Windows-hosted application can use either C run-time library functions or C++ with the Microsoft Foundation Class Library, or both. When you build your project, Visual Workbench recognizes from the file extensions whether a file is C file (extension .C) or a C++ file (extension .CPP). It takes the appropriate action when compiling each file type.

 To build an application for Windows:

1.	Open or create a project, using the Open, New, or AppWizard command on the Project menu.

2.	If you created a new project, select Windows application (.EXE) from the list of project types.

3.	From the Project menu, choose Build.

Toolbar shortcut:

Shortcut:  SHIFT+F8

When the build has finished, there should be 0 errors and 0 warnings reported on the status bar. If there are any errors, correct them and repeat the build. If there are link or include file errors, make sure that the library and include-file paths are correct in the Directories dialog box (opened from the Options menu).


Building a C++ Application

You can use AppWizard to create the framework for a C++ application for Windows. AppWizard uses the Microsoft Foundation Classes to create all the necessary project files for an application with features that you normally want in an application for Windows. The program has a frame window with a menu bar, a toolbar, and a status line.

 To build a C++ application using AppWizard:

1.	From the Project menu, choose AppWizard.

The MFC AppWizard dialog box appears.

2.	Type a project name in the Project Name box.

The project specifies all the files required to build your C++ application. You can select drives or directories as necessary, or choose another subdirectory name.

AppWizard also proposes the project name as a subdirectory name in the current directory to store the project files. This name appears in the New Subdirectory box. You can enter another name, if you choose.

3.	If you want to include or exclude certain features from your program, click Options. In the Options dialog box, select or clear the check boxes for the desired features.

 More on the Options option

4.	If you want to specify class names or the files in which class information is contained, click Classes, and enter the desired information in the dialog box.

 More on the Classes option

5.	Choose OK.

AppWizard creates the selected subdirectory with the required files, and then opens the project in Visual Workbench.

6.	From the Project menu, choose Build.

Toolbar shortcut:

Shortcut:  SHIFT+F8


Building a Console Application for Windows NT

A Console application uses standard input/output, and runs in an MS-DOS virtual machine under Windows NT. When you build a program as a Console project type and then run it from Windows NT in an MS-DOS virtual machine, the virtual machine functions as if it were a video monitor. You can write to the window and perform input and output operations either with standard C routines like printf and scanf, or with C++ iostream objects cin and cout and the overloaded << and >> operators.

 To build a Console application:

1.	Open or create a project, using the Open or New command on the Project menu.

2.	If you created a new project, select Console application (.EXE) from the list of project types.

3.	From the Project menu, choose Build.

Toolbar shortcut:

Shortcut:  SHIFT+F8

When the build has finished, there should be 0 errors and 0 warnings reported on the status bar. If there are any errors, correct them and repeat the build. If there are link or include-file errors, make sure that the library and include-file paths are correct in the Directories dialog box, opened from the Options menu.


Building a Static Library

The Build command can compile source files into a static library. You can then include the library when you build other programs.

 To build a static library:

1.	Open or create a project, using the Open or New command on the Project menu.

2.	If you created a new project, select Static library (.LIB) from the list of project types.

3.	If you created a new project, click OK.

The Edit - Projectname dialog box appears. Select the programs that comprise your project and add them to the project. You can select files and use the Add button, double-click filenames, or click the Add All button to add all currently displayed files.

When you have completed adding files, click OK.

Visual Workbench opens the newly created project.

4.	From the Project menu, choose Build.

Toolbar shortcut:

Shortcut:  SHIFT+F8


 Building a Windows DLL

The Build command can compile source files into a dynamic-link library (DLL) for Windows. Programs written for Windows can then call the DLL.

 To build a dynamic-link library:

1.	Open or create a project, using the Open or New command on the Project menu.

2.	If you created a new project, select Windows dynamic-link library (.DLL) from the list of project types.

3.	If you created a new project, click OK.

The Edit - Projectname dialog box appears. Select the programs that comprise your project and add them to the project. You can select files and use the Add button, double-click filenames, or click the Add All button to add all currently displayed files.

When you have completed adding files, click OK.

Visual Workbench opens the newly created project.

4.	From the Project menu, choose Build.

Toolbar shortcut:

Shortcut:  SHIFT+F8

Note  If you chose the /O1 optimizing option in the Optimizations category of the C/C++ Compiler Options dialog box, set /OPT:NOREF in the Other Options text box of the Miscellaneous category in the Linker Options dialog box to prevent removal of exported functions. The /O1 option implies the /Gy option, which creates packaged functions.


Build Options
  Setting Run and Debug Options

  Setting Compiler and Linker Options

  Setting Resource Compiler Options

  Setting Options for External Projects


  Setting Debug Options

When you run your executable program or DLL in the debugger, you may need to include command-line arguments, run other DLLs, or choose a display or debugging mode.

 To set options for the debugger:

1.	If you are debugging an executable file, enter any command-line arguments in the Program Arguments box.

If you are debugging a DLL, enter the name of the program which calls the DLL in the Calling Program box.

2.	If you want to set breakpoints in any additional DLLs, enter the names of the DLLs in the Additional DLLs box.

The debugger loads symbolic information for all DLLs listed.

3.	Select Hexadecimal Display if you want values in the debugger displayed in hexadecimal format.

This affects the displays in the Modify Variable and QuickWatch dialog boxes, and the Locals and Watch windows.

4.	Select Uppercase for Hexdecimal Display if you want hexadecimal digits displayed only in uppercase letters [image] F7AE, instead of f7ae.

5.	Select Use a Single Edit Window for all Source Files if you want to use the same edit window to display each source file when the debugger breaks in it rather than opening a new edit window for each source file.


  Setting Compiler and Linker Options

Visual Workbench sets the minimum options required by your project type for the compiler and linker when you create your project. You can alter the default settings or set additional options for the compiler, linker, or resource compiler.

You can set option strings that the compiler and linker use to build programs either with debugging information (Debug) or without debugging information (Release). The option button Common to Both displays options common to both debug and release builds, and allows you to set common options.

You set the values of the Debug or Release option strings in the Compiler and Linker dialog boxes; you choose which option string to use when building in the Build Mode group of the Project Options dialog box.

 To set compiler options:

1.	Create or open a project.

2.	From the Options menu, select Project.

3.	Under Customize Build Options, click Compiler.

The Compiler Options dialog box opens. The current options string appears in the text box at the top of the dialog box.

4.	Select the Debug Specific, Release Specific, or Common to Both option button.

The option string displayed in the text box changes to display the options string corresponding to your choice. The string _DEBUG is defined with the /D option for the Debug options string for instance, but NDEBUG is defined for the Release options string. Neither appears in the options string that is common to both debug and release options.

5.	In the Category box, click the category in which you want to set options.

If you want help on the category, press F1.

6.	Set the desired option.

In some cases, you can choose alternatives from list boxes. In other cases, you can toggle an option with check boxes or option buttons.

If none of the predetermined categories have the option that you want to set, you can select Custom Options. In the Other Options box you can enter any options that you choose.

The option (or options, if one setting requires another option to be set) appears immediately in the Options string.

Note  If you want to know what a given option in the options string is, or in which category to set or clear it, you can double-click the option in the options string with the mouse to select it and then press F1.

7.	Click Close.

8.	Click OK in the Project Options dialog box.

 To set linker options:

1.	Create or open a project.

2.	From the Options menu, select Project.

3.	Under Customize Build Options, click Linker.

The Linker Options dialog box opens. The current options string appears in the box at the top of the dialog box.

4.	Select the Debug Specific, the Release Specific, or the Common to Both option button.

The option string displayed in the text box changes to display the options string corresponding to your choice.

5.	In the Category box, click the category in which you want to set options.

If you want help on the category, press F1.

6.	Set the desired option.

In some cases, you can choose alternatives from list boxes. In other cases, you can toggle an option with check boxes or option buttons. If none of the predetermined categories have the option that you want to set, you can select Miscellaneous. In the Other Options box, you can type any options supported by the linker.

The option [image] or options, if one setting requires another option to be set [image] appears immediately in the Options string.

Note  If you want to know what a given option in the options string is, or in which category to set or clear it, you can double-click the option in the options string with the mouse to select it and then press F1.

7.	Click OK.

8.	Click OK in the Project Options dialog box.


  Setting Resource Compiler Options

The resource compiler compiles resource files used by programs for Windows.

 To set resource compiler options:

1.	From the Options menu, select Project.

The Project Options dialog box opens.

2.	Under Customize Build Options, choose Resources.

3.	In the Custom Options box, type any other options supported by the resource compiler.

4.	Under Defines, you can type strings that you want defined for the resource compiler for Debug builds and for Release builds.

Do not enter /D with the strings that you want defined. You can enter either a string or a string followed by an equal sign and a value. For instance, you enter either _TEST or VERSION=1.11a.

5.	Click OK.


  Setting Options for External Projects

An external project is a project file (.MAK) not created by Visual Workbench. If you open a project file and Visual Workbench determines that it did not create the file, it displays a message box asking you if the file is an external makefile. If you choose Yes, it then treats the project as an external project. You can also explicitly specify that a project file that you are opening is an external makefile by selecting the Use as External Makefile check box in the Open Project dialog box. In either of these cases, Visual Workbench displays the External Project Options dialog box if you choose the Project command from the Options menu.

Note  When you create a project with AppWizard, you can click the Options button and select External Makefile to create a makefile in a form recognized by Microsoft NMAKE. It selects a target name based on the project name.

Visual Workbench uses the options that you set in the Build and Rebuild All commands on the Project menu.

 To set options for an external project:

1.	From the Options command, select Project.

The External Project Options dialog box opens.

2.	Enter the name of the target file built by your build program in the Debug Target Name box, if it is not based on the project name.

Visual Workbench uses this name with the debugging commands on the Debug menu and the Execute command on the Project menu.

3.	Select the Project Type that the compiler is to build from the option buttons under Project Type.

"Other" indicates a static library.

4.	Select the build mode from the option buttons under Build Mode.

The mode selected determines whether Visual Workbench uses the string in Debug Build box or the string in the Release Build box.

5.	In the Debug Build box, enter the string that starts your make program with appropriate options to build a version of your program with symbolic debugging information.

If you want to build a target program with a name different from the project name, enter the any options required to name the target program as well.

6.	In the Release Build box, enter the string that starts your make program with appropriate options to build a version of your program without symbolic debugging information.

If you want to build a target program with a name different from the project name, enter the any options required to name the target program as well.

7.	In the Rebuild All Options box, enter the options required by your make program for it to recompile and relink all the source files used by your program whether they are out of date or not.

Note  The default entry, /a, is the option used by Microsoft NMAKE.

8.	Click OK.


Building with Precompiled Header Files
  Building with Automatic Precompiled Headers

  Building with Selected Precompiled Headers


  Building with an Automatic Precompiled Header

You can greatly speed compile time by compiling any C or C++ files [image] including inline code [image] into a precompiled header file (.PCH) and thereafter using the precompiled header for each build. Although the Visual C++ compiler allows several ways to create and use precompiled header files, the Precompiled Headers category in the C/C++ Compiler Options dialog box presents a single, simplified approach to implementing this feature.

Note  If you use AppWizard to create a project for a Windows program, AppWizard sets up the project options to use a precompiled header by default.

You can take two approaches to the use of precompiled header files:

By using an automatic precompiled header

or

By selecting precompiled headers

The easiest approach is to use automatic precompiled header files.

The compiler creates a file named project.PCH (if it doesn't exist), and then compiles only header files into this precompiled header file. The inclusion of header files stops when the compiler encounters the first declaration, definition, hdrstop pragma, or #line directive in a header file.

If you have only one source file in your project, all preprocessor directives up to the first line of C or C++ code are automatically compiled into project.PCH. Any subsequent compilations then use project.PCH instead of the preprocessor directives, provided that they haven't changed in any way.

If you have more than one source file, you must take care to use automatic precompiled headers effectively. You can use automatic precompiled headers in three ways. In all three ways, preprocessor directives must be:

Contiguous

In the same order (with the exception of groups of #define statements)

At the beginning of each source file

The three ways are:

Place identical preprocessor code in every file. The compiler creates project.PCH when it compiles the first file, and all subsequent files and all subsequent builds use it.

Place a subset of identical preprocessor directives at the beginning of every file. The compiler creates project.PCH containing all the identical code. During the first build, this method requires the compiler to rebuild project.PCH every time it encounters different preprocessor directives after the subset of identical preprocessor directives. On all subsequent builds, the compiler uses project.PCH instead of the subset of precompiler directives.

Identify in advance the point at which the compiler should stop including preprocessor directives in project.PCH. You can either specify a filename in the Compiler Options dialog box, or you can include a hdrstop pragma in a common place in all your source files after the last header file to be included.

 To set automatic precompiled header options:

1.	Create or open a project.

2.	From the Options menu, select Project.

3.	Under Customize Build Options, click Compiler.

The Compiler Options dialog box opens. The current options string appears in the text box at the top of the dialog box.

4.	Select the Common to Both option button.

5.	In the Category box, click Precompiled Headers.

6.	Click the Automatic Use of Precompiled Headers check box.

7	.If you want to stop building the precompiled header after a certain header file, enter the name of that header file in the Precompile through Header text box.

8.	Click Close.

9.	Click OK in the Project Options dialog box.


Building with Precompiled Header Files
  Building with Selected Precompiled Headers

If your project includes source files with both C and C++ code and you want to use separate precompiled headers for each language, you can select precompiled headers. You can choose distinct filenames for the precompiled header files for both C and C++ files, and include different code in each one. The compiler precompiles all code up to the named file. This option allows you to precompile code as well as header files.

Note  The compiler ignores hdrstop pragmas in files from projects where you have selected precompiled headers rather used automatic precompiled headers.

 To set selected precompiled header options:

1.	Create or open a project.

2.	From the Options menu, select Project.

3.	Under Customize Build Options, click Compiler.

The Compiler Options dialog box opens. The current options string appears in the text box at the top of the dialog box.

4.	Select the Common to Both option button.

5.	In the Category box, click Precompiled Headers.

6.	If you have C++ files in your project, in the C++ Files: Precompile through Header box, type the name of the C++ header file at which you want to stop building the precompiled header.

The compiler takes the base name of this file and appends .PCH to it to create the precompiled header file.

7.	In the C++ Files: Precompile with Source box, highlight the C++ source file name that includes the list of header files up to the header file specified.

8.	If you have C files in your project, complete steps 6 and 7 using the text boxes under C Files.

9.	Click Close.

10.	Click OK in the Project Options dialog box.


Setting Default Directories

The Setup program for Visual C++ sets the values of the directories where Visual C++ finds its various components. Visual Workbench also keeps track of the last four strings set in the Include Files Path (and Library Files Path and Executable Files Path) and makes them available in a list box. If you have different types of projects that require different directories for include files, you can easily switch among them.

 To set directories for include files or library files:

Delete the current string and type a new string. You can enter multiple directories separated by semicolons (;).

Add a directory to the string by moving the insertion point to the desired location, then typing a semicolon (;) followed by the additional directory.

Select a string from the list box, if you have previously changed the contents of the text box. (Visual Workbench retains the last four strings used.)

 To set the directory for help files or MFC source files:

Delete the current string and type a new string.You can enter only one directory.

Note The Browser and the debugger use the MFC Files path to find MFC source files, if necessary.


OBJ file
An .OBJ file contains intermediate code produced by compiling a program and used by the linker to form an executable file.


out of date
A file is out of date if it has been edited after the last compile or compiled after the last link. Visual Workbench checks the time stamp of the file on disk before executing the Build command from the Project menu.


resource file
A resource is read-only data stored in your application's EXE file or DLL. Windows reads a resource from disk on demand. Certain types of resources have prescribed formats recognized by Windows. These include bitmaps, icons, cursors, dialog boxes, and fonts.


project
A project is a list of files and options associated with a program. Visual C++ compiles and links a program [image] known as building [image] using information in the project. Compiler, linker, and resource compiler options are all saved in the project.

Any project can be edited by adding or deleting files or changing options. The project information is stored in an ASCII makefile with the extension .MAK.

A project can include source files(.C or .CPP), header files (.H or .HXX), resource files (.RC), a module-definition file (.DEF), object files (.OBJ), and library files (.LIB). The .MAK file contains options for the linker, the compilers, and any other required tools.


Static Library
A static library is a collection of routines or data that has been compiled into object code by the compiler. The code for the routines or data is linked into a program by the linker.


Building Basics

You generate a program or a library in Visual C++ by creating a project and then building it.

The project keeps track of the various files that are needed to build the program or library. It also keeps track of options for the tools used to create the program or library. Each project has a type associated with it. When you create a project and select a project type, you are specifying the kind of target file to generate with the project. Each project in Visual C++ produces a single target file.

When you build a project, you run a set of Visual C++ tools with the options currently specified by the project. The tools take as their input the source files that you include in the project, include files distributed with Visual C++, any libraries required by the project type, and any libraries that your target requires. Those tools generate the target file for your project.

 To create and build a project:

1.	Create a project.

If you are creating a Windows-based program, you can use AppWizard on the Project menu. It creates a set of C++ starter files for the project type that you select. The starter files include skeleton code for a fully functioning, minimal Windows-based program. AppWizard automatically creates a project and adds the starter files to it.

Otherwise, use New on the Project menu, select a project type, and add the appropriate files to the project.

2.	Select how to build your project.

From the Options menu, you can open the Project Options dialog box to select how to build your project. If you select the Debug build mode, symbolic debugging information is generated for your files, which you can then use for debugging your code. If you select the Release build mode, no symbolic debugging information is generated. In addition, the Debug mode generally does not use any optimizations, while the Release mode generally does.

In addition, you can choose custom settings for the compiler, for the linker, and if you're building a Windows-based program, for the resource compiler.

3.	Build your project.

From the Project menu, select the Build command to run all the tools with all the specified source files. After you have once built a project, selecting the Build command again only runs tools to build the output from source files that are dated later than the target file. The Rebuild All command runs all the tools on all the source files every time that you select it, regardless of the dates of files.

The Output window appears, and results from the tools are displayed there. If you have an error in your code, the Output window displays an error message. While the Output window is active, you can place the insertion point in the error line, press F1 and get information about the error. If the error is a compiler error, you can also display the source file containing the error and highlight the specific line by double-clicking the error line in the Output window. These features help you correct mistaken language syntax, undeclared variables, misspelled keywords and the like.

Once you have corrected errors detected in the build process, you can then move on to correct any logic errors or behavioral anomalies by using the debugger.


Build Shortcuts
Shortcuts

Toolbar Shortcuts

To:	Click this Button
Compile the active source file
Build the project using dependency rules
Build the project from the start
Keyboard Shortcuts

To:	Press
Compile the active source file	CTRL+F8
Build the project using dependency rules	SHIFT+F8
Build the project from the start	ALT+F8


Tips and Troubleshooting

Disk Space Required

When building a program for Windows, the Resource Compiler requires free disk space equal to approximately twice the size of the compiled executable file.

Stopping a Build or Compile

You can press the CTRL+BREAK key combination to stop the current build or compile.

Selecting Options Strings

If you want to know what a given option in the options string is, or in which category to set or clear it, you can double-click the option in the options string with the mouse to select it and then press F1.

When Visual C++ builds your project, it uses options corresponding to the Build Mode selection on the Project Options dialog box. If you select the Debug build mode, Visual C++  uses the Debug options strings from the Compiler Options and Linker Options dialog boxes and the Debug defines from the Resource Compiler Options dialog box. If you select the Release build mode, Visual C++  uses the Release options strings from the Compiler Options and Linker Options dialog boxes and the Release defines from the Resource Compiler Options dialog box.

Using External Projects

If you are building an external project, you need to specify options to use for Debug and Release builds in the command line for the utility used to build the project. You can specify these options in the Debug Build and Release Build text boxes of the External Project Options dialog box. You can use Microsoft NMAKE as your build utility for external projects; the text boxes in the External Project Options dialog box contain default values for NMAKE.

The External Project Options dialog box does not recognize in its text boxes the predefined macros provided by Visual Workbench.

Using Precompiled Headers

If you use AppWizard to create a project for a Windows program, AppWizard sets up the project options to use a precompiled header by default.

The compiler ignores hdrstop pragmas in files from projects where you have selected precompiled headers rather used automatic precompiled headers.

Specifying Directories

To specify more than one directory for a category in the Directories dialog box under the Options menu, separate them with a semicolon (;).

When an #include directive is encountered in a program (and a complete path is not provided), the compiler searches for the file in this order:

1.	The current directory.

2.	The path or paths specified with the /I option, if you have set that option in the Compiler Options dialog box under Project on the Options menu.

3.	The paths specified in the Include Files path in the Directories dialog box.

The Browser and the debugger use the MFC Files path in the Directories dialog box to find MFC source files, if necessary.

Building DLLs

If you are building a dynamic-link library for Windows (DLL) which was compiled with the /O1 optimizing option, set the /OPT:NOREF option in the Other Options text box of the Miscellaneous category in the Linker Options dialog box to prevent removal of exported functions. The /O1 option implies the /Gy option, which creates packaged functions. You set the /O1 option in the Optimizations category of the C/C++ Compiler Options dialog box.


The Debugger

How Do I?	Brief	Click
Learn about the debugger	What you should know about the debugger
See a list of shortcuts	List of toolbar and keyboard shortcuts
Add or delete breakpoints	Setting or removing breakpoints
Set breakpoints for certain conditions	Setting breakpoints to break at location, break when an expression has changed, or break at an exported Windows function
Trace program execution	Stepping through a program by various means
Debug exceptions	Specifying debug actions for system and user-defined exceptions in your program
Debug threads	Choosing a single thread to debug in the Visual Workbench debugger
Locate errors	Viewing errors in the output window; moving to an error in a source file
Display the Watch window	Displaying variables and watch expressions
Open the Memory window	Displaying memory locations starting at a specified address
Format watch variables	Using formatting symbols to change the display format of variables in the Watch window
Display local or register variables	Using the Locals window to display values for all local variables for the currently active function
Toggle between hexadecimal and decimal	Viewing numbers in hexadecimal or decimal
View mixed source code	Viewing assembly-language code generated by your source
View nested sequence of function calls	Using Call Stack command to list function calls that led to current statement
View variables and expressions quickly	Using QuickWatch for exploratory debugging
Set Watch expressions	Adding or deleting expressions from the Watch window
Change the value of variables	Changing the value of a variable to see results in real time
Expand or collapse variables	Expanding or collapsing variables that contain more than one element, such as arrays, structures, classes, or enumerated types
Set debug options	Setting options that affect debugging
Interrupt the debugger	Interrupting the debugger when normal steps fail
Troubleshoot	Speeding up your work and clearing up problems


Displaying the Watch Window

You can use the Watch command on the Window menu to display the Watch window or to bring it to the foreground. The Watch window displays variables and watch expressions.

 To display a variable or watch expression in the Watch window:

1.	Choose Watch from the Window menu.

2.	Type the variable name or watch expression in the Watch window and press ENTER.

If the variable that you want to display is a structure of any type, it is marked with a plus symbol (+) in the the left margin of the window. You can expand the structure by double-clicking the variable. An expanded variable is marked with a minus symbol (-) in the left margin. You can collapse an expanded variable by double-clicking it.

The Watch window shows variables in their default format. However, you can display variables in different formats by inserting special symbols.

Tip  Use the QuickWatch command on the Debug menu to control the contents of the Watch window.

Shortcut: SHIFT+F9

Toolbar shortcut:

Displaying values in the Watch window requires that you build the program in Debug mode.

Although you can display the Watch window at any time, it is most useful for single-step debugging.

  For more information see Formatting Watch Variables


Formatting Watch Variables

You can use formatting symbols to change the display format of variables in the Watch window. The value initially displayed depends on the Hexadecimal Display check box in the Debug dialog box under the Options menu. To change the format, follow the variable name with a comma and a letter:

Symbol	Format	Value	Display
d,i	Signed decimal integer	0xF000F065	-268373915
u	Unsigned decimal integer	0x0065	101
o	Unsigned octal integer	0xF065	0170145
x,X	Hexadecimal integer	61541 (dec.)	0x0000F065
l,h	long or short prefix for: d, i, u, o, x, X
f	Signed floating-point	3./2.	1.500000
e	Signed scientific-notation	3./2.	1.500000e+000
g	Shorter of e and f	3./2.	1.5
c	Single character	0x0065	'e'
For instance, if the value of x is 0x0065, you can type x,c in the watch window and press Enter for the following result:

x,c = 'e'

You can display the contents of memory locations with the following formatting symbols:

Symbol	Format	Value	Display
ma	64 ASCII characters	esp	2657:304C .4...0...".0W&.......1W&.0.:W..1...."..1.JO&.1.2.."..1...0y....1
m[b]	16 bytes in hexadecimal, followed by 16 ASCII characters	esp	2657:304C B3 34 CB 00 84 30 94 80 FF 22 8A 30 57 26 00 00  .4...0...".0W&..
mw	8 words	esp	2657:304C 34B3 00CB 3084 8094 22FF 308A 2657 0000
md	4 double words	esp	2657:304C 00CB34B3 80943084 308A22FF 00002657
With the memory location formatting symbols, you can enter any value or expression that evaluates to a location.

To display the value of a character array as a string, precede the array name with an ampersand (&):

&yourname = 0x32E7:0x4706 "John Jacob Googleheimer Smith"

Also, a character from the list can follow an expression:

rep+1,x

alps[0],mb

xloc,g

count,d

To watch the value at an address or the value pointed to by a register, use the BY, WO, or DW operator. Follow the operator with a variable, register, or constant.

BY returns the contents of the byte pointed to.

WO returns the contents of the word pointed to.

DW returns the contents of the doubleword pointed to.

If the BY, WO, or DW is followed by a variable, then the environment watches the byte, word, or doubleword at the same address as the variable.

Note  With structures and arrays, you can use formatting symbols only on the unexpanded variables. Double-click in the result, displayed as {...}, to expand the variable.


Displaying Local or Register Variables

You can use the Locals command on the Window menu to display the Locals window or to bring it to the foreground. The Locals window displays values for all local variables for the currently active function.

 To display the local variables in the Locals window, choose Locals from the Window menu.

Tip  Displaying the values of local variables requires that you build the program in Debug mode.

You can examine the names and current values of the native CPU registers and flags in the Registers window. You can change the value of any register or flag directly in the Registers window while the program is being debugged.

 To display the Registers window, choose Registers from the Window menu.

 To change the value of any register in the Registers window:

1.	Use the TAB key or mouse to move the insertion point to the beginning of a register value.

2.	Enter the new value by typing over the current value.

The flag values displayed in the Registers window are:

Flag	Set Symbol	Clear Symbol
Overflow	O=1	O=0
Direction	D=1	D=0
Interrupt	I=1	I=0
Sign	S=1	S=0
Zero	Z=1	Z=0
Auxiliary carry	A=1	A=0
Parity	P=1	P=0
Carry	C=1	C=0
 To set or clear a flag in the Registers window:

1.	Use the TAB key or mouse to move the insertion point to the flag.

2.	Press the SPACEBAR to toggle the flag.

or

Double-click the flag to toggle it.


Toggling Hexadecimal and Decimal Display

The default format for displaying numbers is decimal. Memory locations are usually more useful when displayed in hexadecimal (base 16) format rather than decimal (base 10). The Hexadecimal Display option in the Debug dialog box toggles between decimal and hexadecimal display formats in the:

Watch window.

Locals window.

various dialog boxes.

 To change the display format between hexadecimal and decimal:

1.	From the Options menu, choose Debug.

2.	Select the Hexadecimal Display check box.

Shortcut:  ALT+F9

A check in the Hexadecimal Display check box indicates that the values are displayed in hexadecimal format. If Hexadecimal Display is cleared, the values are in decimal.


Viewing Mixed Source Code Display

While you are debugging, you can use the Mixed Source/Asm command to view the assembly language code generated by your source code. When you open a source window, each source code statement is immediately followed by the associated assembly language statements.

 To view mixed source code:

From the View menu, choose Mixed Source/Asm.

or

Press CTRL+F7.

Note  When you choose Mixed Source/Asm mode, all source windows are then displayed as read-only text. You must either switch out of this mode or terminate the debugging session if you want to edit your source code.

  More information on viewing mixed source code


Watch expressions
A watch expression can be any valid C or C++ expression. For example, the following are all valid watch expressions in C and C++:

count

count + 1

count + 1 == 5

For relational expressions, the Watch window shows 0 if the expression is false and 1 if the expression is true:

count + 1 == 5 = 0

count + 1 == 5 = 1


More Information on Viewing Mixed Source Code

This option sets the viewing mode for source code for the entire project. All source files which have associated object files are then displayed in this mode in the entire project. Visual Workbench retains this setting between debugging sessions. If you set it in one session and then leave the debugger to return later, source windows will again display mixed source and assembly language.

When you step through your source code using the Step Into command or the Step Into button on the toolbar, the debugger steps through single assembly-language statements.

You can specify the color for assembly-language statements with the Colors command on the Options menu.


Viewing Errors

The Output window shows a list of all errors that prevent a program from being built, including filename, line number, and error number. The Output window behaves like a source window, allowing you to copy and print information from the window. If displayed, the status bar gives a summary of the current error.

If you don't understand the error, move the insertion point to the error number and press F1 to display online information about it.

 To move through the list of errors:

From the View menu, choose Next Error to highlight the error following the current error.

Choose Previous Error to highlight the error preceding the current error.

or

In the Output window, double-click an error, or select an error and press ENTER.

As each error is highlighted in the Output window, the corresponding line containing the error is highlighted in the source window.

You can move to any line number in a source file.

 To move to a specific line:

1.	From the View menu, choose Line. The Line dialog box appears.

2.	In the Number box, type a line number.

3.	Choose OK.

If you enter a line number greater than the last line in your source file, the editor moves to the end of the file.


Using Call Stack

During a debug session, you can view all the functions that have been called but have not returned. The Call Stack command on the Debug menu displays a dialog box that lists the function calls that led to the current statement. Each call is shown with the arguments passed to it. The most recently executed function is listed first.

 To observe the behavior of a function call:

1.	Place the insertion point at the desired location in the function.

2.	From the Debug menu, choose the Step to Cursor command to execute your program to the location of the insertion point.

The Locals window is updated automatically to show the local variables for the function or procedure.

3.	From the Debug menu, choose Call Stack.

Shortcut:  CTRL+K

The calls are listed in the calling order, with the current function (the most deeply nested) at the top.

While the Call Stack dialog box is open, you can select any function name shown in the Calls list and click the GoTo button, or double-click the function name. The function's code will be displayed in the source window.


Using QuickWatch

You can use QuickWatch to view variables and expressions quickly. Unlike watch expressions, which are stored in the Watch window, the values of QuickWatch variables and expressions appear only in the QuickWatch dialog box. You can easily add them to the Watch window from the QuickWatch dialog box.

QuickWatch is useful in exploratory debugging where you are checking a number of variables that are suspect.

The QuickWatch dialog box is active only if your program is running.

 To view a variables value or an expressions result using QuickWatch:

1.	Place the insertion point on a variable or expression in your code.

2.	From the Debug menu, choose QuickWatch.

Shortcut: SHIFT+F9

Toolbar shortcut:

 To add a variable or expression to the Watch window from QuickWatch:

1.	Place the insertion point on a variable or expression in your code.

2.	From the Debug menu, choose QuickWatch.

Shortcut: SHIFT+F9

Toolbar shortcut:

3.	Choose Add to Watch Window.

The Watch window opens if not currently open.

Option

  Zoom


Watching Expressions

You can use the Watch window to display variables you want to view or expressions that you want to see evaluated as the program progresses. Values or expressions that you enter into the Watch window are evaluated only while the program is in a debug session. Otherwise, the Watch window displays an error until a debug session begins.

 To add a variable or expression to the Watch window:

1.	While the program is paused between steps or at a breakpoint, move the insertion point to the first blank line in the Watch window.

2.	Type the variable name or expression.

3.	Press ENTER.

The variable or expression is evaluated immediately. If the expression or variable cannot be evaluated, an error message will appear in the window next to it.

You can also copy and paste variable names from your program source files into the Watch window. You must always press ENTER after pasting to evaluate the variable or expression.

You can also use the QuickWatch dialog box to add variables to the Watch window.

Unlike the insertion of variables and expressions, you can delete a variable or expression either in or out of a debug session.

 To delete a variable or expression from the Watch window:

1.	 Move the insertion point to the line containing the variable or expression.

2.	Select the entire variable name or expression, or the current line or multiple lines, using either the mouse or the SHIFT and ARROW keys.

3.	Press DEL.


Modifying a Variable

While the program is paused at a breakpoint or between steps, you can change the value of any variable in your program. This gives you the flexibility to try out changes and see their results in real time or to recover from some logic error and continue. You can modify any variable in either the Watch window or the Locals window directly. You can also modify any variable in your program by using the QuickWatch dialog box.

 To modify the value of a Watch window or Locals window variable:

1.	In the Watch window or Locals window, select the variable value you want to modify and press DELETE.

or

Place the insertion point at the end of the variable value and use the BACKSPACE key to delete the value.

2.	Type the new value.

3.	Press ENTER.

You can also use the QuickWatch dialog box to modify a variable.

 To modify the value of a variable using the QuickWatch dialog box:

1.	Place the insertion point on a variable or expression in your code.

2.	From the Debug menu, choose QuickWatch. The QuickWatch dialog box appears with the variable or expression you want.

Shortcut: SHIFT+F9

Toolbar shortcut:

3.	Type a new value or expression in the New Value box.

4.	Choose Modify Value.

Tip  To change the value of a structure or array, modify the individual fields or elements. You cannot change an entire array or structure at once.


Expanding and Collapsing Variables

In the Watch window, the Locals window, and the QuickWatch dialog box, variables that contain more than one element [image] such as arrays, structures, classes or enumerated types [image] are displayed with either a + or - sign preceding them.

The + symbol indicates that the variable contains elements and can be expanded. The - symbol indicates that the variable is fully expanded and can be collapsed.

 To expand or collapse a variable:

1.	Move the insertion point to the line containing the variable.

2.	Press ENTER

or

Double-click anywhere on the variable.


Zoom Button
The Zoom button expands or contracts an array or structure so you can see all its elements. The button is unavailable if the currently selected item cannot be expanded.


Adding or Deleting Breakpoints

Breakpoints specify to the debugger where or when to break execution of a program, that is, stop the program temporarily. You can then examine the state of your program, examine or modify variables, examine the call stack, and so on. You can set multiple breakpoints in your program.

  More Information on Breakpoints

The Toggle Breakpoints button on the toolbar is the easiest way to set and clear breakpoints at locations in a program. The Breakpoints dialog box allows you set more complex breakpoints, such as conditional breakpoints.

Toolbar shortcut:

Shortcut:  F9

 To set a breakpoint using the toolbar:

1.	Move the insertion point to the line where you want the program to break.

2.	Click the Toggle Breakpoints button.

The line is highlighted, indicating that the breakpoint is set.

 To remove a breakpoint using the toolbar:

1.	 Move the insertion point to the line containing the breakpoint.

2.	 Click the Toggle Breakpoints button.

You can add or delete breakpoints with the Breakpoints command on the Debug menu. This displays the Breakpoints dialog box, which allows you to set all types of breakpoints.

 To add a breakpoint using the Breakpoints dialog box:

1.	From the Debug menu, choose Breakpoints.

Shortcut:  CTRL+B

2.	Set the conditions that will pause the program:

Break at location

Break at location if an expression is true

Break at a location if an expression has changed

Break when expression is true

Break when expression has changed

Break at WndProc if message is received

3.	Choose Add.

4.	Choose OK.

The Breakpoints box shows the currently active breakpoints.

 To remove a breakpoint:

1.	From the Debug menu, choose Breakpoints.

Shortcut:  CTRL+B

2.	In the Breakpoints box, select the breakpoint you want to remove.

3.	Choose Delete to remove the selected breakpoint. Or choose Clear All to remove all of the listed breakpoints.

4.	Choose OK.


Interrupting the Debugger

While your program is running in the debugger, you can usually set breakpoints in a source file to halt the program.

However, there may be other times when you cannot set a breakpoint to halt the program, such as when your program encounters an infinite loop. In such cases, you can interrupt your program by selecting Break on the Debug menu. This action returns control to the debugger.

Note  You should take care when interrupting execution. If you interrupt execution while Windows or other system code is executing, the results can be unpredictable.


Breakpoints
  Break at Location Procedures

  Break When Procedures

  Break at WndProc Procedures


   Break at Location Procedures

The Breakpoint dialog box default type is "Break at Location."

 To set a breakpoint at a location:

1.	Position the insertion point on a line in a source file.

2.	From the Debug menu, choose Breakpoints.

Shortcut:  CTRL+B

The line number for the line with the insertion point automatically appears in the Location box.

3.	Choose Add to add this location as a breakpoint.

4.	Choose OK.

The Breakpoints box shows the currently active breakpoints.

You can also enter a location directly into the Location box in the Breakpoints dialog box. You can enter a function name, a source or executable filename, or a line number. If you omit the line number, the first executable line in the source or executable file or function is assumed.

  More Information on Locations

Two of the breakpoint types evaluate whether an expression is true or has changed. When the expression evaluates correctly, the program pauses at the location specified.

You can also break at any location when an expression is true, or when an expression has changed.

 To break at a location when an expression is true, or when an expression has changed:

1.	Position the insertion point on a line in a source file.

2.	From the Debug menu, choose Breakpoints.

Shortcut:  CTRL+B

The line number for the line with the insertion point automatically appears in the Location box.

3.	In the Type box, choose Break at Location if Expression is True or Break at Location if Expression has Changed.

4.	Specify an expression in the Expression box.

  More Information on Expressions

5.	Enter the length of the expression in bytes in the Length box.

6.	Choose Add to add this location as a breakpoint.

7.	Choose OK.

The Breakpoints box shows the currently active breakpoints.

Tip  An error occurs when an expression contains an out-of-scope variable. To ensure that potentially out-of-scope variables are always in scope, use the context operator {fn, s, e}. (Click the button above labeled More Information on Locations for further information on the context operator.) Typically, just {fn} is enough to adequately scope the variable. Note that the context operator has the same precedence as the cast operator, and can therefore be used as follows: {fn1}(i+j) - {fn2}k.


   Break When Procedures

Two of the breakpoint types evaluate only whether an expression is true or has changed. When the expression evaluates correctly, the program pauses immediately.

To detect when an expression has changed, you must enter an expression that evaluates to a memory location (an L-value) in the Expression box when you set the breakpoint.

If you choose Break when an Expression has Changed, you may also need to edit the value in the Length box. The default length is 1, which indicates 1 times the size of the expression's type. If you are dereferencing a pointer, for instance, you must also enter the length of this memory location (in bytes) in the Length box. Otherwise the length refers to the length of the pointer.

 To break when an expression is true or when an expression has changed:

1.	From the Debug menu, choose Breakpoints.

Shortcut:  CTRL+B

2.	From the Type box, select Break when Expression is True or Break when Expression has Changed.

3.	Specify an expression in the Expression box.

  More Information on Expressions

If you chose Break when Expression has Changed, the expression must evaluate to a memory location.

4.	If you chose Break when Expression has Changed, and you are evaluating an expression which points to a memory location, you must also enter in the Length box the length in bytes of the memory location specified by the expression.

5.	Choose Add to add this location as a breakpoint.

6.	Choose OK.

The Breakpoints box shows the currently active breakpoints.

Tip  An error occurs when an expression contains an out-of-scope variable. To ensure that potentially out-of-scope variables are always in scope, use the context operator {fn, s, e}. (Click the More button above for further information on the context operator.) Typically, just {fn} is enough to adequately scope the variable. Note that the context operator has the same precedence as the cast operator, and can therefore be used as follows: {fn1}(i+j) - {fn2}k.


  Break at WndProc Procedures

The breakpoint type Break at WndProc if Message is Received lets you set a breakpoint that tests messages received by any exported Windows function. You can select whether to break on a specific message or on any message from a class of messages or from several classes of messages.

 To set a breakpoint on a message:

1.	From the Debug menu, choose Breakpoints.

Shortcut:  CTRL+B

2.	In the Type box, select Break at WndProc if Message is Received.

3.	In the WndProc box, enter the name of the Windows callback function that you want tested for messages.

If you are setting a breakpoint during a debug session, the list contains all of the exported functions in your project; otherwise it is blank.

4.	Click the Messages button to open the Messages dialog box.

5.	Under Message Type, select the Selection option button.

6.	In the Selection box, select the message.

7.	Choose OK to close the Messages dialog box.

8.	Choose Close to close the Breakpoint dialog box.

You can follow a similar procedure to set a breakpoint on one or more classes of messages.

 To set a breakpoint on any message in one more classes:

1.	From the Debug menu, choose Breakpoints.

Shortcut:  CTRL+B

2.	In the Type box, select Break at WndProc if Message is Received.

3.	In the WndProc box, enter the name of the exported Windows function.

4.	Choose the Messages button to open the Messages dialog box.

5.	Under Message Type, select Class.

6.	In the Class box, select one or more message classes.

7.	Choose OK to close the Messages dialog box.

8.	Choose Close to close the Breakpoint dialog box.

If you set a breakpoint using either of these two procedures, the program will pause execution at the program's main window procedure when a message matching the qualifications is received.

Note  If you are debugging a program which uses the Microsoft Foundation Class Library, setting a breakpoint on a message may trace into the Microsoft Foundation Class source code. The debugger then requires the path to the Microsoft Foundation Class source files in order to open the file containing the breakpoint. If you do not have the MFC Files Path set correctly in the Directories dialog (on the Options menu), the debugger prompts you for the path.


More Information on Locations

The following examples illustrate the syntax:

Format	Example	Description
.line number	.35	Sets a breakpoint at line 35 in the current source file
filename!.line number	MyApp.cpp!.35	Sets a breakpoint at line 35 in MYAPP.CPP
function name	CMyWindow::OnCall	Sets a breakpoint at the beginning of this function
These are specific examples of a more general syntax for locations.

General Syntax for Breakpoint Locations

The general syntax for breakpoint locations has the following form:

{fn,s,e}.line

or

{fn,s,e}label

where

{}	The context operator, with the context specified by the following three elements
fn	The name of a function
s	The name of a source file, with drive and path if necessary
e	The name of an executable file or DLL
line	A line number in a source file
label	A label in a function
If you use this form, you must also type the braces enclosing fn, s, and e forming the context operator. If you omit any of those elements, you must include the commas.

This general syntax form can be abbreviated, as shown in the shortened forms in the previous table.

You can also set breakpoints in the following forms:

Format	Example	Description
offset	0x1002A	Sets a breakpoint at the specified offset in memory
offset	EIP	Sets a breakpoint at the instruction pointer (EIP) offset in memory
These forms of breakpoints are most useful if you are viewing mixed source and assembly language code. Use the Mixed Source/Asm command on the View menu to display source code in this form.

Note  If you are not viewing mixed source and assembly language, the breakpoint is displayed on the source line that generates the assembly language statement.


More Information on Breakpoints

Breakpoints are useful when you have a general idea of where a bug occurs in a program. The debugger runs until it reaches the breakpoint, then stops. At this point you can step to the next line of code or trace through a function until you find the problem. While the program is paused at a breakpoint, you can also examine variable values using the QuickWatch dialog box or the Watch or Locals windows, or examine register values using the Registers window.

You can set and clear breakpoints using either the Breakpoint dialog box or the Toggle Breakpoints button on the toolbar.

Toolbar shortcut:

The Breakpoints dialog box keeps a list of all breakpoints assigned to your project. Breakpoints can be set in any of your project source files or in an executable file. To add a breakpoint, you first select the breakpoint type, fill in parameters if needed, and then choose the Add button. To remove a breakpoint, select it in the list and choose Delete. To make a breakpoint inactive, select it and choose Disable.

The Toggle Breakpoints button on the toolbar simply sets or clears a breakpoint at the insertion point. The breakpoint dialog box allows you to set more complex breakpoints, such as breaking if an expression is true or breaking on a window message.

You can set any of the following six different kinds of breakpoints:

Break at a location

Break at a location if an expression is true

Break at a location if the content of a memory location has changed

Break when an expression is true

Break when the content of a memory location has changed

Break at a windows procedure if a specified message is received

All breakpoints active when a project is closed are saved as part of the project information and become active when the project is reopened. A project is closed when you choose Close from the Project menu, when you open or create another project, or when you exit Visual Workbench.


More Information on Breakpoint Expressions

Breakpoint expressions can be any valid C or C++ expressions. They can also contain the BY, WO, or DW cast operators, which return the byte, word, or doubleword at the given address.

Constants are treated as decimal numbers unless they begin with a leading '0' (octal) or '0x' (hexadecimal).

The expressions listed below are all valid for breakpoints of type Break when Expression is True:

frame.size < 10

i == 100

i == 100 || j > 10

work.rate  *  hours  >= 1000

The expressions listed below are all valid for breakpoints of type Break when Expression changed:

*i

frame.size

next->node

You can also type a starting address, such as an offset or a register, in the Expressions box. In this case, you must also specify in the Length box the number of bytes to examine for changes.

If you want to watch the address contained in a pointer, rather than the memory location referenced by the pointer, you must give the pointer's address. In other words, for a pointer p, the expression p watches the contents of memory to which p points; the expression &p watches the value of p [image] the address to which p points.


Tracing Program Executions
  Executing to a Location

  Stepping Over or Out of Routines


  Executing to a Location

 To execute until a breakpoint is reached, choose Go from the Debug menu.

Shortcut:  F5

Toolbar shortcut:

 To execute to the cursor:

1.	Open a source file and move the insertion point to the location where you want the debugger to break.

2.	From the Debug menu, choose Step to Cursor.

Shortcut:  F7

You can step through your program one statement at a time, starting from a breakpoint, using the Step Into command or the Step Into button on the toolbar.

 To run the program and execute the next statement:

1.	Open a source file and set a breakpoint.

2.	 From the Debug menu, choose Go.

When the program comes to the breakpoint, the debugger pauses execution.

3.	From the Debug menu, choose Step Into.

Shortcut: F8

Toolbar shortcut:

Whether it is in the current function or in a call to another function, the debugger executes the next statement, then pauses execution.

4.	Repeat Step 3 to continue executing the program one statement at a time.


  Stepping Over or Out of Routines

You can step through your program one statement at a time in a chosen function, starting from a breakpoint by using the Step Over command or the Step Over button on the toolbar.

 To run the program and execute the next statement only in the current function:

1.	Open a source file and set a breakpoint.

2.	From the Debug menu, choose Go.

Shortcut:  F5

Toolbar shortcut:  .

When the program comes to the breakpoint, the debugger pauses execution.

3.	From the Debug menu, choose Step Over.

Shortcut:  F10

Toolbar shortcut:  .

The debugger executes the next statement. But if it contains a function call, it does not enter that function.

4.	Repeat Step 3 to continue executing the program a statement at a time.

You can stop the debugger after it has executed the return statement in a function. It stops on the line following the function call.

 To run the program and stop execution after the current function returns to the calling function:

1.	Open a source file and set a breakpoint in the function.

2.	 From the Debug menu, choose Go.

Shortcut:  F5

Toolbar shortcut:

When the program comes to the breakpoint, the debugger pauses execution.

3.	From the Debug menu, choose Step Out.

Shortcut:  SHIFT+F7

Toolbar shortcut:

The debugger continues execution until it has completed execution of the return from the current function, then pauses.


Debugging Exceptions

You can use the Exceptions dialog box, accessed from the Debug menu, to specify debug actions for system and user-defined exceptions in your program. Exceptions can occur inside or outside exception handlers (sections of code containing structured exception handling statements). The debugger is always called when an exception occurs.

Using the Exceptions dialog box, you can list each exception in your program that might occur and determine beforehand what actions the debugger will take when that exception occurs. The debugger can take one of two actions: Stop Always or Stop If Not Handled.

 More on Actions

By default, a list of system exceptions is provided in the Exceptions List of the Exceptions dialog box. You can modify this list, deleting system exceptions or adding your own exceptions. This information is saved in the project.vcw file (where project represents your project name) and persists with the project.

Each exception has a unique number. System exceptions are defined in WINBASE.H with the prefix of EXCEPTION (for example EXCEPTION_ACCESS_VIOLATION).

For any exception not in the exception list, the actions is Stop If Not Handled, which is also the default for all exceptions in the list.

 To add a new exception to the exception list:

1.	From the debug menu, choose Exceptions to open the Exceptions dialog box.

2.	In the Exception Number box, type the DWORD exception number for the user-defined exception.

3.	Optionally, type the name of the exception in the Name box.

4.	Optionally, select an action to apply to the exception from the Action options.

5.	Optionally, choose Add.

6.	Choose Close.

You can also easily change any parameter associated with an exception.

 To change an existing exception in the exception list:

1.	From the debug menu, choose Exceptions to open the Exceptions dialog box.

2.	Select the exception in the Exceptions List.

3.	Change any of the parameters, such as the action.

4.	Optionally, choose the Change button.

5.	Choose Close.

Or you can delete any exception from the Exception list.

 To delete an exception from the exception list:

1.	From the debug menu, choose Exceptions to open the Exceptions dialog box.

2.	Select the exception in the Exceptions List.

3.	Choose the Delete button.

When exceptions are deleted from the Exceptions list, their action reverts to Stop If Not Handled.

4.	Choose Close.

If you wish to restore system exceptions to the list, use the Default button.

 To restore all default system exceptions to the exceptions list:

1.	From the debug menu, choose Exceptions to open the Exceptions dialog box.

2.	Choose the Default button.

All default system exceptions are restored to the exceptions list without disturbing any of the user-defined exceptions that have been added.

3.	Choose Close.


More on Actions

The debugger takes one of its two actions when it is notified of an exception. The debugger may be notified one or two times when an exception is thrown. It is always notified the first time, before the program gets a chance to handle the exception. When the program continues, if the exception is not handled, the debugger is notified again. For each exception, you can choose whether to stop in the debugger at each of these notifications. The Action group in the Exceptions dialog box contains two options:

Stop Always

When the exception occurs, stop at the first-chance notification and at the last-chance notification, if there is one. When the debugger stops the first time, you have the opportunity to change some element in the program (the EIP register for instance) to fix the cause of the exception.

When you continue the program after a first-chance notification, a dialog box appears asking if you want to pass the exception on to the program being debugged. If you choose Yes, the programs exception handlers are invoked. Choosing No dismisses the exception and assumes that you fixed it in the debugger.

If the exception is not then properly handled (either by your debugger fix or by the programs exception handler), the debugger will stop again. If you continue the program at this point, the exception is dismissed, on the assumption that you fixed it in the debugger. If you didn't fix it in the debugger, it will occur again as another first-chance exception.

Stop If Not Handled

When the exception occurs, dont stop at the first-chance notification; instead pass the exception on to the program, send a notification line to the Output window, and stop only at last-chance notification. That is, if the programs exception handlers fail, then stop in the debugger. If you continue the program at this point, the exception is dismissed, on the assumption that you fixed it in the debugger. If you didn't fix it in the debugger, it will occur again as another first-chance exception.


Debugging Threads

Windows NT supports multiple threads of execution per application. If the application you are debugging has more than one thread, use the Threads dialog box, accessed from the Debug menu, to choose a single thread to debug in the Visual Workbench debugger.

The Threads dialog box displays a list of all threads that currently exist for the application. From this list you can :

Set focus on a thread (make it the active thread that the debugger will recognize) by selecting a single thread and choosing the Set Focus button.

Suspend a thread by selecting the thread and choosing the Suspend button.

Resume execution of a suspended thread by selecting the thread and choosing the Resume button.

Kill a threads execution by selecting the thread and choosing the Terminate button.

The Thread list in the Threads dialog box displays status information on each thread as follows:

Thread ID

This is the DWORD that uniquely identifies the thread. When you set focus on a thread, it is displayed in the Thread list with an asterisk next to its identifier.

Suspend Count

This can be a value from 0 to 127.

Priority

This can be one seven priorities:

Idle

Lowest

Below Normal

Normal

Above Normal

Highest

Time Critical

Current Location

This is the current address of the thread, displayed either as a function name or as an address, depending on the state of the Current Location Display option at the bottom of the dialog box. If Function Name is selected, the current function name is displayed if known by the debugger. If no function is known, the address is displayed. If Address is selected, the current address is always displayed.


Using the Memory Window

You can open the Memory window with the Memory command on the Window menu to display memory locations starting at a specified address (0x00010000 by default). You can scroll the memory window to view any memory locations in the programs available address space. Options in the Memory Window Options dialog box control the starting address, the display format, the number of values to display on each line, and other parameters.

Viewing Memory at a Dynamic Address

You can set a dynamic starting point for the memory window display by entering an expression in the Memory Window options dialog box. You specify these dynamic starting points with "live expressions."

  To create a live expression:

1.	From the Options menu, choose Memory Window.

The Memory Window Options dialog box opens.

2.	Type the address expression in the Address text box.

For example, to cause the Memory window to display memory contents starting at the address of a pointer variable *pPtr type *pPtr.

3.	Select the Re-evaluate Expressions Always checkbox.

It is usually more convenient to view an item in the Watch window than the Memory window. However, some items are more easily viewed using live expressions. For example, you can examine what is currently on top of the stack by entering ESP as the live expression. Or you could also specify a pointer variable as the address expression, then follow the pointer in the Memory window as it increments through an array.

Changing Memory Contents Directly

You can also change memory contents directly.

  To change the contents of a memory location:

1.	Move the insertion point to the desired memory address, either by using the mouse or by tabbing.

2.	Type the new memory contents over the existing contents.

The Memory window ignores any characters that are not compatible with the current display format.

Setting Memory Window Options

To change the format and starting location of data displayed in the Memory window, open the Memory Window Options dialog box by choosing Memory Window from the Options menu while the debugger is paused at a break or between tracing steps.


Debugging DLLs

There are two basic approaches that you can take to debugging a Dynamic Link Library (DLL). You can use either of the following two methods:

Open a project containing the program that calls the DLL and specify the DLL(s) that it calls.

This is the preferred method if you are developing both the program and the DLL. In this case, you can set breakpoints in either or both, in order to see the interactions between calling program and DLL, for instance.

Open a project containing the DLL and specify which program calls it.

You need to use this method if you are writing a DLL to run with an application for which you don't have the source code. This is the case if you are building a DLL to be called by Microsoft Excel, for instance.

 To debug a DLL using the project for the executable program:

1.	Open the project for the DLL and use the Debug build mode on the Project Options dialog box under the Options menu to build a version of the DLL with symbolic debugging information.

2.	Open the project for the executable program, and use the Debug build mode on the Project Options dialog box under the Options menu to build a version of the program with symbolic debugging information if you want to set breakpoints in the executable program as well as the DLL. Otherwise, use the Release build mode to build the program.

3.	From the Options menu, select Debug. The Debug dialog box appears.

4.	If the executable program requires any command-line arguments when it starts up, enter those arguments in the Program Arguments text box.

5.	Enter the name of the DLL (or DLLs) that you want to debug in the Additional DLLs text box.

6.	Click OK. The information is now stored with your project.

7.	Set breakpoints at the points where you want to determine the state of your DLL or executable. You can open a file for the DLL and set breakpoints in that file, even though it is not a part of the project for the executable.

8.	Start the debugger by selecting one of the commands from the Debug menu (Go, or one of the Step commands).

 To debug a DLL using the project for the DLL:

1.	If you are developing the executable program, open the project for the executable program and build it.

2.	Open the project for the DLL and use the Debug build mode on the Project Options dialog box under the Options menu to build a version of the DLL with symbolic debugging information..

3.	From the Options menu, select Debug. The Debug dialog box appears.

4.	Enter the name of the executable program which calls the DLL in your project in the Calling Program text box.

5.	Enter the name of any additional DLL (or DLLs) that you want to debug in the Additional DLLs text box.

6.	Click OK. The information is now stored with your project.

7.	Set breakpoints at the points in the source files for your DLL where you want to determine the state of your DLL.

8.	Start the debugger by selecting the Go command from the Debug menu.

Debugging a DLL Created with an External Project

If you are debugging a DLL created with an external project, which uses an external makefile, you need to specify additional information in the External Project Options dialog box.

 To debug a DLL created with an external project:

1.	From the Options menu, select Project. The External Project Options dialog box appears.

2.	In the Debug Target Name text name, enter the name of the DLL that your external makefile builds.

3.	In the Project Type group box, select Dynamic Linked Library.

4.	In the Build Mode group box, select Debug.

5.	 Click OK.

6.	 From the Project menu, select the Build or Rebuild All commands to build the DLL.

7.	 Follow the procedures above to debug the DLL.


Debug Options

You can use the Debug command on the Options menu to set options that affect debugging. The first text box in the Debug dialog box is labeled Program Arguments (for all project types except Windows DLLs [image] for Windows DLLs, the first text box is labeled Calling Program).

Program Arguments

You can type any additional command-line arguments that you want passed to the program when it starts. These arguments are used when the program is started with either the Go or the Restart command on the Debug menu.

Note  This text box does not appear for DLL project types.

Calling Program

When you are debugging a DLL, you must type the name of the program that calls the DLL.

Note  This text box appears only for DLL project types.

Additional DLLs

If you want to break in a DLL while you are debugging an executable program or if you want to break in a DLL other than the one you are debugging, you need to enter the name of the DLL in this box. This causes the debugger to load the symbolic information for that DLL.

Toggling Hexadecimal and Decimal Display

The default format for displaying numbers is decimal. Memory locations are usually more useful when displayed in hexadecimal (base 16) format rather than decimal (base 10). The Hexadecimal Display option in the Debug dialog box toggles between decimal and hexadecimal display formats in the:

Watch window

Locals window

Various dialog boxes

A check mark in the Hexadecimal Display check box indicates that the values are displayed in hexadecimal format. If the Hexadecimal Display check box is cleared, the values are in decimal.

Shortcut:  ALT+F9

Using a Single Edit Window for all Source Files

A check mark in the Single Edit Window for all Source Files check box causes the debugger to display each successive source file opened at a breakpoint to be displayed in a single edit window, replacing the previous source file. If the check box is cleared, the debugger opens each successive source file in its own edit window.


Debugger Basics

With the debugger, you can examine the state of an executable program for Windows or a dynamic-link library at any point as it runs.

After you have corrected errors that prevent you from building your program [image] mistaken language syntax, undeclared variables, misspelled keywords, and the like [image] you use the debugger to detect and correct logic errors and behavioral anomalies in your program.

The debugger allows you to control the execution of your program, and examine its state at various points in its execution. In the debugger, you can specify the conditions under which to stop the execution of your program. These conditions are known as breakpoints. You can set breakpoints with the Breakpoints command on the Debug menu. You can also toggle a breakpoint using the Breakpoint button on the toolbar.

 More on breakpoints

After setting breakpoints, you start execution of your program under the control of the debugger with the Go command on the Debug menu.

Alternatively, you can execute your program a statement at a time, or step through your program. If you choose to step through your program, you can either enter the code for the function when it is called in a statement, using the Step Into command on the Debug menu, or skip over the code for the function, using the Step Over command. You can similarly exit from a called function with the Step Out command, which returns you to the statement where the function was called.

You can also place the insertion point on a line in a source file, and select the Step to Cursor command on the Debug menu. This runs your program until it arrives at the line containing the insertion point.

When the program is stopped, you can use the Watch window on the Windows menu and the QuickWatch dialog box on the Debug menu to examine the values of variables, and change them for subsequent program execution. The Watch window also displays the values of selected variables at each breakpoint.

Other windows on the Window menu also display aspects of the program's state when it is paused. The Registers window displays the values of the registers in the CPU at the breakpoint. The Locals window displays the value of variables local to the current function. This window is updated every time the scope of variables in the program changes.

To see a list of all the nested functions that have called the current function, you can use the Call Stack command on the Debug menu. In the Call Stack dialog box, the Calls list box displays the functions, with the current function (the most deeply nested) at the top of the list, and less deeply nested functions further down the list. You can double-click a function in the list to display the source code associated with that function.

When you stop debugging, either by exiting the program or by selecting the Stop Debugging command, the project retains any breakpoints that you have set. If you close the project, it stores the breakpoints, and restores them when you open the project again. Your debugging can thus span sessions.

Viewing Mixed Source Code

The View Mixed Source/Asm command on the View menu sets the viewing mode for source code for the entire project. All source files which have associated object files are then displayed in this mode in the entire project. Visual Workbench retains this setting between debugging sessions. If you set it in one session and then leave the debugger to return later, source windows will again display mixed source and assembly language.

When you step through your source code using the Step Into command or the Step Into button on the toolbar, the debugger steps through single assembly-language statements.

You can specify the color for assembly-language statements with the Color command from the Options menu.

Debugging a DLL

There are two ways that you can debug a dynamic-link library (DLL):

If you are writing both the DLL and the executable file which calls the DLL, you can open the project which builds the executable file. Then, in the Debug dialog box under the Options menu, you specify any arguments required by the executable program, and any DLLs that it calls. You need to specify only the DLLs in which you want to set breakpoints.

If you use this method, you must build both the executable program and the DLL.

If you are writing only the DLL, open the project which builds the DLL. Then, in the Debug dialog box under the Options menu, you specify the executable program which calls the DLL, and any additional DLLs that it calls. You need to specify only the DLLs in which you want to set breakpoints.

This is the method to use if you are writing a DLL that Microsoft Excel, for instance, is going to call.

Debugging Information

By default, the compiler uses the /Zi option for debug builds to create and store symbolic information for the debugger. This information is stored in a program database file named project.PDB. All object files refer to this file for symbolic debugging information. This makes object files smaller, and ensures that debugging information is correct when using precompiled headers.

 See debug options

Interrupting the Debugger

While your program is running in the debugger, you can usually set breakpoints in a source file to halt the program.

However, there may be other times when you cannot set a breakpoint to halt the program, such as when your program encounters an infinite loop. In such cases, you can interrupt your program by selecting Break on the Debug menu. This action returns control to the debugger.

Note  You should take care when interrupting execution. If you interrupt execution while Windows or other system code is executing the results can be unpredictable.


Debugging Shortcut
Debugging Shortcuts

Toolbar Shortcuts

To:	Click:
Set or clear a breakpoint
Start or continue a program using the debugger
Single-step through every line of the program
Single-step through program but skip functions
Run to first instruction after call to current function
Open QuickWatch to view the value of a variable
Keyboard Shortcuts

To:	Press:
Start program execution from beginning	SHIFT+F5
Quit a debugging session	ALT+F5
Start or continue a program using the debugger	F5
Run to the location of the insertion point	F7
Single step through every line of the program	F8
Single-step through program but skip functions	F10
Run to first instruction after current function	SHIFT+F7
Toggle breakpoints	F9
Toggle hex mode	ALT+F9
Toggle mixed mode	CTRL+F7
Open the Breakpoints dialog box	CTRL+B
Open Quickwatch to view the value of a variable	SHIFT+F9
Open the Call Stack dialog box	CTRL+K


More on Breakpoints

Breakpoints are useful when you have a general idea of where a bug occurs in a program. The debugger runs until it reaches the breakpoint, and then stops. At this point you can step to the next line of code or trace through a function until you find the problem. While the program is paused at a breakpoint, you can also examine variable values using the QuickWatch dialog box or the Watch or Locals windows, or examine register values using the Registers window.

You can set and clear breakpoints using either the Breakpoint dialog box or the Toggle Breakpoints button on the toolbar.

Toolbar shortcut:

Shortcut:  F9

The Breakpoints dialog box keeps a list of all breakpoints assigned to your project. Breakpoints can be set in any of your project source files or in an executable file. To add a breakpoint, you first select the breakpoint type, fill in parameters if needed, and then choose the Add button. To remove a breakpoint, select it in the list and choose Delete. To make a breakpoint inactive, select it and choose Disable.

The Toggle Breakpoints button on the toolbar simply sets or clears a breakpoint at the insertion point. The breakpoint dialog box allows you to set more complex breakpoints, such as breaking if an expression is true or breaking on a window message.

You can set any of the following six different kinds of breakpoints:

Break at a location

Break at a location if an expression is true

Break at a location if the content of a memory location has changed

Break when an expression is true

Break when the content of a memory location has changed

Break at a windows procedure if a specified message is received

All breakpoints active when a project is closed are saved as part of the project information and become active when the project is reopened. A project is closed when you choose Close from the Project menu, when you open or create another project, or when you exit Visual Workbench.

Breakpoint Locations

The following examples illustrate the syntax:

Format	Example	Description
.line number	.35	Sets a breakpoint at line 35 in the current source file
filename!.line number	MyApp.cpp!.35	Sets a breakpoint at line 35 in MYAPP.CPP
function name	CMyWindow::OnCall	Sets a breakpoint at the beginning of this function
These are specific examples of a more general syntax for locations.

General Syntax for Breakpoint Locations

The general syntax for breakpoint locations has the following form:

{fn,s,e}.line

or

{fn,s,e}label

where

{}	The context operator, with the context specified by the following three elements
fn	The name of a function
s	The name of a source file, with drive and path if necessary
e	The name of an executable file or DLL
line	A line number in a source file
label	A label in a function
If you use this form, you must also type the braces enclosing fn, s, and e forming the context operator. If you omit any of those elements, you must include the commas.

This general syntax form can be abbreviated, as shown in the shortened forms in the previous table.

You can also set breakpoints in the following forms:

Format	Example	Description
offset	0x1002A	Sets a breakpoint at the specified offset in memory
offset	EIP	Sets a breakpoint at the instruction pointer (EIP) offset in memory
These forms of breakpoints are most useful if you are viewing mixed source and assembly language code. Use the Mixed Source/Asm command on the View menu to display source code in this form.

Note  If you are not viewing mixed source and assembly language, the breakpoint is displayed on the source line that generates the assembly language statement.

Breakpoint Expressions

Breakpoint expressions can be any valid C or C++ expressions. They can also contain the BY, WO, or DW cast operators, which return the byte, word, or doubleword at the given address.

Constants are treated as decimal numbers unless they begin with a leading '0' (octal) or '0x' (hexadecimal).

The expressions listed below are all valid for breakpoints of type Break when Expression is True:

frame.size < 10

i == 100

i == 100 || j > 10

work.rate  *  hours  >= 1000

The expressions listed below are all valid for breakpoints of type Break when Expression changed:

i

frame.size

next->node


Tips and Troubleshooting

Interrupting the Debugger

You can interrupt the program running in the debugger by selecting Break on the Debug menu. This may be necessary if the program enters an infinite loop, for instance, and you cannot set a breakpoint to stop it.

Setting Breakpoints

You can set breakpoints at a location quickly by moving the insertion point to a line in your source file and then clicking the Breakpoint button on the toolbar or by pressing F9.

When you close a project session, the currently active breakpoints are saved with the project. When you open the project again, those saved breakpoints are set. You can then resume debugging where you left off.

Breakpoints are indicated in your source files by the background color that is selected in the Color dialog box under the Options menu.

Examining Values

While debugging, press SHIFT+F9 to display the QuickWatch dialog box.

To set the value of a variable, you must have the debugger running. You can then either  display the QuickWatch dialog box and enter the new value for the variable.

Values or expressions that you enter into the Watch window are evaluated only while the program is in a debug session. Otherwise, the Watch window displays an error until a debug session begins.

Viewing Mixed Source and Assembly Language

When you choose Mixed Source/Asm mode on the View menu, all source windows are then displayed as read-only text. You must either switch out of this mode or terminate the debugging session if you want to edit your source code.

Locating Microsoft Foundation Class Library Source Files

If you are debugging a program which uses the Microsoft Foundation Class Library, setting a breakpoint on a message may trace into the Microsoft Foundation Class source code. The debugger then requires the path to the Microsoft Foundation Class source files in order to open the file containing the breakpoint. If you do not have the MFC Files Path set correctly in the Directories dialog (on the Options menu), the debugger prompts you for the path.


The Browser

How Do I?	Brief	Click
Learn about the browser	What you should know about the browser
See a list of browser shortcuts	List of shortcut keys for the browser
Create a browser Database	Creating a browser database  (PROJECTNAME.BSC) when building a project
Open a browser database	Opening the browser window to load the current browser database or loading a database not associated with the current project
Query a browser database	Searching for and viewing various relationships in a browser database
Browse classes	Viewing class hierarchical relationships
Browse function relationships	Graphically displaying relationships between calling and called functions
Browse definitions and references	Using the browser to find a definition of a function, then find where the definition is referenced
Expand and collapse graphics	Collapsing or expanding nodes in a class or function graph to hide or show subordinate nodes
Troubleshoot	Speeding up your work and clearing up problems


Browser Basics

Part of the process of program development involves understanding relations between program elements, such as between base classes and derived classes or between called and calling functions. It is also important to be able to move quickly between related program elements that may be located in several different files.

The browser uses information generated by the compiler to help you find related symbols and display symbol relationships. The generated database contains information about where each symbol is defined and used and about the relationships among modules, constants, macros, variables, functions, and classes.

Note  The Browser Information compiler option is enabled by default. Because creating a browser database slows down the build [image] and browser database files can be very large [image] you may want to use the Compiler Options dialog box to disable the creation of a browser database, for release builds, for instance.

The Browser represents the relations between base and derived C++ classes and between called and calling functions as graphical trees. The nodes of the tree represent either classes or functions. If a node contains further branches, you can expand it to get a detailed view of the relationships. You can also collapse a node to hide its branches and get an overview of relationships.

If you edit your source code after building a browser database, references to symbols and definitions of symbols in the browser database no longer correspond to their locations in the source code, or they may be deleted entirely. Going to references and definitions from the Browser window or from the Browse menu may then take you to an erroneous location (although it may be close) or fail altogether. In this case, you should build the project again in order to create a current browser database.


Browser Shortcuts

To:	Press
Expand node one level	ENTER, ALT+N, numpadENTER, SHIFT+PLUS SIGN, or numpadPLUS SIGN
Collapse node completely	ENTER, ALT+N, MINUS SIGN, numpadENTER, or numpadMINUS SIGN
Expand all nodes in a branch	SHIFT+8 or numpadASTERISK
Expand an entire graph	ALT+X
Jump to definition for selected symbol in source file or Find button text box	F11
Jump to first reference for selected symbol in source file or in Find button text box	SHIFT+F11
Jump to next reference in browser list	CTRL+numpadPLUS SIGN
Jump to previous reference in browser list	CTRL+numpadMINUS SIGN
Pop context	CTRL+numpadASTERISK


Preparing a Browser Database
  Creating a Browser Database

  Loading a Browser Database


  Creating a Browser Database

To use the browser, you must first create a browser database. Visual Workbench does this for you automatically as part of the normal build process when the Browser Information check box in the C/C++ Compiler Options dialog box is enabled.

Note that the Browser Information compiler option is enabled by default for all project types. Since generating a browser database slows down the build and browser database files can be very large, you may want to turn off Browser Information when you do not specifically want to build a browser database.

The following procedure assumes that you have a project loaded in Visual Workbench. You may want to use the SCRIBBLE sample project located in the \MSVCNT\MFC\SAMPLES\SCRIBBLE directory as an example to experiment with the browsers capabilities.

 To create a browser database (.BSC) file:

1.	From the Options menu, choose Project.

The Project Options dialog box appears.

2.	Under Customize Build Options, choose Compiler.

The C/C++ Compiler Options dialog box appears.

3.	In the Category box, select Listing Files.

This opens the Category Settings: Listing Files group in the lower right-hand corner of the dialog box, which contains the Browser Information categories (see Figure ??.1).

4.	Select the Browser Information check box to enable it, if it isnt already enabled.

Include Local Variables should be checked and Dont Pack Information should be cleared (not checked).

5.	Choose OK in the C/C++ Compiler Options dialog box.

6.	Choose OK in the Project Options dialog box.

7.	Click the Rebuild button on the toolbar or choose Rebuild All Targetname from the Project menu.

Shortcut: ALT+F8

Toolbar shortcut:

During the build, Visual Workbench creates a browser database file with the name of your project and the extension .BSC in your project directory.


Loading a Browser Database
  Opening a Browser Database

You can open a browser database by four methods:

Choosing the Open command on the Browse menu

Choosing the Open command on the File menu

Choosing the Next Definition or Next Reference command on the Browse menu

Dragging a browser database file (.BSC) from the Windows File Manager and dropping it into Visual Workbench

Choosing the Open command on the Browse menu

This method opens the Browse window. The Open command is normally followed by a browser database filename, which is usually the name of the current project plus a .BSC extension. However, if you have opened a browser database using the Open File dialog box, the name of the most recently opened database appears after the Open command.

The Open command on the Browse menu appears with no name following it if (1) there isnt an active project or if (2) there currently isn't a browser database open. In this case, choosing the Open command opens the Open File dialog box with a file filter of *.BSC.

  To open the Browse window for the current project:

From the Browse menu, choose Open Project.BSC (where Project is the name of the current project).

If you have created a browser database for the current project, the Browse window appears. Otherwise, a message appears, indicating that the browser database file cannot be opened.

Choosing the Open command on the File menu

This method opens any existing browser database by using the Open File dialog box. This can be a browser database generated by Visual Workbench or by Microsoft Programmers WorkBench.

  To open a browser database using the Open File dialog box:

1.	From the File menu, choose Open.

The Open File dialog box appears.

Shortcut: CTRL+O

Toolbar shortcut:

2.	From the drop-down list in the List Files of Type box, select Browse Database (*.bsc).

3.	Use the Directories and Drive list boxes to locate the directory that contains the browser database.

The browser file appears in the file list.

4.	Double-click the browser database filename.

The Browse window appears.

The filename of the currently open database appears on the Browse menu following the Open command. When you close the Browse window, the Browse menus Open command continues to display the name of the most recently used database.

Choosing the Next Definition or Next Reference command on the Browse menu

The this method uses the Browse menus Go to Definition or Go to Reference command when a browser database is associated (named on the Browse menu) but not open.

  To open a browser database and jump to the first definition or reference:

1.	Select a symbol name in a source file (or place the insertion point at the beginning of a symbol name).

Note that the browser database filename associated with the source file must appear on the Browse menu after the Open command.

2.	Choose Go to Definition to jump to the first definition, or Go to Reference to jump to the first reference of the symbol.

Go to Definition Shortcut:  F11

Go to Reference Shortcut:  SHIFT+F11

The database named in the Browse menus Open command is opened, the Browse window is minimized, and the source file containing the first definition (or first reference if you chose Go to Reference) appears with the insertion point at that definition or reference.

.

Dragging a .BSC File from File Manager and Dropping It into Visual Workbench

You can use the Windows File Manager to display a file icon and drag and drop the file icon into Visual Workbench. When the file is a browser database file (with an extension of .BSC), the Browse window opens with the browser database.


Querying the Browser Database

You can search for information in the browser database in several ways, depending on what relationships you want to view and what type of program elements (symbols) you are browsing.

 To query the database:

1.	Select a query type from the Types list.

Query types include:

  Definitions and References

  Call Graph

  Caller Graph

  Derived Class Graph

  Base Class Graph

2.	If you choose Definitions and References, click the list under Subset to specify which subset of symbols you want to consider. Alternatively, you can accept the default value ALL to browse all symbols.

3.	Type a symbol name in the Symbol box, or click the arrow to display a list of the most recently used symbols.

You can accept the default *, for all symbols, you can enter a specific symbol name, or you can use a partial symbol name followed by * to view symbols with similar or related names. This list is filtered by the subset type that you specify in the Subset box.

4.	Choose the Display Result button to begin the query.


Browsing Classes

You can view class hierarchical relationships by selecting a class name and either viewing a tree of all classes derived from the class (Derived Class Graph) or a tree of all the classes from which it is derived (Base Class Graph). Each node of the tree represents a class.

Once a class graph is displayed, you can view information about each class in the two window partitions to the right of the graph. When you select any class in the graph, all member functions and variables are displayed in the top right pane. The location where it is defined and all locations where it is referenced are displayed in the bottom right pane.

 To display a tree of all classes that are derived from a class:

1.	In the Type box, select Derived Class Graph.

Notice that Classes appears automatically in the Subset box.

2.	In the Symbol box, type the class name, or click the arrow to display a list of the most recently used symbols. You can use * to match partial or multiple names. For example, select CObject.

3.	Choose the Display Result button.

If you type a * in the Symbol box, a dialog box appears. Choose the class that you want to see from the list of classes displayed.

The CObject derived class graph is displayed in the Browse window.

 To view the inheritance path of a particular class, select the Base Class Graph query type.

This graph will be a chain of single nodes unless the class uses multiple inheritance, in which case the multiple base classes will appear as multiple branches. The derived class appears at the top left of the graph, and the ultimate base class appears at the bottom right of the graph. Depending on the size of the pane displaying the graph and the depth of the graph, you may have to expand the graph with Shift+8 to see all the nodes.

 To display a graph of base classes from which a class is derived:

1.	In the Type box, select Base Class Graph.

2.	In the Symbol box, type the class name, or click the arrow to display a list of the most recently used symbols. You can use * to match partial or multiple names. For example, select CObject.

3.	Choose the Display Result button.

The base class graph appears in the Browse window.


Browsing Function Relationships

You can use the Browser to graphically display relationships between calling and called functions by selecting the Caller Graph or Call Graph query types. These graphs are typically tree structures, where each node represents a function. If a node represents a recursive function, it is followed by an ellipsis (...).

 To display a tree of all functions that are called by a function:

1.	In the Type list, select Call Graph.

The Subset box displays Functions.

2.	In the Symbols box, type the function name, or click the arrow to display a list of the most recently used symbols. You can use * to match partial or multiple names.

Note  If you type the name of a function with more than one definition (such as a C++ class constructor), a dialog box appears to let you choose the function from a list box. For example, if you type the function name CObject::CObject, a dialog box appears to let you choose from the two CObject constructors.

3.	Choose Display Result or press ENTER.

The call tree of the selected function is displayed.

 To display a graph of all functions that call a function:

1.	In the Type list, select Caller Graph.

The Subset box displays Functions.

2.	In the Symbols box, type the function name, or click the arrow to display a list of the most recently used symbols. You can use * to match partial or multiple names.

Note  If you type the name of a function with more than one definition (such as a C++ class constructor), a dialog box appears to let you choose the function from a list box. For example, if you type the function name CObject::CObject, a dialog box appears to let you choose from the two CObject constructors.

3.	Choose the Display Result button.

The caller tree of the selected function is displayed in the leftmost pane, and a list of definitions and references in the rightmost pane.


Expanding and Collapsing Graphs

A node in a class graph or a function graph can be collapsed or expanded to hide or show subordinate nodes. An icon of an empty file box indicates that a node has either been expanded or has no subordinate nodes.

An icon of a file box containing files indicates that a node has subordinate nodes but is collapsed.

You can expand a graph one level at a time, or all at once, using the mouse or various keyboard shortcuts. The active node refers to the selected symbol in the graph.

 To display different levels of the graph:

Double-click on a node, or select the node and press ENTER or ALT+N to expand or collapse the node.

Select the node and press ENTER on the numeric keypad or click the Expand/Collapse Node button to expand or collapse the node.

Select the node and press SHIFT+= (the plus sign) or + on the numeric keypad to expand the node one level. Similarly, select the node and press - (the minus sign) or - on the numeric keypad to collapse the node.

Press * (SHIFT+8) or * on the numeric keypad to fully expand the active branch.

Press ALT+X or click the Expand Tree button to expand the entire graph.


Browing Definitions and References
Browsing Definitions and References

You can use the Browser to move quickly between files and to access common program elements. For example, you may wish to examine or change a definition of a function, but are not sure where the function is defined. Or, after changing a function's definition, you may want to find every place where it is referenced.

When you display a symbol, references and definitions are automatically displayed for the active node in the rightmost pane. For references and definitions of all types of symbols, use the following procedure.

 To display a list of locations where a symbol is defined or referenced:

1.	In the Type list, select Definitions and References.

2.	In the Subset list, select the type of symbol that interests you, or accept ALL for all symbol types.

3.	In the Symbol box, type the symbol name, or click the arrow to display a list of the most recently used symbols. You can use * to match partial or multiple names. If the symbol is a class name, you can follow it with a double colon to display all the members of the class.

4.	Choose the Display Result button.

5.	If the query displays multiple symbols, select the symbol in the leftmost pane that interests you.

A list of files and line numbers containing the definition of the symbol is displayed in the rightmost pane, followed by a list of files and line numbers containing references to the symbol.

6.	To open the source file containing the definition or reference and go to the specified definition or reference line, double-click the corresponding definition or reference in the list in the rightmost pane, or select the entry and press ENTER.

or

Select the symbol in the leftmost pane, and choose Go to Definition or Go to Reference from the Browse menu.

If the source file is already open, it becomes the active window. If it is not open, it is opened and displayed in the active window. The definition or reference is selected.

You can also go to references and definitions from a source file. Use the following procedure for access from source files.

 To go to a reference or definition from a source file:

1.	Open the source file containing the desired symbol.

2.	Select the desired symbol.

3.	From the Browse menu, select Go to Definition or Go to Reference.

If the source file is already open, it becomes the active window. If it is not open, it is opened and displayed in the active window. The definition or reference is selected.

Shortcut for Go to Definition: F11

Shortcut for Go to Reference: SHIFT+F11

4.	You can then select the Next or Previous command from the Browse menu to go to the next definition or reference, or to the previous definition or reference.

Shortcut for Next: CTRL+numpadPLUS SIGN

Shortcut for Previous: CTRL+numpadMINUS SIGN

You can also use the Pop Context command on the Browse menu return to a previous definition or reference in a source file. Each time you select Pop Context, it returns to the previous selection that you made. Continued selections return to previous selections that you made, in the order that you made them, until you reach your first selection.

Shortcut: CTRL+numpadASTERISK


A Derived Class Graph branches from left to right with the Base Class on the left and derived classes expanding to the right.


A Base Class Graph branches from left to right with the Derived Class on the left and the class or classes from which it is derived expanding to the right.


In a Call Graph, a node on the left represents a function that calls all functions labeled in nodes to its right.


A Caller Graph places a node on the left representing a function that is called by all the functions labeled in nodes to its right.


The Browser displays locations of symbol definitions and references. They are displayed automatically when you select any symbol. To see where any class or function in a graphical tree is defined and a list of all locations where it is referenced, simply click the node. The definitions and references appear to the right of the graph.

You can double-click any reference or definition to open the corresponding source file with the insertion point on the corresponding line.

You can also specifically request a query type of references or definitions. This has the advantange that you can apply the search to all types of symbols, including variables, types, macros and labels as well as classes and functions.


Browser Tips and Troubleshooting
Tips and Troubleshooting

Manipulating the Browser Window

You can double-click selected nodes in graphs to expand and collapse them.

You can resize the panes in the window by moving the mouse pointer between the panes, and dragging the pane border in the desired direction.

Speeding Up Builds

The Browser Information compiler option is enabled by default. Because creating a browser database slows down the build [image] and browser database files can be very large [image] you may want to use the Compiler Options dialog box to disable the creation of a browser database, for release builds, for instance.

Creating Correct References

If you edit your source code after building a browser database, references to symbols and definitions of symbols in the browser database no longer correspond to their locations in the source code, or they may be deleted entirely. Going to references and definitions from the Browser window may then take you to an erroneous location (although it may be close) or fail altogether. In this case, you should build the project again in order to create a current browser database.

Specifying Directories

The Browser uses the MFC Files path in the Directories dialog box to find MFC source files, if necessary.


Profiling You Application
Using the Profiler

You can use the Profiler to examine the behavior of an application when it runs. You can determine:

The parts of code your application executes

The parts of code your application never executes

The absolute amount of time your application spends executing any part of the code

The relative amount of time your application spends executing any part of the code

This information can help you (1) determine where to optimize the performance of your code and (2) determine what performance your application gained after the optimizations.

 To profile an application:

1.	Open the project for the application.

If you want to examine the line coverage, build the application using the Debug build mode.

2.	From the Debug menu, select Profile.

The Profiler dialog box appears.

3.	From the Options buttons, select the type of profile that you would like to examine:

Function Timing lists the amount of time spent in each function

Function Sampling lists the relative amounts of time spent in each function

Function Coverage indicates which functions were executed or unexecuted

Line Coverage indicates which lines were executed or unexecuted

Merge incorporates the output from the current run into previous runs of the Profiler

Custom allows you to select a Profiler command file, then run it

4.	If you want to focus your profile more closely, enter options to PREP.EXE in the Advanced Profiler Options text box.

  More information on advanced Profiler options

5.	Click OK. The profile information is displayed in the Output window.

For timing, times are indicated in milliseconds. For sampling, relative times are indicated in percent. For coverage, executed lines or functions are marked with an asterisk; unexecuted lines or functions are marked with a dot.


More on Advanced Profiler Options
More Information on Advanced Profiler Options

You can include the following options to PREP.EXE in the Advanced Profiler Options text box:

Option	Description
/EXC	Excludes a specified module from the profile.
/EXCALL	Excludes all modules from the profile.
/FC	Selects function count profiling.
/FS	Selects function sampling profiling.
/FT	Selects function timing profiling. This option causes the profiler to generate count information as well.
/FV	Selects function coverage profiling.
/INC	Includes in profile.
/H[[ELP]]	Provide a short summary of PREP options.
/IO filename	Merges an existing .PBO file. Up to eight .PBO files can be merged at a time. The default extension is .PBO.
/IT filename	Merges an existing .PBT file. Up to eight .PBT files can be merged at a time. You cannot merge .PBT files from different profiling methods. The default extension is .PBT.
/LC	Selects line count profiling.
/LV	Selects line coverage profiling.
/M filename	Substitutes for /IT, /IO, and /OT options.
/NOLOGO	Suppresses the PREP copyright message.
/OI filename	Creates a .PBI file. The default extension is .PBI.  If /OT is not specified, the output .PBI file is  programname1.PBI
/OM filename	Creates a self-profiling .EXE file for function timing, function counting, and function coverage. Without this option, the executable code is stored in the .PBI file.
/OT filename	Specifies the output .PBT file. The default extension is .PBT.  If /OT is not specified, the output .PBT file is  programname1.PBT
/SF function	Starts profiling with function. Function name must correspond to an entry in the .MAP file.
/?	Provides a short summary of PREP options.
The /INC and /EXC options specify individual .LIB, .OBJ and .C (.CPP or .CXX) files. /EXCALL excludes all modules. For line coverage, you can specify line numbers with source files as shown below:

/INC test.cpp(3-41,50-67)

Here we are including lines 3-41 and lines 50-67 from the source file TEST.CPP. Note the absence of spaces in the source specification.

The most useful options to use from the Profiler dialog box are /SF with function timing and coverage, and EXCALL to exclude all modules followed by one or more INC options to include the modules of interest.

For further information on profiling options, see the 32-Bit Source Profiler User's Guide.


Wizards

How Do I?	Brief	Click
Learn about Wizards	What you should know about Wizards
Generate starter files to create an application	Using AppWizard to create a suite of files for a Windows-based application with the Microsoft Foundation Class Library; selecting options
Add menus to starter files	Adding resources such as menus to applications created with AppWizard
Add dialogs to starter files	Adding dialogs and other resources to applications created with AppWizards and the Microsoft Foundation Class Library
Modify code and resources	Using ClassWizard to connect visual objects to commands and message-handler functions
Modify function templates (event handling routines)	Use ClassWizard to edit the function template that invokes the dialog
Connect visual objects with messages	Use ClassWizard to "bind" views, dialogs, controls, and commands with messages and handler functions
Troubleshoot	Speeding up your work and clearing up problems


Wizard Basics

AppWizard and ClassWizard, along with App Studio, are tools that help you build applications for Windows NT using the Microsoft Foundation Class Library.

AppWizard Creates Skeleton Code

AppWizard automatically creates the starter files for a new application. The starter files consist of C++ source files, resource files, header files, and a project file. They incude the code necessary to implement basic features for applications for Windows NT. These basic features include such things as window management, a basic menu structure, and basic menu commands. They also include skeleton code for features that you need to implement for your specific application.

In the course of developing your application, you add the code required to flesh out the skeleton fully. For instance, you need to add code that loads a file for your application properly, or saves a document in the appropriate file format on disk. AppWizard marks these locations in the source files that it creates.

ClassWizard Fills Out Implemention Details

ClassWizard allows you to create new classes or member functions and variables to implement the details of your application's operation. It also works with App Studio to implement user-interface objects, such as dialog boxes, in your application. You use App Studio, which is a graphical resource editor, to create these user-interface objects. You then use ClassWizard to generate functions and message-maps for each user-interface object.

You may create an edit box in a dialog box in App Studio, for instance. Later, in ClassWizard, you can create a class member function to handle input to the edit box and the member variables to validate and store the entered information. You can also use ClassWizard to connect a menu command or a toolbar button to the dialog box to invoke it.

ClassWizard is available from both Visual Workbench and from App Studio.

Using the Tools To Create an Application

The development phase of any Windows-based application typically includes a number of passes, involving editing source and resource files, building the project, and testing and debugging. Because these activities are iterative and interwoven during a normal development cycle, they don't follow one another in a strict sequential order.

The following steps, nonetheless, descibe the general procedure for beginning application development using AppWizard, ClassWizard, and App Studio:

1.	From the Project menu, select AppWizard. Use AppWizard to select the location for your project and the characteristics of your project.

2.	Use ClassWizard to create classes, member functions, and member variables for the skeleton code in your application. It also displays the locations in the source files where you need to add code specific to your implementation.

3.	Use App Studio to create resources for your application.

4.	Use ClassWizard to create the member functions to handle those resources.

5.	Build the application with the Build command on the Project menu.


Using AppWizard to Generate Starter Files

The AppWizard command on the Project menu creates a suite of files for a new Windows-based application, using the Microsoft Foundation Class Library. AppWizard creates files with code to display a main window with the menu structure common to most applications. Depending on your choice of options, you can also include the necessary skeleton code for:

 Creating a toolbar and status bar

 Printing

 Creating and displaying your online help files

 Supporting Object Linking and Embedding (OLE)

 To create a Windows-based application using AppWizard:

1.	From the Project menu, choose AppWizard.

The MFC AppWizard dialog box appears.

2.	Enter a name for your project in the Project Name box.

AppWizard copies the project name into the New Subdirectory box, in preparation for the automatic creation of a subdirectory with that same name in the current directory. This subdirectory contains the files for your project.

3.	If desired, choose a different directory from the directory list or a different drive from the drive box.

If you choose a different directory or drive, AppWizard automatically changes where it creates your project subdirectory.

4.	If desired, enter a different subdirectory name in the New Subdirectory box.

5.	Choose the Options button either (1) to include additional skeleton code in your application or (2) to exclude default choices for skeleton code from your application.

  More information on AppWizard Options

6.	Choose the Classes button to alter the proposed names of classes, the names of files for header or implementation code for all classes, or the document type or document extension for document classes.

  More information on AppWizard Class Options

The document type is the name that appears in selection dialogs when your application has multiple document classes [image] such as both spreadsheets and charts. The document extension is the filename extension proposed for documents of the current class.

7.	Choose OK.

The AppWizard creates the required files and opens the project in Visual Workbench.

8.	From the Project menu, choose Build.

This action compiles the generated files and links the resulting object code into a Windows-based application.

At this point, you can run the skeleton application. You can display the menus, manipulate the window, and dismiss the application.

Your next step is to add the functionality you want for the application.


More Information on AppWizard Options

You can select from the following options:

Option	Default	Comments
Multiple Document Interface (MDI)	Yes	Allows your application to open multiple child windows with document types that you specify in your application. If the check box is cleared, your application uses the Single Document Interface (SDI) and can have only one document window open.
Initial Toolbar	Yes	Displays an initial toolbar and status bar with standard buttons representing menu commands for your application. In addition, your application includes menu commands to display or hide the toolbar or status bar.
Printing and Print Preview	Yes	Includes the menu commands and code for printing documents and for previewing documents on your display as they will be printed.
Context-Sensitive Help	No	Generates the skeleton files necessary to build a context-sensitive help file for Windows NT.
OLE Client	No	Provides the code necessary for your application to serve as a client for object linking and embedding (OLE), using OLE-linked and OLE-embedded objects. In this case, the document class is derived from COleClientDoc instead of CDocument. It also adds an OLE command to the application's menu.
External Makefile	No	Creates a makefile that can be edited directly for use with the NMAKE utility. You must then open this project file as an external project file. The default choice is to create a makefile for use with Visual Workbench.
Generate Source Comments	Yes	Puts comments in the code generated by AppWizard, indicating where you should add to the generated code. If you clear this option, AppWizard generates no comments.


More Information on AppWizard Class Options

AppWizard automatically generates the appropriate classes for your application, depending on the selections that you have made in the Options dialog box. AppWizard names the classes based on the project name and specifies filenames for them.

In each case, you can alter the proposed class name. In some cases, you can alter the proposed filenames to contain the class information.

Label	Description	Property
New Application Classes	The new classes based on your choices in the Options dialog box.	Fixed
Class Name	The selected class in the New Application Classes list.	Modifiable
Base Class	The MFC class on which the selected class is based.	Fixed
Header File	Name of the file containing header information for the class.	Modifiable for all classes except the Application class
Implementation File	Name of the file containing skeleton code for the class.	Modifiable for all classes except the Application class
File Extension	Filename extension to be appended by default to files created from the selected Document class.	Typed by the user
Doc Type Name	Name based on the selected Document class that appears in the default filename, the Windows shell registration name, the title bar of a document, and constants in the code created by AppWizard	Modifiable


Adding a Menu with App Studio
Adding a Menu Command with App Studio

Use App Studio to add resources to a Windows-based application created with the Microsoft Foundation Class Library. Although this procedure covers menu commands because they're a common addition to programs, you can add other types of resources with App Studio in a similar fashion.

Note  You should use AppWizard to generate the starter files. AppWizard creates files containing classes for a skeleton application and a resource file (.RC) for the application. If you don't use AppWizard, you must create the .RC file.

 To add a menu command with App Studio:

1.	From the Visual Workbench File menu, choose Open.

The File Open dialog box appears.

2.	From the list of file types, choose .RC.

3.	Double-click the .RC file for your project in the file list.

This action opens App Studio and compiles the .RC file for your application.

Note  You must have checked the Open .RC Files Using App Studio check box in the Editor dialog box under the Options menu. If the check box is cleared, the file is opened as text in an editor window in Visual Workbench.

4.	From the list in the resource window, choose Menu.

5.	From the list of menu resources displayed, choose the menu to which you want to add a command.

6.	Click the Open button.

7.	Choose the menu name to which you want to add a command. Alternatively, if you want to add a new menu, leave the selection at its current location.

Depending on your choice, the text box for your new command appears at the bottom of the chosen entry or at the far right of the menu bar.

8.	If necessary, choose the menu item text box.

9.	Type the menu command. If you want to specify an accelerator key, type an ampersand (&) before you type the accelerator key.

The property page appears, with entries for this menu command. It has a default proposal for the object ID and the caption that you typed.

10.	If you choose, edit the proposed object ID.

In general, it is preferable to use an ID that you can easily relate to the command.

11.	From the File menu, choose Save.

You can now use ClassWizard (on the Resource menu) to bind the menu command to a member function.


Adding a Dialog Box

Use App Studio to create a dialog box with controls and give the controls object IDs.

Note  You should use AppWizard to generate the starter files. AppWizard creates files containing classes for a skeleton application and a resource file (.RC) for the application. If you don't use AppWizard, you must create the .RC file.

 To add a dialog box using the resource window in App Studio:

1.	From Visual Workbench file menu, select Open.

2.	From the list of file types, choose .RC.

3.	Double-click the .RC file for your project in the file list.

This action opens App Studio and compiles the .RC file for your application.

Note  You must have checked the Open .RC Files Using App Studio check box in the Editor dialog box under the Options menu. If the check box is cleared, the file is opened as text in an editor window in Visual Workbench.

4.	From the list in the resource window, choose Dialog.

5.	Click the New button to create a new resource.

6.	Select Dialog from the list of available types in the Resource list of the New Resource dialog box.

A dialog creation window with an empty, new dialog box appears.

7.	From the Window menu, choose Show Control Palette to display the palette of available controls. Drag and drop the desired controls from the palette onto the dialog box.

8.	To give the dialog box an ID and a caption of your choice, double-click the new dialog box to display its property page .

9.	Double-click each control in the new dialog box to display its property page, to give it an ID of your choice, and to assign it the desired properties.

10.	From the File menu, choose Save.

You are now ready to add a class for the dialog and the member variables in the class for each control in the dialog.

 To add a class and associated member variables for a dialog box using ClassWizard [image] in App Studio:

1.	From the Resource menu, select ClassWizard.

2.	In the ClassWizard dialog box, choose Add Class.

The Add Class dialog box appears. The proposed class type is CDialog, which is what you want.

3.	Type a class name for your dialog class.

As you enter the name, ClassWizard also fills in proposed names for the .CPP and .H files automatically.

4.	Display the Dialog ID list, and choose the dialog ID that you assigned to your dialog box.

5.	Choose Create Class to dismiss the Add Class dialog.

6.	Choose Edit Variables to add member variables for the dialog controls.

7.	Choose Add Variable to add member variables associated with the controls in your dialog box.

Member variables names all begin with m_ by convention.

You give the variables the appropriate properties and types.

If you want to provide initial values for the member variables, later you can edit the OnInitDialog() function in the dialog class.

8.	Choose OK to dismiss the Add Member Variables dialog.

For certain types of variables, you can specify maximum and minimum values or lengths.

Repeat steps 6 and 7 for each control and associated member variable.

9.	Choose Close to dismiss the Edit Variables dialog box.

10.	Choose OK to close ClassWizard.

11.	Choose Save from the File menu.

12.	Exit from App Studio, and return to Visual Workbench.

You can now invoke ClassWizard from Visual Workbench to make the connection between a menu command and the dialog box and to add the member functions to handle messages related to the dialog.


Modifying Code and Resources with ClassWizard

ClassWizard creates additional classes for your application and connects user-interface objects to commands and message-handler functions. Most commonly, you create additional classes for dialog boxes with ClassWizard. For this reason, CDialog is the default choice for the base class from which to derive your class.

You also use ClassWizard (1) to create member functions for user-interface objects and member variables for dialog box controls and (2) to connect dialog boxes and their controls and other user-interface objects to member functions.

Although this procedure covers connecting dialog boxes because they're a common addition to programs, you can add other types of resources with ClassWizard in a similar fashion.

Note  To connect a dialog box [image] or other user-interface object [image] to a menu command or toolbar button, you must first create the menu entry or toolbar button and its object ID.

 To add a dialog box to your application:

1.	From the Browse menu, choose ClassWizard.

2.	From the Class Name drop-down list, select the class that will handle the message.

Which class should you choose? A dialog box gathers input from the user of your application and stores it in its member variables. The application usually assigns the values of member variables in the dialog box to member variables in another class. Choose the class with member variables whose values you want to alter.

Later, when you edit the code for the class, you will create a dialog object in a member function of that class and add the code in that class to invoke the dialog box.

Note  You need to include the header file for the dialog box class in the file containing the class that you choose here.

3.	From the Object IDs list box, choose the ID for the menu command you want to bind to the new member function in the class.

You can choose an ID associated with other user-interface objects, such as a toolbar button.

4.	From the Messages list box, choose COMMAND.

5.	Click the Add Function button.

The Add Member Function dialog box appears. In this dialog box, specify the name of the member function you're adding to your class.

6.	 If desired, edit the proposed function name.

By convention, a message-handler function name begins with "On" and takes the rest of its name from the object ID.

7.	Click OK.

To indicate that the message is bound to a handler function, ClassWizard displays a hand icon that appears next to the selected message in the Messages box.

In addition, ClassWizard takes the following actions:

Adds a message-map entry to the class's message map in the .CPP file for the class.

Adds a member function declaration to the class declaration in the .H file for the class.

Adds a member function template to the .CPP file for the class. You must add the code in this template to define the action of your handler function.

You can now modify the function template to add the code that starts up your dialog box.

 To modify the function template for your dialog box:

1.	Select the function that you previously bound to the dialog box, if necessary.

2.	Click the Edit Code button.

The template for the function appears in a Visual Workbench source window. If you selected the option to generate comments when you generated the starter files, the comment indicating where you add your code is selected.

3.	Add the code to implement the actions your handler function takes.

In the case of a dialog box, you add code to invoke the dialog box and to assign values to and retrieve values from its member variables, among other possible actions.

 Sample Code To Add

Note  If you are adding code that refers to objects in another file, be sure to include the header file defining those objects in an #include statement in this file.

4.	From the File menu, select Save to save the changes to this .CPP file.

You can now build your application again with the Build command on the Project menu or the Build button on the toolbar.

Note  You can bind more than one user-interface object to a single function. You can bind both a menu command and a toolbar button to a single function, for instance. In this case, selecting either object in your application causes the same action.


Binding Commands with ClassWizard

Use the ClassWizard command on the Browse menu to connect menus, buttons, and other user-interface objects to the implementation code in your application created with the Microsoft Foundation Class Library.

ClassWizard presents a list of your program's user-interface objects [image] views, dialog boxes, dialog controls, and commands. It also presents a list of available messages to which you can connect these user-interface objects. ClassWizard lets you specify the handler function that responds to a given message when an object receives it. The connection between message, object, and handler function resides in the class's message map. The message-handler function becomes a member function of the selected class.

Note  You must first create an object of the desired class with App Studio and then assign it an object ID before you can bind it to a command.

 To bind a message to an object:

1.	From the Browse menu, choose ClassWizard.

2.	From the Class Name list, select a class to handle the message.

3.	From the Object IDs box, choose the ID for the specific object you want to bind to the new member function in the class.

4.	From the Messages box, choose a message you want to handle with a handler function.

5.	Click the Add Function button.

The Add Member Function dialog box appears. In this dialog box, you specify the name of the member function you're adding to your class.

6.	 If desired, edit the proposed function name.

By convention, a message-handler function name begins with "On," and takes the rest of its name from the object ID.

7.	Click OK.

To indicate that the message is bound to a handler function, ClassWizard displays a hand icon that appears next to the selected message in the Messages box.

In addition, ClassWizard takes the following actions:

Adds a message-map entry to the class's message map in the .CPP file for the class.

Adds a member function declaration to the class declaration in the .H file for the class.

Adds a member function template to the .CPP file for the class. You must add the code in this template to define the action of your handler function.

8.	Click the Edit Code button.

The template for the function appears in a Visual Workbench source window. If you selected the option to generate comments with the starter files, the comment is selected indicating where you add your code.

9.	Add the code to implement the actions your handler function takes. If you are adding code that refers to objects in another file, be sure to include the header file defining those objects in this file.

10.	From the File menu, select Save All to save the changes to the .H and .CPP files.

You can now build your application again by choosing the Build command on the Project menu or choosing the Build button on the toolbar.

Note  You can bind more than one user-interface object to a single function. You can bind both a menu command and a toolbar button to a single function, for instance. In this case, selecting either object in your application causes the same action.


Object
An object is an instance of a class. That is, a class defines characteristics, and an object of that class is the memory with the locations and sizes specified by the characteristics. With App Studio, you create user-interface objects, which are specific instances of certain classes, and connect those user-interface objects to code using ClassWizard.


Message
A message in the ClassWizard Messages list can be either of the following:

A Windows message. These messages are generated by Windows NT for input events and are directed to windows in your application.

A command. These messages are generated by visual user-interface objects and are directed to command targets in your application.


Sample Dialog Code
\\ The following sample code fills in the template
\\ for a simple member function in the CMyDoc class
\\ to invoke the dialog box defined in CMyDialog:

#include "mydialog.h"
.
.
.
void CMyDoc::OnMyDialog()
{
    CMyDialog dlg;
    // Initialize dialog data from the values in the
    // class of which this function is a member.
    dlg.m_nMyValue1 = m_nMyValue1;
    dlg.m_nMyValue2 = m_nMyValue2;

    // Invoke the dialog box as a modal dialog box.
    if (dlg.DoModal() == IDOK)
    {
        // Retrieve the dialog data from the dialog controls and
        // assign it to the member variables in the class.
        m_nMyValue1 = dlg.m_nMyValue1;
        m_nMyValue2 = dlg.m_nMyValue2;

        // Update the program's state to reflect the new values.
        MyUpdateFunction();
    }
}


Tips and Troubleshooting

Creating Projects with AppWizard

You should use AppWizard to generate the starter files. AppWizard creates files containing classes for a skeleton application and a resource file (.RC) for the application. If you don't use AppWizard, you must create the .RC file.

When you type a project name in the MFC AppWizard dialog box, this name is appended to the displayed path as a subdirectory and is used for the project file name.

If you use the drive and directory controls in the MFC AppWizard dialog box to select a location for your application, the displayed path changes automatically. The project name that you entered is automatically appended to new drive and directory choices.

If you choose the option to include a toolbar with your application in the Options dialog box of the MFC AppWizard dialog box, you need to edit the bitmap that is added to your suite of files. Use App Studio to edit the bitmap.

Adding Functions with ClassWizard

To connect a dialog box [image] or other user-interface object [image] to a menu command or toolbar button with ClassWizard, you must first create the menu entry or toolbar button and its object ID using App Studio.

You can bind more than one user-interface object to a single function. You can bind both a menu command and a toolbar button to a single function, for instance. In this case, selecting either object in your application causes the same action.

If you delete a member function in the ClassWizard dialog box, the declaration is deleted from the class in the header file, and the message map entry is deleted from the implementation file. You must delete the function code and any cross-references to the function manually.

To add a function and edit its related code, or to view class information, you should make your selections in this order in the ClassWizard dialog box:

1.	Select a class name.

2.	Select an Object ID.

3.	Select a Message.

You can then select an associated function to edit or delete, or click the Add Function button to add a member function to the class.

By convention, the names of all message-handling functions begin with the prefix On.

Adding Variables with ClassWizard

Edit Variables is available in the ClassWizard dialog box only in classes with a data map. This includes dialog and form view classes.

By convention, the names of all member variables in the class library begin with the prefix m_.

Adding Code from ClassWizard

After you've added a new member function in the ClassWizard dialog box, choose Edit Code to add the implementation code for the function. A Visual Workbench editor window with the file containing the class for the member function appears, with a highlighted comment indicating where to add your code.

You can select a function in the ClassWizard dialog box and then click Edit Code to locate and examine code quickly.

If you are using ClassWizard to add code that refers to objects in another file, be sure to include the header file defining those objects in an #include statement in this file.

Importing Classes from Other Projects

If you are importing several message-handling classes from another project, you can save time by rebuilding the ClassWizard information file (project.CLW) rather than importing each class separately in the Add Class dialog box. You can completely rebuild the .CLW file by deleting the project's CLW file, and then opening ClassWizard from App Studio. Answer Yes when asked if you want to rebuild the .CLW file. Then use the Select Source Files dialog box to provide ClassWizard with a list of files in your project.

Opening App Studio with .RC Files

You must have check the Open .RC Files Using App Studio check box in the Editor dialog box under the Options menu to start App Studio directly when opening an .RC file from the File Open dialog box. If the check box is cleared, the file is opened as text in an editor window in Visual Workbench.


Workspaces

How Do I?	Brief	Click
Learn about Workspaces	What you should know about the Workspaces.
Automatically save a workspace	Setting an option to automatically save your arrangement of windows when you exit Visual Workbench.
Create a named workspace	Saving an arrangement of windows under a name [image] Edit, Debug, or Custom (a named workspace).
Load a named workspace	Loading a named workspace saved with the current project.
Save changes to a named workspace	Saving changes to any named workspace.
Set an initial workspace	Setting options for an initial workspace when Visual Workbench or a project is opened. Overrides an automatically saved workspace.
Rename the default named workspaces	Changing the default names (Edit, Debug, and Custom) for the workspaces you can associate with a project.
Troubleshoot	Speeding up your work and clearing up problems.


Workspace Basics

A workspace is a convenient way of saving and restoring an arrangement of windows. For example, suppose you like to debug with a narrow Registers window to the right of your source window and with the Watch and Locals windows below. With the arrangement saved as a workspace, you can simply load it at the start of each debugging session [image] without the trouble of positioning and sizing windows.

Visual Workbench allows you to:

Automatically save your current arrangement of windows when you close a project or Visual Workbench. This workspace is called Last Workspace Used and is opened during the following session. The current workspace changes each time you close Visual Workbench or a project.

Specify a named workspace (Edit, Debug, or Custom) for a project or for Visual Workbench when no project is open. Up to three workspaces can be saved for a project or Visual Workbench. A named workspace is opened with the Load Workspace command on the Project menu. A named workspace does not change between sessions unless you save changes to an existing workspace.

Set an initial workspace. An initial workspace is automatically opened when you open Visual Workbench or a project. Your options for an initial workspace are None, Last Workspace Used, or any named workspace [image] Edit, Debug, Custom. Set an initial workspace with the Workspace command on the Options menu.

Rename the default names for Edit, Debug, or Custom named workspaces. You can change each name to suit your preference.

A workspace saves and restores:

Window arrangements, minimized, maximized, or sized

Color settings

Status of the toolbar and status bar

Applications open from the Tools menu

Workspace information is stored in a file with the project name and a .WSP extension. Any files already opened that do not belong in the current workspace are either closed, minimized, or not affected, depending on your settings in the Workspace dialog box..


Automatically Saving a Workspace

It is often useful to maintain your Visual Workbench setup between sessions. Whenever you exit Visual Workbench or close a project, the current workspace (Visual Workbenchs configuration) is automatically saved. When a project is closed, either directly or by exiting Visual Workbench, the current workspace is saved in the projects workspace file. If no project is open when you exit Visual Workbench, the current workspace is saved in Visual Workbenchs workspace file.

 To automatically save your arrangement of windows as a workspace:

1.	From the Options menu, choose Workspace.

The Workspace dialog box appears.

2.	Select Last Workspace Used from the Initial Workspace box.

When you close your project or exit Visual Workbench, the arrangement of windows is saved as a workspace. When you reopen the project or Visual Workbench, the workspace is displayed.

As long as this option is in effect, Visual Workbench updates the workspace whenever you exit or close a project.

Since Visual Workbench always loads the most recently used project when it starts, the last workspace associated with that project is also loaded. If no project was active at the end of the last session, the last workspace used in Visual Workbenchs default state is loaded.


Saving a Named Workspace

You can save up to three workspaces for each project in addition to the current workspace, which is automatically saved and becomes the Last Workspace Used." These three workspaces are called named workspaces, since you can use default names or use your own. You can also save up to three workspaces for Visual Workbench itself, before any project is assigned to it.

To save a workspace for Visual Workbench itself, save the workspace when no project is open. To save a workspace for a project, first open the project, then take the following steps.

 To save a workspace for an open project:

1.	Arrange and size the appropriate windows.

2.	From the Project menu, choose Save Workspace.

3.	From the cascading menu, choose Edit, Debug, or Custom.

Edit, Debug, and Custom are default workspace names, and are simply useful labels. You can change the default names by choosing the Workspace command from the Options menu.

The workspace information is stored in a file with the project name and a .WSP extension.

 To save changes to a workspace:

1.	Rearrange files or windows of a workspace (Edit, Debug, Custom, or a name of your own) on your screen.

2.	From the Project menu, select Save Workspace.

3.	From the cascading menu, choose either the Edit, Debug, or Custom command. The command you choose should correspond to the workspace name you are saving.

You can also select the The Prompt Before Redefinition option in the Workspace dialog to remind you that your workspace has changed when you close a project or Visual Workbench. You are given the option to save the changes.

Tip  A modified workspace is saved as it was created, either automatically or with the Save Workspace command. For example, saving a revised Edit workspace as Custom has a similar effect to using the Save As command on a source file.


Loading a Workspace
Loading a Named Workspace

The Load Workspace command loads a named workspace previously saved with the current project or Visual Workbench.

 To load a named workspace:

1.	From the Project menu, select Load Workspace.

2.	From the cascading menu (Edit, Debug, Custom), choose the workspace you want to load.

Any files already open that do not belong in the current workspace are either minimized to an icon or are closed depending on the setting of the Close Non-Workspace Windows on Load check box in the Workspace dialog box.


Setting an Initial Workspace

You can load a specific workspace when opening Visual Workbench or a project. This is done by setting an option for an initial workspace. An initial workspace is a workspace that is opened automatically without choosing the Load Workspace command. The default is no initial workspace.

 To set an initial workspace:

1.	Create a workspace or workspaces for Visual Workbench or a project.

2.	From the options menu, choose Workspace.

The Workspace dialog box appears.

3.	Select a workspace name from the Initial Workspace box.

The name "Last Workspace Used" opens your last arrangement of windows when you exited Visual Workbench or closed a project. With Last Workspace Used selected, a workspace is automatically saved for you. Selecting another name [image] the defaults are Edit, Debug, and Custom [image] opens the workspace specifically saved under that name.

4.	Uncheck the Close Non-Workspace Windows on Load check box if you want to minimize rather than close open windows not part of the initial workspace you have specified. Select the check box to close rather than minimize windows.

5.	Choose OK.

When you open a project, the initial workspace for the project is displayed. When you close a project, the last workspace used in that project is displayed.

The following table shows what happens to open windows when you open a project with the various combinations of settings for Initial Workspace and Close Non-Workspace Windows on Load. Named Workspace refers either to one of the named workspaces or Last Workspace Used.

	Close Non-Workspace Windows on Load Option
Initial Workspace Option	Checked	Unchecked
Named Workspace	Open windows are closed	Open windows are minimized
None	Open windows are unchanged	Open windows are unchanged


Renaming a Workspace

The default workspace names you can save for a project or Visual Workbench are Edit, Debug, and Custom. But you can rename any workspace to a name better suited to your purposes. When you change a default name, the new name appears on the Load Workspace and Save Workspace cascading menus.

 To rename a workspace:

1.	From the Options menu, choose Workspace.

The Workspace dialog appears.

2.	Change the name in the appropriate Workspace text box [image] Workspace #1, Workspace #2, or Workspace #3.

3.	Precede a letter in the name with a ampersand (&) to create an accelerator key in the Load and Save Workspace cascading menus. Each workspace name must have a different letter to avoid conflicts.

4.	Choose OK.


Tips and Troubleshooting

You can pick any name that you want to give to workspaces in the Workspace dialog box. The names are a convenient way for you to relate window arrangements to your work habits and preferences. These names appear on the cascading menus under Load/Save Workspace on the Project menu. An ampersand before a letter in the name identifies it as an accelerator key.

The following table shows what happens to open windows when you open a project with the various combinations of settings for Initial Workspace and Close Non-Workspace Windows on Load. Named Workspace refers either to one of the named workspaces or Last Workspace Used.

	Close Non-Workspace Windows on Load Option
Initial Workspace Option	Checked	Unchecked
Named Workspace	Open windows are closed	Open windows are minimized
None	Open windows are unchanged	Open windows are unchanged
A modified workspace is saved as it was created, either automatically or with the Save Workspace command. For example, saving a revised Edit workspace as Custom has an effect similar to using the Save As command on a source file.


Preferences

How Do I?	Brief	Click
Learn about syntax coloring	What you should know about syntax coloring
Change syntax colors	Changing colors for various language elements such as functions and variables
Change colors in a source window	Changing the color of screen elements; revert to default
Change the color of jumps in help	Changing the color of jumps in help from default green to a color of your preference, such as dark blue
Set the size of the undo buffer	Changing the size of the undo buffer to allow more undo or redo actions in the editor
Set font and font size	Changing font and font size for a single window or for all windows
Set directory paths	Editing the default paths for executable, include, and library files after setup
Troubleshoot	Speeding up your work and clearing up problems


Syntax Coloring Basics

Using different colors for various language elements such as functions and variables gives you immediate visual clues about the structure of your source code. You can change the default colors of these elements as well as the color of other text in the development environment such as reserved words, breakpoints, errors, and tags. You can also turn off syntax coloring for all source files. These changes are global and affect all source files with extensions recognized by Visual Workbench. To make global syntax coloring changes, choose Color from the Options menu.

Visual Workbench performs syntax coloring based on file extensions. You can override Visual Workbenchs default coloring for a file by choosing Syntax Coloring from the View menu. This allows you to specify C, C++, or no syntax coloring for any individual file.


Changing Syntax Colors

For any source file in Visual Workbench, you can specify which syntax coloring to apply (C or C++), or whether to turn off syntax coloring altogether. This is useful if you have C or C++ code in a header file with a filename extension other than .H, .HPP, or .HXX, or if you have C or C++ source code with filename extensions that Visual Workbench doesnt recognize.

Note  You should be cautious when using nonstandard filename extensions since the filename extensions .CPP, .CXX, and .C are used by Visual Workbench to determine whether the C++ or C compiler is used during the build.

 To change syntax coloring in an individual source file:

1.	Click in the source file window or use the Window menu to make the source window active.

If there are multiple windows open on the source file, select one of them. Syntax coloring changes will appear in all windows opened on the source file.

2.	From the View menu, select Syntax Coloring.

A cascading menu appears on the right with three choices: C, C++, and None.

3.	Choose C or C++ to determine syntax coloring for that source file.

Or choose None to turn syntax coloring off.

Note  Global syntax coloring must be enabled before you can use the Syntax Coloring command on the View menu on any specific file. To enable global syntax coloring, choose Color from the Options menu and then select the Syntax Coloring check box in the Color dialog box.


Changing Screen Colors

To familiarize yourself with the steps in changing screen colors, change the color of comments in the source window to black text on a light-blue background.

 To change the colors in the source window:

1.	From the Options menu, choose Color. The Color dialog box appears.

2.	From the Items list, select the item you want to change.

For this example, select Comment.

3.	In the Foreground Color and Background Color groups, select the color squares to represent the item.

For example, select the light-blue square in the Background Color group and the black square in the Foreground Color group. The new color combination is shown in the Sample Text box.

4.	Choose OK to apply the change to the source window.

You can change several items in the Items list before choosing OK.

 To change a source window item back to its original colors:

1.	From the Options menu, choose Color.

2.	From the Items list, select the source item to be restored.

For example, select Comment.

3.	Choose Restore to Default.

4.	Choose OK.

Display items such as keywords and identifiers can be changed back to their default colors without changing the foreground and background colors of the source text.

To restore all items to their default values, choose Restore All Defaults.


Changing the Color of Jumps in Help

The default color for jumps in help is green. Some users may find green hard to read against a customized background color. You can change this color by modifying your WIN.INI file.

 To change the color of jumps:

1.	Open your WIN.INI file in a text editor.

2.	Find the [Windows Help] section. If the section does not exist, create it.

3.	Write the following lines after the section heading:

JumpColor=0 0 255
PopupColor=100 45 65

The values in the above example change the jump color to blue and popup jump color to violet. The values represent red, green, and blue respectively:

Key	Red Value	Green Value	Blue Value
JumpColor	0	0	255
PopUpColor	100	45	65
The values can range from 0 to 255. In the JumpColor key example above, the value for green is set to 0. You can edit the colors by changing the three values in each line. The default values are 0 0 0.

When Windows Help is loading, it reads the key values from the WIN.INI file.


Setting the Size of the Undo Buffer

The Undo command in the Edit menu allows you to "undo" previous editing actions. The number of editing actions you can undo is determined by the size of the Undo buffer. The default size for the buffer is 4K (kilobytes). You can set the buffer from 0 to 64K.

 To set the size of the buffer:

1.	From the Options menu, choose Editor.

2.	In the Undo Buffer Size box, type a number from 0 to 64. The number represents the size in kilobytes for the buffer.

3.	Choose OK.

If the buffer is set to 10K and you have deleted 2K of text four times in an editing session, you can undo all four editing actions.


Setting the Font and Font Size

You can specify which font type and size appear in a Visual Workbench source window. You can choose any font type and size found in your setup of Windows. You can also determine what will be the default font for any new window.

 To set the font type, style, and size:

1.	From the Options menu, choose Font. The Font dialog box appears.

2.	From the Font list box, select the font you want to apply.

The sample text in the Sample box changes to the font you selected.

3.	Optionally, select the font style from the Font Style list box.

The sample text in the Sample box changes to the font style you selected.

4.	From the Size list box, select the font size.

The sample text in the Sample box changes to the font size you selected.

5.	Choose OK.

 To set the default font for new source windows:

1.	Choose a font, style, and size as just described.

2.	Choose the Use as Default Font button.

The currently selected font, style, and size appear in the Default Font description.

3.	Choose OK.

The default font is automatically applied to any new or opened window. The default font information is stored with other Visual Workbench information and is persistent between sessions.The currently used default font for all your editor windows is indicated below the Use as Default Font button. You can change the default font by selecting a font and a point size from the Font and Size boxes and then choosing the Use as Default Font button.

Text within the source window can be only one font and size. Multiple fonts cannot be displayed in the same source window. However, each source window can contain a different font and size, even when source windows with different fonts are attached to the same source file.


Setting Directories

When Visual C++ is installed, the Setup program determines the correct directory paths for several file types and updates the Directories dialog box with these paths. The file types are:

Build utilities (executable files)

Include files

Libraries

Microsoft Foundation Class Library source files

Help files

  To edit the directories paths:

1.	From the Options menu, choose Directories.

2.	Edit any path.

3.	Choose OK.

The directories for build utilities, include files, and libraries are drop-down lists that can contain up to four different paths, making it easy to quickly change build environments.

The Directories dialog box contains the following drop-down list boxes:

Executable Files Path

Specifies where the build utilities, such as NMAKE, LINK, and BSCMAKE, reside.

Include Files Path

Specifies where the compiler should look for include files surrounded by angle brackets (< and >) (for example: #include <stdio.h>).

Library Files Path

Specifies where the linker should look for libraries to resolve external references.

In addition, the Directories dialog box contains the following edit boxes:

Help Files Path

Specifies where Help files accessed from Visual Workbench are located.

MFC Files Path

Specifies where the base directory for the Microsoft Foundation Class Library is located. This is needed when you use the debugger to trace into class library source code or when you use the browser to jump to definitions or references in the class library source code.

Directory information is stored in a Windows NT registry.


Tips and Troubleshooting

Specifying Directories

To specify more than one directory for a category in the Directories dialog box, separate them with a semicolon (;).

When an #include directive is encountered in a program (and a complete path is not provided), the compiler searches for the file in this order:

1.	The current directory.

2.	The path or paths specified with the /I option, if you have set that option in the Compiler Options dialog box under Project on the Options menu.

3.	The paths specified in the Include Files path.

Directory information is stored in the Windows NT registry.

Using Fonts

Open windows display a new default font only if they are closed and then opened again.

To restore the displayed font to its startup characteristics if you have selected a new default font, select Courier 10-point regular.

Text within the source window can be only one font and size. Multiple fonts cannot be displayed in the same source window. However, each source window can contain a different font and size, even when source windows with different fonts are attached to the same source file.


Modifying the Tools Menu

How Do I?	Brief	Click
Learn about the Tools menu	What you should know about the Tools command
Add a tool or command	Adding tools to the Tools menu
Change or edit commands	Editing any property for a tool; removing a tool or command
Change the order of commands on the Tools menu	Moving menu commands up or down in the list of menu commands
Specify arguments for a tool or command	Setting default arguments for a tool or command; setting an option to specify arguments when tool is loaded.
Specify predefined macros for a tool or command	Using predefined macros to better integrate a tool or command into Visual Workbench
Redirect output from tools	Gaining access to the Output window's built-in parser to jump to file locations where errors have occurred
Use your own editor	Using the Add Tool command to add your editor to the Tools menu.
Troubleshoot	Speeding up your work and clearing up problems


The Tools Command
Tools Menu Basics

The Tools menu is a convenient place from which to run frequently used tools while you are in Visual Workbench. After adding an application to the Tools menu, you can run it from the menu or load it with a shortcut key. You can add up to eight commands to the Tools menu.

You can stop any running tool by pressing CTRL+BREAK.

The Tools command on the Options menu adds, deletes, and edits commands on the Tools menu. You can specify arguments for any program by entering the arguments in the Arguments box. You can also choose to be asked for arguments when the tool or command runs. For tools that generate output, you can redirect it

Macros

To help you integrate your tools with the current status of the Visual Workbench environment, Visual Workbench provides a set of 11 argument macros:

Macro Name	Expands to a String Containing:
$File	The complete filename of the current source (defined as drive+path+filename). Blank if non-source window is active.
$FileName	The filename or the current source (defined as filename). Blank if non-source window is active.
$FileDir	The directory of the current source (defined as drive+path). Blank if non-source window is active.
$Proj	The current project base name (defined as filename). Blank if no project is currently open.
$ProjDir	The directory of the current project (defined as drive+path). Blank if no project is currently open.
$Cmdline	The command-line arguments passed to the application (obtained from the debug dialog in the Options menu).
$Line	The current cursor line position within the active window.
$Col	The current cursor column position within the active window.
$Dir	The current working directory (defined as drive+path).
$Target	The current project target name (defined as drive+path+filename).
$RC	A resource file (*.RC). For Visual Workbench projects, this is the first resource file in the project list. For external projects, it is $Target.Rc. If there is no resource file or there is no active project, $Rc is blank.


Adding Tools and Commands

You can add up to eight commands to the Tools menu. A tool can be any program that you can run in NT, such as native Windows NT programs, Window 3.1 programs, Console applications, POSIX programs, or OS/2 programs. Once you've added a program to the Tools menu, you can run it from the Tools menu or load it with a shortcut key.

To familiarize yourself with the steps in adding a program to the Tools menu, use the Notepad accessory that comes with Windows.

 To add Notepad to the Tools menu, then run it:

1.	From the Options menu, choose Tools. The Tools dialog box appears.

2.	Choose Add from the Tools dialog box. The Add Tool dialog box appears.

3.	Select the drive and directory to locate NOTEPAD.EXE.

4.	Select NOTEPAD.EXE.

5.	Choose OK. The Tools dialog box is again displayed.

You can change the default menu name by editing the Menu Text text box.

You can also add arguments to be passed to the program by typing them in the Arguments text box. You can also use up to 10 predefined macros.

  More information on predefined macros

You can also set the initial directory for your program by typing it in the Initial Directory text box.  An initial directory is the current directory when the program starts up [image] for instance, C:\MyWinApp\Dialogs.

Note  If the program you are adding to the Tools menu has a .PIF file, the startup directory specified in the Initial Directory text box.

6.	Choose OK.

The name of the program now appears on the Tools menu. To run the program, choose it from the menu.


Editing Properties of Commands on the Tools Menu
Editing the Properties of Commands on the Tools Menu

After adding a command to the Tools menu, you can edit the information pertaining to it. You can also delete the command.

 To edit a Tools menu command:

1.	From the Options menu, choose Tools. The Tools dialog box appears.

2.	Select the program or command you want to edit from the Menu Contents box.

3.	Perform one or more of the following actions:

To move the selected command down one position in the menu, choose Move Up

To move the selected command down one position, choose Move Down.

To change the menu title, the command line (tool path), command-line arguments, or the initial directory, type the new information in the appropriate text box.

If you want to specify a letter in the menu title as an access key (a menu accelerator key), precede that letter in the Menu Text text box with an ampersand (&). The first letter in the title is the keyboard access key by default.

 To delete a command from the Tools menu:

1.	From the Options menu, choose Tools.

2.	Under Menu Contents, select the command you want to delete from the Menu Contents list.

3.	Choose Delete to remove the command from the list.

4.	Choose OK.


Moving Commands Up or Down on the Tools Menu

You can change the order of a command on the Tools menu.

 To move commands up or down on the Tools menu:

1.	From the Options menu, choose Tools. The Tools dialog box appears.

2.	Select the command from the Menu Contents box.

3.	Choose one of the following commands:

Choose this Command:	To Do this:
Move Up	Move the selected command up one position in the menu
Move Down	Move the selected command down one position in the menu
4.	Choose OK.

You can also add arguments to be passed to the program by typing them in the Arguments text box. You can also use up to 10 predefined macros.

  More information on predefined macros


Using Argument Macros

You can specify arguments for any program added to the Tools menu by entering the arguments in the Arguments box. To help you integrate your tools with the current status of the Visual Workbench environment, Visual Workbench provides a set of 11 argument macros.

Macro Name	Expands to a String Containing:
$File	The complete filename of the current source (defined as drive+path+filename). Blank if non-source window is active.
$FileName	The filename or the current source (defined as filename). Blank if non-source window is active.
$FileDir	The directory of the current source (defined as drive+path). Blank if non-source window is active.
$Proj	The current project base name (defined as filename). Blank if no project is currently open.
$ProjDir	The directory of the current project (defined as drive+path). Blank if no project is currently open.
$Cmdline	The command-line arguments passed to the application (obtained from the debug dialog in the Options menu).
$Line	The current cursor line position within the active window.
$Col	The current cursor column position within the active window.
$Dir	The current working directory (defined as drive+path).
$Target	The current project target name (defined as drive+path+filename).
$RC	A resource file (*.RC). For Visual Workbench projects, this is the first resource file in the project list. For external projects, it is $Target.RC. If there is no resource file or there is no active project, $RC is blank.
Macro recognition is case-insensitive. All path macros end in a backslash (\).

To use a macro as an argument, type the macro name in the Arguments box. For macros that expand to a directory, you can type the macro name in the Initial Directory box.

For example, the following procedure demonstrates how to add the $File argument macro to Notepad (NOTEPAD.EXE) as a tool.

  To add the $File macro, then run it:

1.	From the Options menu, choose Tools.

2.	Under Menu Contents, select the command you want to edit [image] in this case, Notepad.

3.	In the Arguments box, type $File.

4.	Choose OK to close the Tools dialog box.

5.	Open any source file or make an open source file active by clicking in it.

6.	From the Tools menu, choose Notepad.

The Windows Notepad editor opens with the active Visual Workbench source file as its text file.


Using Error Syntax for Tools

When you redirect the output from a tool to the Output window, you gain access to the Output windows built-in error parser. The error parser is used by the internal build tools to detect filename, error, and line-number information on an output string, making that string a hot link to the specified file and line number. For example, Double-clicking on an error line in the Output window, jumps you directly to the referenced line in the correct source file.

 To by enabling redirection:

1.	From the Options menu, choose Tools.

2.	For the appropriate tool, check the Redirect to Output Window checkbox.

The integrated Find in Files and Profiler tools use this parser as well. For instance, you can double-click on any output line from the Find in Files command and jump to the referenced file and line.

If the output to a tool you have installed and redirected to the output window has the correct error syntax, you can use it in the same way. For example, you could install Microsoft MASM as a tool to compile assembly code, then be able to jump to source code syntax errors directly from its error list in the Output window.

The error syntax is as follows:

error_string	::=	file_spec  error_spec   STRING  |  file_spec STRING
file_spec	::=	FILENAME '(' line_spec ')' ':'
line_spec	::=	NUMBER  |  NUMBER '-' NUMBER
error_spec	::=	ERRORKEYWORD ERRORNUMBER ':'
where:

STRING	::=	Null terminated string
FILENAME	::=	Valid file specification  &&  text file
NUMBER	::=	{1-9}{0-9}*
ERRORNUMBER	::=	{A-Z}+{0-9}{0-9}{0-9}{0-9}
ERRORKEYWORD	::=	"error" | "warning" | "fatal error"
Note  Although the error number is part of this syntax, it is optional and not really useful to any tool except internal build tools. This error number is used internally to link to Help files.


Using Your Own Editor

You can add any editor to the Tools menu and open it from within the Visual Workbench. However, you cannot debug a source file from your own editor.

 To add an editor to the Tools menu:

1.	From the Options menu, choose Tools. The Tools dialog box appears.

2.	From the Tools dialog, choose Add. The Add Tool dialog box appears.

3.	Select the drive and directory to locate your editor. You can specify the file extension to focus your search in the List Files of Type box.

4.	Select the executable file.

5.	Choose OK to close the Add Tool dialog box.

6.	Optionally, give a name for the application in the Menu Text box. The filename base is given as a default.

You can assign a mnemonic to a tool (a mnemonic is the letter used to run a command on a menu). An ampersand (&) before a letter in the name marks the letter as the mnemonic. For example, the entry Notepa&d designates D as the mnemonic to open the application. By default, the first letter in the name is used.

7.	In the Arguments box, add any arguments for the application at startup.

A check in the Ask for Arguments box displays the Tool Arguments dialog box that prompts you for arguments on startup of the tool. Any arguments defined in the Arguments box are also listed in the Tool Arguments dialog box.

8.	In the Initial Directory box, optionally specify the directory you want to be current when the editor is opened. The default is the current directory for Visual Workbench when the editor is opened.

9.	Choose OK.


Tips and Troubleshooting

Using Predefined Macros

You can use predefined macros in the Arguments box of the Tools dialog box.

  More information on predefined macros

Stopping a Tool

You can stop a tool that is running with the CTRL+BREAK key combination.

Using Command-line Tools and Programs

If you have particular command-line tools or programs you like to use, here are some tips to make it easier to integrate these tools with Visual Workbench.

To use commands that don't have an executable file on disk (such as DIR), to pipe the output of a program to another tool, or to redirect the output to a file, you need to start a shell to run the program. In the Command Line text box of the Tools dialog box, enter C:\sysdir\CMD.EXE (use the appropriate drive and directory for your system). In the Arguments box, type /c programname or /c command, followed by options, pipes or redirections, and program or output file names.

To keep an MS-DOS window open with the output of a command-line tool after the tool has been run from the Tools menu, use the Windows PIF Editor to edit the file _DEFAULT.PIF. Under Windows NT, CMD.EXE runs a virtual MS-DOS machine using _DEFAULT.PIF when it is invoked. Change the Display Usage option button selection from Full Screen to Windowed, and clear (uncheck) the Close Window on Exit check box. You will then need to close the MS-DOS window using the Control-menu box whenever you run the tool, but you will be able to view the tool's output when it has finished.

Instead of editing _DEFAULT.PIF, you can also create batch files to run the desired commands, and then create custom .PIF files for those batch files. You can then enter the .PIF file name in the Command Line text box. With this method, if you don't need to see the output of the command [image] such as a command to check in source code, for instance [image] you can close the MS-DOS window, and if you do, you can leave it open.

If you are adding a program that has an existing .PIF file, the specification for the startup directory in the .PIF file overrides the directory that you specify in the Initial Directory box of the Tools dialog box. To avoid confusion, make the specification the same in both the .PIF file and in the Initial Directory box.

Specifying Tool Arguments

Specify arguments to be used automatically every time that you run a tool on the Tools menu by entering the arguments for that tool in the Arguments box in the Tools dialog box. If you want to specify different arguments each time the tool runs, or you want to specify additional arguments at the time the tool runs, check the Ask for Arguments check box.


Comprehensive List of Dialog Boxes
Comprehensive List of Visual Workbench Dialog Boxes

About Box	Find Source
Add Class	Font
Add Member Function	Import Class
Add Member Variable	Line
Add Tool	Memory Window Options
Breakpoints	Messages
Browse Window	MFC AppWizard
Call Stack	New Application Information
Class Info	Open Browser Database
Classes	Open Project
ClassWizard	Options
Color	Page Setup
Confirm Replace	Print
Debug - DLL	Profile
Debug - EXE	Project Options
Directories	QuickWatch
Edit - Project	Repair Class Information
Edit Member Variable	Replace
Editor	Resolve Ambiguities
Exceptions	Resource Compiler Options
External Project Options	Search
File New Project	Select Class
File Open	Select Source File
File Save As	Symbols
Find	Tool Arguments
Find in Files	Tools
Find Next	Workspace


File Open Dialog
Open File Dialog

Use the Open File dialog box to open any text file.

Options

File Name	Drives
Directories	List Files of Type
Read only	Open a new window for the file
Tips

You can double-click a filename in the list box to open the file.

You can select a file type from the List Files of Type box to display a list of all files with a predetermined type from the current drive and directory.

If you type a pattern using a wildcard (* or ?) in the File Name box and press ENTER, the list box displays files matching that pattern. This file type subsequently appears as the default when you open this dialog box again.


File Name
Enter the name of a file to open, save or select. If you type a pattern using a wildcard (* or ?) and press ENTER, the list box displays files matching that pattern.


Directories
Double-click a directory entry to display files from that directory in the Files box.


Drives
Click the arrow to display a list of all attached drives. Click a drive from that list to display directories and filenames from the selected drive.


Files of Type
Click the arrow to display a list of file types. The filename extension determines the file type. Click a file type to display a list of all files of that type from the current drive and directory in the File Name box.


Read only
Select the check box to open the selected file as a read-only file. To save any changes made to the file, you have to save it under another name using the File Save As command.


Open a new window for the file
Select the check box to open the selected file in a new window. Clear the check box to open the file and replace the existing source file in the window that currently has the focus.

Note  This check box appears only if a source window currently has the focus, and you have not modified the contents of the window.


Save As Dialog

Use the Save As dialog box to save the contents of the active file in a different file, or the displayed text in a non-editor window in a text file.

Options

  File Name

  Directories

  Open New Window For This File

  Drives

  List Files of Type

Tips and Troubleshooting

If you open the Save As dialog while an Output, Locals, Watch, Registers, or Browse window is active, the Save As dialog proposes the name of the window followed by the extension .TXT for the file name in which to save the text displayed in the window. In the case of the Browse window, it does not save the .BSC file in .BSC format under a different name.

If you type a pattern using a wildcard (* or ?) in the File Name box and press ENTER, the list box displays files matching that pattern. This file type subsequently appears as the default when you open this dialog box again.

Check the Open New Window For This File check box if you want to keep the window with the file under its current name open. The default behavior, when the check box is cleared, replaces the existing file in the current window with the newly saved file under the new name.


Open New Window For This File
Opens a new window for the file with the new name and keeps the existing window open with file under its current name when checked. You can use this feature to make a template file with #include and #define directives, for instance, and then quickly copy this information to other files, while keeping the original open for further revisions.


Find in Files Dialog

Use the Find in Files dialog box to search for a sequence of characters in one or more files. You can use regular expressions to match character patterns in the selected files.

Options

File Name	Drives
Directories	List Files of Type
Find What	Selected Files
Whole Word Only	Match Case
Use Regular Expressions	Add
Add All	Remove
Remove All
Tips and Troubleshooting

You can double-click a filename in the list box to add it to the project.

You can double-click a filename in the Selected Files box to delete it from the search.


Selected Files
Lists the files to be searched.


Add
Adds the file selected to the list of files to search.


Add All
Adds all the files currently displayed in the file list to the list of files to search.


Remove
Deletes the file selected in the Selected Files list from the search.


Remove All
Deletes all the files from the Selected Files list.


Open Browser Database Dialog

Use the Open Browser Database dialog box to open a browser database (.BSC) file.

Options

  File Name

  Directories

  Drives

  List Files of Type

Tip  You can double-click a filename in the list box to open the file.


Print Dialog

Use the Print dialog box to print the current file to any printer that you have installed for Windows.

Options

  Printer

  Print Range

Tip  To print a range of selected text, highlight the text before selecting Print from the File menu. Then choose Selection from the Print Range option buttons.


Printer
Click the arrow to display a list of installed printers. Click a printer from the list to use that printer.


Print Range
Prints either all the source file or the selected text.


Page Setup Dialog

Use the Page Setup dialog box to:

Set the margins on printed pages.

Specify the text for running headers and running footers on each page.

Options

  Header

  Footer

  Margins

Tips and Troubleshooting

You can use the following special character sequences in headers and footers to insert the corresponding information automatically:

To Print	Use
Filename	&f
Page number of current page	&p
Current system time	&t
Current system date	&d
Left aligned	&l
Centered	&c
Right aligned	&r
With some printers, the minimum margin is determined by the physical characteristics of the printer. For instance, some laser printers cannot print on the top 0.25", or on the left 0.25", of any page.

The base page size for the printer is set when you install the printer or modify the installation. You can use the Printer Setup command on the File menu to determine the page size or modify it.


Header
The text printed at the top of every printed page. The header is always centered and prints 0.25" from the top of the page.


Footer
The text printed at the bottom of every printed page. The footer is always centered and prints 0.5" from the bottom of the page.


Margins
The width, in inches, of each margin on every printed page.


Find Dialog

Use the Find dialog box to:

Find a symbol or a sequence of symbols in a file.

Find all symbols or sequences of symbols that match a given pattern.

Set bookmarks (tags) on lines containing a symbol or sequence of symbols.

Options

Find What	Match Case
Set Bookmarks on All	Match Whole Word Only
Regular Expression	Direction
Tips and Troubleshooting

If you are using regular expressions, remember to use a backslash in front of a special character if you want to use it without its special meaning. For instance, if you want to search for filenames ending with the extension .DOC or .DOT, and you use the regular expression .DO[CT], that expression also finds :DOC, @DOC, %DOT, _DOT, and so on. Those strings are not what you intended to find. To match the period character (.) only, your regular expression should be \.DO[CT].

You can use the following keyboard shortcuts for your searches, after you have dismissed the Find dialog box:

Search	Key
Find selected text	CTRL+F3
Repeat last Find (forward)	F3
Repeat last Find (backward)	SHIFT+F3
Find next error	F4
Find previous error	SHIFT+F4
Find matching brace	CTRL+M
Find next bookmark	F2
Find previous bookmark	SHIFT+F2


Find What
Specifies the string of characters to find, or the regular expression to match.


Tag All
Marks or "tags" all lines containing the string or regular expression found. The lines are highlighted in your source file. You can move quickly to lines with bookmarks using the Next Bookmark (F2) and Previous Bookmark (SHIFT+F2) commands on the View menu.


Regular Expression
Interprets special characters in the Find What box as patterns to match. Special characters and their matches are:

.	Any single character.

*	None or more of the preceding character or expression. For instance, ba*c matches bc, bac, baac, baaac, and so on.

+	At least one or more of the preceding character or expression. For instance, ba+c matches bac, baac, baac, but not bc.

^	The beginning of a line.

$	The end of a line.

[ ]	Any one of the characters contained in the brackets, or any of an ASCII range of characters separated by a hyphen. For instance, b[aeiou]d matches bad, bed, bid, bod and bud, and r[eo]+d matches red, rod, reed and rood, but not reod or roed. x[0-9] matches x0, x1, x2, and so on. If the first character in the brackets is ^ (caret), then the regular expression matches any characters except those in the brackets.

[^ ]	Any character except those following the ^ character (caret) in the brackets, or any of an ASCII range of characters separated by a hyphen. For instance, x[^0-9] matches xa, xb, xc, and so on, but not x0, x1, x2, ....

\{\}	Any sequence of characters between the escaped braces. For instance, \{ju\}+fruit finds jufruit, jujufruit, ..., jujujujufruit, and so on. Note that it will not find jfruit, ufruit or ujfruit because the sequence ju is not in any of those strings.

\{c\!c\!c\}	Any one of the characters separated by the alternation symbol (\!). For instance, \{j\!u\}+fruit finds jfruit, jjfruit, ..., uufruit, and so on.

\~	Not the following character. b\~ad matches bbd, bcd, bdd, and so on, but not bad.

\( \)	Indicates a tagged expression to retain for replacement purposes. If the expression in the Find What text box is \(lpsz\)BigPointer, and the expression in the Replace With box is \1NewPointer, all selected occurrences of lpszBigPointer are replaced with lpszNewPointer. Each occurence of a tagged expression is numbered according to its order in the Find What text box, and its replacement expression is \n, where 1 corresponds to the first tagged expression, 2 to the second, and so on. You can have up to 9 tagged expressions.

\:e	Predefined expression, where :e can be:

\:a	Any alphanumeric character.

\:b	Any whitespace character.

\:c	Any alphabetic character.

\:d	Any decimal digit.

\:f	Any part of a filename.

\:h	Hexadecimal number.

\:i	Microsoft C/C++ identifier.

\:n	Unsigned number.

\:p	Any directory path.

\:q	Any quoted string.

\:w	Any English word.

\:z	Any unsigned decimal integer.

\	Removes the pattern match characteristic in the Find What text box from the special characters listed above. For instance, 100$ matches 100 at the end of a line, but 100\$ matches the character string 100$ anywhere on a line.


Match Case
Finds only text strings that match the case of the characters in the Find What string exactly. Otherwise, the command finds strings with either upper- or lowercase characters that match the characters in the Find What string.


Match Whole Word Only
Matches text strings only if they are preceded and followed by a space, tab, or punctuation character, or the start or end of a line. Otherwise, the command matches any string, whether it is a fragment of a larger string or not.


Direction
The options have the following meanings:

Up

Search from the current cursor position towards the beginning of the file.

Down

Search from the current cursor position towards the end of the file.


Find Next Dialog

Use this dialog box to find another occurrence of the string, to tag all subsequent occurrences of the string, or to cancel the search.

Options

  Find Next

  Tag All

  Cancel

Tips and Troubleshooting

You can use the following keyboard shortcuts for your searches [image] after you have dismissed the Find Next dialog box:

Search	Key
Find selected text	CTRL+F3
Repeat last Find (forward)	F3
Repeat last Find (backward)	SHIFT+F3
Find next error	F4
Find previous error	SHIFT+F4
Find matching brace	CTRL+M
Find next tag	F2
Find previous tag	SHIFT+F2


Find_Find_Next
Finds the next occurrence of the Find What string.


Find_Tag_All
Tags this and all subsequent occurrences of the Find What string in the file.


Find_Cancel
Cancels the search for subsequent occurrences of the Find What string. The cursor remains at the start of the currently matched string.


Replace Dialog

Use the Replace dialog box to:

Find and replace a symbol or a sequence of symbols in a file.

Find and replace all symbols or sequences of symbols that match a given pattern.

Options

Find What	Match Case
Replace With	Match Whole Word Only
Regular Expression	Replace All
Tips and Troubleshooting

It is a good idea to test regular expressions using only the Find command before using the Replace command, because they may match expressions that you don't intend to match. You should test them especially if you intend to use the Replace All option, because you can only Undo the very last replacement if your regular expression replaces unintended matches.


Replace With
The string of characters to replace the characters found. You cannot use regular expressions in this string.


Replace All
Replaces all strings that match the Find What string automatically, without requiring confirmation for each replacement.


Confirm Replace Dialog

Use this dialog box to skip a specific instance for replacement, to replace a specific instance, to replace this and all subsequent instances, or to cancel the replacement entirely.

Options

  Find Next

  Replace

  Replace All

  Cancel


Replace_Find Next
Does not replace this occurrence of the string, and finds the next occurrence.


Replace_Replace
Replaces this occurrence of the string and finds the next occurrence.


Replace_Replace_All
Replaces this and all subsequent occurrences of the string.


Replace_Cancel
Does not replace this occurrence of the string, and does not search for any further occurrences of the string. The cursor remains at the start of the currently matched string.


Line Dialog

Use the Line dialog box to display a specific line in a source file. The number represents the position of the line in the file.

Options

None

Tips

If you enter a number greater than the position of the last line in the file, the last line is displayed.


New Project Dialog

Use the New Project dialog box to create a file containing information required to build a new project.

Options

  Project Name

  Browse

  Use Microsoft Foundation Classes

  Project Type

Tips

If you are building a program that has only one source file, creating a new project is optional.


Project Defined
A project specifies the type of program to build and all the files required to build the program. It also describes how to build the program using those files, the tools comprising Visual C++, and the selected options for those tools. This information is maintained in the project's .MAK file.


Project Name
Name for the file containing the project. It can be up to eight characters long.


Project Type
Type of program that the project builds. You view the list of types by clicking the arrow.


Use Microsoft Foundation Classes
Links the appropriate class library in addition to any other libraries already specified in the project, if selected.


Browse
Displays a dialog box that displays project files in the selected drive and directory. You can select another drive or directory to list other files. You enter the name of the new project file in the text box.


Open Project Dialog

Use the Open Project dialog box to open existing project files.

Options

  File Name

  Directories

  Drives

  List Files of Type

  Use as an External Makefile

Tips and Troubleshooting

You can double-click a filename in the list box to open the file.

If you type a pattern using a wildcard (* or ?) in the File Name box and press ENTER, the list box displays files matching that pattern. This file type subsequently appears as the default when you open this dialog box again.


Allows you to indicate that the selected project should be interpreted as an external makefile. An external makefile is a project file that either was not created with Visual Workbench or was not created in the current Visual Workbench targeting mode.


Edit - Project Dialog

Use the Edit - Project dialog box to add or delete files in existing projects.

Options

File Name	Files in Project
Directories	Add
Drives	Add All
List Files of Type	Delete
Tips and Troubleshooting

You cannot add certain included files to your project using the Edit Project dialog box. These files (with extensions .H, .HXX, .HPP, .INC, .FON, .ICO, .CUR, .mrb, or .DLG) are included automatically when Visual C++ scans the project files for file dependencies.

You can double-click a filename in the list box to add it to the project.

You can double-click a filename in the Files in Project box to delete it from the project.


Files in Project
Lists the files required to build the program specified by the project.


Add
Adds the file selected in the list of files to the project.


Add All
Adds all the files currently displayed in the file list to the project.


Delete
Deletes the file selected in the Files in Project list from the project.


Show Call Stack Dialog
Call Stack Dialog

Use the Call Stack dialog box to examine the function calls that led to the current location in the program that you are debugging.

To display the source code for a calling function from the list box, select the function and click the Go To button. An editor window with the source code appears, and the insertion point in the window is displayed on the currently active line.

Options

  Calls

  Show Function Parameters


Function names in the calling order. The current function [image] the most deeply nested [image] is at the top of the list. Double-click a function to display the source code for the selected function in an editor window, with the insertion point on the currently active line.


Click the check box if you want to show the values of function parameters following function names.


Breakpoints Dialog

Use the Breakpoints dialog box to specify breakpoints. A breakpoint specifies when to halt program execution temporarily. At that point, you can examine values of variables, registers, and so on. A breakpoint can be:

A location in the source file. Program execution halts immediately before the debugger executes the line marked with a breakpoint.

A condition. Program execution halts whenever the condition becomes true.

You can click the arrow to select from the following types of breakpoints:

Break:	When Condition Is:
at Location	Next location that the program executes is specified in the Location box
at Location if Expression is True	Next location that the program executes is specified in the Location box and the expression in the Expression box is true
at Location if Expression has Changed	Next location that the program executes is specified in the Location box and the value in the memory location specified by the Expression box has changed
when Expression is True	The expression in the Expression box is true
when Expression changed	The value in the memory location specified by the Expression box has changed
at WndProc if Message is Received	The program receives the messages specified in the Messages dialog box
Options

Type	Messages
Location	Add
Expression	Enable/Disable
Length	Delete
Breakpoints	Clear All
Tips

When you close a project session, the currently active breakpoints are saved with the project. When you open the project again, those saved breakpoints are set. You can then resume debugging where you left off.

Breakpoints are indicated in your source files by the background color that is selected in the Colors dialog box under the Options menu.

Breakpoints are useful if you have a general idea of the location in your code where you are getting anomalous behavior or what conditions are associated with the anomalous behavior.

You can set breakpoints at a location quickly by moving the insertion point to a line in your source file and then clicking the Breakpoint button on the toolbar or by pressing F9.


Type
The type of breakpoint. You can select from types in the list box.


Location
The location of the breakpoint. You can specify the location in the following ways:

.nnn

nnn is the number of a line in a source file

source_file!.nnn

source_file is a filename, which you can fully qualify with drive and path if it is not in the current directory

{,source_file,}.nnn

source_file is a filename, which you can fully qualify with drive and path if it is not in the current directory

FuncName

FuncName is the name of a function

{function_name,source_file,path_to_exe}FuncName

function_name is the name of a function, source_file is a filename, which you can fully qualify with drive and path if it is not in the current directory, and path_to_exe is the path to the .EXE or .DLL program

 More information on locations


Expression
An expression of type int that is evaluated as true or false, or as a changed value in a memory location. If the expression takes on a value other than zero, it is assumed to be true. You can specify the expression in the following ways:

expression
{function_name,source_file,path_to_exe}expression

function_name is the name of a function, source_file is a filename, which you can fully qualify with drive and path if it is not in the current directory, and path_to_exe is the path to the .EXE or .DLL program. expression can be any valid C or C++ expression.

If you choose the breakpoint type When Expression has Changed, expression can be a starting address, such as a segment and offset or a register. In this case, you must also specify in the Length box the number of bytes in memory to examine for changes.

 More information on expressions


Length
If a "changed" breakpoint is selected in the list of breakpoints, this field is active. It indicates the length of the memory location. The default value is 1, which is 1 times the size of the variable type. Normally, you don't need to change this value. If you are dereferencing a pointer, however, enter the length in bytes of the variable at the location to which the pointer refers.

For instance, if you have declared long *lptr;, and you type *lptr in the expression box, type the length in bytes of a long in the Length box.

The length you specify should always be a positive number.


Breakpoints
The list of breakpoints currently set. A plus sign (+) indicates that the breakpoint is currently enabled. A minus sign (-) indicates that the breakpoint is currently disabled. You can select a breakpoint in this list box, and then disable or enable it, or delete it.


Messages
If you have chosen Break at WndProc, this button displays the Messages dialog box. In the Messages dialog box, you can select a message or a class of messages on which to break.


Breakpoint_Add
Adds the breakpoint with the characteristics that you have defined in the dialog box to the list of breakpoints.


Breakpoint_Delete
Deletes the breakpoint that is currently selected in the Breakpoints box.


Breakpoint_Disable
If the currently selected breakpoint is enabled, click the Disable button to suspend its action temporarily in subsequent debugger operations.

If the currently selected breakpoint is disabled, click the Enable button to restore its action in subsequent debugger operations.


Clear All
Clears all breakpoints that you have set for a program.


Messages Dialog

Use the Messages dialog box to specify the message or class of messages on which to break a debugging session. The program breaks if it recieves the speciifed message(s). You choose a procedure for Windows as the breakpoint in the Breakpoints dialog box.

Options

  Message Type

  Selection

  Class

Tips

In the Breakpoints dialog box, select Break at WndProc if Message is Received from the list in the Type box. This enables the Messages button on that dialog box, which you can then click to choose Windows messages.


Message Type
Choose either an individual message, or one or more classes of messages.


Selection
Select a message. Click a message from the list to break on that message.


Class
Select from one or more message classes. Click a class to add it to your current selections. Click a selected class to remove it from your current selections.


QuickWatch Dialog

Use the QuickWatch dialog box to modify the display in the Watch window. You can quickly add, modify, or expand variables or expressions.

The Current Value list box displays the current value of any variable or expression that you have entered in the Expression text box after you click New Expression or press the Enter key. If the variable is an array or structure, it displays a plus or minus sign in the lefthand column. If the entry displays a plus sign, you can double-click it to expand it. If the entry displays a minus sign, you can double-click it to collapse it.

Options

Expression	New Expression
New Value	Modify Value
Zoom	Add to Watch Window
Tips

Press SHIFT+F9 to display the QuickWatch dialog box.


Zoom
Expands the selected array or structure variable. If the variable is already expanded, it contracts the variable.


Expression
The variable or expression to display or modify.


New Expression
Displays the expression in the Expression text box in the Current Value list, along with its value, or values if it is an array or structure.


New Value
The value to assign to a variable or expression after you press Modify Value.


Add to Watch Window
Adds the variable or expression to the Watch window. If the Watch window is not displayed, it also displays the window.


Modify Value
Modifies the value of the current variable or your expression in your program to have the value in the New Value text box.


Modify Variable Dialog

Use the Modify Variable dialog box to give a new value to a variable in a program that you are debugging. The program subsequently uses that value while it is running in the debugger until the program code sets the value again.

Options

  Variable

  New Value

Tips and Troubleshooting

Press CTRL+F9 to display the Modify Variable dialog box.


Variable
The variable for which you want to set a new value in the New Value text box. By default, the dialog box displays the variable selected in the active source window or the symbol nearest the insertion point in the active source window.


New Value
Type a new value for the selected variable in this field.


Project Options Dialog
Exceptions Dialog

Use the Exceptions dialog box to specify debug actions for system and user-defined exceptions in your program. Exceptions can occur inside or outside exception handlers (sections of code containing structured exception handling statements).  The debugger is always called when an exception occurs.

Options

Exception Number	Name
Action	Exception List
Default	Add
Change	Delete


Exception Number
The unique number of the exception.. System exceptions are defined in WINBASE.H with the prefix of EXCEPTION (for example EXCEPTION_ACCESS_VIOLATION).


Name
Optional name to be displayed in the exception list for the exception.


Action
Action to take when the debugger is notified of an exception. It can take two actions: Stop Always or Stop If Not Handled.

 More on Actions


Exception List
The list of system exceptions that you want to handle. You can modify this list, deleting system exceptions or adding your own exceptions. This information is saved in the project.vcw file (where project represents your project name) and persists with the project.


Default
Restore all default system exceptions to the exceptions list without disturbing any of the user-defined exceptions that have been added.


Add
Add the exception, as specified in the Number and Name text boxes, to the Exceptions List, along with an optional action. The default action, if none is specified, is Stop If Not Handled.

 More on Actions


Change
Accept changes made to the highlighted exception in the Exceptions List. A change might include a different action, for instance.


Delete
Delete the selected exception from the Exceptions List. The debugger still handles deleted exceptions, with the action Stop If Not Handled.

 More on Actions


Project Options Dialog
Threads Dialog

Use the Threads dialog box to select a single thread to debug, if your program has multiple threads. While debugging programs with multiple threads, you can select a thread to debug, suspend a thread, resume running a suspended thread or terminate a thread.

Options

  Thread List

  Suspend

  Resume

  Current Location Display

  Set Focus


Thread List
The Thread list in the Threads dialog box displays status information on each thread as follows:

Thread ID

This is the DWORD that uniquely identifies the thread. When you set focus on a thread, it is displayed in the Thread list with an asterisk next to its identifier.

Suspend Count

This can be a value from 0 to 127.

Priority

This can be one of seven priorities: Idle, Lowest, Below Normal, Normal, Above Normal, Highest, or Time Critical

Current Location

This is the current address of the thread, displayed either as a function name or as an address, depending on the state of the Current Location Display option at the bottom of the dialog box.


Current Location Display
The type of address displayed in the ThreadList. If Function Name is selected, the current function name is displayed if known by the debugger. If no function is known, the address is displayed. If Address is selected, the current address is always displayed.


Suspend
Increments the suspend count of the thread selected in the Thread List. A thread is suspended when its count goes from 0 to 1.


Resume
Decrement the suspend count of the suspended thread selected in the Thread List. A thread resumes when its count goes from 1 to 0.


Set Focus
Make the active thread [image] the thread the debugger recognizes [image] the selected thread in the Thread List.


Project Options Dialog
Profile Dialog

Use the Profile dialog box to examine the behavior of an application when it runs. You can determine which parts of the code it executes, which parts it never executes, the absolute amount of time that it spends executing any part of the code, or the relative amount of time it spends executing any part of the code. You can use this information to determine where to optimize the performance of your code, and to determine what you gained after your optimizations.

Options

Function Timing	Function Sampling
Function Coverage	Line Coverage
Merge	Custom
Advanced Profiler Options
Tips and Troubleshooting

For function timing, you can focus your application's profile by entering /SF functionname in the Advanced Profiler Options dialog box. Profiling begins on entry into that function, continues through all nested functions, and ends on exit from that function.

For function coverage, you can focus your application's profile by entering the following options in the Advanced Profiler Options dialog box:

/SF functionname /EXCALL /INC filename [/INC filename ...]

to exclude all modules and then to include only the module(s) of interest. You can use .LIB, .OBJ, .C, .CPP or .CXX filenames. Profiling begins on entry into the specified function, continues through all nested functions, and ends on exit from that function. The output lists the included functions whether or not they were executed.

To profile an application at the line level, you need to compile the application to include debugging information.

For line coverage, you can focus your application's profile by entering the following options in the Advanced Profiler Options dialog box:

 /EXCALL /INC filename [/INC filename ...]

to exclude all modules and then to include only the module(s) of interest. You can use .LIB, .OBJ, .C, .CPP or .CXX file names. Profiling covers only the specified module(s). You can specify one or more ranges of lines in parentheses following the file name [image] for instance, /INC test.cpp (3-41, 50-67), to cover lines 3 through 41 and lines 50 through 67.


Function Timing
Determine the amount of time (in milliseconds) your program spends in any function, and in each of the functions called. If you enter no function name in the Arguments text box, Profiler times all functions. If you enter /SF functionname, it begins timing with functionname.


Function Sampling
Determine what percentage of its running time the program spent in any function. If you enter no function name in the Arguments text box, Profiler samples all functions. If you enter /SF functionname, it begins sampling with functionname.


Function Coverage
Marks functions that were executed in the program. An asterisk (*)marks functions that were executed; a period (.) marks functions that were not executed.


Line Coverage
Marks lines that were executed in the program. An asterisk (*)marks lines that were executed; a period (.) marks lines that were not executed.


Custom
The Browse button brings up the Select Command File dialog box, which allows you to change drives and directories to select a Profiler command file. A Profiler command file is a batch file containing commands to run the software components of the Profiler with customized switch settings. Command files allow much greater versatility in using the Profiler. See the 32-Bit Source Profiler User's Guide for further information.

The dropdown list box contains the last-used Profiler command files.


Arguments
Any options accepted by PREP.EXE.

 More on advanced Profiler options

See the 32-Bit Source Profiler User's Guide for further information about PREP.


Merge Output
Merges the output from the current profiling run into previous profiling runs. Merged runs depict behavior more accurately in some profiling operations, such as function sampling, or combined results under various environmental conditions.


Project Options Dialog
Select Command File Dialog

Use the Select Command File dialog box to select a profiler command file. Profiler command files are MS-DOS batch files and have the file name extension .BAT.

Options

  File Name

  Directories

  Drives

  List Files of Type

Tips

You can double-click a filename in the list box to select the file.

You can select a file type from the List Files of Type box to display a list of all files with a predetermined type from the current drive and directory.

If you type a pattern using a wildcard (* or ?) in the File Name box and press ENTER, the list box displays files matching that pattern.


Memory Window Options Dialog

Use the Memory Window Options dialog box to specify the behavior of the Memory window.

Options

  Address Expression

  Display Format

  Show Raw Data

  Re-evaluate Expression Always (Live)

  Number of Values per Line

Tips and Troubleshooting

You set default values for the Debug and Release option strings when you choose a project type. You can view or modify either of these option strings in the Compiler Options dialog box.


Address Expression
An address expression that evaluates to a memory address, such as a numeric value, a register, or a variable address.


Display Format
The format applied to display data in the memory window. The dropdown list box includes several formats, from ASCII to Real Long (64-bit float). By default, memory is displayed in Byte (8-bit hex) format, which automatically provides an additional field of ASCII characters to the right.


Reevaluate Expression Always (Live)
Check this box to cause the Memory window to evaluate the address expression continuously and display the resulting memory location in the Memory window. The live address is always displayed at the top of the Memory window.


Show Raw Data
Select this check box to display data in Byte (8-bit hex) format in addition to the display format you choose using the Display Format drop-down list box.


Number of Values per Line
The number of formatted values to put on each line of the Memory window. By default, this is specified as Var. (variable) and is dependent on the dimensions of the Memory window. You can specify an integer number in this text box to specify explicitly the number of columns of values the Memory window.


Project Options Dialog

Use the Project Options dialog box to specify:

The type of project that you want to create.

Custom build options for the compiler and linker, and resources to use, other than the default selections.

The build mode for the project. You can select either Debug or Release to build versions of your program either with or without symbolic debugging information.

Options

Project Type	Resources
Build Mode	Compiler
Linker	Use Microsoft Foundation Classes
Tips and Troubleshooting

You set default values for the Debug and Release option strings when you choose a project type. You can view or modify either of these option strings in the Compiler Options dialog box.

The Build Mode options specify whether to use the Debug or the Release options string when the compiler builds your project.

If you choose a project type, but omit required file types when you add files to your project, you will not be able to build your project. A dialog box will appear informing you that your project is missing a file type. All projects for Windows, for instance, require a .DEF file. If you omit the .DEF file from your project, the dialog box asks if you want to include a default .DEF file, and then edit it. If you don't have the .DEF file, the Build command does not build your program for Windows.

If you create a project initially with a certain project type and set custom options for that type, but later change to another project type (from a type not using p-code to a type using p-code, for example), Visual Workbench changes all the options for the compilers and the linker to the defaults for the new type. It displays a message indicating that it is going to make this change. If you choose Cancel, it reverts to the original project type, and makes no changes to the option strings. You can then examine and record your option selections and retype the desired ones after making the change to the project type.

If you choose a project type, but subsequently set options that represent a different project type, the Build command builds the program using the options that you subsequently set. For instance, when you choose an executable program for Windows, the default options string includes /GA. Later, if you open the Compiler Options dialog box and set /GD, for DLLs for Windows, this option replaces /GA, because these two options are exclusive. The Build command then builds a DLL instead of an executable program.


Project Type
Project type for the current project. Your selection from the list of available types sets appropriate default options for the compiler, linker, and other tools to use with the project. Your selection also sets up the appropriate project structure, with the appropriate source file types.


Compiler
Displays the dialog box for compiler options. You can examine the options currently set or set new options.


Linker
Displays the dialog box for linker options. You can examine the options currently set or set new options.


Resources
Displays the dialog box for setting options for the resource compiler.


Build Mode
Allows you to choose whether or not to include information used by the debugger in your program when you build your project. Your choice determines which options string the compiler uses to build your project. To include or delete options from the debug or release options, click the Compiler button to display the Compiler Options dialog box.


External Projects Options Dialog
External Project Options Dialog

Use the External Project Options dialog box to specify options to use with project files (makefiles) that were not created with Visual Workbench.

Note  This dialog box appears only if you selected Use as an external makefile in the Open Project dialog box when you opened the project, or if you selected External Makefile under Options when creating a project with AppWizard.

Options

Debug Target Name	Debug Build
Project Type	Release Build
Build Mode	Rebuild All Options


Target File Name
Name of the file that Visual Workbench builds with the Build or Rebuild All commands on the Project menu. If it is an executable file (rather than a DLL), it also starts this file in the debugger with commands on the Debug menu or with the Execute command on the Project menu.

If you want to rename the build target, as well as changing it in the Debug Target Name edit box, you must also alter the information in the Debug Build and Release Build edit boxes. You must add the appropriate options used by your build program to change the name of the program that it builds.


Project Type
The type of target that the external makefile builds. Other indicates a static library file.


Build Mode
The command and options string from the Build text boxes to use when you select the Build command on the Projects menu. The Debug option button selects the Debug Build string. The Release option button selects the Release Build string.


Debug Build
Specifies the command line to build the project with symbolic debugging information. This includes the make program name and any arguments that it requires.


Release Build
Specifies the command line to build the project with no symbolic debugging information. This includes the make program name and any arguments that it requires.


Rebuild All Options
Specifies the command line argument to be used when the Rebuild All command on the Project menu is selected. Select the option or options for your make program which cause it to rebuild all its targets unconditionally.

The default option, /a, causes NMAKE.EXE to rebuild all its target files whether or not the dependencies are out of date.


Resource Compiler Options Dialog

Use the Resource Compiler Options dialog box to specify options for the resource compiler. The resource compiler compiles resource files (.RC) and adds that information to your executable for Windows. It can optionally create a .RES file.

Options

  Custom Options

  Defines

Tips and Troubleshooting

When defining symbols in the Defines text box, do not include /d in any definition.

When typing custom options in the Custom Options text box, include the option switch, followed by any optional arguments. For instance, to search the RESOURCES directory on drive D for resource or header files, type:

/i d:\resources

For the resource compiler to succeed, it needs free disk space equal to approximately twice the size of the completed executable.


Custom Options

Allows you to type any of the following options for the resource compiler in the text box:

30	l[im32]
31	m[ultinst]
d	p
e	r
fe newname	t
fo newname	v
i directory	x
k	z


30

Marks the executable file so that it runs with either Windows 3.0 or Windows 3.1.


31

Marks the executable file so that it runs only with Windows 3.1. This is the default option.


d

Defines a symbol for for the preprocessor. You can test the symbol with the #ifdef preprocessor directive.


e

Changes the default location of global memory for a DLL from below the Expanded Memory Specification (EMS) bank line to above the EMS bank line. This option has no effect with Windows 3.1.


fe

Uses the name following the option for the name of the .EXE file.


fo

Uses the name following the option for the name of the .RES file.


i

Searches the specified directory before searching the directories specified by the INCLUDE environment variable.


k

Keeps the segments in the order that they are specified in the .DEF file. It prevents them from being sorted for faster loading.

Normally, you only use this option if the resource compiler doesn't have enough memory to sort the segments, and it issues an error which indicates that you should use the /k option.


l[im32]

Specifies to Windows that the application uses expanded memory directly, according to version 3.2 of the Lotus/Intel/Microsoft Expanded Memory Specification (LIM EMS). This option has no effect with Windows 3.1.


m[ultinst]

Assigns each instance of the application task to a distinct EMS bank when Windows is running with version 4.0 of the Lotus/Intel/Microsoft Extended Memory Specification (LIM EMS). If not specified, all instances of a task share the same EMS bank. This option has no effect with Windows 3.1.


p

Creates a private DLL that is called by only one application. This allows Windows to use memory more efficiently. This option has no effect in Windows 3.1.


r

Creates a .RES file from an .RC file. Use this option when you do not want to add the compiled .RES file to the .EXE file.


t

Creates an application that runs with Windows only in protected mode (standard or 386 enhanced), not in real mode. This option has no effect with Windows 3.1.


v

Displays messages that report on the progress of the compiler.


x

Prevents the resource compiler from checking the INCLUDE environment variable when searching for header or resource files.


z

Prevents the resource compiler from checking for RCINCLUDE statements. If you have not used RCINCLUDE statements, using this option can greatly improve the speed of the resource compiler.


Defines

Allows you to define symbols for the preprocessor. You can test the symbols with the #ifdef preprocessor directive.

The symbols defined in the Debug text box are used when you select the Debug build mode. The symbols defined in the Release text box are used when you select the Release build mode.

Do not enter the /d option with the symbols to be defined.


Debug Dialog (.EXE)
Debug Dialog

Use the Debug dialog box to specify values required to run and debug an executable program.

Options

  Program Arguments

  Additional DLLs

  Hexadecimal Display

  Single debug source window

Tips and Troubleshooting

You can debug only 32-bit programs written for Windows NT with the Visual Workbench debugger.


Debug Dialog (DLL)
Debug Dialog

Use the Debug dialog box to specify values required to run and debug a dynamic-link library (DLL).

Options

  Calling Program

  Additional DLLs

  Hexadecimal Display

  Hexadecimal constants in uppercase

  Single debug source window

Tips and Troubleshooting

To debug the DLL, you must specify the program which calls it in the Calling Program text box. This can be either a program that you are developing, or a program that already exists, such as Microsoft Excel.


Program Arguments
Command-line arguments that the program requires when it starts running. The Go and Restart commands start the program using these arguments. This text box does not appear when the debugging target is a DLL.


Calling Program
Name of the program that calls the DLL being debugged. This text box appears only when the debugging target is a DLL.


Additional DLLs
Names of any additional DLLs for which you want symbolic debugging information loaded. You can then set breakpoints in those DLLs.


Hexadecimal Display
A check in the Hexadecimal Display check box indicates that the values are displayed in hexadecimal format. If Hexadecimal Display is not checked, the values are in decimal.


Single debug source window
A check in the Single debug source window check box indicates that the each time a new source file is entered when stepping through instructions or at a breakpoint, the source file is displayed in the existing source file window rather than opening a new window. If Single debug source window is not checked, a new source window is opened each time a new file is entered.


Directories Dialog

Use the Directories dialog box to specify which directories to search for executable files, include files, run-time libraries, help files, and C++ class libraries.

The Executable Files Path, Include Files Path  and Library Files Path boxes each have a drop-down list. You can:

Select a path from the list.

Add directories to the current entry by typing a semicolon (;) before each added name and then the directory name.

Add new paths to the list, by deleting the currently displayed path and entering a new one. The currently displayed path is retained in the list.

You can have up to four paths in each list. If you add a path, and you already have four in the list, Visual Workbench deletes the least recently used path. Visual Workbench displays the most recently used path, and makes it the current path.

The Help Files Path and MFC Files Path boxes are editable text boxes. You must separate directories in these paths with a semicolon (;).

Options

 Executable Files Path

 Help Files Path

 MFC Files Path

 Include Files Path

 Library Files Path

Tips and Troubleshooting

To specify more than one directory for a category, separate them with a semicolon (;).

When an #include directive is encountered in a program (and a complete path is not provided), the compiler searches for the file in this order:

1.	The current directory.

2.	The path or paths specified with the /I option, if you have set that option in the Compiler Options dialog box under Project on the Options menu.

3.	The paths specified in the Include Files path.


Executable Files Path
Directories to search for executable files. By default, this box displays the directory in which you installed Visual C++. If you regularly use tools that are not in the directory with the Visual C++ executables when building projects, you can add the directory to this entry.

If you are using different compilers for different projects, you can create a path for each compiler by deleting the current path from the text box and typing the new path in the list box. The current path is retained in the list in the drop-down list box. You can subsequently use the drop-down list box to choose among the four most recently used paths.


Include Files Path
Directories to search for include files.

If you are using different include files for different projects, you can create a path for each include file directory by deleting the current path from the text box and typing the new path in the list box. The current path is retained in the list in the drop-down list box. You can subsequently use the drop-down list box to choose among the four most recently used paths.


Library Files Path
Directories to search for run-time libraries.

If you are using different libraries for different projects, you can create a path for each library file directory by deleting the current path from the text box and typing the new path in the list box. The current path is retained in the list in the drop-down list box. You can subsequently use the drop-down list box to choose among the four most recently used paths.


Help File Path
Drive and path for the Visual C++ help files.


MFC Files Path
Directories to search for C++ class libraries.


Editor Dialog

Use the Editor dialog box to specify various characteristics and behaviors of the editor in Visual Workbench.

Options

  Tab Settings

  Scroll Bars

  Source Files

  Undo Buffer Size (K bytes)


Tab Setting
The number of tab stops in the editor window, and how they are maintained in the saved file. If you choose Keep Tabs, the files are saved with tab characters. If you choose Insert Spaces, the white space preceding each tab position is replaced by an equivalent number of spaces.


Scroll Bars
Select whether to display either horizontal scroll bars or vertical scroll bars, or both, in editor windows.


Source Files
In this group, you can select whether or not to:

Save the latest changes to files before running tools.

Prompt before saving files before building the project.

Open .RC files in App Studio and display the resources defined in the .RC file as graphic elements and properties. The default behavior is to open .RC files as text in an editor window.

Use a modeless dialog box for Search and Replace commands. If you select a modeless dialog, it remains open at the top of the screen, but allows you to modify the file in the window.

Create a new source window when opening a file, if the window with the focus is a source window and you have not modified the contents of the window.


Undo Buffer Size
The size, in 1K byte increments for the undo buffer, which the Undo and Redo commands use to save the latest commands. The range of acceptable values is from 0 to 64, with a default size of 4. A value of 0 disables the Undo and Redo commands. The oldest commands are deleted from the buffer when it fills. The larger the buffer, the more commands that are saved.


Workspace Dialog

Use the Workspace dialog box to name up to three window arrangements for a project, called workspaces, and to load a specified workspace automatically when you start the project.

Options

Workspace #1	Initial Workspace
Workspace #2	Prompt Before Redefinition
Workspace #3	Close Non-Workspace Windows on Load
Tips

You can pick any name that you want to give to workspaces in the Workspace dialog box. The names are a convenient way for you to relate window arrangements to your work habits and preferences. These names appear on the cascading menus under Load/Save Workspace on the Project menu. An ampersand before a letter in the name identifies it as an accelerator key.

The following table shows what happens to open windows when you open a project with the various combinations of settings for Initial Workspace and Close Non-Workspace Windows on Load. Numbered Workspace refers either to one of the numbered workspaces or Last Workspace Used.

	Close Non-Workspace Windows on Load Option
Initial Workspace Option	Checked	Unchecked
Numbered Workspace	Open windows are closed	Open windows are minimized
None	Open windows are unchanged	Open windows are unchanged


Workspace #1
Name of the first window arrangement. The default name is Edit. Use an ampersand (&) to mark the letter to use as an accelerator on the Load Workspace and Save Workspace cascading menus on the Project menu.


Workspace #2
Name of the second window arrangement. The default name is Debug. Use an ampersand (&) to mark the letter to use as an accelerator on the Load Workspace and Save Workspace cascading menus on the Project menu.


Workspace #3
Name of the third window arrangement. The default name is Custom. Use an ampersand (&) to mark the letter to use as an accelerator on the Load Workspace and Save Workspace cascading menus on the Project menu.


Initial Workspace
Name of the workspace to display when you initially load the project. You can choose to display no workspace, to display a predefined workspace, or to display the last workspace used.

If you choose Last Workspace Used, the last arrangement of windows used when you close the project is displayed again when you next open the project. This allows you to readily begin again where you previously left off.


Prompt before Redefinition
Choose whether or not to be notified that you are replacing an existing workspace definition if you save a workspace.


Close non-workspace
Choose whether or not to close any open windows not belonging to the newly loaded workspace. If you clear the check box, open non-workspace windows are minimized if the Initial Workspace is a numbered workspace or Last Workspace Used. If Initial Workspace is None, open non-workspace windows are not affected.


Font Dialog

Use the Font dialog box to select a font and its characteristics to use in the current window or to use as the default in all windows.

The Sample box shows the font in the selected style and size, as it will appear in windows on your display.

Options

  Font

  Font Style

  Size

  Use as Default Font

Tips and Troubleshooting

Open windows display a new default font only if they are closed and then opened again.

To restore the displayed font to its startup characteristics if you have selected a new default font, select Courier 10-point regular.


Font
Select a font from the list displayed. These are the fonts installed with Windows on your computer.


Font Style
Select a style from the list displayed for the chosen font. The list displayed depends on the installed font. Besides regular, you may be able to choose bold, italic, or combined bold and italic styles.


Size
Select a point size from the list displayed for the chosen font. The sizes available depend on the installed font.


Default Font
Make the current font selections the default choices for files displayed in editor windows.


Color Dialog

Use the Color dialog box to set the colors for various text elements of the Visual Workbench screen display.

Options

Items	Syntax Coloring
Restore All Defaults	Foreground Color
Restore to Default	Background Color


Items

Items in this box are the text elements for which you are changing the color. Select an item from the list and then select the foreground and background colors for that item. Alternatively, you can restore the default color combination for the item by clicking Restore to Default.

The list box always includes the following items:

Item	Coloring Affects
Watch Window	Entire window
Locals Window	Entire window
Registers Window	Entire window
Output Window	Entire window
Breakpoint Line	Line in editor window with breakpoint
Current Line	Line in editor window with insertion point
Error Line	Line in editor window with error
Bookmarked Line	Line in editor window with bookmark (tag)
Text Selection	Selected text in editor window
Assembly Line	Line in editor window with assembly language code
Source Text (Default)	Foreground and background in editor windows for elements not otherwise specified
The following items appear in the box only if Syntax Coloring is checked:

Item	Coloring Affects:
Keyword	C keywords
C++ Keyword	C++ keywords
Identifier	Function names, symbol names, defined symbols, and so on
Comment	C and C++ comments
Number	Integers and longs
Real	Floating point numbers
String	Characters delimited by double quotes


Restore to Default
Restores the selected item to its default color combination.


Restore All Defaults
Restores all items to their default color combinations.


Syntax Coloring
Displays or removes language elements in the list of items. The elements are:

Keyword

C++ Keyword

Identifier

Comment

Number

Real

String


Foreground Color
The color used to display characters.


Background Color
The color behind the characters.


Tools Dialog

Use the Tools dialog box to add programs to the Tools menu. You can then start the programs by selecting them from the Tools menu.

Options

Menu Contents	Redirect to Output Window
Command Line	Close Window on Exit
Menu Text	Add
Arguments	Delete
Initial Directory	Move Up
Ask for Arguments	Move Down
Tips and Troubleshooting

You can use predefined macros in the Arguments box.

To pipe the output of a command-line program to another tool, or to redirect the output to a file, you need to start an MS-DOS shell to run the program. In the Command Line text box, enter C:\sysdir\CMD.EXE (use the appropriate drive and directory for your system). In the Arguments box, type /c programname, followed by pipes or redirections and program or output file names. If you want a window to stay open after the command or program terminates, you can edit _DEFAULT.PIF to change the Display Usage option from Full Screen to Windowed, and clear the Close Window on Exit check box.  Under Windows, COMMAND.COM runs a virtual MS-DOS machine using _DEFAULT.PIF when it is invoked.

If you are adding a command-line program that has an existing .PIF file, the specification for the startup directory in the .PIF file overrides the directory that you specify in the Initial Directory box. To avoid confusion, make the specification the same in both the .PIF file and in the Initial Directory box.

If you are adding a command-line program, you may want the MS-DOS window to stay open after the program finishes in order to examine the output on screen. In this case, edit the .PIF file and clear the Close Window on Exit check box.

Only console applications written for Windows NT can send their output to an Output window.


Menu Contents
The list of programs currently displayed on the Tools menu.


Path Name
The file specification necessary to run the program. This can include the drive and directory path, and must include the filename for the program.


Menu Text
The text that you want to appear on the Tools menu to identify this program.


Arguments

Any combination of static command-line arguments and dynamic macro arguments that the program requires to run properly. Visual Workbench always starts the program with these arguments.

Note  The length of arguments plus the expansion of any of the following macros cannot exceed the permissible length for an MS-DOS command line.

You can use the following predefined dynamic macros in the argument list:

Macro	Description
$File	Current fully qualified source file name. It is null if a non-source window is active.
$FileName	Current source file basename and extension. It is null if a non-source window is active.
$FileDir	Current source file drive and directory (ending in \). It is null if a non-source window is active.
$Proj	Current project basename. It is null if no project is currently open.
$ProjDir	Current project drive and directory (ending in \). It is null if a non-source window is active.
$Line	Current line containing the insertion point within the active window.
$Col	Current column containing the insertion point within the active window.
$Dir	Current working directory (ending in \).
$Target	Current project target name. If the project is an external project, it is the name in the Target File Name box in the External Project Options dialog box. Otherwise, it is the same as $Proj.EXE.
$RC	The .RC file in the current project, if any. For external projects, it is always $Target.RC.


Initial Directory
The current directory when the program runs. Visual Workbench changes to this directory before starting the program. You can use the predefined macros described for the Arguments option.

Note  If you are adding a program that has an existing .PIF file, the specification for the start-up directory in the .PIF file overrides the directory that you specify in the Initial Directory text box. To avoid confusion, make the specification the same in both the .PIF file and in the Initial Directory box.


Ask for Arguments
When checked, displays a dialog box for additional arguments for the program each time you start the program. In addition to the arguments that are automatically used every time the program starts, you can enter arguments for each particular instance of the program.


Redirect to Output Window
When checked, the output from the tool is displayed in an Output window. Each tool uses its own separate Output window. You can switch among Output windows using the Windows menu.

Note  Only console applications written for Windows NT can send their output to an Output window.


Close Window on Exit
When checked, the tool's Command window closes automatically when the tool finishes executing.


Add
Displays the Add Tools dialog box. After you select the drive and directory to examine, you can pick a program from the list displayed. When you dismiss the dialog box, the program appears in the Menu Contents list, with its name and path in the text boxes. You can then specify additional information for the tool.


Delete
Deletes the program currently selected in the Menu Contents list from the Tools menu.


Move Up
Moves the identifying text that is currently selected in the Menu Contents list up one position in the list.


Move Down
Moves the identifying text that is currently selected in the Menu Contents list down one position in the list.


Tool Arguments Dialog

The Tool Arguments dialog box appears when you start a tool from the Tools menu if you have previously checked Ask for Arguments in the Tools dialog box. It allows you to specify different arguments each time the program starts.

Option

  More information on Arguments

Tip

Specify arguments to be used automatically every time the program runs by entering them in the Arguments box in the Tools dialog box.


Arguments
More Information on Arguments

This option is completed by any combination of static command-line arguments and dynamic macro arguments that the program requires to run properly. Visual Workbench starts the program with these arguments only in this instance.

Note  The length of arguments plus the expansion of any of the following macros cannot exceed the permissible length for an MS-DOS command line.

You can use the following predefined dynamic macros in the argument list:

Macro	Description
$File	Current fully qualified source file name. It is null if a non-source window is active.
$FileName	Current source file basename and extension. It is null if a non-source window is active.
$FileDir	Current source file drive and directory (ending in \). It is null if a non-source window is active.
$Proj	Current project basename. It is null if no project is currently open.
$ProjDir	Current project drive and directory (ending in \). It is null if a non-source window is active.
$CmdLine	Command-line arguments passed to the application (from the Debug dialog box on the Options menu).
$Line	Current line containing the insertion point within the active window.
$Col	Current column containing the insertion point within the active window.
$Dir	Current working directory (ending in \).
$Target	Current project target name. If the project is an external project, it is the name in the Target File Name box in the External Project Options dialog box. Otherwise, it is the same as $Proj.EXE.
$RC	The .RC file in the current project, if any. For external projects, it is always $Target.RC.


Add Tool Dialog

Use the Add Tool dialog box to select the drive and directory to examine and then to pick a program from the list displayed. When you dismiss the dialog box, the program appears in the Menu Contents list of the Tools dialog box, with its name and path in the text boxes. You can then specify additional information for the tool.

Options

  File Name

  Directories

  Drives

  List Files of Type

Tips and Troubleshooting

If you type a pattern using a wildcard (* or ?) in the File Name box and press ENTER, the list box displays files matching that pattern. This file type subsequently appears as the default when you open this dialog box again.


Find file Dialog
Find Source Dialog

Use the Find Source dialog box to specify the path for the specified file when Visual Workbench does not find a file. This may happen if a source file has been moved from the project directory before starting a debugging session, or if an executable file is not in the directory specified during Setup.

Option

  Please enter the path for FILENAME


Path
Type the path for file.


Resolve Ambiguities Dialog

Use the Resolve Ambiguities dialog box to select the correct symbol reference for breakpoints in the debugger. If you choose to examine information about a C++ symbol, because of function overloading the debugger may find more than one C++ symbol with the same name in the symbolic debugging information.

Select the appropriate symbol in the list box to set the desired breakpoint.

Options

None


Symbols Dialog

Use the Symbols dialog box to select the correct symbol reference in the Browser. If you choose to examine information about a C++ symbol, because of function overloading the Browser may find more than one C++ symbol with the same name in the symbolic debugging information.

Select the appropriate symbol in the box to view the desired browser information.

Options

None


About Box

The About box contains information about the running application and about your system. In particular, it indicates the version number of the program.


MFC AppWizard Dialog

Use the AppWizard dialog box to create a complete suite of files for a new application for Windows using the Microsoft Foundation Class libraries. You can also use the Options button to select a variety of different features to be included in, or excluded from, your application. The Classes button allows you to change the proposed names for classes in your application.

Options

Project Name	Drive
Directory	Options
New Subdirectory	Classes
Tips

When you type a project name, this name is appended to the displayed path as a subdirectory, as well as being used for the project file name.

If you use the drive and directory controls to select a location for your application, the displayed path changes automatically. The project name that you entered is automatically appended to new drive and directory choices.


Project Name
The name for the project file. This name is also used to create other candidate names for components of the application.


Subdirectory
The subdirectory for the project's files. AppWizard creates this subdirectory if it doesn't exist.


Options
Choices for inclusion of comments in generated code, or code support for various user interface features and application programming interfaces.


Classes
Allows you to change the default choices for class names, filenames, file extensions and document type names for your new application.


Options Dialog

Use the Options dialog box to select code and class library support required for your application.

Options

Multiple Document Interface	Context Sensitive Help
Initial Toolbar	External Makefile
Printing and Print Preview	Generate Source Comment
OLE Client
Tips and Troubleshooting

If you choose the option to include a toolbar with your application, you need to edit the bitmap that is added to your suite of files. Use App Studio to edit the bitmap.


Multiple Document Interface
Generate skeleton code for a Multiple Document Interface application. An MDI application has multiple child windows for documents. Microsoft Word for Windows is an example.

If you clear this check box, AppWizard generates skeleton code for a Single Document Interface (SDI) application. An SDI Application has one document window only. The Windows Notepad is an example.


Generate Source Comments
Generates comments in the source code indicating where you need to add functionality required to complete your application.


Initial Toolbar
Adds a toolbar bitmap to your project, and adds the code to display the bitmap. This option also adds code to display a status line.


Support Printing
Adds the menu commands for printing and print preview, and adds the code to call the appropriate class library functions for printing.


Support VBX
Adds the function call to initialize support for Visual Basic controls.


Support Help
Adds the function calls to initialize and display Windows help. In addition, it creates a subdirectory for the components of your Windows help files and creates template files for building a Windows help file.


Support OLE
.

Generates application support code for OLE links and embedded objects in documents. The document class for your application is derived from COleClientDoc instead of CDocument.


External Makefile
Creates a makefile that can be edited directly for use with the NMAKE utility. You must then open this project file as an external project file. The default choice is to create a makefile for use with Visual Workbench.


Classes Dialog

Use the Classes dialog box to alter proposed choices for filenames, class names, document names and filename extensions when creating a new application with AppWizard. The proposed names are based in part on the project name that you chose.

Options

New Application Classes	Implementation File
Class Name	File Extension
Base Class	Doc Type Name
Header File


Classes
Lists the classes generated by AppWizard for the application type that you selected. You can click a class in this box to display the information corresponding to the class in the text boxes. You can then alter the proposed choices, if you wish.


Class Name
The name of the class for your application. The initial candidate name uses part of the project name that you entered, except in the case of CMainFrame. You can type another name, if you choose.


Base Class
The name of the base class in the Microsoft Foundation Class library from which the selected class is derived.


Header File
The name of the header file that AppWizard creates for the selected class. You may change the name for all classes except the application class. The name of the header file for the application class is always based on the project name.


Implementation File
The name of the file containing implementation code that AppWizard creates for the selected class. You may change the name for all classes except the application class. The name of the implementation file for the application class is always based on the project name.


File Extension
The three-character filename extension used for document files created by your application. This applies only to document classes.


Doc File Type
The default name applied to document types in your application. This applies only to document classes. If your application supports multiple document types [image] spreadsheets and charts, for instance [image] this name appears in dialog boxes for selecting document types.


New Application Information Dialog

Use the New Application Information dialog box to accept the classes that your new application creates, the header and implementation files to contain those files, and the optional features that your application supports. It also displays the directory path for those files, with the subdirectory that it creates for them.

Note  To view all the information in the list, click the list or tab to it. You can then use the ARROW keys to see all the information.

The Create button creates the subdirectory, the skeleton files and the skeleton classes.

Cancel returns you to AppWizard to revise the choices for your application.


ClassWizard Dialog

Use the ClassWizard dialog box to add message-handling classes to your project. With these message-handling classes, you can specify member functions to handle messages sent from command user-interface objects or from Windows. ClassWizard creates the message map entries and member function declarations. You can display the skeleton of the member function in a Visual Workbench editor window and create the code to handle the message. You can also add and edit member variables associated with controls in a dialog box.

For classes derived from CDialog or CFormView, create the resource first in App Studio. Then use the resource identifier from App Studio when you create the class.

Options

Class Name	Class Info
Object IDs	Edit Variables
Messages	Add Function
Member Functions	Delete Function
Add Class	Edit Code
Tips

If you delete a member function, the declaration is deleted from the class in the header file, and the message map entry is deleted from the implementation file. You must delete the function code and any references to the function manually.

To add a function and edit its related code, or to view class information, you should make your selections in this order:

1.	Select a class name.

2.	Select an Object ID.

3.	Select a Message.

You can then select an associated function to edit or delete, or click the Add Function button to add a member function to the class.

After you've added a new member function, choose Edit Code to add the implementation code for the function. A Visual Workbench editor window with the file containing the class for the member function appears, with a highlighted comment indicating where to add your code.

You can select a function and then click Edit Code to locate and examine code quickly.

Edit Variables is available only in classes with a data map. This includes dialog and form view classes.


Class Name
Name of a class in your application. You can select classes from the list box.


Object IDs
The IDs that can generate messages, such as menu items, dialog box controls, and so on. The first entry in theis list is always the name of the current class.


Messages
The messages that the selected object in the Object IDs list can handle. If you select the name of a class associated with a window in the Object IDs list, this list then shows the Windows messages that the window can receive.


Member Functions
The member functions in the selected class. These member functions are message-handler functions.


Add Class
Allows you to create a new class derived from a class in the CCmdTarget class hierarchy.


Class Info
Displays information about the selected class. It also allows you to choose the filter for messages to be displayed in the Messages list.


Edit Variables
Allows you to create member variables associated with dialog box controls and specify their attributes for dialog data exchange and validation routines (DDX/DDV) built into the Microsoft Foundation Class library.


Add Function
Adds a member function to handle the selected message.


Delete Function
Deletes the member function declaration from the header file and the function reference from the message map for the selected function.

Note  You must manually delete the function code and any references to the function.


Edit Code
Opens an editor window with the insertion point at the selected member function. Here you insert code for the actions that a member function takes when its corresponding object receives a message. This code defines the message handler for that object.

In classes derived from CDialog, for instance, the handler member function is called when a dialog box receives a control notification message indicating an action involving a control in that dialog box.


Select Class Dialog

Use the Select Class dialog box to select the class to be associated with a new resource. If you choose a class from this list, the information about the class appears automatically in the ClassWizard's controls.

Option

 Class List


Class List
The list of classes defined in the current project.


Add Class Dialog

Use the Add Class dialog box to add new message-handling classes to your application. ClassWizard automatically creates a message map for the class, and updates it when you add or delete the message-handling functions.

Options

Class Name	Header File
Class Type	Implementation File
Dialog ID	Browse
Import Class	Select Class
Tips

If you are importing several classes, you can save time by rebuilding the .CLW file rather than importing each class separately. You can completely rebuild the file by deleting the project's .CLW file, and then opening ClassWizard from App Studio. Answer Yes when asked if you want to rebuild the .CLW file. Then use the Select Source Files dialog box to provide ClassWizard with a list of files in your project.


Class Name
The name of the new class that you want to add.


Class Type
The type of class that you want to add. The class that you add is derived from the class that you select in the drop-down list box.


Header File
The name of the file to contain header information for the added class.


Implementation File
The name of the file to contain implementation code for the added class.


Dialog ID
The resource identifier of the dialog. App Studio records this identifier when you create the dialog.


Browse
Click this button to select from a file list of the appropriate type: either .CPP files or .H files.


Import Class
Click this button to add a message-handling class from another project.


Select Class
Click this button to select an existing class from the current project. When you dismiss the Select Class dialog box after selecting a class, the Add Class dialog box is also dismissed and the fields in the Class Wizard dialog box are filled with information from the selected class.

Note  This button appears only if a new resource is selected in App Studio.


Browse Files Dialog

Use the Browse Files dialog box to select a file.

Options

  File Name

  Directories

  Drives

  List Files of Type

Tips

You can double-click a filename in the list box to select the file.

You can select a file type from the List Files of Type box to display a list of all files with a predetermined type from the current drive and directory.

If you type a pattern using a wildcard (* or ?) in the File Name box and press ENTER, the list box displays files matching that pattern.


Import Class Dialog

Use the Import Class dialog box to add message-handling classes copied from another project to the ClassWizard .CLW file (project.CLW).

Options

  Class Name

  Header File

  Implementation File

  Browse

Tips

If you are importing several classes, you can save time by rebuilding the .CLW file rather than importing each class separately. You can completely rebuild the file by deleting the project's .CLW file, and then opening ClassWizard from App Studio. Answer Yes when asked if you want to rebuild the .CLW file. Then use the Select Source Files dialog box to provide ClassWizard with a list of files in your project.


Class Name
The name of the class that you want to import.


Header File
The name of the file to contain header information for the imported class.


Implementation File
The name of the file to contain implementation code for the imported class.


Class Info Dialog

Use the Class Info dialog box to determine the characteristics of the selected class.

Options

Class Name	Header File
Base Class	Implementation File
Resource	Message Filter


Class Name
The name of the selected class.


Base Class
The class from which the selected class is derived.


Resource
The resource ID associated with the class, if it is a dialog class.


Header File
The name of the file containing header information for the selected class.


Implementation File
The name of the file containing implementation code for the selected class.


Message Filter
Select a filter for the Messages box in the ClassWizard dialog box. For the class indicated, the list box displays only those messages that correspond to the filter that you select. Window is the most inclusive list. Other choices exclude certain messages.


Edit Member Variable Dialog

Use the Edit Member Variable dialog box to add member variables associated with dialog box controls to a dialog box class or to edit their characteristics. Member variables created with ClassWizard automatically use the Microsoft Foundation Class library's built-in routines for dialog data exchange and validation (DDX/DDV).

Options

Class Name	Maximum Value
Control	Add Variable
Maximum Characters	Delete Variable
Minimum Value


Class Name
Class NameThe name of the class whose member variables you are editing.


Control
The list of controls in the dialog box that you can map to member variables. The type column displays the type for the member variable. The member column displays the name of the member variable.


Max Characters
If a member variable is type CString, you can specify the maximum allowable number of characters that the user can enter in the text box. Otherwise, this box does not appear.


Minimum Value
If a member variable is a numeric type (int, UINT, float, etc.), you can specify the minimum value that the user can enter in the text box. Otherwise, this box does not appear.


Maximum Value
If a member variable is a numeric type (int, UINT, float, etc.), you can specify the maximum value that the user can enter in the text box. Otherwise, this box does not appear.


Add Variable
Allows you to add a member variable for the selected control.


Delete Variable
Deletes the selected member variable.


Add Member Function Dialog

Use the Add Member Function dialog box to specify the name of a message-handling member function that you add to a dialog class.

Option

  Member Function Name

Tips

By convention, the names of all message-handling functions in the class library begin with the prefix On.


Member Function Name
The name of the message-handling function to add. To maintain the naming convention, append to the proposed prefix On.


Add Member Variable Dialog

Use the Add Member Variable dialog box to specify the names, properties, and types of member variables that you add to a dialog class.

Options

  Member Variable Name

  Property

  Variable Type

Tips

By convention, the names of all member variables begin with the prefix m_.


Member Variable Name
The name of the member variable to add. Since member variables use the prefix m_ by convention, add a variable name to the prefix to maintain the convention.


Property
The property for the variable. The property indicates whether the variable contains a value or is an object of the control's type. A variable that is an object of the control's type allows you to work with the control at run-time. The list of properties depends on the control.


Variable Type
The type for the member variable. The list of types depends on the control and the property selected.


Repair Class Information Dialog

Use the Repair Class Information dialog to:

Delete obsolete classes from the ClassWizard .CLW file.

Update the information in the .CLW file with new names or locations of classes that you have changed.

Options

  Class Name

  Implementation File

  Remove

  Header File

  Browse

Tips

You can completely rebuild the information used by ClassWizard by deleting the project's .CLW file, and then opening ClassWizard from App Studio. Answer Yes when asked if you want to rebuild the .CLW file. Then use the Select Source Files dialog box to provide ClassWizard with a list of files in your project.


Class Name (Repair)
The name of the class that you want to repair.


Header File (Repair)
The name of the file to contain header information for the repaired class.


Implementation File (Repair)
The name of the file to contain implementation code for the repaired class.


Browse
Click this button to select from a list of files.


Remove
Click this button to remove information about a class from the ClassWizard information file (project.CLW).


Rebuild ClassWizard Database
The ClassWizard .CLW file for this project has been deleted, or is out of date or corrupted. You may have deleted classes from your project, for instance. If you select Yes, ClassWizard asks you to confirm the files contained in the project, and then creates another .CLW file containing information about the classes in your project.


Select Source File Dialog

Use the Select Source File dialog box to add or delete files in existing projects when rebuilding the ClassWizard .CLW file (project.CLW). It initially lists all the files contained in the project, and you can add or delete files if necessary.

Options

File Name	Files in Project
Directories	Add
Drives	Delete
List Files of Type
Tips

You can double-click a filename in the list box to add it to the list of files used to build the .CLW file used by ClassWizard.

You can double-click a filename in the Files in Project list box to delete it from the list.


Files in Project
Lists the files required to build the ClassWizard .CLW file for the program specified by the project.


Add
Adds classes in the file selected in the list of files to the ClassWizard .CLW file for the project.


Delete
Deletes the file selected in the Files in Project list from the list. The file that you remove is not used to build the ClassWizard .CLW file.


Search Dialog

The Search dialog box is opened either:

By choosing the Search for Help On command from the Help menu.

By pressing F1 on a keyword in a source file when help on the "keyword" exists in more than one help file. (A keyword in help is any language element you wanted help on [image] functions, language keywords, messages, class names, and so on.) For example, help on the function CreateBitmap exists in both the Foundation Class Library help and the Win32 SDK help, since both libraries include the CreateBitmap function. If you request help on CreateBitmap from a source file, the Search dialog lets you choose the help topic you would like to see [image] the topic in Foundation Class Library help or the topic in the Win32 SDK help.

Options

 Help Keyword

 Files

Help Files You Can Search

With the Search for Help On command, you can search for a help keyword in these reference help files:

On the Help menu:

Build Tools

C/C++ Language

Foundation Classes

Win32 SDK

Installed with Visual C++ but not on the Help menu:

ERRORS.HLP (Build Errors)

If you open the Search dialog from a source file by pressing F1 with the insertion point on a keyword, it can list any of the files listed above.

Note  You cannot get help on Visual Workbench or App Studio procedures from the Search dialog.

Tips

If the help keyword appears in more than one help file, the Files box lists those Help files. You then choose which help file to open. If the selected help file contains more than one instance of the help keyword, the Search dialog box for that help file appears.

If the Search dialog appears after you have requested help from a source file, the keyword is automatically displayed in the Help Keyword box.

If the selected help file contains more than one instance of the help keyword, the Search dialog box for that help file appears.


Help Keyword
The item that you want to find. This can be a language element, a function name, or any other keyword that you type into the text box. It can also be an element in a source file, either selected or at the position of the insertion point at the time you press F1.


Files
The Help files that contain the help keyword that you entered, if there are instances in multiple help files. To display the help file containing the appropriate help, select the desired help file in the list box, then click OK or double-click the desired help file.


Browse Window

Use the Browse window to view relationships among symbols in your project. You can view relationships among derived classes and their base classes, or among called and calling functions. You can also find the locations where your code defines a symbol as well as all the locations where it references that symbol.

In the Query group, you choose which types of information that you display. When you click Display Result, the results of that query are displayed in the panes in the lower portion of the window. The type of information displayed and the number of panes displayed depend on the type of query.

Options

Type	Previous Query
Subset	Expand Tree
Symbol	Collapse Node
Display Result
Tips

You can double-click selected nodes in graphs to expand and collapse them.

You can resize the panes in the window by moving the mouse pointer between the panes, and dragging the pane border in the desired direction.


Type
The type of symbol relationship to display. You can choose from:

Definitions and References
Call Graph
Caller Graph
Derived Class Graph
Base Class Graph


Subset
The subset of symbol types for definitions and references. This potentially narrows your search for information.You can choose either ALL symbols or:

Functions
Variables
Types
Macros
Classes


Symbol
The name of the symbol for which you want information. You can use a partial name followed by * to select multiple symbols and then you can choose the specific one that you want. If the symbol is a class name, you can follow it with a double colon to display all the members of the class.


Display Result
Display the results of the query in the panes of the browse window.


Previous Query
Display the results of the previous query. It restores the previously used entries to the Query boxes.


Expand Tree
Expand completely the tree in a displayed graph. If you want to expand a node only, double-click it.


Collapse Node
Collapse a displayed graph from a selected node down. You can also double-click a node to collapse a node.


Keyboard Shortcuts
Action	To:	Press
Move insertion point	Move one character left	LEFT ARROW
	Move one character right	RIGHT ARROW
	Move one word left	CTRL+LEFT ARROW
	Move one word right	CTRL+RIGHT ARROW
	Move one line up	UP ARROW
	Move one line down	DOWN ARROW
	Move to the first indentation of current line	HOME
	Move to the beginning of current line	HOME, HOME
	Move to the first indentation of next line	CTRL+ENTER
	Move to the end of line	END
	Move to the beginning of the file	CTRL+HOME
	Move to the end of file	CTRL+END
Delete, insert, copy	Delete one character to the left	BKSP
	Delete one word to the left	CTRL+BKSP
	Delete one character to the right	DEL
	Delete to the end of the word	CTRL+T
	Delete selected text and copy to Clipboard	CTRL+X, SHIFT+DEL
	Turn keyboard insert mode on or off	INS
	Copy selected text to Clipboard, keeping it	CTRL+C, CTRL+INS
	Insert contents of Clipboard	CTRL+V, SHIFT+INS
	Copy current line to Clipboard, deleting it	CTRL+Y
	Undo the last edit	CTRL+Z, ALT+BACKSPACE
	Redo the last edit	CTRL+A
	Insert carriage return but don't move the cursor	CTRL+SHIFT+N
Tabs	Toggle tabs on and off (display in a file)	CTRL+ALT+T
	With multiple lines selected, move lines one tab stop to the right	TAB
	With multiple lines selected, move lines one tab stop to the left	SHIFT+TAB
Scroll text	Scroll up one line at a time	CTRL+UP ARROW
	Scroll down one line at a time	CTRL+DOWN ARROW
	Scroll right one screen	CTRL+PAGE UP
	Scroll left one screen	CRTL+PAGE DOWN
Select text	Select character to the left	SHIFT+LEFT ARROW
	Select character to the right	SHIFT+RIGHT ARROW
	Select one word to the left	SHIFT+CTRL+LEFT ARROW
	Select one word to the right	SHIFT+CTRL+RIGHT ARROW
	Select current line if insertion point is home	SHIFT+DOWN ARROW
	Select line above if insertion point is home	SHIFT+UP ARROW
	Select to end of the line	SHIFT+END
	Select to beginning of line	SHIFT+HOME
	Select one screen up	SHIFT+PGUP
	Select one screen down	SHIFT+PGDN
	Select block	SHIFT+CTRL+M
	Select to beginning of file	SHIFT+CTRL+HOME
	Select to end of file	SHIFT+CTRL+END
Change case	Change selection to uppercase	CTRL+U
	Change selection to lowercase	CTRL+u
Find	Open the Find dialog box	ALT+F3
	Select text string in Find box	CTRL+F or ALT+A
	Find the selected text	CTRL+F3
	Find next, forward	F3
	Find next, backward	SHIFT+F3
	Next find in files tag	F4
	Previous find in files tag	SHIFT+F4
	Find the next error	F4
	Find the previous error	SHIFT+F4
	Find matching brace	CTRL+M
Bookmarks	Find next bookmark	F2
	Find previous bookmark	SHIFT+F2
	Toggle bookmark	CTRL+F2
Files	Create a new source file	CTRL+N
	Open a source file	CTRL+O
	Save a source file	CRTL+S
Window management	Switch to next document window	CTRL+F6
	Switch to previous document window	SHIFT+CTRL+F6
	Switch to next window (includes all windows)	F6
	Switch to previous window (includes all windows)	SHIFT+F6
	Switch to previously active window	CTRL+TAB
	Close active window	CTRL+F4
Debug	Start program execution from beginning	SHIFT+F5
	Quit a debugging session	ALT+F5
	Start or continue a program using the debugger	F5
	Run to the location of the insertion point	F7
	Single step through every line of the program	F8
	Single-step through program but skip functions	F10
	Run to first instruction after current function	SHIFT+F7
	Toggle breakpoints	F9
	Toggle hex mode	ALT+F9
	Toggle mixed mode	CTRL+F7
	Open the Breakpoints dialog box	CTRL+B
	Open Quickwatch to view the value of a variable	SHIFT+F9
	Open Modify Variable dialog box	CTRL+F9
	Open the Call Stack dialog box	CTRL+K
Browse	Expand node one level	ENTER, ALT+N, numpadENTER, SHIFT+PLUS SIGN, or numpadPLUS SIGN
	Collapse node completely	ENTER, ALT+N, MINUS SIGN, numpadENTER, or numpadMINUS SIGN
	Expand all nodes in a branch	SHIFT+8 or numpadASTERISK
	Expand an entire graph	ALT+X
	Jump to definition for selected symbol in source file or Find button text box	F11
	Jump to first reference for selected symbol in source file or in Find button text box	SHIFT+F11
	Jump to next reference in browser list	CTRL+numpadPLUS SIGN
	Jump to previous reference in browser list	CTRL+numpadMINUS SIGN
	Pop context	CTRL+numpadASTERISK
Build	Compile the active source file	CTRL+F8
	Build the project using dependency rules	SHIFT+F8
	Build the project from the start	ALT+F8
	Stops compiles, builds, and any tool	CTRL+BREAK
Help	Opens help on selected keyword in source file, Output window, or Find box or Find drop-down list box	F1


Project File Button
Project Files Button

Lists all files in the current project. To open a project file, click the Project Files button on the toolbar, then select the file from the drop-down list

Keyboard shortcut:	CTRL+P


Open File Button
Open Button

Opens the Open File dialog box. Double-clicking a filename or pressing ENTER with a file name selected opens the file.

Keyboard shortcut:	CTRL+O


Save Button

Saves a file. Save button is inactive until you alter text in the active source window.

Keyboard shortcut:	CTRL+S


Find Button

Begins find for a text string. The Find button also features a drop-down box containing a list of the previous 16 search strings. The list is maintained throughout your editing session. When you begin a search from the toolbar, the search is confined to the active window.

 To begin a find with the Find button:

Enter a search string in Find box, then press ENTER

Select a text string in the drop-down list box, then press ENTER

Select a text string in a source file, then press CTRL+F3.

Note  You can use regular expressions with a find from the toolbar.

Action	Keyboard Shortcut
Enter text in source file to Find box	CTRL+F3
Select text string in Find box	CTRL+F or ALT+A
Search forward	RETURN or F3
Search backward	SHIFT+RETURN or SHIFT+F3
Help on selected keyword	F1
Go to definition	F11
Go to reference	SHIFT+F11


Find Next Button

Repeats the last search.

Action	Keyboard Shortcut
If focus is in Find box	RETURN
If focus is elsewhere	F3


Compile Button
Compile File Button

Compiles the active source file.

Keyboard shortcut:	CTRL+F8


Build Button

Builds the project using dependency rules. Builds only the files not up-to-date.

Keyboard shortcut:	SHIFT+F8


Build All Button
Rebuild All Button

Builds the project from the start. Builds all the files regardless of dependencies.

Keyboard shortcut:	ALT+F8


Breakpoint Button
Toggle Breakpoints Button

Sets or clears a breakpoint on the current line in the current source file.

Keyboard shortcut:	F9


QuickWatch Button

Opens the Quickwatch dialog box. Use the Quickwatch dialog box to modify the display in the Watch window. You can quickly add, modify, or expand variables or expressions.

Keyboard shortcut:	SHIFT+F9


Go Button
Run Button

Runs program associated with the current project. If the project is an external makefile, specify the target executable with the Project command on the Options menu.

Keyboard shortcut:	F5


Step Into Button

Single-steps through every line of the program. Enters functions when encountered.

Keyboard shortcut:	F8


Step Over Button

Single-steps through program but skips functions. Runs functions when encountered and stops immediately after.

Keyboard shortcut:	F10


Step Out Button

Runs to first instruction after call to current function. Continues program out of function, then stops at line after function call.

Keyboard shortcut:	SHIFT+F7


Help in Brief

  Files on the Help Menu

  Keyword Search Command on the Help Menu

  Other Commands on the Help Menu

  Help on Language Elements in Editor Windows

  Help on Errors in the Output Window

  Help on Dialog Boxes

  Additional Help for Compiler and Linker Options

  Opening or Closing Secondary Windows


The Help Menu

Commands on the Help Menu open a contents screen for a help file. Visual C++ includes the following help files:

Help File	Description
Visual Workbench	How to use Visual Workbench.
App Studio	How to use App Studio.
Build Tools	Compiler options, linker options, and module-definition statements. Opens help file on tools specific to the target defined by project.
C/C++ Language	Reference for language features and C/C++ run-time library functions.
Foundation Classes	Reference for the Microsoft Foundation Class Library.
Win32 SDK	Reference for Win32 Software Development Kit.


Keyword Search

The Help menu also provides a single location from which you can search for a keyword. You may search in these reference help files if you have them installed:

  Build Tools

  Build Errors

  C/C++ Language

  Foundation Classes

  Win32 SDK

Note  You cannot get help on Visual Workbench or App Studio procedures with the Keyword Search command.

The Keyword Search command brings up a dialog where you can enter a keyword (CreateWindow, Open, C1016) . If the keyword appears in one or more of the files above, the dialog box displays a list of the help files in which it appears. You can then choose which help file you want. If the individual help file has more than one reference, it displays its search dialog box.


Other Commands on the Help Menu

Technical Support

This command opens a help file with information about obtaining technical support.

About Visual C++

This command opens the About box for the product. It contains the version number of the product, which is useful when your are seeking technical support. It also contains information about your system.


Help on Language Elements in Editor Windows

You can get help in editor windows for keywords by placing the insertion point on a keyword, then pressing F1. A keyword for help is any language element you want help on [image] functions, language keywords, messages, class names, and so on.

You can also get help on a selection by pressing F1. This may be useful if a portion of a selection is normally a delimiter, such as the slash in the compiler optimization option /O1.

Note  Clicking the Right mouse button does not call up help. You may be familiar with this means of getting help from earlier versions of QuickHelp. WinHelp does not support the Right mouse button.


Help on Dialog Boxes

To get help on an open dialog, choose the Help button or press F1. Help describes the purpose of the dialog box and provides specific information for each of the controls [image] list boxes, check boxes, edit boxes, option buttons, and so on [image] in the dialog.

In some cases, help for the dialog box also contains troubleshooting information and tips on using the dialog box.


Help on Errors in the Output Window

You can get help on the error displayed in the Output window by moving the insertion point to the error number, then pressing F1.


Additional Help for Compiler and Linker Options

You can get additional help in the Compiler Options and the Linker Options dialog boxes. Use the following methods:

Select an option in the Option String by double-clicking it, then press F1. You get a brief description of the option and the location of the control in the dialog box that sets the option.

Select a control [image] an edit box, a list box, an option button [image] in the Category group and press F1. You get a description of the option or options set by that control. You can also view all the options set in that category by scrolling up and down in the Help window.

Select a category in the Category list box and press F1. You get a description of the options set in that category. You can scroll down in the Help window to view information on the options set by each control in the category.


Closing Help Windows
Opening or Closing Secondary Windows

This help system sometimes presents information in a "secondary" window. A secondary window does not have a menu bar or a button bar. All secondary windows in this help system will have titles such as "More" or "Shortcuts" to indicate their content. Both the main window and one secondary window can be open at the same time.

 To close a secondary window, either:

Choose the Close button in the topic

Double-click the system menu

Open the system menu, then choose Close.

Shortcut key: ALT+F4.

Close Windows Help by choosing the Exit command on the File menu.

Note  If you close Windows Help by any means other than choosing the Exit command on the File menu, an open secondary window will remain open. For instance, you can close Windows Help by double-clicking its system menu. This action does not close an open secondary window.


Help on the File Menu
File Menu Commands

Command	Description	Toolbar Button
New	Creates an empty source window that will be named when it is saved.	none
Open...	Opens the Open File dialog box. To open a file in an open project, use the Project Files button on the toolbar
Close	Closes an open file. Or double-click the files control-menu box.	none
Save	Saves a file. Toolbar button is inactive until you alter text in the source window.
Save As...	Opens the Save As dialog box, which prompts you for a filename.	none
Save All	Saves all source files currently opened.	none
Print...	Opens the Print dialog box. If text is selected, this command will print just the selected text.	none
Page Setup...	Opens the Page Setup dialog box. Sets margins on printed pages and specifies the text for running headers and running footers on each page.	none
Exit	Exits Visual Workbench and prompts you to save any modified files.	none
Choose Using the Editor on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Edit Menu
Edit Menu Commands

Command	Description	Toolbar Button
Undo	Reverses the last edit action. To set the undo buffer size, use the Editor command (Options menu).	none
Redo	Reverses the last undo command.	none
Cut	Deletes to the Clipboard.	none
Copy	Copies to the Clipboard.	none
Paste	Pastes text from the Clipboard.	none
Delete	Deletes but does not save to the clipboard.	none
Find...	Opens the Find dialog box. Or you can use the Find button to select from the last 16 items searched. To repeat the last search, click the Find Next button.
Replace...	Opens the Replace dialog box.	none
Find in Files...	Finds text in multiple source files. Opens the Find in Files dialog box. Output from search goes to the output window.	none
Find Matching Brace	Moves the insertion point from a brace or parenthesis to its matching brace or parenthesis (forward or backward). Beeps if brace or parenthesis not found.	none
Read Only	Write-protects a file. Useful for viewing files that you don't want to accidentally alter.	none
Choose Using the Editor on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the View Menu
View Menu Commands

Command	Description
Line...	Opens the Line dialog box. Type line number, then press ENTER.
Mixed Source/Asm	Displays assembly code mixed with source code.
Next Virtual Window Tag	Virtual Window is the name of the currently selected virtual output window. Jumps to the next source file and location specified in the window list.
Previous Virtual Window Tag	Virtual Window is the name of the currently selected virtual output window. Jumps to the previous source file and location specified in the window list.
Output	Displays virtual output window. Select virtual output window from pop-up menu to be displayed in the Output window.
Toggle Bookmark	Line is highlighted when bookmark is set.
Next Bookmark	Places insertion point at next bookmark.
Previous Bookmark	Places insertion point at previous bookmark.
Clear All Bookmarks	Clears all bookmarks in the active file.
Toolbar	Checked when Toolbar is displayed.
Status Bar	Checked when Status Bar is displayed.
Syntax Coloring	Select C, C++, or None from cascading menu to set syntax coloring for a single source file. To set global syntax coloring, use the Color dialog box from the Options menu .
Choose Using the Editor, Debugging Your Application, or Changing Preferences on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Project Menu
Project Menu Commands

Command	Description	Toolbar Button
AppWizard...	Opens AppWizard dialog box, which lets you create a suite of MFC project files to be used with ClassWizard.	none
New...	Opens New Project dialog box where you name the project, select a project type and add files to the project. The new project is automatically saved to disk.	none
Open...	Opens the Open Project dialog box, which lets you open an existing project. Loads browser database, if available, for the project.	none
Edit...	Opens the Edit Project dialog box. Adds files to or deletes files from a project. To change the project type, use the Project command on the Options menu.	none
Close	Closes the current project. You can also close a project by opening another project, creating a project, or exiting Visual Workbench.	none
Compile File	Compiles the active source file.
Build	Builds the project using dependency rules. Builds only the files not up-to-date.
Rebuild All	Builds the project from the start. Builds all the files regardless of dependencies.
Stop Build	Cancels the build as soon as the build tool being used is finished.
Execute	Runs a program outside the debugger. TARGETNAME is the name of the executable file produced by building the current project. See the Debug menus Go command to run a program in the debugger.	none
Scan Dependencies	Updates include dependency list for active file.
Scan All Dependencies	Updates include dependency list for entire project.
Load Workspace	Loads one of three previously saved workspaces associated with the current project.	none
Save Workspace	Saves one of three workspaces associated with the current project.	none
Choose Managing Projects, Compiling Files or Building Projects, Using Wizards to Create Applications for Windows, or Using Workspaces to Manage Your Environment on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Browse Menu
Browse Menu Commands

Command	Description
Go to Reference	Jumps to first place where Browser symbol is referenced. Selects symbol in source window or Browse window.
Go to Definition	Jumps to first place where a symbol is defined. Select symbol in source window or Browse window.
Next	Jumps to the next definition or reference, depending on where Go To Definition or Go to Reference was last used.
Previous	Jumps to the previous definition or reference, depending on where Go To Definition or Go to Reference was last used.
Pop Context	Returns to the symbol that was used before the last Go to Definition or Go to Reference
Open...	Opens the Browse window with the database listed or, if no database name is listed, opens the File Open dialog box.
ClassWizard...	Opens the ClassWizard dialog box. Creates a new class or maps a Windows message to a member function. This dialog box lets you create new classes for windows and documents and automate creation of message maps and message handler member functions.
Choose Examining Symbols with the Browser or Using Wizards to Create Applications for Windows on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Debug Menu
Debug Menu Commands

Command	Description	Toolbar Button
Go	Runs program associated with the current project. If the project is an external makefile, specify the target executable with the Project command on the Options menu.
Restart	Reloads program and starts. Use when execution has paused at a breakpoint, between steps, or when program has completed. Discards variable values.	none
Stop Debugging	Quits a debugging session. Program must be at a breakpoint or paused between steps. If command is dimmed, the program being debugged has focus or has finished.	none
Break	Breaks the running program at its current position.
Step Into	Single-steps through every line of the program. Enters functions when encountered.
Step Over	Single-steps through program but skips functions. Runs functions when encountered and stops immediately after.
Step Out	Runs to first instruction after call to current function. Continues program out of function, then stops at line after function call.
Step to Cursor	Runs to the location of the insertion point. Treats the insertion point location as a breakpoint.	none
Call Stack...	Opens the Call Stack dialog box.  Call Stack dialog box lists all function calls that lead to current statement.	none
Breakpoints...	Opens the Breakpoints dialog box. Sets or clears a breakpoint. Default is at location on the current line.
Quickwatch...	Opens the QuickWatch dialog box. Use the QuickWatch dialog box to modify the display in the Watch window. You can quickly add, modify, or expand variables or expressions.	none
Exceptions...	Let's you determine the action taken by the debugger for individual exceptions. Opens the Exceptions diaog.
Threads...	Suspends, resumes, terminates, or sets focus on a thread. Opens the Threads dialog box. The Threads dialog shows status of all active threads including state, priority, and current location.
Profile...	Views analysis of application's performance. Opens the Profile dialog.
Choose Debugging Your Applications or Profiling Your Applications on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Tools Menu
Tools Menu Commands

Command	Description
Stop	Stops any tool. This command also stops compiles and builds.
App Studio	Creates menus, dialogs, icons, and other resources. App Studio lets you visually build your Windows-based application elements and hook them up with Microsoft Foundation Class library code.
Your Commands...	You can add commands to open tools from the Tools menu. To install a tool, use the Tools command on the Options menu.
Choose Modifying the Tools Menu on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Options Menu
Options Menu Commands

Command	Description
Project...	Opens the Project Options dialog box. Sets custom compiler and linker options, build mode (debug, release, or common), or the project type.
Debug...	Opens the Debug dialog box. Specifies an EXE file to debug a DLL (you must specify a host program to debug any dynamic-link library), sets hard- or soft-mode debugging, or toggles hexadecimal display.
Directories...	Opens the Directories dialog box. Sets directories for include files, libraries, executables, help files, and MFC source files.
Editor...	Opens the Editor dialog box. Sets options that include tab settings, scroll bar enabling, save before build, prompt before save, and undo buffer size.
Workspace...	Opens the Workspace dialog box. Sets workspace options.
Tools...	Opens the Tools dialog box. Adds a tool to, or removes tool from, the Tools menu.
Memory...	Adjusts parameters of the Memory window. Opens the Memory dialog.
Color...	Opens the Colors dialog box. Changes syntax coloring.
Font...	Opens the Fonts dialog box. Changes the font in a window.
Choose Using the Editor, Managing Projects, Debugging Your Application, or Changing Preferences on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Window Menu
Window Menu Commands

Command	Description
Cascade	Arranges windows as overlapped.
Tile	Arranges windows as side-by-side.
Duplicate	Opens an additional window on an open source file
Close All	Closes all views of the active window.
Watch	Opens the Watch window (or brings it to the top)
Locals	Opens the Locals window (or brings it to the top)
Registers	Opens the Registers window (or brings it to the top)
Memory	Opens the Memory window (or brings it to the top)
Output	Opens the Output window (or brings it to the top). Output from build utilities, including errors and warnings, Debugger, Grep and Profiler tools, and optionally from tools on the Tools menu appear here.
Choose Using the Editor or Debugging Your Application on the Visual Workbench contents screen for specific procedures that relate to these commands.


Help on the Help Menu
Help Menu Commands

Command	Description
Visual Workbench	Opens help for Visual Workbench.
App Studio	Opens help for App Studio
Build Tools	Opens help for the C/C++ compiler options, linker options, and module-definition statements.
C/C++ Language	Opens help for C/C++ run-time functions and C/C++ language descriptions.
Foundation Classes	Opens help on Microsoft Foundation Class library.
Win32 SDK	Opens help on Windows NT APIs, messages, data types, and macros.
Keyword Search...	Opens the Search dialog box for keyword search in reference help files.
Technical Support	Opens help on how to contact Microsoft Product Support to help solve your problems. Also answers to commonly asked questions.
About Visual C++...	Displays a dialog box that shows software version, registered owner, and serial number.
Choose Help in Brief on the Visual Workbench contents screen for information that relate to these commands.


App Studio Jumps
This file is nothing more than jumps to topics in APSTUDIO.HLP. The jumps are accessed by keyword selections in MSVC.HLP. The JI macro makes the jump.


App Studio Help: Contents Screen


App Studio: Basics


App Studio: The Dialog Editor


App Studio: The Menu Editor


App Studio: The String Editor


App Studio: The Graphics Editor


App Studio: Using the Accelerator Editor


Compiler Options: Build Tools Help


Linker Options: Build Tools Help


Module-Definition Statements: Build Tools Help


Using Search Plus

Search Plus provides a way to search the full text of help files. You can search for a single word, a combination of words in a topic, one word near another word, an exact phrase, and so on.

  To search for a word or phrase:

1.	If the help file is not already open, open it using WINHLP32.

2.	Click Search Plus on the button bar.

3.	Enter the word or words that you want to find in the Search dialog box.

If you want to enter groups of words, or exclude words, and so on, click the Hints button. This displays the Search Hints dialog box. It describes the use of keywords to combine words, the use of quoting and grouping operators, and the use of a wildcard for expanding a root word.

You can also set the range used for the keyword NEAR. It determines how many other words can separate two words for which you are searching.

4.	In the Look At group box, select either the Topic Titles Only or the All Text option button.

5.	In the Look In group box, select the help files in which you want to search for the desired topic.

6.	Click the Search button.

The titles of topics found are displayed in the Topics Found list.

7.	Double-click the desired topic in the Topics Found list. Each entry in the topic displayed is highlighted.

Topics in the current help file have no label before the topic title. Topics in other help files in the group are preceded by a label. These labels change as you switch from one help file to another.

You can also use the Go To, Next and Previous buttons to display topics.

Tips and Troubleshooting

Using Search Keywords

The keywords AND, OR, and NOT operate only on a topic level. The following Search For string finds any topic that contains both words:

menu AND command

The order of words in the Search For string does not matter. The following Search For strings produce identical results:

menu AND command

and

command AND menu

The search mechanism ignores letter case. The same results appear if you search for cobject or COBJECT.

You cannot search for the Search keywords, such as NOT, for instance.

Exclusion from Searches

You can search for alphanumeric characters only. Characters such as ~ [tilde], # [number sign], \ [backslash] and ( [left parenthesis] are excluded from the search.

Some words are excluded from the full-text search capability in order to build a smaller search index file. The excluded words are not usually helpful for finding information in this kind of material, such as "because," for instance.

This exclusion has a side-effect with the NEAR keyword, because excluded words are essentially invisible to the search mechanism, even though they are visible to you on the topic page. For instance, if you set NEAR to 1 and search for:

menus NEAR commands

the search would find "commands because the menus" in the sentence "It may not display all the listed commands because the menus are dynamic," since both "because" and "the" are excluded from the search index.

Narrowing Your Search

If you find a very large number of topics with your search, you can narrow your search in four ways:

Exclude help files in the Look In group from the search list by clearing the check box for the help file.

Use the keywords (AND, OR and NOT) and the grouping operators listed in the Search Hints dialog box to create likely combinations of words.

Use the "" quoting operators to search for an exact phrase.

Use the NEAR keyword with combinations of words to find only those that are close together in a topic.

Recovering from Errors

If you get an error message that refers to an old or missing index file, one of two things may have happened:

The .IND index file may have accidentally been deleted or moved to a directory other than that containing the help files. In this case, reinstall the help files using Setup.

The VIEWER.INI file may have been deleted or corrupted. In this case, simply close the help file, open it again and try again.

If you get an error message that refers to a title setup problem, when you click the OK button, the Help file will close. In this case, open the help file again and continue.