1. Introducing Digital Mars C++

User Guide & Reference

Welcome to the Digital Mars C++ for Windows 95, 98, ME, NT, 2000, XP, Visa, 7, Windows 3.1, DOS and DOS32. For a list of the Digital Mars C++ features, see features.

Table of Contents

Part 1: "Welcome to Digital Mars C++"

In addition to the current chapter, introducing the Integrated Development and Debugging Environment (IDDE).

• Introducing Digital Mars C++
• Introducing the IDDE

Part 2: "Creating an Application with Digital Mars C++"

Guide to creating a first application in Digital Mars C++.

• Starting a Project and Defining Workspaces
• Generating an Application Framework
• Defining Classes and Their Hierarchies
• Editing Program Code
• Adding Look and Feel with Resources
• Testing an Application

Part 3: "Learning Digital Mars C++ by Example"

Tutorial chapters on building DOS and Windows hypertext file reader applications.

• Introduction to the Tutorial
• Lesson 1: Create the DOS Application
• Lesson 2: Generate an Application Framework
• Lesson 3: Customize the Interface
• Lesson 4: Add Messages with ClassExpress
• Lesson 5: Add a Dialog Box with ClassExpress

Part 4: "More about Creating Programs"

IDDE settings, workspaces, the application framework designers, the class browsers, the text editor, and version control.

• More about Projects and Workspaces
• More about Project Build Settings
• More about AppExpress
• More about ClassExpress
• Class Editor Reference
• Hierarchy Editor Reference
• Text Editor Reference
• Using Version Control

Part 5: "More about Testing Programs"

Debugging features of Digital Mars C++.

• Controlling and Configuring the Debugger
• Commands Available in Debugging Mode

Part 6: "About Managing Resources"

How to use the Digital Mars ResourceStudio to create and edit resources.

• ResourceStudio Resource Editor
• Dialog Editor
• Menu, Accelerator and String Table Editors
• Bitmap, Cursor, Icon, and Font Editors
• Version Information and Custom Resource Editors

Part 7: "Appendixes"

Appendixes on expression evaluation, the relationship between IDDE settings and command-line options, and the NetBuild feature.

• Expression Evaluation
• IDDE Settings and Command-Line Options
• Using NetBuild

Suggestions for the new users of Digital Mars C++

If you are new to Digital Mars C++, congratulations and welcome. We hope you find our product powerful and easy to use. Check out Introducing the IDDE and work through the tutorials in Part 3 to become proficient with Digital Mars C++ quickly.

Suggestions for users new to Windows development

If you are starting to program for Windows, Digital Mars C++ is a great platform. Read Generating an Application Framework, and Adding Look and Feel with Resources. Also you should read the tutorials in Part 3, which guide you through the development of a Windows application.

Suggestions for users porting to Digital Mars C++

If you need to port your code from another compiler or from a previous version of C++, read the Switching to Digital Mars C++ chapter in the Compiler & Tools Guide.

Suggestions for users upgrading to Digital Mars C++

If you are upgrading from a previous version of Digital Mars C++ and want to learn about the new product features, read Generating an Application Framework, Defining Classes and Their Hierarchies, Adding Look and Feel with Resources, More about AppExpress, and More about ClassExpress.

2. Introducing the IDDE

The IDDE is the Integrated Development and Debugging Environment. The IDDE comes with the CD version of the development system. This chapter introduces the Digital Mars C++ development system. The first part of the chapter describes the IDDE main window and toolboxes. The second part introduces Part Two of this manual, and outlines the steps involved in developing an application in the IDDE.

Running Digital Mars C++ under Windows 3.1, Windows 95, and Windows NT

Digital Mars C++ ships with three different integrated development and debugging environments (IDDEs), each tailored to a specific operating system and target. All IDDEs share the same user interface, and can build applications for DOS, Windows 3.1, Windows 95, Windows NT, and DOSX. Minor differences between the three IDDEs are noted throughout this manual, as appropriate. Not every IDDE can debug every kind of executable. To debug a Windows NT program, for example, you need the full 32-bit IDDE running under Windows NT.

Screen images in this manual may vary in appearance from one operating system to another.

Starting and exiting the IDDEs

To start the IDDE from the Program Manager, make sure that Digital Mars C++ is installed properly, then double-click on the appropriate IDDE icon in the Digital Mars C++ program group. The IDDE main window opens at the top of the screen.

To exit the IDDE, choose one of three commands from the IDDE File menu: Exit, Exit & Save All, or Exit & Discard. Exit leaves the IDDE and returns to the Program Manager. Exit & Save All exits and saves all the changes to the current project and options. Exit & Discard exits the IDDE without saving any changes to the current project or options.

IDDE Windows and Toolboxes

You can create, edit, and debug an application within the IDDE. The IDDE provides a variety of tools for use throughout the development process.

Unlike most Windows applications, the IDDE offers more than a single window in which to work. The IDDE is a feature-rich environment in which you work with multiple windows and toolboxes on the desktop. This section describes the general characteristics of those windows and toolboxes.

IDDE main window

The IDDE main window, shown in Figure 2-1, is positioned at the top of the desktop (workspace), which is the entire screen area. From the IDDE main window, open other windows on the desktop, load projects, set project options, and perform additional tasks. Most of the actual work, such as editing program code, is done in other windows on the desktop.

As shown in Figure 2-1, the IDDE main window has the following parts: system menu, title/status bar, main menu bar, and the minimize button. (Also shown is the Workspace toolbox docked below the main window. Docking means that the toolbox is attached to the IDDE main window, or the desktop edge.) The system menu and the minimize button are the standard Windows user interface elements. The other elements of the main window as well as the IDDE toolboxes are described in the following sections.

The title/status bar

The top line of the IDDE main window serves as both a title bar and a status bar. When you start the IDDE, the title bar displays the program name, Digital Mars C++. As actions occur in the IDDE, the title bar changes to a status bar and displays the status of the session, including the following information:

• The command description when a menu item is highlighted
• The current project that is loaded, and whether the IDDE is in debugging mode
• Various messages, the results of expressions, and other status information from the IDDE

The menu bar

The IDDE main window menu bar is located below the title bar. Table 2-1 summarizes the functions of the IDDE menus.

For information on how to choose menu commands, see your Windows, Windows 95, or Windows NT documentation.

The IDDE toolboxes

The IDDE includes the following four toolboxes:

• Views
• Build
• Debug
• Workspace

Open a toolbox through the IDDE's Window menu. If the toolbox's name is checked, it appears in the workspace. If the name is not checked, select it to open the toolbox. The following sections describe the toolboxes in detail.

The Views toolbox

The Views toolbox, shown in Figure 2-2, is used to open the IDDE windows. Each of the IDDE windows is represented by an icon in the toolbox.

To open a window from the Views toolbox, click and drag the appropriate icon from the toolbox onto the desktop. Alternatively, double-click on the icon to open the window. To replace one window on the screen with another, drag the icon of the window you want into a window on the desktop. Table 2-2 lists the IDDE windows.

You can open multiple Data and Source windows. When you have more than one Data or Source window open, and then minimize more than one of them, the IDDE adds a pop-up menu to the Data or Source icons in the Views toolbox (see Figure 2-3). A small triangle in the lower-right corner of the icon indicates that a Source or Data window is minimized.

To open a minimized Data or Source window:

1. Move the cursor over the triangle in the lower-right corner of the Data or Source window icon.
2. Click to open the pop-up menu.
3. Choose the window title you want from the pop-up menu. That window becomes active.

Alternatively, move the cursor over the window title in the pop-up menu, then click and hold the mouse button. A window icon appears to the right (see Figure 2-3). Drag the cursor over the icon, then move the cursor over either the desktop or an open window and release the mouse button.

The Build toolbox

The Build toolbox, shown in Figure 2-4, provides quick access to project build commands.

To use the Build toolbox, click on the appropriate button in the toolbox. These buttons perform the following tasks:

• Compile a single source file
• Build the project
• Rebuild the entire project
• Stop the build in progress

The Debug toolbox

Debug toolbox icons (shown in Figure 2-5) let you efficiently choose debugging commands during a debugging session. The commands available in the Debug toolbox correspond to the commands on the IDDE Debug menu and are described in detail in the section "Debug Toolbox Icons," in Controlling and Configuring the Debugger.

The Workspace toolbox

When you first open the IDDE, the Workspace toolbox appears docked below the IDDE main window menu bar. The Workspace toolbox is used for switching between workspaces, which are customized layouts of windows that you define. The Workspace toolbox is shown in Figure 2-6.

As you create new workspaces, their names appear on tabs in the Workspace toolbox. To switch to a different workspace, click on its tab. For more information on defining workspaces, see Starting a Project and Defining Workspaces.

Using toolboxes

The IDDE's Window menu lists the names of all toolboxes. When a checkmark is displayed next to the toolbox name, the toolbox appears in the current workspace. To open a toolbox, select the toolbox name from the IDDE's Window menu.

You can position a toolbox on the desktop by clicking on its title bar and dragging the toolbox to the desired position on the screen. To dock a toolbox, position it on the IDDE main window or on the edge of the screen. To undock the toolbox, click on the toolbox and drag it away from the IDDE main window or the desktop edge.

You can change the shape of a toolbox by clicking the toolbox edge and dragging the outline of the toolbox to the desired shape.

If you want to remove an icon from a toolbox, right-click on the icon you want to remove, drag it from the toolbox, and drop it.

Toolboxes can be configured with commands in their pop-up menus. To access a toolbox's pop-up menu, right-click on an empty part of the toolbox (as shown in Figure 2-7). When the first menu item, Dockable, is checked, you can dock the toolbox. The next three items (Small, Medium, and Large) let you change the size of the toolbox and its icons. The last item on the menu, Reset Palette, lets you restore any icons or buttons you have removed from the toolbox.

To identify a toolbox icon, hold the mouse cursor over the icon for a few seconds. A small yellow tag appears, showing the name of the icon.

To close a toolbox, click on the Close box. Each toolbox has a Close box in the upper-right corner, as shown in Figure 2-8.

The IDDE windows

This section describes the general properties of the IDDE windows and how to work with them.

Opening and closing windows in the IDDE

Digital Mars C++ supports both standard Windows methods and a few unique methods for displaying and managing windows. In the IDDE, open a window in any of the following ways:

• From the Views toolbox.
• Through the Goto View submenu of the IDDE's Window menu. The Goto View submenu lists all of the windows you can open, along with the shortcut keys that open those windows.
• By choosing Window List from the IDDE's Window menu or from the system menu of any IDDE window. A dialog box listing all IDDE windows opens. Choose a window name from the list and click OK.

When you open a Source window to edit a specific source file, the filename is added to the Window List dialog box. You can then activate this particular window from the Window List dialog box.

Each window has a Close box similar to that of a toolbox (see Figure 2-8). Click on the box to close the window.

Using the drag-and-drop feature

The Digital Mars C++ IDDE provides a drag-and-drop feature that lets you execute commands by dragging from one window onto another or onto the desktop. For example, you can drag a module's name from the project window onto the desktop in order to edit that module in a Source window. When something cannot be dropped on a particular window or the desktop, the cursor changes from that icon to a "No" sign (a circle with a diagonal line through it). Most of the drag-and-drop functionality is available in debugging mode and is described in Commands Available in Debugging Mode.

Using the IDDE

The following sections serve as an overview of Part Two of this manual and introduce you to the process involved with creating an application in the Digital Mars C++ environment.

Creating a project

Projects are integral to the Digital Mars C++ development system. You cannot build an application without creating a project. A project is a collection of source files, headers, resource files, and other components that you need to build an application.

To help you create a new project, a new tool called ProjectExpress is included. This tool lets you select the project target (the result of your development efforts), the directory for the project files, and other options. While in ProjectExpress, you can also use AppExpress to generate the framework for the application.

AppExpress is a tool that automatically generates an application framework. AppExpress lets you select from a variety of application types, then creates a working skeleton of source code and resource definitions. After the framework is generated, then concentrate on customizing the framework and implementing the features of the application.

Using workspaces

Because the IDDE provides a variety of windows used for specialized tasks, you probably do not need all of them open simultaneously. The IDDE workspaces provide a convenient way to switch from one screen layout to another. Workspaces are task-oriented, as opposed to project-oriented. You create workspaces for different tasks, such as editing, browsing, or debugging, which you perform in different projects. The Workspace submenu of the IDDE's Environment menu provides access to workspace commands.

Creating and editing your application

Once you have created a project, you can start working on the program's code. This section introduces the IDDE tools.

Creating and editing resources

If writing a Windows application, you probably need to create resources such as menus and dialog boxes. Commands on the IDDE's Resource menu access the Digital Mars C++ ResourceStudio, a powerful tool for creating and editing resources.

Binding resources to classes

ClassExpress is a tool for binding resources, such as dialog box controls, to the classes in the program. This is needed in order to be able to respond to user actions. Launch ClassExpress by choosing ClassExpress from the IDDE's Tools menu, or from within ResourceStudio.

Editing class hierarchies

The IDDE provides two tools for editing class hierarchies: Class Editor and Hierarchy Editor. Open a Class or Hierarchy Editor window from the Views toolbox, or from the Goto View submenu of the IDDE's Window menu. Both editors have the same functionality, but different interfaces. The Class Editor emphasizes member editing, while the Hierarchy Editor emphasizes inheritance relationships.

Editing code

While you can greatly reduce the amount of work needed to write a complex application using the tools Digital Mars C++ provides, eventually you need to edit the raw source code. The IDDE includes a powerful, scriptable text editor with features such as customizable key bindings, automatic token coloring, delimiter matching, and other features. Edit code in the Source window, which can be opened from the Views toolbox or the Goto View submenu of the IDDE's Window menu.

Debugging your application

After writing most or all of the application's source code, it is time to test and debug it. Do this by switching the IDDE into debugging mode and using the commands on the IDDE's Debug menu, the Debug toolbox, and various debugging windows opened from the Views toolbox.

Using help

The following sections describe several ways to get online help in the IDDE.

The title/status bar

When you click and hold on a command in a menu, the IDDE main window title/status bar shows a brief description of the menu command.

The IDDE Help menu

The IDDE provides several online help systems through the IDDE Help menu. The first items on the IDDE Help menu access the IDDE Help system, shown in Figure 2-9. To navigate the IDDE Help system, click on the icon representing the type of help needed.

Alternatively, choose Search from the IDDE Help menu to find a particular topic in the IDDE Help system.

Other commands on the Help menu access Windows API and Microsoft Foundation Class reference material.

Finally, the About Digital Mars C++ command on the IDDE Help menu displays a dialog box with version information on the Digital Mars C++ Development System.

Other ways to launch online help

To view help information for a run-time library function, highlight the name of the function in a Text Editor window and type CTRL+ALT+F1.

To view frequently used help topics without navigating IDDE Help, associate specific .hlp files with key combinations. (For example, to view help for ResourceStudio, map rstudio.hlp with the key combination CTRL+ALT+F4.)

To associate a key combination with a help file, choose Edit/Browsing Settings from the IDDE's Environment menu. Click Text, then click Help files.

3. Starting a Project and Defining Workspaces

What Are Projects and Workspaces?

Workspaces, which are among the IDDE's most useful features, are window configurations used for particular tasks. To create a workspace, you name and save the exact arrangement of windows on your screen. Any time you need to perform a similar task, you can instantly open that workspace, with the windows organized the way you want them. For more information on workspaces, refer to More about Projects and Workspaces.

Starting a Project

Purpose of a project

Projects speed development time because they let you recompile only the source files that have changed, or whose header files have changed, since the last time the project was built. For example, if your program has five source files and you have changed one of them since the last build, only that file is recompiled when you build the project. (You can, however, choose to recompile all the files.) The project management system does this by automatically analyzing the dependencies of the source files and constructing or updating the makefile each time the project is built.

Contents of a project

The IDDE stores information about a project on disk as a project file with a .prj extension. Among other information, this file includes a list of the source files contained in a project. When you build the project, the IDDE constructs a makefile (.mak) or updates the existing makefile based on the files the project contains. Project options are stored in an option set file (.opn) that is referenced in the project file. The option set file can be loaded into another project, making it easy to transfer all option settings from one project to another.

Creating a new project

Naming the project

Figure 3-1 ProjectExpress Project Name page

Select the directory in which you want to create the project from the Directories listbox, or click on New Directory to make a new directory for this project. Enter the name of the new project in the Project Name textbox.

If you select Use AppExpress to create new application, then click on Finish, AppExpress will start. AppExpress is discussed in Generating an Application Framework.

Setting the project type

Figure 3-2 ProjectExpress Project Type page

After the project is created, you can modify these settings by choosing Settings from the Project menu. These options are discussed in more detail in More about Projects and Workspaces.

Adding files to the project

Figure 3-3 ProjectExpress Project Edit page

If you are creating a new project, you do not need to do anything on this page. After the project is created, you can open a similar dialog box by choosing Edit from the Project menu (see the section "Adding and deleting project files" later in this chapter).

Setting defines and include directories

Figure 3-4 ProjectExpress Initial Settings page

To define a macro on the compiler command line, enter the macro in the Defines textbox (for example, COLOR=1). Separate multiple macro definitions with semicolons. Type any #include file search paths you want on the compiler command line in the Include Directories textbox. Type any directories to be excluded from parsing in the Browser Exclude Directories textbox. (For more information about parsing, see Defining Classes and Their Hierarchies).

In general, you can leave these fields blank. You may change these options later by choosing Settings from the Project menu.

After the project is set up the way you want, click on Finish to create the new project.

Opening an Existing Project

IDDE lets you work with only one project at a time. If you're already working with a project when you open a new one, the IDDE closes the project in process.

An additional method for opening existing projects is to choose one from the list of projects at the bottom of the Project menu. Projects are added to this menu as they're opened or created. This makes it easier for you to switch back and forth between projects as you work.

Adding and deleting project files

Figure 3-5 Edit Project dialog box

The Project Files listbox contains the files in your project.

• To add a file to your project, select the file from the File Name listbox and click on Add, or double-click on the name of the file.
• To add all the files in the File Name listbox, click in the listbox, click on Select All, and then click on Add.
• To remove a file from the project, select it from the Project Files listbox and click on Remove, or double-click on the name of the file.
• To remove all the files from the project, click on the Project Files listbox, click on Select All, and then click on Remove.

After you click OK, the IDDE checks your project for dependencies and creates a makefile. While checking for dependencies, the IDDE adds the additional files it needs to build your project. For example, it adds all the header files that your source files reference with the #include directive.

The Project window

Figure 3-6 Project window

You can double-click on the name of a source file in the right pane to open that file for editing in a Source window. (See Editing Program Code, for a description of text editing functions.)

You can see the current project's subprojects, or open a subproject, by double-clicking on the project name in the left pane.

The icon to the left of each filename indicates certain properties of the file. If the icon is blue, the file was explicitly added to the project; if the icon is gray, the file is included in the project by a dependency relationship or by parsing.

The icon next to each filename contains different information during debugging. An asterisk indicates that the module contains debug information. A "T" at the right of the icon indicates that tracing is enabled in the module. Dots indicate that the module contains breakpoints: a green dot indicates enabled breakpoints, and a red dot indicates disabled breakpoints.

Closing a project

Importing a Microsoft or Borland project

First, choose Open from the Project menu. In the "List files of type" listbox, choose Import Make. When you open a Microsoft or Borland makefile, the IDDE lets you work with it as you would a Digital Mars C++ project.

To build the project with the original Microsoft or Borland makefile, use the Make page under the Build tab in the Project Settings dialog box (see More about Project Build Settings) to call the original makefile or batch file.

Defining Workspaces

The purpose of workspaces

Creating a workspace

Figure 3-7 Workspace toolbox

Selecting a workspace

More options for workspaces

4. Generating an Application Framework

Before reading this chapter, take look at the material in Starting a Project and Defining Workspaces in the IDDE. AppExpress creates both an application framework (according to specifications you provide) and the project in which that framework resides.

More about AppExpress and More about ClassExpress are the reference chapters for the AppExpress and ClassExpress tools.

What Is an Application Framework?

Using a framework to build an application dramatically shortens its development time. All the files needed to create the application are included in the skeleton program. Standard user interface components such as windows, menus, and toolbars are already defined. Some of the necessary connections between the defined C++ classes are established automatically.

With a framework as a starting point and using the MFC library, you can build many different types of applications by:

• Adding or changing user interface components with ResourceStudio (see Chapter 7, "Adding Look and Feel with Resources")
• Creating new C++ classes, class methods, and class member variables with ClassExpress
• Writing code

Because message maps are used by MFC to route Windows messages to the messages' handlers, they provide the essential translations needed to present the event-driven model of the Windows API in an object-oriented guise. By automating the creation and maintenance of message maps, AppExpress and ClassExpress relieve you of much error-prone drudgery, and allow you to spend more of your development time writing code that implements functionality.

The following sample message map was automatically generated by AppExpress for an MDI-style application framework:

    BEGIN_MESSAGE_MAP( CMainView, CView)
	//{{ AFX_MSG_MAP( CMainView) 
	// NOTE -ClassExpress will add and
	// remove mapping macros here. 
	// DO NOT EDIT what you see in these
	// blocks of generated code ! 
	//}} AFX_MSG_MAP
	// Standard printing commands 
	ON_COMMAND( ID_FILE_PRINT, CView::OnFilePrint)
	ON_COMMAND( ID_FILE_PRINT_PREVIEW, 
		CView:: OnFilePrintPreview)
	END_MESSAGE_MAP() 

Creating a Framework with AppExpress

Launching AppExpress

[Figure 4-1 AppExpress window]

Looking at the AppExpress window

• A listbox at the upper left displaying the steps required to create an application framework. The current selection from this list determines which page of options is shown in the larger pane to the right.
• A pane on the right showing the options associated with the currently selected step.
• Buttons below the panes that you can use to navigate among the steps, preview your work, or generate a framework.

Specifying an application framework

• Select an application type
• Select a directory for the project
• Provide copyright information and project options
• Specify class names
• Specify source file names
• Specify help file names

Selecting an application type

1. Select Application Type from the steps list in the AppExpress window.
2. Select an application type by clicking on a radio button in the Applications group. There are six categories of applications, two of which SDI and MDI can be made OLE clients and/or servers.

Selecting application type options sets default options for many of the other steps in AppExpress. For example, if you select Dialog Box, AppExpress automatically creates three C++ classes with default class names in your skeleton program. You can change these defaults; for example, you can modify the default class names by selecting Names from the steps list.

Selecting a directory for the project

1. Select the Select Directory item from the steps list. The Select Directory options page opens as shown in Figure 4-2.
2. Select the appropriate drive and directory. Or, click on Create New Directory to create and name a new directory. AppExpress suggests the project name as the new directory name, but you may change that default.

   

   [Figure 4-2 Select Directory options]

Providing copyright information and project options

1. Select Miscellaneous from the steps list. The Miscellaneous options page opens as shown in Figure 4-3.

   

   [Figure 4-3 Miscellaneous options]

2. Provide copyright information in the appropriate fields. AppExpress uses this information to write a copyright notice in the comment header of all of your application's source files, and to construct the application's About dialog box.
3. Specify the project name in the appropriate field. Stack and heap sizes can be changed later in the Project Settings dialog box.

Specifying class names

1. Select Names from the steps list. The Names options page opens as shown in Figure 4-4.
2. In the options pane, select a class from the Name drop-down list automatically created by AppExpress. The class names included in this list depend on the application type you have selected.
3. If you like, you can edit the selected class name. Note, however, that C++ class names follow a standardized naming convention. Using the default names allows your program's structure to be easily understood by others.
4. In the appropriate field, type the names of the header and source files in which AppExpress should place the class source code.

To discard any changes you have made on this page, click on the Set Default Names button.

[Figure 4-4 Names options]

Naming source files

1. Select File Names from the steps list. The File Names options page opens as shown in Figure 4-5.
2. In the options pane, click on the filename you want to change. The files listed depend on the application type you have selected. Their names correspond to their functionality within the application.
3. Edit the filename, but remember that these changes could make it harder for someone else to identify the purpose of the file.

   

   [Figure 4-5 File Names options]

Specifying help file names

1. Select Help Options from the steps list. The Help Options options page opens as shown in Figure 4-6.

   

   [Figure 4-6 Help Options options]

   Note If you selected Quick Console or Dialog Box as the application type, or if Include Help is not selected in the Application Type options page, then you have no help options.

2. Edit the filenames if you want. Note, however, that any changes could make it harder for someone else to identify the purpose of the file.

Generating an application framework

Click on the Finish button in the AppExpress window. AppExpress generates the project and its source files, as you specified, hands it off to the project system, and closes.

Note If you checked the Include Help box among the Application Type options, then you will need to build the help file for your application. You do this by running the makehelp. bat file that AppExpress creates in your project directory.

Your skeleton program is ready. You can now build the program from within the IDDE, or you can add to your program by using other Digital Mars C++ tools. The next section shows how to enhance your application's C++ classes by using ClassExpress.

Building on a Framework with ClassExpress

Specifically, you can use ClassExpress to:

• Write message maps
• Create new classes derived from existing classes
• Create new class methods mapped to specific messages
• Create new class member variables (that is, data variables that are members of a class) mapped to specific user-interface objects
• Create new classes that can be OLE2 automation servers or clients
• Create new classes that act as interfaces to Visual Basic Custom Controls (also known as VBXs)

Message maps, defined in "What Is an Application Framework?" in this chapter, are discussed in greater detail in Chapter 17, "More about AppExpress."

You can use ClassExpress immediately after creating an application framework as well as at later points in development. For example, you probably want to wait until you have created some dialog boxes with ResourceStudio (see Chapter 7, "Adding Look and Feel with Resources" ) before mapping class member variables to user interface objects.

Launching ClassExpress

Launching ClassExpress opens the window shown in Figure 4-7.

[Figure 4-7 ClassExpress window]

Looking at the ClassExpress window

• A listbox at the upper left presenting the different kinds of code that ClassExpress can generate
• A pane on the right showing the page of options associated with each selection from the list at the upper left

Writing a message map with ClassExpress

ClassExpress runs from within the IDDE or as a stand-alone application. If run from within the IDDE, ClassExpress will be loaded with the IDDE's open project if there is one; otherwise, it prompts to open an existing project (which also opens the project in the IDDE's project system).

As an example, the following steps demonstrate how to add a message handler to the CAboutDlg class of an SDI application generated by AppExpress:

1. Select Message Maps from the listbox. (If you just started ClassExpress, this should already be selected.) The ClassExpress window is displayed as shown in Figure 4-7.
2. Select the class CAboutDlg from the Class drop-down list. The contents of the three other lists in the options pane are updated to reflect the following selection:
   • Control IDs in Class: This list contains all of the menu links and control IDs for which this class can add handlers. For example, IDOK is a universally defined constant for an OK button. Because the CAboutDlg class includes an OK button by default, the IDOK constant is always predefined for this class.

     Because this class represents a dialog box- which itself can respond to many Windows messages- the first item in the Control IDs in Class list is the name of the class itself (CAboutDlg).

   • Windows Messages: This list contains all of the Windows messages that apply to the selected item in the Control IDs in Class list. For example, if you highlight IDOK in that list, two applicable messages (button notifications, in this case) are displayed in the Windows Messages list: BN_CLICKED and BN_DOUBLECLICKED. If a handler is defined for a message, a red box appears before the message name in this list.
   • Function Name: This list contains all of the handlers that exist within the selected class. These are the methods that are linked to Windows messages.
3. Select CAboutDlg from the Control IDs in Class list. The list of Windows messages changes, revealing a long list of messages to which your dialog box could respond.
4. Double-click on WM_ACTIVATE. Notice that the method OnActivate (in its fully prototyped form) is added to the Function Name list.

Adding a new class to your application

1. Select Message Maps from the listbox. (If you just loaded ClassExpress, then this should already be selected.)
2. Click on the Add Class button. The Add Class dialog box shown in Figure 4-8 opens.

   

   [Figure 4-8 Add Class dialog box]

3. Select a class type from the Class Type drop-down list. This type specifies the base class from which your new class will be derived. The list displays names of MFC classes without the initial letter 'C', thereby allowing you to navigate rapidly within the list by typing the first letter of a class type. For example, typing 'V' selects the View class type.
4. The New Class Name field becomes active, displaying a suggested name for the new class. Edit this name as appropriate.
5. If you selected CDialog or CFormView, then the field Dialog ID is displayed. Move to this field and choose the resource ID of the dialog that you want to associate with the new class's window.
6. Check the OLE Automation box if you want your new class to be a programmable OLE object. If you choose this option, any other Windows application that is an automation client can use the OLE interface you define for this object.
7. If you check the OLE Automation box and you are deriving a new class from the CCmdTarget or CWnd class, the Creatable check box is displayed. Check this box if you want other applications to be able to create the OLE automation object that you are defining.
8. If you check the OLE Automation check box and you are deriving a new class from the CCmdTarget or CWnd class, you must also type a name in the External Name field. This is the name that is exposed to other applications that may want to use your OLE automation object.
9. Decide whether to edit the implementation filename of your new class (shown in the last field in the Add Class dialog box). By default, the base part of the filename is the name of your new class without the initial letter 'C', and truncated if necessary.
10. Click OK to add the new C++ class to your application. If you want, you can create message mappings for your new class by using the steps outlined in the previous section.

In addition, ClassExpress can bind your classes to your dialog boxes and generate C++ wrapper classes for Visual Basic custom controls (VBXs). It also provides extensive support for building OLE servers and containers. For more information on these features, refer to Chapter 18, "More about ClassExpress."

5. Defining Classes and Their Hierarchies

These tools are suited for developing a class hierarchy from scratch, for adding classes to an application framework generated with AppExpress, and for browsing and editing pre-existing class hierarchies. They are especially useful for understanding the architecture of unfamiliar source code.

The Class and Hierarchy Editors can perform the same operations on classes and hierarchies; they differ only in their interface. The Class Editor's interface emphasizes member editing; the Hierarchy Editor's interface, through its graphical display, emphasizes inheritance relationships. Use one or the other, or both simultaneously, according to preference.

This chapter describes basic operations that may be performed with the Class and Hierarchy Editors. For a complete reference on these two tools, see Class Editor Reference, and Hierarchy Editor Reference.

Parsing and Browsing

To present you with a list of classes and members, the IDDE must parse the source code. By default, this is done automatically. When the IDDE detects that source code or project settings have changed since the last parse, it reparses the necessary files. If errors are encountered during parsing, messages are displayed in the Output window. You can double-click on the error message to open for editing the appropriate file at the point at which the error was detected.

How the class browsers expand macros

The parser treats an entire project as one "database" of code. Consequently, preprocessor macros defined in any header will expand in any subsequently parsed file. This can produce unexpected errors. For example:

// foo1.h ------------------------------------
#define pBar (pIndirect->pBar) 
// . . .

// foo1.cpp ----------------------------------
#include <foo1.h> 


// foo2.cpp ----------------------------------
struct A 
{   int *pBar;    // ERROR! Expands to: int * 
    (pIndirect-> pBar);
}; 

Browsing library source code

1. Choose Settings from the IDDE's Project menu.
2. In the Project Settings dialog box, click the Directories tab.
3. In the Browser Exclude Directories textbox, type the name of the directory containing the class library headers (for example, c:\dm\mfc\include).
4. Click OK.

Class Editor

To open a Class Editor window, do one of:

1. Choose Class Editor from the Window menu's Goto View submenu.
2. Click and drag the Class Editor icon from the Views toolbox to an empty area of the desktop.

1. The Classes pane, which contains a list of classes.
2. The Members pane, which contains a list of members of the current (highlighted) class.
3. The Source pane, which displays member source code. You can edit the source code in this pane as in the Source window (see Editing Program Code, for a description of text editing features).

The Class Editor window contains a standard menu bar and toolbar; pop-up menus are available in each pane. You can set options for the grouping, sorting, and display of classes and members in the Classes and Members panes in the Editing/ Browsing Settings dialog box. For a complete reference on Class Editor menus and options, see Class Editor Reference.

You can change the relative sizes of panes in the Class Editor window by first positioning the cursor over the line separating the panes. The cursor changes to a two-headed arrow. Press the left mouse button and drag the separator to the desired location.

To select a class in the Classes pane, click on it. Additional classes may be selected by holding down the Control key and clicking. By default, classes are displayed hierarchically, with derived classes below and indented relative to their bases. Classes with multiple bases are displayed beneath each of the bases. Triangular buttons to the left of base classes can be used to collapse and expand branches of the hierarchy. You can set an option to display classes alphabetically in the Editing/ Browsing Settings dialog box.

By default, class members in the Members pane are grouped into Functions, Data, and Typedefs. The tree structure can be expanded or collapsed by clicking on the triangular buttons to the left of the category names. To select a class member, click on it. Additional members can be selected by clicking while holding down the Control key. You can display a member declaration or definition in the Source pane by double-clicking on the member name.

Creating classes

Creating a top-level class

To create a new top-level class:

1. Choose Add Top from the pop-up menu in the Classes pane. The Add Class dialog box is displayed (Figure 5-2).

   
   Figure 5-2 Add Class dialog box

2. Type a name for the new class.
3. Click OK.

Creating a derived class

To create a new derived class:

1. Select the base class of the new class.
2. Choose Add Derived from the pop-up menu in the Classes pane. The Create Derived Class dialog box opens. (This dialog box is similar to the Add Class dialog box.)
3. Type a name for the new class.
4. Click OK.

Creating a sibling class

To create a new sibling class:

1. Select the class whose base class will be the base class of the new class.
2. Choose Add Sibling from the pop-up menu in the Classes pane. The Create Derived Class dialog box is displayed.
3. Type a name for the new class.
4. Click OK.

Editing inheritance relationships

When altering inheritance relationships, the Class and Hierarchy Editors change only the class declarations. In particular, they do not change references to base classes and their members in a derived class's constructors or functions. If such references exist, you must change them manually in the source file.

Connecting to a base class

To make one existing class derive from another existing class:

1. Select the class that will be the derived class.
2. Choose Connect Base from the pop-up menu in the Classes pane. The Add Base dialog box opens (Figure 5-3).

   
   Figure 5-3 Add Base dialog box

3. From the listbox, select the class (or classes) to be this class's base class.
4. Select the desired access specifier. Check Virtual if virtual inheritance is desired.
5. Click OK.

Deleting a connection

To delete an inheritance relationship:

1. Select a derived class.
2. Choose Delete Base Connection from the pop-up menu in the Classes pane.
3. A message box requests confirmation. Click Yes to delete the base connection.

Editing inheritance attributes

To edit the base class access specifier:

1. In the Classes pane, select the derived class.

   In cases of multiple inheritance, select the base connection to edit by clicking on the instance of the derived class below the appropriate base.

2. Choose Edit Base Attributes from the pop-up menu in the Classes pane.

   The Edit Base Attributes dialog box opens (Figure 5-4).

   
   Figure 5-4 Edit Base Attributes dialog box

3. Select the desired access specifier. Check Virtual if virtual inheritance is desired. Click OK.

Working with class members

A list of the members of the currently selected class is shown in the Members pane (Figure 5-5). By default, the member list is sorted into three categories: Data, Functions, and Typedefs. Within each category, items are sorted alphabetically. The colored diamond in front of each member identifies the access as public (green), protected (yellow), or private (red). Names of members defined as macros appear in red.

Note: Members that appear in red are not syntactically verified before source changes are saved back to the file.

The lists following each category header can be collapsed or expanded by clicking on the triangular button to the left of the category name.

Figure 5-5 Members pane of Class Editor

Adding a class member

To add a class member:

1. Choose Add from the pop-up menu in the Members pane. The Add Member dialog box opens (Figure 5-6).

   
   Figure 5-6 Add Member dialog box

2. Type the member declaration. The member may be a data item (for example, int nCats), a function (for example, int NumCats()), or a typedef (for example, typedef int CATCOUNT). Do not type any storage specifiers into the declaration textbox; these are added by the Class Editor.
3. Select the desired access and storage specifiers. Check the Inline check box for an inline function.
4. Click OK.

By default, the first eight letters of the class name are used to derive the source filename for new functions. You may change the file name by entering an alternative name in the Source File textbox of the Add Member dialog box.

Deleting a class member

To delete a class member:

1. Select the class member to be deleted.
2. Choose Delete from the pop-up menu in the Members pane.
3. When the message box requests confirmation, click Yes to delete the member.

Changing member attributes

To change a member's access and storage specifiers:

1. Select the member you want to change.
2. Choose Edit Attributes from the pop-up menu in the Members pane. The Change Member Attributes dialog box opens (Figure 5-7).

   
   Figure 5-7 Change Member Attributes dialog box

3. Select the desired access and storage specifiers. Check the Inline check box for an inline function. Click OK.

If you are editing several members' attributes simultaneously and the access specifiers are not identical, a Don't Change option is displayed in the Access group box. Likewise, if the storage specifiers are not identical, a Don't Change option is displayed in the Storage group box. These options let you change other member attributes without affecting the original access or storage of each member. You may, however, select a particular access or storage specifier, and all members are given that attribute. Also, when you are editing several members' attributes, if the inline attributes are not the same, the Inline check box changes to allow three states (checked, unchecked, and grayed, indicating "Do not change") instead of the normal two-state options.

Viewing and editing member source

To view and edit member declarations and function definitions:

1. Double-click on the member in the Members pane.

   The member's declaration (for data items and pure virtual functions) or definition (for other functions) is displayed in the Source pane. If the source code is not available (as with MFC libraries, for example), the definition is displayed.

2. Click in the Source pane to begin editing. Editing operations here are identical to editing operations in other Source windows.
3. To save changes, choose Save from the pop-up menu in the Source pane.

Note: If you close the current project before you save a source file you've modified with the Class Editor, you cannot discard the changes or close the file until you reopen the project.

Viewing and editing source files

To view and edit the header file containing the class declaration:

1. Select the class in the Classes pane.
2. Choose Show Header from the pop-up menu in the Classes pane. A Source window containing the contents of the class header file is displayed.
3. Edit the class declaration as desired.

   You may add or delete class members as you would without the Class Editor. However, if you add functions to the declaration, you have to add the function definitions manually to the source file as well.

4. Save your changes by choosing Save from the Source window's File menu.
5. To close the Source window, choose Close from the File menu.
6. Click on the Class Editor window. If you have made changes to the header file, a message box asks whether it is OK to reparse. Click Yes.
7. Click on the class whose declaration you just edited to see the member changes updated in the Members pane.

To view and edit the source file containing member function definitions:

1. Select a member function from the Members pane.
2. Choose Show Source from the pop-up menu from the Members pane. (Show Source is dimmed if the source code is not available.)

   The file containing the member function's source code is opened for editing in a Source window.

3. Edit the member functions as desired.

   You may edit member functions as you would without the Class Editor. However, if you change function arguments or return types, or add new functions, you must modify or add the function declarations manually in the header file as well.

4. Save your changes by choosing Save from the Source window's File menu.
5. To close the Source window, choose Close from the File menu.
6. Click on the Class Editor window. If you have made changes to the source file, a message box asks whether it is OK to reparse. Click Yes.

Hierarchy Editor

To open a Hierarchy Editor window, do one of the following:

• Choose Hierarchy Editor from the Goto View submenu of the IDDE's Window menu.
• Double-click on the Hierarchy Editor icon in the Views toolbox, or drag the icon to an empty area of the desktop.

To enable the Hierarchy Editor child windows:

1. Choose Settings from the Hierarchy Editor's pop-up menu. The Editing/Browsing Settings dialog box opens to the Hierarchy page.
2. Check the items labeled Members and Source in the Pop-up Windows group box.
3. Click OK.

Figure 5-8 Hierarchy Editor window

Unlike the Members and Source panes of the Class Editor, Hierarchy Editor windows are independent. They have their own menus and may be positioned, sized, and closed separately. Otherwise, they behave as do the corresponding panes of the Class Editor. For a complete reference on Hierarchy Editor menus and options, see Hierarchy Editor Reference.

Creating classes

Operations relating to class creation and the establishment of hierarchical relationships are carried out in the Hierarchy Editor's graphical display window.

Creating a top-level class

To create a new top-level class:

1. Activate the Hierarchy Editor window.
2. Choose Add Top from the pop-up menu. The Add Class dialog box opens (Figure 5-9).

   
   Figure 5-9 Add Class dialog box

3. Type a name for the new class.
4. Click OK.

Creating a derived class

To create a new derived class:

1. Select the class that will act as the base class of the new class.
2. Choose Add Derived from the pop-up menu.

   You can also perform this step with the mouse. Hold the left mouse button down and drag the cursor from the selected class to an empty area of the window. A rubber band line appears as you do this (Figure 5-10). Release the mouse button.

   The Create Derived Class dialog box opens (this dialog box is similar to the Add Class dialog box).

   
   Figure 5-10 Creating a new derived class using the mouse

3. Type a name for the new class.
4. Click OK.

Creating a sibling class

To create a new sibling class:

1. Click on the class whose base class is to be the base class of the new class.
2. Choose Add Sibling from the pop-up menu. The Create Derived Class dialog box is displayed.
3. Type a name for the new class.
4. Click OK.

Editing inheritance relationships

In altering inheritance relationships, Class and Hierarchy Editors change only the class declarations, not references to base classes and their members in a derived class's constructors or functions. If such references exist, you must change them manually.

Connecting to a base class

To make an existing class a base of another existing class:

1. Click on the class that is to be the derived class.
2. Choose Connect Base from the pop-up menu. The Add Base dialog box opens (Figure 5-11).

   
   Figure 5-11 Add Base dialog box

3. From the listbox, select the class (or classes) that will be the derived class's base class.
4. Select the desired access specifier. Check Virtual if virtual inheritance is desired.
5. Click OK. The display changes to show the new inheritance relationship.

Deleting a connection

To delete an inheritance relationship:

1. Click on the line connecting the base and derived classes. The line is highlighted to show that it is selected (Figure 5-12).

   
   Figure 5-12 Highlighted base-derived connection

2. Choose Delete Base Connection from the pop-up menu.
3. When the message box requests confirmation, click Yes to delete the base connection.

Changing base class

To change a class's base class:

1. Click on the line connecting the derived class and its current base.

   The line is highlighted to indicate that it has been selected. Note that at the end nearest the base class, there is a small black box (referred to as the line's "handle").

2. Click on the line's handle. Holding down the left mouse button, drag the handle over the class that is to be the derived class's new base class.
3. When the message box requests confirmation, click Yes to change the base connection.

Editing inheritance attributes

To edit the base class access specifier:

1. Click on the line connecting the base and derived classes. The line is highlighted to show that it is selected.
2. Choose Edit Base Attributes from the pop-up menu. The Edit Base Attributes dialog box opens (Figure 5-13).

   
   Figure 5-13 Edit Base Attributes dialog box

3. Select the desired access specifier. Check Virtual if virtual inheritance is desired. Click OK.

Working with class members

A list of members of the currently selected class is displayed in the Members child window (Figure 5-14). By default, the member list is sorted into three categories: Data, Functions, and Typedefs. Within each of these categories, items are sorted alphabetically. The colored diamond in front of each member identifies the access as public (green), protected (yellow), or private (red). Lists following each category header can be collapsed or expanded by clicking on the triangular button to the left of the category name.

Figure 5-14 Members child window

Adding a class member

To add a class member:

1. Activate the Members child window.
2. Choose Add from the Member menu or from the pop-up menu. The Add Member dialog box opens (Figure 5-15).

   
   Figure 5-15 Add Member dialog box

3. Type the member declaration. The member may be a data item (for example, int nDogs), a function (for example, int NumDogs()), or a typedef (for example, typedef int DOGCOUNT). Do not type any storage specifiers into the declaration textbox; these are added by the Hierarchy Editor.
4. Select the desired access and storage specifiers. Check the Inline check box for an inline function.
5. Click OK.

By default, the first eight letters of the class name are used to derive the source file name for new functions. You can change the file name by entering an alternative name in the Source File textbox of the Add Member dialog box.

Deleting a class member

To delete a class member:

1. Select the class member to be deleted.
2. Choose Delete from the Member menu or from the pop-up menu.
3. When the message box requests confirmation, click Yes to delete the member.

Changing member attributes

To change a member's access and storage specifiers:

1. Select the member to be changed.
2. Choose Edit Attributes from the Member menu or from the pop-up menu. The Change Member Attributes dialog box opens (Figure 5-16).

   
   Figure 5-16 Change Member Attributes dialog box

3. Select the desired access and storage specifiers. Check Inline for an inline function. Click OK.

The class declaration in the header file is modified and the Members display is updated to reflect the changes.

Viewing and editing member source

To view and edit member declarations and function definitions:

1. Double-click on the member in the Members child window.

   The member's declaration (for data items and pure virtual functions) or definition (for other functions) is shown in the Source child window.

2. Click in the Source child window to begin editing. Editing operations here are identical to those in other Source windows.
3. To save changes, choose Save from the pop-up menu.

Viewing and editing source files

To view and edit the header file containing the class declaration:

1. Click on the class in the Hierarchy Editor window.
2. Choose Show Header from the pop-up menu.

   A Source window containing the contents of the class header file opens.

3. Edit the class declaration as desired.

   You may add or delete class members as you would without the Hierarchy Editor. However, if you add function declarations, you must add the function definitions to the source file manually as well.

4. Save your changes by choosing Save from the Source window's File menu.
5. To close the Source window, choose Close from the File menu.
6. Click on the Hierarchy Editor window. If you have made changes to the header file, a message box asks whether it is OK to reparse. Click Yes.
7. Click on the class whose declaration you just edited to see the member changes updated in the Members window.

1. Select a member function from the Members child window.
2. Choose Show Source from the Member menu or from the pop-up menu.

   The file containing the member function's source code is opened for editing in a Source window.

3. Edit the member functions as desired.

   You may edit member functions as you would without the Hierarchy Editor. However, if you change function arguments or return types, or add new functions, you must modify or add the function declarations manually in the header file as well.

4. Save your changes by choosing Save from the Source window's File menu.
5. To close the Source window, choose Close from the File menu.
6. Click on the Hierarchy Editor window. If you have made changes to the source file, a message box asks whether it is OK to reparse. Click Yes.

6. Editing Program Code

In addition to its role in editing project code, use the Source window for monitoring program execution while debugging. See Chapter 24, Commands Available in Debugging Mode, for more information.

Chapter 21, Text Editor Reference, contains descriptions of all Source window menu commands, toolbar icons, dialog boxes, and options. Refer to it once you've read this chapter and you need more details about specific aspects of the editor.

Refer to the Digital Mars C++ IDDE Help for the key combination used to execute a particular editting command. It contains a reference to all key combinations for every key binding set.

Role of the Text Editor

Anyone familiar with Windows can get started quickly with the IDDE text editor because it uses standard Windows editing commands. In addition, the text editor has some features that make working with C and C++ files easier. For example, the editor can automatically indent or unindent after braces and can check delimiters.

The text editor can display keywords, preprocessor directives, and comments in special font styles and colors. This technique helps track errors in source code while editing. For example, an unmatched comment (/* without a matching */) turns a large part of the code a different color, making it obvious where the problem lies. Keywords and preprocessor directives are easier to spot when they are in a different color or font style. Misspelled keywords can be caught immediately when they remain displayed in the default font.

Source windows are an integral part of the IDDE environment and work together with other IDDE windows to make application development easier. For example, the IDDE automatically saves all files open in Source windows when you rebuild your project. During compilation, error messages are displayed in the Output window; double-clicking on an error message opens a Source window on the corresponding source file, if necessary, and then jumps to the line in the source code that caused the error.

The Source Window

[Figure 6-1 Source window]

Most work with a Source window is in the editing area. This is where text is displayed and edited, as described later in this chapter. The Source window contains a typical IDDE window menu and toolbar; a pop-up menu is available by right-clicking in the editing area. Complete information about the menus and toolbar is contained in Chapter 21, Text Editor Reference.

The status bar, shown in Figure 6-2, provides information about the current state of the file being edited.

[Figure 6-2 Source window status bar]

Information string

Displays information about the state of the current function. For example, the message Pattern not found is displayed when the Find command is unable to locate the specified pattern.

Modification flag

Displays Mod if the file has been modified since it was last saved.

Insertion mode

Displays Ovr when the typing mode is set to overtype. When the typing mode is set to insert, nothing is displayed in this field. Toggle the insertion mode with the Insert key.

Read-only flag

Displays Rd when the file is set to read-only. When the file is in read/ write mode, nothing is displayed in this field. The read-only attribute is set in the Current Buffer Options dialog box described later in this chapter.

Line number

Displays the line number of the insertion point.

Column number

Displays the column position of the insertion point.

File Manipulation

Creating files

Opening files

• Choose a file from the list of recently opened files at the bottom of the IDDE's or Source window's File menu.
• Double-click on a filename in the Project window.
• Click New! in a Source window to open another view of the same file.
• Choose Load from the Source window's File menu. The file you select opens in the same Source window, replacing the previous file.

Saving files

To save the files in all Source windows, choose Save All from the Source window's File menu. The editor displays the Save As dialog box for any untitled file.

To save an unnamed file or a named file under a new name, choose Save As from the File menu. The text editor displays the File Save As dialog box, as shown in Figure 6-3.

[Figure 6-3 File Save As dialog box]

Enter a name for the file and click OK.

Writing blocks of text to files

Printing files

[Figure 6-4 Text Print dialog box]

The contents of the Text Print dialog box depend on the default printer you specify in the Windows control panel. Make any necessary changes in the dialog box, then click OK to print.

Closing files

Text Editing

Typing mode

Word wrap

Indentation

It also is possible to change the indentation of a selected block of text by choosing Indent Block or Unindent Block from the Format Text submenu of the Source window's pop-up menu.

Moving around in a file

Jumping to a matching delimiter

Delimiter checking can also be done automatically using the text editor options described later in this chapter.

Note: The IDDE editor looks for any parenthesis, bracket, or brace, including text in strings and comments.

Jumping to a specific line

[Figure 6-5 Goto Line dialog box]

Type the line number in the textbox and click OK. The editor moves the insertion point to the beginning of the specified line.

Jumping to a function

[Figure 6-6 Goto Function dialog box]

You can select a function name from the scrolling list or type in a function name. The insertion point then moves to the beginning of the specified function.

Jumping to a bookmark

[Figure 6-7 Bookmarks dialog box]

To use bookmarks, first position the insertion point where you want the bookmark to be located. Then choose Bookmark from the Goto menu, select a bookmark, and click on the Drop button. When you want to return to this location, click on this entry's name in the list of bookmarks, then click on Goto.

Selecting text

Both commands require that you first select a block of text in the standard manner. Column changes the currently selected text block into a column-oriented select block; only the characters in the columns between the start and end of the original text block are selected. This is shown in Figure 6-8.

[Figure 6-8 A column select block]

Line changes the currently selected text block into a line-oriented select block; all the lines from the start to the end of the original text block, including the first and last lines, are selected.

This is shown in Figure 6-9.

[Figure 6-9 A line select block]

Choosing Normal from the Select submenu of the pop-up menu changes a column-or line-oriented text block back to the original selection. Cancel deselects the current selection block; this can also be accomplished by clicking somewhere outside the selected text.

The text editor supplies standard Windows functions for cutting, copying, pasting, and deleting text. These functions can be accessed through either the Edit menu or the pop-up menu. In addition, by clicking and dragging a block of selected text, you can reposition the text anywhere in the buffer. Press the Control key while releasing the block to copy rather than move the block. When you are dragging text blocks around in this way, a small outlined box is drawn next to the cursor to indicate this mode.

Searching and replacing

Finding a string

[Figure 6-10 Find dialog box]

If you select some text before opening the Find dialog box, the selected text becomes the default search pattern. You can either use this text as it appears, select a previous string from the drop-down list, or type in a new string. Then click on the Next (or Previous) button. The editor locates and selects the next (or previous) occurrence of the string in the active file. You can repeat the search in the same direction by choosing Repeat Find from the Edit menu. If the pattern is not found, the editor returns to the current insertion point and displays Pattern not found in the status line.

By checking Regular Expression in the Find dialog box, you can use the wildcard characters ? and * in your search string. The ? character matches any single character, while the * character matches any string of consecutive characters. Regular expressions permit more powerful text searches.

Replacing a string

[Figure 6-11 Replace dialog box]

Type the search string or regular expression in the Pattern textbox, just as you did in the Find dialog box described earlier. Then type the replacement string in the Replacement textbox. Note that wildcards cannot be used in the Replacement textbox. You can also select previous search and replacement strings from the drop-down list. Begin the replacement by clicking OK.

If you check the Confirm Changes option, the editor scrolls the display to each occurrence of the search string, selects it, and asks whether you want to replace it by displaying the Confirm Replacement dialog box in Figure 6-12.

[Figure 6-12 Confirm Replacement dialog box]

Click on Yes to replace the string and continue searching, or click on No to continue searching without replacing. Click on Cancel to stop searching. If you do not check Confirm Changes, the editor replaces all occurrences of the search string without confirmation messages.

You can use the Undo command to undo the entire set of replacements of the search string.

Searching through multiple files

• Locating undefined symbols
• Changing function, variable, or class names
• Fixing references to a function with changed parameters

The Global Find dialog box opens, as shown in Figure 6-13.

[Figure 6-13 Global Find dialog box]

To perform a global search, first specify the set of source files you want to search. You can choose to search:

• All source files in the current project
• All files listed in the Search window (which opens after the first search)
• All files matching the criteria you specify, including filename, directory, date, time, and file attributes

By double-clicking on a filename, you can open the file; the first occurrence of the pattern is highlighted. You can continue searching for your string or expression in that file by choosing Repeat Find from the Source window's Edit menu. For more information, see Chapter 21, Text Editor Reference.

Undoing edits

Text Editor Options

[Figure 6-14 Editing/ Browsing Settings dialog box]

The Editing/Browsing Settings dialog box is a tabbed dialog that contains numerous options for different aspects of the text editor:

• The Text page contains options for indentation, cursor styles, keyboard emulation, and text editor font.
• The C++ page lets you set options to enable C++ mode globally, check delimiters, indent after braces, auto-align comments, and add keywords to the keyword dictionary.
• The Keys page lets you customize key bindings and assign key combinations to macros.
• The Display page lets you select special colors and font styles for keywords, comments, and preprocessor symbols.
• The Backup page lets you set options for backing up files.
• The General page lets you set the maximum undo level and select a key binding file.

[Figure 6-15 Current Buffer Options dialog box]

This dialog lets you override global indentation options, set word wrap, and set the buffer to read-only.

You can find detailed information about text editor options in Chapter 21, Text Editor Reference.

Macros

Compiling Files and Checking Errors

For more information about compiling files and building the project, see Chapter 8, Testing an Application.

7. Adding Look and Feel with Resources

ResourceStudio contains tools for creating and modifying the resources. This chapter defines the different types of resources and explains how to use ResourceStudio to create three basic resources: menus, dialog boxes, and bitmaps. The final section describes how to work with the identifiers by which resources are referenced in the source code.

For more information about ResourceStudio, see ResourceStudio Resource Editor. For more information on resources and programming with resources, refer to the following texts:

• Programming Windows 3.1 by Charles Petzold
• Microsoft Windows Programmer's Reference, Volume 4: Resources

What Are Resources?

An application's resources typically are defined in a resource script file (.rc). Each resource definition contains information and data relevant to that resource type, as well as the identifier by which the resource is referenced in the source code. Resource script files are created and edited with ResourceStudio.

Resources are compiled by a special resource compiler and are linked to the Windows application separately from the application code. This modular design enables you to modify the appearance of an application without changing, or even accessing, the program source code. Separating resources from code also makes it easier to use the same resource definitions for multiple applications.

Resource Types

Bitmaps

Cursors

In addition to image information, a cursor resource also specifies the cursor's hot spot, the exact pixel in the image that maps to the mouse pointer's screen location.

Icons

Fonts

Dialog boxes

A dialog box resource is a complex set of data describing each control in detail, as well as general properties such as the dialog box size and location.

Menus

Accelerators

Strings

Version information

User-defined resources

Using ResourceStudio

• Create new resources in script or binary form
• Edit resources, even those already linked to an executable or DLL
• Copy resources between files

Starting ResourceStudio

Edit

opens the current project's resource (.rc) file for editing.

New

opens the current project's resource file. A dialog box then opens, allowing you to create a new resource.

Open

opens a dialog box from which you can select for editing any file that contains resources.

Settings

opens ResourceStudio to the Settings dialog box, but does not load any resource file.

To create a new resource file, choose Open from the Resource menu, and in the File Open dialog box click Cancel. Then, double-click on the ResourceStudio icon on the desktop. The Resource Studio Shell window opens (Figure 7-1).

Figure 7-1 Resource Studio Shell window

The Shell window is ResourceStudio's main window and contains the main menu and toolbar. From this window, you can create and open resource files and set ResourceStudio preferences.

Another window that will open as you work is the Property Sheet. The Property Sheet does not open immediately, but rather opens when it is first needed. While creating and editing resources, you can use the Property Sheet to view and edit properties of the currently selected object. (In this context, "object" refers to either a resource as a whole or to an element within a resource, such as a dialog box control or a menu item.) Some types of objects have multiple pages of properties; to switch between pages, simply click on the tabs.

Creating a new resource file

Resources are contained in resource files. Use ResourceStudio to create and edit most types of files that store Windows resources. For example, you can edit the resources of executable files even if you do not have the original source code.

To create a new resource file, choose New from the File menu. The New File dialog box opens (Figure 7-2), listing the types of resource files that can be created with ResourceStudio.

Figure 7-2 New File dialog box

Select the type of resource file you want to create (see Table 7-1). Note that resource script (.rc) and binary resource (.res) files usually contain more than one resource. If you are starting to create resources for a new application, .rc is likely to be your choice of file type. Resource scripts can contain any type of resource.

Resources such as icons can be contained either in individual icon resource files (.ico) or with other resources in a resource script file. Some resources, such as dialog boxes and menus, are contained only in .rc or .res files. Thus, these resource options do not appear separately in the New File dialog box.

Warning: If dialog boxes for NT come out with a white background, select Windows 95 as the target platform. This is because the Windows NT target is for NT 3.51, an old version.

After selecting a type of resource file, click OK. The window that opens next depends on the type of file you specified. If you selected one of the file types containing a single resource (icon, cursor, bitmap, or font), that resource type's editor opens in a separate window.

If you selected Resource Script or Binary Resource, the Browser window opens (Figure 7-3).

Figure 7-3 Browser window

The Browser window has three main areas:

Resource Types:

A listbox containing all the resource types found in the current file.

Resources:

A listbox containing resources of the currently selected type.

Preview/Edit:

A display of the selected resource. Resources also are opened for editing in this area when created, or by choosing Edit Resource from the File menu.

Note: ResourceStudio has several subprograms, each of which is used to edit a particular resource type. In this chapter, for example, you will use the Menu editor, Dialog box editor, and Bitmap editor. Each individual resource editor can either be opened in a separate window or can use the right pane of the Browser window from which it is launched. The latter is the default behavior in most circumstances.

Editing a resource file

• Windows executable (.exe): Bound resources of any type
• Dynamic-link library (.dll): Bound resources of any type

Creating a new menu resource

Figure 7-4 A typical menu

A menu is a hierarchical structure containing pop-up items, menu items, and separators.

• Pop-up items open a drop-down menu box containing menu items and additional pop-ups. The top-level items that are displayed on the window's menu bar are usually pop-up items. A pop-up item can be thought of as a container for other items (including other pop-ups).
• Menu items usually constitute the majority of items in drop-down menus. When a menu item is chosen, Windows sends a message containing the item's command identifier to the application.
• Separators are lines that divide the menu into logical groups.

Figure 7-5 Menu editor open in Browser window

Note: While a resource editor is open in the Browser window, the Browser window's menu is replaced by that of the particular resource editor. The editor's toolbar is displayed at the top of the right pane, below the Browser window's toolbar.

The new menu resource initially contains a single pop-up item and a menu item. The list of items is indented to show the hierarchy. Pop-up items are labeled POPUP, menu items are labeled MENUITEM, and separators are labeled SEPARATOR. The currently selected item is enclosed in a box; to select any item, click on it. The Property Sheet shows properties of the selected item.

The Test menu window (Figure 7-6) opens at the same time. You can test the menu in progress at any time in this window.

Figure 7-6 Test menu window

Adding a pop-up item

The Property Sheet displays the properties of the new pop-up item (Figure 7-7). At this point, you probably want to change only the menu name, which is contained in the Text field.

Figure 7-7 Properties of a Pop-up menu

When changing the menu name, you can also assign an activation key to the menu. Put an ampersand (&) in front of the corresponding letter in the text.

Adding a menu item

The Property Sheet displays the properties of the new menu item (Figure 7-8). You can change the item's text and add an activation key. As with pop-up items, you add an activation key by typing an ampersand (&) in front of the corresponding letter in the text.

Figure 7-8 Properties of a menu Item

The ID field contains the command ID, which is sent to the application when the user chooses this menu item. New command and resource IDs are assigned automatically to new objects when they are created; you can also change ID names and numerical values as desired. For more information on resource IDs, see the section "Managing Resource IDs" later in this chapter.

Adding separators

Editing menus

Rearrange menu items quickly by clicking and dragging. To move an item, drag the item to the location where it should be inserted. If you hold down the Control key while dragging, a copy of the selected item is inserted. The copy is given a new, unique resource ID.

You can also rearrange menus with the arrow keys. To move an item up or down within its present level in the hierarchy, press Ctrl+Up Arrow or Ctrl+Down Arrow. To move an item horizontally, use Ctrl+Right Arrow or the Ctrl+Left Arrow.

Closing the menu editor

Figure 7-9 Browser window after creating menu resource

The Resource Types list contains an entry called Menu to show that you have at least one menu resource. The Resources list contains the ID of your menu resource. The Preview/ Edit area shows a preview of the new menu.

The Property Sheet displays the menu resource's ID and memory options (Figure 7-10).

Figure 7-10 Properties of a menu resource

To edit a menu resource, double-click on its ID in the Resource list, or select the resource and choose Edit Resource or Edit in Separate Window from the File menu.

Creating menus with accelerators and item help

1. Create a string table resource by choosing New String Table from the Browser window's Resource menu.
2. Close the String Table editor by choosing Close Editing from the File menu.
3. Create a new accelerator table resource by choosing New Accelerator Table from the Browser window's Resource menu.
4. Close the Accelerator Table editor by choosing Close Editing from the File menu. Note the accelerator table's resource ID.
5. Create a new menu resource by choosing New Menu from the Browser window's Resource menu.
6. Make the new menu's resource ID the same as that of the accelerator table resource. In the Property Sheet, select the accelerator table resource's ID from the drop-down list in the ID field. You now can add menu items with accelerators and item help.

To show which key combination is associated with each menu item, add the accelerator to the item text. For readability, the accelerator is usually separated from the command name with a tab. For example, if you want Ctrl+F to be the accelerator for a command called Find, enter Find\tCtrl+F into the Text field of the menu item's Property Sheet (Figure 7-11).

Figure 7-11 Menu item text

Simple guidelines for creating menus

• Place frequently chosen options near the top of the menu to make them more accessible to the user.
• Group related options under specific menu titles.
• Follow standard conventions to make the application easier to use.

Creating a new dialog resource

Figure 7-12 A typical dialog box

The following types of controls can be included in your dialog boxes:

• Push buttons send command codes to your application when the user clicks on them. They trigger an immediate action.
• Check boxes are rectangular buttons that turn options on or off. Text describing the option is displayed to the left or right.
• Radio buttons provide a set of options, only one of which may be selected. They are generally arranged in logical groups of two or more.
• Edit controls (or textboxes) are rectangular boxes used for text entry.
• Listboxes contain a list of items, usually in text form. The user can browse through the list and select one or more items.
• Comboboxes combine the features of an edit control and a listbox; they let the user select an item from a list or type a selection into the textbox.
• Scroll bars let the user specify a numerical option with an analog control. (Edit controls and listboxes have their own scroll bars and do not need a stand-alone scroll bar.)
• Group boxes are rectangular frames with an optional caption, used to group other controls together visually.
• Static text is used to convey information or to label controls that do not have captions (such as edit controls).
• Pictures are used for decorative purposes. Picture types include empty frames, solid boxes, and icons.
• Custom controls are user-defined controls implemented in a DLL.
• User controls are user-defined controls that are not implemented in DLLs, or whose implementation is non-standard. (ResourceStudio treats VBX controls as user controls.)
• The following Windows 95 controls are supported: Animate controls, Tab controls, Tree View controls, List View controls, Hotkey controls, Track Bars, Progress controls, and Up/ Down controls.

Figure 7-13 DialogExpress dialog box

DialogExpress gives you several options for simple dialog boxes that you may use as a starting point for your own dialog box. Select Standard and click OK. The Dialog editor opens in the right pane of the Browser window (Figure 7-14).

Figure 7-14 Dialog editor open in Browser window

At the same time, the Dialog editor toolbox (Figure 7-15) opens. This toolbox provides shortcuts to commands in the Tool menu that let you create the different types of dialog box control.

Figure 7-15 Dialog editor toolbox

The Property Sheet shows the General, Styles, and Look properties of the dialog box (Figure 7-16). You may want to start by changing the dialog box title.

Type the new title into the Text field of the General properties page.

Figure 7-16 Properties of a dialog resource

Adding a push button

1. Choose Push Button from the Tool menu or click on the corresponding icon in the toolbox.
2. Click in the dialog box on the point at which you want to position the upper-left corner of the new button. Hold down the left mouse button and drag the cursor. A rubber-band rectangle appears.
3. Release the left mouse button when the rectangle is the proper size for the new button. A new push button is placed in your dialog box (Figure 7-17).

Figure 7-17 Dialog box resource with new push button

The new push button is selected and highlighted. Then move and resize the new push button control with the mouse.

• To move a control, click and drag it to a new location.
• To resize a control, click and drag one of the eight "handles" that appear along its edges.

The Property Sheet lets you modify push button properties (Figure 7-18). To change the button text, for example, change the Text field to the desired text. As with items in menus, you can set the activation key of a button or other control by typing an ampersand (&) before the corresponding letter in the text.

Figure 7-18 Properties of a push button control

Adding static text

The Property Sheet shows the properties of the static text (Figure 7-19). To change the text, edit the Text field. After entering the text, you can resize the static control to the size of the text by dragging the handles.

Figure 7-19 Properties of a static text control

To center the text within the control, select Center from the drop-down list in the Align/ Style property. Center the control within the dialog box by choosing Horizontal from the Center submenu of the Controls menu.

A static text control may contain multiple lines of text. While typing text into the Caption field, press Ctrl+Enter to start a new line. Likewise, insert tab characters by pressing Ctrl+Tab.

Testing the dialog box

Figure 7-20 Testing the new dialog box

When you are testing the dialog box, ResourceStudio does not function; you must close the test dialog box by pressing Alt+F4 before continuing.

Aligning controls

1. Add a few odd-sized buttons to your dialog box, using the procedure described in the section "Adding a push button" earlier in this chapter. Place them in a horizontal row.
2. Select all the buttons at once by clicking on one, then holding down either the Shift or Control key as you click on the others. You can also choose Select from the Tool menu and drag a rubber-band box around the controls.
3. Establish one button as the "standard." Hold down Control and click on this button. The standard button is highlighted in blue on your screen. Figure 7-21 shows what your dialog box might look like. In the example, the button labeled "# 2" has been selected as the standard.

Figure 7-21 Multiple selection of controls

Now you can perform any of the following alignment operations from the Controls menu:

• To make all the buttons the same size as the standard, choose Both from the Make Same Size submenu.
• To align the tops of the buttons with the top of the standard, choose Top from the Align submenu.
• To even out the horizontal spacing between the buttons, choose Horizontal from the Space Evenly submenu.

Closing the dialog box editor

Figure 7-22 Browser window after creating dialog box resource

After creating a dialog box resource, you can use ClassExpress to create a corresponding dialog box class, set up the class's message map, and implement dynamic data exchange and validation. ClassExpress can be run directly from the Browser window's File menu. For further information, see Chapter 18, More about ClassExpress, as well as Chapter 13, Lesson 4: Add Messages with ClassExpress and Chapter 14, Lesson 5: Add a Dialog Box with ClassExpress.

Creating a new bitmap resource

To create a new bitmap resource, choose New Bitmap from the Resource menu of the Browser window. The BitmapExpress dialog box opens (Figure 7-23).

Figure 7-23 BitmapExpress dialog box

BitmapExpress allows you to set the number of colors and the initial size of the bitmap. If you are creating a bitmap for an MFC toolbar, you also can specify the number of buttons. For now, accept the defaults and click OK. The Bitmap editor opens in the right-most pane of the Browser window (Figure 7-24).

Figure 7-24 Bitmap editor open in Browser window

The Bitmap editor window is divided into two panes. Draw in either. To change the relative sizes of the panes, click and drag the bar separating the panes.

The Bitmap editor toolbox (Figure 7-25) also opens. This toolbox lets you choose graphics tools (also available in the Tool menu), set foreground and background colors, and select the line width and background pattern.

Figure 7-25 Bitmap editor toolbox

The Property Sheet shows the General and Palette properties of the bitmap (Figure 7-26). Page between the two groups of properties by clicking on the tabs. The File field specifies the bitmap file; bitmaps are included in resource scripts by reference. If you want to change the bitmap file's name, type a new name into the File textbox.

Figure 7-26 Properties of a bitmap resource

Changing bitmap size

Selecting colors and patterns

• Foreground color: Click on the color in the color palette with the left mouse button.
• Background color: Click on the color in the color palette with the right mouse button.
• Line type: Click in the line type display and select a line type from the pop-up menu.
• Background pattern: Click in the background pattern display and select a pattern from the pop-up menu.
• Brush: Click in the brush display and select a paintbrush or spray brush from the pop-up menu. The menu is only available when the Paintbrush or Spray brush tool is selected; it is also available by right-clicking on these tools.

Drawing tools

• Eraser: Removes all or part of the image
• Pen: Draws individual pixels or freehand lines
• Selection tool: Selects a rectangle that may be cut, copied, flipped, or inverted
• Brush: Paints freehand lines with the selected brush
• Spray brush: Paints patterns of pixels
• Paint can: Floods an area with color
• Line: Draws straight lines
• Eye-dropper: Picks up a color from the image
• Rectangles and ovals: Draw outlines or solid shapes

Zoom and grid

To help finish the details of the image, you can display a pixel grid in the image. A pixel grid can be displayed only when the zoom factor is 4 or 8. To show a pixel grid, choose Grid from the View menu.

Closing the bitmap editor

Figure 7-27 Browser window

Useful ResourceStudio features

Toolbars and pop-up menus

In many parts of ResourceStudio, clicking with the right mouse button opens a pop-up menu. The contents of the menu depend on the item clicked and on the current mode or tool. Pop-up menus are a convenient way to access commands available from the main menu.

Undo and redo

Operations that you have performed are saved in lists. To set the number of operations that are saved (and thus that can be undone or redone), choose Preferences from the Shell window's Edit menu. Each Browser window and each resource type's editor keeps its own undo and redo list.

To view a list of stored operations, click the right mouse button on the Undo or Redo toolbar icon. Select one or more operations from the list (see Figure 7-28).

Figure 7-28 List of stored operations in Bitmap editor

Clipboard and drag and drop

ResourceStudio also supports drag and drop of all items that can be cut, copied, and pasted. To move a resource or resource element, click and drag it to the new location. For example, to move resources from one file to another, open a Browser window for each file, then drag the resources from the first file to the second. To copy rather than move the element, hold down the Control key until you have released the item.

Managing Resource IDs

Resource ID field

• Textual
• Symbolic
• Numeric

Textual IDs

Symbolic IDs

Assign a symbolic ID either by typing the name into the ID field or by selecting a pre-existing ID from the drop-down list. If you enter a new symbol, ResourceStudio automatically assigns a unique numeric value. If you want to specify the numeric value, follow the symbolic name with an equal sign and the value (for example, IDD_ TEST= 451). Reassign the value of an existing symbol in the same way.

Numeric IDs

Note: When editing resources in .exe or .dll files, remember that the compiled source code refers to resources and commands by the numeric (or textual) ID; reassigning or changing IDs may result in incorrect behavior.

Automatic creation of resource IDs

When assigning values to new symbols typed in by the user or created automatically, ResourceStudio uses different ranges for various purposes:

Resource item range (100-1999)

Used for resources within a resource file

User range (2000-2999)

Used for resource IDs created by the user from within the Resource ID Browser dialog box (see below)

Control range (3000-31999)

Used by the Dialog editor for dialog controls

Command range (32000-65535)

Used by menu and accelerator editors for menu commands

Resource ID browsing

The Resource ID Browser dialog box opens (Figure 7-29).

Figure 7-29 Resource ID Browser dialog box

The upper listbox shows all the symbolic resource IDs in the resource file. Symbols can be sorted by name, value, or used/ unused state. Click on an ID to show a list of resources using the ID in the lower listbox. Open a resource shown in the lower listbox by double-clicking on it, or by selecting it and clicking View Usage.

The remaining buttons are:

New

Opens the New Resource ID dialog box. Here you can create a new symbol and assign a value. By default, the value is in the User range (2000-2999).

Delete

Deletes the currently selected symbol. A symbol may only be deleted if it is not in use.

Change

Opens the Change Resource ID dialog box. Here you can change the symbol name or value.

Renumber

Performs a renumbering operation on all symbolic IDs. Each symbol is examined and a new value is assigned based on how it is used. If a symbol is used by items whose values are usually in different ranges, a dialog box asks for the range in which to place the value.

8. Testing an Application

This entire phase of the development cycle can be carried out in the IDDE. Because all debugging in Digital Mars C++ takes place within the IDDE, you do not have to leave the IDDE and run a separate debugger. The IDDE itself provides a wealth of tools for examining all facets of your application's structure and behavior.

Two other chapters present detailed information about the debugging capabilities of Digital Mars C++. Controlling and Configuring the Debugger describes the commands you use when debugging, and the options available in the IDDE for configuring the debugging environment. Commands Available in Debugging Mode, describes the commands available in each of the debugging windows.

Debugger Highlights

• Provides a Windows graphical user interface
• Debugs Windows applications under Windows on the same screen
• Debugs DOS applications running in a DOS box under Windows 3.1
• Takes advantage of virtual memory, letting you debug large DOS applications under Windows 3.1
• Debugs Win32s applications (in the Win32s IDDE, scw32s.exe) under Windows 3.1
• Debugs 32-bit Windows and character-mode console applications (in the Win32 or 32-bit IDDE, scw32.exe)
• Provides a graphical representation of data structures
• Supports high-speed, hardware watchpoints, and breakpoints
• Lets you drag and drop to execute commands

Choosing an Environment for Debugging

• To debug a Win32 executable under Windows 95 or Windows NT, use the Win32 IDDE (scw32.exe).
• To debug a 16-bit executable, use the 16-bit IDDE (scw.exe).
• To debug Win32s executables under Win32s, use the Win32s IDDE (scw32s.exe).

Building a Project

Selecting the project type

[Figure 8-1 Target page of the Project Settings dialog box]

On this page, choose the operating system your target executable will run on, and the target type. Not all target types are available with all operating system types.

The Target page also presents the option of building a Debug or Release version of the executable. If you want to debug your executable, select the Debug option.

For more information on the Target page of the Project Settings dialog box refer to More about Projects and Workspaces.

Setting compiler and linker options for debugging

To verify that the these settings are appropriate, choose Settings from the Project menu, and then click on the Build tab to select the Build page of the Project Settings dialog box. Select the Debug Information subpage by clicking on that label in the left listbox. The Debug Information subpage is shown in Figure 8-2.

[Figure 8-2 Debug Information options]

For more information about project, compiler, and linker options, see More about Projects and Workspaces.

Building executable files

Performing a standard build

The IDDE Make facility is used by default to determine the steps needed to build your project. It is functionally identical to the DOS command-line Make utility SMAKE, included with Digital Mars C++. If you need to use a different, DOS command-line Make utility, such as NMAKE or PolyMake, you can do so; see More about Project Build Settings, for details on how to use an external Make program.

Rebuilding the project

Typical situations in which you use the Rebuild All command include:

• When you have changed some of the project options
• When you suspect corrupted object .obj files
• When you want to create a final build

Linking the project

Typical situations in which you use the Link command include:

• When you have added a new library .lib file
• When you wish to build from object .obj files only
• When you have changed linker options

Other project options

Precompiling headers

Generating an assembly listing

Running a Project

If your program requires no command-line arguments, choose Execute Program from the Project menu. The IDDE launches your application.

If your program requires arguments, first choose Arguments from the Project menu. The IDDE displays the dialog box in Figure 8-3.

[Figure 8-3 Run Arguments dialog box]

Enter your arguments -- not the program name -- in the dialog box. For example, entering:

*.* /s 

After specifying the arguments, click OK. Then run your application as described above.

Quick Start: Debugging an Application

After building your project, you can enter debugging mode by choosing Start/Restart Debugging (F4) from the Debug menu. (That is, you may either choose this command from the menu, or type its keyboard shortcut given in parentheses.) Alternatively, you can click on the Restart Debugging icon in the Debug toolbox. Any open Source windows change to debugging mode. Your application executes to the breakpoint set automatically on WinMain (for Windows applications) or main (for DOS applications and 32-bit console applications).

Other debugging windows, such as the Function window and Data/ Object window, can be opened as needed from the Views toolbox or from the Goto View submenu of the IDDE's Window menu.

In debugging mode, the Start/Restart Debugging command on the Debug menu remains available. This command restarts the program. The Stop Debugging command on the Debug menu exits debugging mode, and returns the IDDE to editing mode.

Stepping through code

Note: If you accidentally step into a function call when you meant to step over it, you can move to where you intended to be- the statement following the call- by choosing Return from Call from the Debug menu. This command executes to the current function's return address (unless a breakpoint or watchpoint is encountered before control reaches that point).

Setting and clearing breakpoints

To set a breakpoint on a statement, first click on that statement in the Source window to make it the selected line. Then choose Set/Clear Breakpoint (F9) from the Source window pop-up menu (which appears when you click the right mouse button in the Source window), or click on the Toggle Breakpoint icon in the Debug toolbox. These commands act as toggles; repeating them clears the breakpoint.

The Source window pop-up menu, as it appears in debugging mode, is shown in Figure 8-4.

[Figure 8-4 Source window pop-up menu in debugging mode]

A breakpoint symbol in the left margin of the Source window indicates a breakpoint on the adjacent line. You can also clear a breakpoint by dragging the symbol out of the Source window.

Executing up to a statement

Viewing a list of functions

You can easily set a breakpoint at the beginning of a function from within the Function window by choosing the Set/Clear Breakpoint (F9) command from the Bpt menu.

Examining the values of variables

Examining the call chain

The Call window's Show menu contains commands that let you zoom in on a particular function in the chain. For example:

• The Source command updates the Source window and displays the statement that is executing within the selected function.
• The Data command updates the Data/Object window and displays local data for the selected function.

Setting watchpoints

Digital Mars C++ debuggers are designed to take advantage of hardware watchpoints provided by 386 and higher microprocessors. The Digital Mars C++ installation program may install the file SCWDEBUG. 386 in the [386Enh] section of system. ini if your system needs it to allow the use of hardware watchpoints. Because watchpoints are implemented with hardware assistance, using this powerful tool imposes no speed penalty on program execution.

Setting a watchpoint on a variable

[Figure 8-5 Set Watchpoint dialog box]

The debugger maintains information about the type of variables and their location in memory. The selected variable's type determines the size of the watchpoint. The Set Watchpoint dialog box displays the address and size of the watchpoint as noneditable fields, and provides options for breaking on a Read access, Write access, or both. To clear the watchpoint, choose Clear Watchpoint from the Watch menu of the Data/Object window.

Warning Exercise caution when setting a watchpoint on an automatic variable (that is, a local, nonstatic variable). If you attempt to set such a watchpoint, the debugger warns you by displaying a message on the status line. You should clear the watchpoint by the time the function whose local variable you are watching returns. If you don't, Windows itself can use the stack location subsequently, thus triggering the watchpoint and causing Windows to crash.

In addition to setting watchpoints on variables, watchpoints can also be set on locations in memory using the Memory window, whose Watch menu is identical to that of the Data/Object window.

Letting your program run until the next breakpoint

Letting your program run until it terminates

Interrupting execution of the debugged application

The technique is most useful when you suspect that your own code is hung. Returning to the debugger lets you examine your program's state, which may be one that you thought impossible. Inspecting the values of variables and the call chain can suggest how to identify and eliminate the source of the error.

Note: Use Ctrl+Alt+F11 to break execution of Win32s applications.

9. Introduction to the Tutorial

The tutorial is designed to complement Part Two, "Creating an Application with Digital Mars C++." The tutorial provides a quick tour of the IDDE that shows you how to perform the most common tasks. Part Two contains more in-depth information, to show you procedures for less common tasks and alternative ways of accomplishing things.

Prerequisite Knowledge

For more information, consult the references listed in Chapter 1, Introducing Digital Mars C++.

The Tutorial Application

The hypertext files that the tutorial applications accept as input are text files containing simple commands that control document formatting and show images as well as commands that define links to other such documents. The markup language recognized by the tutorial applications, referred to throughout the tutorials as TML, is a subset of the Hypertext Markup Language (HTML). HTML is a format that has become a standard for information interchange on the World-Wide Web (WWW), a distributed hypermedia system accessible through Internet connections.

Special WWW browser programs enable users worldwide to access and share text, graphics, audio, and other data. The tutorial applications only hint at the richness of full-featured WWW browsers. The DOS TML Reader built in Lesson 1 is called TMLDOS; the Windows version of Lessons 2 through 5 is called TMLRead.

Tutorial Structure

• Lesson 1 teaches you the basics: how to start the IDDE, open Source windows for editing text, and compile and run a program. In addition, the first lesson shows you how to run in debugging mode and perform fundamental debugging tasks. The example program in Lesson 1 is a DOS application; however, the skills you learn are equally applicable to Windows application development.

• Lesson 2 shows you how to use AppExpress to generate an application framework for a Windows program. You also learn to use precompiled headers and to use TRACE calls within your program to track its progress. Lesson 2 concludes with a brief introduction to MFC and describes the classes that constitute the application framework you generated.

• Lesson 3 Lesson 3 teaches you how to use the ResourceStudio. You modify the menu and accelerator table generated by AppExpress, and attach a new toolbar bitmap to your application's resources. You then edit the source code to make use of the new toolbar.

• Lesson 4 shows you how to use ClassExpress to add message handlers to your application. You add handlers for Windows messages, such as scrolling, mouse button clicks, and keypresses, then monitor the message handlers as the application framework calls them.

• Lesson 5 returns to the ResourceStudio, with which you add a menu item to open a simple Preferences dialog box. You use ClassExpress to create a new class for the dialog box and add message handlers. Finally, you add code to connect the menu item to the dialog box and to exchange information between the dialog box and the main program.

Tutorial Source Code

Each lesson's subdirectory (except lesson2) contains three subdirectories, named start, finish, and backup.

• The start subdirectory is your working directory during the tutorial; it contains the project and source code that you change as part of the lesson.
• The finish subdirectory contains the project as it should appear after the steps in the lesson are performed correctly.
• The backup subdirectory is a copy of the initial contents of the start subdirectory. If you want to redo the lesson from scratch, delete the contents of the start subdirectory and copy all the files in the backup subdirectory to the start subdirectory.

The source and executable of the final DOS version of the TML Reader is contained in tutorial\tmldos. The source and executable of the final Windows version is located in tutorial\tmlread.

10. Lesson 1: Create the DOS Application

• Start the IDDE and load a project
• Edit source code
• Build and run the application
• Create a debugging workspace
• Run the application in debugging mode

Starting the IDDE and Loading a Project

First, start the IDDE. If you haven't yet installed Digital Mars C++, please see the Getting Started Guide for installation instructions.

1. Double-click on the Digital Mars C++ 16-bit group icon in the Windows Program Manager. (If the Digital Mars C++ 16-bit group is already open, you may omit this step.)
2. Double-click on the Digital Mars C++ icon. The IDDE main window opens at the top of the screen (see Figure 10-1).

   

   [Figure 10-1 The IDDE main window and Workspace toolbox]

Next, you must load the DOS TML Reader project. (A project is a collection of source and other support files from which an executable is generated.) To open the project:

1. Choose Open from the IDDE's Project menu.
2. Use the Open Project dialog box to find samples\tutorial\lesson1\start\tmldos.prj, located under the directory in which you installed Digital Mars C++.
3. Click OK.

In the next section you edit one of the source files.

Editing Source Code

1. In the Project window, double-click on display.c. A Source window opens, showing the contents of the source file (see Figure 10-2).

   

   [Figure 10-2 Source window]

2. Choose Function from the Source window's Goto menu. The Goto Function dialog box opens.
3. Select Display from the Function Name listbox, then click OK. The editor moves to the start of Display().
4. Choose Find from the Edit menu. The Find dialog box opens.
5. In the Pattern textbox, type LESSON 1.
6. Click on Next.
7. You should see the following line in the source code:

   	/* INSERT CODE FOR LESSON 1 HERE! */ 
   	

   Just after this comment, but before the procedure's closing brace, insert the following two lines of code:

   	disp_move(disp_numrows - 1, 0);
   	disp_eeol(); 
   	

8. Choose Save from the File menu.

Building and Running the Application

1. From the IDDE's Project menu, choose Rebuild All.

   The Output window opens automatically. This window informs you of build progress and displays any warning or error messages. If no errors exist, you see the message "Successful build." (You can still work in the IDDE while the build is in progress, because the process of building is multitasked. The Output window can be behind other IDDE windows, even when messages are being written to it.)

2. From the IDDE's Project menu, choose Arguments. The Run Arguments dialog box opens.
3. Type sample.tml into the textbox and click OK.
4. From the Project menu, choose Execute Program.

[Figure 10-3 The DOS TML Reader]

The DOS TML Reader is believed to be without any significant bugs. However, most applications have bugs during at least some of their development phase. To help you locate and correct incorrect code as quickly as possible, the IDDE has powerful debugging features.

The following sections show you how to set up a workspace for debugging and debug your source code.

Setting Up a Workspace for Debugging

The IDDE predefines a workspace named Debugging, which contains a configuration of windows useful for typical debugging sessions. Here, however, we define a new workspace specific to this lesson, to show you how this is done and to avoid disturbing any customizations you may have already made to the Debugging workspace.

To create a workspace for debugging:

1. Choose New from the Workspace submenu of the IDDE's Environment menu.
2. When prompted for a workspace name, type Lesson1.
3. Click OK.

Next, you need to add windows to the workspace. During debugging, the Source window follows program execution, the Function window views a list of functions in a particular program module, the Data/ Object window views program data, and the Call window displays the program call chain.

1. To open the Project window, press Ctrl+Shift+P.
2. In the Project window, double-click on main.c. A Source window opens.
3. To open the Function window, press Ctrl+Shift+F.
4. To open the Data/Object window, press Ctrl+Shift+D.
5. To open the Call window, press Ctrl+Shift+L.

Arrange the windows the way you want them (one example is shown in Figure 10-4), then choose Save Workspace Set from the Workspace submenu of the IDDE's Environment menu.

[Figure 10-4 A possible Lesson 1 workspace]

Now that the workspace is ready, you can begin debugging. The following section shows you how to run the application in debugging mode and how to set a breakpoint on a function, how to view program data, and how to step through code.

Running in Debugging Mode

1. The IDDE opens a window (the Digital Mars Application Window), in which the application runs. This window may be behind other windows.
2. The application is executed to the start of main.
3. The Source window changes to debugging mode (see Figure 10-5). Arrows indicating execution points within functions, and flags indicating breakpoints are shown in the left margin. You cannot edit the code while in debugging mode.

   

   [Figure 10-5 Source window in debugging mode]

4. The Project window changes to debugging mode (see Figure 10-6). The icons next to the source module names change to indicate their status:
   • A bug symbol indicates that the module contains debugging information.
   • A small "T" indicates that tracing is enabled in the module.
   • A green dot indicates that a breakpoint is set and enabled in the module.

     

     [Figure 10-6 Project window in debugging mode]

5. The Function window is updated to show a list of functions in the program (see Figure 10-6). An arrow next to main indicates that it is in the call chain; a diamond indicates that a breakpoint is set.

   

   [Figure 10-7 Function window]

6. The Call window is updated to show the call chain and execution status (see Figure 10-8).

   

   [Figure 10-8 Call window]

Setting and running to breakpoints

1. Click and drag display.c from the Project window to the Source window.
2. Choose Set/Clear Breakpoint from the Bpt menu. A breakpoint is set at the start of ShowScreen.
3. Choose Go Until Breakpoint from the IDDE's Debug menu. The program is executed to the start of ShowScreen.

[Figure 10-9 Call chain to function ShowScreen]

Viewing data

1. Choose Data from the Show submenu of the Source window's pop-up menu. The Data/Object window is updated to show the local data in ShowScreen (see Figure 10-10).

   

   [Figure 10-10 Data/Object window showing local data]

2. In the Call window, click on main, then choose Data from the Show menu. The Data/Object window is updated to show the local data in main.
3. Choose Local/Global Data from the Data/Object window's View menu. The Data/Object window is updated to display global data accessible in the current module. Choose Local/Global Data again to resume display of local data.

Stepping through code

1. Choose Step Into from the IDDE's Debug menu (or press F8) seven times. The IDDE executes seven lines of code. The seventh step takes execution into ShowLine; at that point the Call window adds ShowLine to the call chain, and the Data/Object window is updated to display the function's local data.
2. Choose Return from Call from the IDDE's Debug menu to execute the rest of ShowLine and return to the calling function.
3. Choose Step Over from the IDDE's Debug menu (or press F10) several times. The IDDE executes some lines of code in the function, but it does not step into subroutines. ShowScreen is in a loop that writes lines to the screen one-by-one. The results appear in the Digital Mars Application Window.

Running to the end

Ending the debugging session

In this chapter you have learned how to start the IDDE, load a project, edit source code, build and run the application, and run in debugging mode. These are the fundamental tasks you perform repeatedly as you develop your own applications, whether you are developing in C or C++, for DOS or for Windows. In the following lessons, you learn about the IDDE's more advanced features, many of which are designed specifically for Windows application development in C++.

11. Lesson 2: Generate an Application Framework

• Use AppExpress to generate a new project containing the SDI framework
• Build and run the bare application framework, a standardized skeleton composed of C++ classes derived from MFC library base classes.
• Use precompiled headers to speed build time
• Add calls to the TRACE macro with Class Editor
• Follow TRACE output in the Trace Messages window

There are many ways to create an application framework. This lesson provides the most straightforward way.

Generating the Framework

1. Start the IDDE and close any open project by choosing Close from the Project menu.
2. Start AppExpress by choosing AppExpress from the Tools menu.

[Figure 11-1 Setting up an SDI application with AppExpress]

AppExpress contains six pages of options that together define the project to be generated. You define these options in six steps, listed in the upper-left portion of the window. For this project, you need to change options on only four of the six pages. Set up the project options as follows:

1. On the Application Type page (shown when AppExpress is started), select SDI.
2. Deselect Include Help to suppress generation of Windows Help support.
3. Click on Next to switch to the Select Directory page. Change to the samples\tutorial\lesson2 directory under the directory in which you installed Digital Mars C++, then click on Create New Directory.
4. Type start in the textbox and click Create.

   Note: To avoid filename conflicts, it is a good idea to keep each project you create in a separate directory.

5. Click on Next to switch to the Miscellaneous page. Type your company name and suffix (or your own name) in the appropriate textboxes. This information is displayed in the automatically generated About dialog box, and in comments at the beginning of each source file.
6. In the Project Name textbox, type TMLRead.
7. Click on Next to switch to the Names page. You can customize the names of automatically generated classes here. From the Name drop-down list, select CTMLReadApp. In the Edit textbox, type CTMLReadApp.
8. Click Finish.

• Source and header files for the MFC-derived classes
• Resource script and binary files
• Project options and other support files

Building and Running the New Project

1. From the IDDE's Project menu, choose Rebuild All.
2. From the Project menu, choose Execute Program.

[Figure 11-2 New application framework generated by AppExpress]

At present, default functionality for several menu commands is provided by the MFC base classes. For example, if you choose Open from the File menu, a standard Windows File Open dialog box opens. You can select a file in this dialog box, but the code needed to read data from the file is not yet installed.

To close TMLRead and return to the IDDE, choose Exit from the File menu.

The project can take a considerable amount of time to compile. Next you learn how to decrease compilation time by using precompiled headers.

Using Precompiled Headers

To precompile the Windows and MFC header files:

1. Choose Settings from the Project menu. The Project Settings dialog box opens.
2. Click on the Build tab.
3. In the left listbox, click on Header Files.
4. In the Precompile section of the right pane, select Specific Header.
5. In the textbox below the Specific Header selection, type stdafx.h.

   Note: You can specify multiple specific headers to precompile by entering in this textbox a list of their names separated by semicolons or spaces.

   

   [Figure 11-3 Using precompiled headers]

6. Click OK.
7. An Editor/Browser message box is opens, noting that project settings have changed and asking if you want to reparse all files. Click No, because you are about to build in the next step, which will stop any parse in progress.
8. From the IDDE Project menu, choose Rebuild All.

Now that you have created, compiled, and executed the application framework, the rest of the chapter helps you to understand the framework's structure. The following three sections are optional.

Adding TRACE Calls with Class Editor

To add a TRACE call to the application class's constructor:

1. Choose Class Editor from the Goto View submenu of the IDDE Window menu. The Class Editor window opens (see Figure 11-4).
2. Under Classes, click on CTMLReadApp. The application class's members appear in the Members list.
3. Under Members, double-click on CTMLReadApp. The application class constructor's source code is shown in the source pane.
4. Add the following line to the constructor:

   	TRACE("CTMLReadApp::CTMLReadApp()\n"); 
   	

   The constructor should now appear as follows:

   	//////////////////////////////////////////////////////////////////
   	// CTMLReadApp construction 
   
   	CTMLReadApp:: CTMLReadApp()
   	{   
   	    TRACE("CTMLReadApp::CTMLReadApp()\n");
   	    // TODO: add construction code here, 
   	    // Place all significant initialization in InitInstance
   	} 
   	

5. Press Ctrl+S to save the modified constructor.

[Figure 11-4 Adding TRACE calls with Class Editor]

You can add similar TRACE calls to these other member functions:

• CTMLReadApp::InitInstance()
• CMainFrame::CMainFrame()
• CMainFrame::~CMainFrame()
• CMainFrame::OnCreate()
• CTMLReadDoc::CTMLReadDoc()
• CTMLReadDoc::~CTMLReadDoc()
• CTMLReadDoc::OnNewDocument()
• CTMLReadDoc::Serialize()
• CTMLReadView::CTMLReadView()
• CTMLReadView::~CTMLReadView()
• CTMLReadView::OnDraw()

In the next section you execute the application and watch the TRACE output in the Trace Messages window.

Watching TRACE Output in the Trace Messages Window

1. Choose Trace Messages from the Goto View submenu of the IDDE's Window menu. The Trace Messages window opens.
2. Choose Output to Window from the Options menu of the Trace Messages window.
3. Choose MFC Debug Messages from the Options menu. The MFC Trace Debug Options dialog box opens.
4. Check Enable Tracing and uncheck any other options that are checked. Click OK.

1. Choose Execute Program from the IDDE's Project menu.
2. The IDDE is minimized and the application window opens. Double-click on the IDDE icon to reopen the IDDE windows. Position the windows so you can watch the Trace Messages window while the program executes.

When you close TMLRead, the Trace Messages window receives messages from the application's class destructors.

[Figure 11-5 TRACE output in the Trace Messages window]

The next section gives an overview of the classes in the application framework and explains the messages you see in the Trace Messages window.

The Application Framework and MFC Classes

The MFC library is a C++ class library that supports programming for Windows. It encapsulates most of the Windows Application Programming Interface (API), and provides additional C++ programming support such as container and string classes. The MFC library makes it easy to work with Windows elements in an object-oriented manner. For example, MFC library classes exist to represent objects such as windows, dialog boxes, controls, device contexts, Graphic Device Interface (GDI) objects, and so on. Windows API functions are implemented as member functions of the classes with which they are logically associated.

TMLRead is built on a Single Document Interface (SDI) framework. The SDI framework contains five fundamental objects:

Document:

The document contains data, reads the data from disk, and provides access to the data. In TMLRead, the document is an object of type CTMLReadDoc, derived from the MFC library class CDocument.

View:

The view displays the data contained by the document. In TMLRead, the view is an object of type CTMLReadView, derived from the MFC library class CView (which is, in turn, derived from CWnd, the base class for all types of windows).

Document Template:

The document template defines the association between document and view classes. In an SDI application, this is an object of type CSingleDocTemplate.

Frame Window:

The frame window object is the application's main window. In TMLRead it contains a toolbar, a status bar, and the view. The frame window is an object of type CMainFrame, derived from the MFC library class CFrameWnd.

Application:

The application object creates and controls the other objects, and takes care of general program initialization and cleanup. In TMLRead the application is an object of type CTMLReadApp, derived from the MFC library class CApplication.

The TRACE output from the previous section lets you see the creation, use, and destruction of objects in the application. For example, when you start the application, you see the following messages:

	[00001] NOTIFY(StartTask)
	[00002] CTMLReadApp::CTMLReadApp() 
	[00003] CTMLReadApp::InitInstance()
	[00004] CTMLReadDoc::CTMLReadDoc() 
	[00005] CMainFrame::CMainFrame()
	[00006] CMainFrame::OnCreate() 
	[00007] CTMLReadView::CTMLReadView()
	[00008] CTMLReadDoc::OnNewDocument() 
	[00009] CTMLReadView::OnDraw() 

If you choose New from TMLRead's File menu, you see the following messages:

	[00010] CTMLReadDoc::OnNewDocument()
	[00011] CTMLReadView::OnDraw() 

	[00012] CTMLReadDoc::Serialize()
	[00013] CTMLReadView::OnDraw() 

When you choose Exit from TMLRead's File menu, the application's objects are destroyed in reverse order in which they were created. You see these messages in the Trace Messages window:

	[00014] CTMLReadView::~CTMLReadView()
	[00015] CMainFrame::~CMainFrame() 
	[00016] CTMLReadDoc::~CTMLReadDoc()
	[00017] NOTIFY(ExitTask) 
	[00018] NOTIFY(DelModule) 

You may find it useful to continue to add TRACE calls to the application as it is built. It is often difficult to follow the workings of a message-driven system; the Trace Messages window, however, acts as a kind of passive debugger that keeps you informed of the internal workings of your application.

In the next chapter, you begin to shape the application framework to the specific needs of the application. The first step in this process is to customize the user interface with the Resource Editor.

12. Lesson 3: Customize the Interface

• Use ResourceStudio to customize TMLRead's menu and toolbar
• Edit the code that sets up the toolbar

Before starting this lesson, start the IDDE and open the project tmlread.prj found in directory samples\tutorial\lesson3\start.

Launching ResourceStudio

1. Open the Project window by pressing Ctrl+Shift+P.
2. In the Project window, double-click on tmlread.rc.
3. When asked if you want to use ResourceStudio to edit this file, click Yes. ResourceStudio starts, with its Shell window minimized. (The Shell window is a control center from which you can create and open resource files. You will use it later in this lesson.)

[Figure 12-1 The Browser window of ResourceStudio]

The TML Reader is only able to read and display TML files; it cannot edit or write them. Thus, you can remove menu items related to editing and saving.

Customizing the Menu

Within ResourceStudio are several individual editors, each capable of editing a single type of resource. For example, the Dialog editor is used to edit dialog box resources, and the Menu editor to edit menu resources. By default, the editors use the right pane of the Browser window.

To start the Menu editor:

1. Click on Menu in the Browser window's upper-left pane.
2. Double-click on IDR_MAINFRAME in the lower-left pane.

[Figure 12-2 The Menu editor in the Browser window]

As the Menu editor opens, the Property Sheet also opens (Figure 12-2). This window is used to edit resource and resource element properties and options.

[Figure 12-3 The Property Sheet]

The Test Menu pop-up window also opens simultaneously with the Menu editor (Figure 12-2). It is a top-level window whose menu is identical to the one you are editing. This window does nothing when you choose menu items that are not top-level menu items or submenus.

Because changes you make to the menu in the Browser window are immediately reflected in the menu of the Test Menu window, you can verify your changes as you make them.

[Figure 12-4 The Test Menu window]

Now you can remove unnecessary menus and menu items.

1. Click on "MENUITEM New" to select this menu item.
2. Press Delete.
3. Repeat the above steps to delete:
   • "MENUITEM Save"
   • "MENUITEM Save As"
   • "POPUP Edit"
   • "MENUITEM Index"
   • "MENUITEM Using Help" and the following "SEPARATOR"

To close the Menu editor, choose Close Editing from the File menu, or press Escape. The Browser window menu and toolbar return. The right pane shows a preview of the menu.

Although we have removed menu items for commands that will not be supported, at present it would still be possible to access some of those commands through their accelerators. In the next section we remove those commands from the accelerator table.

Customizing the Accelerator Table

1. Click on Accelerator in the Browser window's upper-left pane.
2. Double-click on IDR_MAINFRAME in the lower-left pane.

[Figure 12-5 The Accelerator Table editor in the Browser window]

Removing accelerators is quite similar to removing menu items. To remove the unnecessary accelerators:

1. Click on ID_FILE_NEW.
2. Press Delete.
3. Repeat the above steps for all the accelerators, leaving only ID_FILE_OPEN and ID_FILE_PRINT.

To close the Accelerator Table editor, press Escape.

Commands may be sent to TMLRead in one other way: by clicking on buttons in the toolbar. In the next section we replace the toolbar bitmap with one containing only commands that are supported by TMLRead.

Importing a New Toolbar Bitmap

1. Click on Bitmap in the Browser window's upper-left pane.
2. Click on IDR_MAINFRAME in the lower left-pane.
3. Press Shift+ Delete.

1. Double-click the ResourceStudio icon to restore the Shell window.
2. In the Shell window, choose Open from the File menu.
3. Select the file newbar.rc and click OK.
4. In the upper-left pane of the new Browser window, click on Bitmap.
5. In the lower-left pane, click on IDB_NEWBAR. A preview of the bitmap appears in the right pane (Figure 12-6).

   

   [Figure 12-6 New toolbar bitmap]

6. Choose Copy from the Edit menu. The bitmap is copied to the clipboard.
7. Choose Close from the File menu. The second Browser window closes. Activate the Browser window containing tmlread.rc by clicking on it.
8. Choose Paste from the Edit menu. The bitmap is added to your application's resources.

1. Click on the Property Sheet to bring it to the front. The Property Sheet shows the resource ID and memory options for the bitmap resource.
2. From the ID drop-down list, select IDR_MAINFRAME.

Exiting ResourceStudio

1. Choose Save from the Browser window's File menu.
2. Choose Close from the File menu. The Browser window closes, but the Shell window and Property Sheet remain open.
3. Choose Exit from the Shell window's File menu.

Setting Up the New Toolbar

1. In the Project window, double-click on mainfrm.cpp. A Source window opens, displaying the frame window class's source code.
2. Scroll downward a few lines until you find the following code:

   	// toolbar buttons -IDs are command buttons
   	static UINT BASED_CODE buttons[] = { 
   		// same order as in the bitmap 'toolbar. bmp'
   		ID_FILE_NEW, 
   		ID_FILE_OPEN,
   		ID_FILE_SAVE, 
   		ID_SEPARATOR,
   		ID_EDIT_CUT, 
   		ID_EDIT_COPY,
   		ID_EDIT_PASTE, 
   		ID_SEPARATOR,
   		ID_FILE_PRINT, 
   		ID_APP_ABOUT,
   		ID_CONTEXT_HELP, 
   	}; 
   	

3. Remove and rearrange lines until the array looks like this:

   	// toolbar buttons -IDs are command buttons
   	static UINT BASED_CODE buttons[] = { 
   		// same order as in the new toolbar bitmap
   		ID_FILE_OPEN, 
   		ID_SEPARATOR,
   		ID_FILE_PRINT, 
   		ID_SEPARATOR,
   		ID_APP_ABOUT, 
   	};
   	

4. Save the code by choosing Save from the Source window's File menu.

In the last section you build the application and view the results of your labor.

Building and Running the Application

The source files are recompiled, the resource script is compiled by the resource compiler, and all the object files and resources are linked together to create the final application. Then the IDDE minimizes itself and executes the application (Figure 12-7).

You can verify that the changes you made to the menu and toolbar are correct. To close the application, choose Exit from the File menu.

[Figure 12-7 TMLRead with customized menu and toolbar]

You now have completed initial customization of TMLRead's resources. You deleted excess menu items and accelerators and installed a new toolbar bitmap. More changes to the application's resources can be made as the need arises; in Lesson 5, for example, you will return to ResourceStudio to add support for a Preferences dialog box. In the next lesson, though, you will use ClassExpress to install functions to handle Windows messages, such as those generated by key presses and button clicks.

13. Lesson 4: Add Messages with ClassExpress

In this lesson, you use ClassExpress to expand the functionality of the TML Reader and add member functions that handle Windows messages announcing user actions. Member functions that handle Windows messages are called message handlers, or just handlers. You can think of them as callbacks, which are called by MFC when the message they are intended to process is received. A message handler is called in response to only one message.

The Windows message stream is the lifeblood of a Windows application, regardless of whether the application is constructed in an object-oriented or a procedural way. A well-behaved Windows application can interact with the user only if it taps into the message stream and responds to messages in nondefault ways. Using ClassExpress to add MFC message handlers demonstrates how easy it is to enhance the behavior of your MFC application.

In this lesson, you:

• Launch ClassExpress from the IDDE
• Use ClassExpress to add message handlers
• Edit message handlers in the IDDE Source window
• Rebuild and run the application

• Seen how Windows messages are handled in an MFC application
• Used ClassExpress to perform the purely administrative chores associated with handling Windows messages

Windows Message Handling in MFC

Message handling in a traditional Windows application

For example, to handle the WM_SIZE message, you must add a case WM_SIZE to the switch. The statements following that case statement must have to unpack and coerce the window procedure's parameters, wParam and lParam, into constituent parts in a way that is specific to the WM_SIZE message. The result would look much like the following:

	LRESULT CALLBACK WndProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) 
	{
	    // local and static variables... 
	    switch (msg)
	    {   
		// ... 
		case WM_SIZE:
		{   
		    UINT nType = (UINT) wParam;
		    int cx = LOWORD(lParam); 
		    int cy = HIWORD(lParam);
		    // Now do what you really want to do 
		    // ...
		} 
		break; 
		// ... 
		default:
		    break; 
	    } 
	    return DefWindowProc(hwnd, msg, wParam, lParam); 
	} 

MFC's design

However, you will sometimes find that your handler can call the inherited handler to perform the bulk of its work.

For example, to handle the WM_SIZE message, use ClassExpress to add a handler for this message to your View class. (By convention, the handler for the WM_SIZE message is named OnSize.) Whenever a WM_SIZE message is received by a window represented by an object of your View class, your handler is called. The prototype of this handler is as follows:

	void OnSize(UINT nType, int cx, int cy); 

To route Windows messages to handlers, MFC consults tables, called message maps, that pair Windows messages with the member functions that handle them. You never have to edit message maps manually because AppExpress and ClassExpress create and maintain them for you. AppExpress creates message maps when you generate an application framework. Their definitions are placed in the implementation (.cpp) files of your derived classes. When you use ClassExpress to add a handler to a class, the message map is updated automatically with a new entry associating the chosen message with your handler. Furthermore, ClassExpress adds a prototype for the new handler to the class's header file and inserts a stub for the member function into the implementation file. All you need to do is to add code to the body of the handler.

Note: This introduction to MFC message handling has necessarily been brief and has glossed over several topics you will want to learn more about. For a definitive discussion of how MFC works, see the expository chapters of the Microsoft Foundation Class Library Reference.

Because you used AppExpress in Lesson 2 to generate an application framework for the TML Reader, message maps have already been created for your derived classes. During the course of this lesson, ClassExpress updates them. ClassExpress can be run either separately- from a Program Manager icon- or from within the IDDE. Because you will be using the Source window to edit the code that ClassExpress generates, you will launch ClassExpress from within the IDDE.

Launching ClassExpress

1. If you are not already in the IDDE, launch it.
2. Open the project tmlread.prj in directory samples\tutorial\lesson4\start.
3. Choose ClassExpress from the Tools menu. This launches ClassExpress and automatically loads the project tmlread.prj.

[Figure 13-1 ClassExpress, displaying the Message Maps page]

The lists on the Message Maps page

The list labeled Control IDs in Class contains an entry for the class itself, as well as the names of any commands and controls that the selected class could potentially handle.

The list labeled Function Name contains a list of message handlers already generated for the selected class by AppExpress. These methods are referenced in the class's message map.

The contents of the list labeled Windows Messages depends on what you select in the Control IDs in Class list. If you select the class name in the Control IDs list, then the Windows Messages list contains a list of Windows messages. However, if you select a control ID, the Windows messages list contains notification messages appropriate to that type of control. If you select a command ID (usually corresponding to a menu item), the rightmost list contains names of potential message map entries for commands.

Because the TML Reader handles messages that signal user input, the handlers must be added to the class corresponding to the window that receives those messages. Thus, you will add the handlers to the View class, CTMLReadView.

Adding Message Handlers

WM_SIZE

Detect when the window is resized, so it can recompute word-wrapping

WM_VSCROLL

Permit scrolling through a document using the vertical scrollbar

WM_KEYDOWN

Permit scrolling through a document using the keyboard

WM_SETCURSOR

Change the cursor when it is positioned over a hyperlink

WM_LBUTTONDOWN

Detect clicks on hyperlink jumps so it can change its display

WM_ERASEBKGND

Repaint the window background

Adding a handler for WM_SIZE

1. From the drop-down list labeled Class, select the name of the View class, CTMLReadView.
2. Use the scrollbar to move through the Windows messages list until the message WM_SIZE is visible.
3. Double-click on WM_SIZE.

	afx_msg void OnSize(UINT nType, int cx, int cy); 

Also notice that a solid square appears to the left of the message name, WM_SIZE, indicating that a handler now exists for that message.

The ClassExpress window is displayed, as in Figure 13-2.

[Figure 13-2 ClassExpress after adding a WM_SIZE handler]

Adding other message handlers

What you have just done

• The prototype for the handler is added to the declaration of the selected class, and the handler becomes a protected member function.
• An entry ON_WM_messagename() is added to the message map for the class in that class's implementation file.
• A stub function is created for the handler in the implementation file. The body of the function just calls the base class handler, and contains the comment:

  	// TODO: Add your message handler code here and/or call default 
  	

• The prototype for OnSize is added to the declaration of the class CTMLReadView in tmlrdvw.h.
• An entry ON_WM_SIZE() is added to the message map for the class CTMLReadView in its implementation file, tmlrdvw.cpp.
• A stub function for CTMLReadView::OnSize is added to the file tmlrdvw.cpp. The body of the function just calls the base class handler CView::OnSize.

Saving Your Work

Clicking Close updates your project files and returns you to the IDDE. To observe the handlers in action and confirm that they are indeed called when you expect them to be, you can add code that notifies you when they are called.

Adding Code to Handlers

1. Open the file tmlrdvw.cpp in a Source window.
2. Find the function CTMLReadView::OnLButtonDown.
3. Add the following line to the top of the function:

   	AfxMessageBox("Left button clicked!"); 
   	

4. Now find the function CTMLReadView::OnSize.
5. Add the following line to the top of the function:

   	::MessageBeep(-1); 
   	

6. Type Ctrl+S to save your changes.

Building and Running the Project

1. Choose Build from the Project menu to update the executable.
2. Choose Execute Program from the Project menu to run the program.
3. With the mouse cursor in the client area of the program's window, press the left mouse button. A box containing the message "Left button clicked!" is displayed (Figure 13-3). This message is displayed each time you press the left mouse button in the client area. It is not displayed when you release the left mouse button, move the mouse, or click with the right mouse button. To remove the message box, click OK.

   

   [Figure 13-3 TML Reader running, with message box displayed]

4. Now resize the window by dragging a corner of the window's border to a different position. You hear a beep when you release the mouse button.

   Note: You will already have heard beeps during the initial sequence of messages received by the View window. This is normal: the window receives multiple WM_SIZE messages early in its life-cycle.

5. After you have confirmed to your satisfaction that the handlers are called when, and only when, they ought to be called, quit the program by choosing Exit from TMLRead's File menu.

Summary

• How Windows messages are handled in an MFC application
• How to launch ClassExpress from the IDDE and use it to add message handlers
• How to verify that the message handlers are called in response to the messages they handle

14. Lesson 5: Add a Dialog Box with ClassExpress

This lesson shows you how to use some additional, powerful features of Digital Mars C++. To accomplish this, a body of code that supplies some substantial functionality has been added to the application you built in Lesson 4. In between the end of Lesson 4 and the start of this lesson, only the Source window has been used to create or change C++ files in the project. That is, none of the new code has been automatically generated; it has all been manually entered.

Start this lesson with the project samples\tutorial\lesson5\start\tmlread.prj, located in the directory where you installed Digital Mars C++. The first task you will perform is to build that project. Once you have done so, you will have a fully functional TML Reader.

In the remainder of the lesson, you will implement a Preferences dialog box. In addition to supplying C++ code for the start of this lesson, we have also already used ResourceStudio to create a dialog resource that defines the Preferences dialog box. However, this dialog box is not yet connected to the application. It lies dormant within tmlread.rc. You will perform all the tasks necessary to animate it and make it fully functional.

Specifically, you'll use ResourceStudio to:

• Add a new menu item for invoking the Preferences dialog box
• Launch ClassExpress

• Create a new class that represents the Preferences dialog box
• Add a handler for the new menu item
• Add a handler to this new class for one of the buttons in the dialog box
• Add data members to the new class that transfer information between the application's data and the controls in the dialog box. You will also specify validation criteria for the values that the user enters in the dialog box, so that MFC can perform automatic data validation.

• Add code for the two new handlers
• Rebuild the project and examine the results of your efforts

• Added a new menu command
• Used MFC and ClassExpress to implement a dialog box, validate its data, and exchange data between the dialog box and your application

Building and Exploring the TML Reader

Before building the Reader, you must first copy the file viewhdrs.h from the tutorial\tmlread directory to the tutorial\lesson5\backup directories. Various TMLRead modules include this header file, and cannot be compiled without it.

Building the Reader

1. If you are not already in the IDDE, launch it.
2. Open the project tmlread.prj in the directory samples\tutorial\lesson5\start located beneath the directory where you installed Digital Mars C++.
3. Choose Build from the Project menu.
4. Choose Execute Program from the Project menu to run the program. The IDDE minimizes, and TMLRead is launched. No file is yet displayed.

Exploring the capabilities of the Reader

1. Choose Open from TMLRead's File menu.
2. In the File Open dialog box, select the file sample.tml in the samples\tutorial\lesson5\start directory, then click OK. TMLRead reads, parses, and displays the file.
3. Scroll within the document using the arrow keys and the Page Up and Page Down keys. Code within CTMLReadView::OnKeyDown causes the scrolling to occur.
4. Now scroll by using the vertical scroll bar. In this case, code within CTMLReadView::OnVScroll is responsible for the scrolling.
5. Drag either the left or right border of the window to resize it. Notice that the ends of lines are automatically adjusted so that paragraphs wrap properly, filling almost all of the window's width. The handler CTMLReadView::OnSize causes rewrapping to occur.
6. If you are not now displaying the beginning of the file, press the Home key. The heading "Contents" announces the table of contents of this document, presented as a hierarchical bulleted list of the major sections of sample.tml. Each line in the table of contents is underlined and displayed in green. These properties of the text indicate that it is a hyperlink. Place the cursor over any hyperlink; the cursor changes to a hand with an extended index finger, a visual cue that you can meaningfully click on the text. Move the cursor so that it is not over a hyperlink; the cursor reverts to the default cursor. This behavior is provided by CTMLReadView::OnSetCursor after a necessary initialization by CTMLReadView::PreCreateWindow.
7. Click on the last hyperlink in the Contents section, named "Hyperlinks," with the left mouse button. This displays the last section of the file. The method CTMLReadView::OnLButtonDown handles the mouse click by determining whether or not it occurred on a hyperlink; if a hyperlink is clicked, the jump occurs.
8. At the end of the last paragraph, there is the following hyperlink phrase: "here is a link to another sample document." Click on this phrase. The file complex.tml is read and displayed. Again, CTMLReadView::OnLButtonDown causes the jump to occur.
9. Choose Previous File from TMLRead's File menu to return to sample.tml.
10. Examine each section of sample.tml by clicking each hyperlink in the document's contents at the top of the file. This will give you a good sense of the features of TML, the subset of HTML (HyperText Markup Language) recognized by the Reader.
11. Choose Print Preview from TMLRead's File menu to see a WYSIWYG display of how sample.tml would look if it were printed on the current default printer. The presence and functionality of the buttons at the top of the Print Preview window has been supplied almost entirely by MFC. When you finish looking at the Print Preview display, click Close to return to the main view of the Reader.
12. Choose Exit from TMLRead's File menu. This closes the Reader and returns you to the IDDE.

Turning aspects of the Reader's display into preferences

nParVSpace

Vertical space between paragraphs

nMargin

Amount of horizontal space between the document and the edges of the window

nIndent

Amount by which items in a list are offset from the left margin

	eDftParVSpace = 12
	eDftMargin = 10 
	eDftIndent = 40 

[Figure 14-1 The Preferences dialog box]

Of course, the user should be allowed to configure many other aspects of the Reader's display, such as colors and fonts. However, implementing this simple Preferences dialog box gives you the fundamental skills needed to realize more ambitious designs using the Digital Mars C++ tools.

Before you connect the Reader's data with the controls of the Preferences dialog box, you need to first outfit the user interface with a way to call the dialog box. In the next section, therefore, you'll use ResourceStudio to add a menu item to TMLRead.

Using ResourceStudio to Add a Menu Item

1. Open the Project window if it is not already open.
2. Double-click on tmlread.rc in the Project window. When asked if you want to use ResourceStudio to edit this file, click Yes.

   The Browser window of ResourceStudio opens, as shown in Figure 14-2.

   

   [Figure 14-2 The Browser window of ResourceStudio]

3. Select the item named Menu in the upper-left pane. The lower-left pane now displays the ID of the TMLRead menu, IDR_MAINFRAME.
4. Double-click on IDR_MAINFRAME in the lower-left pane. The pane on the right now contains a representation of the TMLRead menu, shown in Figure 14-3.

   The Property Sheet and the Test menu window also open; they are described in Chapter 12, "Lesson 3: Customize the Interface."

   

   [Figure 14-3 ResourceStudio displaying the TMLRead menu]

5. In the right pane, click on the item MENUITEM Status Bar to select it. This item is the last one belonging to the POPUP View item. When a new menu item is added, it will appear beneath this one.
6. Choose New Item from the Menu menu in the Browser window. This inserts a new item whose text is Item, and creates a new ID for it. The Property Sheet, shown in Figure 14-4, shows these settings.

   

   [Figure 14-4 The Property Sheet after adding a new item]

7. Click on the Property Sheet to make it active.
8. Click on the General tab near the top of the window to ensure that the General page is displayed.
9. In the ID textbox, type ID_VIEW_PREFS to change the ID name.
10. In the text textbox, type &Preferences....
11. Click on the Connect tab.
12. On this page, type the string Customize the appearance of the view. This prompt will appear in the status bar whenever the Preferences item is selected.
13. Save your work by choosing Save from the Browser window's File menu.
14. Close the Browser window, close the ResourceStudio Shell window (and with it, the Property Sheet), and return to the IDDE.

Two command handlers must be added- one for ID_VIEW_PREFS, the other for the Default button of the Preferences dialog box. Thus, a class must be created that represents the Preferences dialog box in the same way that CAboutDlg represents the About dialog box. The handler for the Default button will be a method for this new class. In the next section, you use ClassExpress to add the CPrefDialog class.

Using ClassExpress to Create a New Dialog Class

1. Launch ClassExpress by choosing ClassExpress from the IDDE's Tools menu.
2. Click the Add Class button. The Add Class dialog box opens, as shown in Figure 14-5. ClassExpress detects that a new dialog box has been added to the project, and assumes that you want to create a corresponding class.

   It initializes the selections in the Class Type and Dialog ID drop-down lists to reflect this assumption: Class Type is set to Dialog, and Dialog ID to IDD_PREFDIALOG.

   

   [Figure 14-5 The Add Class dialog box]

   The focus is in the New Class Name editbox. ClassExpress has suggested the name CTestDialog and has selected the substring Test so that you can change it just by typing. It has also suggested TestDial.cpp as the name of the implementation file.

3. Type Pref to change the name of the dialog class to CPrefDialog. Notice that ClassExpress accordingly changes the suggested name of the implementation file to PrefDial.cpp.
4. Click OK in the Add Class dialog box to accept the settings. ClassExpress confirms the operation with a message box.
5. Click OK to close this message box. This returns you to the ClassExpress window, which displays the Message Maps page, as shown in Figure 14-6.

   

   [Figure 14-6 ClassExpress displaying the Message Maps page]

Using ClassExpress to Add Methods

First you'll add a method that handles the command generated when Preferences is chosen from the View menu. This method also is responsible for updating the application to reflect any changed preferences. Then, you'll add a method that responds to a click on the Default button of the Preferences dialog box.

The procedure in each case is similar to the one that you used in Lesson 4. The results of your actions also will be similar: ClassExpress adds these methods to class declarations, add entries to Message Maps, and create stub functions for the methods. When you return to the IDDE, you will only need to write the code for these two methods.

Creating a handler for the Preferences command

This method needs access to data members of CTMLReadView in order to initialize the dialog box and to update those data members if the user clicks OK. Because of these requirements, the method is added to the class CTMLReadView.

1. Select the class CTMLReadView in the Class combobox on the Message Maps page.
2. In the Control IDs in the Class listbox, select ID_VIEW_PREFS, the ID of the command issued when the Preferences item in the View menu is chosen. The listbox on the right, Windows Messages, now contains the two items, COMMAND and UPDATE_COMMAND_UI.
3. Double-click on COMMAND in the Windows Messages listbox. The Method Name dialog box opens, asking you for a name for the method that is called when Preferences is chosen. ClassExpress suggests the name OnViewPrefs for this method.
4. Click OK in the Method Name dialog to accept the name OnViewPrefs.

Creating a handler for the Default button of the Preferences dialog box

Follow these steps to add this method:

1. Select the class CPrefDialog in the Class combobox on the Message Maps page.
2. In the Control IDs in Class listbox, select ID_PREFS_DEFAULT, the ID of the Default button. The listbox on the right, Windows Messages, now contains the two items BN_CLICKED and BN_DOUBLECLICKED.

   Note: These so-called messages are actually notifications that the button sends to its parent, the Preferences dialog box, via WM_COMMAND messages. BN_xxx stands for Button Notification. The BN_xxx identifiers are defined in windows.h.

3. In the Windows Messages listbox, double-click on BN_CLICKED, the notification sent when the Default button is clicked. The Method Name dialog box opens, suggesting OnClickedPrefsDefault for the method name.
4. Change this name to OnDefault.
5. Click OK in the Method Name dialog box to return to the ClassExpress main window.

Once you are back in the IDDE, you must write code to implement these two handlers. To have the handlers to perform their intended tasks, you must first make it possible to transfer data into and out of the controls of the Preferences dialog box. MFC and ClassExpress make it surprisingly easy not only to transfer data to and from a dialog box, but also to validate data that the user has entered into a dialog's controls. Adding these capabilities is addressed in the next section, the last one in which you use ClassExpress.

Adding Dialog Data Exchange and Validation

MFC and ClassExpress add order, simplicity and elegance to this situation. To use the MFC model of dialog box data exchange and validation, you must first add data members to the dialog class. (This replaces the ad hoc collection of static data favored by the traditional approach.) You use ClassExpress to associate data members with controls in the dialog box. MFC then automates the transfer of data between the dialog's controls and the dialog class data members. When adding a data member with ClassExpress, you also specify its type and the validation criteria in the associated control. MFC uses this information to perform its automatic data validation.

In the next step, you'll add data members to the CPrefDialog class using the Data Transfer page of ClassExpress. After you complete this task, there is a review of the changes that ClassExpress has made to the CPrefDialog source files, and an explanation of how MFC accomplishes data exchange and validation.

Throughout this section, you'll work with the CPrefDialog class on the Data Transfer page of ClassExpress. Perform the following steps to set up ClassExpress for this part of the lesson:

1. In the upper-left listbox, select the second item, Data Transfer. ClassExpress opens the Data Transfer page in the larger pane on the right, as shown in Figure 14-7.

   

   [Figure 14-7 ClassExpress displaying the Data Transfer page]

2. Be sure that CPrefDialog is selected in the Class Name combobox at the top of the Data Transfer page.

Adding data members to CPrefDialog

1. Click on the Add Variable button. The Add Member Variable dialog box opens, as shown in Figure 14-8.

   

   [Figure 14-8 The Add Member Variable dialog box]

2. Select IDC_PARVSPACE from the Control ID combobox.
3. Change the Member Variable Name to nParVSpace. (For simplicity, you can name the member variables of CPrefDialog the same as the members of CTMLReadView to which they correspond.)
4. For the DDX Type option, select Value.

   In fact, the Control Name combobox does not contain symbolic indentifiers for the three edit controls in the Preferences dialog box. Rather, you see only the integer resource ids of these controls. Select 3001, the resource id of the Paragraph Spacing edit control.

5. In the Variable Type combobox, select int. Two new textboxes, Minimum Value and Maximum Value, appear at the bottom of the dialog box, as shown in Figure 14-9.

   

   [Figure 14-9 Add Member Variable with Variable Type set to int]

6. Type 0 in the Minimum Value field.
7. Type 100 in the Maximum Value field.
8. Click OK in the Add Member Variable dialog box. The Data Transfer page now reflects this additional data member and its validation criteria in the Control ID and Variables list, as shown in Figure 14-10.

   

   [Figure 14-10 The Data Transfer page after adding nParVSpace]

9. Follow the procedure described in steps 3 through 10 of the previous task to add an int variable named nMargin associated with the control IDC_MARGIN. Set its minimum and maximum values to 0 and 50, respectively.

   In fact, the Control Name combobox does not contain symbolic identifiers for the three edit controls in the Preferences dialog box. Rather, you see only the integer resource ids of these controls. Therefore, add a data member corresponding to the control 3004, the resource id of the Margin edit control.

10. Then, follow steps 3 through 10 to add a final int variable, nIndent, associated with the control IDC_INDENT. Sets its minimum and maximum values to 0 and 120, respectively.

    In fact, the Control Name combobox does not contain symbolic identifiers for the three edit controls in the Preferences dialog box. Rather, you see only the integer resource ids of these controls. Therefore, add a data member corresponding to the control 3005, the resource id of the Indent edit control.

Seeing the changes in the CPrefDialog source files

Changes to the class definition

	// Dialog Data
	    //{{ AFX_DATA(CPrefDialog) 
	    enum { IDD = IDD_PREFDIALOG };
	    int nParVSpace; 
	    int nMargin;
	    int nIndent; 
	    //}} AFX_DATA 

	// Implementation
	protected: 
	    virtual void DoDataExchange(CDataExchange* pDX); // DDX/ DDV support 

Changes to the constructor

	CPrefDialog::CPrefDialog(CWnd* pParent /*= NULL*/)
	   : CDialog(CPrefDialog::IDD, pParent) 
	{
	    //{{ AFX_DATA_INIT(CPrefDialog)
	    nParVSpace = 0; 
	    nMargin = 0;
	    nIndent = 0; 
	    //}} AFX_DATA_INIT
	} 

Changes to the DoDataExchange function

	void CPrefDialog::DoDataExchange(CDataExchange* pDX) 
	{
	    CDialog::DoDataExchange(pDX); 
	    //{{ AFX_DATA_MAP(CPrefDialog)
	    DDX_Text(pDX, IDC_PARVSPACE, nParVSpace); 
	    DDV_MinMaxInt(pDX, nParVSpace, 0, 100);
	    DDX_Text(pDX, IDC_MARGIN, nMargin); 
	    DDV_MinMaxInt(pDX, nMargin, 0, 50);
	    DDX_Text(pDX, IDC_INDENT, nIndent); 
	    DDV_MinMaxInt(pDX, nIndent, 0, 120);
	    //}} AFX_DATA_MAP 
	} 

The overloaded DDX_xxx and DDV_xxx functions are declared in the MFC include file afxdd_.h. These functions all take a pointer, pDX, to a CDataExchange object. This object contains two public data members that enable the functions.

The CDataExchange data member m_bSaveAndValidate informs the functions of the direction of the transfer. If m_bSaveAndValidate is TRUE, then the transfer is from the controls to the data members; if this data member is FALSE, the transfer is from the data members to the controls. The DDX_xxx functions perform the appropriate transfer in each case. If m_bSaveAndValidate is TRUE, each DDV_xxx validation function checks whether the data meets the validation criteria it implements. If the data fails to meet the criteria, the validation function opens a message box informing the user, and sets the focus to the control containing the invalid value. If m_bSaveAndValidate is FALSE, the validation functions do nothing.

The CDataExchange data member m_pDlgWnd is a pointer to the CWnd whose data is being transferred and validated. The presence of this data member saves DoDataExchange from having to pass the this pointer to every DDX_xxx and DDV_xxx function.

Note: Because DoDataExchange is a CWnd member function and m_pDlgWnd is a CWnd*, DDX and DDV can be used with any window, and not just with those derived from CDialog.

DoDataExchange is called by the UpdateData function whenever data exchange must take place. You never call it directly. In particular, DoDataExchange is called when a window or dialog box is first opened to initialize its controls. It is also called by the CDialog member function OnOK when a user clicks on a button in the dialog box with an ID of IDOK. Thus in the Preferences dialog box, the inherited handler for the OK button already performs data transfer and validation, so you do not need to supply an override. Similarly, the CDialog member function OnCancel simply terminates a dialog box- behavior completely suitable for the Preferences dialog box.

With these concepts in mind, you can clearly see the purpose and effect of the handlers that you supply in the next task.

Writing Code for the New Handlers

Implementing CTMLReadView::OnViewPrefs

1. In the Project window, double-click on tmlrdvw.cpp. This opens a Source window in which you can edit the file tmlrdvw.cpp.
2. Find the group of #include statements toward the top of the file. Add this line after the last #include statement:

   	#include "prefdial.h" 
   

3. Find the function CTMLReadView::OnViewPrefs. (It is at the bottom of the file.)
4. Edit the function by entering the following code. (You may omit the lengthy comments.)

   	void CTMLReadView::OnViewPrefs()
   	{   
   	    CPrefDialog dlgPref; 
   
   	    // Initialize dlgPref data members with
   	    // current values from CTMLReadView 
   	    //
   	    dlgPref.nParVSpace = nParVSpace; 
   	    dlgPref.nMargin = nMargin;
   	    dlgPref. nIndent = nIndent; 
   
   	    // Display the dialog modally.
   	    // If user clicks OK, DoDataExchange 
   	    // will be called to validate data in
   	    // the controls. If the controls hold valid 
   	    // values, their contents will be
   	    // transferred to the CPrefDialog data 
   	    // members. In that case, we must transfer
   	    // the values to the corresponding 
   	    // CTMLReadView data members.
   	    // 
   	    if (dlgPref. DoModal() == IDOK)
   	    {   
   		// Transfer the data to our view class
   		// 
   		nParVSpace = dlgPref.nParVSpace;
   		nMargin = dlgPref.nMargin; 
   		nIndent = dlgPref.nIndent; 
   
   		// Make sure that the view is redrawn
   		// to reflect the new preferences 
   		//
   		bWordsWrapped = FALSE; 
   		OnUpdate(NULL, 0L, NULL);
   	    } 
   	}
   

5. Save your work by choosing Save from the File menu of the Source window.
6. Close the Source window by clicking on the close box in the upper-left corner of the window (on the caption bar).

Implementing CPrefDialog::OnDefault

1. In the Project window, double click on prefdial.cpp. This opens a Source window in which you can edit the file prefdial.cpp.
2. Find the group of #include statements, toward the top of the file. Add this statement to the end of the group:

   	#include "viewhdrs.h" 
   

3. Find the function CPrefDialog::OnDefault. (It is at the bottom of the file.)
4. Edit the function by entering the following code. (You may omit the lengthy comments.)

   	void CPrefDialog::OnDefault()
   	{   
   	    // Set data members to default values
   	    // 
   	    nParVSpace = CTMLReadView::eDftParVSpace;
   	    nMargin = CTMLReadView::eDftMargin; 
   	    nIndent = CTMLReadView::eDftIndent; 
   
   	    // Transfer these values to the controls. 
   	    // UpdateData calls DoDataExchange to effect 
   	    // the transfer. The argument determines the 
   	    // direction of the transfer: 
   	    // TRUE causes values to move from the 
   	    // controls to the data members; 
   	    // FALSE, used here, transfers the values of 
   	    // the data members to the controls. 
   	    // UpdateData uses its argument to set the 
   	    // m_bSaveAndValidate data member of the 
   	    // CDataExchange object whose address 
   	    // it passes to DoDataExchange. 
   	    // 
   	    UpdateData(FALSE); 
   	}
   

5. Save your work by choosing Save from the File menu of the Source window.

Rebuild and Test TMLRead

1. Choose Build from the Project menu to incorporate the changes you have made into the executable file tmlread.exe.
2. Choose Execute Program from the Project menu to run the Reader.
3. Choose Open from the File menu of TMLRead. Again, load the file sample.tml.
4. Choose Preferences from the View menu of TMLRead.
5. Enter 25 into all three edit controls.
6. Click on the Default button to verify that the CPrefDialog data members are set to default values by CPrefDialog::OnDefault.
7. Click Cancel. You should see no change in the display of sample.tml.
8. Again, choose Preferences from the View menu of TMLRead.
9. Change the values to 150, 40, and 10, respectively.
10. Click OK. Observe the message box informing you of invalid data.
11. Click OK to close the message box. The focus returns to the editbox containing 150.
12. Continue experimenting with the Preferences dialog box, eventually clicking OK when valid data is entered in the controls. After you have confirmed that the dialog box is performing as you want, exit the program by choosing Exit from the Reader's File menu. This returns you to the IDDE.

Summary

• How to use the ResourceStudio to add a new menu item
• How to use ClassExpress to add a handler that responds to the choice of that menu item
• How to use ClassExpress and MFC to implement a dialog box, validate its data, and exchange data between the dialog box and your application

15. More about Projects and Workspaces

Environment Menu Commands

[Figure 15-1 Environment menu commands

A list of available workspaces is added to the end of the Environment menu. The current workspace is checked. Choosing a name in this list is equivalent to clicking on the workspace tab in the Workspace toolbox.

Workspace

The Workspace submenu (Figure 15-2) contains commands for creating and editing workspaces.

[Figure 15-2 Workspace submenu]

New

Opens the Workspace Name dialog box.

[Figure 15-3 Workspace Name dialog box]

To create a new empty workspace, type a name for the workspace and click OK. The Build and Views toolboxes open automatically.

The New command is disabled if you already have five workspaces.

Clone

Opens the Workspace Name dialog box. To create a copy of the current workspace, type a name for the new workspace and click OK.

The Clone command is disabled if you already have five workspaces.

Delete

Deletes the current workspace from the workspace set. The last remaining workspace cannot be deleted.

Rename

Opens the Workspace Name dialog box. Type a new name for the current workspace and click OK.

Reset

Resets the current workspace to the configuration it had when you started the session or when you last saved it during the current session with Save Workspace Set.

Save Workspace Set

Saves the current workspace configurations. These configurations can be restored with the Reset command.

Environment Settings

This command opens the Environment Settings dialog box with which you specify various environment options. Two pages of options are available: Workspace and Color.

Workspace

[Figure 15-4 Workspace page of the Environment Settings dialog box

Save workspace set on exit

Open last project on launch

Color

[Figure 15-5 Color page of the Environment Settings dialog box

To change an item's color, first click on the item name. A dashed box appears around the item name. Then click on Change Color. You may then choose a new color from a Windows Color dialog box.

Editing/Browsing Settings

Opens the Editing/Browsing Settings dialog box, with which you can view and change the IDDE's editing and browsing options. For more information, see Chapter 19, "Class Editor Reference," Chapter 20, "Hierarchy Editor Reference," and Chapter 21, "Text Editor Reference."

More about Projects

What a project contains

C and C++ files

C source files have the .c extension; C++ source files have either the .cpp or the. cxx extension. When compiled, they all generate object (.obj) files.

Header files

If you do add a header file explicitly, it is flagged automatically for precompilation. See the description of the Header Files page of the Project Settings dialog box in Chapter 16, "More about Project Build Settings."

The header files that are included by C/C++ source files to provide common interface definitions are identified by the file extensions .hpp, .hxx, and .h.

In some situations, a C/C++ source file may be included by another source file. In this case, you probably do not want a separate object file created from that included source file. Do not add the file to the project. When you compile the target, the project system adds the included file but tracks it as an included object that should not be compiled or linked independently.

Assembly files

Note: For assembly files to be built as part of a project, MASM must be in a directory specified by the PATH environment variable. For a NetBuild project, MASM must be in a directory specified by the PATH environment variable of every buildserver, and the buildclient.

Object files

Resource and dialog script files

.rc

Source scripts of resource files that are compiled by the Digital Mars C++ resource compiler

.ico, .cur, .bmp

Binary resources

.res

Compiled binary resources

Libraries

Libraries or library interfaces to a DLL that you want to link into your executable are identified by the file extensions .lib.

Linker definition files

If you have your own .def file, you can include it in the project. The IDDE automatically modifies the .def file to change a linker option if necessary. If you do not specify a .def file, one is generated and maintained automatically for you.

Project files

Option set

Batch and makefiles

When you add a batch file or a makefile to a project, the Build Order dialog box (accessible via the Build Order button on the Make page under the Build tab of the Project Settings dialog box) becomes available to specify when to execute your batch files and makefiles.

Project-generated files

.prj

The project file that contains information on the base directory of the project, the option set, the Version Control System (VCS) configuration location, and each of the files and its attributes.

.mak

The makefile generated from the project options and files. You don't have to write and maintain a makefile- the project system does it for you.

.def

The linker definition (module definition) file. You can specify your own .def file or let the project system generate and maintain one for you.

.dep

The file that keeps the dependency listing.

.opn

The file in which project options are stored.

.lnk

A resource file that directs the linker to build your target. It is generated and maintained by the project system.

Hierarchical project structure

You can use hierarchical projects if you need to build more than one target as part of a system. For example, if your system includes an executable and a DLL, you can create a separate project for the DLL and include this new subproject in the master project. The library is built automatically when (and if) necessary. (Note that, since Windows relies on the module name to determine the uniqueness of modules, you need to give your targets different names. For example, do not name the executable generated by a project mymod.exe and name a DLL created by a subproject mymod.dll; an error results.)

In other cases, some files may need different compiler settings. You have two options. You can put those files in a separate subproject, setting compile options for the project as necessary. Or, you can override compile options on a file-by-file basis. To do this, right-click on the file in the Project window, and choose Settings from the pop-up menu. You can then set compile options for that file.

If you have a special preprocessing or translation step in your build process, you can create a subproject (a project within another project) for that make step. To accomplish the preprocessing, use the Make page under the Build tab in the Project Settings dialog box (see Chapter 16, "More about Project Build Settings") to call your own makefile or batch file.

Use hierarchical projects to handle different releases or versions of a project. To build all the variants in one simple step, create a master project that contains only projects. When you build the master, each of the variants is built.

These examples show that the hierarchical project system can be used in a variety of ways to customize the build process. Note that dependency tracking still works for subprojects- they are built as needed, before the master project is built.

Note: When you build a project that has a hierarchical structure, all subprojects are rebuilt with either the Debug or Release setting, whichever is applied to the master project. To ensure that each subproject is linked with the correct libraries (Debug or Release), you need to rebuild each subproject's .lnk file.

Dependency tracking

The IDDE also tracks changes made to build options and determines how much of the project needs to be rebuilt based on those changes. For example, if you change a compiler setting, all the sources are rebuilt. If you change a resource compiler option, only the resource compiler and link steps are executed. If you change a link option or library directory, only the linker is run. By tracking these changes, the project system supports efficient and accurate builds.

In the Windows 3.1 version of the IDDE, the project system can track files in the project with respect to version control. For more information on project and source code control, see Chapter 22, "Using Version Control."

Project menu commands

[Figure 15-6 Project menu commands]

New

Opens the ProjectExpress dialog box, as described in Chapter 3, "Starting a Project and Defining Workspaces."

Open

Opens the Open Project dialog box, as described in Chapter 3, "Starting a Project and Defining Workspaces."

Edit

Opens the Edit Project dialog box, as described in Chapter 3, "Starting a Project and Defining Workspaces."

Close

Closes the current project.

Build

Builds your project. The IDDE examines all files in the project to determine whether they are up-to-date and recompiles only the necessary files.

Stop Build

Stops a build in progress. You can also stop a build by choosing Stop! from the Output window's menu bar.

Rebuild All

Rebuilds all files in your project, regardless of whether they are up-to-date.

Link

Links all object files and libraries. Use Link instead of Build when adding .lib or .obj files to a project or subtracting them from a project. You can also use this command if you know all files are up-to- date. There is no dependency checking with Link, so linking is faster than building. Also, you would use Link rather than Build if you changed source code but you wanted to generate an .exe with existing .obj files.

Execute Program

Executes your application. Command-line arguments may be set with the Arguments command.

Arguments

Opens the Run Arguments dialog box (Figure 15-7).

[Figure 15-7 Run Arguments dialog box

Type the command-line arguments that you want passed to an application when you choose Execute Program.

Settings

Opens the Project Settings dialog box. This dialog box lets you set project options that specify how the IDDE builds a project. The following pages are available by clicking on the tabs at the top of the dialog box: Target, Build, Option Sets, VCS, and Directories.

Target settings

[Figure 15-8 Target page of the Project Settings dialog box

Operating system

• Windows 95
• Windows NT
• Win32s
• Windows 3.1
• DOS
• DOSX

Target type

Executable

Builds an executable program (.exe). Dynamic Link Library: Builds a Windows DLL. This option is not available when Operating System is set to DOS or DOSX.

Static library

Builds a static library (.lib) -- that is, a library a program links to at compile time- as opposed to DLL, which links at run-time.

COM

Builds a DOS executable .com file. This option is only available when Operating System is set to DOS.

Console

Builds a Windows console program. In Windows 3.1 (and Win32s) this creates an SDI application in which the standard input and output functions are carried out through the SDI window. In Windows 95 and Windows NT, this creates an executable that runs as a console application, simulating an old-style teletype.

Uses

MFC (Microsoft Foundation Class Library)

Links the libraries needed for an application that uses classes from the MFC. Two methods of linking are available: static library (.lib) or dynamic link library (DLL).

OLE (Object Linking and Embedding)

Links the libraries needed for creating an application that uses OLE.

VBX (Visual BASIC Control)

Links the libraries needed to create a Visual Basic control.

OCX (OLE Control)

Links the libraries for building an OLE control.

ODBC (Open Database Connectivity)

Links the libraries needed to access an ODBC data source.

Project settings

Debug

The executable contains debugging information and can be debugged by the IDDE debugger.

Release

The executable contains no debugging information. It cannot be debugged.

Allow project to be built

Parse for browsing

Build settings

Option sets

[Figure 15-9 Option Sets page of the Project Settings dialog box

When you exit the IDDE or close a project, current options are saved in the project option file (. opn). This file has the same name as the project. For example, if the project name is test. prj, the option set associated with that project is named test. opn.

The list of option sets includes sets you define and several predefined option sets. Click on an option set name to select the option set; double-click on an option set name or click on Load to load the option set.

The predefined option sets are useful starting points for defining your own custom options. When you load one of these option sets, save any changes to another option set so the defaults are intact for later use. These option sets are named according to the target type and whether debugging information is placed in the executable.

The four buttons on the dialog box have the following functions:

Load

Loads the selected option set.

Save

Saves the current option set.

Create

Creates a new option set. You are prompted for the new set's name.

Browse

Opens the Option Set Name dialog box, from which you can select an option set file to load.

VCS options

Directories

[Figure 15-10 Directories page of the Project Settings dialog box

Include directories

Library directories

Compiler output directory

Target output directory

Browser exclude directories

Source search path

The Project Window

Parse menu commands

[Figure 15-11 Parse menu commands

Update All

Parses all unparsed files in the project.

Parse All

Parses all files in the project.

Parse File

Parses the selected file, adding information about classes and members in the file to the global parse information.

Unparse File

Unparses the selected file. It removes classes and members in the file from the global parse information.

Stop Parse

This command cancels a parse operation in progress. You can also stop a parse by choosing Stop! from the Output window's menu bar.

View menu commands

Trace menu commands

VCS

Project window left pane pop-up menu commands

[Figure 15-12 Left pane pop-up menu commands

New Subproject

Opens the New Sub-Project dialog box, in which you select a project to be a subproject of the currently selected project.

Link

Links the project. This is the same as choosing Link from the IDDE's Project menu.

Build

Builds the project. This is the same as choosing Build from the IDDE's Project menu.

Rebuild All

Rebuilds the entire project. This is the same as choosing Rebuild All from the IDDE's Project menu.

Parse

Parses all files. This is the same as choosing Parse All from the Parse menu.

Edit Project

Opens the Edit Project dialog box, as described in Chapter 3, "Starting a Project and Defining Workspaces." This is the same as choosing Edit from the IDDE's Project menu.

Settings

Opens the Project Settings dialog box. This is the same as choosing Settings from the IDDE's Project menu.

Project window right pane pop-up menu commands

[Figure 15-13 Right pane pop-up menu commands

Compile

Compiles the selected file.

Parse

Parses the selected file. This is the same as choosing Parse File from the Parse menu.

Other

Opens the Other submenu, which contains the Preprocess, Disassemble, and Precompile commands.

Preprocess

Preprocesses the selected file.

Diassemble

Disassembles the selected file.

Precompile

Precompiles the selected file.

Get

Is the same as choosing Get from the VCS menu.

Put

Is the same as choosing Put from the VCS menu.

Remove

Removes the selected file from the project. You can also remove a selected file from the project by pressing Delete.

Attributes

Sets read/write attributes for the selected file. They are mutually exclusive, so only one can be selected. A checkmark is displayed next to the selected item.

Read Only

Sets the attribute to read only.

Read/Write

Sets the attribute to read/ write.

Don't Show

Filters the display of the project's files.

Modules

Does not list modules added by the debugger.

Parsed

Does not list files added by the parser.

Dependencies

Does not list files included through dependency relationships.

Settings

Lets you set certain compiler options for an individual source file, overriding those specified for the project as a whole. Choosing this command opens the Project Settings dialog box with only the Build tab available (see Chapter 16, "More about Project Build Settings"). Only the compiler-related subpages (Compiler, Code Generation, Header Files, Code Optimizations, Output, Warning, and Debug Information) are available. The Inherit from Project button resets this source file's individual options to those of the project.

"..." pop-up menu commands

[Figure 15-14 "..." pop-up menu commands

Use this menu to set up the display of project file information in the right pane. Information that can be displayed includes:

Name

Displays the filename.

Ext

Displays the file extension.

Path

Displays the file path.

Date

Displays the modification date.

Time

Displays the modification time.

Parsed

Displays whether or not the file has been parsed.

EXE/DLL

Displays to which EXE or DLL the module belongs (in debugging mode).

Virtual

Displays whether the module is virtual (in debugging mode).

Columns of information are removed from the display by dragging the column heading out of the column heading area. (The item then becomes available on the "..." pop-up menu.) The order of the columns can be changed by dragging the column headings to a new position.

Project window mouse functions

To resize the panes, first position the cursor on the dividing line between panes. The cursor changes to a two-headed arrow. Then click the left mouse button and drag the separator to the desired location.

The right mouse button opens the pop-up menus (see the sections "Project window left pane pop-up menu commands" and "Project window right pane pop-up menu commands" earlier in this chapter).

Click on a project or subproject in the left pane to open that project. Double-click on the current project in the left pane to toggle (expand or collapse) the display of its subprojects.

Click on a project file in the right pane to select it. Double-click on a file in the right pane, or drag it to an empty part of the workspace, to open the Source window to view and edit the file. (Double-clicking on a subproject in the right pane opens that subproject.)

You can drag files from the right pane to Source windows, Function windows, Data/ Object windows, and Assembly windows.

Finally, to eliminate a column of information from the right pane, click on the title at the top of the column and drag it outside the column heading area. Columns of information are restored from the "..." pop-up menu, to the right of the column titles. To rearrange columns of information, drag the title at the top of the column to a new position. You can make columns wider or narrower by dragging the column title's right edge to the right or left. Clicking on a column title re-sorts the list of project files according to that column.

16. More about Project Build Settings

The Build page of the Project Settings dialog box is composed of 18 subpages. The subpages are displayed in a listbox on the left of the window. To access a particular subpage, click on its name. The options displayed on the right change with each subpage. Subpages are organized hierarchically, as shown in the listbox.

This chapter covers all the subpages on the Build page of the Project Options dialog box. The first section introduces the build settings and the Project Settings dialog box, and the later sections describe the subpages in the order in which they are listed on the Build page.

For more detailed information on how each of these options affects the compilation of code, refer to the Compiler and Tools Guide. Appendix B, IDDE Settings and Command-Line Options, details how each of these options map to the corresponding DMC, Optlink, Make, or Librarian command line options.

Introducing Build Settings

Click on the Build tab in the dialog box to open the Build page. The Build page is composed of subpages of options. Select a subpage by clicking on its name in the listbox on the left of the Build page. The following subpages are available:

• Compiler
• Code Generation
• Header Files
• Memory Models
• Code Optimizations
• Windows Prolog/Epilog
• Output
• Warnings
• Debug Information
• Linker
• Packing & Map File
• Definitions
• Segments
• Imports/Exports
• Resource Compiler
• Make
• External Make
• Librarian

Compiler

[Figure 16-1 Compiler subpage]

Enforce ANSI compatibility

Treat source as C++

• Compiling the file to take advantage of type-safe linkage
• Linking a C file to a C++ file without changing it or giving it a C++-compatible extension

Relax type checking

• char == signed char == unsigned char
• short == unsigned short
• long == unsigned long

• int == unsigned == enum == short

• int == unsigned == enum == long

Suppress predefined macros

Exception handling

Run-time type information

Enable new[], delete[] overloading

Compiling with Enforce ANSI compatibility automatically enables this option.

char behavior

signed:

Makes char types behave as signed char types.

unsigned:

Makes char types behave as unsigned char types.

char == unsigned char:

Changes the type of char to be unsigned.

Prototyping

There are three prototyping possibilities: Standard, Autoprototype, and Strict.

Standard:

Turns off autoprototyping and strict prototyping.

Autoprototype:

Enables the compiler to generate a prototype according to the way the function is used, even if one is not specified for a function. Subsequent uses are checked against the generated prototype. This is especially useful when compiling old C code that is not completely prototyped.

Strict:

Requires that all functions be declared (prototyped) before being used. This declaration provides the compiler with the function name, return type, and storage class of a function, as well as the number and type of arguments that may be passed to it. Once the compiler encounters a function prototype, it can check each function call in the source file against that prototype and flag an error for the calls that do not match it.

International characters

None:

Allows no 2-byte sequences.

Japanese:

Signals the 2-byte sequence with a value in the range 0x81 ... 0x9F and 0xE0 ... 0xFC

Taiwanese/Chinese:

Signals the 2-byte sequence with a value in the range 0x81 ... 0xFC

Korean:

Signals the 2-byte sequence with a value in the range 0x81 ... 0xFD

Other options

Defines

Include filename

Instantiate template

Code Generation

[Figure 16-2 Code Generation subpage

Pointer validation

Generate stack frame

Check stack overflow

Fast floating point

Generate inline 8087 code

Generate virtual function tables in far data

Use Pascal calling convention

Using Pascal as the default linkage type results in a roughly 3% code size reduction and a corresponding speed up in generated code.

Use Stdcall calling convention

Note: Under Windows 95 and Windows NT, Digital Mars's name mangling scheme now appends the string "@nn" to the names of all stdcall functions (where nn is the number of bytes in parameters to the function). Previous versions of Digital Mars C++ did not append this string to mangled names.

Enable function-level link

No default library

Set data threshold

Code segment

Generate new segment for each function

Override default code segment name

Put switch tables in code segment

Put expression strings in code segment

Struct alignment

Byte:

Aligns structures on byte boundaries.

Word:

Aligns structures on word boundaries.

Double Word:

Aligns structures on double-word boundaries. This is the default for 32-bit DOS applications.

Quad Word:

Aligns structures on boundaries that are multiples of four words. This is the default for Win32 applications.

Target CPU

88:

Generates 16-bit code using the 8088 instruction set.

286:

Generates 16-bit code using the 80286 instruction set. Programs compiled with this option will not run on an 8088 or 8086 processor.

386:

Generates code optimized for machines with an 80386 CPU. Programs compiled with this option require an 80386, 80486, or Pentium processor.

486:

Generates code optimized for machines with an 80486 CPU. Programs compiled with this option require a 32-bit DOS extender or 32-bit operating system, and an 80386, 80486, or Pentium CPU.

Pentium:

Generates code for the Pentium instruction set.

Header Files

[Figure 16-3 Header Files subpage

Precompile options

No headers

All headers

Setting the All Headers option causes the compiler to generate the file scph.sym when it does not exist. If the scph.sym file does exist, the compiler assumes it is a precompiled header. The compiler will then test the header file to see whether all the headers it contains are older than the header file itself. If any are newer, or if the compiler flags have changed, a new scph.sym file is created; otherwise, the old file is loaded as a precompiled header. Setting the All Headers option also causes all files being compiled to use scph.sym as their precompiled header.

The compiler writes out the precompiled header when the first line in the top-level source file is encountered, and when that line is not a comment or an #include statement. To avoid problems with precompiled headers:

• Do not write any declarations that cross boundaries of header files. Each header file should be self-contained.
• Do not write any extern "C" constructs that start in one file and end in another.
• Do not depend on header files being included more than once.
• Do not write any code or data definitions in header files, only declarations.

There are two circumstances in which using precompiled headers is not recommended:

• The file being compiled causes scph.sym to be regenerated, but that file contains a subset of the header files that other files also contain.
• Included files are wrapped in #if blocks or extern "C" blocks. (The extern "C" statement is a non-include statement, so the precompiled header is written out prior to the extern "C" block.) Embed the extern "C" blocks in the included files themselves.

Specific header

Use precompiled headers from directory

Include headers once

Memory Models

[Figure 16-4 Memory Models subpage

Memory model

Tiny:

Tells the compiler to create a .com file active only for DOS compilations.

Small:

Generates code with near pointers for the code segment and the data segment.

Medium:

Generates code with far pointers for the code segment and near pointers for the data segment.

Compact:

Generates code with near pointers for the code segment and far pointers for the data segment.

Large:

Generates code with far pointers for both the code and data segments.

Flat:

Generates code for a Win32 compilation; that is active only for Win32s and DOSX compilations.

Data segment

Assume SS==DS

Always reload DS

Code Optimizations

[Figure 16-5 Code Optimizations subpage

Optimization for

Speed:

Optimizes code for speed at the expense of program size. The code uses all optimizations.

Space:

Optimizes code for space at the expense of execution speed. The code uses all optimizations.

Custom:

Allows selection of optimizations using the Optimization check boxes.

None:

Turns off all Optimization check boxes. No optimization is performed.

Optimizations

For more information on how Digital Mars C++ optimizes code, see the Compiler and Tools Guide.

C++ inlining

Windows Prolog/Epilog

[Figure 16-6 Windows Prolog/Epilog subpage

The first group of radio buttons selects from predefined sets of prolog/epilog options.

Set EXE defaults

Set DLL defaults

Real mode full prolog/epilog

Real mode reduced

Real mode smart callbacks

Custom

The remaining options on the Windows prolog/epilog subpage are discussed in the Compiler and Tools Guide.

Output

[Figure 16-7 Output subpage

Source listing files

Verbose

Macro expansions

Assembly listing (.cod)

Warnings

[Figure 16-8 Warnings subpage]

Warnings

All:

All warnings are produced. Turns on all warnings in the Selected Warnings group.

Selected:

Only warnings that have been checked in the Selected Warnings area are produced.

None:

No warnings are produced. Turns off all warnings in the Selected Warnings group.

Treat warnings as errors

Turn off error maximum

Selected warnings

Debug Information

[Figure 16-9 Debug Information subpage

Debug information

Full:

Turns on all debug information. Use this set when the application uses a class library or DLL.

Reduced:

Turns on the most frequently needed debug information. Use this set for most other programs.

Custom:

Select the debug information to be included.

None:

Turns off all debug information.

Trace prolog/epilog

Line numbers

Symbolic debug information

Three additional options become available when Symbolic Debug Information is checked:

Unreferenced types:

Generates symbols for unreferenced types (for example, typedefs).

All referenced classes:

Forces symbols for all classes that are referenced in DLL files and class libraries to be generated.

Dynamic C++ types:

Adds dynamic C++ class type information to classes with virtual functions. To force the production of typing information for a class with no virtual functions, add a dummy function such as virtual void dummy(){} to the class definition.

Make static functions global

Linker

[Figure 16-10 Linker subpage

Debug information

No default library

Case sensitive

Far call translation

Reorder segments

Export by ordinal

Don't export names

Export, case sensitive

Export, uppercase

DOSSEG ordering

No null DOSSEG

Warn if dups

Delete EXE/DLL on error

Create ImpDef

Fix DS

Keep segments in .def order

Requires Windows 3.0

Requires Windows 3.1

Generate import library

Import lib page size

Alignment

Base

Entry point

Packing & Map File

[Figure 16-11 Packing & Map File subpage

Packing

Win pack

EXE pack

Smart linking

Pack code

Pack data

Map file

No map:

No map file generated.

Segment map:

Generates a list of segments, in the order of their appearance in the module.

Detailed segment map:

Includes more detail about segment type, the modules that were added, the number of bytes per segment, and where each module begins.

Map file options

Cross reference

Line numbers

Group information

Definitions

[Figure 16-12 Definitions subpage

Name

Description

Heap size

For Windows 3.1, heap size is a single text field. For Win32s, the field has two parts: Reserve and Commit, where Reserve is optional. Reserve tells Win32s how much heap space to try to get for this application. Commit specifies the amount of heap space the application actually needs. The two fields are separated by a comma (,). For example, 100000, 4096 would specify 100000 for Reserve and 4096 for Commit.

Stack size

For Windows 3.1, stack size is a single text field. For Win32s, the field has two parts: Reserve and Commit, where Reserve is optional. Reserve tells Win32s how much stack space to try to get for this application. Commit specifies the stack size the application actually needs.

Stub

Version

Initialize once

Private lib

Initialize process

Terminate process

Initialize thread

Terminate thread

Segments

[Figure 16-13 Segments subpage

Segment Type

Code Segment:

Shows options for the code segment.

Data Segment:

Shows options for the data segment.

Attributes

Conforming

Discardable

Shared

Preload

I/O privilege

Moveable

Access Rights

Execute Read

Execute Only

Read Write

Read Only

Instance

Multiple data segments

Single data segment

Mode

Protected mode

Real mode

Imports/Exports

[Figure 16-14 Imports/Exports subpage

Imports

Internal name

External file

External name

Ordinal

Add, Replace, Remove

Exports

External name

Internal name

Ordinal

Parameters

No data

No name

Memory resident name

Private

Add, Replace, Remove

Resource Compiler

[Figure 16-15 Resource Compiler subpage

Error maximum

Use predefined macros

Generate warnings

Verbose

32-bit resources

Define macros

Source file listing

Default hex language

Code page

International characters

None:

Allows no 2-byte sequences.

Japanese:

Signals the 2-byte sequence with a value in the range 0x81 ... 0x9F and 0xE0 ... 0xFC.

Taiwanese/Chinese:

Signals the 2-byte sequence with a value in the range 0x81 ... 0xFC.

Korean:

Signals the 2-byte sequence with a value in the range 0x81 ... 0xFD.

Make

[Figure 16-16 Make subpage

The radio buttons at the top of the dialog box control the Make program that will be run when the IDDE builds the project.

Use IDDE make:

Use the built-in IDDE make tool.

Use external make file:

Use an external Make program.

IDDE make options

Build order

Link order

Track dependencies

If dependencies are tracked, the dependent files are shown in the Project window.

Track system includes

On error continue unrelated

Ignore errors in build

Multitasking

Frequent:

Causes the IDDE to frequently give up time slices so other applications can execute faster.

Moderate:

Causes the IDDE to give up some of the time to other applications.

None:

Turns off multitasking. Other applications are suspended while the IDDE is building a project.

Netbuild

Use NetBuild

Use remote headers

Working directory

Remote password

Build order

[Figure 16-17 Build Order dialog box]

The Build Order dialog box specifies the stage of the build in which the .prj, .bat, or .mak files are executed. Do this by selecting a file from the Build File Pool list, clicking on one of the build steps on the right, then clicking on Add. The selectable steps are:

Step 1:

Happens before any compilation takes place.

Step 3:

Happens after the files have been compiled into object files, but before they have been linked to make the target.

Step 5:

Happens after the final executable has been linked. Return any of the files to the Build File Pool list by selecting the filename in one of the steps and clicking on Remove.

Link order

[Figure 16-18 Link Order dialog box]

The Link Order dialog box specifies the order in which libraries and object files added explicitly to the project are linked. Do this by iteratively selecting files from the LIBs in Project or the OBJs in Project listbox, then clicking Add to move the files to the Link Order listbox.

Return a file to the LIBs in Project or the OBJs in Project listbox by selecting the filename and clicking on Remove.

The libraries added explicitly to the project are linked before other libraries. The object files added explicitly to the project are by default linked after the object files generated by compiling source files in the project. To specify object files to be linked before any other object files use the Prepended linker input files textbox.

When done with the link order, click OK to return to the Make subpage.

External Make

[Figure 16-19 External Make subpage]

Using external make

1. Select Use External Make File.
2. Specify the .exe name of the Make program in the Make Command Line textbox, followed by any arguments. The IDDE expects the program's directory to be in the PATH environment variable.
3. To set the Make's default directory, enter the change in the Initial Directory box. By default, this is the directory that contains Make.
4. Use a Windows PIF file to further customize the way Make behaves.

The radio buttons at the top of the dialog box control the Make program that will be run when the IDDE builds the project:

Use IDDE make:

Use the built-in IDDE make tool.

Use external make file:

Use an external Make program.

Make command line

Initial directory

Librarian

[Figure 16-20 Librarian subpage]

Ignore case

Do not create backup

Page size

17. More about AppExpress

Selecting an Application Type

[Figure 17-1 AppExpress application type options

Applications

• Quick Console: The kind of application generated is determined by whether the 32-Bit Project box in the Project Options group is checked. See the information on the Project Option group later in this section.
• Dialog Box: This standard Windows dialog box can be either modal or modeless and can include dialog box controls such as push buttons, textboxes, and listboxes.
• Form or Database: This is a window with the functionality of a dialog box enhanced with scroll bars. It is appropriate for dialog boxes that have more than one screen of controls.
• Single Document Interface (SDI): This application uses a single window in which the application data is displayed. The OLE Options group of controls is enabled if this application type is selected.
• Multiple Document Interface (MDI): This application lets you display more than one window of data within a parent frame window. The OLE Options group of controls is enabled if this application type is selected.
• OCX Control in MFC: This template is for a custom control that is an OLE2 object.

OLE Options group

• No Support: The application is not OLE-aware: it is neither a server nor a container. This option is the default.
• Server: The generated application acts as an OLE2 server. An OLE2 server can create or edit data, which OLE2 containers can link to or embed.
• Container: A host application. The generated application can contain OLE2 server data elements (OLE2 objects) within this host application's data.
• Server & Container: The generated application acts as both an OLE2 server and as an OLE2 container.

Project options group

Checking Include Help tells AppExpress to generate the files necessary to build a Windows Help file for the specified application type. AppExpress creates a Help subdirectory named hlp beneath the project directory, which contains those files. It also creates the file makehelp.bat, which you run to compile a Windows Help file from the files AppExpress provides.

For all application types other than Quick Console, checking the 32- Bit Project box causes the MFC 3.0 to be used instead of the 16-bit MFC 2.5.

For Quick Console, leaving the box unchecked results in a skeleton WINIO program being generated. WINIO is a library that allows you to write simple Windows programs that perform input/output using standard C library functions (in other words, those functions prototyped in stdio.h.). If the 32-Bit Project box is checked, a Win32 console application is generated. Win32 console applications can only be run under Windows NT and Windows 95 (and not under Win32s).

If you check the 32-Bit Project box, your application can call the Win32 API.

Providing Miscellaneous Information

• In the first three fields, provide a company name, suffix, and copyright year.
• In the Project Name field, type a name for the project. (This name is also referred to as the Windows module name.)

The Document/View Architecture

Frame window

In addition to containing child view windows, the frame window handles all window management- for example, minimizing, maximizing, and closing the window. A standard toolbar and status bar also are displayed in this window.

View

In the SDI frame window, AppExpress generates a child view window that takes up the client area of the frame window. (The client area refers to the part of the window in which the program's data is displayed. It excludes the window border, caption, and menu.) In an SDI application, this view window is given the default class name CSDIAPPView. All display and printing of the application's data is done using this view window and its class. The user's manipulation of the data is also done through the view.

Document

[Figure 17-2 Standard Windows file menu] When you choose Open from this menu, you are telling the program to open a document.

Note: The word document refers to whatever type of data is used by the application. It does not necessarily mean a text-based word processing document.

As the developer of the application, you write code in a CDocument-derived class to handle the operations on the File menu. An example of a skeleton CDocument-derived class follows.

	class CSDIAPPDoc : public CDocument
	{   
	protected: // create from serialization only
	    CSDIAPPDoc(); 
	    DECLARE_DYNCREATE(CSDIAPPDoc)
	// Attributes 
	public:
	// Operations 
	public:
	// Implementation 
	public:
	    virtual ~CSDIAPPDoc(); 
	    virtual void Serialize(CArchive& ar);
	#ifdef _DEBUG 
	    virtual void AssertValid() const;
	    virtual void Dump( CDumpContext& dc) const; 
	#endif
	}; 

In the example above, a Serialize method is included in the Implementation section of the class definition. This method, inherited from the base class, CDocument, performs object storage and retrieval to and from a disk file. In fact, the framework generated by AppExpress already handles the File Open, File Save, and File Save As operations by automatically calling the Serialize method in your CDocument-derived class. You can use the Serialize method to implement object persistence- the ability to preserve the complete state of objects across multiple executions of the program.

When you add your own member variables to this class, you should also override the Serialize method to read and write the added variables.

Pulling it all together: the document template

For more information, refer to the Microsoft Foundation Class Library Reference.

More about Message Maps

The rationale for maps

As a user of a Windows application clicks on buttons, selects menus, drags the mouse to highlight text, or performs any other mouse or keyboard action, the application is notified of this action through a Windows message. This message contains pertinent contextual information such as the screen coordinates at which the mouse was clicked, or an identifier indicating the button that was clicked.

The application developer decides which messages the application should respond to and how. If the developer decides not to write code to handle a particular message, the message can still be passed back to Windows to perform default processing.

If you write a Windows application using the Windows SDK, these decisions are most likely implemented as a switch statement in the main window procedure (usually referred to as a WndProc). For example, your window procedure might look like this:

	LRESULT CALLBACK WndProc(HWND hwnd,
		UINT message, WPARAM wParam, LPARAM lParam) 
	{
	    switch (message)
	    {
		case WM_PAINT:
		    PAINTSTRUCT ps; 
		    BeginPaint(hwnd, &ps);
		    MyPaintProc(hwnd, ps. hdc); 
		    EndPaint(hwnd, &ps);
		    return(0); 
		case WM_CREATE:
		    hmenu = GetSystemMenu(hwnd, FALSE); 
		    AppendMenu(hmenu, MF_SEPARATOR, 0, (LPSTR) NULL); 
		    AppendMenu(hmenu, MF_STRING, IDM_ABOUT, "About..."); 
		    break;
		case WM_DESTROY: 
		    PostQuitMessage(0);
		    return(0); 
	    }
	    return DefWindowProc(hwnd, message, wParam, lParam);
	} 

Components of the message map

BEGIN_MESSAGE_MAP, END_MESSAGE_MAP macros

ClassExpress-specific comment sections

Message-mapping macros

• The message identifier.
• The method that is called when the message event occurs at run-time.

  For example:

  		ON_COMMAND(ID_FILE_PRINT, CView::OnFilePrint) 
  

  This macro sets up a linkage between the Windows message WM_COMMAND and the method OnFilePrint. This method is only called, however, if the WM_COMMAND parameter (in this case, the wParam) is equal to ID_FILE_PRINT. This mapping macro is equivalent to the following case statement in a window procedure:

  		case WM_COMMAND:
  		    if (wParam == ID_FILE_FORMAT) 
  			CView::OnFilePrint(); 
  

  Having the Express tools generate message maps lets you concentrate on the specific function of the application without having to worry about syntactical issues.

Generating and Examining the Source Files

To generate and examine sample source files:

1. Launch AppExpress from the IDDE Tools menu, and make all the selections necessary to create an SDI application. When you click on Finish, AppExpress generates all the source files for this skeleton program. When it is done, AppExpress gives control to the IDDE (with the new project open), and then closes.
2. Open the Project window in the IDDE by clicking the Project View icon and dragging it onto the desktop, or by pressing Ctrl+ Shift+ P.
3. Double-click on the filename mainfrm.h. A Source window opens containing the header file mainfrm.h. (For more information on Source windows, see Chapter 2, "Introducing the IDDE.")

	// mainfrm.h : interface of the CMainFrame class 
	// 
	// Copyright (c) XYZ Corporation, 1994. All Rights Reserved. 
	// 
	// 
	class CMainFrame : public CFrameWnd 
	{   
	protected: // create from serialization only 
	    CMainFrame(); 
	    DECLARE_DYNCREATE(CMainFrame) 
	// Attributes 
	public: 
	// Operations 
	public: 
	// Implementation 
	public: 
	    virtual ~CMainFrame(); 
	#ifdef _DEBUG 
	    virtual void AssertValid() const; 
	    virtual void Dump(CDumpContext& dc) const; 
	#endif 
	protected: // control bar embedded members 
	    CStatusBar m_wndStatusBar; 
	    CToolBar m_wndToolBar; 
	// Generated message map functions 
	protected: 
	    //{{ AFX_MSG(CMainFrame) 
	    afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct); 
		// ClassExpress will add and remove member functions here. 
		// DO NOT EDIT these blocks of generated code ! 
	    //}} AFX_MSG DECLARE_MESSAGE_MAP() 
	}; 

• A file header that uses the company name, suffix, and copyright year that you specified in AppExpress
• The CMainFrame class declaration

In the protected section of the class declaration is a prototype for a function that is called as part of the class's message map. As indicated, do not edit the code in this section because it is reserved for ClassExpress.

AppExpress also generates a .cpp, or implementation, file for the CMainFrame class. This file has the same base name, mainfrm, as the class header file, but has the .cpp extension. To examine mainfrm.cpp, open this file in an IDDE Source window. This implementation file contains the following components:

• A file header.
• Preprocessor include statements for the required header files.
• A declaration of the CMainFrame message map containing a single entry (for the Windows WM_CREATE message).
• Static array data for initialization of the toolbar and status bar.
• The definitions of the CMainFrame constructor and destructor functions. Notice the comment in the constructor indicating where to add member initialization code. Edit these functions to insert initialization and shutdown code for object instantiation.
• The definition of the class's method, OnCreate, for handling WM_CREATE messages.
• The definitions of two functions- AssertValid and Dump- that may be used during debugging.
• A final comment indicating where ClassExpress will add stub methods for new entries in the CMainFrame message map.

18. More about ClassExpress

• Deriving a class to handle user interface events in your program
• Working with Dialog Data Exchange (DDX) and Dialog Data Validation (DDV)
• Enabling a C++ class as an OLE2 automation server or client
• Deriving a C++ class from an existing Visual Basic custom control (VBX)

Deriving a Class to Handle User Interface Events

1. Create an application framework for a standard SDI program using AppExpress (for details, see Chapter 4, "Generating an Application Framework").
2. Use ResourceStudio to create a new dialog box resource (see Chapter 7, "Adding Look and Feel with Resources").
3. Launch ClassExpress from ResourceStudio or from the IDDE's Tools menu.
4. Add a new class to your program by clicking on the Add Class button. (Follow the instructions in Chapter 4, "Generating an Application Framework.") Be sure to derive the new class from the Dialog class type.

   In ClassExpress, all of the base classes from which you derive new classes are themselves derived from the MFC class CCmdTarget. The MFC Library Reference defines CCmdTarget as the base class for the message map architecture. Any class derived from CCmdTarget inherits the ability to respond to user interface events such as menu and toolbar selections and dialog box actions.

5. In the ClassExpress main window, verify that your class has been created by browsing through the Class drop-down list.
6. Select the new class name from the Class list. Note that the list of Control IDs and Windows messages for your derived dialog box class is different from the list for non-dialog classes.

The ability to add new classes that derive specialized message-handling functionality from the base MFC classes is one of the benefits of using ClassExpress. The following material summarizes the type of functionality that a new class inherits if it is derived from CCmdTarget. For more information on any of these base classes, refer to the Microsoft Foundation Class Library Reference.

CmdTarget:

The base class for all MFC classes that offer support for Windows message handling. You probably will not derive a new class directly from CmdTarget; instead, use the other base classes in this list.

Dialog:

This class implements dialog boxes, either modal or modeless. It usually is associated with a dialog box resource template created in ResourceStudio. Member variables of this class typically are mapped to fields or controls in the dialog box. For details on how this mapping is established, see the next section, "Working with Data Transfer: DDX and DDV."

Document:

The application's data is represented by the document class. The data can be anything the programmer chooses. All file input and output should be handled within the document class.

FormView:

A class of views that has built-in support for scrolling and for child controls. FormViews typically are combined with a dialog box resource template. One way in which the FormView class differs from the Dialog class is its added support for scrolling.

FrameWnd:

The main window class for single document interface (SDI) applications.

MDIChildWnd:

The child document window class for multiple document interface (MDI) applications.

ScrollView:

A class of view window that supports scrolling.

View:

The base class that provides the connection between the document class representing the program data and the user interface to that data.

Wnd:

The base class for any window, including dialog boxes, frame windows, views, and dialog box controls. Because this class is used to derive many of the other classes listed here, choose Wnd as a base for a new class if other choices do not satisfy your programming requirements.

Splitter:

This special type of window can contain multiple panes. A pane is usually a window that is associated with a View-derived class in the application.

Working with Data Transfer: DDX and DDV

This section describes MFC library support for data transfer between dialog boxes or other windows and your C++ objects that store that data. This is referred to as Dialog Data Exchange (DDX) and Dialog Data Validation (DDV). You use the Data Transfer options of ClassExpress to bind class member variables to dialog box or window controls.

Note: Data transfer using DDX/DDV can be applied to any window that is derived from the MFC base class, CWnd. It is not restricted to dialog boxes derived from CDialog.

Dialog Data Exchange with Windows 95 Common Controls is also supported.

Implementing Dialog Data Exchange (DDX) using ClassExpress

1. Add a few edit controls to your skeleton dialog box using ResourceStudio.
2. Launch ClassExpress from ResourceStudio or from the IDDE's Tools menu. ClassExpress loads the project and displays the Message Maps options.
3. In the upper-left listbox, click on Data Transfer. From the Class drop-down list, select the CMainDialog class.

   The ClassExpress window should look similar to that shown in Figure 18-1.

   

   [Figure 18-1 Data Transfer page in ClassExpress

4. Click on the Add Variable button. The Add Member Variable dialog box shown in Figure 18-2 opens.

   

   [Figure 18-2 Add Member Variable dialog box

5. From the Control ID drop-down list, select a dialog box control that you want to map to a class member variable.
6. Edit the Member Variable Name to specify the name of a variable to be mapped to the selected Control ID. The variable does not have to exist in the class. (ClassExpress adds it automatically to the class for you.)

   Note: Nonstatic class member variable names are usually prefixed with m_for easy identification; however, you are not required to follow this convention.

7. For DDX Type, select Control to map the control ID and variable name to a control class (such as CButton or CEdit). Select Value to map to a CString or to a numeric type.
8. Select a Variable Type for this member variable from the Variable Type drop-down box. The available types depend on the type of control being mapped and the DDX Type option.
9. If you selected Value from the Type radio buttons, one or two additional fields are displayed along the bottom of the dialog box. If the added member variable is of a numerical variable type, two fields are displayed, which allow you to set the minimum and maximum ranges for the variable's value. If the variable type is CString, then only one field is displayed, in which you specify the maximum number of characters that the CString can contain. (You cannot specify a minimum number of characters.)

   Figure 18-3 shows an example using a CString variable type.

   

   [Figure 18-3 Adding a CString member variable

10. Click OK. You are now back in the ClassExpress window, and the member variable you just added is displayed in the spreadsheet. If you added minimum or maximum values for your member variable, a dialog data validation function name is displayed in the DDV type field.

Understanding data transfer at the source code level

This section explores the source code generated by ClassExpress and explains the implementation of data transfer- the first step in how DDX functions bind member variables to dialog box objects to transfer data between the variables and the controls. Next, the validation of values entered into dialog box controls is explained. The third section describes how data transfer functions are invoked by the UpdateData function.

Dialog Data Exchange (DDX)

1. Select Open from the IDDE's Project menu to open the dialog box project you created earlier.
2. Open the maindlg.cpp file in a Source window. Either double-click on maindlg.cpp in the Project window or open an empty Source window, then open the source file using the Open command in the File menu.
3. From the Edit menu, choose Find and search for DoDataExchange. Look at the definition for the method CMainDialog::DoDataExchange. ClassExpress has overridden the CWnd method DoDataExchange in your CMainDialog class. A sample implementation of DoDataExchange follows.

	void CMainDialog::DoDataExchange(CDataExchange* pDX) 
	{   
	    CDialog::DoDataExchange(pDX); 
	    //{{ AFX_DATA_MAP(CMainDialog) 
	    DDX_Control(pDX, IDABOUT, m_About); 
	    DDX_Control(pDX, IDOK, m_OKButn); 
	    DDX_Control(pDX, IDCANCEL, m_CancelButn); 
	    DDX_Control(pDX, IDHELP, m_Help); 
	    //}} AFX_DATA_MAP 
	} 

DDX functions take the form:

	DDX_xxx(pDX, nIDC, Data); 

• pDX is a pointer to a CDataExchange object. This object contains context information such as the dialog box instance and whether the data exchange is from the member variable to the control or vice versa.
• nIDC is the dialog box control ID.
• Data is the member variable in your dialog class.

The preceding sections cover how ClassExpress prompts you for new member variables, then generates code that performs automatic data exchange between those variables and their respective dialog box or window controls. The next section describes how to enhance data exchange by using data validation.

Dialog Data Validation (DDV)

[Figure 18-4 Adding a numeric member variable

In this example, the member variable m_PayTo is defined as an integer and is limited to values between 100 and 5000. This variable is bound to a dialog box edit control identified by IDC_PAYTO. The user of the application is not allowed to enter a value in that control that is outside the minimum and maximum bounds.

You do not have to write a single line of code to enforce this rule. The DDV functions in the MFC library do this for you. After adding the variable m_PayTo, as shown earlier, and clicking Close in ClassExpress's main window, ClassExpress writes the following lines to the DoDataExchange method of your dialog box class:

	DDX_Text(pDX, IDC_PAYTO, m_PayTo);
	DDV_MinMaxLong(pDX, m_PayTo, 100, 5000); 

Note: For each member variable, the DDV function call should immediately follow the DDX function call in your DoDataExchange function. This is a requirement of the application framework and is enforced when ClassExpress writes new DDX/DDV function calls to the source code file.

DDV functions take the following form:

	DDV_xxx(pDX, Data, ...); 

• pDX is a pointer to a CDataExchange object. This object contains context information such as the dialog box instance and whether the data exchange is from the member variable to the control or vice versa.
• Data is the member variable in your dialog class.
• ... indicates the remaining arguments: minimum and maximum values for numerical variables, and maximum number of characters for strings.

Calling UpdateData

	BOOL UpdateData(BOOL fSaveOrValidate); 

You call UpdateData from the places in your program at which you want to exchange data with the dialog box. UpdateData is called for you automatically in only one place in the dialog initialization.

In response to the WM_INITDIALOG message, the CDialog::OnInitDialog method calls UpdateData with a parameter equal to FALSE, indicating that the controls are being set. Initialize the values of a dialog class's member variables in your OnInitDialog method. For example:

	BOOL CMainDialog::OnInitDialog() 
	{   
	    m_ColorIsRedCheckBox = TRUE; 
	    m_Filter = FILTER_NONE; 
	    CDialog::OnInitDialog(); 
	} 

Making Your Application an OLE Automation Server

• The definition of an OLE automation server
• The difference between creating an automation server in ClassExpress and a standard OLE server in AppExpress
• The mechanics of creating an OLE automation server using ClassExpress
• The source code that ClassExpress generates to implement OLE automation

What is an OLE automation server?

OLE automation server vs. OLE server

Note: An embedded object's data is saved as part of the client application's data. A linked object's data is saved independently of the client's data; the client's data contains a reference to the filename of the linked data.

In these examples, the application that is the container for the spreadsheet is called an OLE client or a container application. The application that originally created the spreadsheet and that is used to edit the spreadsheet is called the OLE server application. The server application is responsible for creating and maintaining data objects embedded in or linked to another application.

When you create an OLE server application with AppExpress, you are making it possible for your application's data to be embedded in or linked to another application's data.

OLE automation was introduced in the second version of the OLE technology. Automation has nothing to do with embedding or linking to data objects. It is used to manipulate objects that an OLE automation server has created.

Using OLE automation to manipulate an object allows you to do some or all of the following:

• Query and change the properties of an object
• Call functions that are defined in the object
• Be notified when an object triggers a specific event

Enabling your application to be an OLE automation server

To enable your application to be an OLE automation server:

1. With the project containing your sample application framework loaded in the IDDE, launch ClassExpress by choosing it from the Tools menu in the IDDE's main window.
2. To act as an OLE automation server, your application needs a C++ class that defines an automation object. In ClassExpress, you take care of this by adding a class. Click on the Add Class button.
3. Select a Class Type. This specifies the MFC class from which your new class is derived.
4. Type the name of the class in the New Class Name textbox.
5. Check the OLE automation box. If your class is derived from CCmd Target or CWnd, the Creatable check box and the External Name textbox become visible.
6. For CCmdTarget-and CWnd-derived classes, if you want OLE client applications to be able to create instances of your OLE automation object, check the Creatable box as well.
7. For CCmdTarget-and CWnd-derived classes, enter an External Name that will be used by OLE automation client applications to identify your automation object.
8. Click OK. At this point, ClassExpress generates the new class in your project's source code and reports that the classes were generated correctly. You are returned to the main ClassExpress window.

Adding exposed functions to an automation server class

1. Click the Add Function button on the Automation Server page of ClassExpress. The Add Function dialog box opens.
2. In the External Name textbox of Add Function, type the name by which automation clients will refer to the new function. As you type, the Internal Name textbox mirrors the name you are entering.
3. If you want your new function to have an Internal Name different from its External Name, type the desired Internal Name in that textbox. The Internal Name is the name the function will have in your source code.
4. Select the function's Return Type from the drop-down list with that label. In addition to the standard types void, short, long, float, and double, this list contains the OLE types CY, DATE, LPDISPATCH, SCODE, BOOL, VARIANT, and LPUNKNOWN. If you are unfamiliar with these latter types, consult the OLE2 Programmer's Reference for their definitions.
5. If your function takes arguments, add them one at a time by clicking on the Add button at the bottom of the Parameters List listbox. The Add Parameter dialog box that is displayed lets you specify the Name and Type of a parameter. Enter the parameter's name in the Name textbox. Select its type from the Type drop-down list. (The Type list contains more OLE types. See the OLE2 Programmer's Reference for details.) Click OK. You are returned to the Add Function dialog box, in which the parameter you just specified is displayed in the Parameters List listbox.

   Follow the procedure just described to add any other parameters the function requires.

6. Click OK in the Add Function dialog box. You are returned to the Automation Server page of ClassExpress. The function you just created is added to the Name listbox, and is referred to using its external name. When this function is selected in the Name listbox, the Implementation listbox displays the prototype of the function that ClassExpress generates to implement it.

Adding properties to an automation server class

1. Click the Add Property button on the Automation Server page of ClassExpress. The Add Property dialog box opens.
2. Select one of the radio buttons to the right of the Implementation label. If you want to grant automation clients read-only access to the property you are adding, select Variable. If you want to grant read/write access to the property, select Get/Set Function.
3. In the External textbox, type the name by which automation clients will refer to this property.

   As you type, the values of the Get Function and Set Function fields are automatically filled in using the external name extname you specify. If you are creating a read-only property, it will be implemented as a member variable in your automation class. The Get Function textbox will contain the proposed name of that variable, m_extname. If you are creating a read/write property, it will be implemented by a pair of member functions- a Get and a Set function- in your automation class. The Get Function and Set Function textboxes will contain the proposed names of those functions, Getextname and Setextname.

4. Select the Type of the property from the drop-down list with that label. In addition to the standard types short, long, float, and double, this list contains the OLE types CY, DATE, LPDISPATCH, SCODE, BOOL, VARIANT, and LPUNKNOWN. If you are unfamiliar with these latter types, consult the OLE2 Programmer's Reference for their definitions.
5. If you want, change the names of the Get and Set Function.
6. Click OK in the Add Property dialog box. You are returned to the Automation Server page of ClassExpress. The property you just created is added to the Name listbox and is referred to using its external name. When this item is selected in the Name listbox, the Implementation listbox displays the member variable or the pair of functions that ClassExpress generates to implement the property.

OLE automation server source code

As explained in the previous section, you create a new class using ClassExpress and indicate that the class should support OLE automation. When the source code is generated, the constructor for your new class contains the following code:

	EnableAutomation(); 
	// To keep the application running as long as 
	// an OLE automation 
	// object is active, the constructor calls 
	// AfxOleLockApp. 
	AfxOleLockApp(); 

This function increments a global count of the number of times this object has been activated by OLE clients. It is the MFC library's way of ensuring that an object is not destroyed by one OLE client, if it is in use by another client. In the destructor for your class, ClassExpress has written a call to the function AfxOleUnlockApp, which decrements the global count for this object.

ClassExpress also creates a new macro structure called a dispatch map, as shown in the following example:

	BEGIN_DISPATCH_MAP(COLEAutoObject, CCmdTarget) 
	    //{{ AFX_DISPATCH_MAP(COLEAutoObject) 
		// NOTE -the ClassExpress will add and 
		// remove mapping macros here. 
	    //}} AFX_DISPATCH_MAP 
	END_DISPATCH_MAP() 

In addition to the OLE initialization code in the constructor and the dispatch map, ClassExpress optionally writes the following macro to your class implementation file (.cpp):

	IMPLEMENT_OLECREATE(COLEAutoObject,"MYOBJ",
		0xd73cfd60, 0x3cea, 0x101b, 0x80, 0x60, 
		0x4, 0x2, 0x1c, 0x0, 0x94, 0x2) 

The IMPLEMENT_OLECREATE macro takes these arguments:

• The new class name
• The external name of the object
• The components of the class's OLE class ID

Another source code file created by ClassExpress has a filename consisting of the project name with the extension .odl. This file contains the Object Description Language implementation for your automation object class. You run the utility program mktyplib.exe, passing the .odl file as an argument. The result is a type library file with an extension of .tlb.

The type library file is used by OLE automation clients to query the objects, properties, and functions exposed by your application.

This section has given you a view of the source code generated for an OLE automation server. OLE automation has many more facets that you should explore. Refer to the Microsoft Foundation Class Library Reference and the OLE2 Programmer's Reference for additional details.

Making Your Application an OLE2 Automation Client

This section uses the OLE2 sample type library hello.tlb, found in samples\ole16\hello below your Digital Mars C++ installation directory. If you do not have this sample file installed, you can select any other type library file that exports an OLE2 automation interface. Otherwise, you should install the OLE2 samples.

To make your application an OLE2 automation client:

1. Launch ClassExpress and, if necessary, open a project. For this example, the application type of the project does not matter.
2. Select Automation Client from the list at the upper left of the ClassExpress window.
3. Click the "..." button to the right of the Type Library File field. The Open dialog box is displayed.

   Note: This dialog box has filtered out all filenames that do not end with .tlb or .olb. These extensions are used for OLE type library files.

4. Browse to the type library file samples\ole16\hello\hello.tlb within the Digital Mars C++ installation directory.
5. Click OK in the Open dialog box. The type library file should now be displayed in the Type Library File field in the ClassExpress window.

   Note: Class names representing exported OLE2 automation interfaces in the type library are displayed in the Class list.

6. Select _DHello from the Class list.
7. ClassExpress fills in the New Header File and New Implementation File fields with the suggested file names for the new C++ class that will be generated in your framework.
8. Click on the Generate button. ClassExpress creates the header and implementation file for your new class.

Creating a C++ Wrapper Class for an Existing VBX

You can use VBXExpress with any 16-bit MFC application. (The restriction arises because VBXs themselves are inherently 16-bit.) Follow these steps to create a wrapper class for a VBX and add it to the class hierarchy of a project:

1. Launch ClassExpress- either from the IDDE or standalone. If you launch ClassExpress standalone, specify your project in the Open dialog box.
2. Select VBXExpress from the list at the upper left of the ClassExpress window.
3. The control labeled VBX File displays the name of the currently selected VBX file. Click the button labeled "...", to the right of the control. An Open dialog box is displayed. Select a VBX file and click OK.

   VBX File displays the name of the file selected.

   ClassExpress examines the VBX file to determine the name and capabilities (events and properties supported) of every VBX control contained in the file. (There can be more than one.) The drop-down list labeled VBX contains the names of all VBXs in the file. The capabilities of the control selected from this list are displayed in the Property and Event list.

4. In the textbox labeled ClassName, specify the name of the C++ wrapper class that will be generated for the currently selected VBX control. In the textboxes labeled Header File, specify the names of the C++ files that will contain the definition and implementation of the class. Default names are provided in all three fields; you don't have to change them.
5. Repeat the above step for each VBX control in the VBX file.
6. Click on the Generate button. ClassExpress creates the C++ wrapper classes.

Summary

• Deriving a new class in an application from one of the many MFC library base classes
• Establishing links between class member variables and dialog box or window controls, and validating user entry without having to write a single line of code
• Manipulating objects within an application from any OLE client application
• Conversely, enabling an application to manipulate OLE automation objects in other applications
• Extending the power of an application with Visual Basic custom controls, without having to write the control yourself

19. Class Editor Reference

The Class Editor Window

• Choose Class Editor from the Goto View submenu of the IDDE's Window menu.
• Double-click on the Class Editor icon in the Views toolbox, or drag the icon from the toolbox to the desktop.
• Choose New! from another Class Editor window's menu bar.
• Double-click on a class in the Hierarchy Editor graphical display.
• In the Class pane, move the cursor towards the left margin until its orientation changes and it points to the right. Then highlight one or more classes and drag them onto the desktop.
• In the Members pane, move the cursor towards the left margin until its orientation changes and it points to the right. Then highlight one or more members and drag them onto the desktop.
• Double-click on an entry in the Query Implementors window.
• In the Query Implementors window, move the cursor towards the left margin until its orientation changes and it points to the right. Then highlight one or more entries and drag them onto the desktop.

Edit menu commands

[Figure 19-1 Edit menu commands

Global Undo

Goto menu commands

[Figure 19-2 Goto menu commands

Macro menu commands

[Figure 19-3 Macro menu commands

New! command

Classes pane pop-up menu commands

[Figure 19-4 Classes pane pop-up menu commands

Add Derived

[Figure 19-5 Create Derived Class dialog box

Class name

Header file

Add Top

Add Sibling

Show Header

Note: You can also perform this action by moving the cursor towards the left margin of the Class pane until its orientation changes and it points to the right. Then select a class and drag it onto the desktop while holding down the Control key.

Connect Base

[Figure 19-6 Add Base dialog box

Access

Public:

Public members of the base class are public members of the derived class, and protected members of the base class are protected members of the derived class.

Protected:

Public and protected members of the base class are protected members of the derived class.

Private:

Public and protected members of the base class are private members of the derived class.

Virtual

Base class

Edit Base Attributes

This command is disabled if classes are sorted alphabetically rather than hierarchically.

[Figure 19-7 Edit Base Attributes dialog box

Access

Public:

Public members of the base class are public members of the derived class, and protected members of the base class are protected members of the derived class.

Protected:

Public and protected members of the base class are protected members of the derived class.

Private:

Public and protected members of the base class are private members of the derived class.

Don't change:

Appears only if you are editing the attributes of more than one connection and the base class access specifiers are not all identical. It means that the base class access specifiers are not altered. It lets you change the Virtual specifier of all connections without affecting their individual access specifiers.

Virtual

If the selected class is derived from multiple bases, only the attributes of the connection with the base class immediately above in the Classes pane are changed.

Delete Base Connection

You will be prompted to confirm this if the Confirm Inheritance Changes option on the General page of the Editing/Browsing Settings dialog box is selected.

This command is disabled if classes are sorted alphabetically rather than hierarchically.

Settings

Members pane pop-up menu commands

[Figure 19-8 Members pane pop-up menu commands

Add

[Figure 19-9 Add Member dialog box

Access

Public:

Public members are accessible from outside the member's class.

Protected:

Protected members are accessible only within the member's class, derived classes, and their friends.

Private:

Private members are accessible only within the member's class and its friends.

Storage

Normal:

The member has no storage modifiers.

Static:

Only one copy of the member exists; it is shared by all objects of the member's class.

Virtual (functions only):

The function may be overridden in derived classes.

Pure virtual (functions only):

The function must be overridden in derived classes; the class is abstract.

Friend (functions only):

The named function is allowed access to the class's private and protected members.

Inline

Declaration

Source file

The member declaration is placed in the class declaration. If the specified source file does not already exist, it is created and added to the project. By default, empty definitions of inline functions are placed in the header file. Empty definitions of normal, static, and virtual functions, as well as static data members, are placed in the source file.

Delete

Edit Attributes

[Figure 19-10 Change Member Attributes dialog box

Access

Public:

Public members are accessible from outside the member's class.

Protected:

Protected members are accessible only within the member's class, derived classes, and their friends.

Private:

Private members are accessible only within the member's class and its friends.

Don't change:

Only appears if you are editing the attributes of more than one member and their access controls are not all identical. It means that the access control is not altered. It lets you change other member attributes without also affecting their individual access controls.

Storage

Normal:

The member has no storage modifiers.

Static:

Only one copy of the member exists; it is shared by all objects of the member's class.

Virtual (functions only):

The function may be overridden in derived classes.

Pure virtual (functions only):

The function must be overridden; the class is abstract.

Friend (functions only):

The named function is allowed access to the class's protected and private members.

Don't change:

Only appears if you are editing the attributes of more than one member and their storage classes are not all identical. It means that the storage class is not altered. It lets you change other member attributes without affecting their individual storage classes.

Inline

Source file

Show Source

If you add new functions or static data definitions to the source file or alter function argument or return types, you must update the class header to reflect the changes.

Settings

Source pane pop-up menu commands

[Figure 19-11 Source pane pop-up menu commands

Save

Changes to static data and to function argument and return types made in the source code are updated automatically in the class declaration and Members pane.

Class editor mouse functions

To resize the panes, first position the cursor over the dividing line between panes. The cursor changes to a two-headed arrow. Then, press the left mouse button and drag the separator to the desired location.

Classes pane

Select a class by clicking on it. Several classes may be selected by clicking on each one while holding down Control. The members of the class last selected appear in the Members pane. You may drag and drop a class into the source pane; the class name is inserted into the buffer.

Members pane

Select a member by clicking on it. Several members may be selected by clicking on each one while holding down Control.

Double-clicking on a member causes its definition (if appropriate) or declaration to appear in the Source pane. If the source is not available, the declaration is displayed.

You may drag and drop a member into the source pane; the member declaration is inserted into the buffer.

Note: In addition to clicking on it, you can select a member when the Members pane is active by typing its name. As you type, the Class Editor attempts to automatically complete the name. (Depending on the rate at which you type, it may consider a character to be the first character of a new selection, rather than the next character in the current select operation.)

Source pane

The source pane supports typical Source window mouse and cursor operations, as described in Chapter 21, "Text Editor Reference."

Toolbar commands

[Figure 19-12 Class Editor toolbar

These options are the same as those in other menus:

Cut:

Same as choosing Cut from the Edit menu.

Copy:

Same as choosing Copy from the Edit menu.

Paste:

Same as choosing Paste from the Edit menu.

Add top:

Same as choosing Add Top from the Classes pane pop-up menu.

Add derived:

Same as choosing Add Derived from the Classes pane pop-up menu.

Add member:

Same as choosing Add from the Member pane pop-up menu.

Connect base:

Same as choosing Connect Base from the Classes pane pop-up menu.

Play macro:

Same as choosing Play from the Macro menu.

Class Editor Settings

General options

[Figure 19-13 General options

Browser operations

Text edits, per buffer

Confirmations

• Member deletions
• Inheritance changes

Open output window on message

Keyboard emulation file

Multiple selections

Yes:

Multiple selections are allowed.

No:

Multiple selections are not allowed.

Confirm:

Multiple selections are allowed, but a confirmation request is displayed each time an operation is performed on multiple classes or members.

Class options

[Figure 19-14 Class options

List classes

Hierarchically:

Base classes are arranged alphabetically, with derived classes placed below and indented relative to their base classes. If a class has multiple bases, that class is listed below each base class.

Alphabetically:

Classes are arranged in alphabetical order, and each class is listed only once.

Font

Apply here only

Member options

[Figure 19-15 Member options

Grouping

By access:

Members are grouped into Public, Protected, and Private. If By Access is not selected, each member is preceded by a colored diamond indicating its access specifier (green for public, yellow for protected, red for private).

By file:

Members are grouped by the source file containing their definitions. When this option is selected, only functions and static data are shown.

By kind:

Members are grouped into Data, Functions, and Typedefs. If more than one Grouping option is selected, members are grouped by kind within files, and by files within access category.

Sorting

Order defined:

Members are arranged in the order they are declared in the class header.

Alphabetical:

Members are arranged alphabetically.

Show full method names

Font

Apply here only

20. Hierarchy Editor Reference

The Hierarchy Editor Window

• Choose Hierarchy Editor from the Goto View submenu of the IDDE's Window menu.
• Double-click on the Hierarchy Editor icon in the Views toolbox, or drag the icon from the toolbox to the desktop.
• Choose New! from another Hierarchy Editor window's menu bar.

Edit menu commands

Figure 20-1 Edit menu commands

Global Undo

Print

Macro menu commands

Figure 20-2 Macro menu commands

New! command

Pop-up menu commands

Figure 20-3 Hierarchy Editor pop-up menu commands

Add Derived

Figure 20-4 Create Derived Class dialog box

Class name

Header file

Add Top

Add Sibling

Show Header

Connect Base

Figure 20-5 Add Base dialog box

Access

Public:

Public members of the base class are public members of the derived class, and protected members of the base class are protected members of the derived class.

Protected:

Public and protected members of the base class are protected members of the derived class.

Private:

Public and protected members of the base class are private members of the derived class.

Virtual

Base class

Edit Base Attributes

Figure 20-6 Edit Base Attributes dialog box

Access

Public:

Public members of the base class are public members of the derived class, and protected members of the base class are protected members of the derived class.

Protected:

Public and protected members of the base class are protected members of the derived class.

Private:

Public and protected members of the base class are private members of the derived class.

Don't change:

Appears only if you are editing the attributes of more than one connection and the base class access specifiers are not all identical. It means that the base class access specifiers are not altered. It lets you change the Virtual specifier of all connections without affecting their individual access specifiers.

Virtual

Delete Base Connection

You are prompted to confirm this if the Confirm Inheritance Changes option on the General page of the Editing/Browsing Settings dialog box is selected.

Settings

Mouse functions

A class is selected by clicking on it. Additional classes may be selected by clicking while holding down Control. Members of the class last selected appear in the Members child window.

Double-clicking on a class opens a Class Editor window. A connection is selected by clicking on it. Additional connections may be selected by clicking while holding down Control.

A new derived class is added by clicking on the base class and dragging the cursor to an empty area of the display.

A new base-to-derived connection is made by clicking on the base class and dragging the cursor to the derived class.

A derived class's connection to a base may be moved to a different base by clicking the connection, then dragging the connection's handle to the new base class. (This is a shortcut for deleting one connection, then establishing a new one.)

Toolbar commands

Figure 20-7 Hierarchy Editor toolbar

The following options are the same as those on other menus:

Add top:

Same as choosing Add Top from the pop-up menu.

Add derived:

Same as choosing Add Derived from the pop-up menu.

Connect base:

Same as choosing Connect Base from the pop-up menu.

Print:

Same as choosing Print from the Edit menu.

Play macro:

Same as choosing Play from the Macro menu.

Members Child Window

Member menu commands

Figure 20-8 Member menu commands

Add

Figure 20-9 Add Member dialog box

Access

Public:

Members are accessible from outside the member's class.

Protected:

Members are accessible only within the member's class, derived classes, and their friends.

Private:

Members are accessible only within the member's class and its friends.

Storage

Normal:

The member has no storage modifiers.

Static:

Only one copy of the member exists; it is shared by all objects of the member's class.

Virtual (functions only):

The function may be overridden in derived classes.

Pure virtual (functions only):

The function must be overridden in derived classes; the class is abstract.

Friend (functions only):

The named function is allowed access to the class's private members.

Inline

Declaration

Source file

The member declaration is placed in the class declaration. If the specified source file does not already exist, it is created and added to the project. By default, empty definitions of inline functions are placed in the header file. Empty definitions of normal, static, and virtual functions, as well as static data members, are placed in the source file.

Delete

Edit Attributes

Figure 20-10 Change Member Attributes dialog box

Access

Public:

Members are accessible from outside the member's class.

Protected:

Members are accessible only within the member's class, derived classes, and their friends.

Private:

Members are accessible only within the member's class and its friends.

Don't change:

Appears only if you are editing the attributes of more than one member and their access controls are not all identical. It means that the access control is not altered. It lets you change other member attributes without also affecting their individual access controls.

Storage

Normal:

The member has no storage modifiers.

Static:

Only one copy of the member exists; it is shared by all objects of the member's class.

Virtual (functions only):

The function may be overridden in derived classes.

Pure virtual (functions only):

The function must be overridden; the class is abstract.

Friend (functions only):

The named function is allowed access to the class's protected and private members.

Don't change:

Appears only if you are editing the attributes of more than one member and their storage classes are not all identical. It means that the storage class is not altered. It lets you change other member attributes without affecting their individual storage classes.

Inline

Source file

Show Source

If you add new functions or static data definitions to the source file, or alter function argument or return types, you must update the class header to reflect the changes.

Settings

Pop-up menu commands

Mouse functions

Select a member by clicking on it. Additional members may be selected by clicking on them while holding down Control.

Double-clicking on a member causes its definition (if appropriate) or declaration to be displayed in the Source child window.

You may drag and drop a member into the Source child window; the member declaration is inserted into the buffer.

Source Child Window

Edit menu commands

Figure 20-11 Edit menu commands

Goto menu commands

Figure 20-12 Goto menu commands

Pop-up menu commands

Figure 20-13 Pop-up menu commands

Save

Changes to static data and to function argument and return types made in the source code are updated automatically in the class declaration and Members child window.

Mouse functions

The Source child window supports typical source window mouse and cursor operations, as described in Chapter 21, "Text Editor Reference."

Hierarchy Editor Settings

The tabs are used to switch between several sets of options. The Hierarchy, Member, and General options are discussed in this section; the remaining options pertain to text editing and are discussed in Chapter 21, "Text Editor Reference."

General options

Figure 20-14 General options

Browser operations

Text edits, per buffer

Confirmations

• Member deletions
• Inheritance changes

Open output window on message

Keyboard emulation file

Multiple selections

Yes:

Multiple selections are allowed.

No:

Multiple selections are not allowed.

Confirm:

Multiple selections are allowed, but a confirmation request is displayed each time an operation is performed on multiple classes or members.

Hierarchy options

Figure 20-15 Hierarchy options

Pop-up windows

Members:

Enables the Members child window.

Source:

Enables the Source child window.

Font

Apply here only

Member options

Figure 20-16 Member options

Grouping

By access:

Members are grouped into public, protected, and private. If By Access is not selected, each member is preceded by a colored diamond indicating its access specifier (green for public, yellow for protected, red for private).

By file:

Members are grouped by the source file containing their definitions. When this option is selected, only functions and static data are shown.

By kind:

Members are grouped into Data, Functions, and Typedefs.

Sorting

Order defined:

Members are arranged in the order in which they are declared in the class header.

Alphabetical:

Members are arranged alphabetically.

Show full method names

Font

Apply here only

21. Text Editor Reference

• The Source Window
• Text Settings
• Using Global Find

The Source Window

• Choose New or Open from the IDDE's File menu.
• Choose Source from the Goto View submenu of the IDDE's Window menu.
• Double-click on the Source icon in the Views toolbox, or drag the icon from the toolbox to the desktop.
• Double-click on a filename in the Project window.
• Choose Show Source or Show Header from pop-up menus in the Class and Hierarchy Editors.
• Double-click on an error message in the Error window.
• Choose New or Open from another Source window's File menu.
• Choose New! from another Source window's menu bar.
• Select text in one Source view, then drag it onto the desktop. This results in an untitled Source window containing the selected text.

File menu commands

[Figure 21-1 File menu commands

New

Open

Load

Close

Save

Save as

Save All

Compile

Save and Add to Project

The Save and Add to Project command changes to Add to Project, Save and Parse, or Parse, depending on whether the file is part of the project, up to date, or parsed. These are the four changes:

1. A new source file is created but not saved, or flagged as modified since the last save. The menu reads "Save and Add to Project."
2. A source file which has not been added to the project is saved. The menu reads "Add to Project."
3. A source file which exists in a project is loaded in the source editor. The menu reads "Parse."
4. A source file exists in a project and has been flagged or modified. The menu read "Save and Parse."

Add to Project

Save and Parse

Parse

Compare

[Figure 21-2 Compare Files dialog box

File 1 and File 2

If either file is open in a Source window, the editor uses the version in memory rather than the one in the disk file.

Line

Display

Horizontal:

The files are displayed one above the other.

Vertical:

The files are displayed side-by-side. The editor performs the comparison on a line-by-line basis. When it finds a mismatch, it highlights the appropriate lines in both files. The Compare dialog box (Figure 21-3) indicates where the mismatch was found.

[Figure 21-3 Compare dialog box showing mismatch

Next match:

Click on this button to resynchronize the comparison. The editor highlights the next set of matching lines and the Compare dialog box indicates where the match occurs.

[Figure 21-4 Compare dialog box showing match

Next difference:

Click on this button to find the next mismatched line. You can continue the comparison in this way until no more differences are found.

Insert

Revert

Page Setup

[Figure 21-5 Page Setup dialog box

Header and footer

You can embed the following special-purpose codes in the header and footer text:

• %f gives the full path and filename of active file
• %d gives the current date and time
• %p gives the current page number

Margins

Font

Printer

Print

[Figure 21-6 Text Print dialog box

Print range

All:

Prints the entire file.

Selection:

Prints the highlighted text selection. (It is disabled if no text is selected.)

Print quality

Copies

Setup

Edit menu commands

[Figure 21-7 Edit menu commands

Undo

Cut

Copy

Paste

Delete

Find

[Figure 21-8 Find dialog box

Pattern

You can initialize the pattern by selecting the text before choosing Find. (The text must not span a line break.) Otherwise, you may type the text you want to find into the textbox, or select text from previous search strings, stored in the drop-down listbox.

The pattern may also be a regular expression (text containing wildcard characters) if the Regular Expression option is selected. Regular expression syntax is discussed in "Using Global Find," later in this chapter.

Ignore case

Whole words only

Regular expression

The search begins at the current insertion point. Click Next to search forward in the file, or Previous to search backward in the file. If the search is successful, the matching text is highlighted. Otherwise, the status line displays the message "Pattern not found."

Repeat Find

If the search is successful, the matching text is highlighted. Otherwise, the status line displays the message "Pattern not found."

Find Previous

Find Next

Replace

[Figure 21-9 Replace dialog box

Pattern

You can initialize the pattern by selecting text before choosing Replace. (The text must not span a line break.) Otherwise, you may type the text you want to find into the textbox, or select text from previous search strings, stored in the drop-down listbox.

The pattern may also be a regular expression (text containing wildcard characters) if the Regular Expressions option is selected. Regular expression syntax is discussed in the section "Using Global Find," later in this chapter.

Replacement

Ignore case

Regular expressions

Confirm changes

Restrict changes to selected text

Whole words only

The search/replace operation begins at the current insertion point. If you have selected Confirm Changes, the Confirm Replacement dialog box (Figure 21-10) is displayed when a match is found.

[Figure 21-10 Confirm Replacement dialog box

You may click Yes to make the replacement, No to skip this replacement, or Cancel to end the search/replace operation. Also, if you uncheck Confirm, then click Yes, the editor replaces all remaining occurrences of Pattern without prompting you.

Global Find

Current Buffer Settings

[Figure 21-11 Current Buffer Options dialog box

Tab spacing

Right margin

Word wrap

Autoindent

Read only

Use as default for ...

Expand tabs with spaces

C++ mode

Persistent

Text Setting

Goto menu commands

[Figure 21-12 Goto menu commands

Line

[Figure 21-13 Goto Line dialog box

Function

[Figure 21-14 Goto Function dialog box

The Function Name listbox holds the available function names. Either type in the function name or scroll and select the function name from the list. When you click OK, the insertion point moves to the beginning of the specified function.

Member functions in the list typically are displayed as member::class. To change the format to class::member, deselect the Reverse Class::Member Format option.

Matching Delimiter

Bookmark

[Figure 21-15 Bookmarks dialog box

Bookmark list

Goto

Clear

Drop

Buffer

[Figure 21-16 Edit Buffers dialog box

Context

Buffer list

Buffer properties

Tab spacing:

Specifies the number of columns between tab stops.

Right margin:

Specifies the column that acts as the right margin.

Word wrap:

Enables word wrap. While typing, lines that extend beyond the right margin are broken automatically at the last word boundary before the margin.

Autoindent:

Causes the text editor to indent automatically on newline. When you press Enter, the editor positions the cursor directly below the first nonblank character in the previous line.

Read only:

The buffer may not be changed.

Use as default for ...:

Saves the Current Buffer Options settings as the defaults for any subsequent file with the same file extension that is loaded. For example, if the currently open file is test.cpp, the check box reads, "Use as default for .cpp." If the currently open file is test.txt, the check box reads, "Use as default for .txt." If the currently open file has no extension, the check box reads, "Use as default." If this is an untitled buffer, the check box is disabled.

Expand tabs with spaces:

Tabs are inserted into the text as an appropriate number of spaces, rather than as tab characters.

C++ mode:

Text is treated as C++ code. Special options for C++ code are set in the Editing/Browsing Settings dialog box (see "Text Settings," later in this chapter).

Persistent:

Causes the buffer options for this file to be saved during the current IDDE session, even if the file is closed. Otherwise, buffer options are set to their global defaults if a file is closed and reopened.

Switch to

Open

Save

Save all

Save as

Close

Close all

Find

Macro menu commands

[Figure 21-17 Macro menu commands

Record Macro

1. Choose Record Macro. If a default macro exists, you are asked to confirm that you want to record over the default macro. Click OK.
2. Enter the sequence of keystrokes and menu selections you want to record.
3. Choose Stop Recording to end the macro.

Play Macro

ScriptMaker

[Figure 21-18 ScriptMaker dialog box

Existing macros

Menu order

Put in menu

Edit

Rename

[Figure 21-19 Rename/Clone Script dialog box

Menu name:

Name under which this macro is listed in the Macro menu.

File name:

Name of the file in which the macro is saved. You can change either or both names. Note that you cannot rename the default macro.

Clone

Menu name:

Name under which this macro is listed in the Macro menu.

File name:

Name of the file in which the macro is saved. When cloning, this filename must be different from that of any other macro.

Delete

New! command

Changes made to a file in one Source window are made automatically in other Source windows containing the same file.

Pop-up menu commands

[Figure 21-20 Source window pop-up menu commands

Copy

Cut

Paste

Delete

Query Implementors

[Figure 21-21 Members window

For example, if the token is Test, Query Implementors shows a list of all implementors of Test, such as One::Test.

In the Members window, you can select an implementor and choose Show Source from the Member menu to open a Source window to the corresponding source code or, double-click an implementor to open a Class Editor window to the member source. Note that if only one implementor of a token is found, the Query Implementors command opens the Class Editor window directly, without first opening the Members window.

Select

[Figure 21-22 Select submenu commands

Normal

Column

Line

Cancel

Format Text

[Figure 21-23 Format Text submenu commands

Indent Block

Unindent Block

Upper Case

Lower Case

Tabs to Spaces

Spaces to Tabs

Write Block

Save

Toolbar commands

[Figure 21-24 Source window toolbar

New:

Same as choosing New from the File menu.

Open:

Same as choosing Open from the File menu.

Save:

Same as choosing Save from the File menu.

Cut:

Same as choosing Cut from the Edit menu.

Copy:

Same as choosing Copy from the Edit menu.

Paste:

Same as choosing Paste from the Edit menu.

Print:

Same as choosing Print from the File menu.

Find:

Same as choosing Find from the Edit menu.

Find previous:

Searches backward in the file for the search string.

Find next:

Searches forward in the file for the search string.

Play macro:

Same as choosing Play Macro from the Macro menu.

Text Settings

General options

[Figure 21-25 General options

Browser operations

Text edits, per buffer

Confirmations

Open output window on message

Keyboard emulation file

Multiple selections

Text options

[Figure 21-26 Text options

Tab spacing

Right margin

Autoindent

Expand tabs with spaces

Show horizontal scroll bar

Remove trailing spaces on save

Cursor styles

Block:

The current character is displayed in inverse video.

Underline:

The current character is underlined.

Vertical bar:

A vertical bar appears to the left of the current character.

Blink:

The cursor blinks. The blink rate is specified in the Windows Control Panel.

Font

Brief-compatible select

Typing replaces selection

Cut/copy line without selection

If this option is not selected, Cut and Copy have no effect if no text is selected.

Normal selection for debugging

Virtual cursor

Enable menu accelerators

Help Files

[Figure 21-27 Text Help File Configuration dialog box

This dialog box lets you associate particular Windows Help files with each of the four Text Help commands. The Text Help commands are run by key sequences such as Shift+F1. (The exact mapping of key sequences to Text Help commands depends on the current key mapping. See "Keys options," later in this chapter.) The Text Help commands call the Windows API function Windows Help, passing it the name of a Windows Help file and (optionally) a keyword. The Text Help commands are useful, for example, for gaining access to help on a particular API function or MFC class directly from the source code.

Text Help Command:

Specifies a Text Help command (TextHelp1, TextHelp2, TextHelp3, TextHelp4).

Help File:

Specifies the Windows Help file to be associated with the selected Text Help command. This filename is passed to Windows Help when the Text Help command is run.

Grab Token At Insertion Point:

If this box is checked, the Text Help commands pass the token at the insertion point in the text buffer to Windows Help as a keyword. This causes Windows Help to search for the associated topic, and, if found, to immediately display help on the keyword topic.

C++ options

[Figure 21-28 C++ options

Check delimiters

Enable C++ mode

Enable C++ mode for untitled files

Indent after {

Auto-align comments at column

Enable C++ mode on extensions

Custom keywords

To add a new keyword, type the keyword into the textbox and click on Add. To remove a keyword from the list, click on the keyword in the list and click on Remove.

Keys options

[Figure 21-29 Keys options

A Key Bindings file (.key) associates keystroke sequences with editor commands and user-defined macros. You can select the particular key binding set you want to use either with the Key File option below, or with the Keyboard Emulation file option under the General tab (see General options, earlier in this section).

Commands are grouped into functional categories. The groups are:

Global:

Global commands, used anywhere (includes all user-defined macros)

Member:

Member-related commands, used in the Class and Hierarchy Editors

Text:

Text editor functions and commands, used in Source windows

Class:

Class-related commands, used in the Class and Hierarchy Editors

Project:

Project-related commands, used in the Project window

Key file

Keys

There are two ways to enter a keystroke sequence into the textbox:

• Click in the textbox and type the keystroke sequence. You can enter most sequences in this way. (Keys you cannot enter directly into the box include Home, End, Delete, Backspace, Right Arrow, Left Arrow, and Tab.)
• Use the Recorder buttons. Click on the green arrow to start recording. Enter your keystroke sequence. Click on the red box to stop recording.

Commands/macros

The list displays commands and associated key sequences. If more than one sequence is assigned to a command, it is listed as many times as necessary. The content and sorting of the list is determined by the Commands/Macros List Options.

Commands/macros list options

Scope:

Displays commands only in the specified functional category. Categories are Global, Member, Text, Class, and Project. Specify All to see all commands.

Show bound keys only:

Shows only those commands with an associated keystroke sequence.

Sort by command:

Displays the list alphabetically by command. If this option is not selected, the list is ordered by key sequence.

Copy to clipboard:

Copies the current contents of the commands/ macros list to the Clipboard.

Assign

If another command in the same functional category is already bound to this keystroke sequence, you are asked if you want to reassign the sequence to the new command.

Unassign

Save as

Display options

[Figure 21-30 Display options

Source code display

Comments:

C/C++ comments

Custom keywords:

Special keywords you specify. (See "C++ options," earlier in this chapter.)

Keywords:

C/C++ keywords

Current line:

The line containing the insert point

Preprocessor:

C/C++ preprocessor directives

Error highlight:

Lines on which compiler errors were found

Selection/highlight color

Execution line color

Backup options

[Figure 21-31 Backup options

Autosave

Backup on file save

Create .bak File:

Copies the previous saved version to file with the extension .bak.

Copy to backup directory:

Copies the previously saved version to another directory. Type the directory into the textbox, or click on Browse to select a directory from a Directory dialog box.

Invoke OnBackup script:

Runs a macro called OnBackup.

Using Global Find

Defining the search

[Figure 21-32 Global Find dialog box

The Global Find dialog box has two sections. The upper section specifies the files to be searched, and the lower section specifies the pattern to be searched for.

Search Files...

In the current project

All files in the current project are searched.

Currently listed in global search results window

Enabled only after an initial global search has been performed. It limits the search to files in which a match was found in the previous global search.

Matching the criteria

Specify files by filename patterns, directory, date, time, and attributes.

File names:

Comma-separated list of filenames and patterns. To search all files, use *.*.

Directory:

Search files in the specified directory. You can click on Browse to select a directory from the Choose Directory dialog box. Check Include Subdirectories to search files in subdirectories as well.

Date:

Select Ignore to ignore the date. Otherwise, specify a date and one of the relational options. For example, specify On and 11/6/94 to search files last modified on November 6, 1994, or After 4/1/90 and to search files last modified after April 1, 1990.

Time:

Select Ignore to ignore the time. Otherwise, specify a time and one of the relational options.

Attributes:

Search files with the given attributes. File attributes are Archive, Read Only, System, and Hidden.

The Attributes check boxes are three-state check boxes:

checked

files with the given attribute are searched.

cleared

files without the given attribute are searched.

grayed

the attribute is ignored when deciding which files to search.

For...

Ignore case

Do not consider case when searching for a match.

Whole words only

Consider text a match only if it is not part of a larger alphanumeric string.

Regular expression

Enables regular expression matching. A regular expression is a string with wildcards, which are:

?	Matches any character.
*	Matches zero or more occurrences of any character.
@	Matches zero or more occurrences of the previous character or expression. For example, Ax@B matches AB, AxB, AxxB, and so on.
%	Matches the beginning of a line. For example, %{ finds lines that start with left braces.
<	Matches the beginning of a line. For example, <{ finds lines that start with left braces.
$	Matches the end of a line. For example, $ finds blank lines.
>	Matches the end of a line. For example, > finds blank lines.
[...]	Matches any of the characters listed between the square brackets. A hyphen can be used to specify a range of characters. For example, [axz] matches a, x, or z; [a-z] matches any lowercase letter.
[~...]	Matches any characters except those listed.
\	Escape character indicates that the following character should be taken literally rather than used as a wildcard character. For example, \% matches a percent sign.
\t	Matches a tab character.
\f	Matches a formfeed character.

The Search window

[Figure 21-33 Search window

Also during the search, the Search Progress dialog box displays statistics (Figure 21-34). Click Stop to terminate the search at the current point, or click Revert to return to the Global Find dialog box.

[Figure 21-34 Search Progress dialog box

When the search is complete, the Search Progress dialog box closes and the Search window contains a list of files in which at least one match occurred.

Search menu commands

[Figure 21-35 Search menu commands

Refine

Reopens the Global Find dialog box. You may refine your search criteria and continue the global search. This command is disabled if no matches were found.

Show File

Opens the selected file in a Source window. You can also open a file by double-clicking on the file in the list. The file is positioned to the first match of the search pattern.

Add Selected To Project

Adds the selected file to the current project.

Add All To Project

Adds all files listed in the Search window to the current project.

Toolbar commands

[Figure 21-36 Search window toolbar

Refine

Same as choosing Refine from the Search menu

Show file

Same as choosing Show File from the Search menu

22. Using Version Control

The VCS works in combination with INTERSOLV's PVCS, a popular version control program for the PC. However, VCS offers significant functional improvements over PVCS alone, because it is integrated with the IDDE's project system and has access to information stored in the project (.prj) file. Digital Mars's VCS guards against accidentally overwriting changes made by others and provides the highest level of support possible for keeping both your private project directory and the master project directory fully synchronized.

Note: If you do not have PVCS, you need to purchase it from INTERSOLV before you can use Digital Mars's VCS. See the PVCS documentation for information on PVCS features and commands.

This chapter assumes a knowledge of PVCS and a familiarity with basic version control concepts. The chapter focuses on using the group-oriented model of software development that VCS makes possible, and it explains how to use VCS to build and maintain projects.

Note: The IDDE's Version Control System (VCS) is supported only in the 16-bit version of Digital Mars C++.

Overview of VCS Concepts

The next section, "Setting Up Version Control with VCS," presents an overview of how you or your project team can use VCS to establish and maintain version control on software development projects of any size.

Terminology

Archive (or master archive):

All revisions of a source file, stored in a commonly accessible directory structure, usually on a network.

Revision:

A revised archived source file that has a revision number and timestamp that identifies when the revision was created.

Workfile:

Your private copy of the revision that you are currently working on.

Private project directory:

Your personal working directory to which others do not have access. You work with workfiles in your private project directory.

GET:

The process of obtaining a private copy of a revision of an archive (usually the latest revision).

MERGE:

The process of collating changes to a revision into the archive, without overwriting or corrupting any changes made by others since you got the revision.

PUT:

The process of creating a new revision of a file in the archive.

Version:

A group of revisions containing all source files that make up a project. Typically you create versions to correspond to milestones in the development process, such as the weekly build or the beta build.

Version control models

Linear:

Only one person can work with a file at any one time.

Parallel:

Groups of people can work with the same set of files simultaneously.

Setting Up Version Control with VCS

Using the linear model with VCS

After changing the revision, the person who receives it must PUT it back into the master archive before others can make changes to it.

The advantage of the linear method of version control is that you do not have to collate (merge) sets of changes to a revision. The obvious disadvantage is that only one person can work on a file at a time. In large development projects in which many people are making changes to related groups of files, this model is often unworkable.

Using the parallel model with VCS

When working in a parallel version control environment, the revisions and versions used by the development team are stored in a master archive, usually on a network. Developers GET a revision (or more typically a group of related revisions) from the master archive and work with the copies (workfiles) in their own private project directory.

After making changes to a group of workfiles, developers must MERGE their changes into the latest version of revisions of the files. This is done in the private project directory because it often involves identifying changes made by others in the interim, along with resolving dependencies in other revisions that were affected by other people's changes.

Note: In your revised file, be sure to identify the revision with which you want your changes merged. You make this reference by adding a $revision entry in the file.

When changes are merged successfully, and all related changes have been made to affected revisions in the private project directory, each developer PUTs the new revisions back into the master archive.

If a revision has been modified during the MERGE, it must be remerged before it can be PUT into the archive. VCS warns you of this automatically and gives you a way to prevent other people from merging changes into the archived version of a revision until you have successfully PUT it.

The parallel model also supports branching of revisions. When you create a branch of a revision, you can PUT it back into the archive without performing a MERGE. This allows others to GET your changes to a revision. You use the branching mechanism if you want a set of changes available to you but you do not want to MERGE the changes until your work is complete. For more information, see "Creating a new branch," later in this chapter.

Setting VCS Options

To open this dialog box, open the project you want to work with, and choose Settings from the IDDE's Project menu. In the Project Settings dialog box, select the VCS tab. The VCS page is shown in Figure 22-1.

[Figure 22-1 VCS page in Project Settings dialog box

Choosing a Development Model

Select Linear if you are working alone, or if you need to deny other developers access to revisions you are working on.

You can switch from the parallel to the linear mode when, for example, you need to prohibit GET operations on revisions you are merging (see "Merge Options," later in this chapter).

The IDDE sets the rest of the VCS options for you, based on the development model you select, as described later in this chapter. If you need more control over the version control process, you may change the default settings. This is not usually necessary.

Get Options

Get read only:

Lets you GET files from the master archive, but with read only access; you cannot modify the files you GET. Check this option if you want to view a revision (for example, an old revision), or if you want to ensure that you do not accidentally change the files. This option is off by default in both development models.

Get and lock:

Prevents others from successfully executing a GET operation on a revision once you GET it. The revision remains locked until you PUT it back in the archive again. This option is on by default when you choose the Linear development model.

Get and touch:

Sets the time-stamp for any revision you GET to the current date and time. This setting forces recompilation of your files. It is off by default in both development models.

Continue on overwrite error:

Tells the IDDE to overwrite a file on a GET operation without displaying a warning. Use this setting to wipe out all changes you have made to a revision and GET a new copy from the master archives. This option is off by default in both development models.

Merge Options

Creating a VCS Configuration File

A sample configuration file, vcs.cfg, comes with Digital Mars C++. (It is installed in \dm\samples\windows\wclock by default.) The sample vcs.cfg contains information that VCS needs to work:

vcsdir:

The directory in which VCS stores master archives. This variable must be defined for VCS to work. (All others are optional and default to the current directory.)

journal:

The file name and path in which VCS creates a journal (journal.vcs) that contains the information about changes to revisions in an archive.

archivework:

The directory in which VCS keeps backup copies of revisions as they are updated. (This command corresponds to the LOGWORK command in older versions of PVCS.) Do not specify a RAM disk as the ARCHIVEWORK directory.

workdir:

The VCS temporary directory.

Selecting the configuration file

1. In the Project window, choose Configuration from the VCS menu. The Set VCS Configuration dialog box opens.

   

   [Figure 22-2 Set VCS Configuration dialog box

2. Select the configuration file you want and click OK. You need to specify its location if it is not in the current directory.

The PVCS Registration dialog box

The User database directory textbox shows the database directory in which the license database is placed. This directory should be a shared directory on the network if multiple developers are using the same copy of the IDDE from the network. If developers have individual copies of the IDDE, do not change the text in this box.

Note: If you have PVCS version 5.0 or later, the IDDE does not display the PVCS Registration dialog box.

Putting Revisions into the Archive

Note: If, while you were performing a MERGE, another person has PUT a new revision of a file you want to PUT, VCS warns you with a modal dialog box that you must perform another MERGE operation on the revision.

To prevent others from working on a revision while you are merging it, check Lock Master File on Merge. See the section "Merge Options," earlier in this chapter, for more information.

To begin a PUT operation, choose Put from the Project window's VCS menu. The Put dialog box is displayed.

[Figure 22-3 Put dialog box

The Put Candidate Files listbox shows those workfiles in your private project directory that have changed since you checked them out. Click the Add button to add files from this list to the Files to Put Back listbox; this shows the files you want to PUT into the master archive. To remove a revision from the Files to Put Back list, select it and click on Remove.

Click on Select All to select all files in the current listbox. Click on Unselect All to deselect them.

Select a file name and click on View Log for a summary of who changed the latest revision of that file and the changes that were made.

To associate comments with all selected files in the Files to Put Back listbox, type them into the Comments textbox.

Click on Put to PUT the files listed in the Files to Put Back listbox into the master archive.

Click on the Advanced button and the Put dialog box expands to show additional options.

When you PUT files into the archives, you can specify a group of files using the Put Special textboxes. The Put Special options are:

Revision:

Specifies the revision number you want to give the workfiles you are putting into the archives. The revision number has the format nn.xx, where nn is the major number and xx is the minor number. The numbers can range from 0 to 65,535.

If you do not explicitly assign a revision number to a revision, VCS assigns one automatically by incrementing the minor number of the most recent revision by one.

Version:

Assigns the name you want to a group of revisions, such as beta or alpha. VCS associates the version name with all revisions listed in the Files To Put Back listbox.

Date/Time:

The date and time of a version or revision you archive. The default date format is mmm/dd/yy; mmm is the month, dd the day, and yy the year. The time format is hh[:mm[:ss]]; hh is the hour, mm is the minute, and ss is the second.

Creating a new branch

When you are ready, you can MERGE your private revisions back into the master archive.

Note: A MERGE is the only way to make the changes in a branch available to other developers.

Getting Revisions from an Archive

When you GET a revision from an archive, VCS records the revision identification numbers of the files, marks them as unchanged and not new, and adds them to your project (if you so specify in the Get dialog box).

If you are using the linear development model, VCS locks the archived revisions when you GET them so nobody else can GET them until you PUT them back. If you are using the parallel model, more than one developer can check out the revision unless you specify Get and Lock on the VCS page in the Project Settings dialog box.

To GET revisions from the master archive:

1. In the Project window, choose Get from the VCS menu. The Get dialog box is displayed.

   

   [Figure 22-4 Get dialog box

2. The VCS File Name listbox shows the names of all revisions in the archive. Select from this list the files you want to move to your private project directory.

   To add one or more files, click on the file name(s), then click on the Add button. To add all files in the archive, click on the Select All button. VCS moves the files you select to the Work Files listbox.

   To view a summary of who made certain changes to a revision, click on View Log. (This is the same log that is available from the Merge dialog box.)

3. When all the files you want are in the Work Files list, click the Get button. VCS copies those files to your private project directory.

   To remove files from the Work Files list, click on the file name(s), then click on the Remove button.

Show Archives provides the following settings:

All archives:

Displays all archives in the VCS File Name listbox. This is the default setting.

New archives:

Displays in the VCS File Name listbox the names of the new archives and archives that have changed since the last time you performed a GET operation. Choose this option to update your private copy of the project with the most current revision(s).

Except merges:

Displays in the VCS File Name listbox all the new revisions in the archive except those you just merged or need to merge. Select this option to choose only those additional archives you need to build and to test merged revisions.

The Add Files to Project option adds the revisions automatically to the current project when VCS gets them from the archive.

To retrieve a specific revision or version, use the Get Special textboxes:

Revision:

is the number of the revision you want to get from the archives. The revision number has the format nn.xx, where nn is the major number and xx is the minor number.

Version:

is the name of the version you want to GET. The version name identifies a particular version, such as alpha or beta.

Date/Time:

is the date and time of a particular version or revision. The default date format is mmm/dd/yy; mmm is the month, dd the day, and yy the year. The time format is hh[:mm[:ss]]; where hh is the hour, mm is the minute, and ss is the second.

Merging Revisions

Note: Remember that in your revised file, you must refer to the revision with which you want your changes merged. You do this by adding a $revision entry in the file.

When you MERGE a revision, VCS creates a backup of your revision in your private project directory. In addition, VCS provides all possible support for performing MERGE operations safely.

To merge your changes into another revision in the archive, choose Merge from the Project window's VCS menu. The Merge dialog box opens.

[Figure 22-5 Merge dialog box

The Merge dialog box contains four listboxes:

Files you modified:

Shows the files you modified in your private project directory since the last time you performed a GET operation.

Files new in VCS:

Shows archives that someone else has changed since the last time you performed a GET operation. The current (most recent) revision number is displayed. These are files you might need to GET to rebuild the project with your changes and to PUT your new revisions back into the archive.

Files to merge:

Shows files that both you and another person changed since the last time you performed a GET operation. These are the workfiles you need to MERGE.

Merged files:

Shows files that you merged during the current MERGE session.

Click the View Changes button to show the changes you need to resolve when you MERGE the selected revision. When you click View Changes, an annotated change file appears in an IDDE editor window. See the PVCS documentation for information on the format of the display and the meanings of symbols.

When you are ready to perform the MERGE operation, click on Merge. VCS guides you through a three-way merge, incorporating your changes and those made by others into a new revision.

Because the IDDE automatically makes backup copies of both the revision in your private project directory and the revision you want to MERGE it with, you can undo a MERGE (before closing the Merge dialog box) by clicking Undo Merge.

Testing the MERGE operation

Using the VCS Manager

To use the VCS Manager in the Project window, choose Manager from the VCS menu.

The VCS Manager dialog box shown in Figure 22-6 is displayed.

[Figure 22-6 VCS Manager dialog box

Note: You probably will not need to use the VCS Manager dialog box on most projects.

The VCS Directory listbox contains the names of revisions to add to a version or revision. Double-click on the file name to add it to the Selected Files listbox. Click on Select All to select all files.

To assign a version name, type the name, such as beta, in the Version textbox, and click on the Assign button. This assigns the version name to all files in Selected Files. The Assign and Unassign buttons are available only if you specify a version name in the Version textbox.

To control access to a particular version or revision, specify the revision (its number) or version (its name) in the appropriate textbox, then click on Lock to deny access or Unlock to allow access.

To delete a version or revision, specify the appropriate information in the Revision or Version textbox, and click on the Delete button.

Creating a Master Archive

The master archive contains the revisions to all source files in a project. It also records information about changes from the previous revision, a history of the changes since the first revision, a record of who changed the files, the comments attached to the revisions as they were changed, and the date and time that each revision was PUT into the archive. See the PVCS documentation for additional information.

To set up a master archive, you PUT the workfiles in your project directory in the archives using the Put command. This command takes files from the original directory and creates the archives automatically. See "Using the VCS Manager," earlier in this chapter, for more information on the Put dialog box and how to use it.

When you PUT files in an archive, VCS changes their extensions automatically. The last character of the extension on each file is changed to V. For example, the file extension on abc.cpp becomes abc.cpv. If the file does not have an extension, VCS adds the extension .__v to the filename (two underscores and a v).

To create a master archive from the workfiles in your private project directory:

1. Choose Put from the VCS menu in the Project window.
2. PUT the workfiles from your private project directory into the archive by double-clicking on the file in the Put Candidate Files listbox.

   The Put Candidate Files listbox displays the names of workfiles that you changed since the last time you performed a GET operation. The listbox also shows the files that do not yet have archives. Because you are creating the archives, all files in the project are displayed. Files you select are added to the Files To Put Back listbox.

3. To add all your workfiles to the master archive, click on Select All. To remove a workfile from the list of files to archive, select the file in the Files To Put Back list and click on the Remove button.
4. Optional: Type a comment in the Comments textbox. VCS applies your comment to all selected files in the Files to Put Back listbox.
5. Click the Put button to create the master archives and PUT your workfiles in them.

23. Controlling and Configuring the Debugger

Chapter 8, "Testing an Application," presents an overview of the Digital Mars C++ debuggers and explains how to perform typical debugging tasks.

Chapter 24, "Commands Available in Debugging Mode," describes the commands and the functionality of each of the debug windows that you can open from the Views palette.

Commands on the Debug Menu

[Figure 23-1 Debug menu commands

This section describes the commands in the Debug menu in the order shown in Figure 23-1.

Note: Frequently used debugging commands are available from the Debug toolbox. See "Debug Toolbox Icons" in this chapter to learn how to use the Debug toolbox.

Start/Restart Debugging

Note: If you need to specify command-line parameters in your application, you can do so in the Run Arguments dialog box, available by choosing the Arguments command from the IDDE's Project menu.

If debugging is in progress, choosing Start/Restart Debugging restarts the application.

Note: If you want to run the program without debugging it, choose the Execute Program from the Project menu.

Stop Debugging

Step Into

If Step Into is used on a procedure or function call, the debugger steps into the first statement of the function only if tracing is enabled for the module containing that function. For more information, see "The Project Window," in Chapter 24, "Commands Available in Debugging Mode."

If the Assembly window is the active window, this command executes to the next assembly (as opposed to source level) instruction. If the assembly window is open but is not the active window when you use this command, it updates to show the next instruction to be executed.

Step Over

If the Assembly window is the active window, this command executes the program to the next assembly instruction without tracing into function calls. If the current instruction is a call to a function, the program executes to the assembly instruction following the call.

Return from Call

Go until Breakpoint

Go until Next Function

Go until End

Break

Animate

To set the animation delay time, choose the Animate Delay command from the Settings submenu of the Debug menu (see the section "Animate delay," later in this chapter).

Stop Animate

Settings

General

[Figure 23-2 General page of the Debugger Settings dialog box

Flip screen

When Flip Screen is turned on, the application gets control of the screen each time it runs. When Flip Screen is turned off, the debugger does not activate the application to bring it to the foreground each time the debugger gives control to the application.

Animate delay

The Animate Delay dialog box lets you specify the delay in milliseconds. For example, to pause for one second between steps, specify 1000; the default is one-half second (500 milliseconds) delay.

Load symbols when editing

Debug application startup

If you check this option, the debugger automatically sets a fixed breakpoint at the main entry point and lets you trace through the application's startup code. If not, the debugger starts tracing from WinMain() or main() onward.

Automatic switch to debug workspace

Automatic check of project dependencies

Show local data on start debugging

Enable C++ class display

Alternate class display

Source search path

Working directory

Exceptions (32-bit IDDE only)

Exceptions presented on this page are NT exceptions, which are part of the Structured Exception Handling mechanism of Win32. NT exceptions comprise both hardware exceptions (such as access violations, division by zero, or stack overflow) and software exceptions (explicitly initiated either by Win32 APIs- HeapAlloc, for instance- or by your own code). However, C++ exceptions are also accommodated on the Exceptions page. When you throw a C++ exception in a Win32 program, an NT exception is raised. The exception code of the NT exception is the same value, unique to Digital Mars C++, regardless of which C++ exception was thrown.

Note: For more information on Structured Exception Handling, see Microsoft Win32 Programmer's Reference, Volume 2.

You can specify whether or not the debugger should stop on a particular exception, or should stop only if you have not provided a handler for it. (Uses of these options are discussed below.) The Exceptions page is shown in Figure 23-3.

[Figure 23-3 Exceptions page of the Debugger Settings dialog box

Number:

Contains an exception code- a DWORD that uniquely identifies an exception. Exception codes are displayed and entered in the Number field as eight-digit hexadecimal numbers. Symbolic constants for the exception codes of predefined NT exceptions can be found in include\win32\winnt.h, located beneath the directory in which you installed Digital Mars C++.

The layout of an exception code's 32 bits is summarized in a comment in the header file include\win32\winerror.h. If you define your own exceptions, your exception code should adhere to that format.

Name:

Contains a descriptive string. No restrictions are placed on the contents of this field.

Action:

This drop-down list box contains two choices: Stop if not Handled, and Always Stop. For both actions, the debugger stops before the operating system itself responds to the exception.

Stop if not handled:

The debugger stops only if no outstanding __try/__except or __try/catch block will handle this exception.

Always stop:

The debugger stops, whether or not the exception will be handled.

If you have written a handler for a particular exception, you can choose to always stop on that exception to determine the point at which it was raised. If an exception occurs that you have not anticipated and for which you have not written a handler, either Action will make the debugger stop. You can then diagnose the cause of the exception by examining values of variables and the call chain. Stop if not Handled can also be used to debug existing exception handlers. It assists you in diagnosing situations where an exception for which you have written a handler is being raised, but which none of your handlers is catching.

Add:

Adds a new exception to the list contained in the main pane, as specified in the Number, Name, and Action fields. The Number field must contain a value not used by any exception already in the list.

Replace:

Replaces information for the currently selected exception in the main pane with the contents of the Number, Name, and Action fields. This button is disabled if the Number field contains a value different from the Number (exception code) of the selected exception.

Remove:

Deletes the currently selected exception from the list in the main pane.

Reset:

Undoes any changes to the built-in exception entries, without altering any added exceptions. If any built-in exception entries have been deleted, they are restored; all Actions and Names for built-in exception entries are reset.

Multiple EXE/DLL debugging

[Figure 23-4 Multiple EXE/DLL page of the Debugger Settings

Single executable:

Debugs only the executable file. Does not debug DLLs called by the executable.

All loading EXE/DLLs:

Debugs the executable file and all DLLs or EXEs called or spawned by the executable, including DLLs loaded at run-time via explicit calls to the LoadLibrary API.

Specific EXE/DLLs:

Debugs the executable file and specific DLLs or EXEs. Select those you want in the Specify Libraries and/or Modules to Debug portion of the dialog box (enabled only when this radio button is selected).

Calling program:

For a DLL project, this textbox lets you specify the application that calls the DLL.

Debug Toolbox Icons

Figure 23-5 Debug toolbox icons

Working with Breakpoints

• Unconditional
• Conditional
• Delayed

Unconditional breakpoints

You set unconditional breakpoints using the Set Breakpoint or the Set/Clear Breakpoint command (F9) in the Source, Assembly, Function, Data/Object, or Breakpoint windows (as well as in the Spy window when debugging a Windows application). After setting an unconditional breakpoint, choose the Go until Breakpoint command from the IDDE's Debug menu to execute your program until it reaches the breakpoint. When the breakpoint is reached, the program halts and returns control to the debugger.

Note: While in debugging mode, you can also set an unconditional breakpoint by double-clicking in the left margin of the Source window at the line where you want execution to stop.

Conditional and delayed breakpoints

• Stop the execution of the program only when a specified condition evaluates to TRUE
• Stop the execution of the program only when it encounters a breakpoint a specified number of times (this is a delayed breakpoint)
• Evaluate an expression at a breakpoint
• Add code to the program without recompiling

Note: When you choose Set Conditional Breakpoint in the Breakpoint window, the Expression dialog box is displayed first. Enter the address or procedure name (for example) where you want to set the breakpoint. The Set Code Breakpoint dialog box is then displayed to allow you to specify the kind of breakpoint to set.

[Figure 23-6 Set Code Breakpoint dialog box

The debugger automatically sets the Line, Address, and Procedure fields, based on the location of the breakpoint.

Limit:

Use this field to reach the breakpoint a specified number of times before the debugger stops program execution. This sets a delayed breakpoint.

Condition:

Use this field when you want an expression to be evaluated every time execution of the program reaches this breakpoint. If the expression evaluates to TRUE (nonzero), the debugger performs the action( s) specified in the Actions group. In the Condition field, enter the expression to be evaluated.

Evaluate:

Check this option if you want the debugger to evaluate the next field's expression whenever the program reaches this breakpoint. If you use the Condition field, a breakpoint is triggered only if the Condition evaluates to TRUE.

This field allows you to insert into your code a statement that you had neglected to include, or to test (in the debugger) that a modification works before editing, compiling, and linking.

Note: Please refer to Appendix A, "Expression Evaluation," for more information about expressions.

Break:

Check this option if you want the debugger to stop execution of the program whenever the program reaches this breakpoint. If you use the Condition field, the debugger stops execution on reaching this breakpoint only if the Condition evaluates to TRUE.

Examples of conditional breakpoints

Example 1

The debugger executes your program and evaluates the condition every time it executes the line on which the breakpoint is set. If the condition specified does not evaluate to TRUE, the debugger continues to execute your program. As soon as the value of i + j exceeds 2000 when this line is executed, the debugger stops executing the program and regains control.

Example 2

Set a conditional breakpoint on the line and specify the Evaluate option, as shown in Figure 23-7.

[Figure 23-7 Setting a breakpoint in your code

Every time the debugger reaches this line and i + j > 2000 is TRUE, it calls RESULTS.AddRes(i). However, it does not stop executing your program because you did not check the Break check box.

For information on breakpoint and watchpoint commands in windows, see "The Command Window," in Chapter 24, "Commands Available in Debugging Mode."

Working with Watchpoints

You can set watchpoints using the debugger. First, highlight either a variable in the Data/Object window or a memory location in the Memory window, then execute the Set Watchpoint command in that window's Watch menu. You need not specify an address for the watchpoint. The debugger sets the watchpoint on the address of the highlighted variable or on the highlighted location in memory.

Digital Mars C++ uses the debugging capabilities of the 80386 and higher microprocessors to provide full-speed execution of watchpoints. These microprocessors relieve the debugger of the need to check for the use of watchpoint locations when certain instructions or functions are executed. Watchpoints implemented with hardware assistance are called hardware watchpoints, in contrast to the slower software watchpoints that debuggers must implement in the absence of hardware support.

Setting watchpoints

[Figure 23-8 Set Watchpoint dialog box

You can set up to four 1-byte watchpoints. You can also set four 2-byte watchpoints if all the addresses in memory for which the watchpoints are set are word aligned.

Use watchpoints on local variables with caution

	Warning: Setting a watchpoint on stack memory 

24. Commands Available in Debugging Mode

The descriptions of the debug windows and their menu commands follow, in alphabetical order. Each window's commands are discussed in the order in which they are listed in the menu bar.

• Debug Windows and Commands
• Assembly Window
• Breakpoint Window
• Call Window
• Command Window
• Console Window
• Data/Object Window
• Function Window
• Graphic Data Window
• Inspector Window
• Memory Window
• Output Window
• Project Window
• Register Window
• Source Window
• Spy Window
• Thread Window (32-Bit IDDE Only)
• Trace Messages Window
• Trace Messages Window
• Watch Window

Debug Windows and Commands

Because many of the commands associated with these views are applicable only while a specific window is active, each debug window has its own menu, located below the window's title bar.

A window's commands are available only while that window is active. For example, because you would not set a breakpoint when using the Call window, no breakpoint commands appear among the Call window's menus. Because setting breakpoints is a typical source-level operation, several breakpoint commands are available when the Source window is active.

Drag and drop

Accelerator keys

The Assembly Window

[Figure 24-1 Assembly window

The header line in the Assembly window (below the menu bar) displays the module and function for the currently highlighted assembly instruction. The first column of information in the window area shows code addresses of the assembly instructions. If you choose the Source command from the View menu to enable the interleaved display of C++ source code, this column also shows the line numbers of source-level statements.

If you execute the Step Into (F8) or Step Over (F10) commands from the IDDE's Debug menu while the Assembly window is active, the debugger steps at the assembly level as opposed to at the source level. For more information on controlling the execution of the debugged program, refer to Chapter 23, "Controlling and Configuring the Debugger."

By default, the disassembly location is set to the address of the next statement to be executed. However, by using the Set Disassembly Address command in the Others menu, you can select another address to disassemble.

The arrow, located to the left of the code address, indicates where execution has currently stopped.

When Opcodes is checked in the View menu, the first column contains source code addresses. The second column displays source-level information and/or assembly instructions. The last column displays opcodes for each assembly instruction if Source is checked in the View menu.

The Assembly window has three menus (shown in Table 24-1) in the debuggers: View, Bpt, and Others.

	Table 24-1 Assembly window commands 

	Menu	Menu Item			Shortcut 
	View	Symbols				none 
		Source				none 
		Opcodes				none 
	Bpt	Set/Clear Breakpoint		Ctrl+S/Ctrl+F9 
		Set Conditional Breakpoint	Ctrl+B 
		Clear All Breakpoints		Ctrl+K 
	Others	Set Disassembly Address		Ctrl+A 
		Jump To Line			Ctrl+J 

View menu

[Figure 24-2 Assembly window View menu

Symbols

Source

Opcodes

Bpt menu

Set/Clear Breakpoint

[Figure 24-3 Assembly window Bpt menu

Note: To set a breakpoint, you can drag and drop from the Assembly window to the Breakpoint window. The presence of a breakpoint is indicated by a solid black diamond to the left of the instruction's address. You can move the breakpoint to a different line by dragging the black diamond to a different line. Drop the diamond outside the window to clear the breakpoint.

Set Conditional Breakpoint

Clear All Breakpoints

Others menu

[Figure 24-4 Assembly window Others menu

Set Disassembly Address

0xnnnn:0xnnnn 

0xnnnnnnnn 

Jump to Line

The Jump to Line command simulates a jump instruction, skipping sections of code without executing them. When stepping through the program, it continues executing from the new location.

Pop-up menu

[Figure 24-5 Assembly window pop-up menu

The Breakpoint Window

When a breakpoint in the Source, Assembly, or Spy windows is set, cleared, or triggered, the status of the breakpoint is displayed in this window.

[Figure 24-6 Breakpoint window

The Breakpoint window lists all breakpoints currently defined in the program. You can view the different parameters of any breakpoint and enable or disable the currently defined breakpoint.

The Breakpoint window displays the following information for every line:Location, Address, Count/Limit, Act, Condition, and Action Expr.

Location:

Gives the name of the module in which the breakpoint is set, followed by the function name and the line number in the module.

Address:

Provides the code address of the breakpoint setting.

Count/Limit:

Displays the number of times the breakpoint is triggered. If you specify a break Condition, the count is the number of times the breakpoint has been reached with the specified expression evaluating to TRUE. The limit is the number of times the breakpoint must be reached for it to be triggered. This field is displayed only if you have specified a limit.

Act:

Corresponds to the Action field in the Set Code Breakpoint dialog box. It can contain either or both of the characters B or E, or nothing. If B is present, execution breaks when it reaches this breakpoint location. (If a break condition is specified, execution breaks only if the Condition expression evaluates to TRUE when the location is reached.) If E is present, the Action Expr. field (see below) is evaluated every time the breakpoint is reached.

Condition:

Shows the expression entered for a conditional breakpoint. This expression is evaluated every time execution reaches this breakpoint location. If the expression evaluates to TRUE and the Action field contains B, execution stops.

Action Expr.:

The expression entered for a conditional breakpoint to be evaluated at each breakpoint hit. If you specify a Condition, the action expression is evaluated only if the Condition expression evaluates to TRUE. This expression is evaluated every time the execution reaches this breakpoint location if the Action field contains E. Evaluation does not stop execution of the program unless the Action field also contains B.

The Breakpoint window has two menus, as shown in Table 24-2: Show and Bpt.

	Table 24-2 Breakpoint window commands 

	Menu	Menu Item			Shortcut 
	Show	Source				Ctrl+S 
		Assembly			Ctrl+A 
	Bpt	Set Breakpoint			F9 
		Set Conditional Breakpoint	Ctrl+B 
		Clear Breakpoint		Ctrl+C 
		Clear All Breakpoints		Ctrl+K 
		Enable Breakpoint		Ctrl+E 
		Disable Breakpoint		Ctrl+D 

Show menu

[Figure 24-7 Breakpoint window Show menu

Source

Assembly

Bpt menu

[Figure 24-8 Breakpoint window Bpt menu

Set Breakpoint

Set Conditional Breakpoint

Clear Breakpoint

Clear All Breakpoints

Enable Breakpoint

Disable Breakpoint

Pop-up Menu

[Figure 24-9 Breakpoint window pop-menu

The Call Window

Each entry lists the name of the function called, followed by the name of the module containing that function.

[Figure 24-10 Call window

Use the Call window to display:

• The source-level and assembly-level execution location of any function
• The local data of any function in the call chain

	No call chain (loading) 

	No call chain (terminating) 

	No call chain (error) 

	PROCEDURE AT segment:offset 

If no local symbols are available, the address is displayed as:

	Unknown Procedure 

	Table 24-3 Show Menu commands 

	Menu	Menu Item	Shortcut 
	Show	Source		Ctrl+S 
		Data		Ctrl+D 
		Functions	Ctrl+U 
		Assembly	Ctrl+A 
		All		Ctrl+L 
		Code Address	none 

Show menu

[Figure 24-11 Call window Show menu

Source

Data

Functions

Note: Dragging and dropping from the Call window to the Function window shows all functions in the module in which the selected entry in the Call window resides.

Assembly

All

Code Address

Note: Dragging and dropping from the Call window to the Memory window displays memory contents starting at the instruction pointer address of the selected entry in the Call window.

Pop-up menu

[Figure 24-12 Pop-up menu for Call window

The Command Window

[Figure 24-13 Command window, showing its response to the help command]

To see a list of the supported commands, type help at a Command window prompt and press Enter.

Note: The Command window must be the active window for the debugger to accept commands typed into it.

	Table 24-4 Command window commands 

	Commands and 
	Function Keys 		Action 


	BC *			Clears all breakpoints set in the program 

	BD [number]		Disables the specified breakpoint 
				(numbering of breakpoints starts at 1) 

	BE [number]		Enables the specified breakpoint 
				(numbering of breakpoints starts at 1) 

	BL			Opens the Breakpoint window 

	BP [.[line]][address]	Sets an unconditional breakpoint on the 
				specified source line or on the specified 
				address given in the format appropriate 
				to the memory model 

	CLS			Clears the command window screen 

	DA [address]		Opens the Memory window to address 
				(displays in ASCII) 

	DB [address]		Opens the Memory window (displays in 
				bytes) 

	DD [address]		Opens the Memory window (displays in 
				double words) 

	DI [address]		Opens the Memory window (displays in 
				integers) 

	DL [address]		Opens the Memory window (displays in 
				long real numbers) 

	DS [address]		Opens the Memory window (displays in 
				short real numbers) 

	DT [address]		Opens the Memory window (displays in 
				10-byte real numbers) 

	DU [address]		Opens the Memory window (displays in 
				unsigned integers) 

	DW [address]		Opens the Memory window (displays in 
				words) 

	G			Executes a Go until Breakpoint 
				command 

	HELP			Displays a list of supported commands 
				and functions 

	K			Opens the Call window 

	L			Restarts the program being debugged 

	M			Opens the Memory window 

	P			Executes a Step Over command 

	Q			Closes the Command Line window 

	R			Opens the Register window 

	SA			Opens the Assembly window 

	SS			Opens the Source window 

	T			Executes a Step Into command 

	U[address]		Opens the Assembly window to the 
				specified address 

	V.[line_number]		Updates the Source window to the 
				specified line number 

	F2			Opens the Register window 

	F3			Switches between the Source and 
				Assembly windows 

	F5			Executes a Go Until Breakpoint 
				command 

	F7			Executes a Find Next command 

	F8			Executes a Step Into command 

	F9			Sets or clears a breakpoint 

	F10			Executes a Step Over command 

The Console Window

The Console window looks and behaves much like a DOS Window. It cannot be closed during program execution; choose Stop Debugging to terminate the application.

In the debugger, the IDDE's Flip Screen option affects the Console window. (This option is described in Chapter 23, "Controlling and Configuring the Debugger.") When the debugger executes the text-mode program, the output is displayed in the foreground by default. Choosing Flip Screen allows you to control whether or not the debugger displays the Console window while it executes your program.

Note: Do not turn off the Flip Screen option when working in text mode unless the program you are working with has no output.

The Console window has no local menus.

The Data/Object Window

This view makes it easy to examine the elements of structures and arrays, as well as the contents of pointers and sets. Use the Data/ Object window to set watchpoints on data or to modify data. You can view a graphical representation of any data structure using the Graphic Data window, described later in this chapter.

[Figure 24-14 Data/Object window

The Module and Call windows can update the Data/Object window to display global and local data, respectively. After the variable information is displayed in the Data/Object window, you can examine and modify it.

The Data/Object window supports the display of C++ data type names either in the form member::class or in the form class::member. To control how these data type names are displayed, use the Alternate Class Display option in the Debugger Settings dialog box described in Chapter 23, "Controlling and Configuring the Debugger."

If you didn't select a module or function to show data for, the Data/Object window displays the message:

	No data context selected 

	No global data 

	No local data (no call chain) 

	Table 24-5 Data/Object window commands 

	Menu	Menu Item				Shortcut 
	Find	In Current Scope			none 
		In All Modules				Ctrl+F 
		Next					F3 
	View	Child/Contents				Ctrl+C 
		Parent					Ctrl+P 
		Right (Next Element)			Ctrl+R 
		Left (Prev. Element)			Ctrl+L 
		Specific Index				Ctrl+I 
		Variable Level				Ctrl+V 
		Local/Global Data			Ctrl+X 
		Methods in Class			none 
	Show	Graphic Data Structure			Ctrl+G 
		Memory					Ctrl+E 
		Source of Method			none 
		Address					Ctrl+A 
	Expr	Evaluate Expression			none 
		Convert Decimal to Hex			none 
		Convert Hex to Decimal			none 
	Bpt	Set/Clear Breakpoint on Method		F9 
		Set Conditional Breakpoint on Method	Ctrl+B 
		Clear All Breakpoints			none 
	Watch	Set Watchpoint				Ctrl+W 
		Clear Watchpoint			none 
		Clear All Watchpoints			Ctrl+K 
	ShowAs	Show as Original Type			none 
		Show Value in Hex			Ctrl+H 
		Show Value with Type			Ctrl+T 
		Show Pointer as Array			none 
		Examine String Pointer			Ctrl+S 
		Show Char Ptrs as Strings		none 
	Modify						N/A 
	Inspect!					N/A 
	New!						N/A 

Find menu

[Figure 24-15 Data/Object window Find menu

In Current Scope

In All Modules

Next

View menu

[Figure 24-16 Data/Object window View menu

Child/Contents

• If the selected item is an array, the Data/Object window displays the list of elements in the array, one element per line. The name of each element is its index value in the array. Examine and modify an array element just as you would any other variable.
• If the selected item is an instance of a class, the Data/Object window displays its data members and their values.
• If the selected item is a record or structure, the Data/Object window displays the names and values of the structure elements.
• If the selected item is a pointer, the Data/Object window displays the object it points to.
• If the selected item is a function, module, or method, the Data/Object window displays the message:

  This data is not structured

• If the selected item is a nested block, the Data/Object window displays the variables declared in the nested local scope.

Parent

Right (Next Element)

Left (Prev. Element)

Specific Index

When this command is executed, the debugger prompts you to enter an expression to be evaluated. The result of the evaluation becomes the index of the newly displayed or selected array element.

Note: Use any one of the commands Right (Next Element), Left (Prev. Element), or Specific Index when you are viewing the fields of an array element. The Data/Object window displays the fields of the array with the new index.

For example, if there is an array of records and the record fields of the first element of the array are displayed, you can use the Right (Next Element) command to directly view the record fields of the second element of the array. This is faster than executing the Parent command, changing the selection to the next index, and executing the Child/Contents command.

Variable Level

Local/Global Data

Methods in Class

Show menu

[Figure 24-17 Data/Object window Show menu

Graphic Data Structure

Dragging and dropping from the Data/Object window to the Graphic Data window also executes this command.

Note: The Graphic Data Structure command is disabled if there are not enough Windows resources available to generate a view for the Graphic Data window.

Memory

Source of Method

Address

Expr menu

[Figure 24-18 Data/Object window Expr menu

Evaluate Expression

See Appendix A, "Expression Evaluation," for more information on entering and evaluating expressions.

Convert Decimal to Hex

Convert Hex to Decimal

Bpt menu

[Figure 24-19 Data/Object window Bpt menu

Set/Clear Breakpoint on Method

Set Conditional Breakpoint on Method

Clear All Breakpoints

Watch menu

[Figure 24-20 Data/Object window Watch menu

Set Watchpoint

Dragging and dropping from the Data/Object window to the Watchpoint window also executes this command.

Clear Watchpoint

Clear All Watchpoints

ShowAs Menu

[Figure 24-21 Data/Object window ShowAs menu

Show as Original Type

Show Value in Hex

Show Value with Type

Note: The / symbol to the left of the variable name indicates that the variable is cast to a different type.

When executing Show Value with Type, the debugger prompts you to enter the type name. If the type entered is not a predefined type, the debugger prompts you to enter the module in which that type is defined. The selected variable is then cast to that type. To reset the variable to its original type, choose Show as Original Type.

Show Pointer as Array

Examine String Pointer

Show Char Ptrs as Strings

Modify!

The expression must evaluate to a value of the same size as the variable, but not necessarily to the same type. Refer to Appendix A, "Expression Evaluation," for more information.

Inspect!

New!

Pop-up menu

[Figure 24-22 Pop-up menu for the Data/Object window

The Function Window

[Figure 24-23 Function window

The Function window shows information for one function per line. The first column contains the breakpoint indicator. If a breakpoint has been set on or in the function, the first column contains a solid black diamond. If execution has stopped at a breakpoint in the function, the first column contains the outline of a diamond with a line through it.

The next column contains the execution indicator. If the program has executed into the function, the column contains a right arrow.

Next is the name of the function, followed by the name of the module in which the function is defined, the address of the function, and- if a 16-bit program is being debugged- the memory model type (near or far).

The Function window has four local menus: Find, Show, Bpt, and View, listed in Table 24-6.

	Table 24-6 Function window commands 

	Menu	Menu Item			Shortcut 
	Find	Function			Ctrl+F 
		Module				Ctrl+M 
		Next				F3 
	Show	Source				Ctrl+S 
		Local Data			Ctrl+D 
		Global Data			Ctrl+G 
		Assembly			Ctrl+A 
		All				Ctrl+L 
	Bpt	Set/Clear Breakpoint		F9 
		Set Conditional Breakpoint	Ctrl+B 
		Clear All Breakpoints		Ctrl+K 
		Set On All Functions		none 
		Clear From All Functions	none 
	View	Current Module			none 
		All Modules			none 

Find menu

[Figure 24-24 Function window Find menu

Function

Module

Next

Show menu

[Figure 24-25 Function window Show menu

Source

Local Data

Global Data

Assembly

Note: You can drag and drop from the Function window to the Memory window to show the starting address in which the code for the selected function resides.

All

Bpt menu

[Figure 24-26 Function window Bpt menu

Set/Clear Breakpoint

Dragging and dropping from the Function window to the Breakpoint window also executes this command.

Set Conditional Breakpoint

Clear All Breakpoints

Set On All Functions

Clear From All Functions

View menu

[Figure 24-27 Function window View menu

Current Module

All Modules

Pop-up menu

[Figure 24-28 Function window pop-up menu

The Graphic Data Window

[Figure 24-29 Graphic Data window

Data structures are displayed as boxes connected by lines or arrows. Each box represents a particular data object, each line a relationship between data objects, and each arrow a pointer relationship between data objects.

Data objects are items in the structure that can have either a value or a meaning. Any of the following variables can be data objects: simple types, pointers, arrays, structures, or objects (class instances).

To display a graph, select a variable in the Data/Object window and choose the Graphic Data Structure command from the Show menu. This variable becomes the starting (or root) data object of the graph. When you open the Graphic Data window, the root data object is displayed.

The graph generated from the root data object can be either simple or complex. Simple graphs are created when the form of the structure is a singly linked list. Complex graphs are created when the form of the structure is a tree (with multiple pointers of the same type). If the graph cannot be displayed as a simple graph, it is displayed as a complex graph.

Simple graphs

Complex graphs

When viewing a complex subgraph, each object in the complex structure is displayed. You can zoom in and scroll through the graph to examine the information more closely.

If you are viewing a complex subgraph and want to view its parent graph, choose the Show Parent command.

Creating a graph might take a few seconds, depending on the speed of your machine, the amount of memory available, and the complexity of the data structure. The menu commands of the Graphic Data window are not available until a graph is displayed in the Graphic Data window.

Each object in the graph displays information about itself, such as its name or value. To obtain more information about an object, use the Show Information command. Note that if an object is too small to display its information, you must zoom in on it before the information is displayed.

The Graphic Data window has three local menus: Show, Zoom, and Others.

	Table 24-7 Graphic Data Window commands 

	Menu	Menu Item	Shortcut 
	Show	Information	Ctrl+A 
		Subgraph	Ctrl+S 
		Parent		Ctrl+P 
	Zoom	Zoom In		Ctrl+I 
		Zoom Out	Ctrl+U 
		Zoom Reset	Ctrl+R 
	Others	Clear Graph	Ctrl+C 

Show menu

[Figure 24-30 Graphic Data window Show menu

Note: To use the following commands on a particular object, first click on the object, then execute the command.

Information

Subgraph

Parent

Zoom menu

[Figure 24-31 Graphic Data window Zoom menu

Zoom In

Zoom Out

Zoom Reset

Others

[Figure 24-32 Graphic Data window Others menu

Clear Graph

The Inspector Window

[Figure 24-33 Inspector window

Initially the Inspector window is empty. You add variables to it by dragging them from the Data/Object window, or by selecting a variable in the Data/Object window. then selecting Inspect! from the Data/Object window's local menu. You can also add multiple instances of the same variable to the Inspector window. To delete an instance of a variable from the Inspector window, select Delete! from the Inspector window's menu.

	Table 24-8 Inspector window commands 

	Menu	Menu Item		Shortcut 

	Find	Entry			none 
		Next			F3 
	View	Child/Contents		Ctrl+C 
		Parent			Ctrl+P 
		Right (Next element)	Ctrl+R 
		Left (Prev. element)	Ctrl+L 
		Specific Index		Ctrl+I 
		Variable Level		Ctrl+V 
	Show	Graphic Data Structure	Ctrl+G 
		Memory			Ctrl+E 
		Source of Method	none 
		Address			Ctrl+A 
	ShowAs	Show Pointer as Array	none 
		Show Value in Hex	Ctrl+H 
		Show Value with Type	Ctrl+T 
		Show as Original Type	none 
		Examine String Pointer	Ctrl+S 
		Show Char Ptrs as Strings none 
	Watch	Set Watchpoint		Ctrl+W 
		Clear Watchpoint	none 
		Clear All Watchpoints	Ctrl+K 
	Modify!				Alt+M 
	Delete!				Alt+D 

Find Menu

[Figure 24-34 Inspector window Find menu

Entry

Next

View Menu

[Figure 24-35 Inspector window View menu

Child/Contents

• If the selected item is an array, the Inspector window displays the list of elements of the array, one element per line. The name of each element is its index value in the array. You can examine and modify an array element just as you would any other variable.
• If the selected item is an instance of a class, the Inspector window displays its data members and their values.
• If the selected item is a record or structure, the Inspector window displays the names and values of the structure elements.
• If the selected item is a pointer, the Inspector window displays the object it points to.
• If the selected item is a function, module, or method, the Inspector window displays the message:

  	This data is not structured 
  	

• If the selected item is a nested block, the Inspector window displays the variables declared in the nested local scope.

Parent

Right (Next Element)

Left (Prev. Element)

Specific Index

When this command is executed, the debugger prompts you to enter an expression to be evaluated. The result of the evaluation becomes the index of the newly displayed array element.

Note: Use any one of the commands Right (Next Element), Left (Prev. Element), or Specific Index when you are viewing the fields of an array element. The Inspector window displays the fields of the array with the new index.

For example, if there is an array of records and the record fields of the first element of the array are displayed, use the Right (Next Element) command to directly view the record fields of the second element of the array. This is faster than executing the Parent command, changing the selection to the next index, and executing the Child/Contents command.

Variable Level

Show Menu

[Figure 24-36 Inspector window Show menu

Graphic Data Structure

Dragging and dropping from the Inspector window to the Graphic Data window also executes this command.

Note: The Graphic Data Structure command is disabled if there are not enough Windows resources available to generate a view for the Graphic Data window.

Memory

Source of Method

Address

ShowAs Menu

[Figure 24-37 Inspector window ShowAs menu

Show Pointer as Array

Show Value in Hex

Show Value with Type

Note: The / symbol to the left of the variable name indicates that the variable is cast to a different type.

When executing Show Value with Type, the debugger prompts you to enter the type name. The variable on the selected line is then cast to that type. To reset the variable to its original type, choose Show as Original Type from the ShowAs menu.

Show as Original Type

Examine String Pointer

Show Char Ptrs as Strings

Watch menu

[Figure 24-38 Inspector window Watch menu

Set Watchpoint

Dragging and dropping from the Inspector window to the Watchpoint window also executes this command.

Clear Watchpoint

Clear All Watchpoints

Modify!

The expression must evaluate to a value of the same size as the variable, but not necessarily of the same type. Refer to Appendix A, "Expression Evaluation," for more information.

Delete!

Pop-up menu

[Figure 24-39 Inspector window pop-up menu

The Memory Window

[Figure 24-40 The Memory window

The Memory window shows the contents of a range of memory addresses. You can display memory in 11 different formats, ranging from hexadecimal bytes to real numbers. To display memory, either specify a particular address to view or view the address of a variable by using the Data/Object window's Show Memory command.

In addition to examining a particular address, you can scroll through the Memory window to view all the memory in a segment. In 32-bit flat memory, you can scroll through your application's entire address space. You may not have access to certain memory areas that are restricted to your application. In that case, the memory contents are displayed as Xs. You can modify memory and set memory watchpoints as well.

The Memory window in the debugger has three local menus: View, Watch, and Others.

	Table 24-9 Memory window commands 

	Menu	Menu Item		Shortcut 
	View	Character		Ctrl+H 
		Text			Ctrl+T 
		Byte			Ctrl+B 
		Word			Ctrl+R 
		Unsigned		Ctrl+U 
		Integer			Ctrl+I 
		Long Integer		Ctrl+G 
		Short Real		Ctrl+S 
		Long Real		Ctrl+E 
		Extended Real		Ctrl+X 
		Address			Ctrl+D 
	Watch	Set Watchpoint		Ctrl+W 
		Clear Watchpoint	none 
		Clear All Watchpoints	Ctrl+K 
	Others	Modify			Ctrl+M 
		Set Memory Address	Ctrl+A 
		Set Live Memory Expression Ctrl+L 
		Show Child		Ctrl+C

View menu

[Figure 24-41 Memory window View menu

Character

Text

Byte

Word

Unsigned

Integer

Long Integer

Short Real

Long Real

Extended Real

Address

Watch menu

[Figure 24-42 Memory window Watch menu

Set Watchpoint

Clear Watchpoint

Clear All Watchpoints

Others menu

[Figure 24-43 Memory window Others menu

Modify

Set Memory Address

Type the address in the form 0Xnnnn:0Xnnnn to specify a 16-bit segment:offset pair; type the address in the form 0Xnnnnnnnn, where nnnnnnnn is an 8-digit hexadecimal number, to specify a 32-bit address. For 16-bit code, to view another offset in the same segment ac is currently displayed, enter only the offsed location. The Memory window then displays the contents of memory at the new location.

Set Live Memory Expression

Show Child

Pop-up menu

[Figure 24-44 Memory window pop-up menu

The Output Window

[Figure 24-45 Output window

The Output window's local menus are described below.

	Table 24-10 Output window menu commands 

	Menu	Menu Item	Shortcut 

	Edit	Copy All	none 
		Clear		none 
	Stop!			none 

Edit

[Figure 24-46 Output window Edit menu

Copy All

Clear

Stop!

The Project Window

[Figure 24-47 Project window

Two columns in the right pane contain meaningful information only when the IDDE is in debugging mode; otherwise they display N/A. The EXE/DLL column indicates the executable to which a module belongs. The Virtual column indicates whether or not a module whose debug information has been loaded has not had its code loaded. You can set breakpoints for such a module; however, you cannot set watchpoints because the module's data has not yet been loaded.

The icon to the left of each entry in the Project window's right pane contains status information about the module or file:

• The black bug symbol in the left part of the icon (it may look like * on some monitors) signifies that this module is compiled with debugging information.
• The small black T in the right part of the icon signifies that tracing into this module is enabled.
• The dot in the lower part of the icon signifies that a breakpoint has been set in the module. If the dot is green, the breakpoint is enabled; if the dot is red, the breakpoint is disabled.

The Project window in the debugger has four local menus: Parse, View, Trace, and VCS (shown in Table 24-11).

	Table 24-11 Project window commands

	Menu	Menu Item	Shortcut

	Parse	Update All	none
		Parse All	none
		Parse File	none
		Unparse File	none
		Stop Parse	none
	View	Source		Ctrl+R
		Global Data	Ctrl+G
		Functions	Ctrl+U
		Assembly	Ctrl+A
		All		Ctrl+L
		Code Address	none
	Trace	Enable		Ctrl+E
		Disable		Ctrl+D
		Enable All	none
		Disable All	none
	VCS	Configuration	none
		Get		none
		Put		none
		Merge		none
		Manager		none
		Settings	none

Parse menu

View menu

[Figure 24-48 Project window View menu

The commands in this menu are grayed out unless the selected file contains code. For example, they are grayed out for header files, .def files, and .res files.

Source

Note: To search for source files in different directories, include those directories in the DPATH environment variable.

[Figure 24-49 Project window View menu

Global Data

Functions

Assembly

All

Code Address

Note: Dragging and dropping from the Project window to the Memory window displays memory starting from the code address of the selected entry in the Project window.

Trace menu

While stepping through a program using the Go menu commands, the debugger does not stop the program in modules that have tracing disabled. To prevent stepping into a particular module, disable tracing for that module.

[Figure 24-50 Project window Trace menu

Enable

Disable

Enable All

Disable All

VCS menu

Pop-up menus

[Figure 24-51 Project window pop-up menu

There are three items in the Don't Show submenu: Modules, Parsed, and Dependencies. When Modules is checked, the right pane excludes files explicitly added to the project. Checking Parsed excludes files added to the project only as a result of parsing. Checking Dependencies excludes files added to the project only as a result of building the project.

The Register Window

[Figure 24-52 Register window

The Register window displays the registers either horizontally or vertically, and in either hexadecimal or decimal format. Select a specific register by clicking on it or by using the arrow keys. The Register window has two local menus, View and Others, listed in Table 24-12.

	Table 24-12 Register window commands 

	Menu	Menu Item		Shortcut 

	View	Hex			Ctrl+H 
		Decimal			Ctrl+D 
		Vertical/Horizontal	Ctrl+X 
	Others	Modify			Ctrl+M 
		Out Byte to Port	none 
		Out Word to Port	none 
		In Byte from Port	none 
		In Word from Port	none 

View menu

[Figure 24-53 Register window View menu

Hex

Decimal

Vertical/Horizontal

Others menu

[Figure 24-54 Register window Others menu

Modify

Out Byte to Port

Out Word to Port

In Byte from Port

In Word from Port

Pop-up menu

The Source Window

In debugging mode, you can view or change the current execution position, manipulate source-level breakpoints, and set the Assembly window view to a particular source line in a Source window. See Chapter 6, "Editing Program Code," for information on editing in a Source window.

[Figure 24-55 Source window

Use any of the following methods to view the source file of a particular module:

• Use the View Source command in the Project window.
• Select the Open command from the IDDE's File menu to view a module.
• Drag and drop the module from the Project window to an open Source window, or to the desktop, to open a new Source window.
• Double-click on the module in the Project window.

Several different status messages can appear in the Source window. If the source file cannot be found, the window displays the following message:

	Source file not found 

	No source associated 

If a line contains a function call that has not yet returned, the second column contains an arrow. If execution has stopped at a breakpoint in the program, the line with the breakpoint is similarly marked with an arrow. Because it is the current line, it is also highlighted. (Refer to "Working with Breakpoints," in Chapter 23, "Controlling and Configuring the Debugger," for more information about breakpoints.)

The Source window has five local menus: File, Edit, Goto, Macro, and New!. The commands in the Macro menu also can be useful during debugging, because some Source window debugging commands can be recorded, edited, and played back. See Digital Mars C++ IDDE Help for more information on the Digital Mars BASIC scripting language. Some Goto commands also can be useful during the debugging session. The other menus contain commands that are generally applicable to editing. These are discussed in detail in Chapter 21, "Text Editor Reference."

Pop-up menu

[Figure 24-56 Source window debugging mode pop-up menu

Commands in the Source window debugging mode pop-up menu are listed in Table 24-13.

	Table 24-13 Source window debugging mode pop-up menu 

	Menu Item		Shortcut 

	Set/Clear Breakpoint	none 
	Set Conditional Breakpoint none 
	Clear All Breakpoints	none 
	Go Until Line		none 
	Skip to Line		none 
	Show Assembly		none 
	Show Functions		none 
	Show Data		none 
	Show Memory		none 
	Show Code Address	none 
	Query Implementors	none 
	Query Value		none 

Set/Clear Breakpoint

Move a breakpoint by dragging the flag (circle) in the left side to a new line, signifying that a breakpoint has been set on this line. Clear a breakpoint by dragging the flag out of the Source window and dropping it on the desktop.

You also can set an unconditional breakpoint by dragging a source line from the Source window to the Breakpoint window. It is possible to clear the breakpoint by dragging the source line it is set on into the Breakpoint window. You can perform these drag operations only if the Normal Selection for Debugging option on the Text page of the Editing/Browsing Options dialog box is unchecked.

Set Conditional Breakpoint

Clear All Breakpoints

Go until Line

Skip to Line

To use this command, select the source line on which you want execution to resume and choose Skip to Line from the pop-up menu.

If there is more than one source-level statement on that line, the debugger uses the first statement on the line.

After this command is executed, the code and instruction pointer registers are updated and the Source window shows the new execution location. This command simulates a jump instruction and lets you skip portions of code you don't want to execute.

Show Assembly

Show Functions

Show Data

Show Memory

Show Code Address

Query Implementors

Query Value

Toolbar

[Figure 24-57 Source window debugging mode toolbar]

Open:

Same as choosing Open from the File menu.

Toggle Breakpoint:

Same as choosing Set/Clear Breakpoint from the pop-up menu.

Conditional Breakpoint:

Same as choosing Set Conditional Breakpoint from the pop-up menu.

Query Value:

Same as choosing Query Value from the pop-up menu.

Find:

Same as choosing Find from the Edit menu.

Find Previous:

Searches backward in the file for search string.

Find Next:

Searches forward in the file for search string.

Play Macro:

Same as choosing Play Macro from the Macro menu.

The Spy Window

• Log messages sent to selected windows
• Select windows to spy on
• Post messages to windows
• Set breakpoints on messages
• Update the Source window to the location of a corresponding window procedure

[Figure 24-58 Spy window

The Spy window has four local menus: File, Show, Bpt, and Commands, as listed in Table 24-14.

	Table 24-14 Spy window commands 

	Menu	Menu Item		Shortcut 

	File	Open			none 
		Close			none 
		Pause			none 
	Show	Window Proc Source	Ctrl+S 
		lParam Memory		Ctrl+E 
	Bpt	Set Breakpoint on Message	Ctrl+Z 
		Set Breakpoint		Ctrl+B 
		Clear All Breakpoints	Ctrl+K 
	Commands Spy Enabled		Ctrl+Y 
		Clear Spy Window	Ctrl+C 
		Specify Windows		Ctrl+W 
		Specify Messages	Ctrl+M 
		Post Message		Ctrl+P 

File menu

[Figure 24-59 Spy window File menu

Open

Close

Pause

Show menu

[Figure 24-60 Spy window Show menu

Window Proc Source

lParam Memory

Dragging and dropping from the Spy window to the Memory window also executes this command.

Bpt menu

[Figure 24-61 Spy window Bpt menu

Set Breakpoint on Message

Set Breakpoint

Clear All Breakpoints

Commands menu

[Figure 24-62 Spy window Commands menu

Spy Enabled

Clear Spy Window

Specify Windows

Specify Messages

Post Message

Once you have queued at least one message for posting, the Exit and Post button becomes enabled; clicking on it posts all the messages you have queued to their respective windows, in the order in which you queued them.

The Thread Window (32-Bit IDDE Only)

• Switch easily between threads to debug
• Update the Source window with a thread's current location
• Update the Data/Object window with a thread's data
• Update the Call window with a thread's call chain

[Figure 24-63 Thread window

Current threads are listed one per row, with the currently selected thread highlighted. You can change the selection by clicking on a different row or by using the arrow keys. The primary thread is identified by a bold arrow in the left margin. This thread receives user input and is automatically created by the operating system when a process (an instance of an application) is created. The active thread- the one from which the debugger regained control- is identified by a normal arrow in the left margin. The columns of the Thread window have the following significance:

	Table 24-15 Thread window columns 

	Column Title	Meaning 

	id		Thread ID number. Thread IDs are unique 
			within a process. 
	stat		Status. Possible values of this field are: 
			Frz -the thread is "frozen" 
			(suspended) 
			Thw -the thread is "thawed" (resumed 
			or not suspended) 
	prty		Priority. 
	esp		Current top of stack for thread. 
	eip		Current instruction location for thread. 

	Table 24-16 Thread window commands 

	Menu	Menu Item	Shortcut 

	Show	Source		Ctrl+S 
		Data		Ctrl+D 
		Call Chain	Ctrl+C 
		All		Ctrl+L 
	Action	Freeze		Ctrl+F 
		Thaw		Ctrl+T 
		Freeze Others	Ctrl+O 
		Thaw Others	Ctrl+M 

Show menu

[Figure 24-64 Thread window Show menu

Source

Data

Call Chain

All

Action menu

Freeze

Thaw

Freeze Others

Unfreeze Others

Pop-up menu

The Trace Messages Window

Note: Because of differences in system level support for debugging, tracing does not begin in the Trace Messages window on Windows 95 or Windows NT until you start debugging and choose Go Breakpoint or Go End. On Windows 3.1, tracing begins when you start debugging.

[Figure 24-65 Trace Messages window

The top line of the Trace Messages window displays the destinations of messages. The possible messages are:

	Table 24-17 Trace Messages window message destinations 

	Top Line		Meaning

	No output		Messages are neither 
				written to the window 
				nor saved to the file. 

	Output to window only	Messages are written 
				to the window only. 

	Output to window, File:pathname		Messages go to both 
						the Trace Messages 
						window and to the 
						trace file. 

	Table 24-18 Trace Window commands 

	Menu	Menu Item		Shortcut 

	File	Open Trace File		none 
		Close Trace File	none 
		Pause Trace File	none 
	Options	Windows Debug Messages	none 
		MFC Debug Messages	none 
		OLE2 LRPC Spy		none 
		Output to Window	none 
		No Output		none 
	Clear!				none 

File Menu

[Figure 24-66 Trace Messages window File menu

Open Trace File

Close Trace File

Pause Trace File

Options Menu

Note: In the 32-bit IDDE, only the commands Output to Window and No Output are present in the Options menu..

[Figure 24-67 Trace Messages window Options menu

Windows Debug Messages

[Figure 24-68 Windows Trace Debug Options dialog box

The Break Options group lets you specify whether errors, warnings, or messages should cause a break to the debugger. Unless Break with INT 3 is checked, a stack trace is written to the Trace Messages window whenever the debugging version of Windows causes a break to the debugger.

The Debug Options group lets you direct the debugging version of Windows to perform various operations that assist you in diagnosing problems.

The Trace Options group lets you specify which informational messages are written to the Trace Messages window.

The options chosen here are stored in the [Windows] section of win.ini. The Trace Options group corresponds to the DebugOptions entry in win.ini: each check box corresponds to a single bit of the hexadecimal number stored as the value of DebugOptions. The Break and Debug groups correspond to the FilterOptions entry in win.ini: here also, each check box corresponds to a single bit of the hexadecimal number stored as the value of FilterOptions.

For further information on these options, see the documentation for the WINDEBUGINFO structure in Microsoft Windows Programmer's Reference, Volume 3. In particular, the bits of the fields dwOptions and dwFilter of WINDEBUGINFO correspond to the DebugOptions and FilterOptions entries in win. ini.

Note: If you choose this command and are not running the debug version of Windows, a message box informs you:

	This command requires installed 
	debugging Windows system binaries. 

MFC Debug Messages

[Figure 24-69 MFC Trace Debug Options dialog box

This dialog box lets you choose which MFC debug messages to capture. The options chosen here are stored in the [Diagnostics] section of the file afx. ini, located in the Windows directory. The Enable Tracing check box corresponds to the TraceEnabled entry in afx. ini. The remaining check boxes correspond as a group to the single entry TraceFlags in afx. ini, and each check box corresponds to a single bit of the hexadecimal number stored as the value of TraceFlags.

OLE2 LRPC Spy

[Figure 24-70 OLE LRPC Trace Debug Options dialog box

Output to Window

No Output

Clear!

The Trace Messages Window

[Figure 24-71 Trace Messages window]

The top line of the Trace Messages window displays the destinations of messages. The possible messages are:

Table 24-19 Trace Messages window message destinations

No output

Messages are neither written to the window nor saved to the file.

Output to window only

Messages are written to the window only.

Output to window, File:pathname

Messages go to both the Trace Messages window and to the trace file.

	Table 24-20 Trace Window commands 

	Menu	  Menu Item	 	   Shortcut 

	File	  Open Trace File	   none 
		  Close Trace File	   none 
		  Pause Trace File	   none 
	Options	  Windows Debug Messages   none 
		  MFC Debug Messages	   none 
		  OLE2 LRPC Spy		   none 
		  Output to Window	   none 
		  No Output		   none 
	Clear!				   none 

File Menu

[Figure 24-72 Trace Messages window File menu

Open Trace File

Opens a trace file, to which the Trace Messages window output is saved. You are prompted to enter a filename. Provided you have chosen Output to Window in the Options menu (see below), the file is created and all subsequent Trace Messages window output is written to this file, until you close or pause trace output to the file.

Close Trace File

Closes the trace file so that trace messages no longer are written to it. To begin logging output again, open a trace file using the Open Trace File command.

Pause Trace File

Acts as a toggle to pause any Trace Messages window output to an open trace file. To resume logging output to the log file, choose the Pause Trace File command again. When output is paused, the menu option has a checkmark next to it.

Options Menu

Note: In the 32-bit IDDE, only the commands Output to Window and No Output are present in the Options menu..

[Figure 24-73 Trace Messages window Options menu]

Windows Debug Messages

(Not in 32-bit IDDE) Displays the Windows Trace Debug Options dialog box, which lets you specify the categories of errors, warnings and debug messages that you want the debugging version of Windows to trap and notify you of.

[Figure 24-74 Windows Trace Debug Options dialog box The Break Options group lets you specify whether errors, warnings, or messages should cause a break to the debugger. Unless Break with INT 3 is checked, a stack trace is written to the Trace Messages window whenever the debugging version of Windows causes a break to the debugger.

The Debug Options group lets you direct the debugging version of Windows to perform various operations that assist you in diagnosing problems.

The Trace Options group lets you specify which informational messages are written to the Trace Messages window.

The options chosen here are stored in the [Windows] section of win.ini. The Trace Options group corresponds to the DebugOptions entry in win.ini: each check box corresponds to a single bit of the hexadecimal number stored as the value of DebugOptions. The Break and Debug groups correspond to the FilterOptions entry in win.ini: here also, each check box corresponds to a single bit of the hexadecimal number stored as the value of FilterOptions.

For further information on these options, see the documentation for the WINDEBUGINFO structure in Microsoft Windows Programmer's Reference, Volume 3. In particular, the bits of the fields dwOptions and dwFilter of WINDEBUGINFO correspond to the DebugOptions and FilterOptions entries in win.ini.

Note: If you choose this command and are not running the debug version of Windows, a message box informs you:

	This command requires installed 
	debugging Windows system binaries. 
	

MFC Debug Messages

(Not in 32-bit IDDE) Displays the MFC Trace Debug Options dialog box.

[Figure 24-75 MFC Trace Debug Options dialog box This dialog box lets you choose which MFC debug messages to capture. The options chosen here are stored in the [Diagnostics] section of the file afx.ini, located in the Windows directory. The Enable Tracing check box corresponds to the TraceEnabled entry in afx.ini. The remaining check boxes correspond as a group to the single entry TraceFlags in afx.ini, and each check box corresponds to a single bit of the hexadecimal number stored as the value of TraceFlags.

OLE2 LRPC Spy

(Not in 32-bit IDDE) Enables monitoring of OLE Lightweight Remote Procedure Calls (LRPC), the mechanism by which OLE2 transports procedure calls across process boundaries from an OLE container to an OLE server or vice-versa. The command brings up the OLE2 LRPC Trace Debug Options dialog box.

[Figure 24-76 OLE LRPC Trace Debug Options dialog box]

Output to Window

Displays debug messages in the window. If you have opened a trace file, you must choose this command for messages to be written to the file. Choosing this checks the item on the menu and unchecks No Output.

No Output

Disables display of debug messages in the window. It prevents messages from being written to any opened trace file. Choosing this command checks the item on the menu and unchecks Output to window.

Clear!

The Watch Window

You can set watchpoints on variables in the Data/Object window, on memory locations in the Memory window, or on ranges.

The Watch window, shown in Figure 24-77, displays a list of all watchpoints set in the program. You can view the memory locations of watchpoints and clear watchpoints selectively.

[Figure 24-77 Watch window]

If no watchpoints are set in the program, the Watch window displays the following message:

	No watchpoints defined 

	name [address range] 

address range: This is the range of memory being watched.

Byte1: This shows the successive bytes being watched in the memory range.

The Watch window has two local menus, Show and Commands, listed in Table 24-21.

	Table 24-21 Watch window commands 

	Menu		Menu Item		Shortcut

	Show		Memory			Ctrl+E 
	Commands	Clear Watchpoint	Ctrl+C 
			Clear All Watchpoints	Ctrl+K 

Show menu

[Figure 24-78 Watch window Show menu]

Memory

Displays the starting address of the watchpoint range and updates the Memory window to display the memory at that address.

Commands menu

[Figure 24-79 Watch window Commands menu]

Clear Watchpoint

Clears selected watchpoints.

Clear All Watchpoints

Clears all watchpoints set in the program.

Pop-up menu

[Figure 24-80 Watch window pop-up menu]

25. ResourceStudio Resource Editor

The Shell Window

Figure 25-1 The Shell window

The Shell window is ResourceStudio's main control center. It opens resource files, creates new resource files, sets preferences, arranges windows, and accesses online help.

File menu commands

Any of these files may be reopened by choosing its name from the menu.

[Figure 25-2 Shell window File menu

New

Opens the New File dialog box (see Figure 25-3). Use this dialog box to create a new resource file.

[Figure 25-3 New File dialog box

Type

Specifies the type of resource file to create.

Resource script	Creates a resource script (.rc) file
Binary resource	Creates a binary resource (.res) file
Icon	Creates an icon (.ico) file
Cursor	Creates a cursor (.cur) file
Bitmap	Creates a bitmap (.bmp) file
Font	Creates a font (.fnt) file

For Resource Script or Binary Resource, the new file opens in a Browser window; otherwise, the appropriate resource editor opens in a separate window.

Platform

Specifies the target platform for the resource file.

Windows 3.1	Creates resources for Windows 3.1
Windows NT	Creates resources for Windows NT
Windows 95	Creates resources for Windows 95

Windows 95 resources use the MENUEX and DIALOGEX resource types for menus and dialogs, respectively. For more information, see your Windows 95 documentation.

Support MFC

Applies to resource script files; specifies that the file should include MFC resource headers. Check this box if you plan to use your resources in an MFC application.

Open

Opens the File Open dialog box (see Figure 25-4). This is a standard dialog box for opening files, with an extra field for specifying the target platform.

[Figure 25-4 File Open dialog box

Target platform

Specifies the target platform. Choices include Windows 3.1, Windows NT, and Windows 95.

Exit

Closes ResourceStudio.