Introduction to the Visual C++ User's Guide (for Visual Fortran)

The Visual C++ User's Guide contains the following information:

  • The Visual C++ Environment
  • Customizing the Visual C++ Environment
  • Working with Projects
  • Text Editor
  • Resource Editors
  • Debugger
  • Source Code Control
  • Automating Tasks in the Visual C++ Environment

Windows Utilities:

  • DDEspy
  • PView
  • Spy++
  • WinDiff
  • ZoomIn

To return to the Visual Fortran Home Page:


Home Page: User Interface Basics

The user interface is the portion of the environment where you display information and specify action. These topics describe the basic operation of the user interface in the Microsoft Visual C++ development environment provided by Visual Fortran.

  • Overview

  • How Do I ... Topics

For information about the Visual C++ development environment user interface

  • Windows and document views

  • Toolbar basics

  • Docking and floating toolbars

  • Directories and search order

  • Keyboard shortcuts

  • Alternative ways to work efficiently

Related Home Pages

  • Customizing Visual C++

  • Working with Projects


Overview: User Interface Basics

Home Page (User Interface) | How Do I ... Topics

The Visual C++ development environment user interface consists of an integrated set of windows, tools, menus, toolbars, directories, and other elements that allow you to create, test, and refine your application in one place. You can also work on other types of documents within the visual development environment, for example Microsoft Excel or Microsoft Word documents.

The user interface uses standard Windows interface functionality along with a few additional features to make your development environment easy to use. The basic features that you use most often are windows and document views, toolbars, menus, directories, and keyboard shortcuts.

You can customize the visual development environment to suit your preferences. Among other customizations, you can establish a layout for the windows associated with a particular project workspace. You can also create custom toolbars, menus, and shortcut keys.

What do you want to know more about?

Windows and document views

Working with spreadsheets and other documents in Visual C++

Toolbars and the Menu Bar

Directories

Keyboard shortcuts

Working efficiently

Customizing the user interface


Windows and Document Views

Home Page (User Interface) | Overview | How Do I ... Topics

Whether you are editing or debugging, the windows for the visual development environment workspaces and document views are fully adjustable. You can position windows for a project according to your preferences. Each project can have its own settings.

Two common window types are document windows and docking windows. The position and size of document windows can be changed within the visual development environment window. They can be maximized and minimized. Docking windows, however, attach to the borders of the application window, or float anywhere on your screen.

To see an example of a document window, you can create or open a text file. Examples of docking windows are the Project Workspace window, the Output window, and debugging windows, such as Variables, Watch, and Locals.

The layout for window types — that is, their visibility, position, and size — is associated either with a project, in the case of document windows, or with editing or debugging operations, in the case of docking windows.

Once you have chosen a layout, the settings for that layout are retained with the project you are working on. If you close a project and later open it again, the document windows have the last layout that you used: The same windows are open, and they have the same sizes and positions. When you create layouts of docking windows or toolbars, either for editing, debugging, or viewing in full-screen mode, those layouts are used for all subsequent sessions until you change them again.

Note Some windows are neither document windows nor docking windows. For example, when you use a utility program listed on the Tools menu, such as Spy++, the characteristics of its windows are determined by the utility program.

What do you want to know more about?

Document windows

Floating or docking windows

Shortcut menus in windows

What do you want to do?

Learn window basics

Work with floating or docking windows


Document Windows

Home Page (User Interface) | Overview | How Do I ... Topics

The following windows are document windows:

  • Editor windows, either for text or resources

  • The resource browser window (except when it is used for active project resources in the project workspace)

Document windows are associated with the project workspace. The visual development environment records their positions, sizes, any selections made in them, any splitting of windows, and so on, once you close a project. When you open the project again, these characteristics are restored.

When you are working with documents using the text editor or other resource editors, you can switch to full-screen mode. With full-screen mode, you can see more text at once.

What do you want to do?

Work with document windows


Floating or Docking Windows

Home Page (User Interface) | Overview | How Do I ... Topics

The visual development environment opens various docking windows as you work. For example, when you run the code in a source window, the Output window opens to display the results.

Docking windows have two display modes: floating or docked. In floating mode, a window has a thin title bar and can appear anywhere on your screen. A floating window is always on top of all other windows.

Floating Window

In docked mode, a window is fixed to a dock along any of the four borders of the main visual development environment window.

Docked Window

What do you want to do?

Work with floating or docking windows


Shortcut Menus in Windows

Home Page (User Interface) | Overview | How Do I ... Topics

Most windows contain a shortcut menu with commands appropriate for the window in its current state. The shortcut menus provide quick access to the most commonly used commands for the window you are working in. For example, the shortcut menu for an editor window displays the Cut, Copy, and Paste commands while editing but displays the Toggle Breakpoint and QuickWatch commands while debugging.

Right-click in any window to display the shortcut menu.

There is also a shortcut menu associated with the dock along the border of the application window. If you right-click in the dock area or on a toolbar, the menu displays commands to show or hide all of the docking windows, and to customize the toolbars.

What do you want to do?

Learn window basics


Working with Other Document Types in Visual C++

You can work with spreadsheets, specifications, flowcharts, and other Active documents without leaving the development environment. When you are working with these documents in Developer Studio, the toolbars of the associated COM component are available and work normally. (Microsoft Word and Microsoft Excel are examples of COM components.)

If you create a file by using software other than Visual Fortran, Visual C++, and COM components, you can still add the file to your project. You can also open the file from the FileView pane, but the associated application is started in a separate window.

What do you want to do?

Create a new Active document within Visual C++

Open an existing document of any type in the project


Creating a New Active Document

You can create new documents in the the visual development environment other than simple text files or file types that the build system recognizes. Because Visual C++ is an Active document container, you can create and work in document types such as those created by Microsoft Word or Microsoft Excel.

To create a new Active document within Visual C++

  1. Click New on the File menu and choose the Other Documents tab.

  2. Select a document file type from the list.

  3. To add the document file to an existing project, select the Add to Project check box and choose a project name from the list.

  4. Type a filename in the File Name box. If you do not supply an extension, the default extension for the file type is automatically appended to the filename.

    Note You should use the extension associated with the appropriate COM component, such as .xls for a Microsoft Excel spreadsheet. Whenever you open an Active document in the development environment, the extension is used to identify the associated Active component.

  5. Click OK.

To open an existing document in a Visual C++ project

  • Double-click the filename in the FileView pane of the Project Workspace.

    If the document is an Active document, it is opened within the development environment and the toolbars for the associated COM component become available.


About Toolbars

Home Page (User Interface) | Overview | How Do I ... Topics

When you first start the visual development environment in its default configuration, the Standard toolbar appears just below the Menu Bar. As you open the various editors, other toolbars appear automatically.

Depending on your workspace preferences, and the size of your screen, you can display as many toolbars as you want, or none at all. You can resize a toolbar, add a menu to a toolbar, enlarge the buttons on a toolbar, and move the toolbars to different locations to suit your needs.

The Menu Bar is a special toolbar at the top of the screen that contains menus such as File, Edit, and Build. The only differences between the Menu Bar and other toolbars are:

  • The Menu Bar always fills a complete row when docked horizontally.

  • You cannot hide the Menu Bar, except in full-screen mode.

    When you are working with a document in full-screen mode, the Menu Bar is not displayed. You still have access to the menus by using keyboard shortcuts.

Note The information about toolbars in this Visual C++ User’s Guide applies to the the visual development environment toolbars, but not to other toolbars that may be displayed. For example, when you open a Word document in the visual development environment,the Word toolbars are available and they function exactly as in a Word application window. The visual development environment toolbars are not available when you are using Word, Excel, or other document software inside the visual development environment to work with various documents in your project. For information about other toolbars, refer to the documentation for the other software.

What do you want to do?

Learn toolbar basics

Dock or float a toolbar

Learn how to customize a toolbar

Work in full-screen mode


About Setting Directories

Home Page (User Interface) | Overview | How Do I ... Topics

The visual development environment provides several options you can use to set and search the directories for the files you need for your project. You can change the directory paths that are searched for certain file types or edit the search order.

The visual development environment searches directories in the order in which they appear in the Directories list. Directory information is stored in registry entries, but you can change the paths or search order within the visual development environment.

The Setup program determines the initial directory paths for several file types and updates the Directories list with these paths. The file types are:

File type | Path contents
Executable files | Specifies where the build utilities, such as NMAKE, CL, LINK, and BSCMAKE, reside.
Include files | Specifies where the compiler should look for include files.
Library files | Specifies where the linker should look for libraries to resolve external references.
Source files | Specifies where the debugger should look for default source files, such as the Microsoft Foundation Class Library and the Microsoft run-time library.

What do you want to do?

Set directories or change the search order


About Keyboard Shortcuts

Home Page (User Interface) | Overview | How Do I ... Topics

Keyboard shortcuts offer an alternative method of performing actions for users who prefer the keyboard to the mouse. Some of the commands in the visual development environment are assigned shortcut keys by default. Other commands do not have any default shortcut key assigned to them.

You can also change the existing keyboard shortcuts or create new keyboard shortcuts for commands that do not have keyboard shortcuts by default.

What do you want to do?

Display a list of current keyboard shortcuts

Customize keyboard shortcuts


Working Efficiently

Home Page (User Interface) | Overview | How Do I ... Topics

The visual development environment provides context-sensitive menus, toolbars, keyboard shortcuts, and other features so you have what you need when you need it without clutter. You can also customize these features to reflect your working style.

The visual development environment often provides a variety of methods for accessing commands. The documentation usually describes a standard method using the Menu Bar, but you may find that toolbar buttons, shortcut menus, or keyboard shortcuts work better for you.

  • Dynamic Menu Bar

    The Menu Bar is context-sensitive. When you begin a new activity, you might notice a new item appearing in the Menu Bar. The drop-down menus listed on the Menu Bar change depending on what you are doing. Some commands are specific to an editor; these are present in a menu only when that editor is in use. Any other command that does not apply to the current situation appears dimmed in the menu.

  • Shortcut menus

    In many of the windows and panes in the visual development environment, you can display a shortcut menu by right-clicking either a selected item in a list or the background of the pane or window.

    The shortcut menu includes common commands related to the area or item. Many of the commands on the shortcut menus are also available by using the Menu Bar. However, you can often issue a command with fewer steps by using the shortcut menu.

  • Quick access to common dialog boxes

    In windows where lists appear, you can often display a commonly used dialog box by double-clicking an item in the list. The particular dialog box that appears depends on the item you double-click and on the context.

  • Editable property pages

    You can display properties by selecting an item, right-clicking it, and clicking Properties in the shortcut menu. The properties are displayed in a property page, which may have several tabs. You can keep this property page on top of other windows by clicking the push-pin button in the upper-left corner. If any properties are editable, you can change them by editing within the property page.

    For example, a new source window opens when you create a new text file. As you type code, the syntax coloring depends on the language property of this window. Right-click anywhere in the source window and click Properties to view the property page. To change the syntax coloring, select a different language.

  • Context-sensitive toolbar display

    When you begin editing or start a new activity, the appropriate toolbars appear for the work you are doing. To display any other available toolbar, click Customize on the Tools menu, click the Toolbars tab, and select the appropriate check box.

    Many toolbar buttons are equivalent to menu commands, but you can also have toolbar buttons without a counterpart on any menu.

  • Context-sensitive keyboard shortcuts

    Shortcut keys change dynamically, depending on what you are doing. You can display a list of current keyboard shortcuts and assign different shortcut keys.

  • Quick information about toolbar buttons and commands

    You can display quick information about each toolbar button by placing the mouse pointer on the toolbar button. (You do not click or press a mouse button.) A tooltip displays the name of the toolbar button, and a brief description appears in the lower-left corner of the application window (the status bar).

    To display a description of the action associated with a menu command, place the mouse pointer over the menu command. The description appears in the status bar.

  • Customizable toolbars and menus

    You can change existing toolbars, create custom toolbars, add menus to toolbars, move or copy toolbar buttons and menu commands, rearrange menus, and change the appearance of buttons and commands.

What do you want to do?

Display a list of current keyboard shortcuts

Customize keyboard shortcuts

Learn how to customize toolbars and menus


How Do I ... Topics: User Interface Basics

Home Page (User Interface) | Overview

What do you want to do?

Work with windows or document views

Learn toolbar basics

Dock or float a toolbar

Set directories or search order

Display a list of keyboard shortcuts

Customize the user interface


Working with Windows and Document Views

Home Page (User Interface) | Overview | How Do I ... Topics

What do you want to do?

Learn window basics

Work with document windows

Work with floating or docking windows


Window Basics

Home Page (User Interface) | Overview | How Do I ... Topics

What do you want to do?

Display the shortcut menu for a window

Move a window

Size a window

Show or hide the status bar in the main visual development environment window

Display the clock on the status bar

Place the most recently used windows at the top of the list on the Window menu

Specify the number of windows that will appear on the Window menu

To display the shortcut menu for a window

  • Point to the window and click the right mouse button.

To move a window

  • Click on the title bar, and drag the window to the location you want.

To size a window

  • Click on the window border, and drag the window border to the size you want.

To show or hide the status bar in the main visual development environment window

  1. On the Tools menu, click Options, and then click the Workspace tab.

  2. Select Display Status Bar to show the status bar, or clear the Display Status Bar check box to hide it.

Notes The status bar displays useful information. Its leftmost text field, for instance, describes the currently selected menu command or the action of the button currently under the mouse pointer.

The status bar also displays progress information about the current operation. For a text editor window, it shows the line and column position of the insertion point, the state of the RECORD KEYSTROKES AND COLUMN MODE, whether the editor is in insertion mode or overstrike mode, and whether the file is set for read-only access. The clock can also be displayed on the status bar as described below.

To display the clock on the status bar

  1. On the Tools menu, click Options, and then click the Workspace tab.

  2. Select Display Clock On Status Bar.

To place the most recently used windows at the top of the list on the Window menu

  1. On the Tools menu, click Options, and then click the Workspace tab.

  2. Select Automatically Sort Window Menu.

To specify the number of windows that will appear on the Window menu

  1. On the Tools menu, click Options, and then click the Workspace tab.

  2. Enter the number of windows in the Windows box.


Working with Document Windows

Home Page (User Interface) | Overview | How Do I ... Topics

What do you want to do?

Tile all document windows

Tile a selection of document windows

Overlap document windows

Split document windows

Show or hide document windows and display project documents when you open a project

Begin or end full-screen mode

Change the full-screen mode window settings

Redisplay the full-screen toolbar button while in full-screen mode

To tile all document windows

  • On the Window menu, click Tile Horizontally or Tile Vertically.

To tile a selection of document windows

  1. On the Window menu, click Windows.

  2. Select the windows you want to tile from the list in the Windows dialog box.

    If the window names are adjacent in the list, click the top name you want and hold down SHIFT and click the bottom name to select those and all names in between. If the names are not adjacent, click the first name and hold down CTRL and click each of the other names.

  3. Click Tile Horizontally or Tile Vertically in the Windows dialog box.

To overlap document windows

  • On the Window menu, click Cascade.

To split document windows

  1. On the Window menu, click Split.

  2. Drag the splitter bars in the window to the location you want, and click the mouse to set the location of the splitter bars.

To show or hide document windows and display project documents when you open a project

  1. On the Tools menu, click Options, and then click the Workspace tab.

  2. Select Reload Documents When Opening Workspace to display project documents or clear Reload Documents When Opening Workspace to not show them.

To begin or end full-screen mode

  • On the View menu, click Full Screen to begin full-screen mode. Click the Full-screen toolbar button or press ESC to end it.

Note When you initially select full-screen mode, a toolbar button with a small graphic of a computer screen is displayed. You can toggle full-screen mode on and off by clicking this button.

To change the full-screen mode window settings

  1. Begin full-screen mode.

  2. Press ALT+T to display the Tools menu.

    You can display and use the Tools menu, although the Menu Bar is not visible.

  3. On the Tools menu, click Options, and then click the Editor tab.

  4. Choose the Window Settings that you want and click OK.

Note The Menu Bar is automatically hidden in full-screen mode, but you can display the menus individually by using the keyboard.

To redisplay the full-screen toolbar button while in full-screen mode

  1. Begin full-screen mode.

  2. Press ALT+T to open the Tools menu. (The Menu Bar is automatically hidden in full-screen mode, but you can open a menu by using the keyboard.)

  3. Click Customize, and then click the Toolbars tab.

  4. Click the Full-Screen check box and then click Close.

Tip You should open a file for editing before beginning full-screen mode. If a file is not opened first, full-screen mode is displayed as a large, empty screen. If this happens, press the ESC key to restore the original screen mode.


Working with Floating or Docking Windows

Home Page (User Interface) | Overview | How Do I ... Topics

What do you want to do?

Show or hide a docking window

Expand or contract a docking window in its docking area

Change a docked window to a floating window

Dock a floating window

Position a floating window over a dock without docking it

View a docking window with the same display as a document window

To show or hide a docking window

  1. To show a docking window, click the name of the window on the View menu.

  2. To hide the window, click the Hide button in the corner of the window. This button may be at the upper-left or upper-right corner, depending on the position of the window.

Note You can show or hide the Output and Project Workspace windows at any time. You can show or hide the debugging windows only during the debug process.

To expand or contract a docking window in its docking area

  • Click the Expand or Contract button near the corner of the window. This button may be near the upper-left or upper-right corner, depending on the position of the window.

    This is a dual-purpose button. When the window is fully expanded, the function of this button is Contract; otherwise, the function is Expand. The tooltip indicates the current function.

To change a docked window to a floating window

  • Double-click in the window border.

To dock a floating window

  • Double-click the window title bar to return the window to its previous docked location, or point to the title bar and drag the window to a different dock area.

To position a floating window over a dock (without docking it)

  1. Point to the title bar of the window.

  2. Hold down the CTRL key and drag the window over any dock area of the application window.

Note The window positions for docking windows are not associated with the current project; they remain the same no matter which project you open. However, the locations of the docking windows can be different depending on whether you are editing or debugging. You can create one layout with your choice of docking windows for editing, and another layout with a different choice of docking windows for debugging. You can create a third layout when editing in full-screen mode. When you switch from editing to debugging, the layout automatically changes.

To view a docking window with the same display as a document window

  1. From the Tools menu, choose Options, and click the Workspace tab.

  2. In the Docking Views list, select the check box for a window to enable its docking characteristics. Clear the box for a window to disable its docking characteristics.

Note By default, the Disassembly window has the characteristics of a document window.


Toolbar Basics

Home Page (User Interface) | Overview | How Do I ... Topics

What do you want to do?

Display or hide toolbars

Move a toolbar

Resize a toolbar

Enlarge the toolbar buttons

Restore a default toolbar

Show the ToolTips for a toolbar

Customize a toolbar

To display or hide toolbars

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. In the Toolbars box, click the names of the toolbars that you want to display. Clear the check boxes for any toolbars that you want to hide.

Note Each displayed toolbar appears in its default location, or in the last location that you moved it to.

To move a toolbar

  1. Point between the buttons on a toolbar, or point to the toolbar title bar if it is a floating toolbar.

  2. Drag the toolbar to a new location. If you drag it to the edge of the application window, the toolbar will dock to the edge of the window automatically.

To resize a toolbar

  • To resize a floating toolbar, drag any of its sides.

Note You cannot resize a docked toolbar.

To enlarge the toolbar buttons

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. Check Large Buttons.

To restore a default toolbar

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. In the Toolbars box, click the name of the toolbar you want to restore to its default state.

  3. Click Reset.

Note You cannot reset a custom toolbar.

To show the ToolTips for a toolbar

  • On the Tools menu, click Customize, click the Toolbars tab, and then select the Show ToolTips check box.

Note ToolTips are on-screen descriptions of toolbar buttons that appear when you float your mouse pointer over a button.


Docking or Floating a Toolbar

Home Page (User Interface) | Overview | How Do I ... Topics

When the visual development environment opens in its default configuration after installation, it displays the Standard toolbar docked at the top of the main application window.

You can make the Standard toolbar or any other toolbar be docked or floating.

In docked mode, a toolbar is fixed to any of the four borders of the application window. You cannot modify the size of a toolbar when it is docked.

In floating mode, a toolbar has a thin title bar and can appear anywhere on your screen. A floating toolbar is always on top of all other windows. You can modify the size or position of a toolbar when it is floating.

What do you want to do?

Change a docked toolbar to a floating toolbar

Dock a floating toolbar

Move a docked toolbar to its last floating position

Move a floating toolbar to its last docked position

Position a floating toolbar over a docked toolbar

To change a docked toolbar to a floating toolbar

  1. Point to a blank area between buttons on the toolbar.

  2. Drag the toolbar away from the dock to the position that you want.

Note If you double-click a docked toolbar, it moves to its previous floating position.

To dock a floating toolbar

  1. Point to the title bar or to a blank area in the toolbar.

  2. Drag the toolbar to any of the four borders of the application window.

Note When the mouse pointer reaches the boundary of the docking area, the toolbar window assumes a shape appropriate for the docking location. Along the top and bottom borders, it becomes a single horizontal row of buttons; along the sides, it becomes a single vertical row.

To move a docked toolbar to its last floating position

  • Double-click the docked toolbar.

To move a floating toolbar to its last docked position

  • Double-click the title bar of a floating toolbar.

Tip If the toolbar has not been docked before, it moves to a new row in the toolbar dock below the Menu Bar.

To position a floating toolbar over a docked toolbar

  1. Point to a blank area of the toolbar or its title bar.

  2. Hold down the CTRL key, and drag the toolbar over any docking area of the application window.

Tip The orientation of a docked toolbar generally corresponds to the orientation of the dock. Toolbars dock vertically on vertical docks and horizontally on horizontal docks. You can switch a toolbar’s docked orientation between horizontal and vertical by pressing or releasing the SHIFT key as you drag the toolbar.


Setting Directories

Home Page (User Interface) | Overview | How Do I ... Topics

What do you want to do?

Add or remove a directory

Change the search order for a directory

To add or remove a directory from the Directories list

  1. On the Tools menu, click Options, and then click the Directories tab.

  2. If necessary, select the platform from the Platform list box.

  3. In the Show Directories For list box, select the type of files for the directory.

  4. To add a directory, in the Directories box, scroll to the bottom of the list, double-click the blank line (indicated by an empty rectangle), and type the directory name. To remove a directory, select it, and then press delete.

To change the search order for a directory in the Directories list

  1. On the Tools menu, click Options and then click the Directories tab.

  2. If necessary, select the platform from the Platform list box.

  3. In the Show Directories For list box, select the type of files for the directory.

  4. In the Directories box, select the directory that you want to move.

  5. Drag the selected directory to its new position.

Note Directories are searched in the order in which they appear in the list.


Displaying Keyboard Shortcuts

Home Page (User Interface) | Overview | How Do I ... Topics

You can display the current keyboard shortcuts, including custom key settings and editor emulations.

To display keyboard shortcuts

  1. From the Help menu, choose Keyboard Map and perform one or more of the following actions:
    • Click Category, Editor, Command, Keys, or Description to sort the keyboard shortcut list alphabetically in different ways.

    • Click the Printer button to print a copy of the list.

    • Click the Copy button to copy the list to the Clipboard so you can paste it into a word processor or other text editor.

    • Click the drop-down menu to filter the list to view either All Commands, Bound Commands, or by menu.

For more information, see Customize keyboard shortcuts.


Home Page: Customizing Visual C++

You can customize various aspects of the layout and operation of Microsoft Visual C++.

  • Overview

  • How Do I ... Topics

For information about customizing Visual C++

  • Customizing your toolbars and menus

  • Adding tools to the Tools menu

  • Assigning shortcut keys to commands

  • Customizing in other ways

Related Home Pages

  • User Interface Basics


Overview: Customizing Visual C++

Home Page (Customizing) | How Do I ... Topics

Visual C++ provides many options for customizing your desktop environment to have the look and feel that works best for you.

What do you want to know more about?

Customizing toolbars and menus

Adding tools to the Tools menu

Assigning shortcut keys to commands

Other ways to customize


About Customizing Toolbars and Menus

Home Page (Customizing) | Overview | How Do I ... Topics

With toolbars you can organize the commands in Visual C++ the way you want to so you can find and use them quickly. You can easily customize toolbars — for example, you can add and remove menus and buttons, change the image or text for a button, create your own custom toolbars, hide or display toolbars, resize, and move toolbars. In previous versions of Visual C++, toolbars only contained buttons. Now toolbars can contain buttons, menus, or a combination of both.

The Menu Bar is a special toolbar at the top of the screen that contains menus such as File, Edit, and Build. You can customize the Menu Bar the same way you customize any toolbar; for example, you can quickly add and remove buttons and menus. You can add existing commands to these menus and delete commands. If you delete a default command (a command supplied with the Visual C++ user interface) from a menu, you can choose later to put it back or add it to a different menu or toolbar.

The only differences between the Menu Bar and other toolbars are:

  • The Menu Bar always spans the full width of the window when docked horizontally.

  • You cannot hide the Menu Bar, except when you are editing in full-screen mode. When you begin editing full-screen mode, the Menu Bar is hidden automatically, but you can choose to display it.

A menu displays a list of commands. Some of these commands have images next to them so you can more quickly identify the command you want. You can create a toolbar button, which may make the command easier to use.

Depending on your workspace preferences, and the size of your screen, you can display as many toolbars as you want, or none at all. You can move the Menu Bar, even when you cannot hide it.

What do you want to do?

Customize a toolbar or menu


About Customizing the Tools Menu

Home Page (Customizing) | Overview | How Do I ... Topics

You can customize the Tools menu by adding, editing, and deleting menu items. You can add frequently used utilities to the Tools menu and run them from within Microsoft Visual C++. To do this, use the Tools tab in the Customize dialog box (Tools menu).

What do you want to do?

Customize the Tools menu


About Customizing Keyboard Shortcuts

Home Page (Customizing) | Overview | How Do I ... Topics

Keyboard shortcuts offer an alternative method of performing actions for users who prefer the keyboard to the mouse. In Visual C++, you can:

  • Display a list of current keyboard shortcuts.

  • Delete existing assignments for shortcut keys.

  • Replace default shortcut keys with different ones.

  • Assign shortcut keys to commands that have none by default.

  • Assign multiple shortcut keys to a command.

Using these assignments, you can choose your own set of shortcut keys — ones that are familiar and natural for you to use, or that have some easily remembered value.

What do you want to do?

Display a list of current keyboard shortcuts

Customize keyboard shortcuts


Customizing with Other Options

Home Page (Customizing) | Overview | How Do I ... Topics

In addition to toolbars, menus, and keyboard shortcuts, you can customize editing, debugging, building, and other aspects of Visual C++. You can also use macros and DLL add-ins to automate tasks.

What do you want to know more about?

Arranging your desktop layout

Customizing debugger windows

Using DLL add-ins

Using macros

What do you want to do?

Assign macros to toolbar buttons or keyboard shortcuts

Edit in full-screen mode

Customize the text editor by emulating another editor

Customize syntax coloring in text editor windows

Customize the text editor by setting save preferences, selection margin, tabs, indents, or fonts

Customize a build process


How Do I ... Topics: Customizing Visual C++

Home Page (Customizing) | Overview

What do you want to do?

Customize a toolbar or menu

Customize the Tools menu

Customize keyboard shortcuts

Customize in other ways


Customizing Toolbars and Menus

Home Page (Customizing) | Overview | How Do I ... Topics

What do you want to do?

Create a toolbar

Customize a toolbar

Customize menus on toolbars

Customize menus or menu items

Customize the display for a toolbar button or menu command

Customize menu items for recently used files and workspaces


Creating a Toolbar

Home Page (Customizing) | Overview | How Do I ... Topics

You can create new custom toolbars to work more efficiently. You can include copies of frequently used buttons and menus from existing toolbars, or create a toolbar to use for a special purpose, such as buttons for macros.

What do you want to do?

Create a new toolbar

Rename a custom toolbar

Show or hide a toolbar

Delete a custom toolbar

To create a new toolbar

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. Click New, and in the Toolbar Name box, type a name for the new toolbar.

  3. Position the Customize dialog box out of the way so you can see the new toolbar, and then click the Commands tab.

  4. In the Categories box, click the category that contains the command or other item that you want to add to the new toolbar.

  5. From the Buttons area, drag the button or other item to the new toolbar.

To rename a custom toolbar

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. In the Toolbars box, click the toolbar you want to rename.

  3. In the Toolbar name area, type the new name. Press ENTER.

To show or hide a toolbar

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. In the Toolbars box, select the check box for the toolbar to display it.

    – or –

    To hide the toolbar, clear the check box.

Note You cannot hide the Menu Bar, except when Visual C++ toolbars are hidden automatically. The Menu Bar is hidden automatically when you begin editing in full-screen mode or in another document type, such as a Word document or a spreadsheet.

To delete a custom toolbar

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. In the Toolbars box, select the name of the custom toolbar you want to delete, and click Delete.

Note You cannot delete a default toolbar.


Customizing a Toolbar

Home Page (Customizing) | Overview | How Do I ... Topics

You can customize toolbars by dragging unwanted buttons off or adding a new button, menu, or command.

What do you want to do?

Group related buttons and menus on a toolbar

Add or delete a toolbar button

Create a button for a command or other item

Change the width of a drop-down list on a toolbar

Customize a toolbar button

Troubleshoot the customize command

To group related buttons and menus on a toolbar

To group related buttons and menus, you can add a separator bar before the first and after the last button or menu in the group to distinguish the group from other buttons and menus on the toolbar.

  1. Display the toolbar on which you want to group related buttons and menus.

  2. On the Tools menu, click Customize, and then click the Toolbars tab. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. Right-click the button you want to be the left-most or top button of a group. Click Begin Group on the shortcut menu.

    To put a separator bar at the end of the group, repeat this step for the first button of the next group.

  4. To remove a separator bar, right-click the first button after the separator bar. Click Begin Group on the shortcut menu to clear the check mark and remove the separator bar.

To add or delete a toolbar button

  1. Display the toolbar you want to change.

  2. On the Tools menu, click Customize, and then click the Commands tab.

  3. Add a button by clicking the name of the category in the Categories box, and then dragging the button or item from the Buttons area to the displayed toolbar.

    – or –

    To delete a button, drag it off the toolbar.

Notes If you add a new button, command, or other item to a toolbar that does not have a button, button name, or button image associated with it, you will need to create one or more of these items for it.

When you delete a default button from a toolbar, the button is still available in the Customize dialog box (Commands tab, Deleted Commands or All Commands category). However, when you delete a toolbar button with a custom appearance, its appearance is permanently lost, although the command is still available (Customize dialog box, Commands tab).

To save a toolbar button with a custom appearance for later use, create a toolbar for storing unused buttons, move the button to this storage toolbar, and then hide the storage toolbar.

To create a button for a command or other item

  1. Display the toolbar you want to add a button to.

  2. On the Tools menu, click Customize, and then click the Commands tab.

  3. In the Categories box, click All Commands, and then click the command or other item in the list that you want to add to the toolbar.

  4. Drag the item to the toolbar you want to change.

Note If the item does not have a default button, the Custom Button dialog box opens. Select an image for the button from the Buttons area, or use a custom image created in a graphics program, or create a button with text on it.

To change the width of a drop-down list on a toolbar

  1. On the Tools menu, click Customize, and then click the Toolbars tab.

  2. Click the drop-down list box on a toolbar.

  3. Point to the left or right border of the list box. When the mouse pointer changes to a double-headed arrow, drag the border of the list box to change its width.

To troubleshoot the Customize command

  • If you removed the Customize command from the Tools menu or if you removed the Tools menu, you can still customize a toolbar by right-clicking any toolbar or the Menu Bar, and then clicking Customize on the shortcut menu.

  • To restore the Customize command to the Tools menu, right-click any toolbar or the Menu Bar, and then click Customize on the shortcut menu. With the Customize box open, right-click Tools on the Menu Bar, and then click Reset in the shortcut menu.

  • To restore the Tools menu to the Menu Bar, right-click any toolbar or the Menu Bar, and then click Customize on the shortcut menu. Click the Commands tab. In the Categories box, click Menus. In the Commands box, drag &Tools to the Menu Bar.

  • To customize a toolbar if you removed the Customize command from the Tools menu, or if you removed the Tools menu, right-click any toolbar, and then click Customize on the shortcut menu.

  • To restore the Customize command to the Tools menu, right-click any toolbar, and then click Customize on the shortcut menu. Hold down CTRL and click the Tools menu, and then click Reset on the shortcut menu.


Customizing Menus on Toolbars

Home Page (Customizing) | Overview | How Do I ... Topics

You can move or copy a menu to a toolbar or from one toolbar to another. You can also add an existing menu to a toolbar, create a new menu on a toolbar, or delete a menu from a toolbar.

What do you want to do?

Add a default menu to a toolbar

Add a custom menu to a toolbar

Move or copy a menu from one toolbar to another

Delete a menu from a toolbar

Restore a deleted default menu to a toolbar

Customize menus or menu items

To add a default menu to a toolbar

  1. Display the toolbar you want to add a default menu to.

  2. On the Tools menu, click Customize, and then click the Commands tab.

  3. In the Categories box, click Menus.

  4. Drag the menu you want from the Commands box to the displayed toolbar.

To add a custom menu to a toolbar

  1. Display the toolbar you want to add a custom menu to.

  2. On the Tools menu, click Customize, and then click the Commands tab. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. In the Categories box, click New Menu. The entry New Menu appears in the Commands box.

  4. Drag New Menu from the Commands box to the displayed toolbar. Visual C++ assigns a default name, such as Custom Menu 1.

  5. To rename the new menu, right-click the name on the toolbar, and then click Button Appearance. Type the new menu name in the Button Text box. To specify a letter as the accelerator key, insert an ampersand before the letter.

  6. To add a command to the custom menu, click the custom menu name on the toolbar to display an empty box. Click a category for the command in the Categories box, and then drag the command from the Commands box to the empty box in the custom menu.

To move or copy a menu from one toolbar to another

  1. Display both the toolbar with the menu you want to move and the toolbar you want to move or copy the menu to.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. To move a menu, click the menu on the toolbar, and drag it to the new location on the same toolbar or another toolbar. To copy a menu, hold down the CTRL key and drag the menu on the toolbar to a new location.

To delete a menu from a toolbar

  1. Display the toolbar you want to delete a menu from.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. Drag the menu you want to delete off the toolbar.

Tip When you delete a default menu, the menu is still available in the Customize dialog box (Commands tab, Menus category). However, when you delete a custom menu, it is permanently deleted. To remove and save a custom menu for later use, create a toolbar for storing unused menus, move the menu to this storage toolbar, and then hide the storage toolbar.

To restore a deleted default menu to a toolbar

  1. Display the toolbar you want to restore the menu to.

  2. On the Tools menu, click Customize, and then click the Commands tab.

  3. In the Categories box, click Menus.

  4. Drag the menu you want from the Commands box to the displayed toolbar.


Customizing Menus and Menu Items

Home Page (Customizing) | Overview | How Do I ... Topics

Some customization affects individual items on a menu, while other changes affect the menu as a whole. You can add, delete, copy, or move menu items. You can rename the menu or restore the original settings for a default menu. If you delete a default command (a command supplied by the Visual C++ user interface) from a menu, you can choose later to put it back or add it to a different menu or toolbar.

If you are using a screen reader (a device for people with vision disabilities) or related software, you can require the Menu Bar display to be compatible. The compatible Menu Bar is text-based.

What do you want to do?

Restore the original settings for a default menu

Rename a custom menu

Add a command or other item to a menu

Delete a command from a menu

Restore a deleted default command to a menu

Move or copy a menu command

Always display the Menu Bar compatible with a screen reader

Customize menus on toolbars

To restore the original settings for a default menu

  1. Display the toolbar that contains the menu you want to restore to its original settings.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. Right-click the menu name on the toolbar, and then click Reset on the shortcut menu.

Note Reset restores the default menu to its original image, commands, and submenus. Default submenus are restored to their original form, and custom submenus are removed.

To rename a custom menu

  1. Display the toolbar that contains the menu you want to rename.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. Right-click the menu you want to rename on the toolbar, and then click Button Appearance.

  4. Type the new menu name in the Button Text box. To specify a letter as the accelerator key, insert an ampersand before the letter.

To add a command or other item to a menu

  1. Display the toolbar that contains the menu to which you want to add a command or other item.

  2. On the Tools menu, click Customize, and then click the Commands tab. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. In the Categories box, click a category for the command or other item. To add a menu command that runs a macro, click Macros.

  4. Drag the item you want from the Commands box over the menu on the toolbar. When the menu displays a list of menu commands, point to the location where you want the item to appear on the menu, and then release the mouse.

Notes If you don’t see the command you want under a particular category, click All Commands in the Categories box.

If you add a command to a menu, and the new command doesn’t appear on the menu when you want to use it, the command may be hidden because it is not available in the current editor. To verify that the command was added to the menu, you can view the complete menu, containing all commands for all editors at the same time. The complete menu is only available while the Customize dialog box is open. On the Commands tab in the Customize dialog box, click All Editors in the Show Menus For list. If the missing command is listed when you display commands for All Editors, it will appear on the menu in any editor where it applies.

To delete a command from a menu

  1. Display the toolbar that contains the command you want to delete.

  2. On the Tools menu, click Customize, and then click the Commands tab. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. Click the menu on the toolbar that contains the command you want to delete.

  4. Drag the command you want to delete off the menu.

To restore a deleted default command to a menu

  1. Display the toolbar that contains the menu to which you want to restore a command.

  2. On the Tools menu, click Customize, and then click the Commands tab.

  3. In the Categories box, click the Deleted Commands category.

  4. Drag the command you want from the Commands box over the menu on the toolbar. When the menu displays a list of menu commands, point to the location where you want the command to appear on the menu on the toolbar, and then release the mouse.

To move or copy a menu command

  1. Display the toolbar with the menu that contains the command you want to move or copy. Next, display the toolbar with the menu you want to add the command to.

  2. On the Tools menu, click Customize, and then click the Commands tab. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. On the toolbar, click the menu that contains the command you want to move or copy.

  4. To move the command, drag it over the menu you want. When the menu displays a list of commands, point to where you want the command to appear on the menu, and then release the mouse. To copy the command, hold down CTRL and drag the command over the menu you want. When the menu displays a list of commands, point to where you want the command to appear on the menu, and then release the mouse button.

To always display the Menu Bar compatible with a screen reader

  1. On the Tools menu, click Options, and then click the Workspace tab.

  2. Check Use Screen-reader Compatible Menus.

Note When this option is checked, the Menu Bar that displays at the top of Visual C++ is text-based. If you are using this screen-reader compatible option, you cannot customize the menus by adding graphics.


Customizing a Toolbar Button or Menu Command

Home Page (Customizing) | Overview | How Do I ... Topics

You can change the image on any toolbar button or menu command, except for a button that displays a list or a menu when you click it.

You can copy an image from one toolbar button to another, from one menu command to another, from a toolbar button to a menu command, or vice versa. You can also create an image in a graphics program and then paste it onto the button or menu command.

You can display text, an icon, or both on a toolbar button. And you can display either an icon and text or text only on a menu command.

What do you want to do?

Move or copy a toolbar button

Change the image of a toolbar button

Display text, an icon, or both on a toolbar button

Display an icon and text or text only on a menu command

Rename a toolbar button or menu command

Restore a toolbar button to its original image

Copy an image from one toolbar button or menu command to another

Copy an image from a graphics program to a toolbar button or menu command

To move or copy a toolbar button

  1. Display the toolbar that contains the toolbar button you want to move or copy.

  2. On the Tools menu, click Customize, and then click the Commands tab.

  3. To move a button, drag it to the new location on the same toolbar or to another displayed toolbar. To copy a button, hold down the CTRL key while you drag the button to the new location.

To change the image of a toolbar button

  1. Display the toolbar that contains the button with the image you want to change.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. On the toolbar, point to the button you want to change, and then click the right mouse button.

  4. On the shortcut menu, click Button Appearance.

  5. In the Images area, click the image you want on the toolbar button.

Tip You can change the button so that it has text on it.

To display text, an icon, or both on a toolbar button

  1. Display the toolbar with the button you want to change.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. On the toolbar, right-click the button you want to change, and then click Button Appearance on the shortcut menu.

  4. To display text, click the Text Only button or the Image and Text button, type the text in the Button Text box.

  5. To display an image, click Image Only or Image and Text, and click an image in the Images area.

Note You can’t change the text and icon format for a button that displays a menu list when you click it. When you display text on a toolbar button, the button does not display a tooltip.

To display an icon and text or text only on a menu command

  1. Display the toolbar with the menu command you want to change.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. Click the menu that contains the command you want to change.

  4. Right-click the menu command you want to change, and then click the option you want on the shortcut menu.

Note Some commands do not have an icon associated with them and can only be displayed on a menu as text. A menu command cannot be displayed as an icon only.

To rename a toolbar button or menu command

  1. Display the toolbar that contains the toolbar button or menu command you want to change.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. To rename a toolbar button, right-click the toolbar button on the toolbar, and then click Button Appearance on the shortcut menu. To rename a menu command, click the menu that contains the command you want to change. Right-click the menu command, and then click Button Appearance on the shortcut menu.

  4. Type the new name in the Button Text box. To specify a letter as the accelerator key, insert an ampersand before the letter when you type the name.

Note If the toolbar button does not display text, you only see the name change when you view the tooltip.

To restore a toolbar button to its original image

  1. Display the toolbar that contains the button.

  2. On the Tools menu, click Customize. The Customize dialog box must remain open; however, you might need to move it out of your way.

  3. On the toolbar, point to the button you want to restore, and then click the right mouse button.

  4. On the shortcut menu, click Reset.

Note You can only reset buttons that have a default image.

To copy an image from one toolbar button or menu command to another

  1. Display both the toolbar with the button image or menu command you want to copy and the toolbar you want to change.

  2. On the Tools menu, click Customize, and then click the Commands tab. The Customize dialog box must remain open; however, you might need to move it out of the way.

  3. To copy a toolbar button image, right-click the toolbar button that contains the image you want to copy, and then click Copy Button Image on the shortcut menu. To copy a menu command image, click the menu that contains the command with the image you want to copy. Right-click the menu command, and then click Copy Button Image on the shortcut menu.

  4. To paste the copied image to a toolbar button, right-click the toolbar button you want to paste the image onto, and then click Paste Button Image on the shortcut menu. To paste the copied image to a menu command, click the menu that contains the command you want to paste the image onto. Right-click the menu command, and then click Paste Button Image on the shortcut menu.

Note You can copy an image from a toolbar button to another button only if the other button is also on a toolbar (the same toolbar or a different one). You cannot change a default button image.

To copy an image from a graphics program to a toolbar button or menu command

  1. Copy the graphic you want to appear on the toolbar button or menu command to the Clipboard. If you can select the format for the copied graphic, select bitmap or picture format.

  2. Switch to Visual C++.

  3. Display the toolbar with the button image or menu command you want to change.

  4. On the Tools menu, click Customize. The Customize dialog box must remain open, however, you might need to move it out of your way.

  5. To paste the copied image to a toolbar button, right-click the toolbar button that contains the image you want to change, and then click Paste Button Image on the shortcut menu.

    To paste the copied image to a menu command, click the menu that contains the command with the image you want to change. Right-click the menu command, and the click Paste Button Image on the shortcut menu.

Note For a clear image, copy a picture that is the same size as a default button image or menu command (the default button image is 16 by 16 pixels; the large button image (which you can enable on the Options tab in the Customize dialog box) is 32 by 32 pixels). A larger image may be distorted because it will be scaled to fit the size of the button.


Customizing Menu Items for Recently Used Files and Workspaces

Home Page (Customizing) | Overview | How Do I ... Topics

Files and project workspaces that you have used recently can be opened by selecting the name of the file or workspace from a menu. You can choose whether the recently used files and workspaces are listed on the File menu or on submenus of the File menu. You can also customize the number of files and workspaces listed.

To customize the menu items for recently used files and workspaces

  1. On the Tools menu, click Options, then click the Workspace tab.

  2. To list recently used files and workspaces on submenus of the File menu, select the Show Recently Used Items on Submenus check box.

    – or –

    To list recently used files and workspaces on the File menu itself, clear the check box.

  3. To change the number of recently used files listed, type the number you want in the Recent File List Contains box.

  4. To change the number of recently used workspaces listed, type the number you want in the Recent Workspace List Contains box.


Customizing the Tools Menu

Home Page (Customizing) | Overview | How Do I ... Topics

You can add up to 16 commands to the Tools menu. These commands can be associated with any program that will run on your operating system. You can also specify arguments for any command that you add to the Tools menu.

What do you want to do?

Add a command to the Tools menu

Edit a command on the Tools menu

Remove a command from the Tools menu

Specify an argument for a Tools menu command

Add an argument macro

Learn about error syntax for tools

To add a command to the Tools menu

As an example, the following procedure demonstrates how to add the Windows Notepad accessory to the Tools menu.

  1. On the Tools menu, click Customize, and then click the Tools tab.

  2. To add a tool, in the Menu Contents box, scroll to the bottom of the list, double-click the blank line (indicated by an empty rectangle), type the name of the tool as you want it to appear on the Tools menu, and press ENTER.

    For example, if you want to add a command for the Windows Notepad accessory, you might type Notepad. The remaining steps specify what action will occur when the new Notepad command is selected.

  3. In the Menu Contents box, highlight the name of the tool you just entered.

  4. In the Command box browse or type the path and name of the program, for example, C:\WINDOWS\NOTEPAD.EXE.

  5. In the Arguments text box, browse or type any arguments to be passed to the program.

    You can use the drop-down arrow next to the Arguments text box to display a menu of arguments. Select an argument from the list to insert argument syntax into the Arguments text box. Visual C++ provides the argument macros shown in the Argument Macros table.

  6. In the Initial Directory box, type the file directory where the command is located and click OK.

    You can use the drop-down arrow next to the Initial Directory text box to display a menu of directories. Select a directory from the list to insert directory syntax into the Initial Directory text box.

Notes Once the command appears on the Tools menu, to run the program, choose it from the menu.

You can change the default menu name of the newly added tool by editing the Menu Text box. You can also add arguments to be passed to the program by typing them in the Arguments text box or set the initial directory for your program by typing it in the Initial Directory text box.

If the program you are adding to the Tools menu has a .PIF file, the startup directory specified by the .PIF file overrides the directory specified in the Initial Directory text box.

To edit a command on the Tools menu

  1. On the Tools menu, click Customize, and then click the Tools tab.

  2. In the Menu Contents box, select the command that you want to edit.

  3. Perform one or more of the following actions:
    • To move the command up one position in the menu, choose the Move Up button.

    • To move the command down one position in the menu, choose the Move Down button.

    • To change the menu text, command line (tool path and file name), command-line arguments, or the initial directory, type the new information in the appropriate text box.

    • To specify a letter in the menu title as an access key, precede that letter in the Menu Contents box with an ampersand.

      The first letter in the title is the keyboard access key by default.

    • To specify that a console application’s output is displayed in the Output window rather than in the console window, click Use Output Window.

    • To specify that the window associated with the tool close when you close the tool, select Close Window on Exiting.

    • To be prompted for command-line arguments each time you run the tool, select Prompt For Arguments.

To remove a command from the Tools menu

  1. On the Tools menu, click Customize,and then click the Tools tab.

  2. In the Menu Contents box, select the command you want to delete and press the Delete button.

To specify arguments for a Tools menu command

  1. On the Tools menu, click Customize, and then click the Tools tab.

  2. In the Menu Contents box, select the command for which you want to specify arguments.

    In the Arguments text box, type the arguments that you want or select the drop-down arrow to the right of the Arguments text box to display a list of arguments.

Visual C++ provides the argument macros shown in the Argument Macros table.


Argument Macros

Home Page (Customizing) | Overview | How Do I ... Topics

You can use argument macros to specify arguments for a Tools menu command. Visual C++ provides the argument macros shown in the following table.

Macro name | Expands to a string containing
$(CurCol) | The current cursor column position within the active window.
$(CurDir) | The current working directory (defined as drive+path).
$(CurLine) | The current cursor line position within the active window.
$(CurText) | The current text (the word under the current cursor position, or a single-line selection, if there is one).
$(FileDir) | The directory of the current source (defined as drive+path); blank if a nonsource window is active.
$(FileExt) | The filename extension of the current source.
$(FileName) | The filename of the current source (defined as filename); blank if a nonsource window is active.
$(FilePath) | The complete filename of the current source (defined as drive+path+filename); blank if a nonsource window is active.
$(TargetArgs) | The command-line arguments that are passed to the application you are developing. To set these command-line arguments, type the argument in the Program Arguments box on the Debug tab accessed by the Settings command on the Build menu.
$(TargetDir) | The directory of the current target (defined as drive+path).
$(TargetExt) | The filename extension of the current target.
$(TargetName) | The filename of the current target (defined as filename).
$(TargetPath) | The complete filename of the current target (defined as drive+path+filename).
$(WkspDir) | The directory of the current workspace (defined as drive+path) that contains the .DSW file; blank if no workspace is currently open.
$(WkspName) | The current workspace name (defined as filename) without the .DSW extension; blank if no workspace is currently open.

Notes Macro recognition is not case sensitive. All path macros end in a backslash (\).

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

To add an argument macro to an installed tool and then run it

As an example, the following procedure demonstrates how to add the $(FilePath) argument macro to the Windows Notepad accessory.

  1. On the Tools menu, click Customize and click the Tools tab.

  2. In the Menu Contents box, select the command that you want to edit. In this case, select the Notepad accessory that you installed earlier.

  3. In the arguments text box, type $(FilePath) or select the drop-down arrow to the right of the Arguments box to display a list of Arguments and then click Close.

  4. To see your changes, on the Tools menu, click Notepad. The Windows Notepad accessory opens, with the active source file as its text file.

What do you want to do?

Learn about error syntax for tools

Customize the Tools menu


Error Syntax for Tools

Home Page (Customizing) | Overview | How Do I ... Topics

When you select the Use Output Window check box for a tool on the Tools tab of the Customize dialog box (Tools menu, Customize command), the Output window’s error parser interprets the output of the tool. You can jump to source-code syntax errors directly from the error list in the Output window.

The Find In Files dialog box also uses the error parser. For example, you can double-click any output line from a Find In Files operation to jump to the referenced file and line.

The error parser detects filenames, errors, and line-number information of output strings, and makes each line in the file a hot link to the specified file and line number. For example, you can double-click an error line in the Output window that contains the error number, filename, and line number where the error occurred, and jump directly to the referenced line in the correct source file.

When you create your own tools, you should use the following error syntax so that the error parser can interpret the output correctly (+ denotes one or more; * denotes zero or more):

Error Type | Description
error_string | file_spec error_spec (STRING | file_spec STRING)
file_spec | FILENAME ‘(‘line_spec’)’ ’:’
line_spec | NUMBER | NUMBER ‘-’ NUMBER
error_spec | ERRORKEYWORD ERRORNUMBER ‘:’
where: |
STRING | Null-terminated string
FILENAME | Valid file specification and text file
NUMBER | {1–9}{0–9}*
ERRORNUMBER | {A–Z}+{0–9}{0–9}{0–9}{0–9}
ERRORKEYWORD | “error” | “warning” | “fatal error”

Note Although the error number is part of this syntax, it is optional and not really useful to any tool except internal build tools.

What do you want to do?

Customize the Tools menu

Learn about argument macros for tools


Customizing Keyboard Shortcuts

Home Page (Customizing) | Overview | How Do I ... Topics

You can use the Keyboard tab on the Customize dialog box to establish your choice of shortcut keys for any of the available commands. You can assign more than one shortcut key for any command. You can delete or change key assignments, and you can assign shortcut keys for each editor. You can also reset all shortcut keys to their default settings.

What do you want to do?

Assign a shortcut key

Delete a shortcut key

Reset all shortcut keys to their default value

To assign a shortcut key

  1. On the Tools menu, click Customize, and then click the Keyboard tab.

  2. In the Editor drop-down list, select the editor to which you want to assign the shortcut key. For example, select Text if you want to assign a shortcut key that will be available when you are working in the text editor.

  3. In the Categories list, select the menu that contains the command to which you want to assign the shortcut key.

  4. In the Commands list, select the command to which you want to assign the shortcut key.

  5. Put the cursor in the Press New Shortcut Key box, press the shortcut key or key combination that you want, and click Assign.

    If you press a key or key combination that is invalid, no key is displayed. You cannot assign key combinations with ESC, F1, or combinations such as CTRL+ALT+DEL that are already being used by your operating system.

    If you press a key or key combination that is currently assigned to another command, that command appears under Currently Assigned To.

Note If you use any of the incremental search commands (IncrementalSearch, IncrementalSearchBack, IncrementalSearchRE, IncrementalSearchREBack), you can modify the search by toggling the word mode (CTRL+W), regular expression mode (CTRL+T), and case-sensitive mode (CTRL+C). These keystrokes are not bindable and only affect the incremental search command.

To delete a shortcut key

  1. On the Tools menu, click Customize, and then click the Keyboard tab.

  2. On the Editor, Categories, and Commands lists, select the location for the shortcut key you want to delete.

  3. In the Current Keys list, select the shortcut key you want to delete and click Remove.

To reset all shortcut keys to their default values

  1. On the Tools menu, click Customize, and then click the Keyboard tab.

  2. Click Reset All.


Home Page: Working with Projects

In the Visual C++ development environment, you organize your projects and their elements in a project workspace. A project workspace can contain multiple projects, including sub- or dependent projects.

  • Overviews

  • How Do I...Topics

  • NMAKE Reference

Related Home Pages

  • Customizing the Visual C++ Environment

  • Debugging

  • Source Code Control


Overview: Working with Projects

Home Page (Projects) | How Do I... Topics | NMAKE Reference

In the Microsoft Visual C++ environment, the Project Workspace is a container for your development projects. When you create a new project, a workspace is created at the same time. You use the Project Workspace window to view and access the various elements of your projects.

After you have created a project workspace, you can add:

  • New projects, including dependent projects.

  • New configurations to an existing project.

  • Subprojects (dependent projects).

The workspace directory is the root directory for the project workspace. The projects you add to the project workspace can be located on other paths, even on a different drive.

What do you want to know more about?

Project workspace files

Project workspace views

Elements of project workspaces

Project types

Subprojects

Project configurations

Building a project configuration

Platform types

Customizing a build process

What do you want to do?

Work with projects and files

Work with subprojects

Use project folders

Work with project configurations

Build a project

Build a project at the command Line

Use custom build rules


Project Workspace Files

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

When you create a project workspace, a project workspace file ProjectName.dsw is created to store information at the workspace level. Other associated files are also created, including a project file (.dsp), for building each project, and a workspace options file (.opt).

The workspace options file stores settings such as those you specify in the Project Settings dialog, and the layout of the project workspace.

Notes If you work in a group, you can put the project workspace file and project files under source-code control and share them with other members of your group so that they can build the projects defined in the project workspace. However, you should not share the workspace options file (.opt) because it contains information specific to your computer. A new workspace options file is created automatically when the workspace is opened and no workspace options file is found. If you are using exported makefiles, you should not share these files. Other users can share the project workspace (.dsw) file and project (.dsp) file, but they should export the makefiles locally.


Project Workspace Views

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Tabs at the bottom of the Project Workspace window provide different ways to view your project. A folder containing the various elements of your project workspace appears for each project view. Expanding the folder displays the details of the project workspace for that view.

The Project Workspace window contains the following views.

View | Description
FileView | Displays the files associated with projects that you have created. These can include buildable as well as non-buildable files.
ClassView | Displays the C++ classes defined in your projects. This view is not used with Visual Fortran projects. Expanding the folders shows the classes; expanding a class shows its members.
ResourceView | Displays the resource files included in your projects. Expanding the folders shows the resource types.
Data View | Displays information about the ODBC data sources in database projects. Data View is available only in the Enterprise Edition of Visual C++, which includes the Visual Database Tools.

You can switch from one view to another by clicking the tabs at the bottom of the Project Workspace window.

Each view is hierarchical. You can expand the folders and other items to display their contents or collapse them to display their organization.


FileView

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

The FileView pane shows relationships among the projects and files included in the project workspace. The relationships in FileView are logical relationships, not physical relationships, and do not reflect the organization of files on your hard disk.

FileView shows the relationships of the source files and the dependent files used to build all project configurations. The active project in the workspace is indicated in FileView by bold type. The active configuration determines which set of build options is used when you build the active project. The active project is the project that will be built when you use the commands Build or Rebuild All. You can select a different active configuration by using the Set Active Configuration command on the Build menu. You can select a different active project by using the Set Active Project command on the Project menu.

Note The External Dependencies folder lists files that are not part of the project but that are needed to build the project. You can add a file to the project by simply dragging it from the External Dependencies folder to any of the project folders, or to any top-level project node.

Using FileView with the Visual Database Tools

Important: Feature Only Available with Visual Database Tools Database projects and related features are supported only when the Visual Database Tools are installed. These features include the Data View pane and the use of FileView to view items in database projects. Visual Database Tools are included with the Visual C++ Enterprise Edition (if Visual C++ is installed, see the Visual C++ documentation).

The FileView pane provides a graphical environment for creating, viewing, and editing local files in a database project. Your database projects appear in the FileView pane as a tree.

In the FileView pane you can:

  • View the files and folders in your database projects.

  • Manage your files. For example, you can add, move, copy, and delete files.

The FileView pane lists the following items:

  • Database Project

  • Data Connection

  • Database Query

The FileView pane also lists all of the files and folders for each data source in your database projects. You can expand each folder to see the files that are stored inside. This feature is especially useful for managing your files. For example, you can:

  • Open a folder that contains a file you want to move or copy.

  • Select a file and move or copy it into another folder.

  • Double-click a file to open it in the application workspace.

  • Create, rename, or delete folders.

  • Create or delete files.

If you want to view only files and folders for a specific database project, you can collapse the database projects that you don’t want to see. You can also choose which project you want to set as the active database project.

In addition to the FileView pane, you can use the Data View pane to create, view, and edit files residing on a remote database server as part of a database project. The Data View pane is visible as a tab in the Project Workspace window when your database project is connected to a data source. The Data View pane is available only with the Visual Database Tools.

What do you want to do?

Use Data View

Use ResourceView


Data View

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Important: Feature Only Available with Visual Database Tools The Data View pane is supported only in certain products. Visual Database Tools are included in the Visual C++ Enterprise Edition (if Visual C++ is installed, see the Visual C++ documentation).

Using the Data View pane, you can create, view, and edit files residing on a remote database server as part of a database project. The Data View pane is a starting point for managing your data source connections and the objects related to them.


Elements of Project Workspaces

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Project workspaces can contain the following:

Project | A set of zero or more source files, with one or more configurations. A project also specifies the type of application to build. Your project workspace can contain any number of projects, including subprojects.
Configuration | The settings for a project that specify a platform on which the output file is to run, and the tool settings with which to build the output. You can add any number of configurations to a project. By default, when you create a new project, you create Debug and Release configurations.

Within a project workspace, projects can have the following relations:

Top-level project | A project that is not a dependency of any other project (not a subproject of any other project). A project workspace has at least one top-level project.
Subproject | A project that has a dependency relationship with another project. The build system determines if it needs to build the subproject before it builds the containing project. Any project can be a subproject of any other project.

What do you want to know more about?

Project workspace files

Project types

Subprojects

Project configurations


Project Types

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Each project has a project type, which you choose when you create the project. The project type specifies what to generate and also specifies some default settings required in order to build that output type. It specifies, for instance, the settings that the compiler uses for the source files, the libraries that the linker uses to build each project configuration, the default locations for output files, the defined constants, and so on.

Visual Fortran project types are described in the Visual Fortran Programmer's Guide, in the section on Building Programs and Libraries. Visual Fortran project types include:

  • Fortran Console, Fortran Standard Graphics, Fortran QuickWin, and Fortran Windows applications

  • Fortran Static and Fortran Dynamic-Link libraries


Subprojects

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You create a subproject when you want to establish a dependency relationship between projects. When building a project that contains a subproject, the subproject is built first. If the subproject does not build, the containing project will not build.

For example, you might create an executable program that depends on a static library. If the static library is a subproject of the project that builds the executable program, then the library will be updated before the executable program is built.

You can either create a new project and give it a subproject relationship, or you can choose an existing project and give it a subproject relationship.

What do you want to do?

Create, include, or remove a subproject


Project Configurations

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Projects are controlled by their configuration settings. Specifying settings at the overall project configuration level is sufficient for most projects. But if you prefer, you can specify different settings within a project configuration for various files.

Project configurations have a hierarchical structure of settings. The settings specified at the project configuration level apply to all files within the configuration. However, you can also specify settings for individual files or a folder of files if you need to compile files with settings different from the general configuration settings. For instance, if you specify Default optimizations for a configuration, all files contained within the configuration use Default optimizations. You can, however, specify specific optimization settings — or the setting for no optimizations at all — for any individual files in the configuration.

Important The settings that you specify at the file level override options set at the configuration level.

You can specify some types of settings, such as linking, only at the project configuration level.

You can specify settings at the following levels within a project configuration:

  • Project configuration level. Settings specified at this level apply to all actions. Any settings specified for the project configuration apply to every file in the project unless overridden at the file level.

  • File level. Settings specified at this level apply to file-level actions, such as compiling. Any settings specified for the file apply only to that file and override any settings specified at the project configuration level.

What do you want to know more about?

Building the project configuration

Platform types

What do you want to do?

Specify project configuration settings

Specify file settings


About Building a Project Configuration

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can build or rebuild the program or library that a project configuration defines. When you build a project configuration, the Visual C++ development environment processes only the files in the project that have changed since the last build. When you rebuild a project configuration, the visual development environment processes all the files in the project. You can either choose to build a single project configuration or the default project configuration, or you can choose multiple configurations to build in one operation.

When you create a project, the visual development environment sets default options for both Debug and Release configurations. The Debug configuration contains full symbolic debugging information that can be used by the integrated debugger in the visual development environment or by other debuggers that use the Microsoft debug format. Optimizations are turned off in the Debug configuration because they generally make debugging more difficult. The Release configuration does not contain any symbolic debugging information, and it uses any optimizations that you have set after creating the projects. Depending on your installation and the choices you made when you created your project, you may have other default project configurations with other options, or you may have specifically created other project configurations with other options. Each project configuration also specifies the directories in which the intermediate and final files are created.

What do you want to do?

Create or delete project configurations within a project

Set the active project configuration


Platform Types

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

The platform type for a project configuration specifies the operating environment. The platform type specifies default settings required by a given platform, such as settings that the compiler uses for the source files, the default locations for output files, and so on. It also specifies the tools required to build the final output files for that platform.


Customizing a Build Process

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can specify custom build rules for use with any project or with any individual files that do not already have a rule associated with them. These rules then process the files at the appropriate point in the build if the output file is out of date with respect to the input file.

For example, you can add an .l file to your project, specify a lexical analyzer to process the file and produce a .y output file, and then specify a parser generator to process that file to create a source-code file. You could also select the output file for a configuration, to copy it to a specific directory for testing. Microsoft Visual C++ provides a number of macros for use in these commands.

Note By default, a number of file types have tools associated with them, such as .f90, .for. and .f in Visual Fortran and .c or .cpp files in Visual C++. To specify a custom rule for these files, you must select the Always use custom build step check box on the General tab of the Project Settings dialog box.

The custom rules run only on files in builds of the configurations in which you selected the files. That is, if your file set includes an .l file, and you select it only in one configuration, the rules that you specify run only in that configuration.

For example, assume that you want to include in your project a file named MYLEXINF.L. You first want a lexical analyzer to process MYLEXINF.L to produce a .C file with the same base name (MYLEXINF.C). First, you add MYLEXINF.L and MYLEXINF.C to your project using the Files into Project command on the Insert menu. (If you have not already created a version of MYLEXINF.C, Microsoft Visual C++ recognizes that and asks if you want to add a reference to the file anyway.) You then click the Settings command on the Project menu, and select MYLEXINF.L in the appropriate configuration. Next, select the Custom Build tab, and type commands similar to the following in the Build Command(s) list:

lexer $(InputPath) $(ProjDir)\$(InputName).c

This puts the lexical analyzer source MYLEXINF.C, in the project directory.

In the Output File(s) list, type $(ProjDir)\$(InputName).C. When you build this project, the build system checks the date of MYLEXINF.C. If its date is earlier than MYLEXINF.L, the build system runs these custom commands to rebuild MYLEXINF.C.

What do you want to know more about?

When custom build rules run

Macros for custom build commands

What do you want to do?

Specify custom build rules

Select the directories for the output files

Specify input dependencies

Specify build rules that run before the link process

Specify build rules that run after the build process


When Custom Build Rules Run

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Custom build rules run at different times, depending on whether they are specified on the Custom Build tab, the Pre-link step tab, or the Post-link step tab.

Rules entered on the Custom Build tab run only when any input file is out of date in relation to its output file, or if the output file doesn’t exist.

Per-file rules that you enter on the Custom Build tab run before the normal build-system tools (such as the compiler, the resource compiler, and so forth) are run.

Important Do not attach per-file rules to the output files of build-system tools, such as .obj, .res, or .tbl files. Such per-file rules may not run as expected.

Per-project rules that you enter on the Custom Build tab run after the normal build process finishes.

Rules that you enter on the Pre-link step tab run between compile and link time. No file timestamps are checked.

Rules that you enter on the Post-build step tab run after successful completion of the normal build process, including successful completion of rules entered on the Custom Build tab. No file timestamps are checked.

What do you want to do?

Specify build rules that run before the link process

Specify build rules that run after the build process


Macros for Custom Build Commands

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can use the File and Directory drop-down lists to insert any of the following directory and filename macros in either grid at the current insertion point location. The File and Directory drop-down lists are on the Custom Build tab of the Project Settings dialog box (the Settings command on the Build menu).

Label | Macro | Description
Intermediate | $(IntDir) | Path to the directory specified for intermediate files, relative to the project directory.
Output | $(OutDir) | Path to the directory specified for output files, relative to the project directory.
Target | $(TargetDir) | Fully qualified path to the directory specified to output files.
Input | $(InputDir) | Relative path to the project directory.
Project | $(ProjDir) | Fully qualified path to the project directory.
Workspace | $(WkspDir) | Fully qualified path to the project directory.
Microsoft Developer | $(MSDevDir) | Fully qualified path to the installation directory for Microsoft Visual C++.
Remote Target | $(RemoteDir) | Fully qualified path to the remote output file.
Target Path | $(TargetPath) | Fully qualified name for the project output file.
Target Name | $(TargetName) | Base name for the output file.
Input Path | $(InputPath) | Fully qualified name for the input file.
Input Name | $(InputName) | Base name for the input file.
Workspace Name | $(WkspName) | Name of the project workspace.
Remote Target Path | $(RemoteTargetPath) | Fully qualified name for the remote output file.

During a build, the input macros are set in turn to each file that you have selected for each configuration that you have selected, if you have made multiple selections.

What do you want to know more about?

Customizing a build process

What do you want to do?

Specify custom build tools


How Do I... Topics: Working With Projects and Workspaces

Overviews | How Do I... Topics | NMAKE Reference

A project workspace contains your projects and their configurations. A project is defined as a configuration and a group of files that produce a program or final binary file(s). A workspace can contain multiple projects, including sub- or dependent projects.

What do you want to do?

Work with the Project Workspace

Create a new project workspace

Display or hide the Project Workspace window

Open an existing project workspace

Unload a project from the workspace

Close a project workspace

Work with Projects

Set the active project

Insert or delete projects

Add or remove files from projects

Work with subprojects

Use project folders

Open a Makefile

Export a Makefile

Adjust the build settings

Work with project configurations

Build a project

Run a program


Creating a Project Workspace

Overviews | How Do I... Topics | NMAKE Reference

With the visual development environment, there are essentially two ways to create a new project workspace:

  • Use a New Project wizard to create the initial project. The visual development environment wizards automatically create a project workspace that includes starter files appropriate for the project type. For more information about each type of wizards available with the visual development environment, see the Visual Fortran Programmer's Guide.

  • Create a blank project workspace yourself. In this case, you must create all the files, select the project(s) to include in the project workspace, and select the files to add to the project.

    You must use this approach to create a workspace with a name or location different from the name and location for any of the projects it will contain. After you create the blank workspace, you can create a new project with a different location and insert it into the workspace at the same time.

To use a New Project wizard

  1. From the File menu, click New.

  2. In the New dialog box, click the Projects tab and select from the available project types to launch the wizard.

To create a blank project workspace

  1. On the File menu, click New.

  2. Click the Workspaces tab.

  3. Select Blank Workspace from the type list, and type a name in the Workspace Name box.

If necessary, specify the directory where the project workspace files are stored by using the Location box.


Viewing the Project Workspace Window

Overviews | How Do I... Topics | NMAKE Reference

In order to view or hide the workspace window, you must have a workspace loaded.

To display the Workspace window

  • On the View menu, click Workspace.

To hide the Project Workspace window

  1. Place the mouse cursor anywhere in the Project Workspace window and right-click to display the shortcut menu.

  2. On the shortcut menu, click Hide.

For more information about manipulating this docking window, see Working with Floating or Docking Windows.


Opening an Existing Project Workspace

Overviews | How Do I... Topics | NMAKE Reference

To open an existing project workspace

  1. On the File menu, click Open Workspace.

  2. Select the drive and directory containing the project workspace that you want to open.

  3. Select the .dsw file for the project workspace from the File Name list and click OK.

To reopen a recently used project workspace

  • On the File menu, click Recent Workspaces, and then click the name of the recently used workspace.

    -or-

    On the File menu, click the name of the workspace.

Note You can customize the menu items for recently used files and workspaces. You can specify how many items to list and whether these menu items are displayed on submenus or on the File menu itself. For more information, see Customizing Menu Items for Recently Used Files and Workspaces.

To close a project workspace

  • On the File menu, click Close Workspace.


Unloading a Project from the Workspace

Overviews | How Do I... Topics | NMAKE Reference

Unloading a project from the workspace can enable you to work more efficiently. For example, your workspace may contain multiple projects with multiple configurations. To reduce the time it takes to open and close the workspace, you can unload projects that you aren't currently working on.

Unloading a project does not delete it from the workspace. If a project is currently unloaded, it is simple to load it again.

To unload or load a project

  1. On the FileView tab of the Project Workspace, position the cursor over the project you wish to unload or load, and right-click the mouse button.

  2. From the shortcut menu, choose Unload Project or Load Project.

    When the project is unloaded, its icon changes to a folder and the words '– not loaded' appear next to it.


Setting the Active Project

The active project is the project that will be built when you use the Build or Rebuild All commands. It is also one of the determining factors in the building of dependent projects. For more information about dependent projects, see Creating, Including or Removing Subprojects.

To set the active project

  • On the Project menu, click Set Active Project and choose from the submenu of project names.

    -or-

  • On the Build toolbar, choose a project from the Select Active Project drop-down list. (To view the Build toolbar, right-click an empty part of the menu bar and check Build.)


Inserting and Deleting Projects

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can insert new or existing projects into your project workspace, and delete existing projects from the workspace. You can also delete specific configurations for a project without removing the entire project.

What do you want to do?

Insert a new project into an existing workspace

Add an existing project to the workspace

Delete a project from a workspace

Delete a project configuration

To insert a new project into an existing project workspace

  1. Open the project workspace to which you want to add a new project.

  2. On the File menu, click New and then click the Projects tab.

  3. Select the project type.

  4. Specify the Project Name and Location for the project.

  5. Click Add to Current Workspace.

  6. Select any of the available platforms for which you want to create initial Debug and Release configurations.

  7. Click OK.

The new project that you just created becomes the default project in the workspace.

To add an existing project to a project workspace

  1. Open the project workspace to which you want to add a project.

  2. On the Project menu, click Insert Project into Workspace.

  3. In the Insert Projects into Workspace dialog box, browse to locate the project you want to add. If the project is under source code control, use the Source Control button to locate and select the project file.

  4. If you want the project you are adding to be a subproject of another project, select the Dependency Of check box and select the name of the other project from the list in the Dependency Of box.

To delete a project from the workspace

  • From the FileView tab, select the project and press DELETE.

Note Deleting a project also removes it as a subproject from any other project in the workspace.

To delete a project configuration

  1. On the Build menu, click Configurations.

  2. In the Configurations box, expand the project that you want to delete.

  3. Select each configuration you want to delete, and click Remove.


Adding and Removing Files from Projects

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

When you add a file to a project, you add the file to all configurations for that project. For instance, if you have a project named MyProject, with Debug and Release configurations, adding a file adds it to both those project configurations.

If you add files from directories on a different drive than the project, the visual development environment uses absolute paths in the filenames for those files in the project's .dsp file. Because of the absolute paths, it is difficult to share the project (.dsp) file. Other developers in your group may have other drive names.

To support sharing files outside the project directory, you can use the Persist As field in the source file's property page. In the Persist As field, put in a replacement path for the file that will be persisted ("preserved") in the project file.

For example:

  1. Add a file, c:\basefiles\mybase.cpp, to your project, where your project is located at c:\myproject\project1.

  2. Use the Persist As field in either of two ways:
    • In the Persist As field, change the string "c:\basefiles\mybase.cpp" to "..\..\basefiles\mybase.cpp."

      This requires all users of the project to maintain the same directory structure that you use for the project.

    -or-

    • Define an environment variable, such as "BASEFILES," that contains "c:\basefiles" on the user's machine, and change the string in the Persist As field from "c:\basefiles\mybase.cpp" to "$(BASEFILES)\mybase.cpp."

Note: The NMAKE utility requires that you use upper case for the environment variable names.

What do you want to do?

Add files to a project

Move or copy files from one project to another

Remove files from a project

To add files to a project

  1. Open the project to which you want to add files.

  2. On the Project menu, click Add To Project, and then click Files.

  3. In the Files of type box, specify the type of files to add.

  4. Select one or more files.

  5. Click OK.

Note You can also use the shortcut menu from FileView to add files more quickly.

To move or copy files from one workspace to another

  1. From the FileView pane, select the files that you want to move or copy.

  2. On the Edit menu, click Cut if you want to move the files, or Copy if you want to copy the files.

  3. Close the current project workspace.

  4. Open the destination project workspace.

  5. Select the project to receive the files.

  6. On the Edit menu, click Paste.

To remove files from a project

  1. From the FileView pane, select the files that you want to remove.

  2. On the Edit menu, click Delete.


Creating, Including, or Removing Subprojects

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

A subproject is a project that has a dependency relationship with another project. Sometimes this dependency consists of shared files, that need to be built in the subproject first; or it may include shared resources that need updating in the subproject first. The dependency relationship is established by the configuration settings.

What do you want to do?

Create a new subproject

Insert a subproject

Remove a subproject

To create a new project as a subproject

  1. On the File menu, click New and then click the Projects tab.

  2. Select the type of project.

  3. Specify the Project Name and Location for the new project.

  4. Specify the Project Name and Location for the new project.

  5. Click Add to Current Workspace, click the Dependency of box, and then select the name of the project you want the new project to be a subproject of.

  6. Double-click the appropriate icon to create for your project type.

To include an existing project as a subproject

  1. Open the workspace that contains the project to which you want to add an existing project as a subproject.

  2. On the Project menu, click Insert Project into Workspace.

  3. Select the project file (.dsp) you want to insert as a subproject.

  4. Click the Dependency of box, and then select the project you want to create the subproject for from the drop-down list.

  5. Click OK.

To remove a subproject from a project

  • In the FileView pane, click the project and then select Delete on the Edit menu.


Using Folders in Projects

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Project files are organized into folders in the FileView pane of the Project Workspace. The visual development environment creates a folder for source files, header files and resource files, but you can reorganize these folders, or create new ones. You can use folders to organize explicitly logical clusters of files within the hierarchy of a project. For example, you could create folders to contain all your user interface source files, or specifications, documentation, or test suites. All file folder names should be unique.

The File Extensions field of the folder properties page is used when a new file is added to the project. If the file extension of the added file is listed in the folder's File Extensions field, the file is automatically added to the folder.

To add a folder

  1. On the Project menu, click Add To Project.

  2. Click New Folder.

  3. Enter the Name of the New Folder.

  4. Enter the File Extensions for the folder.

To rename a folder

  1. Right click on the folder you want to rename.

  2. Click Properties.

  3. On the General tab, type the new Folder Name.


Opening a Makefile

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Like any project, you can load a makefile (MAKEFILE, or filename.mak) into the Visual C++ environment project system either as a separate workspace, or as a project that is part of the current workspace. You can also simply add a makefile to a project. For example, you might want to run custom build rules on the makefile rather than building it separately.

To load the makefile as a project and create a project workspace for it

  • On the File menu, click Open.

    -or-

  • On the File menu, click Open Workspace.

To add the makefile as a project to the current workspace

  • On the Project menu, select the makefile project type, and click Insert Project into Workspace.

To add the makefile to an existing project

  • On the Project menu, click Add to Project, then click Files.

When you open a makefile as a project, the visual development environment does one of the following:

  • For makefiles that were created in the current version of the visual development environment, the visual development environment opens the associated workspace without any prompting.

  • For makefiles that were created in an earlier version of the visual development environment, a message box asks if you want to convert the project to the current format. If you click No, the visual development environment does not open the file. If you click Yes, the visual development environment upgrades the makefile project, adding it and any associated files to the workspace, or creating a new workspace.

  • For makefiles that were not created in the visual development environment, a message box asks if you want to create a project to wrap the makefile. If you click No, the visual development environment does not open the file. If you click Yes, the visual development environment creates a project workspace file, and other associated project files for the external makefile. The external makefile becomes a part of the project workspace.

What do you want to know more about?

Building a Project from the Command Line

What do you want to do?

Export a Makefile


Exporting a Makefile

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

If you want to use NMAKE to build a project, instead of building it from within the environment or by using command line tools, you can it export it as a makefile (ProjectName.mak). However, you no longer need to use NMAKE to build a visual development environment project from the command line. For more information, see Building a project from the command line.

Exporting a .mak file consists of two parts: creating the .mak file and creating or updating a corresponding .dep file. The first time you export a .mak file, visual development environment creates an NMAKE-style include file (Projectname.dep), which contains information about any included files required to build the project source files. Within the .mak file, the visual development environment adds an !include directive that references the projectname.dep file. Once this .dep file exists, you can specify whether or not you want the visual development environment to export the dependency information when it exports the .mak file.

You can greatly increase the speed of exporting .mak files by exporting dependency information only when you explicitly want to update the .dep file. You may not wish to update dependency information, for example, if only compiler switches have changed since the last time you built the project.

By default, the information written to the .dep file is applied to all build configurations. If there are significant differences in the dependencies between build configurations, for example, extra header files for a "Win32 Debug" configuration, you can specify that the dependency information be written on a per-configuration basis.

You may also wish to create and maintain the .dep files yourself. If so, you must follow the NMAKE naming convention (ProjectName.dep) or your project will not build.

Here is an example .dep file for MyProject.mak:

FileName.cpp: MyDep1.h, MyDep2.h
FileName2.cpp: YourDep2.h

What do you want to do?

Export a makefile

Automatically export a makefile whenever a project is updated

Automatically write dependency information when exporting a makefile

Specify different dependency information for different configurations

To export a makefile

  1. From the Project menu, select Export Makefile.

  2. In the Export Makefile(s) dialog box, select the project(s) for which you want to create a .mak file.

    A separate .mak file is created for each project you select.

  3. If you want the visual development environment to update dependency information, check the Write dependencies when writing makefiles checkbox.

If you know that you want to automatically export the .mak file each time you update this project, use the following procedure.

To automatically export a makefile when the project is updated

  1. From the Tools menu, choose Options.

  2. On the Build tab, check the Export makefile when saving project file checkbox.

    Selecting this option increases the time it takes to save the project.

To automatically write dependency information every time you export a makefile

  1. From the Tools menu, choose Options.

  2. On the Build tab, check the Always write dependencies when writing makefiles checkbox.

    Selecting this option considerably increases the time it takes to write the .mak file.

To specify per-configuration dependency information

  1. From the Project menu, choose Settings.

  2. On the General tab, check the Allow per-configuration dependencies checkbox.

    Selecting this option increases the time it takes to write the dependency information, according to the number of build configurations in the project.


Working with Project Configurations

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

There are several ways to build a project; you can build just the selected project, all the projects, or a specific project configuration.

What do you want to know more about?

Building the project configuration

Platform types

What do you want to do?

Create or delete configurations in a project

Set the active project configuration

Build the project


Creating and Deleting Configurations in a Project

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

A project configuration consists of settings that determine the characteristics of the final output file for a project. When you create a new project configuration for a project, it is based initially on the settings from an existing project configuration that you select. Options you select for the new configuration, such as the platform, may modify those initial settings. The new project configuration always uses the same set of files as the configuration on which it is based.

What do you want to do?

Create a project configuration

Prevent a file from being built in a configuration

Delete a configuration from a project

To create a project configuration

  1. On the Build menu, click Configurations.

  2. In the Configurations box, select the project to which you want to add a configuration, and click Add.

    You can also directly select the configuration on which you want to base the new configuration, for example, Win32 Debug.

  3. In the Add Project Configuration dialog box, type a unique name for the new configuration.

  4. On the Copy Settings From drop-down list, select the configuration from which the new configuration copies its initial settings.

  5. On the Platform drop-down list, select a platform for the new configuration.

    You can select the same platform as the project on which you are basing the new one if you want merely a variation of the existing settings.

  6. Click OK and then Close.

To prevent a file or files from being built in a configuration

  1. On the Project menu, click Settings, and then select the General tab.

  2. In the pane beneath the Settings For drop-down control, select the file or files that you want to exclude from the build.

  3. Select the Exclude File from Build check box.

To delete a configuration from a project

  1. On the Build menu, click Configurations.

  2. In the Projects and Configurations area, expand the project from which you want to delete a configuration.

  3. Select the configuration that you want to remove and click Remove.

  4. Respond Yes to remove the configuration.


Setting the Active Project Configuration

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

When you set the active project configuration, subsequent build commands act on the active configuration and build its output.

To set the active project configuration

  • On the Build menu, select Set Active Configuration and click a project configuration.

    -or-

  • On the Build toolbar, choose a project configuration from the Select Active Configuration drop-down list. (To view the Build toolbar, right-click an empty part of the menu bar and check Build.)


Specifying Project Configuration Settings

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

The options chosen in the Project Settings dialog box can be applied to multiple projects, but apply only to the selected project configuration. For instance, you can specify settings for the Release configuration that do not apply to the Debug configuration. You can also specify that settings be applied to all current project configurations.

To specify project settings

  1. On the Project menu, click Settings.

  2. On the General tab, select the project or projects.

  3. In the Settings For pane, select the configuration, or select All Configurations.

  4. Click OK to save the settings.

    Note If you specify settings that are incompatible with the project type that you chose when you created your project, you may not get the results that you expect.


Specifying File Settings

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

In general, settings for a project configuration affect all files belonging to that project. However, for each individual file, you can specify settings that are different from, or additional to, the project configuration's settings. You can specify file settings for files within a specific project, or for files from multiple projects. Within the projects in your project workspace, you can select any combination of files.

Note You can also specify input dependencies on individual files as part of a custom build process. This ensures that custom build steps run in the order you need them to.

To set file options for a project or projects

  1. On the Project menu, click Settings and then select the General tab.

  2. Under the Settings For drop-down control, expand the project or projects that contain the files you wish to specify settings for.

  3. Select the files, and then, on any of the available tabs, select the options that you want to apply to these files.

    The available tabs depend on the files or configurations that you have selected. Only those tabs with settings common to the selections appear. Similarly, within each tab, only the settings common to all the files selected are available.

Note If you specify settings incompatible with the project type that you chose when you created your project, you may not get the result that you expect.


Adjusting the Build Settings

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Projects are controlled by their configuration settings. Subproject dependencies are described by the hierarchy in configuration settings. You can also set configurations for specific files within the project.

What do you want to know more about?

Project configurations

Subprojects

What do you want to do?

Specify project configuration settings

Specify file settings


Specifying Custom Build Rules

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

When creating a custom build rule using a custom batch file, prepend the batch file with "call" to insure that all custom build rules following that rule will be executed.

When custom build rules create or incorporate files that are foreign to the current project or require a dependency relationship, click Dependencies on the Custom Build tab to identify these dependencies.

To specify custom build rules

  1. In the Project Settings dialog box, use the Settings For pane to select the source files or output files from project configurations for which you want to specify a custom rule or rules.

    By default, a number of file types have rules associated with them, such as .c or .cpp files if Visual C++ is installed and .for and .f90 files in Visual Fortran. You cannot specify a custom rule for these files. If you select files of this type, the Custom Build tab becomes unavailable.

  2. Select the Custom Build tab.

    If you have made multiple selections, the Input File text specifies multiple selections.

  3. In the Description text box, type a description.

  4. In the Build Command(s) list, select the first line, and type the command that you want to run on the input file.

    If you type more than one command in the grid, the build process runs them in order, from top to bottom.

    Note The command must include all required options. You may want to use a directory macro to specify the location for the output file.

  5. In the Output File(s) list, select the first line, and type the name of an output file that is created by the build commands specified in the Build Commands grid.

    If the commands create more than one output file, type additional names in the subsequent lines of the grid.

What do you want to know more about?

Customizing a build process

Macros for custom build commands

What do you want to do?

Select the directories for the output files

Specify Input dependencies

Specify build rules that run before the link process

Specify build rules that run after the build process


Selecting the Directories for Output Files

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can select the directories in which to put the intermediate and final output files for each project configuration. By putting these files in different directories, you can maintain copies of the same files built in different ways — for instance, the Debug and the Release versions of your project.

To select output directories

  1. On the Project menu, click Settings, and select the General tab.

  2. In the Settings For pane, select the item for which you want to set directories.

    If you select the project configuration, you can set both intermediate and output directories; if you select a file, you can set only the intermediate directory.

  3. In the Intermediate Files text box, type the directory name for the intermediate files (.obj files, for instance).

  4. If you are setting directories for the project level, type the directory name for the final output files (.exe files or .lib, for instance) in the Output Files text box.


Specifying Input Dependencies

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Specifying input dependencies on a per-file basis is a way to ensure that your build steps run in the order you need them to. For example, you may have a custom build step that creates an output file, MyOutput.h. Another file in the project, MyInput.cpp, may have a build rule that depends on MyOutput.h. You can specify MyOutput.h as an input dependency to MyInput.cpp, and the build system will first ensure that MyOutput.h exists and is up-to-date before running the custom build steps for MyInput.cpp.

You can specify input dependencies to a file even if the build process doesn't recognize the extension of either the input file or the dependent file.

To specify input dependencies

  1. On the Project menu, click Settings.

  2. Specify the project configuration and select the file for which you want to specify input dependencies.

  3. Select the Custom Build tab.

    Note If the file type is one that is already handled by the build system (such as .cpp, rc., .idl) you need to check the Always use custom build step option on the General tab in order for the Custom Build tab to appear.

  4. Click the Dependencies button.

  5. Type all of the input files into the User-defined dependencies dialog box.


Specifying Build Rules that Run Before the Link Process

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can use the Pre-link step tab in the Project Settings dialog box to specify build rules that run before the link process. For example, you could create directories or set file attributes before the linker runs.

To specify pre-link steps

  1. From the FileView tab of the project workspace, select the project for which you want to specify the build steps.

  2. From the Project menu, choose Settings, and select the Pre-link step tab.

  3. In the Pre-link description field, type a description of this step. The description you type here is echoed to the output window when this step is executed.

  4. Use the Pre-link command(s): area to type your operating-system batch file commands, environment variables, and build-rule macros.

What do you want to know more about?

When custom build rules run


Specifying Build Rules that Run After the Build Process

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can use the Post-build step tab to specify build rules that run after the build process is finished. These rules will run after any steps specified on other build rule tabs. You can also use this tab to perform steps that do not necessarily run on specific files, for example to copy an output file to a drop point, generate an e-mail message reporting that the build has finished, or run a process that doesn't create an output file.

To specify post-build steps

  1. From the FileView tab of the project workspace, select the project for which you want to specify the build steps.

  2. From the Project menu, choose Settings, and select the Post-build step tab.

  3. In the Post-build description field, type a description of this step. The description you type here is echoed to the output window when this step is executed.

  4. Use the Post-build command(s): area to type your operating-system batch file commands, environment variables and build-rule macros.

What do you want to know more about?

When custom build rules run


Building a Project

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can build all project configurations or selected configurations only. You can also build a single file. If your build output files become cumbersome or take up too much disk space, you can "clean" the project directories.

What do you want to do?

Build the active project configuration

Build multiple project configurations

Build the selected project only

Clean the project directories

Build a project from the command line

Build a single file without a project workspace

Compile a file

Run a program


Building the Active Project Configuration

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can choose the project configuration that is built by default. This configuration is called the active project configuration.

What do you want to do?

Set the active project configuration

Build the active project configuration

Rebuild the active project configuration

Stop a build

To set the active project configuration

  • On the Build menu, select Set Active Configuration and click a project configuration.

To build the active project configuration

  • On the Build menu, click Build project, where project represents the program or library defined by the project configuration.

To rebuild the active project configuration

  • On the Build menu, click Rebuild All.

Note Information about the build is displayed in the Output window. The Output window displays information from the build tools and lists any errors or warnings that occur during the build. If no errors are reported, the build completed successfully. If errors are reported, you need to debug them.

To stop a build

  • On the Build menu, click Stop Build.

Notes The Visual development environment stops the currently executing rule if possible; otherwise, it stops the build as soon as the currently executing rule finishes.

Since builds occur in the background, you can continue to use the Visual development environment during a build. However, some menu commands and toolbar buttons are disabled during a build. You can use the tabs at the bottom of the Output window to view the previous output from another rule while you are running the current build, and then click the Build tab to return to the current build output.

The Visual development environment notifies you with a beep when the build is complete. If you have a sound card installed, you can use the Sound program in the Windows Control Panel to assign the three standard system events listed below to different sounds.

System Event | Indicates
Asterisk ( * ) | Build has completed without errors or warnings.
Question ( ? ) | Build has completed with warnings.
Exclamation ( ! ) | Build has completed with errors.


Building Multiple Project Configurations

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

Any project workspace can have more than one project configuration. Instead of selecting each project configuration in turn and building it as the active configuration using the Build project command on the Build menu, you can select multiple project configurations and build them all.

What do you want to do?

Build multiple project configurations

Stop building multiple projects

To build multiple project configurations

  1. On the Build menu, click Batch Build.

  2. If you don't want to build certain project configurations, clear the check boxes in the Project Configurations list.

  3. Click Build to build only those intermediate files of each project configuration that are out of date, or the Rebuild All button to build all intermediate files for each project configuration.

Note The results for each project configuration are separated in the Output window by a line containing the name of the project configuration being built.

To stop building multiple projects

  • On the Build menu, click Stop Build.

The Visual development environment stops the currently executing rule if possible; otherwise, it stops the build as soon as the currently executing rule finishes. The build of the project configuration currently in progress ends. A message box appears, asking if you wish to continue building the remaining project configurations. If you click Yes, then the batch build continues from the next configuration in the list. If you click No, then the entire batch build is stopped.


Building the Selected Project

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

The Visual development environment can build projects in a hierarchy or just the selected project. The selected project includes all of its subprojects, built recursively. If just a subproject is selected, that subproject and all of its subprojects (if any) are built.

To build all the projects in the workspace

  • Select Build from the Build menu.

To build only the selected project

  1. From the FileView pane, highlight the project.

  2. Click the right mouse button to invoke the shortcut menu, and select Build (selection only).


Cleaning Project Directories

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

When you run the Clean command, the Visual development environment deletes all intermediate files created during the build process, for example .obj and .pch files, as well as output files such as the .exe or .dll file. The location of these files corresponds to the location specified on the General tab of the Project Settings dialog box, under "Intermediate files" and "Output files".

To clean the active project

  • From the Build menu, choose Clean.

To clean a specific project

  1. From the FileView tab, select the project and click the right mouse button.

  2. From the shortcut menu, choose Clean (selection only).

  3. Cleaning a project also deletes files created as a result of running custom build rules.


Building a Project from the Command Line

You can build a Visual development environment project from the command line without first exporting a makefile (MAKEFILE, or filename.mak) and using the NMAKE utility. Visual Fortran provides the dfdev command; the equivalent command when Visual C++ is installed is msdev.

The basic command syntax is

dfdev FileName [/MAKE "ProjectName – ConfigName | ALL"] [/REBUILD /CLEAN /NORECURSE /OUT LogFile /USEENV]

where FileName is the name of your project (.dsp) or workspace (.dsw) file.

For example, the following syntax deletes all intermediate files and then builds a project called MyProject:

dfdev MyProject.dsp /MAKE "MyProject – Win32 Debug" /REBUILD

The following syntax builds a workspace that contains (at least) two projects, building the release configuration of MyProject1 and all configurations of MyProject2, and directing the build output to a file called MyWorkspace.log:

dfdev MyWorkspace.dsw /MAKE "MyProject1 – Win32 Release" "MyProject2 – ALL" /OUT MyWorkspace.log

Note Projects created in Visual C++ or Visual Fortran versions earlier than 5.0 must first be converted before you can build them from the command line. To convert a project, open it inside the development environment.

You can also build all configurations of a certain type within a single project, for example, if you have defined multiple types of Debug configurations. For more information, see "Building by Type of Configuration."

Tip Type dfdev /? /OUT FileName to pipe the command syntax to a file.

The /MAKE Option

The /REBUILD, /CLEAN and /NORECURSE options all modify the /MAKE option, and are meaningless without it. Also, unless you specify a FileName after msdev, any /MAKE options will be ignored. /MAKE requires at least one configuration.

Parameters

Parameter | Description
FileName | A valid workspace or project filename. Must have an extension of .dsp or .dsw.
ProjectName | The project that contains the configurations you want to build. If Filename is a workspace file, ProjectName must be a part of that workspace.
ConfigName | Any valid project configuration, or all configurations for a particular project. To build all configurations, simply type "ALL" for the configuration value (must be uppercase). Corresponds to the choices available from the Settings For drop-down list in the Project Settings dialog box.
LogFile | Name of an optional file used to store the build output information (valid only with the /OUT option).

Options

Option | Operation
/MAKE "projectname1 – configuration1 | projectname1 – configuration2 | projectname2 – configuration1 | ALL" | Builds the specified configurations. The /CLEAN option modifies /MAKE so that the specified configurations are cleaned rather than built.
/? | Displays usage information for the msdev command.
/CLEAN | Deletes intermediate files created during the build process for the specified configuration(s); does not build the project configuration(s).
/REBUILD | Cleans and builds the specified configuration(s), including all dependent projects. Takes precedence if both /CLEAN and /REBUILD are specified.
/NORECURSE | Builds the specified project configuration(s) without building any dependent projects.
/OUT logfile | Creates a log file for the build output, which includes such information as syntax errors and warnings. If you don't specify a filename, the build output information is displayed at the command prompt and is not saved to a file.
/USEENV | Directs the build system to use environment variables for the current build session, rather than the directory settings specified on the Directories tab (Tools menu, Options command). The PATH, INCLUDE and LIB paths must be set correctly for the build to succeed when /USEENV is specified.
/EX MacroName | Invokes the named macro (if the associated .dsm file is not loaded, this command will fail).

Tip Type msdev /USEENV at the command line to launch the Visual development environment and use the environment variables for the duration of that IDE session.

Building by Type of Configuration

For any single project, you can build all configurations of a certain type. The build system uses limited pattern matching to recognize the name of the configuration you specify.

For example, if your project contains Debug and Release configurations for both regular and UNICODE applications, you can build both configurations for only the UNICODE application by issuing the following command:

dfdev MyProject.dsp /MAKE "MyProject – UNICODE"

Or, if your project contains several types of Debug and Release configurations, you can build all of the Debug configurations:

dfdev MyProject.dsp /MAKE "MyProject – DEBUG"

This pattern matching gives you even more flexibility when customizing your batch builds.


Building a Single File Without a Project Workspace

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can create a single source file and then build a console program directly from that source file. This method is generally useful only for relatively simple programs.

To build a console program from a single source file

  1. Close any open project workspace.

  2. Create or open a source file in a text editor window.

  3. On the Build menu, click Build.

  4. In the message box, click Yes.

  5. If necessary, give the source file a new name, with an extension for a file that the Visual development environment can build, such as .CPP.

    If you don't use a valid file extension, the Visual development environment does not build anything because it cannot find a type of source file in the project to build.

  6. Click OK.

The Visual development environment creates a default project workspace using the base name of the source file as the base name for the project. It uses default settings for a console program for the project configuration and builds the program.


Compiling Files

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

You can select and compile files in any project in your project workspace.

To compile selected files

  1. Select the files in the FileView pane of the Project Workspace window.

  2. With the mouse pointer over the selection, click the right mouse button to display the shortcut menu, and click Compile.

  9. If the project file you are compiling is dependent on any other file, such as a precompiled header (.PCH) file, you should first ensure that the dependent file exists and is up to date before compiling this file.

Note If you have specified a custom build rule (or rules) for a file, when you click Compile, the Visual development environment runs that rule with the file as input, and produces the output specified.


Running a Program

Home Page (Projects) | Overviews | How Do I... Topics | NMAKE Reference

When you have completed building a project configuration, you can start the program from the Visual development environment. You can also run programs in the integrated debugger.

To run an executable program

  • On the Build menu, click Execute.

To run an program in the integrated debugger

  • On the Build menu, click Start Debug, and from the cascading menu, click Go, Step Into, or if you have a source file open and it has the focus, Run to Cursor.


Overview: NMAKE Reference

The Microsoft Program Maintenance Utility (NMAKE.EXE) is a 32-bit tool that builds projects based on commands contained in a description file.

What do you want to know more about?

Running NMAKE

Contents of a Makefile

Description blocks

Commands in a Makefile

Macros and NMAKE

Inference rules

Dot directives

Makefile preprocessing

Related Home Pages

Working with Projects Home Page

Debugger Home Page

Build Information for Visual C++

More information for NMake


Running NMAKE

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

The syntax for NMAKE is:

NMAKE [option...] [macros...] [targets...] [@commandfile...]

NMAKE builds only specified targets or, if none is specified, the first target in the makefile. The first makefile target can be a pseudotarget that builds other targets. NMAKE uses makefiles specified with /F; if /F is not specified, it uses the Makefile file in the current directory. If no makefile is specified, it uses inference rules to build command-line targets.

The commandfile text file contains command-line input. Other input can precede or follow @commandfile. A path is permitted. In commandfile, line breaks are treated as spaces. Enclose macro definitions in quotation marks if they contain spaces.

What do you want to know more about?

NMAKE options

Tools.ini and NMAKE

Exit codes from NMAKE


NMAKE Options

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE options are described in the following table. Options are preceded by either a slash (/) or a dash (–) and are not case sensitive. Use !CMDSWITCHES to change option settings in a makefile or in Tools.ini.

Option | Action
/A | Forces build of all evaluated targets, even if not out-of-date with respect to dependents. Does not force build of unrelated targets.
/B | Forces build even if timestamps are equal. Recommended only for very fast systems (resolution of two seconds or less).
/C | Suppresses default output, including nonfatal NMAKE errors or warnings, timestamps, and NMAKE copyright message. Suppresses warnings issued by /K.
/D | Displays timestamps of each evaluated target and dependent and a message when a target does not exist. Useful with /P for debugging a makefile. Use !CMDSWITCHES to set or clear /D for part of a makefile.
/E | Causes environment variables to override makefile macro definitions.
/F filename | Specifies filename as a makefile. Spaces or tabs can precede filename. Specify /F once for each makefile. To supply a makefile from standard input, specify a dash (–) for filename, and end keyboard input with either F6 or CTRL+Z.
/HELP, /? | Displays a brief summary of NMAKE command-line syntax.
/I | Ignores exit codes from all commands. To set or clear /I for part of a makefile, use !CMDSWITCHES. To ignore exit codes for part of a makefile, use a dash (–) command modifier or .IGNORE. Overrides /K if both are specified.
/K | Continues building unrelated dependencies, if a command returns an error. Also issues a warning and returns an exit code of 1. By default, NMAKE halts if any command returns a nonzero exit code. Warnings from /K are suppressed by /C; /I overrides /K if both are specified.
/N | Displays but does not execute commands; preprocessing commands are executed. Does not display commands in recursive NMAKE calls. Useful for debugging makefiles and checking timestamps. To set or clear /N for part of a makefile, use !CMDSWITCHES.
/NOLOGO | Suppresses the NMAKE copyright message.
/P | Displays information (macro definitions, inference rules, targets, .SUFFIXES list) to standard output, and then runs the build. If no makefile or command-line target exists, it displays information only. Use with /D to debug a makefile.
/Q | Checks timestamps of targets; does not run the build. Returns a zero exit code if all targets are up-to-date and a nonzero exit code if any target is not. Preprocessing commands are executed. Useful when running NMAKE from a batch file.
/R | Clears the .SUFFIXES list and ignores inference rules and macros that are defined in the Tools.ini file or that are predefined.
/S | Suppresses display of executed commands. To suppress display in part of a makefile, use the @ command modifier or .SILENT. To set or clear /S for part of a makefile, use !CMDSWITCHES.
/T | Updates timestamps of command-line targets (or first makefile target) and executes preprocessing commands but does not run the build.
/U | Must be used in conjunction with /N. Dumps inline NMAKE files so that the /N output can be used as a batch file.
/X filename | Sends NMAKE error output to filename instead of standard error. Spaces or tabs can precede filename. To send error output to standard output, specify a dash (–) for filename. Does not affect output from commands to standard error.
/Y | Disables batch-mode inference rules. When this option is selected, all batch-mode inference rules are treated as regular inference rules.


Tools.ini and NMAKE

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE reads Tools.ini before it reads makefiles, unless /R is used. It looks for Tools.ini first in the current directory and then in the directory specified by the INIT environment variable. The section for NMAKE settings in the initialization file begins with [NMAKE] and can contain any makefile information. Specify a comment on a separate line beginning with a number sign (#).


Exit Codes from NMAKE

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE returns the following exit codes:

Code | Meaning
0 | No error (possibly a warning)
1 | Incomplete build (issued only when /K is used)
2 | Program error, possibly due to one of the following:
  • A syntax error in the makefile
  • An error or exit code from a command
  • An interruption by the user
4 | System error — out of memory
255 | Target is not up-to-date (issued only when /Q is used)


Contents of a Makefile

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

A makefile contains:

  • Description blocks

  • Commands

  • Macros

  • Inference rules

  • Dot directives

  • Preprocessing directives

Other features you can use in a makefile are wildcards, long filenames, comments, and special characters.


Wildcards and NMAKE

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE expands filename wildcards (* and ?) in dependency lines. A wildcard specified in a command is passed to the command; NMAKE does not expand it.


Long Filenames in a Makefile

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Enclose long filenames in double quotation marks, as follows:

all : "VeryLongFileName.exe"


Comments in a Makefile

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Precede a comment with a number sign (#). NMAKE ignores text from the number sign to the next newline character. Examples:

# Comment on line by itself
OPTIONS = /MAP  # Comment on macro definition line

all.exe : one.obj two.obj  # Comment on dependency line
    link one.obj two.obj
# Comment in commands block
#   copy *.obj \objects  # Command turned into comment
    copy one.exe \release

.obj.exe:  # Comment on inference rule line
    link $<

my.exe : my.obj ; link my.obj  # Err: cannot comment this
 # Error: # must be the first character
.obj.exe: ; link $<  # Error: cannot comment this

To specify a literal number sign, precede it with a caret (^), as follows:

DEF = ^#define  #Macro for a C preprocessing directive


Special Characters in a Makefile

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

To use an NMAKE special character as a literal character, place a caret (^) in front of it. NMAKE ignores carets that precede other characters. The special characters are:

:  ;  #  (  )  $  ^  \  {  }  !  @  —

A caret (^) within a quoted string is treated as a literal caret character. A caret at the end of a line inserts a literal newline character in a string or macro.

In macros, a backslash (\) followed by a newline character is replaced by a space.

In commands, a percent symbol (%) is a file specifier. To represent % literally in a command, specify a double percent sign (%%) in place of a single one. In other situations, NMAKE interprets a single % literally, but it always interprets a double %% as a single %. Therefore, to represent a literal %%, specify either three percent signs, %%%, or four percent signs, %%%%.

To use the dollar sign ($) as a literal character in a command, specify two dollar signs ($$). This method can also be used in other situations where ^$ works.


Description Blocks

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

A description block is a dependency line optionally followed by a commands block:

targets... : dependents...
    commands...

A dependency line specifies one or more targets and zero or more dependents. A target must be at the start of the line. Separate targets from dependents by a colon (:); spaces or tabs are allowed. To split the line, use a backslash (\ ) after a target or dependent. If a target does not exist, has an earlier timestamp than a dependent, or is a pseudotarget, NMAKE executes the commands. If a dependent is a target elsewhere and does not exist or is out-of-date with respect to its own dependents, NMAKE updates the dependent before updating the current dependency.

What do you want to know more about?

Targets

Dependents


Targets

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

In a dependency line, specify one or more targets, using any valid filename, directory name, or pseudotarget. Separate multiple targets with one or more spaces or tabs. Targets are not case sensitive. Paths are permitted with filenames. A target cannot exceed 256 characters. If the target preceding the colon is a single character, use a separating space; otherwise, NMAKE interprets the letter-colon combination as a drive specifier.

What do you want to know more about?

Pseudotargets

Multiple targets

Cumulative dependencies

Targets in multiple description blocks

Dependency side effects


Pseudotargets

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

A pseudotarget is a label used in place of a filename in a dependency line. It is interpreted as a file that does not exist, and so is out-of-date. NMAKE assumes a pseudotarget's timestamp is the most recent of all its dependents. If it has no dependents, the current time is assumed. If a pseudotarget is used as a target, its commands are always executed. A pseudotarget used as a dependent must also appear as a target in another dependency. However, that dependency does not need to have a commands block.

Pseudotarget names follow the filename syntax rules for targets. However, if the name does not have an extension (that is, does not contain a period), it can exceed the 8-character limit for filenames and can be up to 256 characters long.


Multiple Targets

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE evaluates multiple targets in a single dependency as if each were specified in a separate description block.

This... ...is evaluated as this
bounce.exe leap.exe :
jump.obj
   echo Building...

bounce.exe : jump.obj
   echo Building...
leap.exe : jump.obj
   echo Building...


Cumulative Dependencies

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Dependencies are cumulative in a description block if a target is repeated.

This... ...is evaluated as this
bounce.exe : jump.obj
bounce.exe : up.obj
   echo Building
bounce.exe...

bounce.exe : jump.obj
up.obj
   echo Building
bounce.exe...

Multiple targets in multiple dependency lines in a single description block are evaluated as if each were specified in a separate description block, but targets that are not in the last dependency line do not use the commands block.

This... ...is evaluated as this
bounce.exe leap.exe :
jump.obj
bounce.exe climb.exe :
up.obj
   echo Building...

bounce.exe : jump.obj
up.obj
   echo Building
bounce.exe...
climb.exe : up.obj
   echo Building
climb.exe...
leap.exe : jump.obj
# invokes an inference rule


Targets in Multiple Description Blocks

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

To update a target in more than one description block using different commands, specify two consecutive colons (::) between targets and dependents.

target.lib :: one.asm two.asm three.asm
    ml one.asm two.asm three.asm
    lib target one.obj two.obj three.obj
target.lib :: four.c five.c
    cl /c four.c five.c
    lib target four.obj five.obj


Dependency Side Effects

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

If a target is specified with a colon (:) in two dependency lines in different locations, and if commands appear after only one of the lines, NMAKE interprets the dependencies as if adjacent or combined. It does not invoke an inference rule for the dependency that has no commands, but instead assumes that the dependencies belong to one description block and executes the commands specified with the other dependency.

This... ...is evaluated as this
bounce.exe : jump.obj
   echo Building
bounce.exe...

bounce.exe : up.obj

bounce.exe : jump.obj
up.obj
   echo Building
bounce.exe...

This effect does not occur if a double colon (::) is used.

This... ...is evaluated as this
bounce.exe :: jump.obj
   echo Building
bounce.exe...

bounce.exe :: up.obj

bounce.exe : jump.obj
   echo Building
bounce.exe...

bounce.exe : up.obj
# invokes an inference rule


Dependents

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

In a dependency line, specify zero or more dependents after the colon (:) or double colon (::), using any valid filename or pseudotarget. Separate multiple dependents with one or more spaces or tabs. Dependents are not case sensitive. Paths are permitted with filenames.

What do you want to know more about?

Inferred dependents

Search paths for dependents


Inferred Dependents

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

An inferred dependent is derived from an inference rule and is evaluated before explicit dependents. If an inferred dependent is out-of-date with respect to its target, NMAKE invokes the commands block for the dependency. If an inferred dependent does not exist or is out-of-date with respect to its own dependents, NMAKE first updates the inferred dependent. For more information about inferred dependents, see Inference Rules.


Search Paths for Dependents

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Each dependent has an optional search path, specified as follows:

{directory[;directory...]}dependent

NMAKE looks for a dependent first in the current directory, and then in directories in the order specified. A macro can specify part or all of a search path. Enclose directory names in braces ({ }); separate multiple directories with a semicolon (;). No spaces or tabs are allowed.


Commands in a Makefile

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

A description block or inference rule specifies a block of commands to run if the dependency is out-of-date. NMAKE displays each command before running it, unless /S, .SILENT, !CMDSWITCHES, or @ is used. NMAKE looks for a matching inference rule if a description block is not followed by a commands block.

A commands block contains one or more commands, each on its own line. No blank line can appear between the dependency or rule and the commands block. However, a line containing only spaces or tabs can appear; this line is interpreted as a null command, and no error occurs. Blank lines are permitted between command lines.

A command line begins with one or more spaces or tabs. A backslash ( \ ) followed by a newline character is interpreted as a space in the command; use a backslash at the end of a line to continue a command onto the next line. NMAKE interprets the backslash literally if any other character, including a space or tab, follows the backslash.

A command preceded by a semicolon (;) can appear on a dependency line or inference rule, whether or not a commands block follows:

project.obj : project.c project.h ; cl /c project.c

What do you want to know more about?

Command modifiers

Filename-parts syntax

Inline files in a makefile


Command Modifiers

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

You can specify one or more command modifiers preceding a command, optionally separated by spaces or tabs. As with commands, modifiers must be indented.

Modifier | Action
@command | Prevents display of the command. Display by commands is not suppressed. By default, NMAKE echoes all executed commands. Use /S to suppress display for the entire makefile; use .SILENT to suppress display for part of the makefile.
–[number ]command | Turns off error checking for command. By default, NMAKE halts when a command returns a nonzero exit code. If –number is used, NMAKE stops if the exit code exceeds number. Spaces or tabs cannot appear between the dash and number. At least one space or tab must appear between number and command. Use /I to turn off error checking for the entire makefile; use .IGNORE to turn off error checking for part of the makefile.
!command | Executes command for each dependent file if command uses $** (all dependent files in the dependency) or $? (all dependent files in the dependency with a later timestamp than the target).


Filename-Parts Syntax

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Filename-parts syntax in commands represents components of the first dependent filename (which may be an implied dependent). Filename components are the file's drive, path, base name, and extension as specified, not as it exists on disk. Use %s to represent the complete filename. Use %|[parts]F (a vertical bar character follows the percent symbol) to represent parts of the filename, where parts can be zero or more of the following letters, in any order.

Letter | Description
No letter | Complete name (same as %s)
d | Drive
p | Path
f | File base name
e | File extension

For example, if the filename is c:\prog.exe:

%s will be c:\prog.exe

%:F will be c:\prog.exe

%:dF will be c

%:pF will be c:\

%:fF will be prog

%:eF will be exe


Inline Files in a Makefile

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

An inline file contains text you specify in the makefile. Its name can be used in commands as input (for example, a LINK command file), or it can pass commands to the operating system. The file is created on disk when a command that creates the file is run.

What do you want to know more about?

Specifying an inline file

Creating inline file text

Reusing inline files

Multiple inline files


Specifying an Inline File

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

The syntax for specifying an inline file in a command is:

<<[filename]

Specify two angle brackets (<<) in the command where filename is to appear. The angle brackets cannot be a macro expansion. When the command is run, the angle brackets are replaced by filename, if specified, or by a unique NMAKE-generated name. If specified, filename must follow angle brackets without a space or tab. A path is permitted. No extension is required or assumed. If filename is specified, the file is created in the current or specified directory, overwriting any existing file by that name; otherwise, it is created in the TMP directory (or the current directory, if the TMP environment variable is not defined). If a previous filename is reused, NMAKE replaces the previous file.


Creating Inline File Text

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

The syntax to create the content of an inline file is:

inlinetext
.
.
.
<<[KEEP | NOKEEP]

Specify inlinetext on the first line after the command. Mark the end with double angle brackets (<<) at the beginning of a separate line. The file contains all inlinetext before the delimiting brackets. The inlinetext can have macro expansions and substitutions, but not directives or makefile comments. Spaces, tabs, and newline characters are treated literally.

Inline files are temporary or permanent. A temporary file exists for the duration of the session and can be reused by other commands. Specify KEEP after the closing angle brackets to retain the file after the NMAKE session; an unnamed file is preserved on disk with the generated filename. Specify NOKEEP or nothing for a temporary file. KEEP and NOKEEP are not case sensitive.


Reusing Inline Files

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

To reuse an inline file, specify <<filename where the file is defined and first used, then reuse filename without << later in the same or another command. The command to create the inline file must run before all commands that use the file.


Multiple Inline Files

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

A command can create more than one inline file. The syntax is:

command << <<
inlinetext
<<[KEEP | NOKEEP]
inlinetext
<<[KEEP | NOKEEP]

For each file, specify one or more lines of inline text followed by a closing line containing the delimiter. Begin the second file's text on the line following the delimiting line for the first file.


Macros and NMAKE

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Macros replace a particular string in the makefile with another string. Using macros, you can:

  • Create a makefile that can build different projects.

  • Specify options for commands.

  • Set environment variables.

You can define your own macros or use NMAKE's predefined macros.

What do you want to know more about?

Defining an NMAKE macro

Using an NMAKE macro

Special NMAKE macros


Defining an NMAKE Macro

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Use this syntax to define a macro:

macroname=string

The macroname is a combination of letters, digits, and underscores (_) up to 1,024 characters, and is case sensitive. The macroname can contain an invoked macro. If macroname consists entirely of an invoked macro, the macro being invoked cannot be null or undefined.

The string can be any sequence of zero or more characters. A null string contains zero characters or only spaces or tabs. The string can contain a macro invocation.

What do you want to know more about?

Special characters in macros

Null and undefined macros

Where to define macros

Precedence in macro definitions


Special Characters in Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

A number sign (#) after a definition specifies a comment. To specify a literal number sign in a macro, use a caret (^), as in ^#.

A dollar sign ($) specifies a macro invocation. To specify a literal $, use $$.

To extend a definition to a new line, end the line with a backslash (\). When the macro is invoked, the backslash plus newline character is replaced with a space. To specify a literal backslash at the end of the line, precede it with a caret (^), or follow it with a comment specifier (#).

To specify a literal newline character, end the line with a caret (^), as in:

CMDS = cls^
dir


Null and Undefined Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Both null and undefined macros expand to null strings, but a macro defined as a null string is considered defined in preprocessing expressions. To define a macro as a null string, specify no characters except spaces or tabs after the equal sign (=) in a command line or command file, and enclose the null string or definition in double quotation marks (" "). To undefine a macro, use !UNDEF. For more information, see Makefile Preprocessing Directives.


Where to Define Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Define macros in a command line, command file, makefile, or the Tools.ini file.

In a makefile or the Tools.ini file, each macro definition must appear on a separate line and cannot start with a space or tab. Spaces or tabs around the equal sign are ignored. All string characters are literal, including surrounding quotation marks and embedded spaces.

In a command line or command file, spaces and tabs delimit arguments and cannot surround the equal sign. If string has embedded spaces or tabs, enclose either the string itself or the entire macro in double quotation marks (" ").


Precedence in Macro Definitions

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

If a macro has multiple definitions, NMAKE uses the highest-precedence definition. The following list shows the order of precedence, from highest to lowest:

  1. A macro defined on the command line

  2. A macro defined in a makefile or include file

  3. An inherited environment-variable macro

  4. A macro defined in the Tools.ini file

  5. A predefined macro, such as CC and AS

Use /E to cause macros inherited from environment variables to override makefile macros with the same name. Use !UNDEF to override a command line.


Using an NMAKE Macro

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

To use a macro, enclose its name in parentheses preceded by a dollar sign ($):

$(macroname)

No spaces are allowed. The parentheses are optional if macroname is a single character. The definition string replaces $(macroname); an undefined macro is replaced by a null string.

What do you want to know more about?

Macro substitution


Macro Substitution

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

To substitute text within a macro, use the following syntax:

$(macroname:string1=string2)

When macroname is invoked, each occurrence of string1 in its definition string is replaced by string2. Macro substitution is case sensitive and is literal; string1 and string2 cannot invoke macros. Substitution does not modify the original definition. You can substitute text in any predefined macro except $$@.

No spaces or tabs precede the colon; any after the colon are interpreted as literal. If string2 is null, all occurrences of string1 are deleted from the macro's definition string.


Special NMAKE Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE provides several special macros to represent various filenames and commands. One use for some of these macros is in the predefined inference rules. Like all macros, the macros provided by NMAKE are case sensitive.

  • Filename macros

  • Recursion macros

  • Command macros and options macros

  • Environment-Variable Macros


Filename Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Filename macros are predefined as filenames specified in the dependency (not full filename specifications on disk). These macros do not need to be enclosed in parentheses when invoked; specify only a $ as shown.

Macro | Meaning
$@ | Current target's full name (path, base name, extension), as currently specified.
$$@ | Current target's full name (path, base name, extension), as currently specified. Valid only as a dependent in a dependency.
$* | Current target's path and base name minus file extension.
$** | All dependents of the current target.
$? | All dependents with a later timestamp than the current target.
$< | Dependent file with a later timestamp than the current target. Valid only in commands in inference rules.

To specify part of a predefined filename macro, append a macro modifier and enclose the modified macro in parentheses.

Modifier | Resulting filename part
D | Drive plus directory
B | Base name
F | Base name plus extension
R | Drive plus directory plus base name


Recursion Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Use recursion macros to call NMAKE recursively. Recursive sessions inherit command-line and environment-variable macros and Tools.ini information. They do not inherit makefile-defined inference rules or .SUFFIXES and .PRECIOUS specifications. To pass macros to a recursive NMAKE session, either set an environment variable with SET before the recursive call, define a macro in the command for the recursive call, or define a macro in Tools.ini.

Macro | Definition
MAKE | Command used originally to invoke NMAKE.
MAKEDIR | Current directory when NMAKE was invoked.
MAKEFLAGS | Options currently in effect. Use as /$(MAKEFLAGS).


Command Macros and Options Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Command macros are predefined for Microsoft products. Options macros represent options to these products and are undefined by default. Both are used in predefined inference rules and can be used in description blocks or user-defined inference rules. Command macros can be redefined to represent part or all of a command line, including options. Options macros generate a null string if left undefined.

Microsoft product | Command macro | Defined as | Options macro
Macro Assembler | AS | ml | AFLAGS
Basic Compiler | BC | bc | BFLAGS
C Compiler | CC | cl | CFLAGS
COBOL Compiler | COBOL | cobol | COBFLAGS
C++ Compiler | CPP | cl | CPPFLAGS
C++ Compiler | CXX | cl | CXXFLAGS
FORTRAN Compiler | FOR | fl | FFLAGS
Pascal Compiler | PASCAL | pl | PFLAGS
Resource Compiler | RC | rc | RFLAGS


Environment-Variable Macros

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE inherits macro definitions for environment variables that exist before the start of the session. If a variable was set in the operating-system environment, it is available as an NMAKE macro. The inherited names are converted to uppercase. Inheritance occurs before preprocessing. Use the /E option to cause macros inherited from environment variables to override any macros with the same name in the makefile.

Environment-variable macros can be redefined in the session, and this changes the corresponding environment variable. You can also change environment variables with the SET command. Using the SET command to change an environment variable in a session does not change the corresponding macro, however.

For example:

PATH=$(PATH);\nonesuch

all:
    echo %PATH%

In this example, changing PATH changes the corresponding environment variable PATH; it appends \nonesuch to your path.

If an environment variable is defined as a string that would be syntactically incorrect in a makefile, no macro is created and no warning is generated. If a variable's value contains a dollar sign ($), NMAKE interprets it as the beginning of a macro invocation. Using the macro can cause unexpected behavior.


Inference Rules

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Inference rules supply commands to update targets and to infer dependents for targets. Extensions in an inference rule match a single target and dependent that have the same base name. Inference rules are user-defined or predefined; predefined rules can be redefined.

If an out-of-date dependency has no commands, and if .SUFFIXES contains the dependent's extension, NMAKE uses a rule whose extensions match the target and an existing file in the current or specified directory. If more than one rule matches existing files, the .SUFFIXES list determines which to use; list priority descends from left to right. If a dependent file does not exist and is not listed as a target in another description block, an inference rule can create the missing dependent from another file with the same base name. If a description block's target has no dependents or commands, an inference rule can update the target. Inference rules can build a command-line target even if no description block exists. NMAKE may invoke a rule for an inferred dependent even if an explicit dependent is specified.

What do you want to know more about?

Defining a rule

Batch-mode rules

Predefined rules

Inferred dependents and rules

Precedence in inference rules


Defining a Rule

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

To define an inference rule, use the following syntax:

.fromext.toext:
commands

The fromext represents the extension of a dependent file, and toext represents the extension of a target file. Extensions are not case sensitive. Macros can be invoked to represent fromext and toext; the macros are expanded during preprocessing. The period (.) preceding fromext must appear at the beginning of the line. The colon (:) is preceded by zero or more spaces or tabs. It can be followed only by spaces or tabs, a semicolon (;) to specify a command, a number sign (#) to specify a comment, or a newline character. No other spaces are allowed. Commands are specified as in description blocks.

What do you want to know more about?

Search paths in rules


Search Paths in Rules

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

An inference rule that specifies paths has the following syntax:

{frompath}.fromext{topath}.toext:
commands

An inference rule applies to a dependency only if paths specified in the dependency exactly match the inference-rule paths. Specify the dependent's directory in frompath and the target's directory in topath; no spaces are allowed. Specify only one path for each extension. A path on one extension requires a path on the other. To specify the current directory, use either a period (.) or empty braces ({ }). Macros can represent frompath and topath; they are invoked during preprocessing.


Batch-Mode Rules

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Batch-mode inference rules provide only one invocation of the inference rule when N commands go through this inference rule. Without batch-mode inference rules, it would require N commands to be invoked. N is the number of dependents that trigger the inference rule.

Makefiles that contain batch-mode inference rules must use NMAKE version 1.62 or higher. To check the NMAKE version, run the _NMAKE_VER macro available with NMAKE version 1.62 or higher. This macro returns an integer representing the NMAKE version. For example, the macro returns 162 for NMAKE version 1.62.

A batch-mode inference rule has the following syntax:

{frompath}.fromext{topath}.toext::
commands

The only syntactical difference from the standard inference rule is that the batch-mode inference rule is terminated with a double colon (::).

Note The tool being invoked must be able to handle multiple files. The batch-mode inference rule must use $< as the macro to access dependent files.

The batch-mode inference rules can speed up the build process. It is faster to supply files to the compiler in batch, because the compiler driver is invoked only once. For example, the C and C++ compiler performs better when handling a set of files because it can remain memory resident during the process.

The following example shows how to use batch-mode inference rules:

#
# sample makefile to illustrate batch-mode inference rules
#
O = .
S = .
Objs = $O/foo1.obj $O/foo2.obj $O/foo2.obj $O/foo3.obj $O/foo4.obj
CFLAGS = -nologo

all : $(Objs)

!ifdef NOBatch
{$S}.cpp{$O}.obj:
!else
{$S}.cpp{$O}.obj::
!endif
   $(CC) $(CFLAGS) -Fd$O\ -c $<

$(Objs) :

#end of makefile

NMAKE produces the following output without batch-mode inference rules:

E:\tmp> nmake -f test.mak -a NOBatch=1

Microsoft (R) Program Maintenance Utility   Version 1.62.6200
Copyright (C) Microsoft Corp 1988-1996. All rights reserved.

        cl -nologo -Fd.\ -c .\foo1.cpp
foo1.cpp
        cl -nologo -Fd.\ -c .\foo2.cpp
foo2.cpp
        cl -nologo -Fd.\ -c .\foo3.cpp
foo3.cpp
        cl -nologo -Fd.\ -c .\foo4.cpp
foo4.cpp

NMAKE produces the following result with the batch-mode inference rules:

E:\tmp> nmake -f test.mak -a

Microsoft (R) Program Maintenance Utility   Version 1.62.6200
Copyright (C) Microsoft Corp 1988-1996. All rights reserved.

        cl -nologo -Fd.\ -c .\foo1.cpp .\foo2.cpp .\foo3.cpp .\foo4.cpp
foo1.cpp
foo2.cpp
foo3.cpp
foo4.cpp
Generating Code...


Predefined Rules

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Predefined inference rules use NMAKE-supplied command and options macros.

Rule | Command | Default action
.asm.exe | $(AS) $(AFLAGS) $*.asm | ml $*.asm
.asm.obj | $(AS) $(AFLAGS) /c $*.asm | ml /c $*.asm
.c.exe | $(CC) $(CFLAGS) $*.c | cl $*.c
.c.obj | $(CC) $(CFLAGS) /c $*.c | cl /c $*.c
.cpp.exe | $(CPP) $(CPPFLAGS) $*.cpp | cl $*.cpp
.cpp.obj | $(CPP) $(CPPFLAGS) /c $*.cpp | cl /c $*.cpp
.cxx.exe | $(CXX) $(CXXFLAGS) $*.cxx | cl $*.cxx
.cxx.obj | $(CXX) $(CXXFLAGS) /c $*.cxx | cl /c $*.cxx
.bas.obj | $(BC) $(BFLAGS) $*.bas; | bc $*.bas;
.cbl.exe | $(COBOL) $(COBFLAGS) $*.cbl, $*.exe; | cobol $*.cbl, $*.exe;
.cbl.obj | $(COBOL) $(COBFLAGS) $*.cbl; | cobol $*.cbl;
.f.exe | $(FOR) $(FFLAGS) $*.f | fl $*.f
.f.obj | $(FOR) /c $(FFLAGS) $*.f | fl /c $*.f
.f90.exe | $(FOR) $(FFLAGS) $*.f90 | fl $*.f90
.f90.obj | $(FOR) /c $(FFLAGS) $*.f90 | fl /c $*.f90
.for.exe | $(FOR) $(FFLAGS) $*.for | fl $*.for
.for.obj | $(FOR) /c $(FFLAGS) $*.for | fl /c $*.for
.pas.exe | $(PASCAL) $(PFLAGS) $*.pas | pl $*.pas
.pas.obj | $(PASCAL) /c $(PFLAGS) $*.pas | pl /c $*.pas
.rc.res | $(RC) $(RFLAGS) /r $* | rc /r $*


Inferred Dependents and Rules

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

NMAKE assumes an inferred dependent for a target if an applicable inference rule exists. A rule applies if:

  • toext matches the target's extension.

  • fromext matches the extension of a file that has the target's base name and that exists in the current or specified directory.

  • fromext is in .SUFFIXES; no other fromext in a matching rule has a higher .SUFFIXES priority.

  • No explicit dependent has a higher .SUFFIXES priority.

Inferred dependents can cause unexpected side effects. If the target's description block contains commands, NMAKE executes those commands instead of the commands in the rule.


Precedence in Inference Rules

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

If an inference rule is multiply defined, NMAKE uses the highest-precedence definition. The following list shows the order of precedence from highest to lowest:

  1. An inference rule defined in a makefile; later definitions have precedence.

  2. An inference rule defined in Tools.ini; later definitions have precedence.

  3. A predefined inference rule.


Dot Directives

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Specify dot directives outside a description block, at the start of a line. Dot directives begin with a period ( . ) and are followed by a colon (:). Spaces and tabs are allowed. Dot directive names are case sensitive and are uppercase.

Directive | Action
.IGNORE : | Ignores nonzero exit codes returned by commands, from the place it is specified to the end of the makefile. By default, NMAKE halts if a command returns a nonzero exit code. To restore error checking, use !CMDSWITCHES. To ignore the exit code for a single command, use the dash (–) modifier. To ignore exit codes for an entire file, use /I.
.PRECIOUS : targets | Preserves targets on disk if the commands to update them are halted; has no effect if a command handles an interrupt by deleting the file. Separate the target names with one or more spaces or tabs. By default, NMAKE deletes a target if a build is interrupted by CTRL+C or CTRL+BREAK. Each use of .PRECIOUS applies to the entire makefile; multiple specifications are cumulative.
.SILENT : | Suppresses display of executed commands, from the place it is specified to the end of the makefile. By default, NMAKE displays the commands it invokes. To restore echoing, use !CMDSWITCHES. To suppress echoing of a single command, use the @ modifier. To suppress echoing for an entire file, use /S.
.SUFFIXES : list | Lists extensions for inference-rule matching; predefined as: .exe .obj .asm .c .cpp .cxx .bas .cbl .for .pas .res .rc

To change the .SUFFIXES list order or to specify a new list, clear the list and specify a new setting. To clear the list, specify no extensions after the colon:

.SUFFIXES :

To add additional suffixes to the end of the list, specify

.SUFFIXES : suffixlist

where suffixlist is a list of the additional suffixes, separated by one or more spaces or tabs. To see the current setting of .SUFFIXES, run NMAKE with /P.


Makefile Preprocessing

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

You can control the NMAKE session by using preprocessing directives and expressions. Preprocessing instructions can be placed in the makefile or in Tools.ini. Using directives, you can conditionally process your makefile, display error messages, include other makefiles, undefine a macro, and turn certain options on or off.

What do you want to know more about?

Makefile preprocessing directives

Expressions in makefile preprocessing


Makefile Preprocessing Directives

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

Preprocessing directives are not case sensitive. The initial exclamation point (!) must appear at the beginning of the line. Zero or more spaces or tabs can appear after the exclamation point, for indentation.

!CMDSWITCHES

{+| –}option... Turns each option listed on or off. Spaces or tabs must appear before the + or – operator; none can appear between the operator and the option letters. Letters are not case sensitive and are specified without a slash ( / ). To turn some options on and others off, use separate specifications of !CMDSWITCHES.

Only /D, /I, /N, and /S can be used in a makefile. In Tools.ini, all options are allowed except /F, /HELP, /NOLOGO, /X, and /?. Changes specified in a description block do not take effect until the next description block. This directive updates MAKEFLAGS; changes are inherited during recursion if MAKEFLAGS is specified.

!ERROR text

Displays text in error U1050, then halts NMAKE, even if /K, /I, .IGNORE, !CMDSWITCHES, or the dash (–) command modifier is used. Spaces or tabs before text are ignored.

!MESSAGE text

Displays text to standard output. Spaces or tabs before text are ignored.

!INCLUDE [<]filename[>]

Reads filename as a makefile, then continues with the current makefile. NMAKE searches for filename first in the specified or current directory, then recursively through directories of any parent makefiles, then, if filename is enclosed by angle brackets (< >), in directories specified by the INCLUDE macro, which is initially set to the INCLUDE environment variable. Useful to pass .SUFFIXES settings, .PRECIOUS, and inference rules to recursive makefiles.

!IF constantexpression

Processes statements between !IF and the next !ELSE or !ENDIF if constantexpression evaluates to a nonzero value.

!IFDEF macroname

Processes statements between !IFDEF and the next !ELSE or !ENDIF if macroname is defined. A null macro is considered to be defined.

!IFNDEF macroname

Processes statements between !IFNDEF and the next !ELSE or !ENDIF if macroname is not defined.

!ELSE[IF constantexpression |IFDEF macroname | IFNDEF macroname]

Processes statements between !ELSE and the next !ENDIF if the prior !IF, !IFDEF, or !IFNDEF statement evaluated to zero. The optional keywords give further control of preprocessing.

!ELSEIF

Synonym for !ELSE IF.

!ELSEIFDEF

Synonym for !ELSE IFDEF.

!ELSEIFNDEF

Synonym for !ELSE IFNDEF.

!ENDIF

Marks the end of an !IF, !IFDEF, or !IFNDEF block. Any text after !ENDIF on the same line is ignored.

!UNDEF macroname

Undefines macroname.


Expressions in Makefile Preprocessing

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

The !IF or !ELSE IF constantexpression consists of integer constants (in decimal or C-language notation), string constants, or commands. Use parentheses to group expressions. Expressions use C-style signed long integer arithmetic; numbers are in 32-bit two's-complement form in the range – 2147483648 to 2147483647.

Expressions can use operators that act on constant values, exit codes from commands, strings, macros, and file-system paths.

What do you want to know more about?

Makefile preprocessing operators

Executing a program in preprocessing


Makefile Preprocessing Operators

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

The DEFINED operator is a logical operator that acts on a macro name. The expression DEFINED (macroname) is true if macroname is defined. DEFINED in combination with !IF or !ELSE IF is equivalent to !IFDEF or !ELSE IFDEF. However, unlike these directives, DEFINED can be used in complex expressions using binary logical operators.

The EXIST operator is a logical operator that acts on a file-system path. EXIST (path) is true if path exists. The result from EXIST can be used in binary expressions. If path contains spaces, enclose it in double quotation marks.

Integer constants can use the unary operators for numerical negation (–), one's complement (~), and logical negation (!).

Constant expressions can use the following binary operators.

Operator | Description | Operator | Description
+ | Addition | || | Logical OR
– | Subtraction | << | Left shift
* | Multiplication | >> | Right shift
/ | Division | == | Equality
% | Modulus | != | Inequality
& | Bitwise AND | < | Less than
| | Bitwise OR | > | Greater than
^ | Bitwise XOR | <= | Less than or equal to
&& | Logical AND | >= | Greater than or equal to

To compare two strings, use the equality (==) operator and the inequality (!=) operator. Enclose strings in double quotation marks.


Executing a Program in Preprocessing

Home Page (Projects) | Overview (NMAKE Reference) | How Do I... Topics (Projects)

To use a command's exit code during preprocessing, specify the command, with any arguments, within brackets ([ ]). Any macros are expanded before the command is executed. NMAKE replaces the command specification with the command's exit code, which can be used in an expression to control preprocessing.


Home Page: Text Editor

The Visual C++ development environment includes an integrated Text editor to manage, edit, and print source files.

  • Overview

  • How Do I...Topics

  • Frequently Asked Questions

  • Reference

For information about the Text editor

  • Web access from the Text editor

  • Editor commands and keystrokes

Related Home Pages

  • Macros


Overview: Text Editor

Home Page (Text Editor)

The Visual C++ environment includes an integrated text editor to manage, edit, and print source files. Most of the procedures for using the editor should seem familiar if you have used other Windows-based text editors. With the Text editor, you can:

  • Automatically fill in code syntax by choosing from a generated list of class members, parameters or values.

  • Automate the Text editor with macros.

  • Create source files for different programming languages, including C/C++, Fortran, SQL, and HTML.

  • Set and customize syntax coloring for source files.

  • Emulate two popular text editors: BRIEF and Epsilon.

  • Perform advanced find and replace operations in a single file or multiple files, including using regular expressions and incremental searching.

  • Use virtual spaces for advanced cursor positioning.

  • Navigate through sections of code by matching group delimiters or using the Go To dialog box.

  • Use Bookmarks to mark frequently accessed lines in your source file.

  • Customize the Text editor with save preferences, the selection margin, tabs, and indents.

  • Modify the font style, size, and color.

  • Select lines, multiple lines, or columns.

  • Use drag-and-drop editing within one editor window, between editor windows, and between the Text editor and the debugger.

  • Test SQL scripts, triggers, and stored procedures, and insert triggers or stored procedures into a database.

  • Manage the source window.

Tip While using the Text editor, in many instances you can click the right mouse button to display a shortcut menu of frequently used commands. The commands available depend on what the mouse pointer is pointing to.

What do you want to know more about?

Syntax coloring

Editor emulation

Text search methods

File navigation

Web access from the Text editor

Editor commands and keystrokes


About Syntax Coloring

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Syntax coloring uses different colors for various code elements, such as keywords or comments. This coloring gives you visual cues about the structure and state of your code.

Syntax coloring is based on the language of your source file. It is global; once you set syntax coloring for a particular language, all files of that language are colored the same way.

The Text editor recognizes several languages, including Visual Basic Script (VBS), C/C++, ODL/IDL, and several variants of HTML. Additionally, you can define a list of keywords that you would like colored, and specify how you would like them colored.

Software products that support HTML differ widely in the set of elements, attributes, and entities they recognize. The HTML syntax-coloring feature lets you select a range of HTML support, and allows custom variations. When you create an HTML file, the default HTML support is Microsoft Internet Explorer 3.0. To switch to a different support, choose Properties from the Edit menu and select the HTML support of your choice from the Language box. The HTML support you select becomes the new default.

The built-in HTML support includes:

  • HTML Server Side Script.

  • HTML 2.0. This conforms with the DTD given in RFC1866.

  • HTML IExplore3. Microsoft Internet Explorer 3.0.

What do you want to do?

Set syntax coloring for one source file

Change colors used for syntax coloring

Set syntax coloring for user-defined keywords

Set syntax coloring for extensionless header files

Set syntax coloring for a custom HTML variation


About Editor Emulation

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor can emulate two popular text editors: BRIEF and Epsilon. With the emulation feature, the Text editor can emulate the key bindings, text selection, caret display, window display, and most editing commands of the selected editor. Epsilon and BRIEF macro languages are not supported, but Visual C++ includes macro capabilities; see the Automation Overview for more information. If you need shell-like functions, you can hook up cmd.exe or command.com from the Tools menu. For more information, see Customizing the Tools Menu.

The Epsilon emulation is based on the Lugaru Epsilon editor version 6.0, and the BRIEF emulation is based on the Borland BRIEF editor version 3.1.

Note Each editor emulation includes the use of native syntax for regular expressions during find and replace operations. For more information on regular expression syntax, see Regular Expressions, Regular Expressions with BRIEF Emulation, and Regular Expressions with Epsilon Emulation.

You can use the Compatibility tab in the Options dialog box to set overall editor behavior. Your choice of editor also dictates the regular expression language used throughout the product, wherever regular expression searches are supported. The Compatibility tab contains a drop-down list box of the editors available for emulation. The supported editor emulations are:

  • Visual C++ Developer Studio

  • Visual C++ version 2.0

  • BRIEF

  • Epsilon

The Options checklist contains the compatibility options and their default settings for the chosen editor. You can change these options to create a custom emulation model. When you create a custom emulation model, the word “Custom” appears in the list box with the name of the standard editor. For example, if you change some of the options for the BRIEF emulation, “Custom (BRIEF)” appears in the list.

The following default compatibility options are set for each editor emulation.

For this editor emulation | These default options are set
Developer Studio | Enable copy without selection.
Visual C++ 2.0 | Enable copy without selection. Enable virtual space.
BRIEF | Disable backspace at start of line. Enable copy without selection. Enable line-mode pastes. Enable virtual space. Include caret positioning in undo buffer. Use BRIEF’s regular expression syntax.
Epsilon | Include caret positioning in undo buffer.

What do you want to do?

Set an editor emulation

Create a custom editor emulation


About Text Search Methods

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor supports two common searching methods: full string searching and incremental searching. With full string searching, you specify the entire search string before the search begins. With incremental searching, the search is performed as you type the string.

With the advanced find and replace capabilities of the Text editor, you can search for text in a single source file or in multiple files. You can search for literal text strings or use regular expressions to find words or characters. A regular expression is a search string that uses special characters to match a text pattern in a file. You can use regular expressions, including tagged regular expressions, with both the Find and Replace commands. Regular expressions are not supported with incremental searching.

With the Find and Replace commands, you can:

  • Find text in a single file.

  • Find text in multiple files.

  • Replace text.

  • Use regular expressions.

If you use the SearchIncremental or SearchIncrementalBack commands, you can toggle case-sensitive mode with the FindToggleCaseSensitivity command by pressing CTRL+C. These keystrokes are not bindable and affect only the incremental search commands.

Because incremental search finds the match while you are typing, you rarely need to type the complete search string. If you are looking for a string that occurs multiple times in your file, you can use the FindNext and FindPrev commands. Incremental search stops when you press the ESC key.

What do you want to do?

Find text in a single file

Find text in multiple files

Find text using regular expressions


About File Navigation

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor provides a variety of methods to move around in a source file. In addition to the standard Windows navigation mechanisms, the Text editor includes an assortment of commands that enable you to move to almost any location in a file. Further, in addition to comprehensive GoTo and Bookmarks commands, the Text editor includes several advanced navigation features, such as virtual space and matching group delimiters.

You can move between open files with the Window menu, or by pressing CTRL+TAB or CTRL+SHIFT+TAB.

What do you want to know more about?

Virtual space

Matching group delimiters

Using Go To

Using bookmarks

What do you want to do?

Enable virtual space

Match delimiters

Use Go To

Use bookmarks


About Virtual Space

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

All editors support moving the cursor by one character position. The most common difference among text editors is whether you can move the cursor into a location that does not currently contain text. For example, if your cursor is on column 20 and there is no text on the line below the current line, moving the cursor down can do one of two things: Either the cursor moves to column 1 — because there is no text on the line below — or the cursor moves to column 20 of the next line. This behavior is called virtual space.

With the Text editor, you can treat text selection and space insertion in two ways. When you select the Virtual Spaces option, spaces are inserted between the end of the line and the insertion point before new characters are added to the line. When you clear the Virtual Spaces option, the Text editor behaves like Microsoft Word for Windows — the insertion point is set to the end of the line.


About Matching Group Delimiters

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Source code is often grouped using delimiters such as (), {}, and []. These groupings are called levels. You can navigate these levels using the LevelUp and LevelDown commands. The Text editor understands nested levels, and matches the correct delimiter even if the level spans several pages and itself contains many levels.

The LevelUp command searches backward for one of the right-side delimiters, and then positions the cursor before the matching left-side delimiter. The LevelDown command searches forward for a left-side delimiter, and then positions the cursor after the matching right-side delimiter.

The Text editor also provides the GoToMatchBrace and GoToMatchBraceExtend commands. When the cursor is initially positioned next to a delimiter, the GoToMatchBrace command moves the cursor to the matching delimiter in a block. Since this command works independently of whether the character is a right-side or left-side delimiter, you can quickly jump between the start and end of a level. The GoToMatchBraceExtend command extends the selection to the matching delimiter instead of moving the cursor.


About Go To

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Go To dialog box allows you to jump quickly to several different items in a file, including:

  • Bookmarks (type a bookmark name or select one from the drop-down list).

  • Definitions (type the name of a class, function, or variable to go to where it is defined).

  • Error/Tag (select a tagged line from the drop-down list).

  • Lines (type the line number).

  • Reference (type the name of a class, function, or variable to go to where it is referenced).

Some of the items in the Go to what box require additional information from you before the Go To command can execute. For example, if you select Line in the Go to what box, you must provide a line number.

The Go To dialog box includes helper text that prompts you for additional information when it is required. If the helper text appears dimmed, then the Go To item you selected is not available. A Go To item can be unavailable for two reasons:

  • The file type is incorrect.

    For example, you cannot supply a hexadecimal address in a source code file.

  • You have not yet defined any of the selected items.

    For example, you cannot jump to a bookmark if you have not defined any bookmarks.


About Bookmarks

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can set bookmarks to mark frequently accessed lines in your source file. Once a bookmark is set, you can use menu or keyboard commands to move to it. You can remove a bookmark when you no longer need it.

You can use both named and unnamed bookmarks. Named bookmarks are saved between editing sessions. Once you create a named bookmark, you can jump to that location whether or not the file is open. Named bookmarks store both the line number and the column number of the location of the cursor when the bookmark was created. This location is adjusted whenever you edit the file. Even if you delete the characters around the bookmark, the bookmark remains in the correct location.

Unnamed bookmarks are temporary. They are removed when the file containing them is closed or reloaded. Unnamed bookmarks store only the current line, not the column offset of the cursor. When a line containing an unnamed bookmark is deleted, the bookmark is also removed. You can jump to an unnamed bookmark by activating the file and using either the BookmarkNext or BookmarkPrev command. The advantage of unnamed bookmarks is that they are very easy to set (just use BookmarkToggle), and they provide you with visible feedback in the selection margin of your document.


About Web Access from the Text Editor

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can open an Internet address from within the Text editor. Place the cursor on the address and right-click to display the shortcut menu. One of the available commands will be Open, with the Internet address next to it. If you click Open, your browser will start, access the Internet address, and display the appropriate page.

Another way to open an Internet address is to type it into the Find tool, then press CTRL+SHIFT+G.


About Editor Commands and Keystrokes

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can access Text editor commands in many ways: from the menus, from the Edit toolbar, and from the shortcut menu. There are many Text editor commands, but not all of them appear on the menus and toolbars. However, you can drag any command to a menu or toolbar, which allows you to customize the Editor with the commands you find most useful.

To see a complete list of commands, choose Keyboard from the Help menu, and choose Edit in the drop-down list. All of the Text editor commands are listed, along with the current key binding and a brief description. For information on customizing menus and toolbars, see the Customizing Visual C++ Overview.

The Advanced menu (available from the Edit menu) contains some of the most useful edit commands, including Incremental Search, Format Selection, Tabify Selection, Untabify Selection, Make Selection Uppercase, Make Selection Lowercase, and View Whitespace.

The Edit toolbar contains other useful commands. To display the Edit toolbar, choose Customize on the Tools menu. Click Toolbars, then select the Edit check box, and click Close.


How Do I ... Topics: Text Editor

Home Page (Text Editor) | Overview | FAQ | Reference

What do you want to do?

Write macros

Set syntax coloring

Emulate another editor

Find and replace text

Navigate in files

Customize the Text editor

Edit text

Select text

Manage files

Tip While using the Text editor, in many instances, you can click the right mouse button to display a pop-up menu of frequently used commands. The commands available depend on what the mouse pointer is pointing to.


Setting Syntax Coloring

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Syntax coloring uses different colors for various elements of your code, such as keywords or comments. This coloring gives you visual cues about the structure and state of your code.

What do you want to know more about?

Syntax coloring

What do you want to do?

Set syntax coloring for one source file

Change colors used for syntax coloring

Set syntax coloring for user-defined keywords

Set syntax coloring for extensionless header files

Set syntax coloring for a custom HTML variation

To set syntax coloring for one source file

  1. From the Window menu, select the source window you want to activate.

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

  2. From the View menu, choose Properties.

    The Source File Properties page appears. The Language box displays the current language setting for syntax coloring. The drop-down list contains the available language choices.

  3. In the Language box, select the language for which you want to set syntax coloring, or select None to turn syntax coloring off.

  4. Close the property page.

    The choice you made takes effect.

Tip If you create or save a file with a recognized extension (such as VBS, CPP, or HTM), syntax coloring for the language indicated by that extension takes effect immediately.

To change colors used for syntax coloring

  1. From the Tools menu, choose Options.

  2. Select the Format tab.

  3. In the Category box, select the type of window for which you want to define formatting.

  4. In the Font box, select the font you want.

    The Font box displays the different fonts installed on your system. The text sample in the sample box changes to the font you select.

  5. In the Size box, select the size to be used with the font you selected.

    The Size box displays the sizes available for the selected font. The text sample in the sample box changes to the size you select.

  6. In the Colors box, select the type of text you want to color.

  7. In the Background box, select a background color.

  8. In the Foreground box, select a foreground color.

    The Background and Foreground boxes display the 16 standard colors and the Automatic setting. The text sample displayed in the Sample box changes to the color you select.

    The behavior of the Automatic setting depends on the element selected. For colors that map to standard system elements (such as Foreground Color, Background Color, or Selected Text Color), the Automatic setting sets the element to the appropriate system color. For syntax coloring elements and other non-system defined colors, the Automatic setting indicates that the foreground color or background color from the same category is to be used.

  9. Click OK.

To set syntax coloring for user-defined keywords

  1. In the same directory as msdev.exe, use the Text editor or Windows Notepad to create a text-only file named usertype.dat.

  2. Add your keywords to usertype.dat, one keyword per line.

    Note The usertype.dat file is read during initialization. It cannot be renamed, nor can it be reloaded during an editing session. The syntax coloring mechanism checks the usertype.dat file last. Thus, all previously defined color settings take precedence over the user-defined keywords.

  3. Save the file as a text-only file, exit, and then restart Visual Studio.

  4. From the Tools menu, choose Options.

  5. Select the Format tab.

  6. In the Colors box, select User Defined Keywords.

  7. Set the font, font size, foreground color, and background color to your preferences.

    For more information, see To change colors used in syntax coloring.

  8. Click OK.

Tip For any source file, you can use the Source File Properties page to specify which language syntax coloring to apply (or turn off syntax coloring altogether). For more information, see Setting Font Style, Size, and Color.

To set syntax coloring for extensionless header files

  1. Open the langext.dat file. This file resides in the same directory as msdev.exe.

  2. Add the filenames you want to color to the file.

  3. Save the file.

Note The langext.dat file pairs filenames with a language. This file is consulted only when extension matching fails. That is, an HTML file is always identified as HTML, not as C/C++, even if it is listed in the C/C++ section of langext.dat.

To set syntax coloring for a custom HTML variation

  1. Create a text file with an extension of .hlx in the \msdev\bin\ide directory.

    The first line of the file is a signature that uniquely identifies the type of the file. It contains the name of the variation that will be displayed on the Source File Properties page. After the signature line, the format resembles that of a Windows initialization file. A semicolon at the beginning of a line indicates a comment.

  2. Create three sections in the file: an [Elements] section, an [Attributes] section, and an [Entities] section.

    Each section contains a list of names separated by spaces, carriage returns, or line feeds. The names do not need to be in alphabetical order. You must specify all the elements, attributes, and entities you want to color.

    See the example for a general outline of a sample .hlx file.

  3. Save the .hlx file.

Note If the custom variation you specify in the .hlx file has the same name as a built-in HTML support, it will override the built-in HTML support. There is a 14-character limit to the name of the HTML variation you specify.

Sample .hlx file

The following example gives the general outline of an .hlx file. For brevity, this example is shortened to omit most names.

@HLX@ "HTML - Custom"
; Custom HTML tagset file.
; Must begin with the "@HLX@" signature and
; the name of the HTML variant in quotes. The
; name is limited to 14 characters.
;--------------------------------
[Elements]
; Element set, case-insensitive
; HTML tags, e.g. <H1>

A APPLET

; break control
BR NOBR WBR

; headings
H1 H2 H3 H4 H5 H6

; character formatting
B CITE CODE EM I KBD STRIKE STRONG TT U VAR
FONT S SUB SUP SMALL BIG BLINK DFN

; etc. ...

;--------------------------------
[Attributes]
; Attribute set, case-insensitive
; (applied to all elements)

ACTION ALIGN ALINK ALT

; etc. ...

;--------------------------------
[Entities]
; Entity set, case-sensitive
; special characters, e.g. &amp;
; If this section is empty or omitted, the standard set from RFC1866 is used.

gt lt amp quot
; etc. ...


Emulating Another Editor

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor can emulate two popular Text editors: BRIEF and Epsilon. The Epsilon emulation is based on the Lugaru Epsilon editor version 6.0, and the BRIEF emulation is based on the Borland BRIEF editor version 3.1.

What do you want to know more about?

Editor emulation

What do you want to do?

Set an editor emulation

Create a custom editor emulation

To set an editor emulation

  1. From the Tools menu, choose Options.

  2. Select the Compatibility tab.

    In the Current source editor emulation box, select the editor that you wish to emulate. The default editor is Developer Studio. The Options box lists the status of predefined editor options.

  3. Click OK.

To create a custom editor emulation

  1. From the Tools menu, choose Options.

  2. Select the Compatibility tab.

    In the Current source editor emulation box, select a standard editor on which to base your custom editor. The Options box lists the editor’s current options.

  3. Select the options you want to create the desired editor behavior.

    The name of the custom editor reflects the name of the standard editor. For example, if you customize the BRIEF emulation, the custom editor is named “Custom (BRIEF).”

  4. Click OK.


Finding and Replacing Text

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor supports both full string searching and incremental searching. You can search for text in a single source file or in multiple files. You can search for literal text strings or use regular expressions to find words or characters. You can also use tagged regular expressions for searching and replacing.

With the Find command, you can search the active window or all open documents for the following types of text strings:

  • Whole Word Match Matches all occurrences of a text string not preceded or followed by an alphanumeric character or the underscore (_).

  • Case Match Searches for text that matches the capitalization of the text string.

  • Regular Expressions Uses special character sequences — regular expressions — to search for text. If you select the Regular Expression check box in the Find dialog box, you can build the search string using regular expressions from the drop-down list.

You can toggle these types of searches using toolbar buttons; you can also toggle whether you search the active file only or all open files, again with a toolbar button.

You can set bookmarks at every occurrence of the text string or expression. You can then use the BookmarkNext command to move to each bookmark in your file.

What do you want to know more about?

Text search methods

Find commands

Regular expressions

What do you want to do?

Find text in a single file

Find text in multiple files

Replace text

Find text using regular expressions


Finding Text in a Single File

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

What do you want to do?

Find a text string

Start a find without using the Find dialog box

Find a string using incremental search

Find text using regular expressions

To find a text string

  1. Move the insertion point to where you want to begin your search.

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

  2. From the Edit menu, choose Find.

  3. In the Find what box, type the search text or a regular expression.

    Tip Select the menu button to the right of the box to display a list of regular search expressions. When you select an expression from this list, the expression is substituted as the search text in the Find what box. If you do use regular expressions, be sure the Regular expression check box is selected. You can also use the drop-down list to select from a list of up to 16 previous search strings.

  4. Select any of the Find options.

  5. Start the search by clicking the Find Next or Mark All buttons.

    The Find dialog box disappears when the search begins.

  6. To continue your search, use the Find Next or Find Previous shortcut keys, or the equivalent toolbar buttons on the Edit toolbar. The default shortcut key for Find Next is F3; the default key combination for Find Previous is SHIFT+F3.

Tip You can use buttons on the Edit toolbar to change whether searches are case-sensitive, match whole words, or use regular expressions. To view the Edit toolbar, right-click in an empty part of the menu bar and check Edit.

To start a find without using the Find dialog box

  • Type or select a search string in the Find box on the Standard toolbar, and press ENTER.

Note You can use regular expressions with the Find box on the Standard toolbar if you have previously selected the Regular expression check box in the Find dialog box.

To find a string using incremental search

  1. From the Edit menu, choose Advanced; then choose Incremental Search.

    The cursor moves to the status bar.

  2. Begin typing the search string.

    As you type each character, the Text editor selects the matching string in your file.

  3. If necessary, press the SearchIncremental key combination to go to the next match in your file.

  4. Press the ESC key or use any of the navigational commands to end the search.

Note If there is no match, the Text editor beeps and displays a warning in the status bar.


Finding Text in Multiple Files

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Find in Files command supports two output panes. This allows you to conduct a second search through multiple files without losing the results from your first search.

To find a text string in multiple source files

  1. From the File menu, choose Find In Files.

  2. In the Find what box, type the search text or a regular expression.

    Tip Select the menu button to the right of the box to display a list of regular search expressions. When you select an expression from this list, the expression is substituted as the search text in the Find what box. If you do use regular expressions, be sure the Regular expression check box is selected. You can also use the drop-down list to select from a list of up to 16 previous search strings.

  3. In the In files/file types box, select the file types you want to search.

    You can use the drop-down list to select from common file types or to type text specifying other file types.

  4. In the In folder box, select the primary folder that you want to search. Click the Browse button to display the Choose Directory dialog box if you want to change drives and directories.

  5. If necessary, select one or more of the Find options.

  6. If you want to direct the search output to a second Find in Files pane, select the Output to pane 2 check box.

  7. To select additional folders to search, click the Advanced button.

    The Look in additional folders portion of the dialog box appears.

  8. If necessary, select the Look in folders for project source files check box or the Look in folders for project include files check box, or both.

    Note These project source and project include file folders are the same as the project’s directory paths.

  9. To add a folder to the Look in additional folders list, double-click the empty selection. Then type the path and filename, or click the Browse button to display the Choose Directory dialog box to change drives and directories.

    To remove a folder from the Look in additional folders list, select the folder and press DEL.

    The Visual C++ environment retains the contents of the Find In Files list between uses of the Find In Files command in any single session.

  10. Click the Find button to begin the search.

    The Output window displays the list of file locations where the text string appears. Each occurrence lists the fully qualified filename, followed by the line number of the occurrence and the line containing the match.

  11. To open a file containing a match, double-click the entry in the Output window.

    An editor window containing the file opens, with the line containing the match selected. You can jump to other occurrences of the text string by double-clicking the specific entries in the Output window, or you can use the GoToNextErrorTag command.

When you jump to a found string location specified in the Output window, the corresponding source file is loaded if it is not already open in the editor.

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


Replacing Text

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

To replace text

  1. Move the insertion point to where you want to begin your search.

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

  2. From the Edit menu, choose Replace.

  3. In the Find what text box, type the search text or a regular expression.

    Tip Click the button to the right of the box to display a list of regular search expressions. When you select an expression from this list, the expression is substituted as the search text in the Find what text box. If you do use regular expressions, be sure the Regular expression check box is selected. You can also use the drop-down list to select from up to 16 previous search strings.

  4. In the Replace with text box, type the replacement text.

    Tip Click the button to the right of the box to display a list of tagged expressions you can use as replacement text.

  5. Select any of the remaining Find options.

  6. Start the search by clicking the Find Next, Replace, or Replace All buttons.


Finding Text Using Regular Expressions

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

A regular expression is a search string that uses special characters to match a text pattern in a file. You can use regular expressions with both the Find and Replace commands.

To find text using regular expressions

  1. From the Edit menu, choose either Find or Replace.

  2. In the Find what text box, type a regular expression.

    Tip Click the button to the right of the box to display a list of regular search expressions. When you select an expression from this list, the expression is substituted as the search text in the Find what text box. If you use regular expressions, be sure the Regular expression check box is selected. You can also use the drop-down list to select from up to 16 previous search strings.

  3. In the Replace with text box, type a regular expression if required.

  4. Start the search by clicking the Find Next, Mark All, Replace, or Replace All buttons.


Navigating in Files

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor provides a variety of methods with which to move around in a source file. In addition to the regular mouse movement and page controls, the Text editor includes an assortment of commands that enable you to move to almost any location in a file. Furthermore, the editor includes several advanced navigation features, such as virtual space, and matching group delimiters.

What do you want to know more about?

File navigation

Navigation commands

Matching group delimiters

Using Go To

Go To destinations

Bookmark commands

What do you want to do?

Enable virtual space

Match delimiters

Match conditional statements

Use Go To

Use bookmarks


Enabling Virtual Space

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

With the Text editor, you can treat text selection and space insertion in two ways. When you select the Virtual Spaces option, spaces are inserted between the end of the line and the insertion point before new characters are added to the line. When you clear the Virtual Spaces option, the Text editor behaves like Microsoft Word for Windows — the insertion point is set to the end of the line.

To enable virtual space

  1. From the Tools menu, choose Options.

  2. Select the Compatibility tab.

  3. In the Current source editor emulation box, select the editor emulation in which you want to have virtual spaces.

  4. Select the Enable virtual space check box.

  5. Click OK.

Note Many word processors support moving the cursor one sentence at a time. The Text editor supports this as well (with the SentenceLeft and SentenceRight commands), but most source code doesn’t have the spacing and punctuation marks needed for sentence navigation. Instead, you can use the LineUp and LineDown commands to navigate single lines of source code.


Matching Delimiters

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Source code is often grouped using delimiters such as (), {}, and []. These groupings are called levels. You can navigate these levels using the LevelUp and LevelDown commands. The editor understands nested levels, and matches the correct delimiter even if the level spans several pages and itself contains many levels.

The editor also provides the command GoToMatchBrace, which allows you to jump quickly between the start and end of a level. The GoToMatchBraceExtend command extends the selection to the start or end of a level, instead of moving the cursor.

What do you want to do?

Search forward for a matching level

Move to a matching brace

Select code between the start and end of a level

To search forward for a matching level

  • Press the LevelDown key combination.

    The command begins searching for one of the left-side delimiters, which are (, {, and [. When the left-side delimiter is found, the cursor is positioned at the matching right-side delimiter. If a matching delimiter cannot be found, the editor beeps.

To move to a matching brace

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

  2. Press the GoToMatchBrace key combination.

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

To select code between the start and end of a level

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

  2. Press the GoToMatchBraceExtend key combination.

    The insertion point moves forward or backward to the matching brace, and all the code between the braces is selected.


Matching Conditional Statements

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Source code is often grouped between compiler preprocessor statements. The Text editor will allow you to move from inside a conditional statement to the enclosing preprocessor statement.

To move to a matching conditional statement

  • Move the insertion point to a line that is enclosed by preprocessor statements.

  • Press the ConditionalUp key combination to move the insertion point up to the line containing the matching preprocessor statement (such as #ifdef).

  • Press the ConditionalDown key combination to move the insertion point down to the line containing the matching preprocessor statement (such as #endif).

    Note If you hold down the SHIFT key, you can use the ConditionalUpExtend and ConditionalDownExtend key combinations to select text from the current cursor position to the enclosing #if, #ifdef, #else, #elif, or #endif preprocessor statement. This key binding of the SHIFT key with the ConditionalUpExtend and ConditionalDownExtend commands is available in the standard configuration after installation. If you have changed shortcut key assignments, this keystroke combination may not be available.


Using Go To

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Go To dialog box allows you to jump quickly to several different items in a file, including bookmarks, definitions, errors or tags, specific lines, or references.

To use the Go To dialog box

  1. From the Edit menu, choose Go To.

  2. In the Go To what box, select the type of item you want.

  3. Enter any additional information required.

  4. Click one of the navigation buttons: Go To, Previous, or Next.

Note If the Go To what item is undefined, the additional selection criteria box is unavailable. For example, if you have not defined any bookmarks, the Enter Bookmark Name box appears dimmed.


Using Bookmarks

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can set named or unnamed bookmarks to mark frequently accessed lines in your source file. Once a bookmark is set, you can use menu or keyboard commands to move to it. You can remove a bookmark when you no longer need it.

What do you want to do?

Set a named bookmark

Set an unnamed bookmark

Remove a named bookmark

Remove multiple named bookmarks

Remove an unnamed bookmark

Jump to a named bookmark

Move to the next bookmark

Move to the previous bookmark

To set a named bookmark

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

  2. From the Edit menu, choose Bookmarks.

  3. In the Name box, type a name for the bookmark.

  4. Click Add to add the named bookmark to the list of bookmarks and to set the bookmark at the insertion point.

  5. Click Close.

To set an unnamed bookmark

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

  2. Press the BookmarkToggle key combination.

    The line is selected, or marked in the margin if you have set the selection margin.

To remove a named bookmark

  1. From the Edit menu, choose Bookmarks.

  2. Select the name of the bookmark to remove.

  3. Click Delete.

  4. Click Close.

To remove multiple named bookmarks

  1. From the Edit menu, choose Bookmarks.

  2. Select the names of the bookmarks to remove.

  3. Click Delete.

  4. Click Close.

To remove an unnamed bookmark

  1. Move the insertion point to anywhere on the line containing the unnamed bookmark.

  2. Press the BookmarkToggle key combination.

To jump to a named bookmark

  1. From the Edit menu, choose Bookmarks.

  2. Select the name of the bookmark to jump to.

  3. Click Go To.

Note If the file containing the bookmark is not currently open, the Text editor opens the file.

To move to the next bookmark

  • Press the BookmarkNext key combination.

To move to the previous bookmark

  • Press the BookmarkPrev key combination.


Customizing the Text Editor

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can set the Text editor’s behavior to suit your preferences and work habits in several areas, including how you like to save your files; tabs and indents; and font style, size, and color.

You can customize the Edit toolbar, or place Text editor commands on any menu or toolbar. For more information, see Overview: Customizing Visual C++.

What do you want to do?

Set save preferences

Set the selection margin

Set tabs and indents

Set font style, size, and color


Save Preferences

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can set save preferences — such as whether to be prompted before saving a file — in the Options dialog box. By default, the Text editor saves all changed files before building an application. The following table lists the save preferences.

Save Option | Description
Save before running tools | Saves files before you build a project or run a build utility such as NMAKE.
Prompt before saving files | Confirms (with a dialog box prompt) that you want to save files.
Automatic reload of externally modified files | Automatically reloads externally modified files that have been loaded (but not yet changed) by the editor.

To change the save options

  1. From the Tools menu, choose Options.

  2. Select the Editor tab.

  3. Select any of the Save options.

  4. Click OK.


Setting the Selection Margin

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The selection margin is an area to the left of each line of text. The selection margin is used to show breakpoints, temporary bookmarks, current and caller line, and error line. It also has special selection behavior — mostly the same as Microsoft Word for Windows.

What do you want to do?

Set the selection margin

Use the selection margin

Set the color of the selection margin

To set the selection margin

  1. From the Tools menu, choose Options.

  2. Select the Editor tab.

  3. Select the Selection margin check box.

  4. Click OK.

To use the selection margin

When the mouse pointer is moved into the selection margin, it changes to a select arrow that points up and to the right (a mirror image of the standard select arrow).

Do any of the following:

  • Click in the margin to select the entire line to the right of the mouse pointer.

  • Click in the margin and move the mouse pointer to select multiple consecutive lines.

  • While holding down SHIFT, click in the margin and move the mouse pointer to extend a selection.

  • While holding down CTRL, click anywhere in the margin to select the entire file. (This is equivalent to choosing the Select All command from the Edit menu.)

To set the color of the selection margin

  1. From the Tools menu, choose Options.

  2. Click the Format tab.

  3. In the Colors box, choose Selection Margin.

  4. Set the foreground and background colors you want.

  5. Click OK.


Setting Tabs and Indents

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can indent text with tab characters several ways:

  • Use the INDENT SELECTION key.

  • Use Auto Indent (without Smart Indent).

  • Use Auto Indent (with Smart Indent enabled).

When you press the TAB key, the insertion point moves to the next indent level. You can display (or hide) the tab symbols by selecting Advanced from the Edit menu, and then selecting View Whitespace.

You can also use Auto Indent (without Smart Indent) to automatically indent new lines to match the previous line.

What do you want to do?

Set Auto Indent

Set Smart Indent

Change tab and indent settings

Display or hide tab symbols

Indent a group of lines

Unindent a group of lines

To set Auto Indent

  1. From the Tools menu, choose Options.

  2. Select the Tabs tab.

  3. Under Auto indent, select the option you want:
    • None: to disable Auto Indent

    • Default: to set the tab and indent size to match that of the previous level

    • Smart: to use Smart Indent
  4. Click OK.

If you use Auto Indent (with Smart Indent enabled), the Text editor automatically indents the text based on the context of the previous lines.

To set Smart Indent

  1. From the Tools menu, choose Options.

  2. Select the Tabs tab.

  3. Under Auto Indent, select Smart.

  4. Under Smart indent options, select the language element and specify the number of previous lines to use for the context of smart indenting.

  5. Click OK.

Backspacing over a tab character deletes that tab character, regardless of the indent setting.

If you select the Insert spaces option, a tab character is not inserted, and only spaces are inserted to reach the next indent level.

Note The File type box on the Tabs tab contains a list of file types. The initial tab settings for each file you load are assigned based on the file extension and the setting of this box. You can use the Tab size and Indent size boxes on the Tabs tab or on the Source File Properties page to specify individual settings for these two fields on a per-file basis, as needed.

To change tab and indent settings

  1. From the Tools menu, choose Options.

  2. Select the Tabs tab.

  3. In the Tab size box, type the number of spaces to use as a tab stop. The default is four spaces.

  4. In the Indent size box, type the number of spaces to use for indents. The default is four spaces.

  5. Select the Keep tabs option to treat each tab as a single tab character when the file is saved.

    –or–

    Select the Insert spaces option to use spaces as specified in the Tab size box.

  6. Click OK.

To display or hide tab symbols

  1. From the Edit menu, choose Advanced.

  2. Select View Whitespace.

    Spaces are displayed as dots and tab symbols are displayed as >> whenever they appear in a source file.

To indent a group of lines

  1. Select the group of lines.

  2. Press the LineIndent key combination.

To unindent a group of lines

  1. Select the group of lines.

  2. Press the LineUnindent key combination.

    Note The LineUnindent command only returns to previous tab stops.


Setting Font Style, Size, and Color

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can change the font style, size, and color settings for any window with the Format command. You may discover that different fonts in various windows give visual clues about the function of the windows — the default setting for source windows, a different font for the Watch window, and so on. You can use the text font and size to better manage your window display of information.

Note In addition to setting font coloring, you must enable syntax coloring in order to view colored text elements.

To change a font style, size, or color

  1. From the Tools menu, choose Options.

  2. Select the Format tab.

  3. In the Category box, select the window you want to format

  4. In the Font box, select the font you want.

    The Font box displays the different fonts installed on your system. The text sample in the sample box changes to the font you select.

  5. In the Size box, select the font size you want.

    The Size box displays the sizes available for the selected font. The text sample in the sample box changes to the size you select.

  6. In the Colors box, select the type of text you want to color.

  7. In the Background box, select a background color; in the Foreground list box, select a foreground color.

  8. Click OK.

    Note The Background and Foreground lists display the 16 standard colors and the Automatic setting. The text sample displayed in the Sample box changes to the color you select.

    The behavior of the Automatic setting depends on the element selected. For colors that map to standard system elements (such as foreground color, background color, or text selection color), the Automatic setting sets the element to the appropriate system color. For syntax coloring elements and other non-system defined colors, the Automatic setting indicates that the foreground color or background color from the same category is to be used.

Text within one category of window can be only one font and size. Multiple fonts cannot be displayed in the same category of source window.

The font and size settings apply to everything within the selected category, while the foreground and background color settings apply only to the selected element of that category.

Tip You can reset the formatting options for a selected category to the default settings by choosing Reset All.


Editing Text

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

With the Text editor, you can cut, copy, and paste selected text using menu commands or drag-and-drop operations. You can also undo and redo selected editing actions.

The Text editor provides the following editing commands:

  • Cutting, copying, pasting, and deleting text

  • Undoing and redoing editing actions

  • Using the drag-and-drop feature

  • Specifying column blocks for editing

All editing commands require a selection in order to work. Some of the commands can make a selection based on the current cursor location. Command names that begin with an object (such as WordCapitalize) assume that object for a default selection; otherwise, the default selection will be the character adjacent to the cursor. For example, the Delete command removes the character to the right of the cursor if there is no selection.

Note You can enable the Copy command to work on the current line even if there is no selection. From the Tools menu, choose Options. Select the Compatibility tab, and click the Enable copy without selection option. This enables the Copy command to work on the current line if there is no selection.

When you cut text from the file, the text is removed from your file and placed on the Clipboard. When you delete text from the file, the text is removed from your file, and the Clipboard is not used. All Windows applications share the same Clipboard. Commands that use the Clipboard overwrite whatever was previously placed onto the Clipboard by other commands or other Windows applications. This single-Clipboard behavior is true even when emulating an editor (such as Epsilon) that supports multiple Clipboards.

What do you want to know more about?

Edit commands

What do you want to do?

Cut, copy, paste, or delete text

Undo or redo an edit action

Use the drag-and-drop feature

Select text

Set tabs and indents


Cutting, Copying, Pasting, or Deleting Text

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can edit your text using the following actions.

Action | Description
Cut | Removes selected text from the active window.
Copy | Duplicates selected text in the active window.
Paste | Pastes cut or copied text into an active window.
Delete | Deletes text without copying it to the Clipboard.
Undo | Restores the text.
Redo | Reapplies the prior edit.

What do you want to do?

Cut or copy and paste text

Delete text

To cut or copy and paste text

  1. Select the text you want to cut or copy.

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

    The cut or copied text is placed onto the Clipboard and is available for pasting.

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

  4. From the Edit menu, choose Paste.

To delete text

  1. Select the text you want to delete.

  2. From the Edit menu, choose Delete.

    The deleted text is not placed onto the Clipboard, and cannot be pasted.


Undoing or Redoing an Edit Action

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Use the Undo command to undo previous editing actions. Use the Redo command to reapply editing actions that have been undone. Redo is unavailable unless you have used the Undo command.

The number and scope of editing actions you can undo is determined by the size of the Text editor’s UndoRedoSize buffer in the registry.

Note You can also undo automated edits. For example, if you have used ClassWizard to add a command handler, you can undo the ClassWizard edits by choosing AutomatedEdit in the Undo drop-down list.

To undo an edit action

  • From the Edit menu, choose Undo.

To redo an edit action

  • From the Edit menu, choose Redo.


Using Drag-and-Drop Editing

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Drag-and-drop editing is the easiest way to move or copy a selection of text within a file, between files, or between applications. The text you drop remains selected, which makes it easy to copy a chunk of text into several places.

What do you want to do?

Move text

Copy text

To move text using drag-and-drop editing

  1. Select the text you want to move.

  2. Drag the selected text to the new location.

    Note You can also use the right mouse button for drag-and-drop editing. Select the text you want, and then use the right mouse button to drag the text to a new location. A shortcut menu appears, asking if you want to move or copy the selected text.

    Tip At any time during a drag-and-drop procedure, you can click the other mouse button to cancel the operation.

To copy text using drag-and-drop editing

  1. Select the text you want to copy.

  2. While holding down the CTRL key, drag the selected text to the new location.


Selecting Text

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can select lines, multiple lines, and column blocks of text to cut, copy, delete, indent, and unindent. Most of the selection commands have extensions (the word “Extend” is appended to the name of the command) that move the cursor and extend the selection. By default, these commands are bound to the same key combination as the primary selection command plus the SHIFT key (such as SHIFT+LEFT ARROW for the CharLeftExtend command).

What do you want to know more about?

Selection commands

What do you want to do?

Select a line of text

Select multiple lines of text

Select a column block of text

To select a line of text

  • In the selection margin, point to the beginning of the text you want to select and click the left mouse button.

To select multiple lines of text

  1. In the selection margin, point to the beginning of the text you want to select.

  2. Drag either up or down to select the lines of text.

To select a column block of text

  1. Point to the beginning of the text you want to select.

  2. Hold down the ALT key and click the left mouse button (do not release).

  3. Move the mouse to point at the end of the text you want to select and release the ALT key.

    When you release the left mouse button, the block of text is selected, and the text is available for cut, copy, delete, and indent operations. To cancel column-select mode, click the left mouse button.

Note When you use proportional fonts in the editor window, the column positions you select in the first line may not correspond exactly to the subsequent lines you select. The Text editor selects the character most directly in line with the start and end columns, ignoring the actual character count.


Managing Files

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor File menu has several commands for standard file management.

What do you want to know more about?

Text editor file commands

What do you want to do?

Create a new file

Open a file

Open multiple files

Save a file

Print a file

Manage open windows

Set save preferences

Preview HTML pages


Creating a New File

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The New command creates a new source file. Creating a source file does not affect other open source files. You can create source files of many types, including Visual Fortran fixed-form or free-form source files, Visual C++ header or source files, HTML pages, Active Server pages, and VBS (macro) files.

Note The Text editor automatically inserts a small amount of boilerplate text into new HTML and Active Server pages, as well as VBS files.

To create a new source file

  1. From the File menu, click New.

  2. Select the kind of source file you want to create.

  3. Select or clear the Add to Project check box, if necessary.

  4. Type a name in the File name box.

  5. Type a path in the Location box.

  6. Click OK.


Previewing HTML Pages

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can preview HTML pages in the Text editor using the current system browser.

To preview HTML pages in the Text editor

  • Right-click in an HTML file displayed in the editor and choose Preview.


Opening a File

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

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

To open a file

  1. From the File menu, choose Open.

  2. Select the drive and directory where the file is stored.

  3. If you want read only, select the Open as read only check box.

    Note You can edit a file even if the Open as read only check box is selected. When you save the file, the Save As dialog box appears, allowing you to save the file using a different name.

  4. Specify the types of files to display in the Files of type box.

    Files with the chosen extension are displayed in the list box. For example, Project Workspaces displays all files with the .dsw extension. The Files of type box initially lists commonly used file extensions. The default shows the .for, .f90, .f, .fi, .fd, .fpp, and .rc extensions. If Visual C++ is installed, it also shows the .c, .cpp, .cxx, and .h extensions.

    Tip You can specify wildcard patterns in the File name box to display file types. You can use any combination of wildcard patterns, delimited by semicolons. For example, if you type *.h;*.cpp, all files with these extensions are displayed. The wildcard patterns you specify are retained until you close the dialog box.

  5. Select a filename, then click Open.

You can also open a file by double-clicking the file icon in the Project Workspace, or by dragging the icon of a non-project file into the application window.

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


Opening Multiple Files

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can open multiple files from the Open dialog box by using the mouse to select a file or group of files. Before you can select files, they must be visible in the Directories window.

What do you want to do?

Open two or more files in sequence

Open two or more files out of sequence

To open two or more files in sequence

  1. From the File menu, choose Open.

  2. Select the drive and directory where the files are stored.

    The default is the current drive and directory.

  3. Specify the types of files to display in the Files of type box.

    Files with the chosen extension are displayed in the list box. For example, Project Workspaces displays all files with the .dsw extension. The Files of type box initially lists commonly used file extensions. The default shows the .for, .f90, .f, .fi, .fd, .fpp, and .rc extensions (and .c, .cpp, and .h extensions if Visual C++ is installed).

    Tip You can specify wildcard patterns in the File name box to display file types. You can use any combination of wildcard patterns, delimited by semicolons. For example, if you type *.f90;*.rc, all files with these extensions are displayed. The wildcard patterns you specify are retained until you close the dialog box.

  4. Click the first file or directory you want to select.

  5. Hold down the SHIFT key while you click the last file or directory in the group, and then click Open.

To open two or more files out of sequence

  1. From the File menu, choose Open.

  2. Select the drive and directory where the files are stored.

    The default is the current drive and directory.

  3. Specify the types of files to display in the Files of type box.

    Files with the chosen extension are displayed in the list box. For example, Project Workspaces displays all files with the .dsw extension. The Files of type box initially lists commonly used file extensions. The default shows the .c, .cpp, .cxx, .h, and .rc extensions.

    Tip You can specify wildcard patterns in the File name box to display file types. You can use any combination of wildcard patterns, delimited by semicolons. For example, if you type *.h;*.cpp, all files with these extensions are displayed. The wildcard patterns you specify are retained until you close the dialog box.

  4. Hold down the CTRL key while you click each file or directory that you want. After your selection is complete, click Open.

    To cancel a selection, hold down CTRL while you click the selected file or directory.


Saving a File

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

As you make changes to a source file, an asterisk (*) appears in the title bar to indicate that the file has changed since it was last saved. Each source window associated with a source file can retain its own sizing and other window attributes.

What do you want to do?

Save a file

Save all open files

Save selected open files

Save a new file or another copy of an existing file

To save a file

  1. Switch to the source window.

  2. From the File menu, choose Save.

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

    If your file is unnamed, the Save As dialog box appears.

  3. In the File name box, type the filename.

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

  5. Click Save.

To save all open files

  • From the File menu, choose Save All.

To save selected open files

  1. From the Window menu, choose Windows.

  2. Select one or more files from the file list.

  3. Click Save.

  4. Click Cancel.

You can also save another copy of an existing file. This procedure is useful for maintaining revised copies of a file while keeping the original unchanged. For more information, see To save a new file or another copy of an existing file.

To save a new file or another copy of an existing file

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

  2. From the File menu, choose Save As.

  3. In the File name box, type the filename.

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

  5. Click Save.


Printing a File

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

With the Text editor, you can print selected text or a complete file. Text is printed in the default font for the printer if the default editor font is used. Otherwise, the text prints with the selected editor font, if that font is available on the printer.

You can customize your print jobs by adding headers and footers and by adjusting margins.

What do you want to do?

Print selected text

Print an entire file

Customize a print job

To print selected text

  1. Select the text you want to print.

  2. From the File menu, choose Print.

    The Print dialog box appears. Under Print Range, the Selection option is automatically selected for you.

  3. Click OK.

To print an entire file

  1. Move the focus to the source file you want to print.

  2. From the File menu, choose Print.

    The Print dialog box appears. Under Print Range, the All option is automatically selected for you.

  3. Click OK.

To customize a print job

  1. From the File menu, choose Page Setup.

  2. In the Header and Footer boxes, type header or footer text, print control codes, or both.

    Use the right arrow to display a menu that enables you to insert control codes into the text box. You can enter separate alignment options for Filename, Page Number, Current Time, and Current Date. Always enter the alignment option first, then the data. For example:

    &L&F&C&P

    specifies that the filename (&F) be left-aligned (&L) and that the page number (&P) be center-aligned (&C).

    For more information, see Print Control Codes.

  3. Under Margins, type the left, right, top, and bottom measurements.

  4. Click OK.


Managing Open Windows

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Text editor features options that control the display of source windows. You can switch between windows, open new windows, split window views, and view a source file in full-screen mode.

What do you want to do?

Switch to a source window

Create a new window for an open source file

Split a source window

View a source file in full-screen mode

End full-screen mode

Close a source file

To switch to a source window

  1. From the Window menu, choose Windows.

  2. Select a window from the Select Window list.

  3. Click the Activate button, or double-click the selection.

To create a new window for an open source file

  1. Switch to the source window.

  2. From the Window menu, choose the New Window command.

    A second copy of the source file is displayed with an :n suffix. As you open more windows on the source file, the value of n increases. You can scroll and split each window independently. You can make changes to the source file from any window.

    Note When you first open a file, if you select the Read Only check box in the Open dialog box, the current window and any duplicates of the window remain read only.

To split a source window

  1. Switch to the source window.

    If there are multiple windows open on the source file, select one of them.

  2. From the Window menu, choose Split.

    The split bar appears.

  3. Drag the split bar to the location you want.

To view a source file in full-screen mode

  1. Switch to the source window.

  2. From the View menu, select Full Screen.

    The source window is displayed in full-screen mode. A small button appears at the top that allows you to reset the screen to regular mode.

    Initially, the toolbars, status bar, and scroll bars are hidden. From the Tools menu, choose Options and then use the Editor tab to control window settings.

To end full-screen mode

  • Press the ESC key.

All files are automatically closed when you quit Visual Fortran or Visual C++ (you will be prompted to save any changed files). You can also close any individual source file without quitting the application.

To close a source file

  1. From the Window menu, choose Windows.

  2. Select one or more files from the Select window box.

  3. Click Close Window.


Frequently Asked Questions: Text Editor

Home Page (Text Editor) | Overview | How Do I ... Topics | Reference

The following are some frequently asked questions (FAQ) about the Text editor.

  • How can I pretty-print my code?

  • How do I replace spaces with tabs?

  • How do I replace tabs with spaces?

  • Can I print my code in color if I have a color printer?

  • How do I grep?

  • How can I find out which shortcut keys are unassigned?

  • What happened to recording and playing back keystrokes?

  • How do I find the current key combination for a command?


How Can I Pretty-Print My Code?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can select sections of code to automatically indent (AutoIndent), but the Text editor does not automatically reformat to merge or break up lines of code.

To quickly indent sections of code, first set the Smart Indent settings you want, then select the code you want to format.

  1. Choose Options from the Tools menu, click the Tabs tab, then change the Smart Indent options

  2. Choose Advanced from the Edit menu, and then choose Format Selection.


How Do I Replace Spaces with Tabs?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

To replace spaces with tabs

  1. Select the text that contains the spaces you want to replace with tabs, or choose Select All from the Edit menu to select the entire file.

  2. From the Edit menu choose Advanced, then click Tabify Selection.


How Do I Replace Tabs with Spaces?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

To replace tabs with spaces

  1. Select the text that contains the tabs you want to replace with spaces, or choose Select All from the Edit menu to select the entire file.

  2. From the Edit menu choose Advanced, then click Untabify Selection.


Can I Print My Code in Color If I Have a Color Printer?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

This is not supported in the current version of the Visual C++ environment.


How Do I grep?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Use the Find in Files command.

To grep

  1. From the File menu, choose Find in Files.

  2. In the Find what box, type the string you want to find, or click the button to the right of the Find what box to select from a list of regular expressions.

  3. In the In files/file types box, specify the types of files in which you want to search.

  4. In the In folder box, specify the folder where you want to begin the search. Use the Browse button to the right of the box to display a dialog where you can navigate to the folder you want.

    Tip You can search recursively through a directory structure by selecting the Look in subfolders check box.

  5. Select any of the other Find options.

  6. Click Find.

Tip You can direct the output from a Find in Files search to a second output window by selecting the Output to pane 2 check box. This allows you to keep the output from two separate Find in Files searches available.


How Can I Find Out Which Shortcut Keys Are Unassigned?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

To find out which shortcut keys are unassigned

  • From the Help menu, select Keyboard, then select All in the list.

This displays all available commands and the shortcut keys assigned to them; any unassigned shortcut keys are not listed.


What Happened to Recording and Playing Back Keystrokes?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

You can record and playback keystrokes and other actions, such as command executions, by using the macro options available in the Visual C++ environment.

To record a macro

  • Select Macro or Record Quick Macro from the Tools menu.

The Macro option provides you the ability to name, save, and later edit the macro you record. The Quick Macro option by-passes the Macro interface, immediately recording your actions and storing them so that you can play them back, until you record another Quick macro.

For more information, see the Developer Studio Objects Home Page.


How Do I Find the Current Key Combination For a Command?

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

To find the current key combination for a command

  1. Choose Keyboard Map from the Help menu.

    This displays the Help Keyboard dialog box.

  2. Choose Edit from the drop-down list, and scroll to the command you want.

    If no key combination is displayed, you can assign one. For more information, see Customizing Keyboard Shortcuts.


Reference: Text Editor

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ

Text editor commands can help you accomplish nearly any editing task. And, with IntelliSense® options such as Automatic Statement Completion, the Text editor practically writes your code for you.

This section describes these Text editor commands and what they can do.

What do you want to do?

View a quick reference to Text editor commands

View a command map for BRIEF emulation

View a command map for Epsilon emulation


Text Editor Command Quick Reference

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

What do you want to know more about?

Bookmark commands

Editing commands

Editor settings commands

File management commands

Find commands

Go To destinations

Navigation commands

Print control codes

Regular expressions

Selection commands


Bookmark Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Command | Description
Bookmarks | Edits or navigates named bookmarks.
BookmarkClearAll | Clears all unnamed bookmarks in the window.
BookmarkNext | Moves to the line containing the next named or unnamed bookmark.
BookmarkPrev | Moves to the line containing the previous named or unnamed bookmark.
BookmarkToggle | Toggles an unnamed bookmark for the current line.

Note These bookmark commands can open files or activate different files in the open Windows list. These commands are an easy way to move between text in a number of different source files.


Editing Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Command | Description
CharTranspose | Swaps characters around the cursor.
Copy | Copies the selection to the Clipboard.
Cut | Removes the selection and copies it to the Clipboard.
Delete | Deletes the selection.
DeleteBack | Deletes the selection, or if there is no selection, deletes the character to the left of the cursor.
DeleteBlankLines | Deletes the blank lines adjacent to the cursor.
DeleteHorizontalSpace | Deletes the spaces and tabs around the cursor.
SelectionFormat | Formats the selection using the smart indent settings.
IndentSelectionToPrev | Indents the selection to line up with the previous line's indention.
LevelCutToEnd | Cuts the text between the cursor and the end of the next bracketed level.
LevelCutToStart | Cuts the text between the cursor and the beginning of the previous bracketed level.
LineCut | Deletes the selected lines and places them on the Clipboard.
LineDelete | Deletes the selected line.
LineDeleteToEnd | Deletes to the end of the current line.
LineDeleteToStart | Deletes to the beginning of the current line.
LineIndent | Indents the selected text right one tab stop.
LineOpenAbove | Opens a new line above the cursor.
LineOpenBelow | Opens a new line below the cursor.
LineTranspose | Swaps the current and previous lines.
LineUnindent | Indents the selected text left one tab stop.
SelectionLowercase | Makes the selection all lowercase.
Paste | Inserts the Clipboard contents at the cursor.
SentenceCut | Deletes the remainder of the sentence.
SelectionTabify | Replaces spaces with tabs in the selection.
SelectionUntabify | Replaces tabs with spaces in the selection.
SelectionUppercase | Makes the selection all uppercase.
WordCapitalize | Makes the first character uppercase.
WordDeleteToEnd | Deletes a word to the right.
WordDeleteToStart | Deletes a word to the left.
WordLowerCase | Makes the current word lowercase.
WordTranspose | Swaps the current and previous words.
WordUpperCase | Makes the current word uppercase.


Editor Settings Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Command | Description
FindToggleCaseSensitivity | Toggles the search case sensitivity.
FindToggleMatchWord | Toggles whole word matching.
FindToggleOvertype | Toggles between inserting and replacing typing.
FindToggleRegExpr | Toggles the regular expression search.
FindToggleAllDocs | Toggles searching across all open documents.
ToggleViewWhitespace | Shows or hides the tab characters.


File Management Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Command | Description
Bookmark | Edits or navigates bookmarks.
Go To | Moves to a specified location.
GoToErrorTag | Moves to the line containing the current error or tag.
GoToNextErrorTag | Moves to the line containing the next error or tag.
GoToPrevErrorTag | Moves to the line containing the previous error or tag.
WindowList | Manages the currently open windows.


Find Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Command | Description
Find | Finds the specified text.
FindBackwardDlg | Opens the Find dialog, searching backward.
FindForwardDlg | Opens the Find dialog, searching forward.
FindNext | Continues the search forward, finding the next occurrence of the specified text.
FindNextWord | Finds the next whole word occurrence of the selected text.
FindPrev | Finds the previous occurrence of the specified text.
FindPrevWord | Finds the previous whole word occurrence of the selected text.
FindRegExpr | Finds the next string using regular expressions.
FindRegExprPrev | Finds the previous string using regular expressions.
FindRepeat | Continues the previous search.
FindReplace | Replaces specific text with different text.
FindReplaceRegExpr | Replaces specific text with different text, using regular expressions.
SearchIncremental | Starts an incremental search forward.
SearchIncrementalBack | Starts an incremental search backward.


Go To Destinations

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Go To What | Additional Selection Criteria | Comments
Address | Enter address expression | Type any valid debugger expression.
Bookmark | Enter bookmark name | Type the bookmark name.
Definition | Enter identifier | Requires browse information.
Error/Tag | Enter error/tag | Select one of the listed error/tags.
Line | Enter line number | Type the line number.
Offset | Enter offset | Type the decimal or hexadecimal number.
Reference | Enter identifier | Type the browse information.


Navigation Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Command | Description
CharLeft | Moves the cursor one character to the left.
CharRight | Moves the cursor one character to the right.
ConditionalDown | Finds the next matching preprocessor condition.
ConditionalUp | Finds the previous matching preprocessor condition.
DocumentEnd | Moves the cursor to the end of the file.
DocumentStart | Moves the cursor to the beginning of the file.
GoToIndentation | Moves the cursor to the end of the indentation.
GoToMatchBrace | Finds the matching brace.
GoToMatchBraceExtend | Finds the matching brace and selects all text between the braces.
Home | Moves the cursor alternately between the beginning of the current line and the beginning of the text on that line.
IndentToPrev | Moves the cursor to the position of the next text that is on the previous line.
LevelDown | Searches forward for the end of the next bracketed level.
LevelUp | Searches back for the beginning of the previous bracketed level.
LineDown | Moves the cursor one line downward.
LineEnd | Moves the cursor to the end of the text on the current line.
LineStart | Moves the cursor to the beginning of the current line.
LineUp | Moves the cursor one line upward.
PageDown | Moves the cursor one page downward.
PageUp | Moves the cursor one page upward.
ParaDown | Moves the cursor forward to the beginning of the next paragraph.
ParaUp | Moves the cursor backward to the beginning of the previous paragraph.
SentenceLeft | Moves the cursor back to the previous beginning of a sentence.
SentenceRight | Moves the cursor forward to the next end of a sentence.
WindowEnd | Moves the cursor to the bottom of the text window.
WindowStart | Moves the cursor to the top of the text window.
WordLeft | Moves the cursor backward one word.
WordRight | Moves the cursor forward one word.

Note The Home command is different from the LineStart command. LineStart always moves the cursor to the first column in the line; Home moves the cursor to different locations depending on the cursor's current location. The Home command moves the cursor to the first non-blank character in the line. However, if the cursor is already located on the first non-blank character, Home moves to the first column of the line.


Print Control Codes

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The print control codes are used in the Header and Footer boxes of the Print Setup dialog box. You can use these control codes to add the information listed in the table below to your source code listings.

To print this information | Use this code
Filename | &f
Page number | &p
Current time | &t
Current date | &d
Left aligned | &l
Centered | &c
Right aligned | &r


Regular Expressions

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Regular Expression | Description
. | (Period.) Any single character.
[ ] | Any one of the characters contained in the brackets, or any of an ASCII range of characters separated by a hyphen (-). For example, b[aeiou]d matches bad, bed, bid, bod, and bud, and r[eo]+d matches red, rod, reed, and rood, but not reod or roed. x[0-9] matches x0, x1, x2, and so on. If the first character in the brackets is a caret (^), then the regular expression matches any characters except those in the brackets.
^ | The beginning of a line.
$ | The end of a line.
\( \) | Indicates a tagged expression to retain for replacement purposes. If the expression in the Find What text box is \(lpsz\)BigPointer, and the expression in the Replace With box is \1NewPointer, all selected occurrences of lpszBigPointer are replaced with lpszNewPointer. Each occurrence of a tagged expression is numbered according to its order in the Find What text box, and its replacement expression is \n, where 1 corresponds to the first tagged expression, 2 to the second, and so on. You can have up to nine tagged expressions.
\~ | No match if the following character or characters occur. For example, b\~a+d matches bbd, bcd, bdd, and so on, but not bad. You can use this expression to prefix a group of characters you want to exclude, which is useful for excluding matches of particular words. For example, foo\~\(lish\) matches "foo" in "food" and "afoot" but not in "foolish."
\{c\!c\} | Any one of the characters separated by the alternation symbol (\!). For example, \{j\!u\}+fruit finds jfruit, jjfruit, ufruit, ujfruit, uufruit, and so on.
* | None or more of the preceding characters or expressions. For example, ba*c matches bc, bac, baac, baaac, and so on.
+ | At least one or more of the preceding characters or expressions. For example, ba+c matches bac, baac, baaac, but not bc.
\{\} | Any sequence of characters between the escaped braces. For example, \{ju\}+fruit finds jufruit, jujufruit, jujujufruit, and so on. Note that it will not find jfruit, ufruit, or ujfruit, because the sequence ju is not in any of those strings.
[^] | Any character except those following the caret (^) character in the brackets, or any of an ASCII range of characters separated by a hyphen (-). For example, x[^0-9] matches xa, xb, xc, and so on, but not x0, x1, x2, and so on.
\:a | Any single alphanumeric character [a – zA – Z0 – 9].
\:b | Any white-space character. The \:b finds tabs and spaces. There is no alternate syntax to express :b.
\:c | Any single alphabetic character [a – zA – Z].
\:d | Any decimal digit [0 – 9].
\:n | Any unsigned number \{[0-9]+\.[0-9]*\![0-9]*\.[0-9]+\![0-9]+\}. For example, \:n should match 123, .45, and 123.45.
\:z | Any unsigned decimal integer [0 – 9]+.
\:h | Any hexadecimal number [0 – 9a – fA – F]+.
\:i | Any Fortran identifier [a – zA – Z_$][a – zA – Z0 – 9_$]+.
\:w | Any alphabetic string [a – zA – Z]+. The string need not be bounded by white space or appear at the beginning or the end of a line.
\:q | Any quoted string \{"[^"]*"\!'[^']*'\}.
\ | Removes the pattern match characteristic in the Find What text box from the special characters listed above. For example, 100$ matches 100 at the end of a line, but 100\$ matches the character string 100$ anywhere on a line.


Selection Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Command | Description
CharLeftExtend | Extends the selection one character to the left.
CharRightExtend | Extends the selection one character to the right.
ConditionalDownExtend | Selects to the next matching preprocessor condition.
ConditionalUpExtend | Selects to the previous matching preprocessor condition.
DocumentEndExtend | Extends the selection to the end of the file.
DocumentStartExtend | Extends the selection to the beginning of the file.
HomeExtend | Extends the selection alternately between the start of the current line and the start of the text on that line.
LineDownExtend | Extends the selection one line downward.
LineEndExtend | Extends the selection to the end of the text on the current line.
LineUpExtend | Extends the selection one line upward.
PageDownExtend | Extends the selection one page downward.
PageUpExtend | Extends the selection one page upward.
SelectAll | Selects the entire document.
SelectChar | Starts the character-selection mode. While this mode is active, all other navigation commands will select the characters from the position where the command was executed to the current cursor location.
SelectLine | Starts the line-selection mode. While this mode is active, all other navigation commands will select lines from the position where the command was executed to the current cursor location.
SelectColumn | Starts the column-select mode. In column-select mode, the navigation keys act as if virtual space is enabled.
WordLeftExtend | Extends the selection backward one word.
WordRightExtend | Extends the selection forward one word.


BRIEF Emulation Command Quick Reference

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The BRIEF emulation provides BRIEF default key bindings, caret display, text selection, editing commands, and regular expressions.

Note The entire set of emulation commands is available to each editor. For more information, see Customizing Keyboard Shortcuts.

What do you want to know more about?

Block and mark commands

Buffer commands

Cursor movement commands

Editing text commands

Help commands

Macros, playback, and remember commands

Regular expressions

Saving and exiting commands

Scrap commands

Search and translate commands

Special commands

Undo and redo commands

Window commands


Block and Mark Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Column Mark | SelectColumn
Drop Bookmark | BookmarkDrop(BRIEF)
Indent Block | LineIndent
Jump Bookmark | Bookmarks
Line Mark | SelectLine
Lower Case Block | SelectionLowercase
Mark/Unmark | SelectChar
Noninclusive Mark | SelectCharInclusive
Outdent Block | LineUnindent
Print Block | FilePrint
Swap Cursor and Mark | SelectSwapAnchor
Upper Case Block | SelectionUppercase


Buffer Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Delete Current Buffer | FileClose
Edit File | FileOpen
Next Buffer | WindowNext
Previous Buffer | WindowPrevious
Read File into Buffer | InsertFile


Cursor Movement Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Back Tab | (Use the SHIFT+TAB keys)
Beginning of Line | Home(BRIEF)
Cursor Movement | (Use the arrow keys)
End of Buffer | DocumentEnd
End of Line | End(BRIEF)
End of Window | WindowEnd
Go to Line | GoTo
Left Side of Window | WindowLeftEdge
Next Character | (Use the right arrow key)
Next Word | WordRight
Page Down | PageDown
Page Up | PageUp
Previous Character | (Use the left arrow key)
Previous Word | WordLeft
Right Side of Window | WindowRightEdge
Scroll Buffer Down in Window | WindowScrollUp
Scroll Buffer Up in Window | WindowScrollDown
Tab | (Use the TAB key)
Top of Buffer | Home(BRIEF)
Top of Window | WindowStart


Editing Text Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Backspace | (Use the BACKSPACE key)
Delete | (Use the DELETE key)
Delete Line | LineDelete
Delete Next Word | WordDeleteToEnd
Delete Previous Word | WordDeleteToStart
Delete to Beginning of Line | LineDeleteToStart
Delete to End of Line | LineDeleteToEnd
Enter | (Use the ENTER key)
Insert Mode Toggle | FindToggleOvertype
Open Line | LineOpenBelow
Quote | InsertQuoted


Help Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Help | (Common help function)


Macros, Playback, and Remember Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

See the Automation Overview for complete information.


Regular Expressions with BRIEF Emulation

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

?
Any single character.

[ ]
Any one of the characters contained in the brackets, or any of an ASCII range of characters separated by a hyphen (-). For example, b[aeiou]d matches bad, bed, bid, bod, and bud, and r[eo]+d matches red, rod, reed, and rood, but not reod or roed. For numbers, x[0-9] matches x0, x1, x2, and so on. If the first character in the brackets is a tilde (~), then the regular expression matches any characters except those in the brackets.

%
The beginning of a line.

$
The end of a line.

{ }
Indicates a tagged expression to retain for replacement purposes. If the expression in the Find What text box is {lpsz}BigPointer, and the expression in the Replace With box is \0NewPointer, all selected occurrences of lpszBigPointer are replaced with lpszNewPointer. Each occurrence of a tagged expression is numbered according to its order in the Find What text box, and its replacement expression is \n, where 0 corresponds to the first tagged expression, 1 to the second, and so on. You can have up to ten tagged expressions.

~
Not the following character. For example, b~ad matches bbd, bcd, bdd, and so on, but not bad.

{c|c}
Any one of the characters separated by the alternation symbol (|). For example, {j|u}+fruit finds jfruit, jjfruit, ufruit, ujfruit, uufruit, and so on.

@
None or more of the preceding characters or expressions. For example, ba@c matches bc, bac, baac, baaac, and so on.

+
At least one or more of the preceding characters or expressions. For example, ba+c matches bac, baac, and baaac, but not bc.

[ ]
Any sequence of characters between the brackets. For example, [ju]+fruit finds jufruit, jujufruit, jujujufruit, and so on. Note that it will not find jfruit, ufruit, or ujfruit because the sequence ju is not in any of those strings.

[~]
Any character except those following the tilde character (~) in the brackets, or any of an ASCII range of characters separated by a hyphen (-). For example, x[~0-9] matches xa, xb, xc, and so on, but not x0, x1, x2, and so on.

[a-zA-Z0-9]
Any single alphanumeric character.

[\x09\]+
Any white-space character.

[a-zA-Z]
Any single alphabetic character.

[0-9]
Any decimal digit.

[0-9a-fA-F]+
Any hexadecimal number.

{[0-9]+.[0-9]@}|{[0-9]@.[0-9]+}|{[0-9]+}
Any unsigned number. For example,
{[0-9]+.[0-9]@}|{[0-9]@.[0-9]+}|{[0-9]+} should match 123, .45, and 123.45.

[0-9]+
Any unsigned decimal integer.

[a-zA-Z_$][a-zA-Z0-9_$]@
C/C++ identifier.

[a-zA-Z]+
Any English word (that is, any string of alphabetic characters).

"[~"]@"
Any quoted string.

\
Removes the pattern match characteristic in the Find What text box from the special characters listed above. For example, 100$ matches 100 at the end of a line, but 100\$ matches the character string 100$ anywhere on a line.


Saving and Exiting Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Exit | FileExit
Write | FileSave
Write All and Exit | FileSaveAllExit


Scrap Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Copy to Scrap | Copy
Cut to Scrap | Cut
Paste from Scrap | Paste


Search and Translate Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Case Sensitivity Toggle | FindToggleCaseSensitivity
Incremental Search | SearchIncremental
Regular Expressions Toggle | FindToggleRegExpr
Search Again | FindRepeat
Search Backward | FindPrev
Search Forward | Find
Translate Again | FindReplace
Translate Forward | FindReplace


Special Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Go To Routine | Browse
Next Error | GoToNextErrorTag
Repeat | SetRepeatCount


Undo and Redo Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Undo | Undo
Redo | Redo


Window Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

BRIEF Command | Visual C++ Environment Command
Center Line in Window | WindowScrollToCenter
Change Window | WindowSwitchPaneUp, WindowSwitchPaneDown, WindowSwitchPaneLeft, WindowSwitchPaneRight (A default key binding is not provided for this command)
Create Window | WindowSplitHorizontal, WindowSplitVertical
Delete Window | WindowDeleteRowUp, WindowDeleteRowDown, WindowDeleteColumnLeft, WindowDeleteColRight
Line to Bottom of Window | WindowScrollToBottom
Line to Top of Window | WindowScrollToTop
Quick Window Switch | WindowSwitchPaneUp, WindowSwitchPaneDown, WindowSwitchPaneLeft, WindowSwitchPaneRight
Resize Window | WindowSplit
Zoom Window Toggle | WindowMaximize


Epsilon Emulation Command Map

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

The Epsilon emulation provides Epsilon default key bindings, caret display, text selection, and the following general editing commands.

Regular expressions are also available with the Epsilon emulation. See Regular Expressions with Epsilon Emulation for a list.

Note The entire set of emulation commands is available to each editor. For more information, see Customizing Keyboard Shortcuts.

What do you want to know more about?

Bookmark commands

Buffer commands

File commands

Help commands

Indenting commands

Inserting and deleting commands

Keyboard macros commands

Killing and yanking commands

Miscellaneous commands

Moving around commands

Paragraph commands

Parenthetic expressions commands

Regular expressions

Running programs commands

Searching and replacing commands

Sentence commands

Tag commands

Transposing commands

Undo commands

Window commands

Word commands


Bookmark Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
set-bookmark | BookmarkDrop(Epsilon)
jump-to-last-bookmark | BookmarkJumpToLast(Epsilon)
set-named-bookmark | Bookmarks
jump-to-named-bookmark | Bookmarks


Buffer Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
select-buffer | WindowList


File Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
find-file | FileOpen
save-file | FileSave
write-file | FileSaveAs
insert-file | InsertFile
save-all-buffers | FileSaveAs


Help Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
help | (Common help function)


Indenting Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
to-indentation | GoToIndentation
indent-previous | (Use the TAB key)
indent-region | IndentSelectionToPrev
center-line | WindowScrollToCenter
tabify-region | SelectionTabify
untabify-region | SelectionUntabify
indent-under | IndentToPrev


Inserting and Deleting Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
quoted-insert | InsertQuoted
open-line | LineOpenAbove
backward-delete-character | (Use the BACKSPACE key)
delete-character | Delete
delete-horizontal-space | DeleteHorizontalSpace
delete-blank-lines | DeleteBlankLines
overwrite-mode | (Use the INSERT key)


Keyboard Macro Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

See the Automation Overview for complete information.


Killing and Yanking Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
set-mark | StreamSelectExclusive
highlight-region | SelectHighlight
exchange-point-and-mark | SelectSwapAnchor
kill-line | LineCut
kill-region | CutSelection
copy-region | Copy
yank | Paste
append-next-kill | AppendNext
rectangle-mode | SelectColumn


Miscellaneous Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
abort | Cancel
exit | FileExit
argument | SetRepeatCount
goto-line | GoTo


Moving Around Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
beginning-of-line | Home
end-of-line | LineEnd
down-line | LineDown
up-line | LineUp
forward-character | CharRight
backward-character | CharLeft
center-window | WindowScrollToCenter
next-page | PageDown
previous-page | PageUp
scroll-up | WindowScrollUp
scroll-down | WindowScrollDown
goto-beginning | DocumentStart
goto-end | DocumentEnd
beginning-of-window | WindowStart
end-of-window | WindowEnd


Paragraph Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
forward-paragraph | ParaDown
backward-paragraph | ParaUp
mark-paragraph | SelectPara


Parenthetic Expressions Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
find-delimiter | GoToMatchBrace
forward-level | LevelDown
backward-level | LevelUp
kill-level | LevelCutToEnd
backward-kill-level | LevelCutToStart


Regular Expressions with Epsilon Emulation

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

.
Any single character.

[ ]
Any one of the characters contained in the brackets, or any of an ASCII range of characters separated by a hyphen (-). For example, b(aeiou)d matches bad, bed, bid, bod, and bud, and r(eo)+d matches red, rod, reed, and rood, but not reod or roed. For numbers, x(0-9) matches x0, x1, x2, and so on. If the first character in the brackets is a caret (^), then the regular expression matches any characters except those in the brackets.

^
The beginning of a line.

$
The end of a line.

( )
Indicates a tagged expression to retain for replacement purposes. If the expression in the Find What text box is (lpsz)BigPointer, and the expression in the Replace With box is #1NewPointer, all selected occurrences of lpszBigPointer are replaced with lpszNewPointer. Each occurrence of a tagged expression is numbered according to its order in the Find What text box, and its replacement expression is #n, where 1 corresponds to the first tagged expression, 2 to the second, and so on. You can have up to nine tagged expressions.

~
Not the following character. For example, b~ad matches bbd, bcd, bdd, and so on, but not bad.

(c|c)
Any one of the characters separated by the alternation symbol (|). For example, (j|u)+fruit finds jfruit, jjfruit, ufruit, ujfruit, uufruit, and so on.

*
None or more of the preceding characters or expressions. For example, ba*c matches bc, bac, baac, baaac, and so on.

+
At least one or more of the preceding characters or expressions. For example, ba+c matches bac, baac, and baaac, but not bc.

[^]
Any character except those following the caret (^) in the brackets, or any of an ASCII range of characters separated by a hyphen (-). For example, x[^0-9] matches xa, xb, xc, and so on, but not x0, x1, x2, and so on.

[a-zA-Z0-9]
Any single alphanumeric character.

[<tab>]+
Any white-space character.

[a-zA-Z]
Any single alphabetic character.

{0-9]
Any decimal digit.

[0-9a-fA-F]+
Any hexadecimal number.

([0-9]+.[0-9]*|[0-9]*.[0-9]+|[0-9]+)
Any unsigned number. For example,
([0-9]+.[0-9]*|[0-9]*.[0-9]+|[0-9]+) should match 123, .45, and 123.45.

[0-9]+
Any unsigned decimal integer.

[a-zA-Z_$][a-zA-Z0-9_$]*
C/C++ identifier.

[a-zA-Z]+
Any English word (that is, any string of alphabetic characters).

"[~"]*"
Any quoted string.

\
Removes the pattern match characteristic in the Find What text box from the special characters listed above. For example, 100$ matches 100 at the end of a line, but 100\$ matches the character string 100$ anywhere on a line.


Running Programs Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
next-error | GoToNextErrorTag (A default key binding is not provided for this command.)
previous-error | GoToPrevErrorTag (A default key binding is not provided for this command.)


Searching and Replacing Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
incremental-search | SearchIncremental
reverse-incremental-search | SearchIncrementalBack
regex-search | FindRegExpr
reverse-regex-search | FindRegExprPrev
grep | FileFindInFiles
next-match | FindNext
previous-match | FindPrev
replace-string | FindReplace
query-replace | FindReplace
regex-replace | FindReplaceRegExpr
word-mode, regular-expression-mode, case-sensitive-mode, and incremental-mode | (These commands are available only in incremental search mode, not in dialog mode. The commands are not key bindable)


Sentence Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
forward-sentence | SentenceRight
backward-sentence | SentenceLeft
kill-sentence | SentenceCut


Tag Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
goto-tag | Browse
pluck-tag | BrowseGoToDefinition


Transposing Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
transpose-characters | CharTranspose
transpose-words | WordTranspose
transpose-lines | LineTranspose


Undo Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
undo | Undo
redo | Redo
undo-changes | UndoChanges
redo-changes | RedoChanges


Window Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
one-window | WindowSinglePane
split-window | WindowSplitHorizontal
split-window-vertically | WindowSplitVertical
kill-window | WindowKillPane
zoom-window | WindowMaximize
move-to-window | WindowNextPane
next-window | WindowCycle
previous-window | WindowPrevious


Word Commands

Home Page (Text Editor) | Overview | How Do I ... Topics | FAQ | Reference

Epsilon Command | Visual C++ Environment Command
forward-word | WordRight
backward-word | WordLeft
backward-kill-word | WordDeleteToStart
kill-word | WordDeleteToEnd
transpose-words | WordTranspose
capitalize-word | WordCapitalize
lowercase-word | WordLowerCase
uppercase-word | WordUpperCase


Home Page: Resource Editors

A resource is an interface element that the user gains information from or manipulates to perform an action. A Resource editor is a specialized environment for creating or changing resources.

For information about Resource editors

  • Overviews

  • How Do I ... Topics

Resource Editor Home Pages

  • Accelerator Editor Home Page

  • Binary Editor Home Page

  • Dialog Editor Home Page

  • Graphics Editor Home Page

  • HTML Resource Home Page

  • Menu Editor Home Page

  • String Editor Home Page

  • Toolbar Editor Home Page

  • Version Information Editor Home Page

Related Home Pages

  • Text Editor Home Page

  • Adding User-Interface Features Home Page

  • Using the Resource Compiler (Platform SDK)


Overview: Resource Editors

Home Page (Resource Editors) | How Do I ... Topics

The Resource editors share techniques and interfaces to create and modify application resources quickly and easily. You can use the Resource editors to create new resources, modify existing resources, copy existing resources, and delete old resources. The Resource editors are functionally consistent for ease of use.

You can edit all of the Microsoft Windows resources that your application uses. These resources include:

  • Accelerator tables

  • Binary data information

  • Bitmaps, icons, and other image files

  • Cursors

  • Dialog boxes

  • HTML pages

  • Menus

  • String tables

  • Toolbar resources

  • Version information

When you create or open a resource, the appropriate editor opens automatically. You can also open a resource (.rc) file in text format.

The Resource editors have many commands and procedures in common. For example, once you learn how to create and open a dialog box, you know the steps for creating and opening any of the other resources.

What do you want to know more about?

  • Using the Resource Compiler (Platform SDK)

What do you want to do?

View resources

Create new resources

Use resource templates

Copy resources

Edit resources

Open a resource file as text

Use property pages


How Do I ... Topics: Resource Editors

Home Page (Resource Editors) | Overview

The Resource editors share techniques and interfaces that enable you to create and modify application resources quickly and easily. You can use the Resource editors to create new resources, modify existing resources, copy existing resources, and delete old resources. The Resource editors are functionally consistent for ease of use.

What do you want to do?

View resources

Create new resources

Use resource templates

Copy resources

Edit resources

Open a resource file as text

Use property pages


Viewing Resources

Home Page (Resource Editors) | Overview | How Do I ... Topics

You can access your project resources from the ResourceView pane of the Project Workspace. Select the ResourceView tab in the Project Workspace if ResourceView is not the top-most pane.

To view a Resource

  1. From the ResourceView pane, expand the folder for the project whose resources you want to view.

  2. Expand the folder containing the resource you wish to view.

    For example, if you want to view a dialog resource, expand the Dialog folder.

  3. Double-click the resource, for example, IDD_ABOUTBOX.

The resource opens in the appropriate editor. For example, for dialog resources, the resource opens inside the Dialog editor.

You can also open a resource file as text.


Creating a New Resource

Home Page (Resource Editors) | Overview | How Do I ... Topics

You can create a resource as a new default resource, or as a resource patterned after a template. Creating a new default resource is as easy as clicking the appropriate button on the Resource toolbar. For more information on creating a resource from a template file, see Using Resource Templates.

When you create a resource, it is assigned a unique symbol name and value. If you need to change the symbol value, you can use the ID box on the resource’s property page. For more information on the property page, use the ? button.

To create a new resource

  1. From the Insert menu, choose Resource.

  2. Select a resource from the Resource Type list box and click New.

    The visual development environment creates the new resource and assigns it a unique ID, for example, IDD_Dialog1. You will probably want to customize this ID.


Using Resource Templates

Home Page (Resource Editors) | Overview | How Do I ... Topics

A template file is a copy of an edited resource that you can use to create additional resources. Resource templates save time in developing additional resources or groups of resources that share a particular feature.

For instance, you might want to include a Help button and an icon of a company logo in several dialog boxes. Create a new template, and customize that template dialog box with the logo and Help button. Now, when you want to create a new dialog box, you can choose this template dialog box with the features already added.

What do you want to do?

Create templates for resources

Create new resources from templates

To create templates for resources

  1. From the Insert menu, choose Resource.

  2. Select a resource from the Resource Type box, and click New.

    -or-

    Copy a resource from another resource file. For more information, see Copying Resources.

  3. Modify the resource.

    This resource, once saved as a template, can be copied numerous times to save effort on positioning controls, inserting text, and so on.

  4. From the File menu, choose Save As.

  5. In the Save File As Type box, select Resource Template (*.rct).

  6. Select the Template subdirectory under the SharedIDE subdirectory in your Visual C++ installation.

  7. Click Save to save the template. Repeat for any remaining templates.

To create new resources from the templates

  1. From the Insert menu, choose Resource.

  2. Select a resource type. Double-click the resource icon to create a default resource template object.

    -or-

    Click the plus sign (+) next to a resource to move down the hierarchy to the template files grouped under that resource. Then double-click the specific template file under that resource to create a resource template object.


Copying Resources

Home Page (Resource Editors) | Overview | How Do I ... Topics

You can copy resources exactly or copy them from a template (see Using Resource Templates).

What do you want to do?

Copy an existing resource exactly

Copy resources from one file to another

To copy an existing resource exactly

  1. Select the resource you want to copy.

  2. From the Edit menu, choose Copy and then Paste.

The easiest way to copy resources from either an existing resource or an executable file to your current resource file is to have both .rc or .rct files open at the same time. Then use the drag-and-drop method to move items from one file to another.

Note Visual Fortran provides samples that use resource files. You can use the samples and resource files in your own application.

To copy resources from one file to another

  1. Open both files. Make sure both resource files are visible at the same time.

  2. In the source file, select the resource you want to copy.

  3. Hold down the CTRL key and drag the resource to the target file.

    Dragging the resource without holding down the CTRL key moves the resource rather than copying it.

Note To avoid conflicts with symbol names or values in the existing file, the visual development environment may change the transferred resource’s symbol value, or symbol name and value, when you copy it to the new file.


Editing Resources

Home Page (Resource Editors) | Overview | How Do I ... Topics

The editors for the different resources share many of the same procedures. More information about editing individual resources is available from the Home Page of each resource.

Note You can also edit a resource by opening it in text format.

To open an existing resource for editing

  • Select the resource you want to edit, and press ENTER.

To save an edited resource file

  • From the File menu, choose Save. The resource is saved using its current name.

    -or-

  1. From the File menu, choose Save As.

  2. In the Drives box, select the target drive.

  3. In the Directories box, select the directory path.

  4. In the File Name box, type the name for the file.

  5. Click OK. The resource is saved using the name you supply.

To delete an existing resource

  1. Select the resource you want to delete.

  2. From the Edit menu, choose Delete.


Opening a Resource File as Text

Home Page (Resource Editors) | Overview | How Do I ... Topics

There may be times when you want to view the contents of your project resource (.rc) file without opening a resource, such as a dialog box, inside its specific resource editor. For example, you may want to search for a string across all dialog boxes in the resource file without having to open each one separately.

You can easily open the resource file in text format to view all the resources it contains, and perform global operations supported by the Text editor.

To open a resource file as text

  1. From the File menu choose Open, and navigate to the resource file you want to view in text format.

  2. From the Open As drop-down list, select Text.


Using Property Pages

Home Page (Resource Editors) | Overview | How Do I ... Topics

Property pages control the appearance and the behavior of resources and differ according to their purpose. For example, an image resource property page contains information on the ID, language, condition, and filename, as well as a preview of the resource. But a property page for a push-button control in a dialog box contains several tabs of information, each with many style bits to modify the control’s behavior.

Note Whenever you make a change on a property page, it is made immediately. You cannot cancel any changes made on a property page.

Manipulating a Property Page

You can use any of the shortcut keys associated with the Text editor to cut, copy, and paste text. In general, these shortcut keys can be used in any edit control on the property page.

You can control the behavior of the Properties window to suit your working style or the nature of the resource editing task. Use the Pushpin button in the upper-left corner of the property page.

Button position | Result
 | The Properties window stays visible even when you are working in another window. This is convenient if, during an editing session, you want to move back and forth frequently between setting properties and editing objects. Pressing ENTER after you change a value in the Properties window returns you to the editing window but leaves the Properties window visible.
 | The Properties window is dismissed by pressing ENTER or ESC. This is useful if you want to concentrate on working in an editing window but need to bring up the Properties window briefly to change one or two values.


Home Page: Accelerator Editor

The Accelerator editor allows you to add, delete, change, and browse the accelerator key assignments in your project. You can use the Find command to locate specific accelerator keys in the accelerator table. You can also change the properties of several accelerator keys at the same time.

  • Overviews

  • How Do I ... Topics

For information about the Accelerator editor

  • Adding an entry to an accelerator table

  • Deleting an entry from an accelerator table

  • Moving or copying an accelerator table entry

Related Home Pages

  • Resource Editors Home Page


Overview: Accelerator Editor

Home Page (Accelerator Editor) | How Do I ... Topics

An accelerator table is a Windows resource that contains a list of accelerator keys (also known as shortcut keys) and the command identifiers that are associated with them. A program can have more than one accelerator table.

Normally, accelerators are used as keyboard shortcuts for program commands that are also available on a menu or toolbar. However, you can use the accelerator table to define key combinations for commands that don’t have a user-interface object associated with them.

With the Accelerator editor, you can:

  • Add, delete, change, and browse the accelerator key assignments in your project.

  • View and change the resource identifier associated with each entry in the accelerator table. The identifier is used to reference each accelerator table entry in program code.

  • Associate an accelerator key with a menu item.

  • Find one or more accelerator keys in the accelerator table, and use regular expressions with the Find command to locate an accelerator key that matches a pattern.

  • Select multiple accelerator keys and change their properties at one time.

Tip While using the Accelerator editor, in many instances, you can click the right mouse button to display a shortcut menu of frequently used commands. The commands available depend on what the pointer is pointing to. For example, if you click while pointing to an accelerator entry, the shortcut menu shows the Cut, Copy, New Accelerator, and Properties commands.

Note Windows does not allow the creation of empty accelerator tables. If you create an accelerator table with no entries, it is deleted automatically when you exit the visual development environment.

For information about common resource edit procedures such as creating new resources, opening existing resources, and deleting resources, see Resource Editors How Do I ... Topics.

What do you want to know more about?

Setting accelerator properties

Associating an accelerator key with a menu item

What do you want to do?

Edit an accelerator table


About Setting Accelerator Properties

Home Page (Accelerator Editor) | Overview | How Do I ... Topics

The Accel Properties page allows you to control the features of each accelerator key. By default, the property page is dismissed when it does not have focus. If you want the property page to remain on the screen, even when it does not have focus, click the Pushpin button in the upper-left corner of the window.

You can also select several accelerator keys together and change their properties at one time.

The following are legal entries in the Key box of an accelerator property page:

  • An integer between 0 and 255 in decimal, hexadecimal, or octal format. The setting of the Type property determines if the number is an ASCII or virtual key value.

  • Single-digit numbers are always interpreted as the corresponding key, rather than as ASCII values. To enter an ASCII value from 0 to 9, precede it with two zeros (for example, 006).

  • A single keyboard character. Uppercase A – Z or the numbers 0 – 9 can be either ASCII or virtual key values; any other character is ASCII only.

  • A single keyboard character in the range A – Z (uppercase only), preceded by a caret (^) (for example, ^C). This enters the ASCII value of the key when it is pressed with the CTRL key held down.

    Note When entering an ASCII value, the CTRL and SHIFT modifiers on the property page are not available. You cannot use a control-key combination entered with a caret to create a virtual accelerator key.

  • Any valid virtual key identifier. The Key box on the property page contains a list of standard virtual key identifiers.

Tip Another way to define an accelerator key is to click the Next Key Typed button in the property page and then press any of the keys on the keyboard.


About Associating an Accelerator Key with a Menu Item

Home Page (Accelerator Editor) | Overview | How Do I ... Topics

Many times, you want a menu item and a keyboard combination to issue the same program command. You do this by assigning the same resource identifier to the menu item and to an entry in your application’s accelerator table. You then edit the menu item’s caption to show the name of the accelerator. For more information on menu items and accelerator keys, see Associating a Menu Item with an Accelerator Key.


How Do I ... Topics: Accelerator Editor

Home Page (Accelerator Editor) | Overview

What do you want to know more about?

Setting accelerator properties

Associating an accelerator key with a menu item

What do you want to do?

Edit an accelerator table


Editing an Accelerator Table

Home Page (Accelerator Editor) | Overview | How Do I ... Topics

What do you want to do?

Add an entry to an accelerator table

Delete an entry from an accelerator table

Move or copy an accelerator table entry

Find an entry in an accelerator table

Change the properties of multiple accelerator keys

To add an entry to an accelerator table

  1. Select the new-item box at the end of the list.

  2. Type the key you want to use as an accelerator.

    The Accel Properties page appears, with the focus in the Key box.

  3. Select an ID from the drop-down list in the ID box.

  4. Change the modifier and type, if necessary.

    The modifier specifies whether the key you chose is a combination formed with CTRL, ALT, or SHIFT. The type indicates whether the key is an ASCII or a virtual key value.

  5. Press ENTER.

Note Make sure all accelerators you define are unique. When duplicate accelerator keys are assigned, only the first one works correctly.

To delete an entry from an accelerator table

  1. Select the entry you want to delete. Hold down the CTRL or SHIFT key while clicking to select multiple entries.

  2. From the Edit menu, choose Delete.

To move or copy an accelerator table entry to another resource script file

  1. Open the Accelerator editor windows in both resource script files.

  2. Select the entry you want to move.

  3. From the Edit menu, choose Copy or Cut.

  4. Select an entry in the target resource script file.

  5. From the Edit menu, choose Paste.

To find an entry in an accelerator table

  1. From the Edit menu, choose Find.

  2. In the Find What box, select a previous search string from the drop-down list, type the accelerator key you want to find (for example, ID_ACCEL1), or type a regular expression to match a pattern.

    Tip Click the button to the right of the Find What box to display a list of regular search expressions. When you select an expression from this list, it is substituted as the search text in the Find What box. If you use regular expressions, be sure the Regular Expression check box is selected.

  3. Select any of the Find options.

  4. Click Find Next.

To change the properties of multiple accelerator keys

  1. Select the accelerator keys you want to change by holding down the CTRL key as you click each one.

  2. From the View menu, choose Properties.

The Multiple Selection Properties page displays. Changes you make on this page are reflected on each item selected. If you need to undo a change, choose Undo from the Edit menu. The change is undone on each item selected.


Home Page: Binary Editor

The Binary editor allows you to edit resources at the binary level in either hexadecimal or ASCII format. You can use the Find command to search for either ASCII strings or hexadecimal bytes.

  • Overviews

  • How Do I ... Topics

For information about the Binary Editor

  • Creating a new custom or data resource

  • Opening a resource for binary editing

  • Editing binary data

Related Home Pages

  • Resource Editors Home Page


Overview: Binary Editor

Home Page (Binary Editor) | How Do I ... Topics

The Binary editor allows you to edit a resource at the binary level in either hexadecimal or ASCII format. You can also use the Find command to search for either ASCII strings or hexadecimal bytes, and use regular expressions with the Find command to match a pattern. You should use the Binary editor only when you need to view or make minor changes to custom resources or resource types not supported by the visual development environment.

Caution Editing resources such as dialog boxes, images or menus in the Binary editor is dangerous. Incorrect editing could corrupt the resource, making it unreadable in its native editor.

Tip While using the Binary editor, in many instances, you can click the right mouse button to display a shortcut menu of resource-specific commands. The commands available depend on what the pointer is pointing to. For example, if you click while pointing to the Binary editor with selected hexadecimal values, the shortcut menu shows the Cut, Copy, and Paste commands.

What do you want to do?

Create a new custom or data resource

Open a resource for binary editing

Edit binary data

Find binary data


How Do I ... Topics: Binary Editor

Home Page (Binary Editor) | Overview

What do you want to do?

Create a new custom or data resource

Open a resource for binary editing

Edit binary data

Find binary data


Creating a New Custom or Data Resource

Home Page (Binary Editor) | Overview | How Do I ... Topics

You can create a new custom or data resource by placing the resource in a separate file using normal resource script (.rc) file syntax, and then including the file with the Resource Includes command on the View menu.

To create a new custom or data resource

  1. Create an .rc file that contains the custom or data resource.

    You can type custom data in an .rc file as null-terminated quoted strings, or as integers in decimal, hexadecimal, or octal format. For more information, see the Win32 Software Development Kit documentation.

  2. From the View menu, choose Resource Includes.

  3. In the Compile-Time Directives box, type a #include statement that gives the name of the file containing your custom resource. For example:
    #include mydata.rc

    Make sure the syntax and spelling of what you type are correct. The contents of the Compile-Time Directives box are inserted into the resource script file exactly as you typed them.

  4. Click OK to record your changes.


Opening a Resource for Binary Editing

Home Page (Binary Editor) | Overview | How Do I ... Topics

To open a resource for binary editing

  1. Open the project or resource script containing the resource to be edited.

  2. Select the specific resource file you want to edit.

  3. Click the right mouse button and choose Open Binary Data.

If you want to use the Binary editor on a resource already being edited in another editor window, close the other editor window first.

Note If you use the ResourceView window to open a resource with a format that the visual development environment does not recognize (such as a VERSION, RCDATA, or custom resource), the resource is automatically opened in the Binary editor.


Editing Binary Data

Home Page (Binary Editor) | Overview | How Do I ... Topics

To edit a resource in the Binary editor

  1. Select the byte you want to edit.

    The TAB key moves the focus between the hexadecimal and ASCII sections of the Binary editor. You can use the PAGE UP and PAGE DOWN keys to move through the resource one screen at a time.

  2. Type the new value.

    The value changes immediately in both the hexadecimal and ASCII sections.


Finding Binary Data

Home Page (Binary Editor) | Overview | How Do I ... Topics

You can search for either ASCII strings or hexadecimal bytes. For example, to find “Hello,” you can search for either the string “Hello” or for “48 65 6C 6C 6F” (the hexadecimal equivalent).

To find binary data

  1. From the Edit menu, choose Find.

  2. In the Find What box, select a previous search string from the drop-down list, type the data you want to find, or type a regular expression to match a pattern.

    Tip Click the button to the right of the Find What box to display a list of regular search expressions. When you select an expression from this list, it is substituted as the search text in the Find What box. If you use regular expressions, be sure the Regular Expression check box is selected.

  3. Select any of the Find options.

  4. Click Find Next.


Home Page: Dialog Editor

The Dialog editor helps with the creation or editing of a dialog box template or resource.

  • Overviews

  • How Do I ... Topics

For information about the Dialog editor

  • Adding or editing controls in a dialog box

  • Formatting the layout of a dialog box

  • Editing a dialog box

  • Testing a dialog box

Related Home Pages

  • Resource Editors Home Page


Overview: Dialog Editor

Home Page (Dialog Editor) | How Do I ... Topics

Use the Dialog editor to create or edit dialog boxes. You can store a dialog box as a template so you can reuse it. And you can easily switch between designing the dialog box and editing the code that implements it.

With the Dialog editor, you can:

  • Add, arrange, or edit controls.

  • Change the tab order.

  • Use guides in the dialog box layout.

  • Test a dialog box.

You can use resource templates to create dialog boxes to use later, or copy dialog box resources. For more information, see Using Resource Templates.

Tip While using the Dialog editor, in many instances you can click the right mouse button to display a shortcut menu of frequently-used commands. The commands available depend on what the pointer is pointing to.

What do you want to know more about?

Common resource editing procedures

Adding controls to dialog boxes

Arranging controls on dialog boxes

Types of dialog box controls

What do you want to do?

Add or edit controls in a dialog box

Format the layout of a dialog box

Edit a dialog box

Find control labels or IDs

Test a dialog box


Types of Controls

Home Page (Dialog Editor) | Overview | How Do I ... Topics

With the Dialog editor you can create dialog boxes that include the standard control types shown on the Controls toolbar below.

By default, the Controls toolbar is displayed when the Dialog editor is open, but if you close it before exiting the Dialog editor, you will need to explicitly open it the next time you open the Dialog editor.

Note that Visual Fortran supports a subset of the controls, as described in the Visual Fortran Programmer's Guide, in the section Using Dialogs.


About Adding Controls to Dialog Boxes

Home Page (Dialog Editor) | Overview | How Do I ... Topics

You add controls to a dialog box by using the Controls toolbar, which enables you to choose the control you want and to drag it to the dialog box. When displayed, the toolbar stays positioned above other open windows in your workspace. You can add ActiveX controls to the Controls toolbar. You can also add ActiveX controls, which may not be on the toolbar, directly to a dialog box by using the Insert ActiveX Controls command from the Dialog editor shortcut menu. Note that Visual Fortran does not support ActiveX controls.

The fastest way to add controls to a dialog box, reposition existing controls, or move controls from one dialog box to another is to use the drag-and-drop method. The control’s position is outlined in a dotted line until it is dropped into the dialog box. When you add a control to a dialog box with the drag-and-drop method, the control is given a standard height appropriate to that type of control.

When you add a control to a dialog box or reposition it, its final placement may be determined by guides or margins, or whether you have the layout grid turned on.

Once you have added a control to the dialog box, you can change properties such as its caption by using its property page. You can select multiple controls and change their properties all at once.

What do you want to do?

Add controls to dialog boxes

Select specific controls or groups of controls

Size individual controls

Show or hide the Controls toolbar

Use guides and margins


About Arranging Controls on Dialog Boxes

Home Page (Dialog Editor) | Overview | How Do I ... Topics

The Dialog editor provides layout tools that align and size controls automatically. For most tasks, you can use the Dialog toolbar. All commands are also available on the Layout menu, and most have shortcut keys.

Many layout commands are available only when more than one control is selected. For information on selecting more than one control, see Selecting Controls.

The location, height, and width of the current control is displayed in the lower-right corner of the status bar. When more than one control is selected, the position indicators show the position of the dominant control (the control with solid sizing handles). The dominant control determines the anchor point for lining up other controls. You can change which control is dominant. For more information, see Selecting Controls.

When the entire dialog box is selected, the status bar displays the position of the dialog box and its height and width.

The location and size of a dialog box, as well as the location and size of controls within it, are measured in dialog units (DLUs). A DLU is based on the size of the dialog box font, normally 8-point MS Sans Serif. A horizontal DLU is the average width of the dialog box divided by four. A vertical DLU is the average height of the font divided by eight.

What do you want to do?

Align controls

Use guides and margins

Use the layout grid


How Do I ... Topics: Dialog Editor

Home Page | Overview

What do you want to know more about?

Adding, editing, and deleting controls

Arranging controls on dialog boxes

Dialog boxes in Visual C++

What do you want to do?

Start the Dialog Editor

Add or edit controls in a dialog box

Format the layout of a dialog box

Edit a dialog box

Find controls or IDs

Quickly add a message handler for a control

Quickly add the default message handler for a control

Test a dialog box


Starting the Dialog Editor

You can start the Dialog editor by opening an existing dialog box resource or by choosing Resource from the Insert menu, then choosing Dialog and clicking New.


Adding and Editing Controls in a Dialog Box

Home Page (Dialog Editor) | Overview | How Do I ... Topics

One of the first steps in creating a new dialog box (or making a dialog box template) is to add controls to the dialog box. Controls can be arranged to fit a certain size, shape, or alignment, or they can be moved around to work within the dialog box. You can edit certain properties of the control directly. It’s also easy to delete a control.

What do you want to know more about?

Types of controls

What do you want to do?

Add, edit or delete a control

Select specific controls or groups of controls

Size individual controls

Show or hide the Controls toolbar


Adding, Editing or Deleting Controls

Home Page (Dialog Editor) | Overview | How Do I ... Topics

You add controls to a dialog box by using the Controls toolbar to choose the control you want, then placing the control in the dialog box. You can edit the properties of a control, such as its ID, whether it is initially visible at runtime, and so forth.

What do you want to know more about?

Adding controls to dialog boxes

What do you want to do?

Show or hide the Controls toolbar

Add a control to a dialog box

Size a control while you add it

Add multiple controls

Edit the properties of a control or controls

Delete a control

To add a control to a dialog box

  • From the Controls toolbar, select the control you want, and then either click the dialog box at the location where you want to place the control, or drag the control to that location.

    For information about the types of controls available on the Controls toolbar, see Types of Controls.

To size a control while you add it

  • After selecting the control from the Controls toolbar, place the pointer where you want the upper-left corner of the control to be, then drag to the right and down until the control is the size you want.

To add multiple controls

  • Hold down CTRL when you select a control from the Controls toolbar, and then click the dialog box as many times as you want to add this particular control. Press ESC to stop placing controls.

    Note There must be at least one project on the workspace that supports MFC. If the only project on the workspace is an ATL project without MFC support, you will receive an error message, and will be unable to insert the control.

To edit the properties of a control or controls

  • With one or more controls selected in the dialog box, choose Properties from the View menu.

    If you have multiple controls selected, only the properties common to all the controls can be edited. To undo a change, choose Undo from the Edit menu.

To delete a control

  • In the dialog box, select the control, and press DEL.


Selecting Controls

Home Page (Dialog Editor) | Overview | How Do I ... Topics

To size, align, move, copy, or delete controls, you select them and then perform the operation you want. In most cases, you need to select more than one control to use the sizing and alignment tools on the Dialog toolbar.

When a control is selected, it has a shaded border around it with solid (active) or hollow (inactive) “sizing handles,” small squares that appear in the selection border. When multiple controls are selected, the dominant control has solid sizing handles; all the other selected controls have hollow sizing handles.

When you are sizing or aligning multiple controls, the Dialog editor uses the “dominant control” to determine how the other controls are sized or aligned. By default, the dominant control is the last control selected, but you can change it.

What do you want to do?

Select multiple controls

Change the dominant control when more than one control is selected

To select multiple controls

  1. On the Controls toolbar, select the Pointer tool.

  2. Drag the pointer to draw a selection box around the controls you want to select. Controls partially outside the selection box are not selected.

    When you release the mouse button, all controls inside the selection box are selected.

    Once you have selected one or more controls, you can remove or add individual controls without disturbing the selection as a whole.

  3. Hold down the SHIFT key and click the control you want to remove from or add to the existing selection.

To change the dominant control when more than one control is selected

  • Hold down the CTRL key and click the control you want to use to influence the size or location of the others.

    The sizing handles change from hollow to solid. All further resizing or alignment is based on this control.


Sizing Individual Controls

Home Page (Dialog Editor) | Overview | How Do I ... Topics

Use the sizing handles to resize a control. When the pointer is positioned on a sizing handle, it changes shape to indicate the direction in which the control will be resized. Active sizing handles are solid; if a sizing handle is hollow, the control cannot be resized along that axis.

You can also change the size of a control by snapping the control to guides or margins, or by moving one snapped control and guide away from another.

What do you want to do?

Size a control

Set the size of the combo box drop-down area

Make controls the same width, height, or size

Use guides and margins

Use the Layout Grid

To size a control

  1. Click the control, or select it with the TAB key.

  2. Drag the sizing handles to change the size of the control:
    • Sizing handles at the top and sides change the horizontal or vertical size.

    • Sizing handles at the corners change both horizontal and vertical size.

Tip You can resize the control one dialog unit (DLU) at a time by holding down the SHIFT key and using the ARROW keys.

As you type a caption within a control, the control resizes to fit the text caption. You can disable this function by manually resizing the control with the sizing handles. To return to the automatic resizing of a control to fit the text within it, choose Size To Content from the Layout menu.

Setting the Size of the Combo Box Drop-Down Area

When you select a drop-down combo box or drop-down list box to size it, only the right and left sizing handles are active. Use these handles to set the width of the box as it is displayed initially.

You can also set the vertical size of the drop-down portion of the box.

To set the size of the combo box drop-down area

  1. Click the drop-down arrow at the right of the combo box.

    The outline of the control changes to show the size of the combo box with the drop-down area extended.

  2. Use the bottom sizing handle to change the initial size of the drop-down area.

  3. Click the drop-down arrow again to close the drop-down portion of the combo box.

Making Controls the Same Width, Height, or Size

You can resize a group of controls based on the size of the dominant control. You can also resize a control based on the dimensions of its caption text.

To make controls the same width, height, or size

  1. Select the controls you want to resize.

  2. Make sure the correct dominant control is selected.

    The final size of the controls in the group depends on the size of the dominant control. For more information on selecting the dominant control, see Selecting Controls.

  3. From the Layout menu, choose Make Same Size, then choose one of the following commands:
    • Make Same Width

    • Make Same Height

    • Make Same Size


Showing or Hiding the Dialog Editor Toolbars

Home Page (Dialog Editor) | Overview | How Do I ... Topics

When you are in the Dialog editor, you can toggle the display of the Controls toolbar or the Dialog toolbar by selecting them from the list of available toolbars and windows.

To show or hide a Dialog editor toolbar

  • From within the Dialog editor, right-click in an empty part of the menu bar and check or uncheck Controls or Dialog.


Formatting the Layout of a Dialog Box

Home Page (Dialog Editor) | Overview | How Do I ... Topics

The Dialog editor contains special tools for layout. These tools help align and arrange controls in the correct place.

You can use the Dialog editor in three different states for moving controls: with the guides and margins on (default setting), with the layout grid on, or without any snapping or alignment features.

What do you want to do?

Align controls

Use guides and margins

Use the layout grid


Aligning Controls

Home Page (Dialog Editor) | Overview | How Do I ... Topics

Once controls are in place, the Dialog editor offers a variety of ways to refine their positions.

What do you want to know more about?

Arranging controls on dialog boxes

What do you want to do?

Align controls

Align controls on their center, horizontally or vertically

Even the spacing between controls

Center controls in the dialog box

Arrange push buttons along the right or bottom of the dialog box

To align controls

  1. Select the controls you want to align.

  2. Make sure the correct dominant control is selected.

    The final position of the group of controls depends on the position of the dominant control. For more information on selecting the dominant control, see Selecting Controls.

  3. From the Layout menu, choose Align, and then choose one of the following alignments:
    • Left: aligns the selected controls along their left side.

    • Right: aligns the selected controls along their right side.

    • Top: aligns the selected controls along their top edges.

    • Bottom: aligns the selected controls along their bottom edges.

To align controls on their center, vertically or horizontally

  1. Select the controls you want to center.

  2. Make sure the correct dominant control is selected.

    The final position of the group of controls depends on the position of the dominant control. For more information on selecting the dominant control, see Selecting Controls.

  3. From the Layout menu, choose Align, and then choose Horiz. Center or Vert. Center.

To even the spacing between controls

  1. Select the controls you want to rearrange.

  2. From the Layout menu, choose Space Evenly, and then choose one of the following spacing alignments:
    • Across: spaces controls evenly between the leftmost and the rightmost control selected.

    • Down: spaces controls evenly between the topmost and the bottommost control selected.

To center controls in the dialog box

  1. Select the control or controls you want to rearrange.

  2. From the Layout menu, choose Center In Dialog, and then choose one of the following arrangements:
    • Vertical: centers controls vertically in the dialog box.

    • Horizontal: centers controls horizontally in the dialog box.

To arrange push buttons along the right or bottom of the dialog box

  1. Select one or more push buttons.

  2. From the Layout menu, choose Arrange Buttons, and then choose one of the following arrangements:
    • Right: aligns push buttons along the right edge of the dialog box.

    • Bottom: aligns push buttons along the bottom edge of the dialog box.

    If you select a control other than a push button, its position is not affected.


Using Guides and Margins

Home Page (Dialog Editor) | Overview | How Do I ... Topics

Whether you are moving controls, adding controls, or rearranging a current layout, guides can help you align controls accurately within a dialog box. Guides appear as blue dotted lines across the dialog box displayed in the editor and corresponding arrows in the rulers.

When you create a dialog box, four margins are provided. Margins are modified guides, appearing as blue dotted lines.

What do you want to know more about?

Arranging controls on dialog boxes

What do you want to do?

Create and set a guide

Align controls on a guide

Disable the guides

To create and set a guide

  1. Click anywhere within the rulers to create a guide.

  2. Drag the guide into position.

    The number of DLUs is displayed in the ruler and below on the status bar. After the guide is dropped into position, hold the cursor over the guide’s arrow in the ruler to see the exact position of the guide.

Tip To delete a guide, drag the guide out of the dialog box.

Aligning Controls on a Guide

The sizing handles of controls snap to guides when the controls are moved, and guides snap to controls (if there are no controls previously snapped to the guide). When a guide is moved, controls that are snapped to it move as well. Controls snapped to more than one guide are resized when one of the guides is moved.

The tick marks in the rulers that determine the spacing of guides and controls are defined by dialog units (DLUs). A DLU is based on the size of the dialog box font, normally 8-point MS Sans Serif. A horizontal DLU is the average width of the dialog box divided by four. A vertical DLU is the average height of the font divided by eight.

What do you want to do?

Move guides

Move margins

Size a group of controls with guides

Change the intervals of the tick marks

To move guides

  • Drag the guide to the new position.

    The coordinates of the guide are displayed in the status bar at the bottom of the window and in the ruler. Move the pointer over the arrow in the ruler to display the exact position of the guide.

To move margins

  • Drag the margin to the new position.

    To make a margin disappear, move the margin to a zero position. To bring the margin back, place the pointer over the margin’s zero position and move the margin into position.

To size a group of controls with guides

  1. Snap one side of the control (or controls) to a guide.

  2. Drag a guide to the other side of the control (or controls).

    If necessary with multiple controls, size each to snap to the second guide.

  3. Move either guide to size the control (or controls) on that side.

To change the intervals of the tick marks

  1. From the Layout menu, choose Guide Settings.

  2. In the Grid Spacing box, specify the new width and height in DLUs.

  3. Click OK.

Disabling the Guides

You can use special keys in conjunction with the mouse to disable the snapping effect of the guides. Using the ALT key disables the snapping effects of the guide selected. Moving a guide with the SHIFT key prevents snapped controls from moving with the guide.

To disable the snapping effect of the guides

  • Drag the control while holding down the ALT key.

To move guides without moving the snapped controls

  • Drag the guide while holding down the SHIFT key.

To clear all the guides

  1. Click the right mouse button in the ruler bar.

  2. From the shortcut menu, choose Clear All.

To turn off the guides

  1. From the Layout menu, choose Guide Settings.

  2. Under Layout Guides, select None.

  3. Click OK.


Using the Layout Grid

Home Page (Dialog Editor) | Overview | How Do I ... Topics

When you are placing or arranging controls in a dialog box, you can use the layout grid for more precise positioning. When the grid is turned on, controls appear to “snap to” the dotted lines of the grid as if magnetized. You can turn this “snap to grid” feature on and off and change the size of the layout grid cells.

To turn the layout grid on or off

  1. From the Layout menu, choose Guide Settings.

  2. Select or clear the Grid button.

    You can still control the grid in individual Dialog editor windows using the Toggle Grid button on the Dialog toolbar.

To change the size of the layout grid

  1. From the Layout menu, choose Guide Settings.

  2. Type the height and width in DLUs for the cells in the grid. The minimum height or width is 4 DLUs. For more information on DLUs, see About Arranging Controls on Dialog Boxes.


Editing the Dialog Box

Home Page (Dialog Editor) | Overview | How Do I ... Topics

Each dialog box has a property page, a tab order, and mnemonic keys. The tab order is the order that the focus moves from when using the TAB key. Alternatively, a keyboard user can press a mnemonic key to move the input focus from one control to another.

What do you want to do?

Change the tab order

Define mnemonic keys


Changing the Tab Order

Home Page (Dialog Editor) | Overview | How Do I ... Topics

The tab order is the order in which the TAB key moves the input focus from one control to the next within a dialog box. Usually the tab order proceeds from left to right in a dialog box, and from top to bottom. Each control has a property page with a Tabstop check box, used to determine whether a control actually receives input focus.

Even controls that do not have the Tabstop property set need to be part of the tab order. This can be important, for example, when you define mnemonics for controls that do not have captions. Static text that contains a mnemonic for a related control must immediately precede the related control in the tab order.

Note If your dialog box contains overlapping controls, changing the tab order may change the way the controls are displayed. Controls that come first in the tab order are always displayed on top of any overlapping controls that follow them in the tab order.

Tip Once you enter Tab Order mode, you can press ESC to disable the ability to change the tab order.

What do you want to do?

Change the tab order for all controls

Change the tab order for two or more controls

To change the tab order for all controls in a dialog box

  1. From the Layout menu, choose Tab Order.

    A number in the upper-left corner of each control shows its place in the current tab order.

  2. Set the tab order by clicking each control in the order you want the TAB key to follow.

  3. Press ENTER to exit Tab Order mode.

Changing the Tab Order for Two or More Controls

To change the tab order for two or more controls, specify the starting control; that is, select the control prior to the one where you want the changed order to begin. The selected control determines the number of the control you click next. For example, if you are in Tab Order mode, and control number 3 is selected, the next control you click is set to number 4.

To change the tab order for two or more controls

  1. From the Layout menu, choose Tab Order.

  2. Specify where the change in order will begin. To do this, hold down the CTRL key and click the control prior to the one where you want the changed order to begin.

    For example, if you want to change the order of controls 7 through 9, select control 6 first.

    Note To set a specific control to number 1 (first in the tab order), double-click the control.

  3. Reset the tab order by clicking the controls in the order you want the TAB key to follow.

  4. Press ENTER to exit Tab Order mode.


Defining Mnemonic Keys

Home Page (Dialog Editor) | Overview | How Do I ... Topics

Normally, keyboard users move the input focus from one control to another in a dialog box with the TAB and ARROW keys. However, you can define a mnemonic key that allows users to choose a control by pressing a single key.

Note All the mnemonics within a dialog box should be unique. You can use the Check Mnemonics command on the context menu to check your dialog box for duplicate mnemonic keys.

To define a mnemonic key for a control with a visible caption (pushbuttons, check boxes, and radio buttons)

  1. Select the control.

  2. From the View menu, choose Properties to open the control’s property page.

  3. In the Caption box, type an ampersand (&) in front of the letter you want as the mnemonic for that control.

    An underline appears in the displayed caption to indicate the mnemonic key.

To define a mnemonic for a control without a visible caption

  1. Make a caption for the control by using a static text control. In the static text caption, type an ampersand (&) in front of the letter you want as the mnemonic.

  2. Make sure the static text control immediately precedes the control it labels in the tab order.


Finding Control Labels and IDs

Home Page | Overview | How Do I ... Topics

You can use the Find command to search for labels for static text controls, multiple instances of the same word across dialog boxes, or to find a dialog box in a long list. The Find command helps when you need to make changes in dialog boxes, or when you need to check consistency, or when you can remember the contents of a dialog but not its ID. You can also search for control or dialog IDs, if you remember the ID but not the contents.

To find control labels or IDs

  1. From the Edit menu, choose Find.

  2. In the Find What box, select a previous search string from the drop-down list, type the label or ID you want to find, or type a regular expression to match a pattern.

    Tip Click the button to the right of the Find What box to display a list of regular search expressions. When you select an expression from this list, it is substituted as the search text in the Find What box. If you use regular expressions, be sure the Regular Expressions check box is selected.

  3. Select any of the Find options.

  4. Click Find Next.


Testing a Dialog Box

Home Page (Dialog Editor) | Overview | How Do I ... Topics

You can simulate the run-time behavior of a dialog box from within the Dialog editor without compiling your program. This gives you immediate feedback on how the layout of controls appears and performs and thus speeds up the user-interface design process.

When you are in test mode, you can:

  • Type text, select from combo-box lists, turn options on and off, and choose commands.

  • Test the tab order.

  • Test the grouping of controls, such as radio buttons or check boxes.

  • Test the dialog box’s keyboard shortcuts (for controls that have mnemonic keys defined for them).

When you test a dialog box, it is usually displayed at a location relative to the main program window. If the dialog box’s Absolute Align property is selected, the dialog box is displayed at a position relative to the upper-left corner of the screen.

To test a dialog box

  1. From the Layout menu, choose Test.

  2. To end the test session, do one of the following actions:
    • Press ESC.

    • Close the dialog box using its Close button.

    • Choose a push button with a symbol name of IDOK or IDCANCEL.


Home Page: Graphics Editor

  • Overviews

  • How Do I ... Topics

For information about the Graphics editor

  • Editing graphical resources

  • Working with color

  • Managing the Graphics editor workspace

Related Home Pages

  • Resource Editors Home Page


Overview: Graphics Editor

Home Page (Graphics Editor) | How Do I ... Topics

The Graphics editor has an extensive set of tools for drawing images, as well as features to support the creation of toolbar bitmaps. In addition to creating and editing images in bitmap format, you can edit images in GIF or JPEG format. You can also convert images in GIF or JPEG format to bitmap format.

With the Graphics editor, you can:

  • Use the image editor window and docking toolbars

  • Customize and adjust the Graphics editor workspace

  • Edit a graphic resource and draw new graphics

  • Customize colors, change palettes, and select colors

Note Many of the Graphics editor’s functions require a mouse or other pointing device. For keyboard shortcuts or accelerators, choose Keyboard from the Help menu.

Tip While using the Graphics editor, in many instances, you can click the right mouse button to display a shortcut menu of frequently used commands. The commands available depend on what the pointer is pointing to.

For information about common resource edit procedures such as creating new resources, opening existing resources, and deleting resources, see Resource Editors How Do I ... Topics.

What do you want to know more about?

Graphical resources

Color

Image editor window and tools

Image editor panes

What do you want to do?

Edit graphical resources

Work with color

Manage the Graphics editor workspace


About Graphical Resources

Home Page (Graphics Editor) | Overview | How Do I ... Topics

Graphical resources are the images you define for your application. In addition to creating new graphical resources, you can import existing images and add them to your project, and you can open files that are not part of a project for stand-alone editing.

What do you want to do?

Draw or erase freehand

Draw lines or closed figures

Select an area of an image

Edit selected parts of an image

Flip an image

Resize an image

Create a custom brush

Set image properties

Save an image in a different format

Convert an image from one format to another


About Color

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Graphics editor comes equipped with many features that specifically handle and customize colors. You can set a foreground or background color, fill bounded areas with color, or select a color on an image to use as the current foreground or background color.

The Graphic editor’s Colors palette initially displays 24 colors: 16 standard colors and 8 dithered colors. In addition to these 24, you can create your own custom colors. You can save customized color palettes on disk and reload them as needed. The Colors palette you used most recently is saved in the Registry and automatically loaded the next time you start Visual Studio 97.

The Palette tab displays up to 256 colors. Changing any of the colors on the Palette tab will immediately change the corresponding color in the image. The colors on the Palette tab are always solid colors and can indicate any color your video card is capable of displaying.

What do you want to do?

Select foreground or background colors

Fill a bounded area of an image with a color

Pick up a color from an image to use elsewhere

Choose an opaque or transparent background

Invert the colors in a selection

Customize or change colors

Save and load different color palettes


About the Image Editor Window and Tools

Home Page (Graphics Editor) | Overview | How Do I ... Topics

You edit images in the Image Editor window, using the tools on the Graphics toolbar.

What would you like to know more about?

Image Editor window

Graphics toolbar

Colors palette

Status bar

Image menu


Image Editor Window

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Image Editor window shows two views of an image. A split bar separates the two panes. You can drag the split bar from side to side to change the relative sizes of the panes. The active pane displays a selection border.

What do you want to do?

Edit graphical resources

Manage the Graphics editor workspace


Graphics Toolbar

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Graphics toolbar has two parts:

  • The toolbar, which contains 21 tools for drawing, painting, entering text, erasing, and manipulating views.

  • The option selector, which you click to select brush widths and other drawing options.

To use the Graphics toolbar, Colors palette, and option selector, click the tool, color, or option that you want.

What do you want to do?

Edit graphical resources


Colors Palette

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Colors palette has two parts:

  • The color indicator, which shows the foreground and background colors and selectors for screen and inverse color.

  • The Colors palette, which you click to select the foreground and background colors.

What do you want to do?

Work with color


Status Bar

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The status bar, at the bottom of the frame window, displays two panes when an Image Editor window is open. When the pointer is over an image, the left pane shows the cursor’s current position, in pixels, relative to the upper-left corner of the image. During a dragging operation, such as selecting, moving, or drawing a rectangle, the right pane shows the size, in pixels, of the affected area.

What do you want to do?

Edit graphical resources

Manage the Graphics editor workspace


Image Menu

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Image menu, which appears only when the Graphics editor is active, has commands for editing images, managing color palettes, and setting image editor window options.

What do you want to do?

Edit graphical resources

Work with color

Manage the Graphics editor workspace


About Image Editor Panes

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Image Editor window typically displays a image in two panes separated by a split bar. One view is actual size, and the other is enlarged (the default enlargement factor is 6). The views in these two panes are updated automatically: changes you make in one pane are immediately shown in the other. The two panes make it easy for you to work on an enlarged view of your image, in which you can distinguish individual pixels and, at the same time, observe the effect of your work on the actual-size view of the image.

If the image is 200 x 200 pixels or larger, however, only one pane is displayed initially. Move the split bar to display both panes.

You can change the magnification in a pane using the Magnify tool and the magnification factor in the options selector.

You can use the two panes in other ways. For example, you might enlarge the smaller pane and use the two panes to show different regions of a large image. Click in the pane to select it.

You can change the relative sizes of the panes by positioning the pointer on the split bar and moving the split bar to the right or left. The split bar can move all the way to either side if you want to work on only one pane.

If the Image-editor pane is enlarged by a factor of 4 or greater, you can display a grid that delimits the individual pixels in the image.

What do you want to do?

Change the magnification factor

Display or hide the pixel grid


How Do I ... Topics: Graphics Editor

Home Page (Graphics Editor) | Overview

Use the Graphics editor to draw and edit images in bitmap, GIF, or JPEG formats, or to create bitmaps for toolbars.

What do you want to do?

Edit graphical resources

Work with color

Manage the Graphics editor workspace


Editing Graphical Resources

Home Page (Graphics Editor) | Overview | How Do I ... Topics

Graphical resources are the images you define for your application. You can draw freehand or draw shapes. You can select parts of an image for editing, flipping or resizing, or you can create a custom brush from a selected part of an image and draw with that brush. You can define image properties, save images in different formats, and convert images from one format to another.

What do you want to know more about?

Graphics toolbar

What do you want to do?

Draw or erase freehand

Draw lines or closed figures

Select an area of an image

Edit selected parts of an image

Flip an image

Resize an image

Create a custom brush

Change image properties

Save an image in a different format

Convert an image from one format to another


Drawing or Erasing Freehand

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Graphics editor’s freehand drawing and erasing tools all work in the same way: you select the tool and, if necessary, select foreground and background colors and size and shape options. You then move the pointer to the image and click or drag to draw and erase.

When you have selected the eraser tool, brush tool, or airbrush tool, the option selector displays that tool’s options.

Tip Instead of using the eraser tool, you may find it more convenient to draw in the background color with one of the drawing tools.

To select and use a drawing tool

  1. Click a button on the Graphics toolbar.
    • The eraser tool paints over the image with the current background color when you press the left mouse button. When you press the right mouse button, it replaces the current foreground color with the current background color.

    • The pencil tool draws freehand in a constant width of one pixel.

    • The brush tool’s shape and size are determined by the option selector.

    • The airbrush tool randomly distributes color pixels around the center of the brush.
  2. If necessary, select colors and a brush:
    • In the Colors palette, click the left mouse button to select a foreground color or the right mouse button to select a background color.

    • On the options selector, click a shape representing the brush you want to use.
  3. Point to the place on the image where you want to start drawing or painting. The pointer changes shape according to the tool you selected.

  4. Press the left mouse button (for the foreground color) or the right mouse button (for the background color), and hold it down as you draw.

To change the size of the brush, airbrush, or eraser

  • Choose a shape in the option selector.


Drawing Lines or Closed Figures

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Graphics editor tools for drawing lines and closed figures all work in the same way: you place the insertion point at one point and drag to another. For lines, these points are the endpoints. For closed figures, these points are opposite corners of a rectangle bounding the figure.

Lines are drawn in a width determined by the current brush selection, and framed figures are drawn in a width determined by the current width selection. Lines and all figures, both framed and filled, are drawn in the current foreground color if you press the left mouse button, or in the current background color if you press the right mouse button.

To draw a line

  1. From the Graphics toolbar, select the line tool.

  2. If necessary, select colors and a brush:
    • In the Colors palette, click the left mouse button to select a foreground color or the right mouse button to select a background color.

    • On the options selector, click a shape representing the brush you want to use.
  3. Place the pointer at the line’s starting point.

  4. Drag to the line’s endpoint.

To draw a closed figure

  1. From the Graphics toolbar, select a closed-figure drawing tool.

    The closed-figure drawing tools create figures as indicated on their respective buttons.

  2. If necessary, select colors and a line width:
    • On the Colors palette, click the left button to select a foreground color or the right button to select a background color.

    • On the options selector, click the line width you want.
  3. Move the pointer to one corner of the rectangular area in which you want to draw the figure.

  4. Drag the pointer to the diagonally opposite corner.


Selecting an Area of an Image

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The selection tools define an area of an image that you can cut, copy, clear, resize, invert, or move. You can also create a custom brush from the selection. For more information, see Creating a custom brush.

To select an area of an image

  1. In the Graphics toolbar, click the selection tool you want.

  2. Move the insertion point to one corner of the image area that you want to select. Cross hairs appear when the insertion point is over the image.

  3. Drag the insertion point to the opposite corner of the area you want to select. A rectangle shows which pixels will be selected. All pixels within the rectangle, including those under the rectangle, are included in the selection.

  4. Release the mouse button. The selection border encloses the selected area. Now any operation you perform will affect only the pixels within the rectangle.

To select an entire image

  • Click the image outside of the current selection.


Editing Selected Parts of an Image

Home Page (Graphics Editor) | Overview | How Do I ... Topics

You can perform standard editing operations — cutting, copying, clearing, and moving — with the selection, whether the selection is the entire image or just a part of it. Because the Graphics editor uses the Windows Clipboard, you can transfer images between the Graphics editor and other applications for Windows, such as Microsoft Word for Windows.

In addition, you can resize the selection, whether it includes the entire image or just a part.

What do you want to do?

Cut the current selection and move it to the Clipboard

Clear the current selection without moving it to the Clipboard

Paste the Clipboard contents into an image

Move the selection

Copy the selection

Draw with the selection

To cut the current selection and move it to the Clipboard

  • From the Edit menu, choose Cut.

To clear the current selection without moving it to the Clipboard

  • From the Edit menu, choose Clear.

    The original area of the selection is filled with the current background color.

To paste the Clipboard contents into an image

  1. From the Edit menu, choose Paste.

    The Clipboard contents, surrounded by the selection border, appear in the upper-left corner of the pane.

  2. Position the pointer within the selection border and drag the image to the desired location on the image.

  3. To anchor the image at its new location, click outside of the selection border.

To move the selection

  1. Position the pointer inside the selection border or anywhere on it except the sizing handles.

  2. Drag the selection to its new location.

  3. To anchor the selection in the image at its new location, click outside the selection border.

To copy the selection

  1. Position the pointer inside the selection border or anywhere on it except the sizing handles.

  2. Hold down the CTRL key as you drag the selection to a new location. The area of the original selection is unchanged.

  3. To copy the selection into the image at its current location, click outside the selection cursor.

To draw with the selection

  1. Position the pointer inside the selection border or anywhere on it except the sizing handles.

  2. Hold down the SHIFT key as you drag the selection.

    Copies of the selection are left along the dragging path. The more slowly you drag, the more copies are made.


Flipping an Image

Home Page (Graphics Editor) | Overview | How Do I ... Topics

To flip the selection horizontally

  • From the Image menu, choose Flip Horizontal.

To flip the selection vertically

  • From the Image menu, choose Flip Vertical.

To rotate the selection 90 degrees

  • From the Image menu, choose Rotate 90.


Resizing an Image

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The behavior of the Graphics editor while resizing an image depends on whether the selection includes the entire image or just part of it.

When the selection includes only part of the image, the Graphics editor shrinks the selection by deleting rows or columns of pixels and filling the vacated regions with the current background color, or it stretches the selection by duplicating rows or columns of pixels.

When the selection includes the entire image, the Graphics editor either shrinks and stretches the image, or crops and extends it.

There are two mechanisms for resizing an image: the resizing handles and the property page. You can drag the sizing handles to change the size of all or part of an image. Sizing handles that you can drag are solid. You cannot drag handles that are hollow. You can use the property page to resize the entire image only, not a selected part.

Note If you have the Tile Grid option selected (see the Grid Settings command on the Image menu), then resizing snaps to the next tile grid line. If only the Pixel Grid option is selected, resizing snaps to the next available pixel. Usually, only the Pixel Grid option is selected.

What do you want to do?

Resize an entire image using the Property page

Crop or extend an entire image

Shrink or stretch an entire image

Shrink or stretch part of an image

To resize an entire image using the Property page

  1. Open the image whose properties you want to change.

  2. From the View menu, choose Properties.

  3. In the Width and Height boxes, type the dimensions that you want.

    If you are increasing the size of the image, the Graphics editor extends the image to the right, downward, or both, and fills the new region with the current background color. The image is not stretched.

    If you are decreasing the size of the image, the Graphics editor crops the image on the right or bottom edge, or both.

You can use the Width and Height properties to resize only the entire image, not to resize a partial selection.

To crop or extend an entire image

  1. Select the entire image.

    If part of the image is currently selected, and you want to select the entire image, click anywhere on the image outside the current selection border.

  2. Drag a sizing handle until the image is the desired size.

Normally, the Graphics editor crops or enlarges an image when you resize it by moving a sizing handle. If you hold down the SHIFT key as you move a sizing handle, the Graphics editor shrinks or stretches the image.

To shrink or stretch an entire image

  1. Select the entire image.

    If a part of the image is currently selected and you want to select the entire image, click anywhere on the image outside the current selection border.

  2. Hold down the SHIFT key and drag a sizing handle until the image is the desired size.

To shrink or stretch part of an image

  1. Select the part of the image you want to resize. For more information, see Selecting an Area of the Image.

  2. Drag one of the sizing handles until the selection is the desired size.


Creating a Custom Brush

Home Page (Graphics Editor) | Overview | How Do I ... Topics

A custom brush is a rectangular portion of an image that you pick up and use like one of the Graphics editor’s ready-made brushes. All operations you can perform on a selection, you can perform on a custom brush as well.

To create a custom brush

  1. Select the part of the image that you want to use for a brush. For more information, see Selecting and Using a Drawing Tool.

  2. Press CTRL+B.

Pixels in a custom brush that match the current background color are normally transparent: they do not paint over the existing image. You can change this behavior so that background-color pixels paint over the existing image.

You can use the custom brush like a stamp or a stencil to create a variety of special effects.

To draw custom brush shapes in the background color

  1. Select an opaque or transparent background. For more information, see Choosing Opaque and Transparent Backgrounds.

  2. Set the background color to the color in which you want to draw.

  3. Position the custom brush where you want to draw.

  4. Click the right mouse button. Any opaque regions of the custom brush are drawn in the background color.

To double or halve the custom brush size

  • Press the PLUS SIGN (+) key to double the brush size, or the MINUS SIGN ( – ) key to halve it.

To cancel the custom brush

  • Press ESC or choose another drawing tool.


Changing Image Properties

Home Page (Graphics Editor) | Overview | How Do I ... Topics

You use the Properties window to change most resource properties. Exceptions are new icons or cursors for additional target devices.

Tip By default the Properties window is hidden whenever it does not have focus. To keep the Properties window in view when it does not have focus, click the Pushpin button in the upper-left corner of the Properties window.

To change an image’s properties

  1. Open the image whose properties you want to change.

  2. From the View menu, choose Properties.

  3. Change any or all of these properties on the General tab:
    • In the ID box, modify the resource’s identifier. For an image, Microsoft Visual C++, by default, assigns the next available identifier in a series: IDB_IMAGE1, IDB_IMAGE2, and so forth. Similar names are used for icons and cursors.

    • In the Width and Height boxes, modify the image’s width and height (in pixels). The default value for each is 48.

      If you change the dimensions of an image using the property page, the image is cropped or blank space is added to the right of or below the existing image.

    • In the Colors list box, select Monochrome, 16, or 256. If you have already drawn the image with a 16-color palette, selecting Monochrome causes substitutions of black and white for the colors in the image. Contrast is not always maintained: for example, adjacent areas of red and green are both converted to black.

    • In the File Name box, modify the name of the file in which the image is to be stored. By default, Visual C++ assigns a base filename created by removing the first four characters (“IDB_”) from the default identifier and adding the appropriate extension.

    • Select the Save Compressed check box to save the image in a compressed format.
  4. Change any or all of the color properties on the Palette tab:
    • Double-click to select a color and display the Custom Color Selector dialog box.

    • Define the color by typing RGB or HSL values in the appropriate text boxes.


Saving an Image in a Different Format

Home Page (Graphics Editor) | Overview | How Do I ... Topics

When you create a new image using the New command on the File menu, the image is always in a bitmap format. You can, however, save your image as a GIF or JPEG.

To save an image in a different file format

  1. From the File menu, choose Save As.

  2. In the File Name box, type the name you want to give the file and the extension that denotes the file format you want. For example, myfile.gif.

  3. Click Save.


Converting an Image From One Format to Another

Home Page (Graphics Editor) | Overview | How Do I ... Topics

You can open GIF or JPEG images in the Graphics editor and save them as bitmaps. Also, you can open a bitmap file and save it as a GIF or JPEG.

To convert an image from one format to another

  1. Open the image in the Graphics editor.

  2. From the File menu, choose Save As.

  3. In the File name box, type the file name and the extension that denotes the format you want.

  4. Click Save.


Working with Color

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Graphics editor comes equipped with many features that specifically handle and customize colors. You can set a foreground or background color, fill bounded areas with color, or select a color on an image to use as the current foreground or background color.

What do you want to do?

Select foreground or background colors

Fill a bounded area of an image with a color

Pick up a color from an image to use elsewhere

Choose an opaque or transparent background

Invert the colors in a selection

Customize or change colors

Save and load different color palettes


Selecting Foreground or Background Colors

Home Page (Graphics Editor) | Overview | How Do I ... Topics

Except for the eraser, tools on the Graphics toolbar draw with the current foreground or background color when you press the left or right mouse button, respectively.

To select a foreground color

  • With the left mouse button, click the color you want on the Colors palette.

To select a background color

  • With the right mouse button, click the color you want on the Colors palette.


Filling a Bounded Area of an Image with a Color

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Graphics editor provides the fill tool for filling any enclosed image area with the current drawing color or the current background color.

To use the fill tool

  1. From the Graphics toolbar, choose the fill tool.

  2. If necessary, choose drawing colors: in the Colors palette, click the left mouse button to select a foreground color or the right mouse button to select a background color.

  3. Move the fill tool to the area you want to fill.

  4. Click the left or right mouse button to fill with the foreground color or the background color, respectively.


Picking up a Color from an Image to Use Elsewhere

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The color-pickup tool makes any color on the image the current foreground color or background color, depending on whether you press the left or the right mouse button. To cancel the color pickup tool, choose another tool.

To pick up a color

  1. From the Graphics toolbar, select the color-pickup tool.

  2. Select the color you want to pick up from the image. After you pick up a color, the Graphics editor reactivates the most recently used tool.

  3. Draw using the left mouse button for the foreground color, or the right mouse button for the background color.


Choosing an Opaque or Transparent Background

Home Page (Graphics Editor) | Overview | How Do I ... Topics

When you move or copy a selection from a cursor or icon, any pixels in the selection that match the current background color are, by default, transparent: they do not obscure pixels in the target location. A custom brush behaves in the same way.

To toggle the background-color transparency

  • In the Graphics toolbar option selector, click the appropriate button:
    • Opaque background: existing image is obscured by all parts of the selection.

    • Transparent background: existing image shows through parts of the selection that match the current background color.

You can change the background color while a selection is already in effect to change which parts of the image are transparent.


Inverting the Colors in a Selection

Home Page (Graphics Editor) | Overview | How Do I ... Topics

So that you can tell how an image would appear with inverted colors, the Graphics editor provides a convenient way to invert colors in the selected part of the image.

To invert colors in the current selection

  • From the Image menu, choose Invert Colors.


Customizing or Changing Colors

Home Page (Graphics Editor) | Overview | How Do I ... Topics

The Graphics editor’s Colors palette initially displays 24 colors: 16 standard colors and 8 dithered colors. In addition to the displayed colors, you can create your own custom colors.

To change colors on the Colors palette or Palette tab

  1. From the Image menu, choose Adjust Colors.

  2. Define the color by typing RGB or HSL values in the appropriate text boxes.

  3. Set the luminosity by moving the slider on the luminosity bar.

  4. Many custom colors are dithered. If you want the solid color closest to the dithered color, double-click the Color preview window. (If you later decide you want the dithered color, move the slider or the cross hairs again to restore the dithering.)

  5. Click OK to add the new color.


Saving and Loading Different Color Palettes

Home Page (Graphics Editor) | Overview | How Do I ... Topics

You use commands on the Image menu to save or load a palette.

To save a custom Colors palette

  1. From the Image menu, choose Save Palette.

  2. Navigate to the directory where you want to save the palette, and type a name for the palette.

  3. Click Save.

To load a custom Colors palette

  1. From the Image menu, choose Load Palette.

  2. Navigate to the correct directory and select the palette you want to load.

  3. Click OK.

Tip Since the Graphics editor has no means to restore the default Colors palette, save the default Colors palette under a name such as standard.pal or default.pal so that you can easily restore the default settings.


Managing the Graphics Editor Workspace

Home Page (Graphics Editor) | Overview | How Do I ... Topics

By adjusting the Graphics editor workspace to fit your needs and preferences, you can work more effectively and comfortably.

What do you want to do?

Change the magnification factor

Display or hide the pixel grid

Display or hide the Graphics toolbar


Changing the Magnification Factor

Home Page (Graphics Editor) | Overview | How Do I ... Topics

By default, the Graphics editor displays the view in the left pane at actual size and the view in the right pane at 6 times actual size. The magnification factor is the ratio between the actual size of the image and the displayed size. The default is 6, and the range is from 1 to 8.

To change the magnification factor

  1. Select the Image-editor pane whose magnification factor you want to change.

  2. On the toolbar, click the Magnify tool. The pointer changes to the Magnify tool, and magnification-factor options appear in the option selector on the Graphics toolbar. If the current magnification factor matches an option, that option is highlighted.

  3. Click the desired magnification factor.


Displaying or Hiding the Pixel Grid

Home Page (Graphics Editor) | Overview | How Do I ... Topics

For all Image-editor panes with a magnification factor of 4 or greater, you can display a grid that delimits the individual pixels in the image.

To display or hide the pixel grid

  1. From the Image menu, choose Grid Settings.

  2. Select the Pixel Grid check box to display the grid, or clear the box to hide the grid.


Displaying or Hiding the Graphics Toolbar

Home Page (Graphics Editor) | Overview | How Do I ... Topics

Since many of the drawing tools are available from the keyboard, sometimes it is useful to hide the Graphics toolbar. To find out which drawing commands are available from the keyboard, select the Keyboard command from the Help menu, then click Image in the drop-down list.

To show or hide the Graphics toolbar

  1. Place the mouse pointer over the toolbar area and click the right mouse button.

From the pop-up menu, choose Graphics.


Home Page: HTML Resource

An HTML resource is an HTML file that is stored and compiled as part of your resource script (.rc file).

  • Overviews

  • How Do I ... Topics

For information about the HTML Resource

  • Creating a new HTML resource

  • Importing an existing HTML file as a resource

Related Home Pages

  • Resource Editors Home Page


Overview: HTML Resource

Home Page (HTML Resource) | How Do I ... Topics

An HTML resource is an HTML file that is stored and compiled as part of your resource script. When you create a new HTML resource, the visual development environment includes it in the resource script of the active project, providing you with easy access to the HTML page and simplifying distribution of your application.

For information about common resource editing procedures such as creating new resources, opening existing resources, and deleting resources, see Resource Editors How Do I ... Topics.

What do you want to do?

Create a new HTML resource

Import an existing HTML file as a resource


How Do I ... Topics: HTML Resource

Home Page (HTML Resource) | Overview

What do you want to do?

Create a new HTML resource

Import an existing HTML file as a resource

Set syntax coloring for a custom HTML variation

Create a Web browser-style application


Creating a New HTML Resource

Home Page (HTML Resource) | Overview | How Do I ... Topics

In the visual development environment, you create a new HTML resource just as you would any other Windows resource. You can also import an existing HTML file into your project's resource script.

To create an HTML resource

  1. From the Insert menu, choose Resource.

  2. In the Resource Type list, select HTML, then click New.

    The visual development environment creates a new HTML resource, giving it a unique ID, such as IDR_HTML1.

You can take advantage of all other Text editor operations as you code your HTML page. Because the HTML page is part of your project's resource script (.rc file), typical file operations such as saving or closing apply to the entire resource file, not just the HTML page you are editing.

Note If your HTML page contains calls to bitmaps or other graphic images, you may want to include the corresponding image files in your resource script to ensure their availability when the user runs the application. If you do so, then use the res: protocol to display these graphic images from your page. The res: protocol supports displaying a resource that resides in a compiled .dll or .exe module.

What do you want to do?

Import an existing HTML file as a resource


Importing an Existing HTML File as a Resource

Home Page (HTML Resource) | Overview | How Do I ... Topics

If you've already designed your Web page, or want to take advantage of other existing Web pages, you can easily include an HTML file into your project's resource script.

To import an existing HTML file as a resource

  1. From the Insert menu, choose Resource.

  2. In the Resource Type list, select HTML, then click Import.

  3. In the Import Resource dialog box, navigate to the location of the HTML file and click Import.

Note If your imported HTML file contains calls to bitmaps or other graphic images, you may want to import the corresponding image files into your resource script as well, to ensure their availability when the user runs the application. Use the res: protocol to display these graphic images from your page. The res: protocol supports displaying a resource that resides in a compiled .dll or .exe module.

What do you want to do?

Create a new HTML resource


Home Page: Menu Editor

  • Overviews

  • How Do I ... Topics

For information about the Menu editor

  • Creating menus or menu items

  • Selecting menus or menu items

  • Moving and copying menus and menu items

Related Home Pages

  • Resource Editors Home Page


Overview: Menu Editor

Home Page (Menu Editor) | How Do I ... Topics

Menus allow you to arrange commands in a logical, easy-to-find fashion. With the Menu editor, you can create and edit menus by working directly with a menu bar that closely resembles the one in your finished application.

With the Menu editor, you can:

  • Create standard menus and commands.

  • Move menus or commands from one place to another.

  • Edit the properties of several menu items at the same time.

Tip While using the Menu editor, in many instances, you can click the right mouse button to display a shortcut menu of frequently used commands. The commands available depend on what the pointer is pointing to.

For information about common resource edit procedures such as creating new resources, opening existing resources, and deleting resources, see Resource Editors How Do I ... Topics.

What do you want to do?

Create menus or menu items

Select menus or menu items

Move and copy menus and menu items


How Do I ... Topics: Menu Editor

Home Page (Menu Editor) | Overview

Menus allow you to arrange commands in a logical, easy-to-find fashion. With the Menu editor, you can create and edit menus by working directly with a menu bar that closely resembles the one in your finished application.

What do you want to do?

Create menus or menu items

Select menus or menu items

Move and copy menus and menu items


Creating Menus or Menu Items

Home Page (Menu Editor) | Overview | How Do I ... Topics

You can create menus, cascading menus, and menu commands on the menu bar in the Menu editor.

What do you want to do?

Create a menu on the menu bar

Create a menu item

Create a cascading (hierarchical) menu

To create a menu on the menu bar

  1. Select the new-item box (an empty rectangle) on the menu bar. Or move the new-item box to a blank spot with the RIGHT ARROW and LEFT ARROW keys.

  2. Type the name of the menu.

    When you start typing, focus automatically shifts to the Menu Item property page, and the text you type appears both in the Caption box and in the Menu editor window.

    You can define a mnemonic key that allows the user to select the menu with the keyboard. Type an ampersand (&) in front of a letter to specify it as the mnemonic. Make sure all the mnemonics on a menu bar are unique.

    Once you have given the menu a name on the menu bar, the new-item box shifts to the right, and another new-item box opens below for adding menu items.

    Note To create a single-item menu on the menu bar, clear the Pop-up check box on the Menu Item property page.

To create a menu item

  1. Create a menu according to the steps outlined in To create a menu on the menu bar, or open an existing menu.

  2. Select the menu’s new-item box.

    –or–

    Select an existing menu item and press the INS key. The new-item box is inserted before the selected item.

  3. Type the name of the menu item. When you start typing, focus automatically shifts to the Menu Item property page, and the text you type appears in the Caption box.

    You can define a mnemonic key that allows the user to select the menu command. Type an ampersand (&) in front a letter to specify it as the mnemonic. The user can select the menu command by typing that letter.

  4. On the property page, select the menu item styles that apply.

  5. In the Prompt box on the property page, type the prompt string you want to appear in your application’s status bar.

    This creates an entry in the string table with the same resource identifier as the menu item you created.

  6. Press ENTER to complete the menu item.

    The new-item box is selected so you can create additional menu items.

To create a cascading (hierarchical) menu

  1. Select the new-item box on the menu where you want the cascading menu to appear. Then type the name of the menu item that, when selected, will cause the cascading menu to appear.

    When you start typing, focus automatically shifts to the Menu Item property page, and the text you type appears in the Caption box.

    –or–

    Select an existing menu item that you want to be the parent item of the cascading menu, and double-click.

  2. On the property page, select the Pop-up check box. This marks the menu item with the cascading menu symbol, and a new-item box appears to its right.

  3. Add additional menu items to the cascading menu according to the instructions in To create a menu item.


Selecting Menus and Menu Items

Home Page (Menu Editor) | Overview | How Do I ... Topics

To select a menu and display its menu items

  • Click the menu caption on the menu bar or the parent item of the cascading menu. Then click the menu item you want.

To select one or more menu items

  1. Click the menu or cascading menu you want.

  2. Click to select a menu item, or press the SHIFT key while clicking to select multiple menu items. Hold down the SHIFT key and click a selected menu item to deselect it.

    –or–

    With the pointer outside the menu, drag to draw a selection box around the menu items you want to select.


Moving and Copying Menus and Menu Items

Home Page (Menu Editor) | Overview | How Do I ... Topics

To move or copy menus or menu items using drag-and-drop

  1. Drag or copy the item you want to move to:
    • A new location on the current menu.

    • A different menu. (You can navigate to other menus by dragging the mouse pointer over them.)
  2. Drop the menu item when the insertion guide shows the position you want.

To move or copy menus or menu items using the menu commands

  1. Select one or more menus or menu items.

  2. From the Edit menu, choose Cut (to move) or Copy.

  3. If you are moving the items to another menu resource or resource script file, make that Menu editor window active.

  4. Select the position of the menu or menu item you want to move or copy to.

  5. From the Edit menu, choose Paste. The moved or copied item is placed before the item you select.

Note You can also drag, copy, and paste to other menus in other menu windows.


Home Page: String Editor

The String editor allows you to edit your application’s string table. You can use the Find command to locate specific strings in the string table. You can also change the properties of several strings at the same time.

  • Overview

  • How Do I ... Topics

For information about the String Editor

  • Finding a string

  • Adding or deleting a string

  • Changing a string or its identifier

Related Home Pages

  • Resource Editors Home Page


Overview: String Editor

Home Page (String Editor) | How Do I ... Topics

A string table is a Windows resource that contains a list of IDs, values, and captions for all the strings of your application. For example, the status-bar prompts are located in the string table. An application can have only one string table.

String tables make it easy to localize your application into different languages. If all strings are in a string table, you can localize the application by translating the strings (and other resources) without changing source code.

With the String editor, you can edit a program’s string table resource. In a string table, strings are grouped into segments, or blocks, of 16 strings each. The segment a string belongs to is determined by the value of its identifier; for example, strings with identifiers of 0 to 15 are in one segment, strings with identifiers of 16 to 31 are in a second segment, and so on. Thus, to move a string from one segment to another you need to change its identifier.

Individual string segments are loaded on demand in order to conserve memory. For this reason, programmers usually try to group strings into logical groupings of 16 or less and then use each group or segment only when it is needed.

You can search for one or more strings in the string table, and use regular expressions with the Find command to locate all instances of strings that match a pattern. Also, you can select multiple strings and change their properties at one time.

What do you want to do?

Find a string

Add or delete a string

Move a string from one segment to another

Move a string from one resource script file to another

Change a string or its identifier

Change the properties of multiple strings

Add formatting or special characters to a string

Tip While using the String editor, in many instances you can click the right mouse button to display a shortcut menu of resource-specific commands. The commands available depend on what the pointer is pointing to. For example, if you click while pointing to a string table entry, the shortcut menu shows the Cut, Copy, New String, and Properties commands.

Note Windows does not allow the creation of empty string tables. If you create a string table with no entries, it is deleted automatically when you exit the visual development environment.


How Do I ... Topics: String Editor

Home Page (String Editor) | Overview

What do you want to do?

Find a string

Add or delete a string

Move a string from one segment to another

Move a string from one resource script to another

Change a string or its identifier

Change the properties of multiple strings

Add formatting or special characters to a string


Finding a String

Home Page (String Editor) | Overview | How Do I ... Topics

To find a string in the string table

  1. In ResourceView, open the string table by double-clicking its icon.

  2. From the Edit menu, choose Find.

  3. In the Find What box, select a previous search string from the drop-down list, type the caption text or resource identifier of the string you want to find, or type a regular expression to match a pattern.

    Tip Click the button to the right of the Find What box to display a list of regular search expressions. When you select an expression from this list, it is substituted as the search text in the Find What box. If you use regular expressions, be sure the Regular Expression check box is selected.

  4. Select any of the Find options.

  5. Click Find Next.


Adding or Deleting a String

Home Page (String Editor) | Overview | How Do I ... Topics

When the String Editor window is displayed, you can add or delete entries in the string table. String table segments are separated by horizontal lines in the String Editor window.

What do you want to do?

Add a string table entry

Delete a string table entry

To add a string table entry

  1. Select the new-item box (an empty rectangle) at the end of a string segment.

  2. Type the new string.

    The focus shifts to the String Properties page as you start typing. The text is entered in the Caption box, and the string is given the next identifier in sequence.

  3. Press ENTER to place the new string in the string table.

Tip You can also insert new entries into the string table. Select an existing entry, and from the Insert menu, choose New String. The new string is placed after the currently selected string using the next available identifier.

Note Null strings are not allowed in Windows string tables. If you create an entry in the string table that is a null string, the entry is deleted when you close the String editor.

To delete a string table entry

  1. Select the string you want to delete.

  2. From the Edit menu, choose Delete.


Moving a String from One Segment to Another

Home Page (String Editor) | Overview | How Do I ... Topics

To move a string from one segment to another

  1. Select the string you want to move.

  2. From the View menu, choose Properties.

  3. Change the string’s value in the ID box so that it falls in the range you want.

    For example, to move a string with a name of IDS_MYSTRING and a value of 100 to a segment in the 200 range, type the following in the ID box:

    IDS_MYSTRING=201
  4. Press ENTER.


Moving a String from One Resource Script File to Another

Home Page (String Editor) | Overview | How Do I ... Topics

To move a string from one resource script file to another

  1. Open the String Editor windows in both resource script files.

  2. Select the string you want to move.

  3. From the Edit menu, choose Cut.

  4. Place the cursor in the target String Editor window.

  5. From the Edit menu, choose Paste.

Note If the ID or value of the moved string conflicts with an existing ID or value in the destination file, either the ID or the value of the moved string changes. If a string exists with the same ID, the ID of the moved string changes. If a string exists with the same value, the value of the moved string changes.


Changing a String or Its Identifier

Home Page (String Editor) | Overview | How Do I ... Topics

To change a string or its identifier

  1. Select the string you want to edit.

  2. From the View menu, choose Properties, and modify the string in the Caption box.

  3. In the ID box, modify the string’s identifier:
    • Type a new ID, or select one from the list.

    • To change a string’s value, type the ID followed by an equal sign and the new value; for example:
      IDS_ERROR_MSG=2350
  4. Press ENTER.


Changing the Properties of Multiple Strings

Home Page (String Editor) | Overview | How Do I ... Topics

To change the properties of multiple strings

  1. Select the strings you want to change by holding down the CTRL key as you click each one.

  2. From the View menu, choose Properties.

    The Multiple Selection Properties page displays. Changes you make on this page are reflected on each item selected. If you need to undo a change, choose Undo from the Edit menu. The change is undone on each item selected.


Adding Formatting or Special Characters to a String

Home Page (String Editor) | Overview | How Do I ... Topics

To add formatting or special characters to a string

  1. Select the string you want to modify.

  2. From the View menu, choose Properties.

  3. Add any of the standard escape sequences listed below to the text in the Caption box, and press ENTER.
    To get this | Type this
    New line | \n
    Carriage return | \r
    Tab | \t
    Backslash (\) \\
    ASCII character | \ddd (octal notation)
    Alert (bell) | \a


Home Page: Toolbar Editor

The Toolbar editor is a graphic tool that supports the creation of toolbar resources and the conversion of bitmaps into toolbar resources.

  • Overview

  • How Do I ... Topics

For information about the Toolbar editor

  • Creating new toolbars

  • Converting bitmaps to toolbars

  • Creating, moving, or editing toolbar buttons

Related Home Pages

  • Resource Editors Home Page

  • Graphics Editor Home Page


Overview: Toolbar Editor

Home Page | How Do I ... Topics

The Toolbar editor enables you to create toolbar resources and convert bitmaps into toolbar resources. The Toolbar editor uses a graphic display to show a toolbar and buttons that closely resemble how they will look in a finished application.

With the Toolbar editor, you can:

  • Create new toolbars and buttons.

  • Convert bitmaps to toolbar resources.

  • Create, move, and edit toolbar buttons.

The Toolbar editor window shows two views of a button image, the same as the Graphics editor window. A split bar separates the two panes. You can drag the split bar from side to side to change the relative sizes of the panes. The active pane displays a selection border.

Above the two views of the image is the display of the subject toolbar, indicated by white space surrounding the subject toolbar. The selected button in this toolbar shows a fuzzy border.

The Toolbar editor is similar to the Graphics editor in functionality. The menu items, graphic tools, and bitmap grid are the same as those in the Graphic editor. For more information on using the Graphics toolbar, Colors palette, or Image menu, see Image Editor Window and Tools.

What do you want to know more about?

Graphical resources

Color

What do you want to do?

Create new toolbar resources

Convert bitmaps to toolbars

Create, move, or edit toolbar buttons

Create a ToolTip


How Do I ... Topics: Toolbar Editor

Home Page (Toolbar Editor) | Overview

What do you want to do?

Create new toolbars

Convert bitmaps to toolbars

Create, move, or edit toolbar buttons

Create a ToolTip


Creating New Toolbars

Home Page (Toolbar Editor) | Overview | How Do I ... Topics

There are two ways to create a new toolbar:

  • From the Insert menu, choose Resource; then choose Toolbar as the resource type.

  • Convert an existing bitmap to a toolbar.

    For more information on converting bitmaps, see Converting Bitmaps to Toolbars.

For information on editing the new toolbar, see Creating, Moving and Editing Toolbar Buttons.

To create a new toolbar resource

  1. From the Insert menu, choose Resource.

  2. In the Resource Type list, select Toolbar, and click OK.

If a plus sign (+) appears next to the Toolbar resource type, it means that toolbar templates are available. Click the plus sign to expand the list of templates, select a template, and click OK.


Converting Bitmaps to Toolbars

Home Page (Toolbar Editor) | Overview | How Do I ... Topics

You can create a new toolbar by converting a bitmap. You can also create a new toolbar using the Insert menu (see Creating New Toolbar Resources).

The graphic from the bitmap converts to the button images for a toolbar. Usually the bitmap contains several button images on a single bitmap, with one image for each button. Images can be any size; the default is 16 x 16 pixels. You can specify the size of the button images in the New Toolbar dialog box when you choose Toolbar Editor from the Image menu in the Graphics editor.

You can change the command IDs of the buttons on the new toolbar by using the button property pages. For information on editing the new toolbar, see Creating, Moving and Editing Toolbar Buttons.

To convert bitmaps to a toolbar

  1. Open an existing bitmap resource in the Graphics editor.

  2. From the Image menu, choose Toolbar Editor.

    The New Toolbar Resource dialog box appears. You can change the width and height of the icon images to match the bitmap. The toolbar image is then displayed in the Toolbar editor.

  3. To finish the conversion, change the command IDs of the buttons on the toolbar:
    • Open the property page for the toolbar button. (From the View menu, choose Properties.)

    • Type in the new ID, or select an ID from the drop-down list.

Tip Click the Pushpin button on the property page to cycle through all the toolbar buttons without having to reopen the individual property pages.


Creating, Moving, and Editing Toolbar Buttons

Home Page (Toolbar Editor) | Overview | How Do I ... Topics

You can easily create, move, copy, and edit toolbar buttons.

By default, a new or blank button is displayed at the right end of the toolbar. You can move this button before editing it. When you create a new button, another blank button appears to the right of the edited button. When you save a toolbar, the blank button is not saved.

What do you want to do?

Create a new toolbar button

Move a toolbar button

Copy buttons from a toolbar resource

Delete a toolbar button

Insert a space between buttons on a toolbar resource

Close up a space between buttons on a toolbar

Edit the property page of a toolbar

To create a new toolbar button

  • Assign an ID to the blank button at the right end of the toolbar. Open the property page on that toolbar button to edit the ID box.

    –or–

  • Select the blank button at the right end of the toolbar, and begin drawing. A default button command ID is assigned (ID_BUTTON<n>).

To move a toolbar button

  • Drag the button that you want to move to its new location on the toolbar.

To copy buttons from a toolbar

  1. Hold down the CTRL key.

  2. Drag the button to either its new location on the toolbar or to a location on another toolbar.

To delete a toolbar button

  • Select the toolbar button, and drag it off the toolbar.

To insert a space between buttons on a toolbar

  1. To insert a space before a button that is not followed by a space, drag the button to the right or down until it overlaps the next button about halfway.

  2. To insert a space before a button that is followed by a space and retain the space following the button, drag the button until the right or bottom edge is just touching the next button or just overlaps it.

  3. To insert a space before a button that is followed by a space and close up the following space, drag the button to the right or down until it overlaps the next button about halfway.

To close up a space between buttons on a toolbar

  • Drag the button on one side of the space toward the button on the other side of the space until it overlaps the next button about halfway.

    If there is no space on the side of the button that you are dragging away from, and you drag the button more than halfway past the adjacent button, the Toolbar editor also inserts a space on the opposite side of the button that you are dragging.


Editing the Property Page of a Toolbar Button

Home Page (Toolbar Editor) | Overview | How Do I ... Topics

The property page of a toolbar button contains the button ID, the width and height, and the prompt. The ID box has a drop-down list containing common ID names. The Prompt box defines the message displayed in the status bar. Adding \n and a name adds a ToolTip to that toolbar button. For more information, see Creating a ToolTip.

To change the ID of a toolbar button

  1. Select the toolbar button.

  2. From the View menu, choose Properties.

  3. Type the new ID in the ID box, or use the drop-down list to select a new ID.


Creating a ToolTip

Home Page (Toolbar Editor) | Overview | How Do I ... Topics

To create a ToolTip

  1. Select the toolbar button.

  2. From the View menu, choose Properties.

  3. In the Prompt box, add a description of the button for the status bar; after the message, add \n and the ToolTip name.


Home Page: Version Information Editor

Version information consists of company and product identification, a product release number, and copyright and trademark notification. The Version Information editor is a tool for creating and maintaining this data. You can use the Find command to search for version information that you want to change.

  • Overview

  • How Do I ... Topics

For information about the Version Information editor

  • Editing a version information resource

  • Adding a new string block

  • Deleting a string block

  • Finding a string block

Related Home Pages

  • Resource Editors Home Page


Overview: Version Information Editor

Home Page (Version Information Editor) | How Do I ... Topics

Version information consists of company and product identification, a product release number, and copyright and trademark notification. The Version Information editor is a tool for creating and maintaining this data. Although the version information resource is not required by an application, it is a useful place to collect this information that identifies the application.

A single version information resource can contain multiple string blocks, each representing a different language or character set. All you need to do is define the character sets and languages that are specific to your product.

With the Version Information editor, you can add or delete string blocks, search for values, and modify individual string values.

Note The Windows standard is to have only one version resource, named VS_VERSION_INFO.

If you wish to access the version information from within your program, your application can make use of the GetFileVersionInfo function and the VerQueryValue function. For additional information on how to access version information, see the online Microsoft Win32 Programmer’s Reference, Volume 2.

Tip While using the Version Information editor, in many instances, you can click the right mouse button to display a shortcut menu of resource-specific commands. For example, if you click while pointing to a block header entry, the shortcut menu shows the New String Block and Delete String Block commands.

For information about common resource edit procedures such as creating new resources, opening existing resources, and deleting resources, see Resource Editors How Do I ... Topics.

What do you want to do?

Edit the version information


How Do I ... Topics: Version Information Editor

Home Page (Version Information Editor) | Overview

With the Version Information editor, you can add or delete string blocks, search for values, and modify individual string values.

A version information resource has a single fixed-information block at the top and one or more string information blocks at the bottom. The top block has both editable numeric boxes and selectable drop-down lists. The bottom string block has editable text boxes.

You can sort the information sequence of the string block by clicking either the Key or the Value buttons. These buttons automatically rearrange the information into the selected sequence.

What do you want to do?

Edit a version information resource

Add a new string block

Delete a string block

Find a string value

To edit a version information resource

  • Double-click the item you want to edit, and make the changes.

    Note When editing the FILEFLAGS property page, you cannot set the DEBUG flag for .rc files because the Version Information Editor sets that flag with an #ifdef in the resource script, based on the _DEBUG build flag.

To add a new string block

  1. Open a version information resource.

  2. From the Insert menu, choose New Version Info Block.

    This command appends an additional string information block into the current version information resource and opens the Block Header property page.

  3. On the Block Header property page, choose the appropriate language and character set for the new block.

To delete a string block

  1. With a version information resource open, select one of the block headers.

  2. From the Insert menu, choose Delete Version Info Block.

    This command deletes the selected header and leaves the remaining version information intact.

To find a string value

  1. From the Edit menu, choose Find.

  2. In the Find What box, select a previous search string from the drop-down list, type the string you want to find, or type a regular expression to match a pattern.

    Tip Click the button to the right of the Find What box to display a list of regular search expressions. When you select an expression from this list, it is substituted as the search text in the Find What box. If you use regular expressions, be sure the Regular Expression check box is selected.

  3. Select any of the Find options.

  4. Click Find Next.


Home Page: Debugger

The Microsoft visual development environment and DIGITAL Visual Fortran provide an integrated debugger to help locate bugs in an executable program, dynamic-link library (DLL), thread, or OLE or Active X component.

  • Overviews

  • How Do I... Topics

For information about debugging:

The debugger interface

Running to a location

Setting breakpoints

Stepping into functions

Modifying the value of a variable

Related Home Pages

  • Source Code Control Home Page

  • Working with Projects Home Page


Overview: The Debugging Interface

Home Page (Debugger) | How Do I... Topics

Debugging is the process of correcting or modifying the code in your project so that your project can build, run smoothly, act as you expected, and be easy to maintain later.

To this end, the visual development environment provides a variety of tools to help with the varied tasks of tracking down errors in the code and program components.

The debugger interface provides special menus, windows, dialog boxes, and spreadsheet fields. Drag-and-drop functionality is available for moving debug information between components. Occasionally the debugger is paused in break mode, meaning the debugger is waiting for user input after completing a debugging command (like break at breakpoint, step into/over/out/to cursor, break at exception, break after Break command or Restart).

For an introduction to debugging Visual Fortran projects, see the Visual Fortran Programmer's Guide section Debugging Fortran Programs.

What do you want to know more about?

Debug build versus release build

Debugger menu items

Debugger windows

Debugger dialog boxes

Drag and drop information

Using spreadsheet fields

Viewing the value of a variable

Modifying the value of a variable


Debug Build Versus Release Build

Home Page (Debugger) | Overview | How Do I... Topics

When you create a project using the visual development environment, both a Debug and a Release version are automatically created with default options set for each.

Version | Default Values
Debug version | Full symbolic debugging information in Microsoft format No optimization (optimization generally makes debugging more difficult)
Release version | No symbolic debugging information Optimized for maximum speed

Note By using the Fortran tab in the Project Settings dialog, you can change the debugging options for the compiler. Similarly, on the Link tab, by using the Debug Category, you can change the debugging options for the linker.

What do you want to do?

Change the default project settings for a debug build


Debugger Menu Items

Home Page (Debugger) | Overview | How Do I... Topics

Commands for debugging can be found on the Build menu, the Debug menu, the View menu, and the Edit menu.

The Build menu contains a command called Start Debug, which contains a subset of the commands on the full Debug menu. These commands start the debugging process (Go, Step Into, Run To Cursor and Attach to Process). The Debug menu appears in the menu bar while the debugger is running (even if it is stopped at a breakpoint). From the Debug menu, you can control program execution and access the QuickWatch window. When the debugger is not running, the Debug menu is replaced by the Build menu.

The View menu contains commands that display the various debugger windows, such as the Variables window and the Call Stack window.

From the Edit menu, you can access the Breakpoints dialog box, from which you can insert, remove, enable, or disable breakpoints.

What do you want to know more about?

Debug options on the Build/Debug menu.

Debugger Windows

What do you want to do?

Set breakpoints

Viewing, removing, enabling, and disabling breakpoints.


Debug Options on the Build/Debug Menu

Home Page (Debugger) | Overview | How Do I... Topics

To start debugging, choose the Go, Step Into, Run To Cursor or Attach to Process command from the Start Debug submenu of the Build menu. The following table lists the Start Debug menu commands that may appear and their actions.

Start Debug Commands (Build menu)

Menu command | Action
Go | Executes code from the current statement until a breakpoint or the end of the program is reached, or until the application pauses for user input. (Equivalent to the Go button on the toolbar.)
Step Into | Single-steps through instructions in the program, and enters each function (or subroutine) call that is encountered. With Visual Fortran programs, avoid using this menu command for initial program execution. Instead, set a breakpoint or insertion point at the first executable line of Fortran source code and either use Go or Run to Cursor. This avoids entering the Visual Fortran run-time initialization code that is executed before your main Fortran routine.
Run to Cursor | Executes the program as far as the line that contains the insertion point. This is equivalent to setting a temporary breakpoint at the insertion point location.
Attach to Process | Attaches the debugger to a process that is running. Then you can break into the process and perform debugging operations like normal.

When you begin debugging, the Debug menu appears, replacing the Build menu on the menu bar. You can then control program execution using the commands listed in the following table.

Debug Menu Commands that Control Program Execution

Debug menu command | Action
Go | Executes code from the current statement until a breakpoint or the end of the program is reached, or until the application pauses for user input. (Equivalent to the Go button on the Standard toolbar.) When the Debug menu is not available, you can choose Go from the Start Debug submenu of the Build menu.
Restart | Resets execution to the first line of the program. This command reloads the program into memory, and discards the current values of all variables (breakpoints and watch expressions still apply). It automatically halts at the main( ) or WinMain( ) function.
Stop Debugging | Terminates the debugging session, and returns to a normal editing session.
Break | Halts the program at its current location.
Step Into | Single-steps through instructions in the program, and enters each function (or subroutine) call that is encountered. When the Debug menu is not available, you can choose Step Into from the Start Debug submenu of the Build menu. With Visual Fortran programs, avoid using this menu command for initial program execution.
Step Over | Single-steps through instructions in the program. If this command is used when you reach a function (or subroutine) call, the function (or subroutine) is executed without stepping through the function (or subroutine) instructions.
Step Out | Executes the program out of a function (or subroutine) call, and stops on the instruction immediately following the call to the function (or subroutine). Using this command, you can quickly finish executing the current function (or subroutine) after determining that a bug is not present in the function (or subroutine).
Run to Cursor | Executes the program as far as the line that contains the insertion point. This command is equivalent to setting a temporary breakpoint at the insertion point location. When the Debug menu is not available, you can choose Run To Cursor from the Start Debug submenu of the Build menu.

The following additional commands appear on the Debug menu:

Exceptions | Displays the Exceptions dialog, which you can use to specify how you want the debugger to handle your program exceptions.
Threads | Displays the Threads dialog, which you can use to suspend, resume, or set focus to progam threads.
Show Next Statement | Shows the next statement in your program code. If source code is not available, displays the statement within the Disassembly window.
QuickWatch | Displays the Quick Watch window, where you can work with expressions.


Debugger Windows

Home Page (Debugger) | Overview | How Do I... Topics

Several specialized windows display debugging information for your program. When you are debugging, you can access these windows using the View menu. (In addition to windows, the debugger also uses dialog boxes to display debugging information.)

The following table lists the debugger windows and describes the information they display.

Debugger Windows

Window | Displays
Output | Information about the build process, including any compiler, linker, or build-tool errors, thread termination codes, loading symbols notification and first-chance exception notifications.
Watch | Names and values of variables and expressions.
Variables | Information about variables used in the current and previous statements and function (or subroutine) return values (in the Auto tab), variables local to the current function or subroutine (in the Locals tab), and the object pointed to by this (in the This tab--available only if Visual C++ is also installed).
Registers | Contents of the general purpose and CPU status registers.
Memory | Current memory contents.
Call Stack | Stack of all function (or subroutine) calls that have not returned.
Disassembly | Assembly-language code derived from disassembly of the compiled program.

Debugger windows can be docked or floating. For more information, see Working with Floating or Docking Windows.

When a window is in floating mode, you can resize or minimize the window to increase the visibility of other windows. You can copy information from any debugger window. You can print information only from the Output window.

Tip To set formatting and other options for these windows, use the Debug tab in the Options dialog box (accessed from the Tools menu).

What do you want to know more about?

The Watch window

The Variables window

The Call Stack window

The Disassembly window

What do you want to do?

Use symbols for watch variables in the watch window


Watch Window

Home Page (Debugger) | Overview | How Do I... Topics

Use the Watch window to specify variables and expressions that you want to watch while debugging your program. You can also modify the value of a variable using the Watch window.

The Watch window contains four tabs: Watch1, Watch2, Watch3, and Watch4 — Each tab displays a user-specified list of variables and expressions in a spreadsheet field. You can group variables that you want to watch together onto the same tab. For example, you could put variables related to a specific window on one tab and variables related to a dialog box on another tab. You could watch the first tab when debugging the window and the second tab when debugging the dialog box.

If you add an array or user-defined structure variable to the Watch window, plus sign (+) or minus sign (–) boxes appear in the Name column. You can use these boxes to expand or collapse your view of the variable, as described in Spreadsheet Fields.

If the value of a variable appears in red, it indicates that the value has recently changed. Only the last value to change appears in red.

The Watch window displays values in their default format. You can change the display format (to display Unicode characters, for example) using formatting symbols. For details, see Symbols for Watch Variables.

Tip The Watch window does not display variable type information. You can view information for a variable type by using the window’s property page.

What do you want to do?

View the value of a variable

Modify the value of a variable


Variables Window

Home Page (Debugger) | Overview | How Do I... Topics

The Variables window provides quick access to variables that are important in the program’s current context. The window includes three tabs:

  • The Auto tab displays variables used in the current statement and in the previous statement. It also displays return values when you step over or out of a function (or subroutine).

  • The Locals tab displays the variables that are local to the current function (or subroutine).

  • The This tab displays the object pointed to by this (only is Visual C++ is installed).

Each tab contains a spreadsheet with fields for the variable name and value. The debugger automatically fills in these fields. If a value appears in red, it indicates that the value has recently changed. Only the last value to change appears in red.

You cannot add variables or expressions to the Variables window (you must use the Watch window to do so), but you can expand or collapse the variables shown using the tree controls. You can expand an array or structure variable in the Variables window if it has a plus sign (+) box in the Name field. If an array or structure variable has a minus sign (–) box in the Name field, the variable is already fully expanded. To expand or collapse the variable, click the + or – box, as described in Spreadsheet Fields.

In addition to the tabs, the Variables window has a context box on the toolbar that contains a copy of the current call stack in a drop-down list box. Use this list to specify the current scope of the variables displayed. The Context box is part of a toolbar, which you can hide using the right mouse button.

Navigating from the Variables Window

You can navigate to a function’s (or subroutine's) source code or disassembled object code from the Context box in the Variables window. This procedure displays the function’s (or subroutine's) source code, if it is available, in a source window. If source code for the selected function (or subroutine) is not available, it displays the function’s (or subroutine's) object code in the Disassembly window.

This procedure changes the view of the program displayed in the Variables window and other debugger windows, but does not change the next line of execution or the value stored in the program counter.

What do you want to do?

View the value of a variable

Modify the value of a variable


Symbols for Watch Variables

Home Page (Debugger) | Overview | How Do I... Topics

You can change the display format of variables in the QuickWatch dialog box or in the Watch window using the formatting symbols in the following table.

Symbol | Format | Value | Displays
d,i | signed decimal integer | 0xF000F065 | -268373915
o | unsigned octal integer | 0xF065 | 0170145
x,X | Hexadecimal integer | 61541 (decimal) | 0x0000F065
f | signed floating-point | 3./2. | 1.500000
e | signed scientific notation | 3./2. | 1.500000e+000
g | signed floating-point or signed scientific notation, whichever is shorter | 3./2. | 1.5
c | Single character | 0x0065 | 'e'
s | String | 0x0012fde8 | “Hello world”

To use a formatting symbol, type the variable name, followed by a comma and the appropriate symbol. For example, if var has a value of 0x0065, and you want to see the value in character form, type var,c in the Name column on the tab of the Watch window. When you press ENTER, the character-format value appears:

var,c = 'e'

You can use the formatting symbols shown in the following table to format the contents of memory locations.

Symbol | Format | Displays
ma | 64 ASCII characters | 0x0012ffac .4...0...".0W&.......1W&.0.:W..1...."..1.JO&.1.2.."..1...0y....1
m | 16 bytes in hexadecimal, followed by 16 ASCII characters | 0x0012ffac B3 34 CB 00 84 30 94 80 FF 22 8A 30 57 26 00 00 .4...0...".0W&..
mb | 16 bytes in hexadecimal, followed by 16 ASCII characters | 0x0012ffac B3 34 CB 00 84 30 94 80 FF 22 8A 30 57 26 00 00 .4...0...".0W&..
mw | 8 words | 0x0012ffac 34B3 00CB 3084 8094 22FF 308A 2657 0000
md | 4 doublewords | 0x0012ffac 00CB34B3 80943084 308A22FF 00002657

With the memory location formatting symbols, you can type any value or expression that evaluates to a location.

A formatting character can follow an expression also:

rep+1,x
xloc,g
count,d

Note You can apply formatting symbols to structures, arrays, and pointers as unexpanded variables only. If you expand the variable, the specified formatting affects all members. You cannot apply formatting symbols to individual members.


Call Stack Window

Home Page (Debugger) | Overview | How Do I... Topics

During a debug session, the Call Stack window displays the stack of function (or subroutine) calls that are currently active. When a function (or subroutine) is called, it is pushed onto the stack. When the function (or subroutine) returns, it is popped off the stack.

The Call Stack window displays the currently executing function (or subroutine) at the top of the stack and older function (or subroutine) calls below that. By default, the window also displays parameter types and values for each function (or subroutine) call. You can display or hide parameter types and values using the Debug tab of the Options dialog box or the right mouse button shortcut menu.

You can navigate to a function’s (or subroutine's) source code or disassembled object code from the Call Stack window. If source code for the selected function (or subroutine) is not available, it displays the function’s (or subroutine's) object code in the Disassembly window.

Navigating to a function's (or subroutine's) code changes the view of the program shown in the Variables window and other debugger windows, but does not change the next line of execution or the value stored in the program counter.

What do you want to do?

Set a breakpoint at the return address of a function

View the call stack for a function

Run to the cursor location in the call stack


Disassembly Window

Home Page (Debugger) | Overview | How Do I... Topics

The Disassembly window can be especially useful for debugging optimized code, as well as source-code lines that contain multiple statements. Consider, for example, the following line of code:

x=1; y=7; Z=3;

The source window treats each line of code as a unit. Using the source window, you cannot step from one statement on a source-code line to the next, or set a breakpoint on any statement other than the first.

The Disassembly window operates on disassembled (assembly-language or bytecode) instructions instead of source-code statements or lines. Using the Disassembly window, you can set a breakpoint on any instruction. If you use the Step Into or Step Over command while the Disassembly window has focus, the debugger steps through your program instruction-by-instruction instead of line-by-line. Viewing and stepping through your code by disassembled instructions can be especially useful when you are debugging optimized code.

What do you want to do?

View disassembly code


Debugger Dialog Boxes

Home Page (Debugger) | Overview | How Do I... Topics

In addition to windows, the debugger uses a number of dialog boxes to manipulate breakpoints, variables, threads, and exceptions. You can access the Breakpoints dialog box using the Breakpoints command on the Edit menu. You can access the other dialog boxes using commands from the Debug menu.

The following table lists the debugger dialog boxes and describes the information they display.

Debugger Dialog Boxes

Dialog box | Displays
Breakpoints | A list of all breakpoints assigned to your project. Use the tabs in the Breakpoints dialog box to create new breakpoints of various types.
Exceptions | System and user-defined exceptions for your project. Use the Exceptions dialog box to control how the debugger handles exceptions.
QuickWatch | A variable or expression. Use QuickWatch to quickly view or modify a variable or expression or to add it to the Watch window.
Threads | Application threads available for debugging. Use the Threads dialog box to suspend and resume threads and to set focus.


QuickWatch Dialog Box

Home Page (Debugger) | Overview | How Do I... Topics

The QuickWatch dialog box contains a text box, where you can type an expression or variable name, and a spreadsheet field that displays the current value of the variable or expression that you specified.

You can use QuickWatch to quickly examine the value of a variable or expression. You can also use QuickWatch to modify the value of a variable or to add a variable or expression to the Watch window.

The Current Value spreadsheet field displays only one variable or expression at a time. If you type a new variable or expression in the text box and press ENTER, the previous variable or expression in the Current Value field is replaced.

Display of a Scalar Variable or Expression

If you type a scalar variable or expression in the text box, QuickWatch displays the result on the first line of the spreadsheet. If you type an array or structure variable, however, QuickWatch uses the spreadsheet to show additional detail. Plus sign (+) and minus sign (-) boxes appear. Click these boxes to expand or collapse your view of the variable.

What do you want to do?

View the Value of a Variable

Modify the Value of a Variable


Drag and Drop Information

Home Page (Debugger) | Overview | How Do I... Topics

The debugger interface supports intelligent drag-and-drop operations. The result of a drag-and-drop operation depends, in part, on the location where the drop takes place.

For example, you can drag a variable from the Variables window to the Watch window. This action puts the variable information into the Watch window, where it is updated each time the Watch window is updated. If you drag the variable to a text window instead, the variable information is converted into text. If you drag the variable to the Memory window or the Disassembly window, the variable is used as a pointer, and the window scrolls to display the memory contents or instructions at the indicated address.


Spreadsheet Fields

Home Page (Debugger) | Overview | How Do I... Topics

The debugger interface uses spreadsheet fields, which have an interface similar to that of Microsoft Excel. These spreadsheet fields appear in the Watch window, the Variables window, and the QuickWatch dialog box.

The window where the spreadsheet field is located determines which cells are editable. In the Variables window, you can edit the cells in the Value column. In the Watch window, you can edit the cells in the Name and Value columns.

Spreadsheet fields contain controls for easy viewing of array, structure, and pointer variables. If the variable is an array or structure, the branch below the variable contains the component elements or members.

The variables are marked with a box containing a plus sign (+) in the Name column. You can expand the variable by clicking the + box, which opens into a tree that may contain additional boxes. When a variable is expanded, the box in the Name column contains a minus sign ( –). You can collapse an expanded variable by clicking the – box. As an alternative, you can expand a variable by selecting it and pressing the PLUS SIGN or RIGHT ARROW key. You can collapse a variable by selecting it and pressing the MINUS SIGN or LEFT ARROW key.

Scalar variables, which have no components to expand, do not have boxes in the Name column.

When working with these fields, you can autosize a column to fit its contents by double-clicking the divider. You can size a column manually by dragging the divider at the right edge of the column.

Note Rows fit the current font and cannot be resized. To change the font size, use the Format tab of the Options dialog box, accessed from the Tools menu.


How Do I... Topics: Debugging

Home Page (Debugger) | Overview

The visual development environment provides a variety of tools to help with the varied tasks of tracking down errors in the code and program components.

The debugger interface provides special menus, windows, dialog boxes, and spreadsheet fields. Drag-and-drop functionality is available for moving debug information between components.

What do you want to know more about?

The debugger interface

What do you want to do?

Start the debugger

Run to a location

Halt a program

Set a breakpoint

View and enable a breakpoint

Step into a function

Step over or out of a function

View the value of a variable or contents of a register

View the contents of the Thread Information Block

View the last error code for the current thread

Modify the value of a variable or contents of a register

View disassembly code

View the call stack

Use COFF-format debugging information or DLL exports


Starting the Debugger

Home Page (Debugger) | Overview | How Do I... Topics

To start debugging

  1. Click Start Debug on the Build menu. With Visual Fortran, set a breakpoint or create an insertion point at the first executable Fortran statement.

  2. Click Go (if you set a breakpoint) or Run to Cursor (if you created an insertion point).

What do you want to know more about?

Debug options on the Build/Debug menu.


Running to a Location

Home Page (Debugger) | Overview | How Do I... Topics

What do you want to do?

Run until a breakpoint is reached

Run to the cursor

Run to the cursor location in object code

Run to the cursor location in the call stack

Run to a specified function

Set the next statement to execute

Set the next disassembled instruction to execute

To run until a breakpoint is reached

  1. Set a breakpoint.

  2. On the Build menu, click Start Debug.

  3. From the Start Debug menu, choose Go.

To run to the cursor (while the debugger is not running)

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

  2. From the Build menu, select Start Debug and Run To Cursor.

To run to the cursor (while the debugger is running but halted)

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

  2. From the Debug menu, choose Run To Cursor.

To run to the cursor location in disassembly code (while the debugger is running but halted)

  1. In the Disassembly window, move the insertion point to the location where you want the debugger to break.

  2. On the Debug menu, click Run To Cursor.

To run to the cursor location in the call stackcode (while the debugger is running but halted)

  1. In the Call Stack window, select the function (or subroutine) name.

  2. From the Debug menu, choose Run To Cursor.

To run to a specified function (or subroutine)

  1. In the Find box on the standard toolbar, type the function (or subroutine) name.

  2. On the Build menu, click Start Debug.

  3. On the Start Debug menu, click Run To Cursor.

Tip You can use the Run To Cursor command to return to an earlier statement to retest your application, using different values for variables.

To set the next statement to execute (while the debugger is running but halted)

  1. In a source window, move the insertion point to the statement or instruction that you want to execute next.

  2. Click the right mouse button.

  3. On the shortcut menu, click Set Next Statement.

To set the next disassembled instruction to execute (while the debugger is running but halted)

  1. In the Disassembly window, move the insertion point to the disassembled instruction you want to execute next.

  2. Click the right mouse button.

  3. On the shortcut menu, click Set Next Statement.

Tip You can use the Set Next Statement command to skip a section of code. For instance, a section that contains a known bug — and continue debugging other sections.

Caution The Set Next Statement command causes the program counter to jump to the new location. The intervening code is not executed. Use this command with caution.


Halting a Program

Home Page (Debugger) | Overview | How Do I... Topics

To halt debugging

  • Click Break on the Debug menu.

    Control returns to Visual Fortran.


Setting Breakpoints

Home Page (Debugger) | Overview | How Do I... Topics

Use the Breakpoints dialog box (accessed by the Breakpoints command on the Edit menu), to set, remove, disable, enable, or view breakpoints. The breakpoints you set will be saved as a part of your project.

Note You must have a project open before you can set a breakpoint. With no project open, the Breakpoints command does not appear on the Edit menu.

You can set breakpoints on a source-code line or in the Disassembly or Call Stack window.

What do you want to do?

Set a breakpoint at a source-code line

Set a breakpoint at the beginning of a function

Set a breakpoint at the return point of a function

Set a breakpoint at a label

To set a breakpoint at a source-code line

  1. In a source window, move the insertion point to the line where you want the program to break.

  2. Choose the Insert/Remove Breakpoint toolbar button.

    A red dot appears in the left margin, indicating that the breakpoint is set.

    Note If you want to set a breakpoint on a source statement extending across two or more lines, you must set the breakpoint on the last line of the statement.

To set a breakpoint at the beginning of a function (or subroutine)

  1. In the Find box on the Standard toolbar type the function (or subroutine) name.

  2. Click the Insert/Remove Breakpoint toolbar button.

    While in debug mode a red dot appears in your source code in the left margin at the beginning of the function (or subroutine), indicating that the breakpoint is set.

To set a breakpoint at the return point of a function (or subroutine)

  1. Start debugging, and pause the debugger in break mode (program is waiting for user input after completing a debugging command).

  2. On the View menu, click Debug Windows, then click Call Stack.

  3. In the Call Stack window, move the insertion point to the function (or subroutine) where you want the program to break.

  4. Click the Insert/Remove Breakpoint toolbar button.

    While in debug mode a red dot appears in the left margin of your source code, indicating that the breakpoint is set.

To set a breakpoint at a label

  1. In the Find box on the Standard toolbar type the name of the label.

  2. Click the Insert/Remove Breakpoint toolbar button.

    While in debug mode a red dot appears in your source code, in the left margin at the line containing the label, indicating that the breakpoint is set.


Viewing and Enabling Breakpoints

Home Page (Debugger) | Overview | How Do I... Topics

If you set more than one location breakpoint on a line, and some breakpoints are disabled while others are enabled, a gray dot appears in the left margin in the Source window, Disassembly window, and/or Call Stack window (not the Breakpoints dialog). The first time you click the Enable/Disable Breakpoint toolbar button, all breakpoints on the line become disabled, and the gray dot changes to a hollow circle. If you click the Enable/Disable Breakpoint button again, all breakpoints on the line become enabled, and the hollow circle changes to a red dot.

An asterisk (*) in the breakpoint check box indicates that the breakpoint is not supported on the current platform.

What do you want to do?

View the list of current breakpoints

Disable a breakpoint

Disable all location breakpoints

Enable a breakpoint

Remove a breakpoint

View the source code where a breakpoint is set

To view the list of current breakpoints

  1. On the Edit menu, click Breakpoints.

  2. Use the scroll bar to move up or down the Breakpoints list.

To disable a breakpoint

  1. For a location breakpoint in a source code window, or in the Call Stack or Disassembly window, move the insertion point to the line containing the breakpoint you want to disable.

  2. Click the Enable/Disable Breakpoint toolbar button, or click the right mouse button, and choose Disable Breakpoint from the shortcut menu.

– or –

  3. For any breakpoint in the Breakpoints dialog box, find the breakpoint in the Breakpoints list.

  4. Clear the check box corresponding to the breakpoint that you want to disable.

  5. Click OK.

    For a location breakpoint, the red dot in the left margin changes to a hollow circle.

Tip You can also use the SPACEBAR to toggle the state of one or more breakpoints in the Breakpoints list.

To disable all location breakpoints

  • Click the Disable All Breakpoints toolbar button.

    The red dots in the left margin change to hollow circles.

To enable a breakpoint

  1. For a location breakpoint, in a source code window, or in the Call Stack or Disassembly window, move the insertion point to the line containing the breakpoint you want to enable.

  2. Click the Enable/Disable Breakpoint toolbar button, or click the right mouse button, and choose Enable Breakpoint from the shortcut menu.

    – or –

  3. In the Breakpoints dialog box, find the breakpoint in the Breakpoints list.

  4. Select the empty check box corresponding to the breakpoint that you want to enable.

  5. Click OK.

    For a location breakpoint, the hollow circle in the left margin changes to a red dot.

Tip You can also use the SPACEBAR to toggle the state of one or more breakpoints in the Breakpoints list.

To remove a breakpoint

  1. For a location breakpoint in a source window, or in the Call Stack or Disassembly window, move the insertion point to the line containing the breakpoint you want to remove.

  2. Click the Insert/Remove Breakpoint toolbar button, or click the right mouse button, and choose Remove Breakpoint from the shortcut menu.

    – or –

  3. In the Breakpoints dialog box, select one or more breakpoints in the Breakpoints list.

  4. Click the Remove button, or press the DELETE key.

  5. Click OK.

    For a location breakpoint, the red dot in the left margin disappears.

To view the source code where a breakpoint is set

  1. In the Breakpoints list, select a location breakpoint.

  2. Click the Edit Code button.

This action takes you to the source code for a breakpoint set at a line number or function (or subroutine) name. In the case of function (or subroutine) names, the debugger must be running for this to work.


Stepping Into Functions

Home Page (Debugger) | Overview | How Do I... Topics

What do you want to do?

Run the program and execute the next statement

To run the program and execute the next statement (Step Into)

  1. While the program is paused in break mode (program is waiting for user input after completing a debugging command), click Step Into from the Debug menu.

    The debugger executes the next statement, then pauses execution in break mode. If the next statement is a function (or subroutine) call, the debugger steps into that function (or subroutine), then pauses execution at the beginning of the function (or subroutine).

  2. Repeat step 1 to continue executing the program one statement at a time.

If you step into a nested function (or subroutine) call, the debugger steps into the most deeply nested function (or subroutine). For example, on the line of code Fun(Fun2); the debugger steps into the function Fun2, then pauses.


Stepping Over or Out of Functions

Home Page (Debugger) | Overview | How Do I... Topics

What do you want to do?

Step over a function

Step out of a function

To step over a function (or subroutine)

  1. Open a source file, and start debugging.

  2. Execute the program to a function (or subroutine) call.

  3. On the Debug menu, click Step Over.

    The debugger executes the next function (or subroutine), but pauses after the function (or subroutine) returns.

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

To step out of a function (or subroutine)

  1. Start debugging, and execute the program to some point inside the function (or subroutine).

  2. On the Debug menu, click Step Out.

    The debugger continues until it has completed execution of the return from the function (or subroutine), then pauses.

Caution In general, to avoid very slow execution, you should not step out of a function (or subroutine) containing a loop. Instead, you should set a breakpoint at the end of the function (or subroutine), and then choose Go from the Debug menu to execute to the end of the function (or subroutine). Then choose Step Out.


Viewing the Value of a Variable or Contents of a Register

Home Page (Debugger) | Overview | How Do I... Topics

What do you want to do?

View the value of a variable or expression or the contents of a register

View the value of a variable using QuickWatch

View a the value of a variable or expression or the contents of a register in the Watch window

View type information for a variable in the Watch window

View a variable in the Variables window

View type information for a variable in the Variables window

To view the value of a variable or expression or contents of a register

  1. Wait for the debugger to stop at a breakpoint.

    – or –

    Click Break on the Debug menu to halt the debugger.

  2. On the Debug menu, click QuickWatch.

  3. Type or paste the variable or register name or an expression into the Expression text box, and click Recalculate.

  4. Click Close.

Tip The Expression drop-down list box contains the most recently used QuickWatch expressions.

To view the value of a variable using QuickWatch

  1. When the debugger is stopped at a breakpoint, switch to a source window, and click the right mouse button on a variable (Var, for example).

  2. On the shortcut menu, click QuickWatch Var.

  3. Click Close.

To view the value of a variable or expression or the contents of a register in the Watch window

  1. Start debugging, and pause the debugger in break mode (program is waiting for user input after completing a debugging command).

  2. On the View menu, click Debug Windows, then click Watch.

  3. Select a tab for the variable or expression.

  4. Type, paste, or drag the variable or register name or an expression into the Name column on the tab.

    Press ENTER (if typing).

    The Watch window evaluates the variable or expression immediately and displays the value or an error message.

If you add an array or structure variable to the Watch window, plus sign (+) or minus sign (–) boxes appear in the Name column. Use these boxes to expand or collapse your view of the variable described in Spreadsheet Fields.

Change the Watch window display format (to display Unicode characters, for example) using formatting symbols, described in Symbols for Watch Variables.

To view type information for a variable in the Watch window

  1. In the Watch window, select the line containing the variable whose type you want to see.

  2. On the View menu, click Properties.

To view a variable in the Variables window

  1. Start debugging, and pause the debugger in break mode (program is waiting for user input after completing a debugging command).

  2. On the View menu, click Debug Windows, then click Variables.

  3. Click the Auto tab or Locals tab according to the type of variables you want to see.

To view type information for a variable in the Variables window

  1. In the Variables window, click the Auto tab or Locals tab.

  2. Select the line containing the variable whose type you want to see.

    On the View menu, click Properties.


Viewing the Contents of the Thread Information Block

Home Page (Debugger) | Overview | How Do I... Topics

You can view the contents of the Thread Information Block (TIB) for the current thread. The debugger uses a pseudoregister called TIB for this purpose. You can view the contents of this pseudoregister in the Watch window or Quickwatch dialog using the standard procedures for displaying registers (discussed in Viewing the Value of a Variable or Contents of a Register).

For information on Thread Information Blocks, see "Under the Hood" in the May 1996 edition of the Microsoft Systems Journal.


Viewing the Last Error Code for the Current Thread

Home Page (Debugger) | Overview | How Do I... Topics

You can view the last error code for the current thread (the value returned by a call to GetLastError). The debuggers uses a pseudoregister called ERR for this purpose. You can view the contents of this pseudoregister in the Watch window or Quickwatch dialog using the standard procedures for displaying registers (discussed in Viewing the Value of a Variable or Contents of a Register).

To display the error code in meaningful form, use the hr format specifier with ERR:

ERR, hr


Modifying the Value of a Variable or Contents of a Register

Home Page (Debugger) | Overview | How Do I... Topics

When the program is paused at a breakpoint or between steps, you can change the value of any non-const variable or contents of any register (including Intel MMX registers).

What do you want to do?

Modify the value of a variable or contents of a register using QuickWatch

Modify the value of a variable or contents of a register using the Watch window

Modify the value of a variable in the Variables window

To modify the value of a variable or contents of a register using QuickWatch

  1. On the Debug menu, click QuickWatch.

  2. In the Expression text box, type the variable or register name.

  3. Click the Recalculate button.

  4. If the variable is an array, use the + box to expand the view until you see the value you want to modify.

  5. Use the TAB key to move to the value you want to modify.

  6. Type the new value, and then press ENTER.

  7. Click Close.

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

To modify the value of a variable or contents of a register using the Watch window

  1. In the Watch window, double-click the value.

    – or –

    Use the TAB key to move the insertion point to the value you want to modify.

  2. If the variable is an array, use the + box to expand the view until you see the value you want to modify.

  3. Type the new value, and press ENTER.

To modify the value of a variable in the Variables window

  1. In the Variables window, click the Auto tab, Locals tab, or This tab.

  2. Select the line containing the variable whose type you want to modify.

  3. If the variable is an array, use the + box to expand the view until you see the value you want to modify.

  4. Double-click the value, or use the TAB key to move the insertion point to the value you want to modify.

  5. Type the new value, and press ENTER. The new value appears in red.


Viewing Disassembly Code

Home Page (Debugger) | Overview | How Do I... Topics

By default, the Disassembly window displays disassembled code with source-code annotations and symbols. Use options on the Debug tab in the Options dialog box on the Tools menu to change the display.

To view specific source code in the Disassembly window

  1. Start debugging, and pause the debugger in break mode (program is waiting for user input after completing a debugging command).

  2. On the View menu, click Debug Windows, then click Disassembly.


Viewing the Call Stack for a Function

Home Page (Debugger) | Overview | How Do I... Topics

What do you want to do?

View the call stack for a function

Change the call stack display

To view the call stack for a function (or subroutine)

  1. Place the insertion point in the function (or subroutine).

  2. On the Debug menu, click Run To Cursor to execute your program to the location of the insertion point.

    The Locals tab of the Variables window is updated automatically to display the local variables for the function or procedure.

  3. On the View menu, click Debug Windows, then click Call Stack.

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

Tip To run the program to the return address, select the function (or subroutine) in the Call Stack window, and choose Run To Cursor from the Start Debug menu.

Tip To set or remove a breakpoint at a function (or subroutine) return address, select the function (or subroutine) in the Call Stack window, and click the Insert/Remove Breakpoint toolbar button.

To change the call stack display

  1. On the Tools menu, click Options.

  2. Click the Debug tab.

  3. Under Call stack window, select the check boxes for Parameter Values or Parameter Types, according to the information you want to display.

Tip The Context box at the top of the Variables window contains a drop-down list of call stack functions (or subroutines). If you select one of these functions (or subroutines), the debugger window views change accordingly.


Using COFF-Format Information or DLL Exports

The Visual C++ debugger uses CodeView-format debug information. If CodeView-format information is not available, Visual C++ can use two additional types of information:

  • COFF-format debugging information

  • DLL export tables

COFF is a format used by some other debuggers. You can find COFF-format information in the MSVBVM50.DBG file shipped provided with Visual Basic 5.01, for example.

Reading symbolic information from DLL export tables can be useful if you are working with Windows 95 system DLLs, Windows messages, Windows procedures (WindowProcs), COM objects, or marshalling.

Reading COFF and DLL export information entails some overhead, so this capability is turned off by default.

To use COFF-format information or DLL exports

  1. On the Tools menu, click Options.

  2. The Options dialog appears. Select the Debug tab.

  3. Select the Load COFF & Exports check box.

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

To see whether a DBG file contains CodeView- or COFF-format information, use dumpbin /headers. Look in the Debug Directories section of the output file for COFF (coff) or CodeView (cv) entries.

To see what symbols are available in the export table of a DLL, use dumpbin /exports. Symbols are available for any 32-bit system DLLs. By reading the dumpbin /exports output, you can see the exact function (or subroutine) name, including non-alphanumeric characters. This is useful for setting a breakpoint on a function (or subroutine). Function (or subroutine) names from DLL export tables may appear truncated elsewhere in the debugger.


Overview: DDESpy

You can use DDESpy (DDESPY.EXE) to monitor dynamic data exchange (DDE) activity in the operating system.

What do you want to know more about?

Using DDESpy


Selecting the Output

Overview

DDESpy can display DDE information in a window or on your debugging terminal, or it can save the displayed information in a file for later use.

You use the Output menu to select where DDESpy sends output. If you choose the File command, you can specify the name of an output file, or choose the No File button. After you have chosen the File command, DDESpy asks you for an output filename every time you restart it. This prompt can be turned off by reopening the File dialog box and choosing the No File button.

From the Output menu, you can also choose to send your output to either a debug terminal or to the DDESpy window. If you choose a window, you can clear the display window using the Clear Screen command. You can use the Mark command to add marker text to the display — for example, before a DDE event to make it easier to find the event in the output file.

Output Menu Command | Description
File | Specifies the name of an output file.
Debug Terminal | Sends your output to a debug terminal.
Screen | Sends your output to a DDESpy window.
Clear Screen | Clears the display window.
Mark | Marks the text.


Using the Monitor Menu

Overview

You use the Monitor menu to specify one or more types of DDE information that DDESpy can display.

Which types of displayed information would you like to know more about?

String-Handle Data

Sent DDE Messages

Posted DDE Messages

Callbacks

Errors

Filters

The DDE protocol passes information by using shared memory. The contents of the shared memory depend on the type of DDE transaction. Several structures have been defined to allow applications using DDE to access the information in shared memory. DDESpy displays the contents of the appropriate structure for the DDE activity being monitored.


String-Handle Data

Overview

The DDE protocol uses the MONHSZSTRUCT structure to pass string-handle data. DDESpy displays the following information from this structure:

  • Task (application instance)

  • Time, in milliseconds, since you started Windows

  • Activity type (create, destroy, or increment)

  • String handle

  • String contents

The following example shows a typical DDESpy display of string-handle data:

Task:0x94f, Time:519700, String Handle Created: c4a4(this is a test)
Task:0x94f, Time:526126, String Handle Created: c4aa(another test)


Sent DDE Messages

Overview

The DDE protocol uses the MONMSGSTRUCT structure to post DDE messages. DDESpy displays the following information from this structure:

  • Task

  • Time

  • Handle of receiving window

  • Transaction type (sent)

  • Message type

  • Handle of sending application

  • Other message-specific information

The following example shows a typical DDESpy display of DDE message activity:

Task:0x8df Time:642402 hwndTo=0x38dc Message(Sent)=Initiate:
        hwndFrom=9224, App=0xc35d("Server")
        Topic=*
Task:0x94f Time:642457 hwndTo=0x2408 Message(Sent)=Ack:
        hwndFrom=9396, App=0xc35d("Server")status=c35d(fAck
        fBusy )
        Topic=Item=0xc361("System")


Posted DDE Messages

Overview

The DDE protocol uses the MONMSGSTRUCT structure to post DDE messages. The information displayed for posted DDE messages is similar to the information displayed for sent DDE messages. DDESpy displays the following information from this structure:

  • Task

  • Time

  • Handle of receiving window

  • Transaction type (posted)

  • Message type

  • Handle of sending application

  • Other message-specific information


Callbacks

Overview

The DDE protocol uses the MONCBSTRUCT structure to pass information to application callback functions. DDESpy displays the following information from this structure:

  • Task

  • Time

  • Transaction type

  • Exchanged-data format (if any)

  • Conversation handle

  • String handles and their referenced strings

  • Transaction-specific data

The following example shows a typical DDESpy display of callback activity:

Task:0x8df Time:2882628 Callback:
        Type=Advstart, fmt=0x1("CF_TEXT"), hConv=0xc24b4,
        hsz1=0xc361("System") hsz2=0xc4df("xxcall"), hData=0x0,
        lData1=0x83f0000, lData2=0x0
        return=0x0


Errors

Overview

When an error occurs during a DDE transaction, the DDE protocol places the error value and associated information in a MONERRSTRUCT structure. DDESpy uses this structure to display the following information about the error:

  • Task (the handle of the application that caused the error)

  • Time

  • Error value and name


Filters

Overview

You can use the Message Filters and Callback Filters options to choose the types of DDE messages and callbacks to monitor.


Tracking Options

Overview

DDESpy can also display information about aspects of DDE communication in your Windows system:

  • String handles

  • Conversations

  • Links

  • Services

You can use the Track menu to specify which DDE activity DDESpy tracks. When you choose a command from the Track menu, DDESpy creates a separate window for the display of information in conjunction with the DDE functions. For each window created, DDESpy updates the displayed information as DDE activity occurs. Events that occurred prior to creation of the tracking window are not displayed in the tracking window.

DDESpy can sort the displayed information in the tracking window. If you select the heading for a particular column in the tracking window, DDESpy sorts the displayed information based on the column you select. This feature can be useful if you are searching for a particular event or handle.

Tracking String Handles

Windows maintains a system-wide string table containing the string, string handle, and string usage count that applications use in DDE transactions.

To display the system string table

  • From the Track menu, choose the String Handles command.

Tracking Conversations

The Conversations window shows the service name, current topic, and server and client handles for each active conversation.

To display all active DDE conversations in your Windows system

  • From the Track menu, choose the Conversations command.

Tracking Links

The Links window shows the server name, topic, item format, transaction type, client handle, and server handle for every active advise loop in your Windows system.

To display all active DDE advise loops

  • From the Track menu, choose the Links command.

Tracking Services

Server applications use the DdeNameService function to register with the DDE protocol. When the DDE protocol receives the DdeNameService function call, it adds the server name and an instance-specific name to a list of registered servers.

To display a list of registered servers

  • From the Track menu, choose the Services command.


Overview: PView

With the PView process viewer (PVIEW.EXE), you can examine and modify many characteristics of the processes and threads running on your system. PView can help you answer questions such as these:

  • How much memory does the program allocate at various points in its execution, and how much memory is being paged out?

  • Which processes and threads are using the most CPU time?

  • How does the program run at different system priorities?

  • What happens if a thread or process stops responding to Dynamic Data Exchange (DDE), or pipe input/output (I/O)?

  • What percentage of time is spent running application program interface (API) calls?

! Warning: With PView, you can modify the status of processes running on your system. As a result, by using PView, you can stop processes and potentially halt the entire system. Make sure you save edited files before running PView.

What do you want to know more about?

Opening PView


Opening PView

Overview

To start PView

  1. Click the Start button on the Windows taskbar and highlight Programs.

  2. On the resulting Programs submenu, highlight Visual Fortran 6.0.

  3. Next, click Process Viewer. PView opens by displaying the main Process Viewer Application dialog box.

The following buttons control PView actions.

Button | Description
Exit | Closes PView.
Memory Details | Opens the Memory Details dialog box.
Kill Process | Removes the highlighted process from the system. This is different from choosing Close from the System menu, because the process is not informed of the shutdown (with WM_DESTROY) before it is stopped.
Refresh | Updates information in the Process Viewer dialog box and the Memory Details dialog box.
Connect | Displays information about the computer specified in the Computer text box. The Computer text box should contain the network name of the computer you wish to view. Your ability to connect to a remote system may be affected by security on the target machine.

The Process Viewer Application dialog box displays information on active processes and threads. You can select, modify, and view the behavior of processes and threads using PView features.

What do you want to know more about?

Process selection

Process memory used

Priority (base process)

Thread priority

Thread selection

Thread information

Memory Details dialog box


Process Selection

Overview

The Process selection list box displays information on the accessible processes running on the system. From this list, you can select a process for viewing. All subsequent PView information and controls derive from the process selected in this list.

Note Because Windows NT is a secure operating system, you may not be able to view or alter attributes of some programs running on the system. See your Windows NT user’s guide for more information on security.

The Process selection list box contains the following fields.

Field | Description
Process | Name of the process on this line (usually an .EXE filename).
Processor Time | Amount of CPU time that this process has used.
Privileged | Percentage of CPU time that was spent executing privileged code (code in the Windows NT Executive).
User | Percentage of CPU time that was spent executing user code. This time includes time running protected subsystem code.


Process Memory Used

Overview

The Process Memory Used box displays information on the memory usage of the process selected in the Process selection list box.

Field | Description
Working Set | Average amount of physical memory used by the process. The longer a process has been running, the more accurate this value is.
Heap Usage | Current total heap being used by the process. Heap space is taken by dynamically allocated data, including memory reserved by malloc, new, LocalAlloc, HeapAlloc, VirtualAlloc, and GlobalAlloc.


Priority

Overview

With the Priority options box, you can change the base priority of the process highlighted in the Process selection list box. This priority determines the activity of all threads of the selected process.

Field | Description
Very High | Maximum priority. CPU time is split between this and other Very High priority processes. Lower priority processes execute only when all Very High priority processes are blocked.
Normal | Standard priority group, also known as foreground. Most applications run with normal priority.
Idle | Lowest priority group, also known as background. Processes with this priority execute only when the system has no higher-priority processes that need CPU time. Screen savers run at this priority.


Thread Priority

Overview

The Thread Priority box shows the base priority of the thread selected in the Thread selection list box. This is not an absolute priority, but is a range of priorities that can be assigned by the operating system to the selected thread.

Priority | Description
Highest | Highest priority level allowed by the process priority.
Above Normal | Slightly elevated priority.
Normal | Standard priority level for the given process priority.
Below Normal | Reduced priority.
Idle | No CPU time will be spent on this thread unless all other threads are blocked.


Thread Selection

Overview

The Thread selection list box displays statistics for threads of the process selected in the Process selection list box so you can select a thread for further operations.

Field | Description
Thread(s) | Thread ID number. This is the handle returned by CreateThread.
Processor Time | Amount of time that this instance of the thread has been running.
Privileged | Percentage of CPU time that was spent executing privileged code (code in the Windows NT Executive).
User | Percentage of CPU time that was spent executing user code. This time includes time running protected subsystem code.


Thread Information

Overview

The Thread Information box displays execution information about the thread selected in the Thread selection list box.

Field | Description
User PC Value | Value of the instruction pointer for this thread.
Start Address | Address of the entry point of this thread. This information is useful for debugging.
Context Switches | Number of times that this thread has received CPU attention.
Dynamic Priority | Current dynamic thread priority. This number is determined by many factors, including user activity.


Memory Details Dialog Box

Overview

The Memory Details dialog box gives information on the process selected in the Process selection list box.

To view the Memory Details dialog box

  • Choose Memory Details.

    – or –

    Double-click on a process in the Process selection list box.

To update the information in the Memory Details dialog box

  • Return to the Process Viewer dialog box and choose Refresh.

The Memory Details dialog box consists of the following buttons and groups.

Buttons and Groups | Description
OK | Returns to the Process Viewer dialog box.
Process | Displays name and process ID of the process selected in the Process selection box of the Process Viewer dialog box.
User Address Space for | Select a specific .EXE or .DLL file or select Total Image Commit to display the following statistics for all components of the selected process:
 | Total | Sum of all user address space.
 | Inaccessible | Address space that cannot be accessed. This includes memory reserved by VirtualAlloc.
 | Read Only | Read-only data and code.
 | Writeable | Total data address space that can be written to.
 | Writeable (Not Written) | Data address space that can be written to, but has not been.
 | Executable | Code in selected .EXEs and .DLLs.
Mapped Commit | Displays the following statistics for Mapped Commit memory:
 | Total | Sum of all mapped address space.
 | Inaccessible | Address space that cannot be accessed. This includes memory reserved by VirtualAlloc.
 | Read Only | Read-only data and code.
 | Writeable | Total data address space that can be written to.
 | Writeable (Not Written) | Data address space that can be written to, but has not been.
 | Executable | Code in selected .EXEs and .DLLs.
Private Commit | Displays the following statistics for Private Commit memory:
 | Total | Sum of all private address space.
 | Inaccessible | Address space that cannot be accessed. This includes memory reserved by VirtualAlloc.
 | Read Only | Read-only data and code.
 | Writeable | Total data address space that can be written to.
 | Writeable (Not Written) | Data address space that can be written to, but has not been.
 | Executable | Code in selected .EXEs and .DLLs.
Virtual Memory Counts | Displays the following statistics on Virtual Memory usage:
 | Working Set | Average amount of virtual memory used by the process. The longer a process has been running, the more accurate this value is.
 | Peak Working Set | Maximum value attained by the Working Set described above.
 | Private Pages | Number of pages marked as private.
 | Virtual Size | Current size of virtual memory for this process.
 | Peak Virtual Size | Maximum size of virtual memory for this process.
 | Fault Count | Number of page faults. Each page fault represents an attempt to access memory at an address that was not in physical memory.


Home Page: Spy++

Spy++ (SPYXX.EXE) is a Win32-based utility that gives you a graphical view of the system’s processes, threads, windows, and window messages.

  • Overview

  • How Do I ... Topics

Related Home Pages

  • Debugging Home Page

  • Source Code Control Home Page


Overview: Spy++

Home Page (Spy++)

Spy++ (SPYXX.EXE) is a Win32-based utility that gives you a graphical view of the system’s processes, threads, windows, and window messages.

Spy++ has a toolbar and hyperlinks to help you work faster. It also provides a Refresh command to update the active view, a Window Finder Tool to make spying easier, and a Font dialog box to customize view windows. Additionally, Spy++ saves and restores user preferences.

There are two utilities similar to Spy++: PVIEW.EXE, which shows details on processes and threads, and DDESPY.EXE, a monitoring program for Dynamic Data Exchange (DDE) messages.

What do you want to know more about?

The Spy++ toolbar

What do you want to do?

Start Spy++

Use the Windows view

Use the Processes view

Use the Threads view

Use the Messages view


The Spy++ Toolbar

Home Page (Spy++) | How Do I ... Topics

The Spy++ toolbar appears beneath the menu bar. It provides shortcut commands for opening new views, starting or stopping the message stream display, changing message stream options, clearing message stream windows, and finding windows. You can display or hide the toolbar with the Toolbar command on the View menu.

Button | Effect
 | Creates a window to display a tree view of all windows and controls in the system. See Using the Windows View.
 | Creates a window to display a tree view of all processes in the system. See Using the Processes View.
 | Creates a window to display a tree view of all threads in the system. See Using the Threads View.
 | Creates a window to display window messages. This button calls up the Message Options dialog box to let you select the window whose messages will be displayed, in addition to other options. See Using the Messages View.
 | Starts the message logging and displays the message stream. This button is available only when a Messages window is active (has the focus). See Starting and Stopping the Message Log Display.
 | Stops the message logging and display of the message stream. This button is available only when a Messages window is active (has the focus). See Starting and Stopping the Message Log Display.
 | Displays the Message Options dialog box. Use this dialog box to select windows and message types for viewing. This button is available only when a Messages window is active (has the focus). See Choosing Message Options.
 | Clears the contents of the active Messages window. This button is available only when a Messages window is active (has the focus).
 | Opens the Find Window dialog box, which lets you select a window to view messages or find properties. See Using the Window Finder Tool.
 | Searches the current view for a matching window, process, thread, or message.
 | Searches the current view for the next matching window, process, thread, or message. This button (and the related menu item) is available only when there is a valid search result that is not unique. For example, when you use a window handle as the search criteria in the window tree, it will produce unique results, since there is only one window with that handle in the window tree. In this instance, Find Next is not available.
 | Searches the current view for the previous matching window, process, thread, or message. This button (and the related menu item) is available only when there is a valid search result that is not unique. For example, when you use a window handle as the search criteria in the window tree, it will produce unique results, since there is only one window with that handle in the window tree. In this instance, Find Previous is not available.


How Do I ... Topics: Spy++

Home Page (Spy++) | Overview

What do you want to do?

Get started with Spy++

Use the Windows view

Use the Processes view

Use the Threads view

Use the Messages view

Tip While using Spy++, in many instances you can click the right mouse button to display a pop-up menu of frequently used commands. The commands available depend on where the pointer is. For example, if you click while pointing at an entry in the Window view, and the selected window is visible, the pop-up Highlight menu item will cause the border of the selected window to flash so that the window can be easily located on the screen.


Getting Started with Spy++

Home Page (Spy++) | Overview | How Do I ... Topics

What do you want to do?

Start Spy++

Refresh the view

Change fonts

Expand and collapse Spy++ trees


Starting Spy++

Home Page (Spy++) | Overview | How Do I ... Topics

To start Spy++

  • From the Tools menu, choose Spy++.

Note You can run only one copy of Spy++. Attempting to run additional copies of Spy++ will bring the currently running Spy++ to the front.

Spy++ is a read-only program. Using Spy++ does not change program operation, but can slow program execution.

When Spy++ starts, it opens a window titled “Windows 1,” which shows a tree view of all windows and controls in the system. There are also three other views available in Spy++: Messages, Processes, and Threads.


Refreshing the View

Home Page (Spy++) | Overview | How Do I ... Topics

Spy++ takes a “snapshot” of the system tables and refreshes a view based on this information. It is important that you periodically refresh your system views. If you have a Spy++ view open and have not refreshed the view, you will not see those processes, threads, and windows that are subsequently created. Also, you may see items that no longer exist. The Refresh command is available for all views except the Messages view.

To refresh the currently active view

  • From the Window menu, choose Refresh.


Changing Fonts

Home Page (Spy++) | Overview | How Do I ... Topics

You can change the font, font style, and font size for Spy++ windows.

To change font options

  1. From the View menu, choose Font.

  2. Choose a font, font style, and font size.

  3. Click OK.

Selecting Save Font As Default will cause all future Spy++ windows to use this font.


Expanding and Collapsing Spy++ Trees

Home Page (Spy++) | Overview | How Do I ... Topics

You can expand and collapse the Windows, Processes, and Threads views using two methods: by clicking the icons in the window or by using the Tree menu. The + and – icons in the tree act as they do in the Visual C++ Project Workspace window.

The Tree menu contains four commands.

Menu command | Description
Expand One Level | Expands the currently selected item to the next level.
Expand Branch | Fully expands the currently selected item.
Expand All | Fully expands all items in the window.
Collapse | Fully collapses the currently selected item.

Tip If you expand a process, you see all the threads the process owns. If you expand a thread, you see a list of all the windows it owns.

To expand or collapse Spy++ trees

  1. Select one of the items in a Windows, Processes, or Threads view.

  2. From the Tree menu, choose one of the expand or collapse commands.


Using the Windows View

Home Page (Spy++) | Overview | How Do I ... Topics

The Windows view displays a tree of all windows and controls in the system. The Windows view shows only windows.

What do you want to do?

Open the Windows view

Use the Window Finder tool

Search for a window

Open windows properties

Display windows properties


Opening the Windows View

Home Page (Spy++) | Overview | How Do I ... Topics

To open the Windows view

  • From the Spy menu, choose Windows.

The figure below shows the Spy++ representation of the Windows view with the first level expanded.

The Spy++ Windows View

The current desktop window is at the top of the tree. All other windows are children of the desktop, and are listed according to the standard window hierarchy, with sibling windows ordered by Z-order. You can collapse or expand the whole tree by clicking the + or – symbol for the top-level window.

The Windows view is most useful if you need to find a particular window. If you start with a tree expanded at the second level (all windows that are children of the desktop), then you can identify the desktop-level window that you want by its class name and title. Once you have found the desktop-level window, you can expand the level to find a specific child window.

See Also The Processes View, The Threads View, The Messages View


Using the Window Finder Tool

Home Page (Spy++) | Overview | How Do I ... Topics

With the Window Finder Tool you can find the properties of a selected window. The Finder Tool can find disabled child windows and discern which window to highlight if disabled child windows overlap.

To find a window to spy on

  1. Arrange your windows so that Spy++ and the subject window are visible.

  2. From the Spy menu, choose Find Window to open the Find Window dialog box.

  3. Drag the Finder Tool to the window that you want. As you drag the tool, window details appear in the dialog box.

    – or –

    If you know the handle of the window you want (for example, from the debugger), type it in the Handle box.

  4. Under Show, choose Properties or Messages to select what kind of information to display.

  5. Click OK.

Tip To reduce screen clutter, select the Hide Spy option in the Find Window dialog box. This removes the main Spy++ window and leaves the Find Window dialog box visible on top of your other applications. The Spy++ main window will be restored when you choose the OK or Cancel button, or when you clear the Hide Spy option.

In the figure below, the Finder Tool was dragged over the “Exploring” window.

Showing Properties with the Find Window


Searching for a Window

Home Page (Spy++) | Overview | How Do I ... Topics

You can search for a specific window by using its handle, caption, class, or a combination of its caption and class as search criteria. You can also specify the initial direction of the search. The fields in the dialog box will show the attributes of the selected window in the window tree.

To search for a window

  1. Arrange your windows so that Spy++, an active Windows view, and the subject window are visible.

  2. From the Search menu, choose Find Window.

  3. Drag the Finder Tool to the subject window that you want. As you drag the tool, window details appear in the dialog box.

    – or –

    If you know the handle of the window you want (for example, from the debugger), type it in the Handle box.

    – or –

    If you know the caption and/or class of the window you want, type them in the Caption and Class box and delete the Handle box.

  4. Choose Up or Down for the initial direction of the search.

  5. Click OK.

If a matching window is found, it is highlighted in the Windows view.

Tip To reduce screen clutter, select the Hide Spy option in the Find Window dialog box. This removes the main Spy++ window and leaves the Find Window dialog box visible on top of your other applications. The Spy++ main window will be restored when you choose the OK or Cancel button, or when you clear the Hide Spy option.


Opening Window Properties

Home Page (Spy++) | Overview | How Do I ... Topics

You can find out more about entries in the Windows view with the Window Properties dialog box.

To open the Window Properties dialog box

  • Click the item, then choose Properties from the View menu.

Properties dialog boxes are not modal, so you can click another item in a view window and the dialog box will show information on the selected item.

See Also Displaying Window Properties


Displaying Window Properties

Home Page (Spy++) | Overview | How Do I ... Topics

The Window Properties dialog box contains five tabs: General, Styles, Windows, Class, and Process. Click the title of the tab to display that tab’s options.

Window Properties General Tab

Entry | Description
Window Caption | The text in the window caption, or text contained in a window if it is a control.
Window Handle | The unique ID of this window. Window handle numbers are reused; they identify a window only for the lifetime of that window.
Window Proc | The virtual address of the window procedure function for this window. This field also indicates whether this window is a Unicode window, and whether it is subclassed.
Rectangle | The bounding rectangle for the window. The size of the rectangle is also displayed. Units are pixels in screen coordinates.
Restored Rect | The bounding rectangle for the restored window. The size of the rectangle is also displayed. Restored Rect will differ from Rectangle only when the window is maximized or minimized. Units are pixels in screen coordinates.
Client Rect | The bounding rectangle for the window client area. The size of the rectangle is also displayed. Units are pixels relative to the top left of the window client area.
Instance Handle | The instance handle of the application. Instance handles are not unique.
Control ID or Menu Handle | If the window being displayed is a child window, the Control ID label is displayed. Control ID is an integer that identifies this child window’s control ID. If the window being displayed is not a child window, the Menu Handle label is displayed. Menu Handle is an integer that identifies the handle of the menu associated with this window.
User Data | Application-specific data that is attached to this window structure.
Window Bytes | The number of extra bytes associated with this window. The meaning of these bytes is determined by the application. Expand the list box to see the byte values in DWORD format.

Window Properties Styles Tab

Entry | Description
Window Styles | A combination of window style codes and control styles if applicable.
Extended Styles | A combination of extended window style codes.

Window Properties Windows Tab

Entry | Description
Next Window | The handle of the next sibling window in the same sequence (Z-order) shown in the window tree view (“none” if there is no next window). Click this option to view the properties of the next window.
Previous Window | The handle of the previous sibling window in the same sequence (Z-order) shown in the window tree view (“none” if there is no previous window). Click this option to view the properties of the previous window.
Parent Window | The handle of this window’s parent window (“none” if there is no parent). Click this option to view the properties of the parent window.
First Child | The handle of this window’s first child window, in the sequence (Z-order) shown in the window tree view (“none” if there are no child windows). Click this value to view the properties of the first child window.
Owner Window | The handle of this window’s owner window. An application’s main window typically owns system-modal dialog windows, for example (“none” if there is no owner). Click this option to view the properties of the owner window.

Window Properties Class Tab

Entry | Description
Class Name | The name (or ordinal number) of this window class.
Class Styles | A combination of class style codes.
Class Bytes | Application-specific data associated with this window class.
Class Atom | The atom for the class returned by the RegisterClass call.
Instance Handle | The instance handle of the module that registered the class. Instance handles are not unique.
Window Bytes | The number of extra bytes associated with each window of this class. The meaning of these bytes is determined by the application. Expand the list box to see the byte values in DWORD format.
Window Proc | The current address of the WndProc function for windows of this class. This differs from Window Proc on the General tab if the window is subclassed.
Menu Name | The name of the main menu that is associated with windows of this class (“none” if there is no menu).
Icon Handle | The handle for the icon that is associated with windows of this class (“none” if there is no icon).
Cursor Handle | The handle for the cursor that is associated with windows of this class (“none” if there is no cursor).
Bkgnd Brush | The handle for the background brush that is associated with windows of this class, or one of the predefined COLOR_* colors for painting the window background (“none” if there is no brush).

Window Properties Process Tab

Entry | Description
Process ID | The ID of the process that owns the thread that created this window. Click this value to view the properties of this process.
Thread ID | The ID of the thread that created this window. Click this value to view the properties of this thread.

See Also Opening Window Properties


Using the Processes View

Home Page (Spy++) | Overview | How Do I ... Topics

Microsoft Windows supports multiple processes. Each process can have one or more threads, and each thread can have one or more associated top-level windows. Each top-level window can own a series of windows. A + symbol indicates that a level is already collapsed. Click the + symbol to expand the level. The collapsed view consists of one line per process.

Use the Processes view if you want to examine a particular system process, which usually corresponds to an executing program. Processes are identified by module names, or they are designated “system processes.” To find a process, collapse the tree and search the list.

What do you want to do?

Open the Processes view

Search for a process

Open process properties

Display process properties


Opening the Processes View

Home Page (Spy++) | Overview | How Do I ... Topics

To open the Processes view

  • From the Spy menu, choose Processes.

    The Processes View window appears as shown in the figure below.

The Processes View Window

See Also Using the Windows View, Using the Threads View, Using the Messages View


Searching for a Process

Home Page (Spy++) | Overview | How Do I ... Topics

You can search for a specific process by using its process ID or module string as search criteria. You can also specify the initial direction of the search. The fields in the dialog box will show the attributes of the selected process in the process tree.

To search for a process

  1. Arrange your windows so that Spy++ and an active Processes view are visible.

  2. From the Search menu, choose Find Process to open the Process Search dialog box .

  3. Type the process ID or a module string as search criteria.

  4. Choose Up or Down for the initial direction of the search.

  5. Click OK.

If a matching process is found, it is highlighted in the Processes view.

Tip To find all the processes owned by a module, clear the Process box and type the module name in the Module box. Then use Find Next to continue searching for processes.


Opening Process Properties

Home Page (Spy++) | Overview | How Do I ... Topics

You can find out more about entries in the Processes view with the Process Properties dialog box.

To open the Process Properties dialog box

  • Click the item, then choose Properties from the View menu.

Properties dialog boxes are not modal, so you can click another item in a view window and the dialog box will show information on the selected item.

See Also Process Properties for Windows 95, Process Properties for Windows NT


Displaying Process Properties

Home Page (Spy++) | Overview | How Do I ... Topics

What do you want to do?

View process properties for Windows 95

View process properties for Windows NT

Open Process properties

Process Properties for Windows 95

For Windows 95, the Process Properties dialog box contains one tab: General.

Process Properties General Tab for Windows 95

Entry | Description
Module Name | The name of the module.
Process ID | The unique ID of this process. Process ID numbers are reused, so they identify a process only for the lifetime of that process. The Process object type is created when a program is run. All the threads in a process share the same address space and have access to the same data.
Priority Base | The current base priority of this process. Threads within a process can raise and lower their own base priority relative to the process’s base priority.
Threads | The number of threads currently active in this process.

Process Properties for Windows NT

For Windows NT, the Process Properties dialog box contains four tabs: General, Memory, Page File, and Space. Click the title of a tab to display that tab’s options.

Process Properties General Tab for Windows NT

Entry | Description
Module Name | The name of the module.
Process ID | The unique ID of this process. Process ID numbers are reused, so they identify a process only for the lifetime of that process. The Process object type is created when a program is run. All the threads in a process share the same address space and have access to the same data.
Priority Base | The current base priority of this process. Threads within a process can raise and lower their own base priority relative to the process’s base priority.
Threads | The number of threads currently active in this process.
CPU Time | Total CPU time spent on this process and its threads. Equal to User Time plus Privileged Time.
User Time | The cumulative elapsed time that this process’s threads have spent executing code in User Mode in non-idle threads. Applications execute in User Mode, as do subsystems such as the window manager and the graphics engine.
Privileged Time | The total elapsed time this process has been running in Privileged Mode in non-idle threads. The service layer, the Executive routines, and the Kernel execute in Privileged Mode. Device drivers for most devices other than graphics adapters and printers also execute in Privileged Mode. Some work that Windows does for your application may appear in other subsystem processes in addition to Privileged Time.
Elapsed Time | The total elapsed time this process has been running.

Process Properties Memory Tab for Windows NT

Entry | Description
Virtual Bytes | The current size (in bytes) of the virtual address space the process is using. The use of virtual address space does not necessarily imply corresponding use of either disk or main memory pages. However, virtual space is finite, and using too much may limit the ability of the process to load libraries.
Peak Virtual Bytes | The maximum number of bytes of virtual address space the process has used at any one time.
Working Set | The set of memory pages touched recently by the threads in the process. If free memory in the computer is above a threshold, pages are left in the Working Set of a process even if they are not in use. When free memory falls below a threshold, pages are trimmed from the Working Set. If they are needed, they will be soft-faulted back into the Working Set before they leave main memory.
Peak Working Set | The maximum number of pages in the working set of this process at any point in time.
Paged Pool Bytes | The current amount of paged pool the process has allocated. Paged pool is a system memory area where operating system components acquire space as they accomplish their appointed tasks. Paged pool pages can be paged out to the paging file when not accessed by the system for sustained periods of time.
Nonpaged Pool Bytes | The current number of bytes in the nonpaged pool allocated by the process. The nonpaged pool is a system memory area where space is acquired by operating system components as they accomplish their appointed tasks. Nonpaged pool pages cannot be paged out to the paging file; they remain in main memory as long as they are allocated.
Private Bytes | The current number of bytes this process has allocated that cannot be shared with other processes.
Free Bytes | The total unused virtual address space of this process.
Reserved Bytes | The total amount of virtual memory reserved for future use by this process.
Free Image Bytes | The amount of virtual address space that is not in use or reserved by images within this process.
Reserved Image Bytes | The sum of all virtual memory reserved by images run within this process.

Process Properties Page File Tab for Windows NT

Entry | Description
Page File Bytes | The current number of pages that this process is using in the paging file. The paging file stores pages of data used by the process but not contained in other files. The paging file is used by all processes, and lack of space in the paging file can cause errors while other processes are running.
Peak Page File Bytes | The maximum number of pages that this process has used in the paging file.
Page Faults | The number of page faults by the threads executing in this process. A page fault occurs when a thread refers to a virtual memory page that is not in its working set in main memory. Thus, the page will not be retrieved from disk if it is on the standby list and hence already in main memory, or if it is being used by another process with which the page is shared.

Process Properties Space tab for Windows NT

Entry | Description
Show For Space Marked As | Use this list box to select the category of space (image, mapped, reserved, or unassigned).
Executable Bytes | For the selected category, the sum of all the address space that this process is using. Executable memory is memory that can be executed by programs, but may not be read or written.
Exec-Read-Only Bytes | For the selected category, the sum of all the address space in use with read-only properties that this process is using. Exec-read-only memory is memory that can be executed as well as read.
Exec-Read-Write Bytes | For the selected category, the sum of all the address space in use with read-write properties that this process is using. Exec-read-write memory is memory that can be executed by programs as well as read and modified.
Exec-Write-Copy Bytes | For the selected category, the sum of all the address space that can be executed by programs as well as read and written. This type of protection is used when memory needs to be shared between processes. If the sharing processes only read the memory, then they will all use the same memory. If a sharing process desires write access, then a copy of this memory will be made for the process.
No-Access Bytes | For the selected category, the sum of all the address space that prevents a process from using it. An access violation is generated if writing or reading is attempted.
Read-Only Bytes | For the selected category, the sum of all the address space that can be executed as well as read.
Read-Write Bytes | For the selected category, the sum of all the address space that allows reading and writing.
Write-Copy Bytes | For the selected category, the sum of all the address space that allows memory sharing for reading but not for writing. When processes are reading this memory, they can share the same memory. However, when a sharing process wants to have read/write access to this shared memory, a copy of that memory is made for writing.


Using the Threads View

Home Page (Spy++) | Overview | How Do I ... Topics

The Threads view is a flat listing of all threads with associated windows. Processes are not included. You can easily find the process that owns a selected thread. Use the Threads view to search for a particular thread.

What do you want to do?

Open the Threads view

Search for a thread

Open thread properties

Display thread properties


Opening the Threads View

Home Page (Spy++) | Overview | How Do I ... Topics

To open the Threads view

  • From the Spy menu, choose Threads.

See Also Using the Windows View, Using the Processes View, Using the Messages View


Searching for a Thread

Home Page (Spy++) | Overview | How Do I ... Topics

You can search for a specific thread by using its thread ID or module string as search criteria. You can also specify the initial direction of the search. The fields in the dialog box will show the attributes of the selected thread in the thread tree.

To search for a thread

  1. Arrange your windows so that Spy++ and an active Threads view are visible.

  2. From the Search menu, choose Find Thread.

  3. Type the thread ID or a module string as search criteria.

  4. Choose Up or Down for the initial direction of the search.

  5. Click OK.

If a matching thread is found, it is highlighted in the Threads view window.

Tip To find all the threads owned by a module, clear the Thread box and type the module name in the Module box. Then use Find Next to continue searching for processes.


Opening Thread Properties

Home Page (Spy++) | Overview | How Do I ... Topics

You can find out more about entries in the Threads view with the Thread Properties dialog box.

To open the Thread Properties dialog box

  • Click the item, then choose Properties from the View menu.

Properties dialog boxes are not modal, so you can click another item in a view window and the dialog box will show information on the selected item.

See Also Thread Properties for Windows 95, Thread Properties for Windows NT


Displaying Thread Properties

What do you want to do?

View thread properties for Windows 95

View thread properties for Windows NT

Open thread properties

Thread Properties for Windows 95

For Windows 95, the Thread Properties dialog box contains one tab: General.

Thread Properties General Tab for Windows 95

Entry | Description
Module Name | The name of the module.
Thread ID | The unique ID of this thread. Note that Thread ID numbers are reused; they identify a thread only for the lifetime of that thread.
Process ID | The unique ID of this process. Process ID numbers are reused, so they identify a process only for the lifetime of that process. The Process object type is created when a program is run. All the threads in a process share the same address space and have access to the same data. Click this value to view the properties of the process ID.
Current Priority | The current dynamic priority of this thread. Threads within a process can raise and lower their own base priority relative to the base priority of the process.
Base Priority | The current base priority of this thread.

Thread Properties for Windows NT

For Windows NT, the Thread Properties dialog box contains one tab: General.

Thread Properties General Tab for Windows NT

Entry | Description
Module Name | The name of the module.
Thread ID | The unique ID of this thread. Note that thread ID numbers are reused; they identify a thread only for the lifetime of that thread.
Process ID | The unique ID of this process. Process ID numbers are reused, so they identify a process only for the lifetime of that process. The Process object type is created when a program is run. All the threads in a process share the same address space and have access to the same data. Click this value to view the properties of the process ID.
Thread State | The current state of the thread. A Running thread is using a processor; a Standby thread is about to use one. A Ready thread is waiting to use a processor because one is not free. A thread in Transition is waiting for a resource to execute, such as waiting for its execution stack to be paged in from disk. A Waiting thread does not need the processor because it is waiting for a peripheral operation to complete or a resource to become free.
Wait Reason | This is applicable only when the thread is in the Wait state. Event Pairs are used to communicate with protected subsystems.
CPU Time | Total CPU time spent on this process and its threads. Equal to User Time plus Privileged Time.
User Time | The total elapsed time that this thread has spent executing code in User Mode. Applications execute in User Mode, as do subsystems such as the window manager and the graphics engine.
Privileged Time | The total elapsed time that this thread has spent executing code in Privileged Mode. When a Windows system service is called, the service will often run in Privileged Mode to gain access to system-private data. Such data is protected from access by threads executing in User Mode. Calls to the system may be explicit, or they may be implicit, such as when a page fault or an interrupt occurs.
Elapsed Time | The total elapsed time (in seconds) this thread has been running.
Current Priority | The current dynamic priority of this thread. Threads within a process can raise and lower their own base priority relative to the base priority of the process.
Base Priority | The current base priority of this thread.
Start Address | Starting virtual address for this thread.
User PC | The user program counter for the thread.
Context Switches | The number of switches from one thread to another. Thread switches can occur either inside a single process or across processes. A thread switch may be caused by one thread asking another for information, or by a thread being preempted when a higher priority thread becomes ready to run.


Using the Messages View

Home Page (Spy++) | Overview | How Do I ... Topics

Each window has an associated message stream. You can view this message stream in the Messages view. You can create a Messages view for a thread or process as well. This allows you to view messages sent to all windows owned by a specific process or thread, which is particularly useful for capturing window initialization messages.

What do you want to do?

Open the Messages view

View message code descriptions

Control the Messages view

Start and stop the message log

Choose message options

Search for a message

Open message properties

Display Message Properties


Opening the Messages View

Home Page (Spy++) | Overview | How Do I ... Topics

To open the Messages view for a window, process, or thread

  1. Move the focus to either a Windows, Processes, or Threads view window.

  2. Find the name of the window, process, or thread that you want to examine, and select it.

  3. From the Spy menu, choose Messages.

  4. Select the message options you want.

  5. Click OK to begin logging messages.

  6. From the Messages menu, choose Stop Logging.

The Messages view appears as shown below. Note that the first column contains the window handle, and the second column contains a message code (explained in Message Codes). Decoded message parameters and return values are on the right.

The Messages View Window

For a more direct way to select a window for message stream viewing, use the following procedure.

To open the Messages view for a visible window using the Message Options dialog box

  1. Arrange your windows so that both Spy++ and the subject window are visible.

  2. From the Spy menu, choose Messages.

  3. From the Windows tab, drag the Finder Tool to the window you want.

    As you drag the tool, Window details appear in the dialog box.

  4. Click OK to begin logging messages.

  5. From the Messages menu, choose Stop Logging.

Tip To reduce screen clutter, select the Hide Spy option in the Find Window dialog box. This removes the main Spy++ window and leaves the Find Window dialog box visible on top of your other applications. The Spy++ main window will be restored when you choose the OK or Cancel button, or by clearing the Hide Spy option.

See Also Using the Windows View, Using the Processes View, Using the Threads View


Message Codes

Home Page (Spy++) | Overview | How Do I ... Topics

Each message line in the Messages view contains a ‘P,’ ‘S,’ ‘s,’ or ‘R’ code. These codes have the following meanings:

Code | Meaning
P | The message was posted to the queue with the PostMessage function. No information is available concerning the ultimate disposition of the message.
S | The message was sent with the SendMessage function. This means that the sender doesn’t regain control until the receiver processes and returns the message. The receiver can, therefore, pass a return value back to the sender.
s | The message was sent, but security prevents access to the return value.
R | Each ‘S’ line has a corresponding ‘R’ (return) line that lists the message return value. Sometimes message calls are nested, which means that one message handler sends another message.


Controlling the Messages View

Home Page (Spy++) | Overview | How Do I ... Topics

With Spy++, you have considerable control over the content of the Messages view. You can start and stop displaying the messages at any time, and you can specify:

  • Which message types you want to see.

  • Which windows you want to monitor.

  • The display format for message lines.

These settings are available from the Message Options dialog box and apply only to the selected Messages view.


Starting and Stopping the Message Log Display

Home Page (Spy++) | Overview | How Do I ... Topics

When a Messages view window is active, a Start or Stop Logging choice appears on the Spy++ Messages menu, and the Start or Stop Logging toolbar button becomes active.

To stop the message log display

  • From the Messages menu, choose Stop Logging.

To start the message log display

  • From the Messages menu, choose Start Logging.

See Also Using the Messages View


Choosing Message Options

Home Page (Spy++) | Overview | How Do I ... Topics

The Options command on the Messages menu opens the Message Options dialog box with three tabs: Windows, Messages, and Output. Click the title of a tab to display that tab’s options.

The Windows Tab

The Windows tab on the Message Options dialog box contains the Window Finder Tool. Other options on the Windows tab include:

Entry | Description
Parent | Display messages for the selected window and its immediate parent window.
Children | Display messages for the selected window and all its child windows, including nested child windows.
Windows of Same Thread | Display messages for the selected window and all other windows owned by the same thread.
Windows of Same Process | Display messages for the selected window and all other windows owned by the same process.
All Windows In System | Display messages for all windows.
Save Settings as Default | Save the preceding settings for new message stream windows. These settings are saved when Spy++ quits.

The Messages Tab

You can use the Messages tab in the Message Options dialog box to select message types for viewing. Typically, you first select message groups, and then fine-tune the selection by selecting individual messages. The All button selects all message types, and the None button clears all types.

Note that three entries under Message Groups do not map to specific entries under Messages to View. These include:

  • WM_USER: with a code greater than or equal to than WM_USER

  • Registered: registered with the RegisterWindowMessage call

  • Unknown: unknown messages in the range 0 to (WM_USER – 1)

If you select these “groups,” the selection is applied directly to the message stream.

When you create a new Messages window, it can display all messages. When you filter messages from the Messages tab, that filter only applies to new messages, not messages that have already been displayed in the Windows view.

A grayed check box within Message Groups indicates that the Messages to View list box has been modified for messages in that group; not all of the message types in that group are selected.

If you select Save Settings as Default, the current settings are saved for later use as message search options. These settings are also saved when exiting Spy++.

The Output Tab

You can use the Output tab in the Message Options dialog box to select the following options:

Entry | Description
Message Nesting Level | Prefix nested messages with one period per level.
Raw Message Parameters | Display the hexadecimal wParam and lParam values.
Decoded Message Parameters | Display the results of message-specific decoding of the wParam and lParam values.
Raw Return Values | Display the hexadecimal lResult return value.
Decoded Return Values | Display the results of message-specific decoding of the lResult return value.
Message Origin Time | The elapsed time since the Windows system was started (for posted messages only).
Message Mouse Position | The screen coordinates of the mouse when the message was posted (for posted messages only).
Lines Maximum | Limit the number of lines that are retained in the currently selected Messages view.
Also Log to File | Specify an output file for the message log. This output file is written simultaneously with the message log window.
Save Settings as Default | Save the preceding settings for new message stream windows. These settings are saved when you quit Spy++.


Searching for a Message

Home Page (Spy++) | Overview | How Do I ... Topics

You can search for a specific message by using its handle, type, or message ID as search criteria. Any one of these criteria ? or a combination ? is valid search criteria. The initial direction of the search can also be specified. The fields in the Message Search dialog box (shown below) will be preloaded with the attributes of the selected message in the message log.

Message Search Dialog Box

To search for a message

  1. Arrange your windows so that Spy++ and an active Messages view are visible.

  2. From the Search menu, choose Find Message to open the Message Search dialog box.

  3. Drag the Finder Tool to the window that you want.

    – or –

    If you know the window handle of the message you want, type it in the Handle box.

    – or –

    If you know the message type and/or message ID you want, make a selection using the Type and Message boxes and delete the entry in the Handle box.

    You can clear any fields for which you do not want to specify values.

  4. Type the message type, or message ID to search for.

  5. Choose Up or Down for the initial direction of the search.

  6. Click OK.

If a matching message is found, it is highlighted in the Messages view window.

Tip To reduce screen clutter, select the Hide Spy option in the Find Window dialog box. This removes the main Spy++ window and leaves the Find Window dialog box visible on top of your other applications. The Spy++ main window will be restored when you click OK or Cancel, or by clearing the Hide Spy option.


Opening Message Properties

Home Page (Spy++) | Overview | How Do I ... Topics

You can find out more about entries in the Messages view with the Message Properties dialog box.

To open the Message Properties dialog box

  • Click the item, then choose Properties from the View menu.

See Also Displaying Message Properties


Displaying Message Properties

Home Page (Spy++) | Overview | How Do I ... Topics

The Message Properties dialog box contains one tab: General.

Message Properties General Tab

Entry | Description
Window Handle | The unique ID of this window. Window handle numbers are reused; they identify a window only for the lifetime of that window. Click this value to view the properties of this window.
Nesting Level | Depth of nesting of this message, where 0 is no nesting.
Message | Number, status, and name of the selected windows message.
lResult | The value of the lResult parameter, if any.
wParam | The value of the wParam parameter, if any.
lParam | The value of the lParam parameter, if any. This value is decoded if it is a pointer to a string or structure.

See Also Opening Message Properties


Overview: WinDiff

The WinDiff utility (WINDIFF.EXE) graphically compares the contents of two files or two directories. With WinDiff, you can compare and modify the contents of files and directories using a graphical Windows interface.

What do you want to know more about?

The WinDiff command line

WinDiff colors

WinDiff menus

What do you want to do?

Start WinDiff

Use the Expand/Outline Button


WinDiff Command Line

Overview | How Do I ... Topics

The full WinDiff command-line syntax is:

WINDIFF path1 [path2] [-D] [-O] [-N name] [-S [options] savefile]

Parameters

path1

Compares files in path1 with files in current directory.

path1 path2

Compares files in path1 with files in path2.

-D

Compares one directory only.

-O

Outline view (no automatic expansion).

-N name

Send notification at end of comparison, with NET SEND name.

-S options

Save a list of all files, using the following options:

  • -s: Compares files that are the same in both paths.

  • -l: Compares only files in the first (left) path.

  • -r: Compares only files in the second (right) path.

  • -d: Compares two different files in both paths.

savefile

Name of text file to which comparison results are written.


WinDiff Colors

Overview | How Do I ... Topics

File contents are displayed in three background colors.

Background Color | Description
Red | Indicates different text from the first (left) file.
Yellow | Indicates different text from the second (right) file.
White | Indicates identical text from both files.


WinDiff Menus

Overview | How Do I ... Topics

File Menu

You can use the File menu to define selection, naming, and printing options.

Menu Command | Description
Compare Files | Displays the File Open dialog box, in which you can enter the names of two files to compare.
Compare Directories | Displays the Select Directories dialog box, in which you can enter the names of two directories to compare.
Abort | Terminates a file-scanning operation. This menu selection is unavailable until a scanning operation is initiated.
Save File List | Displays the Save File List dialog box, in which you can specify the output file where the comparison results are to be written.
Copy Files | Displays the Copy Files dialog box, in which you can specify files to be copied from one directory to another.
Print | Prints the comparison results.
Exit | Terminates WinDiff.

Edit Menu

You can use the Edit menu to designate the text editor you want to use and to specify which files to display for editing.

Menu Command | Description
Edit Left File | Displays the contents of the first (left) file using the default Notepad editor.
Edit Right File | Displays the contents of the second (right) file using the default Notepad editor.
Edit Composite File | Displays both files using the default Notepad editor.
Set Editor | Displays a WinDiff dialog box, in which you can specify the editor to be used for the preceding operations. By default, Notepad is used.

View Menu

You can use the View menu to compare both the content and graphical representation of two files.

Menu Command | Description
Outline | Displays only the list of filenames (equivalent to the Outline button).
Expand | Displays comparison of the contents of selected files (equivalent to the Expand button).
Picture | Displays a graphical representation of the contents of the two files.
Previous Change | Goes directly to previous area of the file that was changed (if any).
Next Change | Goes directly to next area of the file that was changed (if any).
Rescan Selected File | Recompares the selected file. This allows you to try again if WinDiff is unable to read a file for some reason.

Expand Menu

You can use the Expand menu to display changed lines in the selected file. You can also turn off the display of line numbers.

Menu Command | Description
Left File Only | Expands only the first (left) file, with changed lines colored appropriately.
Right File Only | Expands only the second (right) file, with changed lines colored appropriately.
Both Files | Expands both files, with changed lines colored appropriately.
Left Line Numbers | Displays line numbers for the first (left) file.
Right Line Numbers | Displays line numbers for the second (right) file.
No Line Numbers | Turns off the line number display.

Options Menu

You can use the Options menu to specify file comparison criteria.

Menu Command | Description
Ignore Blanks | Ignores blank spaces in the expanded view, so that lines differing only in the amount of white space are shown as identical.
Mono Colours | Displays differences in black and white only.
Show Identical Files | In outline view, displays files that are identical.
Show Left-Only Files | In outline view, displays files that appear only in the first (left) path.
Show Right-Only Files | In outline view, displays files that appear only in the second (right) path.
Show Different Files | In outline view, displays files that are in both paths, but are different.

Mark Menu

You can use the Mark menu to mark comparison results.

Menu Command | Description
Mark File | Marks selected comparison results.
Mark Pattern | Displays the Mark Files dialog box, in which you can specify the file marking pattern.
Hide Marked Files | Hides all marked files.
Toggle Marked State | Reverses the marked status of marked and unmarked files.

Help Menu

You can use the Help menu to display information about WinDiff.

Menu Command | Description
Contents | Displays the contents of the WinDiff help file.
About | Displays copyright and version information about WinDiff.


How Do I... Topics: WinDiff

Overview

What do you want to do?

Start WinDiff

Use the Expand/Outline Button


Starting WinDiff

Overview | How Do I ... Topics

To start WinDiff

  • Click the Start button on the Windows taskbar and highlight Programs. On the resulting Programs submenu, highlight Visual Fortran 6.0. Next, click WinDiff.

    – or –

  • Use the WinDiff command line.


Using the Expand/Outline Button

Overview | How Do I ... Topics

You can display the filenames or the expanded contents of the selected files. When you choose the Expand button, the contents of the files are expanded and the button label then changes to Outline. When you choose the Outline button, only the filenames are displayed. Files with the same name but different contents are displayed in red text. Identical files are displayed in black text.

To display the expanded contents of the files

  1. Select the files you want to compare.

  2. From the Expand menu, choose Both Files.

  3. From the View menu, choose Expand.

    – or –

    Choose the Expand button.


Overview: ZoomIn

You can use the ZoomIn utility (ZOOMIN.EXE) to capture and enlarge an area of the Windows desktop.

What do you want to know more about?

ZoomIn menus

What do you want to do?

Capture and enlarge an area of the Windows desktop


ZoomIn Menus

Overview | How Do I ... Topics

Edit Menu

You can use the Edit menu to copy to the clipboard and update the ZoomIn window image.

Menu Command | Description
Copy | Copies the contents of the ZoomIn window to the Clipboard.
Refresh | Updates the image in the ZoomIn window. This update is visible only if the Windows desktop target area has changed since it was last captured by ZoomIn.

Options Menu

You can use the Options menu to specify the update interval.

Menu Command | Description
Refresh Rate | Enables the automatic update of the ZoomIn window. This dialog box also allows you to specify, in increments of one-tenth of a second, the automatic update interval.

Help Menu

You can use the Help menu to display information about ZoomIn.

Menu Command | Description
About | Displays copyright and version information about ZoomIn.


How Do I... Topics: ZoomIn

Overview

What do you want to do?

Capture and enlarge an area of the Windows desktop


Capturing and Enlarging the Windows Desktop

Overview | How Do I ... Topics

To use ZoomIn

  1. In Windows Explorer (or My Computer), double-click the file ...\Microsoft Visual Studio\Common\Tools\Zoomin.exe or type ZOOMIN from a Fortran Command Prompt window.

  2. Click within the ZoomIn window's client area and drag the rectangle over the target area you want to enlarge.

    This target area can be anywhere in the Windows graphical desktop area. The area over which you center the ZoomIn rectangle appears in the ZoomIn window's client area.

  3. Release the mouse button when the desired target area is visible in the ZoomIn window.

To enlarge the image, use the scroll bar to scroll down. To reduce the image to its original size, use the scroll bar to scroll up. Each successive click on the scroll bar enlarges or shrinks the image.


Home Page: Source-Code Control

Source-code control systems enable you to track changes to source-code files during software development. The Microsoft visual development environment provides facilities for integrating a source-code control system into the development environment.

Overview | How Do I ... Topics

For information about Source-Code Control see:

Setting up source-code control


Overview: Source-Code Control

Home Page (Source-Code Control) | How Do I ... Topics

The Visual C++ development environment provides the functionality for integrating a system to manage your source code files. If you install a source-code control system that conforms to the Microsoft Source-Code Control Interface, you can directly access source-code control functionality from the visual development environment menus.

What do you want to know more about?

The Microsoft Source-Code Control Interface

What do you want to do?

Set up source-code control

Place files under source-code control


The Microsoft Source-Code Control Interface

Home Page (Source-Code Control) | How Do I ... Topics

If your source-code control system conforms to the Microsoft Source-Code Control Interface, you have access to the commonly supported source-control features available in the Visual C++ environment.

These integrated operations do not encompass all possible capabilities of source-code control systems. Certain source-code control operations require that you use the programs or features of your installed source-code control system. These operations include adminstrative tasks, such as designating locations for master versions of files, creating network connections, setting permissions for drives and/or directories, or adding user information and permissions to the system.

If your installed source-code control system supports other operations in addition to these, the Visual C++ environment provides access to them from the Advanced buttons. Advanced buttons can be found on several dialog boxes, including the Source Control tab of the Options dialog box (Tools menu, Options command), the Add to Source Control dialog box, and the Check In File(s) dialog box (Project menu, Source Control submenu commands). If no other operations are available, the Advanced buttons are dimmed or are not visible.

What do you want to do?

Place an entire project under source-code control.

Place individual files under source-code control.

Get the current version of a file.

Check files in and out of the source-code control system.

Remove files from the source-code control system.

View the history of changes made to a file.

View the differences between a local copy of a file and a master copy.

Using the Source-Code Control toolbar


How Do I... Topics: Source-Code Control

Home Page (Source-Code Control) | Overview

What do you want to do?

Set up source-code control

Place files under source-code control

Check files in and out of source-code control

Remove files from source-code control

Determine a file’s status and examine its history

Maintain project files under source-code control

Use standard and custom toolbars


Setting Up Source-Code Control

Home Page (Source-Code Control) | Overview | How Do I ... Topics

Until you install a source-code control system that conforms to the Microsoft Common Source-Code Control Interface, the source-code control menu commands will not appear in the visual development environment. In addition, either you or the installation program must make the correct entries in the Registry.

To use visual development environment integrated source-code control:

  1. Install a source-code control system that conforms to the Microsoft Common Source Code Control Interface.

  2. Ensure that the installation program for the source-code control system writes the correct information to the Registry, and if it doesn’t, make the correct entries.

  3. Complete all the administrative tasks required by your source-code control system. These tasks may include designating locations for master versions of files, creating network connections, setting permissions for drives and/or directories, or adding user information and permissions to the system.


Placing Files Under Source-Code Control

Home Page (Source-Code Control) | Overview | How Do I ... Topics

When you add a file to your source-code control system, the system manages access to the file and maintains a record of all changes made to the file. It also records when a file was changed and who changed the file. From the visual development environment, you can place entire projects, individual files or workspace files under source-code control.

Workspace files track changes in location of files, additions of files to projects, and the locations of the files in source code control. After changing any of these elements, the workspace file needs to be checked out, updated, and checked in.

What do you want to do?

Add an entire project to source-code control

Add individual files to source-code control

Get the current version of a file


Adding a Project to Source-Code Control

Home Page (Source-Code Control) | Overview | How Do I ... Topics

You can add a project to your source-code control system any time after you have created it.

Note Before you can add any files to source-code control, you must complete any administrative tasks required by your source-code control system, using the administrative program supplied by your system. This may include adding users or creating a source-code control project database, for instance.

To add a project to source-code control

  1. Select an existing project in the FileView pane.

  2. From the Project menu, choose Source Control, and from the drop-down menu, choose Add To Source Control.

    The installed source-code control displays one or more dialog boxes, requesting source-code control project information.

  3. Specify the information required by the installed source-code control system.

    The Add To Source Control dialog box appears, with files in the project workspace selected.

  4. If you want to add the files to source-code control, but immediately check them out, select the Keep Checked Out check box.

  5. In the Comment text box, type a comment about the files, if you want.

    Note If your source-code control system supports additional options, an Advanced button appears on the Add To Source Control dialog box, and you can select those options at this point.

  6. Click OK.


Adding Individual Files to Source-Code Control

Home Page (Source-Code Control) | Overview | How Do I ... Topics

You can set visual development environment options to prompt you automatically each time you insert files into your project, or you can choose explicitly to put them under source-code control.

To prompt automatically for inclusion under source-code control

  1. From the Tools menu, choose Options.

  2. Click the Source Control tab.

  3. Select the Prompt To Add Files When Inserted check box.

  4. Click OK.

    Now, each time you insert files into the project, the visual development environment prompts you to add the inserted files to your source-code control system.

If some or all of the files currently included in your project are not under source-code control, you can add them individually to the source-code control system.

Note Files listed in the External Dependencies folder in FileView are not part of the project, but are needed to build the project. These files will not show up in any source-code control dialog boxes unless they are added to the project. To add a file to the project, simply drag it from the External Dependencies folder into any of the project folders.

To add individual files to source-code control

  1. In the FileView pane of the Project Workspace window, select the files that you want to put under source-code control.

  2. From the Project menu, choose Source Control, and then choose Add To Source Control from the drop-down menu.

    The Add To Source Control dialog box appears, with checks in the Files list next to the files that you have selected. The list includes all files in the project directory that are not already under source-code control, and you may check or uncheck any files in the list.

  3. In the Comment text box, type a comment about the files, if you want.

  4. Click OK.

    The files are now under source-code control, and the file icons in the FileView pane are now grayed to indicate this.


Getting Current Versions of Files

Home Page (Source-Code Control) | Overview | How Do I ... Topics

Updating your local copies of files to versions from the master source-code control files is called “getting” or “synchronizing” files. In any software project with multiple authors, you need to update your local copies frequently to ensure that you incorporate changes that other authors have made.

In a large project, changes can be made in files you normally do not work in, but that do contain information you use. For instance, project-wide header files may define manifest constants or macros that appear in your source files. When you get or synchronize your local files, the master versions of files are copied to your local project. The files are not checked out, and you cannot modify them and check in changes, but you can build with the most up-to-date versions.

If you have checked out files and made changes to your local copies, and other authors have made changes to those same files and checked them in, your source-code control system reports that you have changes to merge. You then need to follow the recommended procedures in your source-code control system to reconcile and verify those changes.

To get current files in your project

  1. In the FileView pane of the Project Workspace window, select the files that you want to get.

  2. From the Project menu, choose Source Control, and from the drop-down menu, choose Get Latest Version.

    The Get Latest Version dialog box appears, with checks next to the files that you have selected. The list includes all files in the project directory that are under source-code control, and you may check or uncheck any files in the list.

  3. Click OK.

The source-code control system copies all the selected files with changes by other authors to your local directory.

You can also have the visual development environment automatically prompt you to get the current versions of files when you open a project workspace.

To get current versions of files when opening a project workspace

  1. From the Tools menu, choose Options.

  2. Click the Source Control tab.

  3. Select the Get Files When Opening The Workspace check box.

  4. Click OK.


Checking Files In and Out

Home Page (Source-Code Control) | Overview | How Do I ... Topics

When you begin work on your project, normally you open the project in the project workspace and get the current versions of the project files to make sure that you are looking at the most up-to-date sources. Before you begin to modify the source files, you check them out; after you have completed the modifications, you check the files in.

When you have a file checked in, your local copy of the file is read-only, and you cannot save any changes to it. When you check out a file, you can make changes to your local copy of the file, and save those changes to the file. When you check the file in, you copy those changes to the master copy of the file in the source-code control project. This makes those changes available to your coworkers. Depending on the characteristics of your source-code control system, only one author can check out a file, or more than one author can check out a file simultaneously.

In addition to selecting files directly from the FileView pane, you can also check them in and out by selecting from the other panes. For instance, if you select a class to check out in the ClassView pane, the visual development environment prompts you to check out files associated with that class.

What do you want to do?

Check files out

Check files in

Check files in and merge changes

Check files in and ignore changes

Remove files from the source-code control system

Check files in and close the workspace

Get the current version of a file

View the history of changes made to a file

View the differences between a local copy of a file and a master copy


Checking Files Out

Home Page (Source-Code Control) | Overview | How Do I ... Topics

When you check a file out, your installed source-code control system changes the status of the file from read-only to writeable. The system also records that you have the file checked out, and dims the Check Out command (Project menu, Source Control submenu). You then have the necessary permissions to revise the file. Your source-code control system may include a mechanism for exclusive use. You then can specify that you have the file checked out, and that no one else may check out that file.

Some source-code control systems allow multiple authors to check out the same file. In this case, the source-code control system merges the changes from the authors when each one checks in the file.

To check files out

  1. In the FileView pane of the Project Workspace window, select the files that you want to check out.

  2. From the Project menu, choose Source Control, and from the drop-down menu, choose Check Out.

    The Check Out File(s) dialog box appears, if it has been selected as an option.

  3. Type a comment in the Comment text box, if you want.

    Note Not all source-code control systems support comments when checking files out. If yours does not, this text box does not appear.

  4. Click OK.

To be prompted when you check out a file for editing, set the source control option from the Tools menu.

To prompt for check out from editor windows

  1. From the Tools menu, choose Options.

  2. Click the Source Control tab.

  3. Select the Check Out Source File(s) When Edited check box.

  4. Click OK.


Checking Files In

Home Page (Source-Code Control) | Overview | How Do I ... Topics

When you check a file in, the source-code control system changes the status of the file from writeable to read-only, and records that you have checked in the file. It also records the differences between the contents of the file when you checked it out and when you checked it in.

You generally want to view the changes to the file before you check it in to confirm the changes that you made. In some cases, you may want to discard all changes to your file before checking it in. In other cases, you may need to merge changes that coworkers have made to the file after you checked it out. If you had the file checked out exclusively, after you check it in, others can check out the file.

What do you want to do?

Check files in and merge changes

Check files in and ignore changes

Check files in and close the workspace


Checking Files In and Merging Changes

Home Page (Source-Code Control) | Overview | How Do I ... Topics

If your source-code control system does not support exclusive use, it could happen that while you had the file checked out, another author also may have checked out the file, made changes, and then checked the file in. In this case, before you check in your local copy of the file, you need to find out if there were changes made by other authors. If so, you need to merge those changes into your local copy. You can then verify that all the changes are compatible and that none cause problems when you use the file. After you have verified the changes, you can check in the file.

To check files in and merge others’ changes

  1. In the FileView pane of the Project Workspace window, select the files that you want to check in.

  2. From the Project menu, choose Source Control, and from the drop-down menu, choose Get Latest Version.

    The Get Latest Version dialog box appears, with checks next to the files that you have selected. The list includes all files in the project directory under source-code control, and you may check or uncheck any files in the list.

  3. Click OK.

    The source-code control system copies master files to your local copies. If there is a file with changes in both your local copy and the master copy, your source-code control system notifies you that you have changes to merge. You then need to follow the recommended procedures in your source-code control system to reconcile the changes and verify those changes.

  4. Repeat steps 1 through 3.

    Remember that while you are verifying the last set of changes, another set may have appeared.

  5. When your source-code control system reports that there are no more files to merge, select the files that you want to check in.

  6. From the Project menu, choose Source Control and from the drop-down menu, choose Check In.

    The Check In File(s) dialog box appears, with checks next to the files that you have selected. The list includes all files in the project directory, and you may check or uncheck any files in the list.

  7. Click OK.

You can also check in a file using the shortcut menu in the text editor windows. Press the right mouse button to display the menu, and choose Check In.


Checking Files In and Removing Changes

Home Page (Source-Code Control) | Overview | How Do I ... Topics

In some cases, you may make changes to your local files, and then decide that you do not want to check the changes in to the source-code control system. You may, for instance, have viewed the local changes and discovered errors, you may have pursued some modifications that were not fruitful, or you may not have had time to implement some changes completely and do not care to check in incomplete code. In these cases, you can have the source-code control system check the files in, but ignore any changes you made.

Note If you want to save the changes before checking the files in without the changes, you can always copy the files to another location, or save them under another name using the Save As command on the File menu.

To check files in but ignore changes

  1. In the FileView pane of the Project Workspace window, select the files that you want to check in without incorporating changes.

  2. From the Project menu, choose Source Control, and from the drop-down menu, choose Undo Check Out.

    The Undo Check Out dialog box appears, with checks next to the files that you have selected. The list includes all checked-out files in the project directory, and you may check or uncheck any files in the list.

  3. Click OK.

    The source-code control system changes the status of the files to checked in, but does not copy any of your changes to the master files. It does not record any differences. It also restores your local copy of the file so that it matches the master file.


Removing Files from Source-Code Control

Home Page (Source-Code Control) | Overview | How Do I ... Topics

When you remove files from your Visual Fortran project, you may first want to remove them from source-code control.

To remove a file from source-code control

  1. In the FileView pane of the Project Workspace window, select the files that you want to remove from source-code control.

  2. From the Project menu, choose Source Control, and from the drop-down menu, choose Remove From Source-Code Control.

    The Remove From Source-Code Control dialog box appears, with checks in the Files list next to the files that you have selected. You may check or uncheck any files in the list.

  3. Click OK.

Note Not all source-code control systems allow individual users to remove files from source-code control. Some systems require source-code control administrators to remove them, and the administrator may need to use the source-code control system’s administrative program.


Determining the Status of Files

Home Page (Source-Code Control) | Overview | How Do I ... Topics

When you are using a source-code control system, it is important to be able to determine the status of files within the system. This can help prevent collisions in groups with multiple authors, ensure that you are working on current files, determine whether you have access to a file, and so on. You also can examine the historical status of files to determine when and what changes were made, and who made them.

What do you want to do?

Examine file histories.

View the changes to a file

Read the FileView pane

Examine the property pages for a file

Check files in and close the workspace

Maintain the project file


Examining File Histories

Home Page (Source-Code Control) | Overview | How Do I ... Topics

In some cases, you may want to know what changes were made to a file, either recently or throughout its existence. You can request the source-code control system to show a history for a file or files that you have added to source-code control. Some source-code control systems allow you to select only a single file. The type of detail shown in the file histories depends on the source-code control system.

To show file histories

  1. In the FileView pane of the Project Workspace window, select the file or files for which you want a history.

  2. From the Project menu, choose Source Control, and then choose Show History from the drop-down menu.

    Your source-code control system displays the history for the selected file or files.

For more information see: Reading the FileView pane, Examining the property pages for a file,Viewing the changes to a file.


Viewing the Changes to a File

Home Page (Source-Code Control) | Overview | How Do I ... Topics

It is best to review the changes that you have made in a file before you check in the file. Your source-code control system displays the differences between your local version of the file and the master version in your source-code control project.

To view your changes

  1. Select the file with the changes that you want to view.

    Note You can select only a single file, which must already be checked out. This method reports only the differences between this version and the master version. You cannot use this method to examine differences between two files in your project, for instance.

  2. From the Project menu, choose Source Control, and from the drop-down menu, choose Show Differences.

    Your source-code control system displays the differences, or reports that the files are identical.


Reading the FileView and ClassView Pane

Home Page (Source-Code Control) | Overview | How Do I ... Topics

The FileView pane of the Project Workspace window displays all the files that are currently in the project workspace, and the ClassView pane displays all the Visual C++ classes (for a mixed-language project). If a project is under source-code control, the file icons are grayed, and if a file is checked out, a check mark appears to the left of the file icon.

If all the files associated with a class are checked out, a red check mark will appear to the left of the class icon. If some, but not all, files associated with a class are checked out, a black check mark will appear to the left of the class icon.

For more information see: Examining the property pages for a file,Examining the file’s history, Viewing the changes to a file.


Examining File Status on Property Pages

Home Page (Source-Code Control) | Overview | How Do I ... Topics

Each file in a project has a property page associated with it. The property page includes information about the file, including its current status in the source-code control system if it is under source-code control.

Note If the file is not under source-code control, no status information appears on the property page.

To examine a property page from the FileView pane

Select the file in the FileView pane of the Project Workspace window, and press ALT+ENTER.

– or –

Select the file in the FileView pane of the Project Workspace window, click the right mouse button to display the shortcut menu, and choose Properties.

– or –

Select the file in the FileView pane of the Project Workspace window, and from the View menu, choose Properties.

To examine a property page from a source editor window

Press ALT+ENTER.

– or –

Click the right mouse button to display the shortcut menu and choose Properties.

– or –

From the View menu, choose Properties.


Checking Files In When Closing the Workspace

Home Page (Source-Code Control) | Overview | How Do I ... Topics

You can choose to have the visual development environment prompt you to check in files when you close the current workspace.

To check in files when closing the workspace

  1. From the Tools menu, choose Options.

  2. Click the Source Control tab.

  3. Select the Check In Files When Closing The Workspace check box.

  4. Click OK.


Maintaining the Project File

Home Page (Source-Code Control) | Overview | How Do I ... Topics

If you work in a group, you generally want to share the Project file (.dsp) for a project workspace with other members of your group. This ensures that everyone in the group can build the projects defined in the project workspace using the same files, settings, tools, and so on, as well as ensuring that everyone gets the changes to the Project file and builds with the most up-to-date settings.

Updating the Project file in a group setting requires some coordination among the members of the group in order for the process to work smoothly. In the optimal case, all members of the group get the Project file from source-code control when they open the project, but no one checks it out.

The system will prompt you to check out the Project file whenever it has determined that changes are necessary. However, you must remember to check it back in and notify the members of the group that it has been changed.

At this point, the other members of the group need to close the project workspace, then reopen it and get the new version of the Project file. If they have set the option to prompt to get the latest versions of files, opening the project workspace reminds them to get the latest version.

If two or more members of the group simultaneously check out the Project file and revise it, checking the Project file in could require merging changes. Because the system may write multiple settings to a single line of the Project file, and changes to settings by different users may alter a single line in two (or more) different places, reconciling those changes manually could result in errors.

Note If your source-code control system supports exclusive check-outs, you should check the Project file out for exclusive use if you need to alter it.


Using the Source-Code Control Toolbar

Home Page (Source-Code Control) | Overview | How Do I ... Topics

You can access the integrated source-code control commands from buttons on a standard toolbar.

To display the Source-Code Control toolbar

  1. On the Tools menu, click Customize, then Toolbars.

  2. From the Toolbars list, select Source Control.

  3. Click Close.

You can also remove buttons from the toolbar, add other buttons, or add source-code control buttons to other toolbars. For information on customizing toolbars, see the section Working with Toolbars.


Overview: Automation

In the Visual C++ Developer Studio environment, you perform many tasks manually. For example, you use menu commands to open projects, change source code files, save changes to these files, and then rebuild applications that use the files.

If your tasks are routine or repetitive, you can benefit from automating them. Through Automation (formerly OLE Automation), you can reduce the time spent on these tasks, and you can prevent errors that often result from performing the tasks manually.

With Automation, you perform tasks programmatically by writing VBScript macros or Developer Studio add-ins. VBScript macros are procedures you write in the VBScript language, and add-ins are in-process COM components (DLLs) you write in Visual C++ or Visual Basic.

In macros or add-ins, you perform tasks by manipulating the Developer Studio environment and its components as objects. For example, you open, edit, and close a document by manipulating it as an object. Similarly, you activate or size a window by manipulating it as an object.

An object represents one component of the development environment, or it represents a collection of related components. For example, a Document object represents one open document, whereas the Documents object represents all open documents. Similarly, a Window object represents one open window, whereas the Windows object represents all open windows. The Documents and Windows objects are called collection objects because they include collections of related objects.

You manipulate objects by using methods, properties, and events associated with the objects. Methods represent actions you take against the objects. Properties represent characteristics of the objects, such as their type or size. And, events represent conditions under which actions are taken against the objects.

Suppose you want to create a Fortran Fixed Form source file quickly — by simply pressing a button. Start by writing a VBScript macro that will create the file. The macro looks like this:

Sub CreateFORFile
   Set FORDoc = Documents.Add(“Text”)
   FORDoc.Language = dsFortran_Fixed
End Sub

This macro does the following:

  • The Sub statement begins the macro, which has the name CreateFORFILE. The name is arbitrary; you can use whatever name you choose.

  • The first line of the macro creates the file by adding a Document object to the collection of Document objects, using the Add method of the Documents collection.

  • The second line of the macro specifies the file type (Fortran Fixed Form) by setting the Language property of the Document object equal to the constant dsFortran_Fixed. This constant represents Fortran Fixed Form.

  • The End Sub statement ends the macro.

After writing the macro, assign it to a toolbar button. Then, press the button to run the macro.

For more information about writing VBScript macros, see Overview: VBScript Macros. For details about objects you can use to perform tasks in Developer Studio, see Reference: Developer Studio Objects. And, for details about creating add-ins, see Overview: Developer Studio Add-ins.


Home Page: Developer Studio Objects

You can automate tasks in the Visual C++ development environment by using Developer Studio objects with VBScript macros and Developer Studio add-ins.

For information about using Developer Studio objects

  • Overviews

  • Frequently Asked Questions

  • Reference

Related Home Pages

  • VBScript macros

  • Add-ins for the Visual C ++ Developer Studio

  • Customizing Visual C++


Overview: Developer Studio Objects

Home Page (Objects) | FAQ | Reference

You can automate tasks from within the Visual C++ Developer Studio environment by creating VBScript macros and Developer Studio add-ins. You can also automate tasks from other applications such as Visual Basic and Excel.

You automate tasks by manipulating the environment (Developer Studio) and its components as objects. For example, you open, edit, and close a document by manipulating it as an object. Similarly, you activate or size a window by manipulating it as an object.

You manipulate objects by using methods, properties, and events associated with the objects. Methods represent actions you take against the objects. Properties represent characteristics of the objects, such as their type or size. And, events represent conditions under which actions are taken against the objects.

What do you want to know more about?

The benefits of automation

Automation from other applications

Developer Studio objects

Methods

Properties

Events

Differences between VBScript macros and Developer Studio add-ins


Automating Developer Studio Tasks from Other Applications

Automating Tasks from Other Applications

With Automation, you can control the Visual C++ environment from other applications such as Word, Excel, or Visual Basic. You can start Visual C++, automate tasks, and then stop Visual C++ when the tasks are finished.

Starting Developer Studio (the Visual C++ Environment)

To start Developer Studio from another application, create an instance of the Developer Studio Application object. For example, to start Developer Studio from Visual Basic or Visual Basic for Applications, use the following code:

Dim app as Application
Set app = CreateObject("MSDev.Application")

When Developer Studio starts, it will be invisible, unless you make it visible by using the Visible property of the Application object:

Dim app as Application
Set app = CreateObject("MSDev.Application")
app.Visible = True

If Developer Studio is already running, you can use that instance of it instead of creating another one. For example, to use the current instance of Developer Studio from Visual Basic or Visual Basic for Applications, use the following code:

Dim app as Application
Set app = GetObject(,"MSDev.Application")

Automating Tasks in Developer Studio

After starting Developer Studio, you can automate tasks in it by using the appropriate code. For example, in the following code, the comment indicates where to insert code for automating tasks:

Dim app as Application
Set app = CreateObject("MSDev.Application")
app.Visible = True
' Insert code for automating tasks here.

Stopping Developer Studio

After completing your Developer Studio tasks, you can stop Developer Studio by quitting the application and releasing all references to the Application object.

Note If you use Visual Basic to automate Developer Studio, Visual Basic automatically releases all references to the Application object.

To quit Developer Studio, use the Exit command on the File menu or the Quit method of the Application object. If you use the Quit method, however, you must use it before you release its reference to the Application object.

For example, the following code shows how to use the Quit method.

Dim app as Application
Set app = CreateObject("MSDev.Application")
app.Visible = True
' Insert code for automating tasks here.
app.Quit

Note If the user tries to stop Developer Studio while your program is controlling it, Developer Studio will remain in memory but the user interface will become invisible. Subsequently, if you try to access Developer Studio objects, Developer Studio will return errors. If this happens, release all references to the Application object so that Developer Studio can quit.


Getting or Setting Properties of Developer Studio Objects

Home Page (Objects) | Overview | FAQ | Reference

Developer Studio objects have a variety of properties. For example, a TextWindow or Window object has a Caption property that indicates the caption of a window. Additionally, a TextWindow or Window object has a Height property that indicates the height of a window.

Some properties are read-only, whereas others are read/write. This means you can only get the values of some properties, whereas you can get or set the values of others.

For example, you can only get the value of the Caption property, as shown in the following example.

Dim X
X = ActiveWindow.Caption

Alternatively, you can get or set the value of the Height property. For example, you can set the value of the Height property to 10, as shown in the following example.

ActiveWindow.Height = 10

For more information about properties, see the property descriptions, and for more examples see Using the Sample Macros provided with Developer Studio.


Applying Methods to Developer Studio Objects

Home Page (Objects) | Overview | FAQ | Reference

Most Developer Studio objects have methods. These represent actions you can take against the objects.

For example, the Open method of the Documents object allows you to open a document. Suppose you create a macro and then save it as MyFile.dsm in your local directory. To open this file, you can use the following code:

Documents.Open ("c:\program files\Microsoft Visual Studio\Common\MSDEV98\Macros\MyFile.dsm")

Similarly, to close this file you can use the Close method of the TextDocument object:

ActiveDocument.Close

For more information about methods, see the method descriptions, and for more examples see Using the Sample Macros provided with Developer Studio.


Using Events with Developer Studio Objects

Home Page (Objects) | Overview | FAQ | Reference

An event is an action or occurrence, often generated by the user, to which a VBScript event handler, Developer Studio add-in, or other Automation controller can respond. For example, if a user clicks on a window, Developer Studio fires the WindowActivate event of the Application object.

In a VBScript event handler, you can respond to an event by taking some action. For instance, you could change the size of a window by setting the Height and Width properties of the Window object.

To respond to an event, add the appropriate event handler to any loaded VBScript macro file. You can add this event handler to multiple VBScript macro files. For example, if you add an event handler for the WindowActivate event to two loaded VBScript macro files, when the user activates a window, both of these event handlers will be called, one at a time.

To add the event handler, find the appropriate event in the documentation, copy the sample event handler from the example, paste the handler into your macro file, insert the appropriate code into the handler, and then reload the macro file.

For example, you could take some action just before Developer Studio quits by using the BeforeApplicationShutDown event. To use this event, go to the description of the event and copy the sample event handler:

sub    Application_BeforeApplicationShutDown()
   ' Insert code to handle event here
end sub

Then, paste this code into your macro file, insert the code for handling the event, and then reload the macro file.

Tip To reload the macro file, open the file in the text editor, click the right mouse button, and then click Reload Macros in File.


Frequently Asked Questions: Developer Studio Objects

Home Page (Objects) | Overview | Reference

You can automate tasks in the Visual C++ environment by using Automation (formerly OLE Automation). Following are some frequently asked questions about Automation.

Where can I find information about Automation?

What are the ways I can access the Visual C++ Developer Studio object model?

How do I automate the Visual C++ environment from an MFC application?

How do I automate the Visual C++ environment from a Visual Basic application?

How do I automate the Visual C++ environment from a Visual Fortran application?

How do I automate the Visual C++ environment from Excel or Word?


Where Can I Find Information About Automation?

Home Page (Objects) | Overview | FAQ | Reference

You can find more information about Automation in the Automation overview.


What Are the Ways I Can Access the Developer Studio Object Model?

What Are the Ways I Can Access the Visual C++ Developer Studio Object Model?

Home Page (Objects) | Overview | FAQ | Reference

You can access the Developer Studio (Visual C++ environment) object model in three ways:

  • Write VBScript macros that script the environment through its object model.

  • Create add-ins.

  • In applications such as Microsoft Word, Microsoft Excel, Microsoft Visual Basic, Microsoft Visual C++, or Digital Visual Fortran, write an Automation controller that accesses the Developer Studio environment by creating an instance of it. For example, in Visual Fortran, use the COMCREATEOBJECT routine to create an instance of Developer Studio. In Visual Basic, use the CreateObject function to create an instance of Developer Studio. Or in Visual C++, call the Win32 CoCreateInstance function. For more information, see the application's documentation.


How Do I Automate Developer Studio from an MFC Application?

How Do I Automate the Visual C++ Environment from an MFC Application?

Home Page (Objects) | Overview | FAQ | Reference

You can automate Developer Studio (the Visual C++ environment) from an MFC application by creating an add-in or executable. The add-in would access the Developer Studio object model by using the Type libraries, whereas the executable would use the header files.


How Do I Automate Developer Studio from a Visual Basic Application?

How Do I Automate the Visual C++ Environment from a Visual Basic Application?

Home Page (Objects) | Overview | FAQ | Reference

You can automate Developer Studio (the Visual C++ environment) from a Visual Basic application by creating an add-in or executable. The add-in would access the Developer Studio object model by using the Type libraries, whereas the executable would use the header files.


How Do I Automate Developer Studio from a Visual Fortran Application?

How Do I Automate the Visual C++ Environment from a Visual Fortran Application?

Home Page (Objects) | Overview | FAQ | Reference

You can automate Developer Studio (the Visual C++ environment) from a Visual Fortran application. Use the Fortran Module Wizard (see the Visual Fortran Programmer's Guide) to create Fortran interfaces from the Developer Studio type libraries. Also see the DSBUILD Visual Fortran Sample for an example of a Visual Fortran application that automates Developer Studio.


How Do I Automate Developer Studio from Excel or Word?

How Do I Automate the Visual C++ Environment from Excel or Word?

Home Page (Objects) | Overview | FAQ | Reference

You can automate Developer Studio (the Visual C++ environment) from Excel or Word by developing an Automation controller that accesses the environment by creating an instance of it. For details, see the Excel or Word documentation.


Reference: Developer Studio Objects

Home Page (Objects) | Overview | FAQ |

The Developer Studio object model enables you to automate development tasks in the Visual C++ development environment. This object model consists of the hierarchy of Developer Studio objects, and their associated properties, methods, and events.

This section describes each object, along with its properties, methods, and events.

  • Objects

  • Properties

  • Methods

  • Events


Objects

Objects and the Object Hierarchy

Home Page (Objects) | Overview | FAQ | Reference

You can control the Visual C++ Developer Studio environment programmatically by manipulating it through Automation (formerly OLE Automation). For example, in a VBScript macro, you can control an open document by manipulating its corresponding Document object.

Each Developer Studio object implements a dual interface through which you can manipulate the object. Each object implements an IDispatch interface for Automation and a Component Object Model (COM) interface for direct access to object members (properties, methods, events).

Add-ins written in Visual C++ versions 5.0 or later, or Visual Basic versions 4.0 or later can employ early binding by using the COM interface. Early binding makes all calls into interface members faster at run time.

Overview of Each Developer Studio Object

Each Developer Studio object is described below.

Object | Represents
Application | The Developer Studio (environment for Visual C++) application.
Breakpoint | A breakpoint, which is used for debugging purposes.
Breakpoints | All the breakpoints set during a Developer Studio session.
BuildProject | A project that contains build (configuration) information.
Configuration | A set of settings to use for building a project.
Configurations | All configurations in a project.
Debugger | Enables you to inspect the execution of processes in the application in Developer Studio.
Document | An open document.
Documents | All open documents; a collection of one or more Document and TextDocument objects.
Project | A group of related files.
Projects | All projects in the currently open workspace.
TextDocument | An open text file.
TextEditor | The Developer Studio text editor.
TextSelection | Selected text in an open text document.
TextWindow | A view of an open text file.
Window | A multiple document interface (MDI) client window in which a document is being edited.
Windows | A collection of windows; all open windows.

The Developer Studio Object Hierarchy for Automation

To manipulate Developer Studio objects, you must know the relationships between them. The Application object is at the top, and the other objects are subordinate to it. This relationship allows you to directly access objects subordinate to the Application object by using the properties and methods of the Application object.

The "has-a" tree is shown below. For example, the Breakpoints object has, as one of its properties, a Breakpoint object.

Application
    Application (Application is its own parent)
        Projects
            Project
                Configurations
                    Configuration
                        Configurations (circular)
        Documents
            Document
                Window (for "Generic" window types)
            TextDocument
                TextSelection
                TextWindow
                Window (for "Text" window types)
        TextEditor
        Windows
        Debugger
        Breakpoints
            Breakpoint

See Also Parent Property.


Application Object

Home Page (Objects) | Overview | FAQ | Reference

The Application object represents Developer Studio and is the topmost object in the Developer Studio object hierarchy. From the Application object, you can directly access other Developer Studio objects by using the Application object's properties and methods, or you can indirectly access objects through other objects obtained by these properties and methods.

The Application object has the following properties, methods, and events:

Properties |
Active | Name
ActiveConfiguration | Parent
ActiveDocument | Path
ActiveProject | Projects
ActiveWindow | TextEditor
Application | Top
CurrentDirectory | Version
Debugger | Visible
Documents | Warnings
Errors | Width
FullName | Windows
Height | WindowState
Left |

Methods |
AddCommand | ExecuteCommand
AddCommandBarButton | ExecuteConfiguration
AddKeybinding | GetPackageExtension
AddProject | PrintToOutputWindow
Build | Quit
Clean | RebuildAll
EnableModeless | SetAddInInfo

Events |
BeforeApplicationShutDown | NewDocument
BeforeBuildStart | NewWorkspace
BeforeDocumentClose | WindowActivate
BuildFinish | WindowDeactivate
DocumentOpen | WorkspaceClose
DocumentSave | WorkspaceOpen

Because the Application object is the topmost object, its name is implied when you access its properties and methods. Accordingly, you only need to specify its property or method names. For example, to access the Quit method, you only need to specify Quit — not Application.Quit.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Application object implements the IApplication dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run-time.

Add-ins written in Visual C++ can access members of the Application object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following header files are used for the Application object:

appauto.h | Declares the dual interfaces.
appguid.h | Declares the GUIDs used to identify the interfaces.
appdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Application object by using the Shared Objects type library, located in msdev98\bin\devshl.dll.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."


Breakpoint Object

Home Page (Objects) | Overview | FAQ | Reference

The Breakpoint object represents a breakpoint that is set for debugging purposes.

The Breakpoint object has the following properties and methods:

Properties |
Application | Location
Condition | Message
Elements | Parent
Enabled | PassCount
Executable | Type
File | WindowProcedure
Function |

Methods
Remove

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Breakpoint object implements the IBreakpoint dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Breakpoint object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following header files are used for the Breakpoint object:

dbgauto.h – Declares the dual interfaces.

dbgguid.h – Declares the GUIDs used to identify the interfaces.

dbgdefs.h – Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Breakpoint object by using the Debugger type library, located in msdev98\bin\ide\devdbg.pkg.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."


Breakpoints Object

Home Page (Objects) | Overview | FAQ | Reference

The Breakpoints object represents all the breakpoints set during a Developer Studio debugging session.

The Breakpoints object has the following properties and methods:

Properties |
Application | _NewEnum
Count | Parent

Methods |
AddBreakpointAtLine | RemoveBreakpointAtLine
Item |

The Breakpoints object is a collection object that contains all Breakpoint objects. To find a particular object, iterate through the collection by using For Each ... Next in a VBScript macro.

Consider the following code snippet:

Dim myBreakpoint
For Each myBreakpoint in Debugger.Breakpoints
   ' Access myBreakpoint here.
   ' For example:
    MsgBox myBreakpoint.PassCount
Next

In Visual C++, you can iterate through the Breakpoints collection by using the Item method or _NewEnum property.

When you reference the Breakpoints collection, the reference always reflects the current contents of the collection. For example, suppose you have two macros (A and B). In macro A, you set a global variable to the collection, and in macro B you use the variable. When you use it, the variable will reflect the current contents of the collection — not the contents present when you set the variable.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Breakpoints object implements the IBreakpoints dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Breakpoints object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Breakpoints object:

Header file | Description
dbgauto.h | Declares the dual interfaces.
dbgguid.h | Declares the GUIDs used to identify the interfaces.
dbgdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Breakpoints object by using the Debugger type library, located in msdev98\bin\ide\devdbg.pkg.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."


BuildProject Object

Home Page (Objects) | Overview | FAQ | Reference

The BuildProject object represents a project that also includes configuration information.

The BuildProject object has the following properties and methods:

Properties |
Application | Name
Configurations | Parent
FullName | Type

Methods |
AddConfiguration | AddFile

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The BuildProject object implements the IBuildProject dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the BuildProject object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the BuildProject object:

Header file | Description
bldauto.h | Declares the dual interfaces.
bldguid.h | Declares the GUIDs used to identify the interfaces.
blddefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the BuildProject object by using the Visual Studio '97 Project System type library, located in Msdev98\bin\ide\devbld.pkg.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."


Configuration Object

Home Page (Objects) | Overview | FAQ | Reference

The Configuration object represents a set of settings to use for building a project. You can have as many configurations as ways you want to build the project.

The Configuration object has the following properties and methods:

Properties |
Application | Name
Configurations | Parent

Methods |
AddCustomBuildStep | MakeCurrentSettingsDefault
AddCustomBuildStepToFile | RemoveFileSettings
AddFileSettings | RemoveToolSettings
AddToolSettings |

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Configuration object implements the IConfiguration dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Configuration object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Configuration object:

Header file | Description
bldauto.h | Declares the dual interfaces.
bldguid.h | Declares the GUIDs used to identify the interfaces.
blddefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Configuration object by using the Visual Studio '97 Project System type library, located in Msdev98\bin\ide\devbld.pkg.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."


Configurations Object

Home Page (Objects) | Overview | FAQ | Reference

The Configurations object represents all configurations in a project.

The Configurations object has the following properties and methods:

Properties |
Application | _NewEnum
Count | Parent

Methods
Item

The Configurations object is a collection object that only contains Configuration objects. To find a particular object, iterate through the collection by using For Each ... Next in a VBScript macro.

Consider the following code snippet:

Dim myConfiguration
For Each myConfiguration in Project.Configurations
   ' Access myConfiguration here.
   ' For example:
    MsgBox myConfiguration.Name
Next

In Visual C++, you can iterate through the Configurations collection by using the Item method or _NewEnum property.

When you reference the Configurations collection, the reference always reflects the current contents of the collection. For example, suppose you have two macros (A and B). In macro A, you set a global variable to the collection, and in macro B you use the variable. When you use it, the variable will reflect the current contents of the collection — not the contents present when you set the variable.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Configurations object implements the IConfigurations dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Configurations object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Configurations object:

Header file | Description
bldauto.h | Declares the dual interfaces.
bldguid.h | Declares the GUIDs used to identify the interfaces.
blddefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Configurations object by using the Visual Studio '97 Project System type library, located in Msdev98\bin\ide\devdbg.pkg.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."

See Also BuildProject object, Configuration object.


Debugger Object

Home Page (Objects) | Overview | FAQ | Reference

With the Debugger object, you can inspect the processes being debugged in Developer Studio.

The Debugger object has the following properties and methods:

Properties |
Application | Parent
Breakpoints | RemoteProcedureCallDebugging
DefaultRadix | State
JustInTimeDebugging |

Methods |
Evaluate | ShowCurrentStatement
Go | StepInto
Restart | StepOut
RunToCursor | StepOver
SetNextStatement | Stop

The Debugger object has the following event:

BreakpointHit

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Debugger object implements the IDebugger dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Debugger object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Debugger object:

Header file | Description
dbgauto.h | Declares the dual interfaces.
dbgguid.h | Declares the GUIDs used to identify the interfaces.
dbgdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Debugger object by using the Visual Studio '97 Debugger type library, located in Msdev98\bin\ide\devdbg.pkg.

Note Visual Studio '97 Debugger is the name that appears in the Visual Basic References dialog box.


Document Object

Home Page (Objects) | Overview | FAQ | Reference

The Document object represents an open document.

The Document object has the following properties and methods:

Properties |
Active | Path
ActiveWindow | ReadOnly
Application | Saved
FullName | Type
Name | Windows
Parent |

Methods |
Close | Redo
NewWindow | Save
PrintOut | Undo

Each open document in Developer Studio is represented by a Document object. This object has members (properties, methods, and events) that you can use to manipulate the document.

If a document is a text file, that document also has a TextDocument object. This object has all the members of a Document object and also has members that allow you to access text-specific attributes of the document.

Use a document's Type property to determine which members you can access. If the type is "Generic," the document is not a text document and you can access only Document members. If the type is "Text," the document is a text document, and you can access TextDocument members as well as Document members.

In VBScript macros, you access TextDocument members by automatically using late binding. In add-ins however, you can also access TextDocument members by using early binding. Early binding offers better performance than late binding by making calls into the interface faster at run time.

You can access the current document by using the ActiveDocument property of the Application object.

All open documents belong to the documents collection represented by the Documents object. You can find a particular document by iterating through this collection.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Document object implements the IGenericDocument dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Document object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Document object:

Header file | Description
appauto.h | Declares the dual interfaces.
appguid.h | Declares the GUIDs used to identify the interfaces.
appdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Document object by using the Visual Studio '97 Shared Objects type library, located in Msdev98\bin\devshl.dll.

Note Visual Studio '97 Shared Objects is the name that appears in the Visual Basic References dialog box.


Documents Object

Home Page (Objects) | Overview | FAQ | Reference

The Documents object represents all open documents. The Documents object is a collection of one or more Document and TextDocument objects.

The Documents object has the following properties and methods:

Properties |
Application | _NewEnum
Count | Parent

Methods |
Add | Open
CloseAll | SaveAll
Item |

The Documents object is a collection object that contains all Document objects. To find a particular object, iterate through the collection by using the Documents property of the Application object. Consider the following code snippet from a VBScript macro:

Dim myDocument
For Each myDocument in Application.Documents
   ' Access myDocument here.
   ' For example:
    MsgBox myDocument.Name
Next

In Visual C++, you can iterate through the Documents collection by using the Item method or _NewEnum property.

When you reference the Documents collection, the reference always reflects the current contents of the collection. For example, suppose you have two macros (A and B). In macro A, you set a global variable to the collection, and in macro B you use the variable. When you use it, the variable will reflect the current contents of the collection — not the contents present when you set the variable.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Documents object implements the IDocuments dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Documents object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Documents object:

Header file | Description
appauto.h | Declares the dual interfaces.
appguid.h | Declares the GUIDs used to identify the interfaces.
appdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Documents object by using the Visual Studio '97 Shared Objects type library, located in Msdev98\bin\devshl.dll.

Note Visual Studio '97 Shared Objects is the name that appears in the Visual Basic References dialog box.

See Also Document object, TextDocument object.


Project Object

Home Page (Objects) | Overview | FAQ | Reference

The Project object represents a group of related files that can include one or more configurations.

The Project object has the following properties:

Properties |
Application | Type
Name | FullName
Parent |

Each project open in Developer Studio is represented by a Project object. This object has members (properties, methods, and events) that you can use to manipulate the project.

If a project includes configuration information, that project also has a BuildProject object. This object has all the members of a Project object and also has members that allow you to configuration-specific attributes of the project.

Use the project's Type property to determine which members you can access. If the type is "Build," the project is a build project and you can access BuildProject members as well as Project members.

In VBScript macros, you access BuildProject members by automatically using late binding. In Add-ins however, you can also access BuildProject members by using early binding. Early binding offers better performance than late binding by making calls into the interface faster at run time.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Project object implements the IGenericProject dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Project object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Project object:

Header file | Description
bldauto.h | Declares the dual interfaces.
bldguid.h | Declares the GUIDs used to identify the interfaces.
blddefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Project object by using the Visual Studio '97 Project System type library, located in Msdev98\bin\ide\devdbg.pkg.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."


Projects Object

Home Page (Objects) | Overview | FAQ | Reference

The Projects object represents all projects in the currently open workspace.

The Projects object has the following properties and methods:

Properties |
Application | _NewEnum
Count | Parent

Methods
Item

The Projects object is a collection object that contains all Project objects. To find a particular object, iterate through the collection by using For Each ... Next in a VBScript macro.

Consider the following code snippet:

Dim myProject
For Each myProject in Application.Projects
   ' Access myProject here.
   ' For example:
    MsgBox myProject.Name
Next

In Visual C++, you can iterate through the Projects collection by using the Item method or _NewEnum property.

When you reference the Projects collection, the reference always reflects the current contents of the collection. For example, suppose you have two macros (A and B). In macro A, you set a global variable to the collection, and in macro B you use the variable. When you use it, the variable will reflect the current contents of the collection — not the contents present when you set the variable.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Projects object implements the IProjects dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Projects object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Projects object:

Header file | Description
bldauto.h | Declares the dual interfaces.
bldguid.h | Declares the GUIDs used to identify the interfaces.
blddefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Projects object by using the Visual Studio '97 Project System type library, located in Msdev98\bin\ide\devdbg.pkg.

Note In the Visual Basic References dialog box (Project menu, References command), the names of the type libraries begin with "Visual C++ 6.0" for Visual C++ version 6.0. For Visual C++ version 5.0, the names begin with "Visual Studio '97."


TextDocument Object

Home Page (Objects) | Overview | FAQ | Reference

The TextDocument object represents an open text file.

The TextDocument object has the following properties and methods:

Properties |
Active | Path
ActiveWindow | ReadOnly
Application | Saved
FullName | Selection
IndentSize | TabSize
Language | Type
Name | Windows
Parent |

Methods |
Close | Redo
ClearBookmarks | ReplaceText
MarkText | Save
NewWindow | Undo
PrintOut |

You can access all TextDocument objects by using the Documents property of the Application object.

You cannot access properties of the TextEditor object through a TextDocument object.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Project object implements the ITextDocument dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the TextDocument object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the TextDocument object:

Header file | Description
textauto.h | Declares the dual interfaces.
textguid.h | Declares the GUIDs used to identify the interfaces.
textdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the TextDocument object by using the Visual Studio '97 Text Editor type library, located in Msdev98\bin\devedit.pkg.

Note Visual Studio '97 Text Editor is the name that appears in the Visual Basic References dialog box.

See Also Document object, Documents object.


TextEditor Object

Home Page (Objects) | Overview | FAQ | Reference

The TextEditor object represents the Developer Studio text editor.

The TextEditor object has the following properties. These properties affect all text documents open in the editor. For details about text documents, see the TextDocument object.

Properties |
Application | Parent
Emulation | VisibleWhitespace
Overtype |

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The TextEditor object implements the ITextEditor dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the TextEditor object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the TextEditor object:

Header file | Description
textauto.h | Declares the dual interfaces.
textguid.h | Declares the GUIDs used to identify the interfaces.
textdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the TextEditor object by using the Visual Studio '97 Text Editor type library, located in Msdev98\bin\devedit.pkg.

Note Visual Studio '97 Text Editor is the name that appears in the Visual Basic References dialog box.


TextSelection Object

Home Page (Objects) | Overview | FAQ | Reference

The TextSelection object represents a selection in a text editor window. A selection can be a single point (the insertion point) or a contiguous range of text.

Using the TextSelection object, you can move the insertion point, control which text is selected, and modify the contents of the selection.

The TextSelection object has the following properties and methods:

Properties |
Application | Parent
BottomLine | Text
CurrentColumn | TopLine
CurrentLine |

Methods |
Backspace | NewLine
Cancel | NextBookmark
ChangeCase | PageDown
CharLeft | PageUp
CharRight | Paste
ClearBookmark | PreviousBookmark
Copy | ReplaceText
Cut | SelectAll
Delete | SelectLine
DeleteWhitespace | SetBookmark
DestructiveInsert | SmartFormat
EndOfDocument | StartOfDocument
EndOfLine | StartOfLine
FindText | Tabify
GoToLine | Unindent
Indent | Untabify
LineDown | WordLeft
LineUp | WordRight
MoveTo |

You can access the TextSelection object by using the Selection property of the TextDocument object.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The TextSelection object implements the ITextSelection dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the TextSelection object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the TextSelection object:

Header file | Description
textauto.h | Declares the dual interfaces.
textguid.h | Declares the GUIDs used to identify the interfaces.
textdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the TextSelection object by using the Visual Studio '97 Text Editor type library, located in Msdev98\bin\devedit.pkg.

Note Visual Studio '97 Text Editor is the name that appears in the Visual Basic References dialog box.

See Also Document object.


TextWindow Object

Home Page (Objects) | Overview | FAQ | Reference

The TextWindow object represents a view of a TextDocument object — that is, a view of a file that is open). A TextDocument object can have several TextWindow objects.

The TextWindow object has the following properties and methods:

Properties |
Active | Parent
Application | Previous
Caption | Selection
Height | Top
Index | Type
Left | Width
Next | WindowState

Methods
Close

You can access the TextWindow object by using the Windows property of the Application object or by using the window-oriented properties and methods of the Document object.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The TextWindow object implements the ITextWindow dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the TextWindow object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the TextWindow object:

Header file | Description
textauto.h | Declares the dual interfaces.
textguid.h | Declares the GUIDs used to identify the interfaces.
textdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the TextWindow object by using the Visual Studio '97 Text Editor type library, located in Msdev98\bin\devedit.pkg.

Note Visual Studio '97 Text Editor is the name that appears in the Visual Basic References dialog box.

See Also Window object.


Window Object

Home Page (Objects) | Overview | FAQ | Reference

The Window object represents a multiple document interface (MDI) client window in which a document is being edited.

The Window object has the following properties and methods:

Properties |
Active | Parent
Application | Previous
Caption | Top
Height | Type
Index | Width
Left | WindowState
Next |

Methods
Close

Each open window is represented by a Window object. This object has members (properties, methods, and events) that you can use to manipulate the window.

If a window is open on a text file, that window also has a TextWindow object. This object has all the members of the Window object and also has members that allow you to access text-specific attributes of the window.

Use the window's Type property to determine which members you can access. If the type is "Generic," the window is not a text window and you can access only Window members. If the type is "Text," the window is a text window, and you can access TextWindow members as well as Window members.

In VBScript macros, you access TextWindow members by automatically using late binding. In Add-ins however, you can also access TextWindow members by using early binding. Early binding offers better performance than late binding by making calls into the interface faster at run time.

You can access the current (active) window by using the ActiveWindow property of the Application object.

All open windows belong to the windows collection represented by the Windows object. You can find a particular window by iterating through this collection.

If any open windows display a document, you can also access the windows collection associated with the document by using the Windows property of the Document object.

Accessing attributes of the main application window

To access attributes of the main application window, use the properties of the Application object, rather than the properties of the Window object.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Window object implements the IGenericWindow dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Window object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Window object:

Header file | Description
appauto.h | Declares the dual interfaces.
appguid.h | Declares the GUIDs used to identify the interfaces.
appdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Window object by using the Visual Studio '97 Shared Objects type library, located in Msdev98\bin\devshl.dll.

Note Visual Studio '97 Shared Objects is the name that appears in the Visual Basic References dialog box.


Windows Object

Home Page (Objects) | Overview | FAQ | Reference

The Windows object represents a collection of open windows. This collection can represent all windows open in Developer Studio or only windows open on a document. For example, if you access the Windows object by using the Windows property of the Application object, the collection represents all windows open in Developer Studio. However, if a document is open and you use the Windows property of the Document object, the collection represents only windows open on the document.

The Windows object has the following properties and methods:

Properties |
Application | _NewEnum
Count | Parent

Methods |
Arrange | Item
CloseAll |

The Windows object is a collection object that contains all Window objects. To find a particular object, iterate through the collection by using For Each ... Next in a VBScript macro.

Consider the following code snippet:

Dim myWindow
For Each myWindow in Application.Windows
   ' Access myWindow here.
   ' For example:
    MsgBox myWindow.Caption
Next

In Visual C++, you can iterate through the Windows collection by using the Item method or _NewEnum property.

When you reference the Windows collection, the reference always reflects the current contents of the collection. For example, suppose you have two macros (A and B). In macro A, you set a global variable to the collection, and in macro B you use the variable. When you use it, the variable will reflect the current contents of the collection — not the contents present when you set the variable.

Using a Dual Interface to Access This Object

This section about dual interfaces is useful for writing add-ins or automating Developer Studio across processes. This section is not applicable to writing VBScript macros.

The Windows object implements the IWindows dual interface. Through this interface, add-ins can directly access the members (properties, methods, and events) of this object and can employ early binding to make calls into these members faster at run time.

Add-ins written in Visual C++ can access members of the Windows object by using the header files in Vc98\Include\objmodel. However, if you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically includes these header files in your source code.

The following table shows the header files you need for the Windows object:

Header file | Description
appauto.h | Declares the dual interfaces.
appguid.h | Declares the GUIDs used to identify the interfaces.
appdefs.h | Declares additional information needed to use the interfaces, such as error IDs and enumerated constants.

Add-ins written in Visual Basic can access members of the Windows object by using the Visual Studio '97 Shared Objects type library, located in Msdev98\bin\devshl.dll.

Note Visual Studio '97 Shared Objects is the name that appears in the Visual Basic References dialog box.


Properties

Home Page (Objects) | Overview | FAQ | Reference

Properties are characteristics of objects. For example, window objects have Height and Width properties. These properties correspond to the height and width of windows.

For more background about properties, see the introduction to properties. And, for examples of using properties, see the macro samples provided with Developer Studio.

The following properties are available:

Property | Description
Active | Gets or sets whether Developer Studio, a document, or a window is active.
ActiveConfiguration | Gets or sets the active configuration for a project.
ActiveDocument | Gets the Document or TextDocument object representing the active document.
ActiveProject | Gets or sets the active project in the workspace.
ActiveWindow | Gets the Window object associated with the active window.
Application | Gets the Developer Studio Application object.
BottomLine | Gets the line at the bottom of a selection.
Breakpoints | Gets the Breakpoints object.
Caption | Gets the caption of a window.
Condition | Gets or sets the condition that allows a breakpoint to occur.
Configurations | Gets the Configurations object.
Count | Gets the number of items in a collection.
CurrentColumn | Gets the column where the insertion point is.
CurrentDirectory | Gets or sets the directory used by the Open command on the File menu.
CurrentLine | Gets the line where the insertion point is.
Debugger | Gets the Debugger object.
DefaultRadix | Gets or sets the default radix (number base) used by the debugger.
Documents | Gets the Documents object.
Elements | Gets the range of memory specifying when a data breakpoint occurred.
Emulation | Gets or sets the emulation mode of the Developer Studio editor.
Enabled | Gets or sets whether a breakpoint is enabled.
Errors | Gets the number of errors that occurred during the last build.
Executable | Gets the description of the .exe or .dll in which a breakpoint is set.
File | Gets the name of the file in which a breakpoint is set.
FullName | Gets the full path.
Function | Gets the name of the function in which a breakpoint is set.
Height | Gets or sets the height of a window in pixels.
IndentSize | Gets or sets the number of columns in one indent.
Index | Gets the one-based ordinal of a window in the Windows collection obtained by using the Windows property of the Application object.
JustInTimeDebugging | Gets or sets whether just-in-time debugging is available.
Language | Gets or sets the programming language used to check the syntax of the language in a document.
Left | Gets or sets the x-coordinate of a window's left edge in pixels.
Location | Gets the location of a breakpoint.
Message | Gets the Windows message that will trigger a breakpoint.
Name | Gets the name of an object.
_NewEnum | References objects in a collection.
Next | Gets the next window in the tab sequence.
Overtype | Gets or sets whether the editor is in overtype mode.
Parent | Gets the parent of an object.
Passcount | Gets the number of times you pass over a breakpoint before triggering it.
Path | Gets the path to an object. This path never ends with a backslash, unless the path has the format "C:\."
Previous | Gets the previous window.
State | Gets the state of the Developer Studio debugger.
Projects | Gets the Projects object.
ReadOnly | Gets or sets whether a document is read-only in Developer Studio.
RemoteProcedureCallDebugging | Gets or sets whether remote procedure call debugging is available.
Saved | Gets a document's saved status, indicating whether a document has changed since it was last saved.
Selection | Gets the TextSelection object, which represents the selected text.
TabSize | Gets or sets the number of columns in a tab character.
Text | Gets or sets the text in a selection.
TextEditor | Gets the TextEditor object.
Top | Gets or sets the y-coordinate of a window's top edge in pixels.
TopLine | Gets the line at the top of a selection.
Type | Returns a string describing the type of breakpoint, document, project, or window.
Version | Gets the version number of Developer Studio.
Visible | Gets or sets whether the Developer Studio main window is visible.
VisibleWhitespace | Gets or sets the visibility of tabs and spaces in all open text documents.
Warnings | Gets the number of warnings that occurred during the last build.
Width | Gets or sets the width of a window in pixels.
WindowProcedure | Gets the name of the Windows procedure that is being monitored for messages that will trigger breakpoints.
Windows | Gets the Windows object.
WindowState | Gets or sets the state of a window.


Active Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Document object, TextDocument object, TextWindow object, Window object

Gets or sets whether Developer Studio, a document, or a window is active.

Syntax

object.Active [=boolean]

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Active property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

boolean

A Boolean that sets the state of the object. Possible values are:

  • True Activates the object.

  • False Deactivates the object.

Return Values

The Active property returns one of the following values:

  • True The object is active.

  • False The object is not active.

Remarks

The Active property has the Boolean type.

Example

The following example browses all open documents for the file MyFile.Cpp. If the file is found, it becomes the active document.

Dim myDocument
For Each myDocument in Application.Documents
   If myDocument.Name = "MyFile.Cpp" Then
      myDocument.Active = True
   End If
Next


ActiveConfiguration Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets or sets the active configuration for a project.

Syntax

object.ActiveConfiguration [=Configuration]

Parameters

object

An expression that evaluates to an Application object. When you access the ActiveConfiguration property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Configuration

An expression that evaluates to a Configuration object.

Remarks

The ActiveConfiguration property has the Configuration type.

The active configuration is the one built when you call the Application object's Build method with no arguments. In the user interface, the active configuration appears in the Active Project Configuration box, and the ActiveConfiguration property gets or sets what is selected in this box.

Example

The following example gets the active configuration for a project:

Dim Config
Set Config = ActiveConfiguration


ActiveDocument Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the Document or TextDocument object representing the active document.

Syntax

object.ActiveDocument

Parameters

object

An expression that evaluates to an Application object. When you access the ActiveDocument property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The ActiveDocument property has the Document type.

The active document is the one edited in the most recently active application document window.

The document retrieved is a Document object or a TextDocument object. The type of object depends on the type of document.

Example

The following example, comments out the selected text in the active document:

ActiveDocument.Selection = "/*" + ActiveDocument.Selection + "*/"


ActiveProject Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets or sets the active project in the workspace.

Syntax

object.ActiveProject [=Project]

Parameters

object

An expression that evaluates to an Application object. When you access the ActiveProject property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Project

An expression that evalutates to a Project object.

Remarks

The ActiveProject property has the Project type.

Example

The following example sets the active project in a workspace:

set ActiveProject  = Projects("someproject")


ActiveWindow Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Document object, TextDocument object

Gets the Window object associated with the active window.

Syntax

object.ActiveWindow

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the ActiveWindow property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The ActiveWindow property has the Window type.

If you access the ActiveWindow property of the Application object, you get the currently active window inside the Developer Studio frame. If you access the ActiveWindow property of the Document or TextDocument object, you get the most recently active window on the document associated with the object.

Example

The following example gets the Window object associated with the active window:

Dim Wnd
Set Wnd = ActiveWindow


Application Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object, Breakpoints object, Configuration object, Configurations object, Debugger object, Document object, Documents object, Project object, Projects object, TextDocument object, TextEditor object, TextSelection object, TextWindow object, Window object, Windows object

Gets the Developer Studio Application object.

Syntax

object.Application

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above.

Remarks

The Application property has the Application type.

The Application object represents the entire Developer Studio application. It provides access to other objects in the Developer Studio object model and provides methods and properties that affect the entire application.

Example

The following example gets the Developer Studio Application object, using the Document object:

Dim App
Set App = Document.Application


BottomLine Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Gets the line at the bottom of a selection.

Syntax

object.BottomLine

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The BottomLine property has the Long type.

The bottom line is not necessarily at the active end of the selection.

Example

The following example gets the line at the end of the selection in the active document:

Dim EndLine
EndLine = ActiveDocument.Selection.BottomLine

See Also CurrentLine property, TopLine property.


Breakpoints Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Gets the Breakpoints object.

Syntax

object.Breakpoints

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

The Breakpoints property has the Breakpoints type.

Example

The following example gets the Breakpoints collection:

Dim bps
set bps = Debugger.Breakpoints


Caption Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextWindow object, Window object

Gets the caption of a window.

Syntax

object.Caption

Parameters

object

An expression that evaluates to a TextWindow object or a Window object.

Remarks

The Caption property has the String type.

Example

The following example gets the caption of the active window:

Dim cap
cap = Activewindow.Caption


Condition Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets or sets the condition that allows a breakpoint to occur.

Syntax

object.Condition [=expression]

Parameters

object

An expression that evaluates to a Breakpoint object.

expression

A String representing the condition you want to set. This condition can be any valid expression. For example, in Visual C++, the expression could be "x == 3" or "a[4]! = 0."

Remarks

The Condition property has the String type and applies only to location or data breakpoints.

You cannot set a condition with the Condition property unless you first set a condition in the Breakpoint dialog box.

Example

The following example sets a condition on the first breakpoint in the Breakpoints collection:

Dim bps
Set bps = Debugger.Breakpoints
bps.Item(1).Condition("var==5")


Configurations Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: BuildProject object, Configuration object

Gets the Configurations object.

Syntax

object.Configurations

Parameters

object

An expression that evaluates to a BuildProject object or a Configuration object.

Remarks

The Configurations property has the Configurations type.

The Configurations object represents the collection of configurations associated with a project.

For BuildProject.Configurations, the Configurations object will contain the list of all configurations on the project.

For Configuration.Configurations, the Configurations object will contain the matching configuration on each dependent project (subproject) of this configuration's project. For example, if the project named "MyMainProj" has dependent projects Sub1 and Sub2, then the Configurations collection on the Debug configuration of MyMainProj will contain the Debug configuration for Sub1 and the Debug configuration for Sub2.

Each configuration in this collection is represented by a Configuration object.

Example

The following example performs a build on each configuration in every build project:

Sub BuildEveryConfiguration
Dim projCol
Dim configCol
Dim numProjects
Dim numConfigs
Dim i
Dim j
set projCol = Projects
numProjects = projCol.Count
For i=1 To numProjects
   Dim proj
   set proj = projCol(i)
   If proj.Type = "Build" Then
      set configCol = proj.Configurations
      numConfigs = configCol.Count
      For j=1 to numConfigs
         Dim config
         set config = configCol(j)
         Build config
      Next
   End If
Next
End Sub


Count Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoints object, Configurations object, Documents object, Projects object, Windows object

Gets the number of items in a collection.

Syntax

object.Count

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above.

Remarks

The Count property has the Long type.

Use the Count property, for example, to get the number of documents in the Documents collection.

Example

The following example prints each document in the Documents collection:

For i = 1 to Documents.Count
   Documents.Item(i).PrintOut
Next


CurrentColumn Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Gets the column where the insertion point is.

Syntax

object.CurrentColumn

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The CurrentColumn property has the Long type.

A selection is a single point (the insertion point) or a contiguous range of text. If the TextSelection object represents a contiguous range of selected text, the CurrentColumn and CurrentLine properties indicate the active end of the selection. This is the point where the user stopped dragging the mouse.

The status bar also shows the location of the insertion point.

Example

The following example gets the number of the column containing the insertion point:

Dim ColNum
ColNum = ActiveDocument.Selection.CurrentColumn


CurrentDirectory Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets or sets the directory used by the Open command on the File menu.

Syntax

object.CurrentDirectory [=string]

Parameters

object

An expression that evaluates to an Application object. When you access the CurrentDirectory property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

string

A String that sets the directory.

Remarks

The CurrentDirectory property has the String type.

The directory name retrieved does not have a trailing backslash.

Example

The following example sets the current directory to C:\Msdev98:

Application.CurrentDirectory = "C:\MSDEV98"


CurrentLine Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Gets the line where the insertion point is.

Syntax

object.CurrentLine

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The CurrentLine property has the Long type.

A selection is a single point (the insertion point) or a contiguous range of text. If the TextSelection object represents a contiguous range of selected text, the CurrentColumn and CurrentLine properties indicate the active end of the selection. This is the point where the user stopped dragging the mouse.

Example

The following example gets the number of the line containing the insertion point:

Dim LineNum
LineNum = ActiveDocument.Selection.CurrentLine


Debugger Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the Debugger object.

Syntax

object.Debugger

Parameters

object

An expression that evaluates to an Application object. When you access the Debugger property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Debugger property has the Debugger type.

Example

The following example gets the Debugger object:

Dim dbg
Set dbg = Application.Debugger


DefaultRadix Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Gets or sets the default radix (number base) used by the debugger.

Syntax

object.DefaultRadix [=radix]

Parameters

object

An expression that evaluates to a Debugger object.

radix

A Long that sets the default radix. Possible values are:

  • 10 Represents base 10 (decimal).

  • 16 Represents base 16 (hexadecimal).

Remarks

The DefaultRadix property has the Long type.

In the Developer Studio user interface, you specify the default radix on the Debug tab of the Options dialog box (Tools menu, Options command).

Example

The following example displays and then sets the default radix to base 10:

PrintToOutputWindow(Debugger.DefaultRadix)
Debugger.DefaultRadix = 10


Documents Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the Documents object.

Syntax

object.Documents

Parameters

object

An expression that evaluates to an Application object. When you access the Documents property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Documents property has the Documents type.

The Documents object represents the collection of open documents. Each document in the collection is represented by a Document object.

Example

The following example gets the Documents object:

Dim Docs
Set Docs = Application.Documents


Elements Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the range of memory specifying when a data breakpoint occurred.

Syntax

object.Elements

Parameters

object

An expression that evaluates to a Breakpoint object.

Remarks

The Elements property has the Long type and applies only to location or data breakpoints.

In the Breakpoints dialog box, you set the value retrieved by this property. For example, you set the memory range or the number of array elements you want to monitor.

Example

The following example gets the range of memory specifying when a data breakpoint occurred:

Dim range
range = Breakpoint.Elements


Emulation Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextEditor object

Gets or sets the emulation mode of the Developer Studio editor.

Syntax

object.Emulation [=mode]

Parameters

object

An expression that evaluates to a TextEditor object.

mode

A Long that sets the emulation mode of the editor. Possible values are:

  • dsDevStudio Developer Studio mode.

  • dsVC2 Visual C++ 2.0 mode.

  • dsBrief BRIEF™ mode.

  • dsEpsilon Epsilon™ mode.

  • dsCustom Custom mode. (This mode represents the current custom emulation.)

Remarks

The Emulation property has the DsEmulation type.

The modes you choose correspond to settings on the Compatibility tab in the Options dialog box (Tools menu, Options command).

Warning If you change emulation modes, you destroy all custom key assignments.

Example

The following example sets the emulation mode to BRIEF:

TextEditor.Emulation = dsBrief


Enabled Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets or sets whether a breakpoint is enabled.

Syntax

object.Enabled [=status]

Parameters

object

An expression that evaluates to a Breakpoint object.

status

A Boolean that enables or disables the breakpoint. Possible values are:

  • True Enables the breakpoint.

  • False Disables the breakpoint.

Remarks

The Enabled property has the Boolean type.

You cannot enable a breakpoint if it is invalid.

Example

The following example enables the first breakpoint in the Breakpoints collection:

Dim bps
Set bps = Debugger.Breakpoints
bps.Item(1).Enabled = True


Errors Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the number of errors that occurred during the last build.

Syntax

object.Errors

Parameters

object

An expression that evaluates to an Application object.

Return Values

The Errors property returns one of the following values:

  • -1 No build has occurred during this session of the IDE.

  • 0 No errors occurred during the last build.

  • 1 or more The number of errors that occurred during the last build, if any errors occurred.

Remarks

The Errors property is set immediately at the end of the build, before the BuildFinish event is fired. The value of the Errors property will match the errors parameter to the BuildFinish event.

Example

The following example reports the number of errors for a build:

if Errors = -1 then
   MsgBox( "No build has occurred yet." )
Else
   if Errors = 0 then
      MsgBox( "The last build was successful." )
   else
      MsgBox( "Errors occurred during the last build." )
   End if
End if

See Also Application::Warnings property, Application::BuildFinish event.


Executable Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the description of the .exe or .dll in which a breakpoint is set.

Syntax

object.Executable

Parameters

object

An expression that evaluates to a Breakpoint object.

Remarks

The Executable property has the String type and applies only to location breakpoints.

The Executable property gets the description that appears in the Breakpoints dialog box. For example, this description might include only the file name, or it might include the full path to the .exe or .dll.

Example

The following example finds the path to the .exe used by the first breakpoint in the Breakpoints collection:

Dim bps
Dim path
Set bps = Debugger.Breakpoints
path = bps.Item(1).Executable


File Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the name of the file in which a breakpoint is set.

Syntax

object.File

Parameters

object

An expression that evaluates to a Breakpoint object.

Remarks

The File property has the String type and applies only to location breakpoints.

The File property gets the file name that appears in the Breakpoints dialog box.

Example

The following example finds the file used by the first breakpoint in the Breakpoints collection:

Dim bps
Dim file
Set bps = Debugger.Breakpoints
file = bps.Item(1).File


FullName Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Document object, TextDocument object, Project object

Gets the full path.

Syntax

object.FullName

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the FullName property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The FullName property has the String type.

The following table summarizes the results of using the FullName property with the objects in the Applies To list:

Object | Results
Application | Gets the full path to the Developer Studio executable, for example: "C:\Program Files\Microsoft Visual Studio\Common\MSDEV98\Bin\MSDev.exe"
Document TextDocument | Gets the full path to the file containing the document, for example: "C:\Mydocuments\Thisdoc.cpp"

Example

The following example displays the full path to each document in the Documents collection:

For i = 1 to Documents.Count
   MsgBox (Documents.Item(i).FullName)
Next

See Also Name property, Path property.


Function Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the name of the function in which a breakpoint is set.

Syntax

object.Function

Parameters

object

An expression that evaluates to a Breakpoint object.

Remarks

The Function property has the String type and applies only to location breakpoints.

The Function property gets the name of the function from the Breakpoints dialog box.

Example

The following example finds the name of the function used by the first breakpoint in the Breakpoints collection:

Dim bps
Dim name
Set bps = Debugger.Breakpoints
name = bps.Item(1).Function

See Also Executable property.


Height Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, TextWindow object, Window object

Gets or sets the height of a window in pixels.

Syntax

object.Height [=value]

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Height property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

value

A Long that sets the height of the window in pixels.

Remarks

The Height property has the Long type.

If object is the Application object, the Height property gets or sets the distance in pixels between the top and bottom edge of the main application window. If object is a Window or TextWindow object, the Height property gets or sets the distance in pixels between the top and bottom edge of that window.

Multiple Document Interface (MDI) child window coordinates are relative to the child window client area. (This area is inside the frame but does not include the docking sites.)

Example

The following example sets the height of the active window to 150 pixels:

ActiveWindow.Height = 150

See Also Left property, Top property, Width property.


IndentSize Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextDocument object

Gets or sets the number of columns in one indent.

Syntax

object.IndentSize [=value]

Parameters

object

An expression that evaluates to a TextDocument object.

value

A Long that sets the value of the IndentSize property.

Remarks

The IndentSize property has the Long type.

When you press TAB, you create an indent equal to the size specified by the IndentSize property. Within that indent are tabs equal to the size specified by the TabSize property.

If the indent size is not a multiple of the tab size, each indent consists of space characters as well as tab characters. For example, if the indent size is seven and the tab size is three, pressing TAB at an indent location inserts two tab characters (each three spaces wide) and one space character (one space wide).

Example

The following example sets the indent size to five columns in the active document:

ActiveDocument.IndentSize = 5

See Also Tabify method, Untabify method.


Index Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextWindow object, Window object

Gets the one-based ordinal of a window in the Windows collection obtained by using the Windows property of the Application object.

Syntax

object.Index

Parameters

object

An expression that evaluates to a TextWindow object or a Window object.

Remarks

The Index property has the Long type.

Windows in the collection accessed by the Windows property of the Application object are ordered by Z-Order. Accordingly, you can use the Index property to determine where a given window lies in the Z-Order of all MDI client windows.

Example

The following example gets the location of the first breakpoint in the Breakpoints collection:

Dim bps
Set bps = Debugger.Breakpoints
bps.Item(1).Location


JustInTimeDebugging Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Gets or sets whether just-in-time debugging is available.

Syntax

object.JustInTimeDebugging [=boolean]

Parameters

object

An expression that evaluates to a Debugger object.

boolean

A Boolean that specifies whether just-in-time debugging is available. Possible values are:

  • True Makes just-in-time debugging available.

  • False Makes just-in-time debugging unavailable.

Remarks

The JustInTimeDebugging property has the Boolean type.

When you make just-in-time debugging available, you also make remote procedure call debugging available. For details, see the RemoteProcedureCallDebugging property.

If just-in-time debugging is not available, and you run a program outside the debugger, if the program fails you can't get help from the debugger. However, if just-in-time debugging is available, the debugger starts immediately.

In the Developer Studio user interface, you enable or disable just-in-time debugging by selecting or clearing the Just-in-time debugging check box on the Debug tab (Tools menu, Options command).

Example

The following example enables just-in-time debugging:

Debugger.JustInTimeDebugging = True


Language Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextDocument object

Gets or sets the programming language used to check the syntax of the language in a document.

Syntax

object.Language [=string]

Parameters

object

An expression that evaluates to a TextDocument object.

string

A string constant of type DsLanguageSettings that specifies the type of language. Possible values are:

  • dsCPP Represents "C/C++."

  • dsFortran_Fixed Represents "Fortran Fixed."

  • dsFortran_Free Represents "Fortran Free."

  • dsHTML_IE3 Represents "HTML IE 3.0."

  • dsHTML_RFC1866 Represents "HTML 2.0, RFC 1866."

  • dsIDL Represents "ODL/IDL."

  • dsVBSMacro Represents "VBS Macro."

Remarks

The Language property has the String type.

Example

The following example sets the programming language used in the active document to C/C++:

ActiveDocument.Language = dsCPP


Left Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, TextWindow object, Window object

Gets or sets the x-coordinate of a window's left edge in pixels.

Syntax

object.Left [=value]

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Left property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

value

A Long that sets the x-coordinate of the window's left edge in pixels.

Remarks

The Left property has the Long type.

If object is the Application object, the Left property gets or sets the distance in pixels between the left edge of the screen and the main application window. If object is a Window object, the Left property gets or sets the distance in pixels between the left edge of the main window and this window.

Note Multiple Document Interface (MDI) child window coordinates are relative to the child window client area. (This area is inside the frame but does not include the docking sites.)

Example

The following example sets the x-coordinate of the active window to 25:

ActiveWindow.Left = 25

See Also Height property, Top property, Width property.


Location Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the location of a breakpoint.

Syntax

object.Location

Parameters

object

An expression that evaluates to a Breakpoint object.

Remarks

The Location property has the String type and applies only to location breakpoints.

The location is a line number (expressed as a string) or the name of a function or symbol.

Example

The following example gets the location of the first breakpoint in the Breakpoints collection:

Dim bps
Set bps = Debugger.Breakpoints
bps.Item(1).Location


Message Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the Windows message that will trigger a breakpoint.

Syntax

object.Message

Parameters

object

An expression that evaluates to a Breakpoint object.

Remarks

The Message property has the DsWindowsMessage type and applies only to message breakpoints.

Example

The following example gets the Windows message that will trigger the first breakpoint in the Breakpoints collection:

Dim bps
Set bps = Debugger.Breakpoints
bps.Item(1).Message


Name Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Configuration object, Document object, Project object, TextDocument object

Gets the name of an object.

Syntax

object.Name

-or-

object

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Name property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods. Additionally, the Name property is the default property of all objects in the Applies To list. Accordingly, you do not have to reference Name explicitly, as shown in the syntax.

Remarks

The Name property has the String type.

The following table summarizes the results of using the Name property with the objects in the Applies To list:

Object | Results
Application | Gets the name of the application.
Configuration | Gets the name of the current configuration, for example "MyProject - Win32 Debug."
Document | Gets the name of the current document, for example "MyFile.cpp."
Project | Gets the name of the current project, for example "MyProject."
TextDocument | Gets the name of the current text document, for example "MyFile.cpp."

The Name property does not get a document's drive and directory. To get the drive and directory, use the Path or FullName property.

Example

The following example gets the name of the active document:

ActiveDocument.Name

See Also FullName property.


_NewEnum Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoints object, Configurations object, Documents object, Projects object, Windows object

References objects in a collection.

Syntax

object._NewEnum

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above.

Remarks

With Visual C++, you can browse a collection to find a particular item by using the _NewEnum property or the Item method. In Visual Basic, you do not need to use the _NewEnum property, because it is automatically used in the implementation of For Each ... Next.

Example

The following example is a Visual C++ code snippet you can insert into an add-in's command handler method using the ActiveX Template Library. This example uses the _NewEnum property to iterate through all open windows and display their captions in the output window.

Tip You can iterate through these windows more efficiently by using the Item method of the Windows object.

CComPtr<IDispatch> pDisp;
   CComQIPtr<IWindows, &IID_IWindows> pWindows;
   m_pApplication->get_Windows(&pDisp);
   pWindows = pDisp;
   pDisp = NULL;
   CComPtr<IUnknown> pUnk;
   CComQIPtr<IEnumVARIANT, &IID_IEnumVARIANT> pNewEnum;
   if (SUCCEEDED(pWindows->get__NewEnum(&pUnk)) && pUnk != NULL)
   {
      pNewEnum = pUnk;
      VARIANT varWindow;
      CComQIPtr<IGenericWindow, &IID_IGenericWindow> pWindow;
while (pNewEnum->Next(1, &varWindow, NULL) == S_OK)
      {
         ASSERT (varWindow.vt == VT_DISPATCH);
         pWindow = varWindow.pdispVal;
         VariantClear(&varWindow);
         CComBSTR bstrCaption;
         pWindow->get_Caption(&bstrCaption);
         m_pApplication->PrintToOutputWindow(bstrCaption);
      }
   }


Next Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextWindow object, Window object

Gets the next window in the tab sequence.

Syntax

object.Next

Parameters

object

An expression that evaluates to a TextWindow object or a Window object.

Remarks

The Next property has the Window type.

Example

The following example gets the next window in the tab sequence:

Dim nxt
set nxt = Window.Next

See Also Previous property.


Overtype Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextEditor object

Gets or sets whether the editor is in overtype mode.

Syntax

object.Overtype [=boolean]

Parameters

object

An expression that evaluates to a TextEditor object.

boolean

A Boolean that sets the Overtype property. Possible values are:

  • True Changes to overtype mode.

  • False Changes to insert mode.

Remarks

The Overtype property has the Boolean type.

By default, the editor is in insert mode.

Example

The following example sets the editor to overtype mode:

TextEditor.Overtype = True

See Also DestructiveInsert method, Indent method, NewLine method, Text property, Unindent method.


Parent Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Breakpoint object, Breakpoints object, Configuration object, Configurations object, Debugger object, Document object, Documents object, Project object, Projects object, TextDocument object, TextEditor object, TextSelection object, TextWindow object, Window object, Windows object

Gets the parent of an object.

Syntax

object.Parent

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Parent property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Parent property's type depends on the object you access the property from (see the table below). For example, the Parent property of the Configuration object has the Project type.

Use the Parent property to access the properties and methods of an object's parent.

The following table shows the parent of each object:

Object | Parent object
Application | Application
Breakpoint | Breakpoints
Breakpoints | Application
Configuration | Project
Configurations | Project
Debugger | Application
Document | Application
Documents | Application
Project | Application
Projects | Application
TextDocument | Application
TextEditor | Application
TextSelection | TextDocument
TextWindow | TextDocument
Window | Document (for "Generic" window types) TextDocument (for "Text" window types)
Windows | Application

If object is a Window object, and this object is associated with a document, then the Parent property gets the corresponding Document object.

For the object hierarchy diagram, see Objects.

Example

The following example gets the parent of the Configurations collection:

Configurations.Parent


Passcount Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the number of times you pass over a breakpoint before triggering it.

Syntax

object.Passcount

Parameters

object

An expression that evaluates to a Breakpoint object.

Remarks

The Passcount property has the Long type.

Example

The following example gets the passcount for the first breakpoint in the Breakpoints collection:

Dim bps
Dim count
Set bps = Debugger.Breakpoints
count = bps.Item(1).Passcount


Path Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Document object, TextDocument object

Gets the path to an object. This path never ends with a backslash, unless the path has the format "C:\."

Syntax

object.Path

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Path property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Path property has the String type.

The Path property does not get an object's file name and extension. To get the file name and extension, use the Name or FullName property.

The following table summarizes the results of using the Path property with the objects in the Applies To list:

Object | Results
Application | Gets the path to the Developer Studio executable, for example: "C:\Program files\Microsoft Visual Studio\Common\MSDEV98\bin."
Document TextDocument | Gets the path to the file containing the document, for example: "C:\Mydocuments."

The Path property does not end the path with a backslash, unless the path has the format "C:\."

Example

The following example gets the path to the active document:

Dim PathString
PathString = ActiveDocument.Path


Previous Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextWindow object, Window object

Gets the previous window.

Syntax

object.Previous

Parameters

object

An expression that evaluates to a TextWindow object or a Window object.

Remarks

The Previous property has the Window type.

The previous window is the one you see when you press CTRL+SHIFT+TAB.

Example

The following example gets the previous window:

Dim prev
Set prev = Window.Previous

See Also Next property.


State Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Gets the state of the Developer Studio debugger.

Syntax

object.State

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

The State property has the DsExecutionState type and gets one of the following values:

  • dsBreak Indicates that the program being debugged is in a paused state.

  • dsNoDebugee Indicates that no program is being debugged.

  • dsRunning Indicates that the program being debugged is running under the debugger.

Example

The following example gets and displays the state of the debugger:

PrintToOutputWindow(Debugger.State)


Projects Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the Projects object.

Syntax

object.Projects

Parameters

object

An expression that evaluates to an Application object. When you access the Projects property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Projects object is a collection object that represents all projects in the currently-open workspace. Each project in this collection is represented by a Project object.

The Projects property gets nothing if there are no open workspaces.

Example

The following example gets the Projects object:

Dim Proj
Set Proj = Application.Projects


ReadOnly Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object

Gets or sets whether a document is read-only in Developer Studio.

Syntax

object.ReadOnly [=boolean]

Parameters

object

An expression that evaluates to a Document object or a TextDocument object.

boolean

A Boolean that sets whether the document is read-only. Possible values are:

  • True Makes the document read-only in Developer Studio.

  • False Makes the document read/write in Developer Studio, but does not change its status on disk. For example, if the document is read-only on disk, it remains read-only.

Return Values

The ReadOnly property returns one of the following values:

  • True The document is read-only.

  • False The document is not read-only.

Remarks

The ReadOnly property has the Boolean type.

Example

The following example makes the active document read-only:

ActiveDocument.ReadOnly = True


RemoteProcedureCallDebugging Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Gets or sets whether remote procedure call debugging is available.

Syntax

object.RemoteProcedureCallDebugging [=boolean]

Parameters

object

An expression that evaluates to a Debugger object.

boolean

A Boolean that specifies whether remote procedure call debugging is available. Possible values are:

  • True Makes remote procedure call debugging available.

  • False Makes remote procedure call debugging unavailable.

Remarks

The RemoteProcedureCallDebugging property has the Boolean type.

In the Developer Studio user interface, you enable or disable remote procedure call debugging by setting or clearing the OLE RPC debugging check box on the Debug tab (Tools menu, Options command).

Remote procedure call debugging requires just-in-time debugging. If you enable remote procedure call debugging, you also enable just-in-time debugging. For details, see the JustInTimeDebugging property. However, if you disable remote procedure call debugging, you do not disable just-in-time debugging.

Example

The following example enables remote procedure call debugging:

Debugger.RemoteProcedureCallDebugging = True


Saved Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object

Gets a document's saved status, indicating whether a document has changed since it was last saved.

Syntax

object.Saved

Parameters

object

An expression that evaluates to a Document object or a TextDocument object.

Remarks

The Saved property has the Boolean type and gets one of the following values:

  • True Indicates that the document has not been changed since it was created or last saved.

  • False Indicates that the document has been changed since it was last saved.

Example

The following example gets the saved status of the active document:

Dim status
status = ActiveDocument.Saved


Selection Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextDocument object, TextWindow object

Gets the TextSelection object, which represents the selected text.

Syntax

object.Selection

Parameters

object

An expression that evaluates to a TextDocument object or a TextWindow object.

Remarks

The Selection property has the TextSelection type.

For the TextDocument object, the Selection property gets the object representing the text selected in a document's active view or in the topmost view if no views are active.

For the TextWindow object, the Selection property gets the object representing the text selected in the text window.

Examples

The following macro converts selected source code into a comment. In this example, note that the Text property is the default; you do not have to specify it.

Sub CommentOutSelection
   MyString = ActiveDocument.Selection.Text
   ActiveDocument.Selection = "/*" + MyString + "*/"
End Sub

The following macro inserts a "#include" statement followed by a line break at the beginning of the active document.

Sub AddWindowsInclude
   ActiveWindow.Selection.StartOfDocument
   ActiveWindow.Selection = "#include <windows.h>"       + vbCrLf
End Sub

For more examples of using the Selection property, see the samples in Sample.dsm, which is in the Developer Studio \Macros directory.


TabSize Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextDocument object

Gets or sets the number of columns in a tab character.

Syntax

object.TabSize [=value]

Parameters

object

An expression that evaluates to a TextDocument object.

value

A Long that represents the number of columns in a tab character.

Remarks

The TabSize property has the Long type.

When you press TAB, you create an indent equal to the size specified by the IndentSize property. Within that indent are tabs equal to the size specified by the TabSize property.

However, if the indent size is not a multiple of the tab size, each indent consists of space characters as well as tab characters. For example, if the indent size is seven and the tab size is three, pressing TAB at an indent location inserts two tab characters (each three spaces wide) and one space character (one space wide).

Example

The following example sets the number of columns in a tab character to 5 in the active document:

ActiveDocument.TabSize = 5

See Also Tabify method, Untabify method.


Text Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Gets or sets the text in a selection.

Syntax

object.Text [=text]

-or-

object [=text]

Parameters

object

An expression that evaluates to a TextSelection object.

text

A String that sets the text in the selection. This string can include one or both of the following values:

  • vbCrLf Represents "\r\n"

  • vbTab Represents "\t"

Remarks

The Text property has the String type.

The Text property is the default property of the TextSelection object. Accordingly, you can reference the TextSelection object without explicitly specifying ".Text," as shown in the syntax.

Note You cannot use the Text property on text in a column selection.

Examples

The following example inserts a tab by using vbTab with the Text property:

Dim Sel
SetSel=ActiveDocument.Selection
Sel.Text=vbTab

Alternatively, you can use the document's Selection property:

Sel=ActiveDocument.Selection
Sel=vbTab

See Also DestructiveInsert method, Indent method, NewLine method, Overtype property, Unindent method.


TextEditor Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the TextEditor object.

Syntax

object.TextEditor

Parameters

object

An expression that evaluates to an Application object. When you access the TextEditor property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The TextEditor property has the TextEditor type.

Example

The following example gets the TextEditor object:

Dim Editorobj
Set Editorobj = Application.TextEditor


Top Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, TextWindow object, Window object

Gets or sets the y-coordinate of a window's top edge in pixels.

Syntax

object.Top [=value]

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Top property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

value

A Long that sets the y-coordinate of the window's top edge in pixels.

Remarks

The Top property has the Long type.

If object is the Application object, the Top property gets or sets the distance in pixels between the top edge of the screen and the main application window. If object is a Window object, the Top property gets or sets the distance in pixels between the top edge of the main application window and this window.

Note Multiple Document Interface (MDI) child window coordinates are relative to the child window client area. (This area is inside the frame but does not include the docking sites.)

Example

The following example sets the top of the active window to 50:

ActiveWindow.Top = 50

See Also Height property, Left property, Width property.


TopLine Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Gets the line at the top of a selection.

Syntax

object.TopLine

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The TopLine property has the Long type.

The top line is not necessarily at the active end of the selection.

Example

The following example gets the line at the beginning of the selection in the active document:

Dim StartLine
StartLine = ActiveDocument.Selection.TopLine

See Also BottomLine property, CurrentLine property.


Type Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object, Document object, Project object, TextDocument object, TextWindow object, Window object

Returns a string describing the type of breakpoint, document, project, or window.

Syntax

object.Type

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above.

Return Values

The following table describes what the Type property returns for each object in the Applies To list:

Object | Type returned | Description
Document TextDocument Window TextWindow | Generic Text | Contains any file other than a text file. Contains a text file.
Project | Build | Represents a project created with Visual C++.
Breakpoint | dsChangedExpression dsLocation dsLocationWithTrueExpression dsLocationWithChangedExpression dsMessage dsTrueExpression |

Remarks

The Type property has the String type for all objects except the Breakpoint object. Used with the Breakpoint object, the Type property is an enum of type DsBreakpointType.

Example

The following example gets the type of the active document:

Dim doctype
doctype = ActiveDocument.Type


Version Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the version number of Developer Studio.

Syntax

object.Version

Parameters

object

An expression that evaluates to an Application object. When you access the Version property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Version property has the String type, for example "5.0".

Example

The following example gets the version of Developer Studio:

Dim Ver
Ver = Application.Version


Visible Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets or sets whether the Developer Studio main window is visible.

Syntax

object.Visible [=boolean]

Parameters

object

An expression that evaluates to an Application object. When you access the Visible property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

boolean

A Boolean that sets whether the window is visible. Possible values are:

True | Makes the window visible.
False | Makes the window invisible.

Remarks

The Visible property has the Boolean type.

Example

The following example makes the Developer Studio main window visible:

Application.Visible = True


VisibleWhitespace Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextEditor object

Gets or sets the visibility of tabs and spaces in all open text documents.

Syntax

object.VisibleWhitespace [=boolean]

Parameters

object

An expression that evaluates to an TextEditor object.

boolean

A Boolean that sets the visibility of tabs and spaces. Possible values are:

  • True Makes tabs and spaces visible.

  • False Makes tabs and spaces invisible.

Remarks

The VisibleWhitespace property has the Boolean type.

Example

The following example makes tabs and spaces visible in all open text documents:

TextEditor.VisibleWhitespace = True

See Also IndentSize property, Tabify method, TabSize property, Untabify method.


Warnings Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Gets the number of warnings that occurred during the last build.

Syntax

object.Warnings

Parameters

object

An expression that evaluates to an Application object.

Return values

The Warnings property returns one of the following values:

  • –1 No build has occurred during this session of the IDE.

  • 0 No warnings occurred during the last build.

  • 1 or more This many warnings occurred during the last build.

Remarks

The Warnings property is set immediately at the end of the build, before the BuildFinish event is fired. The value of the Warnings property will match the warnings parameter to the BuildFinish event.

Example

The following example tests whether a build has occurred, and displays a message box showing the number of warnings generated during the build:

if Warnings = -1 then
   MsgBox( "No build has occurred yet." )
Else
   if Warnings = 0 then
      MsgBox( "The last build was successful." )
   else
      MsgBox( "Warnings occurred during the last build." )
   End if
End if

See Also Application::Errors property, Application::BuildFinish event.


Width Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, TextWindow object, Window object

Gets or sets the width of a window in pixels.

Syntax

object.Width [=value]

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Width property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

value

A Long that sets the width of the window.

Remarks

The Width property has the Long type.

If object is the Application object, the Width property gets or sets the distance in pixels between the left and right edge of the main application window. If object is a Window object, the Width property gets or sets the distance in pixels between the left and right edge of that window.

Note Floating window coordinates are relative to the upper-left corner of the screen. Docking window coordinates are relative to the upper-left corner of the client area of the application's frame window. Multiple Document Interface (MDI) child window coordinates are relative to the child window client area. (This area is inside the frame but does not include the docking sites.)

Example

The following example gets the width of the active window:

Dim width
width = ActiveWindow.Width

See Also Height property, Left property, Top property.


WindowProcedure Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Gets the name of the Windows procedure that is being monitored for messages that will trigger breakpoints.

Syntax

object.WindowProcedure

Parameters

object

An expression that evaluates to an Breakpoint object.

Remarks

The WindowProcedure property has the String type and applies only to message breakpoints.

Example

The following example gets the name of the window procedure associated with the first breakpoint in the Breakpoints collection:

Dim bps
Dim win_name
Set bps = Debugger.Breakpoints
win_name = bps.Item(1).WindowProcedure


Windows Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Document object, TextDocument object

Gets the Windows object.

Syntax

object.Windows

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above. When you access the Windows property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Windows property has the Windows type.

The Windows object is a collection object that represents all open windows associated with an object in the Applies To list. Each window in this collection is represented by a Window object.

The Windows property produces the following results for the objects in the Applies To list:

Object | Results
Application | Gets the collection of all open windows
Document | Gets the collection of all windows open on this document. Text documents are the only types of documents that can have multiple windows. If you try to use this property on a window that is not a text window, you will get a Windows collection containing only one Window object.
TextDocument | Gets the collection of all windows open on this text document.

Example

The following example gets the collection of all open windows:

Dim Allwin
Set Allwin = Application.Windows


WindowState Property

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object, Window object

Gets or sets the state of a window.

Syntax

object.WindowState [=state]

Parameters

object

An expression that evaluates to an Application object or a Window object. When you access the WindowState property of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

state

A Long of type DsWindowState that sets the state of the window. Possible values are:

  • dsWindowStateMaximized Maximizes the window.

  • dsWindowStateMinimized Minimizes the window.

  • dsWindowStateNormal Makes the window a MDI child window.

Remarks

The WindowState property has the type DsWindowState.

Example

The following example maximizes the active window:

ActiveWindow.WindowState = dsWindowStateMaximized


Methods

Home Page (Objects) | Overview | FAQ | Reference

Methods are actions you take against objects. For example, to add a document to the collection of open documents, you use the Add method of the Documents object.

For more background information about methods, see Applying Methods to Developer Studio Objects.

For examples of using methods, see the macro samples provided with Developer Studio.

The following methods are available:

Method | Description
Add | Creates a document of a specified type.
AddBreakpointAtLine | Adds an unconditional location breakpoint to a line.
AddCommand | Adds a command defined by an add-in to Developer Studio.
AddCommandBarButton | Creates a toolbar and toolbar buttons for an add-in.
AddConfiguration | Adds a configuration to the project.
AddCustomBuildStep | Adds a custom build step to a specified configuration.
AddCustomBuildStepToFile | Adds a custom build step to a specified file.
AddFile | Adds a file to the project.
AddFileSettings | Changes the settings of a specified file.
AddKeyBinding | Binds one or more keystrokes to a command.
AddProject | Creates a new project and adds it to the workspace.
AddToolSettings | Changes the settings of a specified tool, such as the Visual C++ compiler.
Arrange | Tiles, maximizes, or minimizes all open windows.
Backspace | Performs the function of the BACKSPACE key.
Build | Builds a specified configuration by processing only the files that have changed.
Cancel | Cancels a selection.
ChangeCase | Changes the case of a selection.
CharLeft | Moves the insertion point one character to the left.
CharRight | Moves the insertion point one character to the right.
Clean | Cleans a specified configuration by deleting all intermediate and output files generated by the configuration.
ClearBookmark | Removes all unnamed bookmarks on the current line.
ClearBookmarks | Removes all unnamed bookmarks in a document.
Close | Closes windows.
CloseAll | Closes all windows or documents.
Copy | Copies the selected text to the Clipboard.
Cut | Removes the selected text and adds it to the Clipboard.
Delete | Performs the function of the DELETE key.
DeleteWhitespace | Deletes white space adjacent to the insertion point.
DestructiveInsert | Inserts text in Overtype mode.
EnableModeless | Enables or disables existing modeless windows in Developer Studio.
EndOfDocument | Moves the insertion point to the end of the document.
EndOfLine | Moves the insertion point to the end of the last line in a selection.
Evaluate | Evaluates an expression, as if you typed it in the Visual C++ debugger's Watch window.
ExecuteCommand | Executes a specified command or VBScript macro.
ExecuteConfiguration | Runs the program in the current workspace.
FindText | Starting after the current selection, FindText searches the rest of a document for a specified string. If the string is found, FindText moves the selection to that string.
GetPackageExtension | Provides access to objects from third parties or other Microsoft products that extend the Developer Studio object model.
Go | Runs the current program under the debugger.
GoToLine | Moves the insertion point to a specified line in a document.
Indent | Indents text.
Item | Gets a specified breakpoint, configuration, document, project, or window from a collection.
LineDown | Moves the insertion point down one line.
LineUp | Moves the insertion point up one line.
MakeCurrentSettingsDefault | Changes the default settings for this configuration to the values of the current settings.
MarkText | Searches a document for a specified string. If the string is found, the MarkText method marks the lines containing the string with unnamed temporary bookmarks.
MoveTo | Moves the insertion point to a specified line and column.
NewLine | Creates a new line.
NewWindow | Creates a new window for a document.
NextBookmark | Moves the insertion point to the next unnamed bookmark in a document.
Open | Opens a document with a specified file name.
PageDown | Moves the insertion point down one page.
PageUp | Moves the insertion point up one page.
Paste | Replaces a selection with the contents of the Clipboard.
PreviousBookmark | Moves the insertion point to the previous unnamed bookmark in a document.
PrintOut | Sends a document to the current printer.
PrintToOutputWindow | Directs the output from a macro to the Macro tab of the Output window.
Quit | Quits Developer Studio.
RebuildAll | Rebuilds a specified configuration by processing all files in the configuration, whether or not the files have changed.
Redo | Reapplies previous editing actions that have been undone.
Remove | Removes a breakpoint from the Breakpoints collection.
RemoveAllBreakpoints | Removes all breakpoints in the Breakpoints collection.
RemoveBreakpointAtLine | Removes all breakpoints on a line.
RemoveFileSettings | Removes the settings of a specified file.
RemoveToolSettings | Removes the settings of a specified tool, such as the VC++ compiler.
ReplaceText | Replaces all instances of a string or regular expression with another string or regular expression.
Restart | Restarts a program that is being debugged.
RunToCursor | In a program you are debugging, sets a temporary breakpoint at the cursor (insertion point) and then starts execution of the program.
Save | Saves a document to a file.
SaveAll | Saves all open documents in the collection.
SelectAll | Extends the selection to include the entire document.
SelectLine | Selects the line defined by the CurrentLine property.
SetAddInInfo | Provides Developer Studio with information about an add-in, when the add-in is loaded. The add-in calls SetAddInInfo.
SetBookmark | Sets an unnamed bookmark at the active end of a selection.
SetNextStatement | Specifies the next statement to execute in a program that you are debugging.
ShowCurrentStatement | In a program you are debugging, moves the insertion point to the line containing the current instruction.
SmartFormat | Formats text in a selection according to the current smart formatting settings.
StartOfDocument | Moves the insertion point to the beginning of the document.
StartOfLine | Moves the insertion point to the beginning of a line.
StepInto | Steps into a called function, executing each instruction step by step.
StepOut | Stops stepping through a called function, executes the remainder of the function, exits the function, and then breaks at the statement after the function call.
StepOver | Executes a called function without stepping through it.
Stop | Stops execution of a program you are debugging.
Tabify | Converts spaces to tabs in a selection.
Undo | Reverses previous editing actions on a document.
Unindent | Removes one indent from all lines in a selection.
Untabify | Converts tabs to spaces in a selection.
WordLeft | Moves the insertion point one word to the left.
WordRight | Moves the insertion point one word to the right.


Add Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Documents object

Creates a document of a specified type.

Syntax

object.Add type

Parameters

object

An expression that evaluates to a Documents object.

type

A String that represents the type of document you want to create. This type is defined by the Type property.

Example

The following example adds a document to the Documents collection:

Documents.Add


AddBreakpointAtLine Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoints object

Adds an unconditional location breakpoint to a line.

Syntax

object.AddBreakpointAtLine ( [line_number] )

Parameters

object

An expression that evaluates to a Breakpoints object.

line_number

(Optional) A Long representing the line to which you will add the breakpoint. The default is the current line in the active text document.

Return Values

The AddBreakpointAtLine method returns the Breakpoint object representing the breakpoint added:

Example

The following example adds a breakpoint at line 10:

Dim bps
Set bps = Debugger.Breakpoints
bps.AddBreakpointAtLine(10)


AddCommand Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Adds a command defined by an add-in to Developer Studio.

Syntax

object.AddCommand ( command_string, method_name, bitmap_offset, cookie )

Parameters

object

An expression that evaluates to an Application object. When you use the AddCommand method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

command_string

A String that contains substrings separated by a newline character ('\n'), which is "Chr(10)" in Visual Basic. In order, the substrings are:

  • Name of the command

    This is the command you want to add. If this command conflicts with an existing command, Developer Studio returns False, keeps the existing command, and does not add this command. To prevent conflicts with Developer Studio commands, the add-in should prefix this command with the name of the add-in.

  • Text displayed on the toolbar button for the command

    If you create a toolbar button for carrying out the command, this is the text that goes on the button.

  • Status bar string

    This is the string displayed on the status bar or in the Customize dialog box when the user selects this command.

  • Tooltip string

    This is the string displayed in the tooltip when the user holds the mouse pointer over the toolbar button assigned to the command.

    Note Even if the add-in does not provide a toolbar button for a command, the add-in must provide all four substrings, because users can create toolbar buttons for commands added by add-ins.

method_name

A String that represents the method exposed by the add-in to implement the command.

bitmap_offset

A Long that is the zero - based index into the medium and large command bar button bitmaps for this button image. For example, 0 (zero) represents the first image, 1 represents the second image, and so on. If the add-in does not provide a default image for toolbar buttons assigned to this command, the value of bitmap_offset is -1.

cookie

A Long that is the identifier of the add-in. Developer Studio passes this value to the add-in through the add-in's OnConnection method.

Return Values

The AddCommand method returns one of the following values:

  • True The command was added.

  • False The command was not added because its name conflicted with the name of an existing command.

Remarks

Only add-ins can call the AddCommand method. VBScript macros cannot.

Example

The following example, written in Visual C++, is the code automatically generated when you create an add-in using the Developer Studio Add-in Wizard:

VARIANT_BOOL bRet;
pApplication->AddCommand(bszCmdString, bszMethod, 0, m_dwCookie, &bRet);
if (bRet == VARIANT_FALSE)
{
   *OnConnection = VARIANT_FALSE;
   return S_OK;
}

See Also AddcommandBarButton method, AddKeyBinding method, Adding Commands to Developer Studio, EnableModeless method, SetAddInInfo method.


AddCommandBarButton Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Creates a toolbar and toolbar buttons for an add-in.

Syntax

object.AddCommandBarButton button_type, command_name, cookie

Parameters

object

An expression that evaluates to an Application object. When you use the AddCommandBarButton method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

button_type

A Long representing the button type. Possible values are:

  • dsGlyph Requires that the button display only an image. (The button looks like a standard toolbar button.)

  • dsText Requires that the button display only button text. (The button looks like a menu such as "File" or "Edit.")

command_name

A String containing the name of the command the button will carry out. This name must match the name added by the AddCommand method.

cookie

A Long representing the identifier of the add-in. Developer Studio passed this value to the add-in through the add-in's OnConnection method.

Remarks

Only add-ins can call the AddCommandBarButton method. VBSscript macros cannot.

Example

The following example, which is written in Visual C++, is the code automatically generated when you create an add-in using the Developer Studio Add-in Wizard:

if (bFirstTime == VARIANT_TRUE)
{
   VERIFY(SUCCEEDED(pApplication->
      AddCommandBarButton(dsGlyph, bszCmdName, m_dwCookie)));
}

See Also AddCommand method, Adding Commands to Developer Studio, AddKeyBinding method, EnableModeless method, SetAddInInfo method.


AddConfiguration Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: BuildProject object

Adds a configuration to the project.

Syntax

object.AddConfiguration name

Parameters

object

An expression that evaluates to a BuildProject object.

name

A String that contains the name of the new configuration.

Example

The following example adds a configuration to a project:

Sub AddMyFile
If Projects(1).Type = "Build" Then
   Projects(1).AddConfiguration "Profile"
End If
End Sub


AddCustomBuildStep Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Configuration object

Adds a custom build step to a specified configuration.

Syntax

object.AddCustomBuildStep ( command, output, description )

Parameters

object

An expression that evaluates to a Configuration object.

command

A String containing commands that you want to execute after building the specified configuration. These commands correspond to those in the Build Commands(s) list on the Custom Build tab of the Project Settings dialog box (Project menu, Settings command) and are separated by commas.

output

A String specifying the files you want to create from this custom build step. These files correspond to those in the Outputs list on the Custom Build tab of the Project Settings dialog box (Project menu, Settings command). Each file name is separated by a newline character. (In VBScript use Chr(10) to represent a newline character.)

description

A String describing the purpose of this build step. This corresponds to the Description box on the Custom Build tab of the Project Settings dialog box (Project menu, Settings command) .

Remarks

The AddCustomBuildStep method runs after the specified configuration is built and applies to the entire configuration, not to a single file in the configuration.

Tip If you have a makefile project, you can also use this method to set the command line. If you are using this approach and you specify more than one command line or more than one output file, then only the first will be used. When using AddCustomBuildStep() on a makefile project, "command" becomes the command, "output" becomes the output, and "description" becomes the "rebuild all option."

Example

The following example includes a build step that copies an executable from a project's configuration to a specified directory after the executable is built:

Sub AddTargetCopyRule
If Projects(1).Type = "Build" Then
   Projects(1).Configurations(1).AddCustomBuildStep "copy ""$(TargetPath)"" ""c:\MyOutDir""", _
       "c:\MyOutDir\$(TargetName).exe", "Copy executable to c:\MyOutDir"
End If
End Sub


AddCustomBuildStepToFile Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Configuration object

Adds a custom build step to a specified file.

Syntax

object.AddCustomBuildStepToFile ( file, command, output, description )

Parameters

object

An expression that evaluates to a Configuration object.

file

A String containing the file name to which you want to add the custom build step.

command

A String containing commands that you want to execute when the given file is out of date with respect to its output. These commands correspond to those in the Commands list in the Custom Build tab and are separated by a newline character. (To get to the Custom Build tab, choose Project: Settings and click the right-arrow.)

output

A String specifying the files you want to create from this custom build step. These files correspond to those in the Outputs list in the Custom Build tab of the Project Settings dialog box, and each file name is separated by a newline character. (In VBScript use Chr(10) to represent a newline character.)

description

A String describing the purpose of the custom build step. This corresponds to the Description box on the Custom Build tab of the Project Settings dialog box (Project menu, Settings command).

Example

The following example adds a custom build step to the readme.txt file in every project in the workspace. In this example, the custom build step makes a copy of the file:

for each proj in Application.Projects
   for each cfg in proj.Configurations
      cfg.AddCustomBuildStepToFile "ReadMe.txt", "copy ReadMe.txt read.doc", "read.doc", "make this easier to open in word"
   next
next


AddFile Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: BuildProject object

Adds a file to the project.

Syntax

object.AddFile file

Parameters

object

An expression that evaluates to a BuildProject object.

file

A String that contains the name of the file.

Example

The following example adds a file to a project:

Sub AddMyFile
If Projects(1).Type = "Build" Then
   Projects(1).AddFile "myfile.cpp"
End If
End Sub


AddFileSettings Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Configuration object

Changes the settings of a specified file.

Syntax

object.AddFileSettings file, settings

Parameters

object

An expression that evaluates to a Configuration object.

file

A String that contains the name of the file whose settings you want to change.

settings

A String that includes the settings or command-line flags you want to add to your project. You can add multiple flags by separating them with spaces. For instance, you can specify "/D_NEW_SYMBOL /J" to add the flags "/D_NEW_SYMBOL" and "/J" to the makefile. If you try to add flags that already exist, Developer Studio will disregard them.

Example

The following example adds a compiler switch to the first configuration of the first project in your workspace:

Sub AddPreprocMacroDefine
If Projects(1).Type = "Build" Then
   Projects(1).Configurations(1).AddFileSettings "myfile.cpp", "/D_DEFINEME"
End If
End Sub

See Also RemoveFileSettings method.


AddKeyBinding Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Binds one or more keystrokes to a command.

Syntax

object.AddKeyBinding key, command, editor

Parameters

object

An expression that evaluates to an Application object. When you use the AddKeyBinding method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

key

A String specifying the keystrokes needed to execute command. This string has the format CTRL+ALT+SHIFT+A, where CTRL, ALT, and SHIFT always appear in this order. If a two-key sequence represents a command, the two keys are separated by a comma, as in CTRL+HOME, S or X, SHIFT+Y.

command

A String specifying the command that key executes.

editor

A String specifying the editor associated with this keybinding. These editors appear on the Keyboard tab of the Customize dialog box (Tools menu, Customize command).

Remarks

If the user removes (uninstalls) an add-in, Developer Studio does not remove keybindings created when the add-in was installed, because the user might have customized these keybindings

Caution Unless keybindings are necessary, do not add them, because they might conflict with existing keybindings — producing unpredictable results for the user.

Example

The following Visual C++ code binds a keystroke to an add-in command:

if (bFirstTime == VARIANT_TRUE)
{
   CComBSTR bszKeystroke("CTRL+4");
   CComBSTR bszEditor("Main");
   VERIFY(SUCCEEDED(pApplication->
      AddKeyBinding(bszKeystroke, bszCmdName,          bszEditor)));
}

See Also AddCommand method, Adding Commands to Developer Studio, AddCommandBarButton method, EnableModeless method, SetAddInInfo method.


AddProject Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Creates a new project and adds it to the workspace.

Syntax

object.AddProject "project name", "project directory", "project type", addfolders

Parameters

object

An expression that evaluates to an Application object.

project name

A String that contains the name of the new project.

project directory

A String that specifies the directory to place this project in.

When your project directory ends with a backslash, you will get a project (.dsp) and workspace (.dsw) both called project name in the directory path you specified.

If you omit the backslash from the project directory but if all subdirectories in the project directory exist, you will get a project (.dsp) and workspace (.dsw) both called project name in the specified directory path.

However, if you omit the final backslash from project directory and if one of the directories in project directory does not exist, then the last subdirectory in the path becomes the workspace (.dsw) name and you get a .dsp file called project name.

project type

A String that specifies the type of the new project. The string must be one of the following:

String | Description
"Application" | A Win32 executable application
"DLL" | A Win32 Dynamic-Link Library
"Console Application" | A Win32 console application
"Static Library" | A Win32 static link library
"Utility" | A utility project
"Makefile" | A makefile project

addfolders

A Variant that is a Boolean. Specifies whether to add the default file folders to the project.

Remarks

Developer Studio creates the project in the workspace directory, unless you specify a path for the first argument. For example, if you specify the path "c:\myproj\myproj.dsp", the project will be placed in the c:\myproj directory for you and will be named "myproj.dsp".

Developer Studio adds debug and release configuration to the project for you.

Example

The following example creates a new project and adds it to the workspace:

Sub AddMyFile
Application.AddProject "MyProj", "c:\myproj", "Console Application", True
End Sub


AddToolSettings Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Configuration object

Changes the settings of a specified tool, such as the Visual C++ compiler.

Syntax

object.AddToolSettings tool, settings

Parameters

object

An expression that evaluates to a Configuration object.

tool

A String that contains the name of the tool whose settings you want to change. For the Visual C++ compiler, specify "cl.exe," and for the linker specify "link.exe."

settings

A String that includes the settings or command-line flags you want to add to your project. These flags apply to all files in the configuration. You can add multiple flags by separating them with spaces. For instance, you can specify "/D_NEW_SYMBOL /J" to add the flags "/D_NEW_SYMBOL" and "/J" to the compiler command line. If you try to add flags that already exist, Developer Studio will disregard them.

Remarks

The functionality of the AddToolSettings method appears in the Project Settings dialog box and on the tabs of each tool, such as the C/C++ and Link tabs.

There is a pseudo-tool, "mfc", which you can use to specify how the MFC libraries are used, by entering a value. These values can be seen in the General tab of the Project Settings dialog box (Project menu, Settings command), in the Microsoft Foundation Classes drop-down list.

Value | How the MFC Libraries Are Used
0 | MFC is not used.
1 | Using MFC in a static library.
2 | Using MFC in a dynamic link library.

Example

The following example adds a preprocessor define, used by the C++ compiler, to the project makefile, which is owned by a specified project and configuration:

Sub AddPreprocMacroDefine
If Projects(1).Type = "Build" Then
   Projects(1).Configurations(1).AddToolSettings "cl.exe", "/D_DEFINEME"
End If
End Sub

See Also RemoveToolSettings method.


Arrange Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Windows object

Tiles, maximizes, or minimizes all open windows.

Syntax

object.Arrange state

Parameters

object

An expression that evaluates to a Windows object.

state

An enum of type DsArrangeStyle that sets the state of the windows. Following are the possible values, which have the Long type:

  • dsCascade Cascades the windows.

  • dsMinimize Minimizes the windows.

  • dsTileHorizontal Tiles the windows horizontally.

  • dsTileVertically Tiles the windows vertically.

Remarks

If you get the collection of windows associated with a document by using the Windows property of the Document object, the Arrange method affects only those windows — not all windows open in Developer Studio.

Example

The following example tiles all open windows horizontally:

Windows.Arrange dsTileHorizontal


Backspace Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Performs the function of the BACKSPACE key.

Syntax

object.Backspace [count]

Parameters

object

An expression that evaluates to a TextSelection object.

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

If the user selects a contiguous range of text, the Backspace method deletes the selection.

Example

If no text is selected, the following example moves the insertion point two columns to the left, deleting the characters in those columns:

ActiveDocument.Selection.Backspace 2


Build Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Builds a specified configuration by processing only the files that have changed.

Syntax

object.Build [configuration]

Parameters

object

An expression that evaluates to an Application object. When you use the Build method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

configuration

(Optional) An object of type Configuration. If this is left off, the active configuration will be cleaned instead.

Remarks

If you do not specify a configuration, Developer Studio builds the default configuration. For example, if you specify Application.Build, Developer Studio builds the default.

To find the appropriate configuration:

  1. Locate the project with that configuration by iterating through the Projects collection, using the Projects property of the Application object.

  2. Locate the appropriate configuration by iterating through the project's Configurations collection, using the Configurations property of the BuildProject object.

Example

The following example iterates through all the configurations on every build project and performs a build on each configuration:

Sub BuildEveryConfiguration
Dim projCol
Dim configCol
Dim numProjects
Dim numConfigs
Dim i
Dim j
set projCol = Projects
numProjects = projCol.Count
For i=1 To numProjects
   Dim proj
   set proj = projCol(i)
   If proj.Type = "Build" Then
      set configCol = proj.Configurations
      numConfigs = configCol.Count
      For j=1 to numConfigs
         Dim config
         set config = configCol(j)
         Build config
      Next
   End If
Next
End Sub

See Also Configuration object, RebuildAll method, Clean method. ActiveConfiguration property.


Cancel Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Cancels a selection.

Syntax

object.Cancel

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

This method has the same effect as pressing the ESC key.

Example

The following example cancels the current selection:

ActiveDocument.Selection.Cancel


ChangeCase Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Changes the case of a selection.

Syntax

object.ChangeCase case

Parameters

object

An expression that evaluates to a TextSelection object.

case

A string constant of type DsCaseOptions that represents the case of the selection. Possible values are:

  • dsLowercase Sets all text to lowercase.

  • dsUppercase Sets all text to uppercase.

  • dsCapitalize Capitalizes the first letter of each word.

Example

The following example changes the case of the current selection to uppercase:

ActiveDocument.Selection.ChangeCase dsUppercase


CharLeft Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point one character to the left.

Syntax

object.CharLeft [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+LEFT ARROW.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

The CharLeft method has the same effect as pressing the LEFT ARROW key.

Example

The following example extends the current selection to the left by two characters:

ActiveDocument.Selection.CharLeft dsExtend 2

See Also CharRight method, WordLeft method, WordRight method.


CharRight Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point one character to the right.

Syntax

object.CharRight [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+RIGHT ARROW.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

The CharRight method has the same effect as pressing the RIGHT ARROW key.

Example

The following example extends the current selection to the right by two characters:

ActiveDocument.Selection.CharRight dsExtend 2

See Also CharLeft method, WordLeft method, WordRight method.


Clean Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Cleans a specified configuration by deleting all intermediate and output files generated by the configuration.

Syntax

object.Clean [configuration]

Parameters

object

An expression that evaluates to an Application object.

configuration

(Optional) A string constant of type Configuration that specifies the configuration to clean. Possible values appear in the Default Project Configuration box. The default value is Nothing.

Remarks

If you do not specify a configuration, Developer Studio cleans the default configuration. For example, if you specify Application.Clean, Developer Studio cleans the default.

To find the appropriate configuration, first locate the project with that configuration by iterating through the Projects collection, using the Projects property of the Application object. Once you find the project, locate the appropriate configuration by iterating through the project's Configurations collection, using the Configurations property of the BuildProject object.

Example

The following example cleans each configuration in every build project:

Sub CleanEveryConfiguration
Dim projCol
Dim configCol
Dim numProjects
Dim numConfigs
Dim i
Dim j
set projCol = Projects
numProjects = projCol.Count
For i=1 To numProjects
   Dim proj
   set proj = projCol(i)
   If proj.Type = "Build" Then
      set configCol = proj.Configurations
      numConfigs = configCol.Count
      For j=1 to numConfigs
         Dim config
         set config = configCol(j)
         Clean config
      Next
   End If
Next
End Sub

See Also Configuration object, Build method, RebuildAll method.


ClearBookmark Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Removes all unnamed bookmarks on the current line.

Syntax

object.ClearBookmark

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The ClearBookmark method does not remove all unnamed bookmarks in a document. To remove all unnamed bookmarks, use the ClearBookmarks method.

Example

The following example removes all unnamed bookmarks on the current line in the current selection:

ActiveDocument.Selection.ClearBookmark

See Also NextBookmark method, PreviousBookmark method, SetBookmark method.


ClearBookmarks Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextDocument object

Removes all unnamed bookmarks in a document.

Syntax

object.ClearBookmarks

Parameters

object

An expression that evaluates to a TextDocument object.

Example

The following example removes all unnamed bookmarks in the current document:

ActiveDocument.ClearBookmarks

See Also NextBookmark method, PreviousBookmark method, SetBookmark method.


Close Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object, TextWindow object, Window object

Closes windows.

Syntax

object.Close ( [SaveChanges] )

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above.

SaveChanges

(Optional) An enum of type DsSaveChanges that indicates whether to save changes to a document before closing it. Following are the possible values, which have the Long type:

  • dsSaveChangesYes Saves all changes and does not prompt the user (the default).

  • dsSaveChangesNo Does not save changes, and does not prompt the user.

  • dsSaveChangesPrompt Prompts the user to save changes. If the user chooses not to save the changes, Close returns the enum dsSaveStatus with the value dsSaveCanceled; otherwise Close returns dsSaveSucceeded.

Return Values

The Close method returns the enum dsSaveStatus, which has one of the following values:

  • dsSaveCanceled Indicates that the user chose not to save changes to the document.

  • dsSaveSucceeded Indicates that the user saved changes to the document.

Remarks

The following table summarizes the results of using Close with objects in the Applies To list:

Object | Results
Document TextDocument | Closes all windows associated with the document and removes them from the Windows collection obtained by using the Windows property of the Application object. Closes the document and removes it from the Documents collection.
TextWindow Window | Closes the window and removes it from the Windows collection obtained by using the Windows property of the Application object. Additionally, if that window was the only one open on a document, then that document is closed and removed from the Documents collection

Example

The following example saves all changes to the current document and then closes all windows in the document:

ActiveDocument.Close


CloseAll Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Documents object, Windows object

Closes all windows or documents.

Syntax

object.CloseAll [SaveChanges]

Parameters

object

An expression that evaluates to a Documents object or a Windows object.

SaveChanges

(Optional) An enum of type DsSaveChanges that indicates whether to save changes to one or more documents before closing them. Following are the possible values, which have the Long type:

  • dsSaveChangesYes Saves the changes (the default).

  • dsSaveChangesNo Does not save the changes.

  • dsSaveChangesPrompt Prompts the user to save changes. If the user chooses not to save the changes, CloseAll returns the enum dsSaveStatus with the value dsSaveCanceled; otherwise CloseAll returns dsSaveSucceeded.

Return Values

The CloseAll method returns the enum dsSaveStatus, which has one of the following values:

  • dsSaveCanceled Indicates that the user chose not to save changes to the document.

  • dsSaveSucceeded Indicates that the user saved changes to the document.

Example

The following example saves the changes to all open documents and then closes those documents:

Documents.CloseAll

See Also Open method.


Copy Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Copies the selected text to the Clipboard.

Syntax

object.Copy

Parameters

object

An expression that evaluates to a TextSelection object.

Example

The following example copies selected text to the Clipboard:

ActiveDocument.Selection.Copy

See Also Cut method, Paste method.


Cut Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Removes the selected text and adds it to the Clipboard.

Syntax

object.Cut

Parameters

object

An expression that evaluates to a TextSelection object.

Example

The following example removes selected text and adds it to the Clipboard:

ActiveDocument.Selection.Cut

See Also Copy method, Paste method.


Delete Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Performs the function of the DELETE key.

Syntax

object.Delete [count]

Parameters

object

An expression that evaluates to a TextSelection object.

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

If no selection exists, the Delete method deletes the first character to the right of the insertion point.

Example

For the current selection, the following example deletes the selection:

ActiveDocument.Selection.Delete

See Also Cut method, DeleteWhitespace method.


DeleteWhitespace Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Deletes white space adjacent to the insertion point.

Syntax

object.DeleteWhitespace [direction]

Parameters

object

An expression that evaluates to a TextSelection object.

direction

(Optional) A string constant of type DsWhitespaceOptions that indicates the direction in which the white space is deleted. Possible values are:

  • dsHorizontal Removes white space to the left and right of the insertion point (the default).

  • dsVertical Removes blank lines at, above, or below the insertion point.

Remarks

White space includes spaces and tab characters.

Example

For the current selection, the following example deletes whitespace to the left and right of the insertion point:

ActiveDocument.Selection.DeleteWhitespace

See Also Cut method, Delete method.


DestructiveInsert Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Inserts text in Overtype mode.

Syntax

object.DestructiveInsert text

Parameters

object

An expression that evaluates to a TextSelection object.

text

A String that specifies the text you want to insert.

Remarks

For each character in text, the DestructiveInsert method deletes a character to the right of the insertion point. However, the DestructiveInsert method ignores Tab characters and newline characters in text.

Example

For the current selection, the following example inserts the text "/* */" in overtype mode:

ActiveDocument.Selection.DestructveInsert "/*  */"

See Also Indent method, NewLine method, Overtype property, Type property, Unindent method.


EnableModeless Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Enables or disables existing modeless windows in Developer Studio.

Syntax

object.EnableModeless boolean

Parameters

object

An expression that evaluates to an Application object. When you use the EnableModeless method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

boolean

A Boolean that specifies whether Developer Studio should enable or disable its modeless windows. Possible values are:

  • True Enables all modeless windows, returning Developer Studio to its normal state. Use this after an add-in has dismissed its modal dialog box.

  • False Disables all modeless windows. Use this before an add-in displays a modal dialog box.

Remarks

Add-ins typically use EnableModeless to disable modeless windows before displaying a modal dialog so that the user cannot click the windows while the dialog is showing.

Example

The following example reports a date:

EnableModeless False
MsgBox "The current date is " & Date
EnableModeless True

See Also AddCommand method, AddCommandBarButton method, AddKeybinding method, SetAddInInfo method.


EndOfDocument Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to the end of the document.

Syntax

object.EndOfDocument [extend]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection. This is the same as pressing CTRL+SHIFT+END.

  • dsMove Does not extend the selection (the default).

Remarks

The EndOfDocument method has the same effect as pressing CTRL+END.

Example

The following example moves the insertion point to the end of the current document:

ActiveDocument.Selection.EndOfDocument

See Also StartOfDocument method.


EndOfLine Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to the end of the last line in a selection.

Syntax

object.EndOfLine [extend]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+END.

  • dsMove Does not extend the selection (the default).

Remarks

The EndOfLine method has the same effect as pressing the END key.

Example

For the current selection, the following example moves the insertion point to the end of the last line in the selection:

ActiveDocument.Selection.EndOfLine

See Also StartOfLine method.


Evaluate Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Evaluates an expression, as if you typed it in the Visual C++ debugger's Watch window.

Syntax

object.Evaluate ( expression )

Parameters

object

An expression that evaluates to a Debugger object.

expression

A String that represents the expression you want to evaluate.

Return Values

The Evaluate method returns a String containing the results of expression. For example, Debugger.Evaluate "2+2" returns "4" — not the number 4.

Example

The following example displays and then sets the value of an expression:

PrintToOutputWindow(Debugger.Evaluate("var"))
Debugger.Evaluate ("var=1")


ExecuteCommand Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Executes a specified command or VBScript macro.

Syntax

object.ExecuteCommand command

Parameters

object

An expression that evaluates to an Application object. When you use the ExecuteCommand method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

command

A String that represents the command or macro you want to execute.

Remarks

You can use the ExecuteCommand method to run commands or macros listed on the Keyboard tab of the Customize dialog box (Tools menu, Customize command).

You can also use commands or macros by running them from the command line or by pressing toolbar buttons or keystrokes associated with them.

Example

The following example executes the AddRevisionMarks macro in Program Files\Microsoft Visual Studio\Common\MSDEV98\Macros\Sample.dsm:

ExecuteCommand AddRevisionMarks


ExecuteConfiguration Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Runs the program in the current workspace.

Syntax

object.ExecuteConfiguration

Parameters

object

An expression that evaluates to an Application object. When you use the ExecuteConfiguration method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

If you run a program outside the debugger, you cannot set breakpoints or evaluate symbols for the program from within the debugger.

Example

The following example runs the program in the current workspace:

ExecuteConfiguration


FindText Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Starting after the current selection, FindText searches the rest of a document for a specified string. If the string is found, FindText moves the selection to that string.

Syntax

object.FindText ( string [, flags] )

Parameters

object

An expression that evaluates to a TextSelection object.

string

A String that represents the string you want to find.

flags

(Optional) A string constant of type DsTextSearchOptions that determines how to conduct the search. To perform complex searches, you can combine values. The values you can use singly or in combination are:

  • dsMatchForward Starts a forward search. This is the default.

  • dsMatchBackward Starts a backward search.

  • dsMatchFromStart Starts a search from the beginning or end of the document. If you specify a forwards search (dsMatchForward), the search starts from the beginning of the document. Alternatively, if you specify a backwards search (dsMatchBackward), the search starts from the end of the document.

  • dsMatchWord Requires that whole words match.

  • dsMatchCase Requires a case-sensitive match.

  • dsMatchRegExp Requires a match with Developer Studio regular expressions.

  • dsMatchNoRegExp Does not require a match with Developer Studio regular expressions. This is the default.

  • dsMatchRegExpB Requires a match with BRIEF® regular expressions.

  • dsMatchRegExpE Requires a match with Epsilon™ regular expressions.

  • dsMatchRegExpCur Requires a match using the current regular expression setting.

Return Values

The FindText method returns one of the following values:

  • True If the search is successful.

  • False If the search is not successful.

Remarks

You can combine values in the flags parameter by using the Or (or) or Concatenation (+) operators. For example, to conduct a case-sensitive forward search, you could specify dsMatchForward or dsMatchCase or dsMatchForward + dsMatchCase. However, you can use only one of the regular expression values at a time. For example, you cannot combine dsMatchRegExpCur with dsMatchRegExpE.

Example

The following example conducts a case-sensitive search for the word "main":

Sub FindMain
   ActiveDocument.Selection.FindText    "main",dsMatchCase + dsMatchWord
End Sub

See Also MarkText method, ReplaceText method.


GetPackageExtension Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object.

Provides access to objects from third parties or other Microsoft products that extend the Developer Studio object model.

Syntax

object.GetPackageExtension ( extension )

Parameters

object

An expression that evaluates to an Application object. When you use the GetPackageExtension method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

extension

A String that specifies an object provided by a third party or other Microsoft product.

Return Values

The GetPackageExtension method returns the specified object.


Go Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Runs the current program under the debugger.

Syntax

object.Go

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

If the program is already running under the debugger and is in break mode, then the program resumes executing.

If you call the Go method in code for the BreakpointHit event, Developer Studio temporarily defers the call, executes the remaining instructions in the event code, and then executes the Go method when the event exits.

When you call the Go method, it performs asynchronously. This means that Go returns immediately, while the debugger starts or continues the debugging session.

Example

The following example performs the Go method:

Debugger.Go


GoToLine Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to a specified line in a document.

Syntax

object.GoToLine line [, select ]

Parameters

object

An expression that evaluates to a TextSelection object.

line

A Long that represents the number of the line to which you want to go. If you specify dsLastLine or if line is beyond the last line in the document, the last line is chosen.

select

(Optional) A string constant of type DsGoToLineOptions that indicates how to select the line to which you want to go. Possible values are:

  • dsSelect Selects the entire line.

  • dsMove Moves the insertion point to the beginning of the line, but does not select any part of the line (the default).

Example

The following example moves the insertion point to the third line in a document and selects the entire line:

ActiveDocument.Selection.GoToLine 3 dsSelect


Indent Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Indents text.

Syntax

object.Indent

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The Indent method has the same effect as pressing the TAB key.

This method indents by the number specified in the IndentSize property. The indent can consist of multiple tab characters, depending on the values of the TabSize property and IndentSize property.

Caution If text is selected, the Indent method deletes the selection.

You can insert a tab by using the vbTab string constant. Consider the following code:

Dim Sel
Sel=ActiveDocument.Selection
Sel=vbTab

Alternatively, you could use the TextSelection object's Text property, which is the default:

Sel.Text=vbTab

Example

The following example inserts one indent at the insertion point:

ActiveDocument.Selection.Indent

See Also DestructiveInsert method, NewLine method, Overtype property, Text property, Unindent method.


Item Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoints object, Configurations object, Documents object, Projects object, Windows object

Gets a specified breakpoint, configuration, document, project, or window from a collection.

Syntax

object.Item [index]

-or-

object index

Parameters

object

An expression that evaluates to one of the objects in the Applies To list above.

index

A Variant that is a Long or String representing the appropriate breakpoint, configuration, document, project, or window.

  • If you specify a Long, the Item method fetches the object by its one-based index in the collection.

  • If you specify a String, it must be one of the strings described in the following table:
Object | String
Configuration | The configuration's name (as defined by the Name property).
Document | The document's file name (as defined by the Type property). For the file name, specify the full path to the file. If you specify only the file name, Developer Studio tries to find an open document with that name. However, if more than one open document has that name, the Item method gets the document from the current directory. If none of the open documents are in the current directory, the Item method chooses one arbitrarily. If you specify a relative path, Developer Studio bases the path on the current directory.
Project | The project's name (as defined by the Name property).
Window | The window's caption (as defined by the Caption property).

Remarks

If you specify numbers for index, do not store these for later use because the indices might change as documents or windows are added or removed.

The Item method is the default. Accordingly, you don't have to reference Item explicitly, as shown in the syntax.

Example

The following example prints all open documents:

Sub PrintAllOpenDocuments( )
   for num = 1 to Documents.Count
      Documents(num).PrintOut
   next
End Sub


LineDown Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point down one line.

Syntax

object.LineDown [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+DOWN ARROW.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Example

The following example moves the insertion point down one line and extends the selection:

ActiveDocument.Selection.LineDown dsExtend

See Also LineUp method.


LineUp Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point up one line.

Syntax

object.LineUp [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+UP ARROW.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Example

The following example moves the insertion point up one line and extends the selection:

ActiveDocument.Selection.LineUp dsExtend

See Also LineDown method.


MakeCurrentSettingsDefault Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Configuration object

Changes the default settings for this configuration to the values of the current settings.

Syntax

object.MakeCurrentSettingsDefault

Parameters

object

An expression that evaluates to a Configuration object.

Remarks

The default settings for a project are initially set up by the AppWizard with which you created your project. This method allows you to change those defaults by applying settings changes to a configuration and then calling this method. To restore settings to the default values (the values you defined as the defaults), the user can click the Reset button in the Project Settings dialog box.

Tip This method is particularly useful in writing Custom AppWizards.

Example

The following example adds the /WX switch as a default setting for every project in the workspace:

for each proj in Application.Projects
   for each cfg in proj.Configurations
      cfg.AddToolSettings "cl.exe", "/WX"
      cfg.MakeCurrentSettingsDefault
   next
next


MarkText Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextDocument object

Searches a document for a specified string. If the string is found, the MarkText method marks the lines containing the string with unnamed temporary bookmarks.

Syntax

object.MarkText ( string [, flags] )

Parameters

object

An expression that evaluates to a TextDocument object.

string

A String that is the string you want to find.

flags

(Optional) A Long that determines how to conduct the search. To perform complex searches, you can combine values. The values you can use singly or in combination are:

  • dsMatchWord Requires that whole words match.

  • dsMatchCase Requires a case-sensitive match.

  • dsMatchPlain Does not use regular expressions (the default).

  • dsMatchRegExp Requires a match with Developer Studio regular expressions.

  • dsMatchRegExpB Requires a match with BRIEF® regular expressions.

  • dsMatchRegExpE Requires a match with Epsilon™ regular expressions.

  • dsMatchRegExpCur Requires a match using the current regular expression setting.

Return Values

The MarkText method returns one of the following values:

  • True If the search is successful.

  • False If the search is not successful.

Remarks

You can combine values in the flags parameter by using the or or + operator. For example, to conduct a case-sensitive forward search, you could specify dsMatchForward or dsMatchCase or dsMatchForward + dsMatchCase. However, you can use only one of the regular expression values at a time. For example, you cannot combine dsMatchRegExpCur with dsMatchRegExpE.

You can move from bookmark to bookmark in a document. First, press CTRL+F2 so that you can move forward or backward. Then, press F2 to move forward, or press SHIFT+F2 to move backward.

Example

The following example conducts a case-sensitive search of the current selection to find the text "TODO" and then marks the lines containing this text with unnamed temporary bookmarks:

Sub MarkMain
   ActiveDocument.Selection.MarkText "TODO",    dsMatchCase
End Sub

See Also FindText method, ReplaceText method.


MoveTo Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to a specified line and column.

Syntax

object.MoveTo line, column [,extend]

Parameters

object

An expression that evaluates to a TextSelection object.

line

A Long specifying the line number . Some possible values are:

  • 0 Does not move the insertion point; it stays on the current line.

  • 1 Moves the insertion point to the first line.

  • dsLastLine Moves the insertion point to the last line in the file.

column

A Long specifying the column number. If this number is greater than the number of the rightmost column, this number becomes the number of the rightmost column. Some possible values are:

  • 0 Does not move the insertion point; it stays in the current column.

  • 1 Moves the insertion point to the first column.

  • dsEndOfLine Moves the insertion point to the end of the line.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+UP ARROW.

  • dsMove Does not extend the selection (the default).

Example

The following example moves the insertion point to the third column in the second line:

ActiveDocument.Selection.MoveTo 2 3

See Also LineDown method.


NewLine Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Creates a new line.

Syntax

object.NewLine

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The NewLine method has the same effect as pressing the ENTER key.

In Insert mode, the NewLine method will insert a new line. In Overtype mode, the NewLine method will move the insertion point to the next line without creating a new line. However, if the insertion point is on the last line the NewLine method will add a new line after the last one.

Whether you are in insert or overtype mode, you can always create a new line by using the dsNewLine string constant. Consider the following code:

Dim sel
Set sel=ActiveDocument.Selection
sel=dsNewLine

Alternatively, you could use the TextSelection object's Text property, which is the default:

Sel.Text=dsNewLine

Additionally, you can move the insertion point to the next line by using either of the following statements:

Sel="void main()"+ dsNewLine
Sel="{"+ dsNewLine

Example

The following example creates a new line:

ActiveDocument.Selection.NewLine

See Also DestructiveInsert method, Indent method, Overtype property, Text property, Unindent method.


NewWindow Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object

Creates a new window for a document.

Syntax

object.NewWindow

Parameters

object

An expression that evaluates to a Document object or a TextDocument object.

Return Values

The NewWindow method returns the Window object corresponding to the window created.

Remarks

You can create a new window for a text document but not for most other document types. If you try to create a new window for a document that does not permit another window, the NewWindow method returns the DS_E_CANNOTCREATENEWWINDOW error.

Example

The following example creates a new window in a text document:

ActiveDocument.NewWindow


NextBookmark Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to the next unnamed bookmark in a document.

Syntax

object.NextBookmark

Parameters

object

An expression that evaluates to a TextSelection object.

Return Values

The NextBookmark method returns one of the following values:

  • True Indicates that the bookmark was found.

  • False Indicates that the bookmark was not found.

Example

The following example moves the insertion point to the next unnamed bookmark in a document:

ActiveDocument.Selection.NextBookmark

See Also ClearBookmarks method, PreviousBookmark method, SetBookmark method.


Open Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Documents object

Opens a document with a specified file name.

Syntax

object.Open PathName[, OpenAs ][, ReadOnly]

Parameters

object

An expression that evaluates to a Documents object.

PathName

A String that specifies the full path to the document.

OpenAs

(Optional) A Variant that is a String specifying the document type when the document opens. Possible values are:

  • "Text" Opens the document as a text file.

  • "Auto" Opens the document in the default editor (the default).

ReadOnly

(Optional) A Variant that is a Boolean specifying whether the document is read-only. Possible values are:

  • True Opens as read-only.

  • False Opens as read/write (the default).

Example

The following example opens the macro file C:\ Program Files\Microsoft Visual Studio\Common\MSDEV98\Macros\Sample.dsm as read-only:

Documents.Open "C:\Program Files\Microsoft Visual Studio\Common\MSDEV98\Macros\Sample.dsm",,True

See Also Close method, CloseAll method.


PageDown Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point down one page.

Syntax

object.PageDown [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+PAGE DOWN.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

The PageDown method has the same effect as pressing the PAGE DOWN key.

Example

The following example moves the insertion point down one page and extends the selection:

ActiveDocument.Selection.PageDown dsExtend

See Also PageUp method.


PageUp Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point up one page.

Syntax

object.PageUp [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+PAGE UP.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

The PageUp method has the same effect as pressing the PAGE UP key.

Example

The following example moves the insertion point up one page and extends the selection:

ActiveDocument.Selection.PageUp dsExtend

See Also PageDown method.


Paste Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Replaces a selection with the contents of the Clipboard.

Syntax

object.Paste

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

You cannot paste over a column selection.

Example

The following example replaces a selection with the contents of the Clipboard:

ActiveDocument.Selection.Paste

See Also Copy method, Cut method.


PreviousBookmark Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to the previous unnamed bookmark in a document.

Syntax

object.PreviousBookmark

Parameters

object

An expression that evaluates to a TextSelection object.

Return Values

The PreviousBookmark method returns one of the following values:

  • True Indicates that the bookmark was found.

  • False Indicates that the bookmark was not found.

Example

The following example moves the insertion point to the previous unnamed bookmark in a document:

ActiveDocument.Selection.PreviousBookmark

See Also ClearBookmarks method, NextBookmark method, SetBookmark method.


PrintOut Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object

Sends a document to the current printer.

Syntax

object.PrintOut

Parameters

object

An expression that evaluates to a Document object or a TextDocument object.

Return Values

The PrintOut method returns one of the following values:

  • True If the document printed successfully.

  • False If the document did not print. For example, a printer error occurred.

Remarks

The PrintOut method does not work with documents having the Generic type.

Example

The following example sends a document to the current printer:

ActiveDocument.PrintOut


PrintToOutputWindow Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Directs the output from a macro to the Macro tab of the Output window.

Syntax

object.PrintToOutputWindow string

Parameters

object

An expression that evaluates to an Application object. When you use the PrintToOutputWindow method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

string

A String that includes the output directed to the Macro tab of the Output window.

Remarks

The output directed by PrintToOutputWindow can contain any string a macro produces. However, this output typically contains data not displayed in a message box, such as debugging messages, logging data from a build, or the results of a file search.

Example

The following example iterates through the Breakpoints collection and displays the details about each breakpoint before removing it:

Dim bp
for each bp in Debugger.Breakpoints
   PrintToOutputWindow(bp.Location)
   PrintToOutputWindow(bp.File)
   PrintToOutputWindow(bp.Function)
   PrintToOutputWindow(bp.Executable)
   PrintToOutputWindow(bp.Condition)
   PrintToOutputWindow(bp.Enabled)
   PrintToOutputWindow(bp.PassCount)
   PrintToOutputWindow(bp.Message)
   PrintToOutputWindow(bp.WindowProcedure)
   PrintToOutputWindow(bp.Type)
   bp.Remove
next


Quit Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Quits Developer Studio.

Syntax

object.Quit

Parameters

object

An expression that evaluates to an Application object. When you use the Quit method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Remarks

The Quit method prompts the user to save documents that have changed, and then closes the documents before shutting down Developer Studio.

Example

The following example directs Developer Studio to quit:

Quit


RebuildAll Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Rebuilds a specified configuration by processing all files in the configuration, whether or not the files have changed.

Syntax

object.RebuildAll [configuration]

Parameters

object

An expression that evaluates to an Application object. When you use the RebuildAll method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

configuration

(Optional) A string constant of type Configuration that specifies the type of configuration. Possible values appear in the Default Project Configuration box. The default value is Nothing.

Remarks

If you do not specify a configuration, Developer Studio rebuilds the default configuration. For example, if you specify Application.RebuildAll, Developer Studio rebuilds the default.

To find the appropriate configuration, first locate the project with that configuration by iterating through the Projects collection, using the Projects property of the Application object. Once you find the project, locate the appropriate configuration by iterating through the project's Configurations collection, using the Configurations property of the BuildProject object.

Example

The following example rebuilds each configuration in every build project:

Sub RebuildEveryConfiguration
Dim projCol
Dim configCol
Dim numProjects
Dim numConfigs
Dim i
Dim j
set projCol = Projects
numProjects = projCol.Count
For i=1 To numProjects
   Dim proj
   set proj = projCol(i)
   If proj.Type = "Build" Then
      set configCol = proj.Configurations
      numConfigs = configCol.Count
      For j=1 to numConfigs
         Dim config
         set config = configCol(j)
         RebuildAll config
      Next
   End If
Next
End Sub

See Also Configuration object, Build method, Clean method.


Redo Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object

Reapplies previous editing actions that have been undone.

Syntax

object.Redo

Parameters

object

An expression that evaluates to a Document object or a TextDocument object.

Return Values

The Redo method returns one of the following values:

  • True If the operation was successful.

  • False If the operation was not successful.

Remarks

You can reverse a Redo operation by using the Undo method.

The Redo method has no effect on a document with the Generic type.

Example

The following example reapplies previously undone editing actions to a document:

ActiveDocument.Redo


Remove Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoint object

Removes a breakpoint from the Breakpoints collection.

Syntax

object.Remove

Parameters

object

An expression that evaluates to a Breakpoint object.

Example

The following example iterates through the Breakpoints collection and displays the details about each breakpoint before removing it:

Dim bp
for each bp in Debugger.Breakpoints
   PrintToOutputWindow(bp.Location)
   PrintToOutputWindow(bp.File)
   PrintToOutputWindow(bp.Function)
   PrintToOutputWindow(bp.Executable)
   PrintToOutputWindow(bp.Condition)
   PrintToOutputWindow(bp.Enabled)
   PrintToOutputWindow(bp.PassCount)
   PrintToOutputWindow(bp.Message)
   PrintToOutputWindow(bp.WindowProcedure)
   PrintToOutputWindow(bp.Type)
   bp.Remove
next


RemoveAllBreakpoints Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoints object

Removes all breakpoints in the Breakpoints collection.

Syntax

object.RemoveAllBreakpoints

Parameters

object

An expression that evaluates to a Breakpoints object.

Example

The following example removes all breakpoints:

Dim bps
Set bps = Debugger.Breakpoints
bps.RemoveAllBreakpoints


RemoveBreakpointAtLine Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Breakpoints object

Removes all breakpoints on a line.

Syntax

object.RemoveBreakpointAtLine ( [ line_number ] )

Parameters

object

An expression that evaluates to a Breakpoints object.

line_number

A Long representing the line on which you want to remove all breakpoints. The default is the current line in the active text document.

Return Values

The RemoveBreakpointAtLine method returns one of the following values:

  • True If breakpoints were removed.

  • False If no breakpoints were removed.

Example

The following example removes the breakpoint on line 10:

Dim bps
Set bps = Debugger.Breakpoints
bps.RemoveBreakpointAtLine(10)


RemoveFileSettings Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Configuration object

Removes the settings of a specified file.

Syntax

object.RemoveFileSettings file, settings

Parameters

object

An expression that evaluates to a Configuration object.

file

A String that contains the name of the file whose settings you want to change.

settings

A String that includes the settings or command-line flags you want to remove from your project settings. You can remove multiple flags by separating them with spaces. For instance, you can specify "/MDd /W3" to remove the compiler flags "/MDd" and "/W3" from the makefile. If you try to remove a flag that does not exist in the makefile, Developer Studio will disregard that entry.

Remarks

The functionality of the RemoveFileSettings method appears on the tabs of the Project Settings dialog box (Project menu, Settings command).

Example

The following example removes the /WX switch from the precompiled header:

for each proj in Application.Projects
   for each cfg in proj.Configurations
      cfg.RemoveFileSettings "stdafx.cpp", "/WX"
   next
next

See Also AddFileSettings method.


RemoveToolSettings Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Configuration object

Removes the settings of a specified tool, such as the VC++ compiler.

Syntax

object.RemoveToolSettings tool, settings

Parameters

object

An expression that evaluates to a Configuration object.

tool

A String that contains the name of the tool whose settings you want to change. For the Visual C++ compiler, specify "cl.exe," and for the linker specify "link.exe."

settings

A String that includes the settings or command-line flags you want to remove from your project makefile. These settings apply to all files in the configuration. You can remove multiple flags by separating them with spaces. For instance, you can specify "/MDd /W3" to remove the compiler flags "/MDd" and "/W3" from the makefile. If you try to remove a flag that does not exist in the makefile, Developer Studio will disregard that entry.

Remarks

The functionality of the RemoveToolSettings method appears on the tabs of the Project Settings dialog box (Project menu, Settings command).

Example

The following example removes the exception handling flag used by the Visual C++ compiler from the project makefile owned by a specified project and configuration:

Sub RemoveExceptionHandling
If Projects(1).Type = "Build" Then
   Projects(1).Configurations(1).RemoveToolSettings "cl.exe", "/GX"
End If
End Sub

See Also AddToolSettings method.


ReplaceText Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextDocument object, TextSelection object

Replaces all instances of a string or regular expression with another string or regular expression.

Syntax

object.ReplaceText ( CurrString, RepString [, flags] )

Parameters

object

An expression that evaluates to a TextDocument object or a TextSelection object.

CurrString

The String you want to replace.

RepString

The replacement String.

flags

(Optional) A string constant of type DsTextSearchOptions that determines how to conduct the search. To perform complex searches, you can combine values. The values you can use singly or in combination are:

  • dsMatchForward Causes a forward search from the beginning of the document. This is the default.

  • dsMatchBackward Causes a backward search from the end of the document.

  • dsMatchWord Requires that whole words match.

  • dsMatchCase Requires a case-sensitive match.

  • dsMatchRegExp Requires a match with Developer Studio regular expressions.

  • dsMatchNoRegExp Does not require a match with Developer Studio regular expressions. This is the default.

  • dsMatchRegExpB Requires a match with BRIEF® regular expressions.

  • dsMatchRegExpE Requires a match with Epsilon™ regular expressions.

  • dsMatchRegExpCur Requires a match using the current regular expression setting.

Return Values

The ReplaceText method returns one of the following values:

  • True If one or more replacements occur.

  • False If no replacements occur.

Remarks

The following table summarizes the results of using the ReplaceText method with the objects in the Applies To list:

Object | Results
TextDocument | Replaces all instances of the specified text string in the entire document.
TextSelection | Replaces all instances of the specified text string in the current selection.

You can combine string constants in the flags parameter by using the or or + operators. For example, to conduct a case-sensitive forward search, you could specify dsMatchForward or dsMatchCase or dsMatchForward + dsMatchCase. However, you can use only one of the regular expression values at a time. For example, you cannot combine dsMatchRegExpCur with dsMatchRegExpE.

Example

In the current selection, the following example replaces all occurrences of "LPVOID" with "void *" by using tagged regular expressions:

Sub ReplaceLPVOID
   ActiveDocument.Selection.ReplaceText "LPVOID",    "void *", dsMatchCase + dsMatchWord
End Sub

See Also FindText method, MarkText method.


Restart Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Restarts a program that is being debugged.

Syntax

object.Restart

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

The Restart method ends the current debugging session and then restarts the program at the first possible point of execution.

Example

The following example performs the Restart method:

Debugger.Restart


RunToCursor Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

In a program you are debugging, sets a temporary breakpoint at the cursor (insertion point) and then starts execution of the program.

Syntax

object.RunToCursor

Parameters

object

An expression that evaluates to a Debugger object.

Example

The following example performs the RunToCursor method:

Debugger.RunToCursor


Save Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object

Saves a document to a file.

Syntax

object.Save ( [FullName][, PromptUser] )

Parameters

object

An expression that evaluates to a Document object or a TextDocument object.

FullName

(Optional) A Variant that is a String specifying the full path to the file in which you want to save the document. If you omit the name, it defaults to the name specified by the FullName property.

PromptUser

(Optional) A Variant that is a Boolean indicating whether to prompt the user to save changes. Possible values are:

  • True Prompts the user to save changes. If the user chooses not to save changes, Save returns the enum dsSaveStatus with the value dsSaveSucceeded; otherwise Save returns dsSaveStatus with the value dsSaveCanceled.

  • False Does not prompt the user (the default).

Return Values

The Save method returns the enum dsSaveStatus, which has one of the following values:

  • dsSaveCanceled Indicates that the user chose not to save changes to the document.

  • dsSaveSucceeded Indicates that the user saved changes to the document.

Example

The following example saves a document to "C:\Document\Mydoc.txt":

ActiveDocument.Save ("c:\document\mydoc.txt")


SaveAll Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Documents object

Saves all open documents in the collection.

Syntax

object.SaveAll ( [PromptUser] )

Parameters

object

An expression that evaluates to a Documents object.

PromptUser

(Optional) A Variant that is a Boolean indicating whether to prompt the user to save changes. Possible values are:

  • True Prompts the user to save changes. If the user chooses not to save changes, SaveAll returns the enum dsSaveStatus with the value dsSaveSucceeded; otherwise SaveAll returns dsSaveStatus with the value dsSaveCanceled.

  • False Does not prompt the user (the default).

Return Values

The SaveAll method returns the enum dsSaveStatus, which has one of the following values:

  • dsSaveCanceled Indicates that the user chose not to save changes to the document.

  • dsSaveSucceeded Indicates that the user saved changes to the document.

Example

The following example prompts the user to save the changes to each open document:

Documents.SaveAll (True)


SelectAll Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Extends the selection to include the entire document.

Syntax

object.SelectAll

Parameters

object

An expression that evaluates to a TextSelection object.

Example

The following example extends the selection to the entire document:

ActiveDocument.Selection.SelectAll

See Also SelectLine method.


SelectLine Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Selects the line defined by the CurrentLine property.

Syntax

object.SelectLine

Parameters

object

An expression that evaluates to a TextSelection object.

Example

The following example selects the current line:

ActiveDocument.Selection.SelectLine

See Also SelectAll method.


SetAddInInfo Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Provides Developer Studio with information about an add-in, when the add-in is loaded. The add-in calls SetAddInInfo.

Syntax

object.SetAddInInfo Hinstance, CmdDispatch, BitmapResourceMedium, BitmapResourceLarge, cookie

Parameters

object

An expression that evaluates to an Application object. When you use the SetAddInInfo method of the Application object, you can omit object because the name of the Application object is implied when you access its properties and methods.

Hinstance

The HINSTANCE of the add-in's DLL, casted to a Long. If you create the add-in using Visual Basic, you can access this with the App object App.HInstance.

CmdDispatch

The pointer to the dispatch interface (dispinterface) implemented by the add-in's Commands object. When a user chooses one of the add-in's commands, Developer Studio invokes the command by using this pointer to communicate with the add-in.

BitmapResourceMedium

A Long that is the ID of the bitmap resource containing medium-sized images of all toolbar buttons that the add-in is adding. Specify -1 if the add-in does not provide toolbar buttons.

BitmapResourceLarge

A Long that is the ID of the bitmap resource containing large-sized images of all toolbar buttons that the add-in is adding. Specify -1 if the add-in does not provide toolbar buttons.

cookie

A Long that is the cookie identifying the add-in. Developer Studio passes this value to the add-in through the add-in's OnConnection method.

Remarks

Only add-ins can call the SetAddInInfo method. VBSscript macros cannot.

Example

The following example, which is written in Visual C++, is the code automatically generated when you create an add-in using the Developer Studio Add-in Wizard:

STDMETHODIMP CDSAddIn::OnConnection(IApplication* pApp, VARIANT_BOOL bFirstTime,
      long dwCookie, VARIANT_BOOL* OnConnection)
{
...
   pApplication->SetAddInInfo((long) AfxGetInstanceHandle(),
      (LPDISPATCH) m_pCommands, IDR_TOOLBAR_MEDIUM, IDR_TOOLBAR_LARGE, m_dwCookie);
...
}

See Also AddCommand method, AddCommandBarButton method, AddKeybinding method, EnableModeless method.


SetBookmark Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Sets an unnamed bookmark at the active end of a selection.

Syntax

object.SetBookmark

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The active end of a selection is where the insertion point is.

Example

The following example sets an unnamed bookmark at the active end of a selection:

ActiveDocument.Selection.SetBookmark

See Also ClearBookmarks method, NextBookmark method, PreviousBookmark method.


SetNextStatement Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Specifies the next statement to execute in a program that you are debugging.

Syntax

object.SetNextStatement [expression]

Parameters

object

An expression that evaluates to a Debugger object.

expression

A Long that indicates where to start execution of the program. The default is the insertion point in the active document.

Remarks

The SetNextStatement method is useful for starting execution somewhere after a breakpoint. If the debugger is not able to complete the operation directed by the SetNextStatement method, it throws the dsCantSetIPToThisLine exception.

Example

The following example starts execution at the insertion point in the active document:

Debugger.SetNextStatement


ShowCurrentStatement Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

In a program you are debugging, moves the insertion point to the line containing the current instruction.

Syntax

object.ShowCurrentStatement

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

The ShowCurrentStatement method is useful for returning the insertion point to the current line. For example, you might want to set or clear a breakpoint on that line. You can only use this method when the program being debugged is in break mode.

Example

The following example moves the insertion point to the line containing the current instruction:

Debugger.ShowCurrentStatement


SmartFormat Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Formats text in a selection according to the current smart formatting settings.

Syntax

object.SmartFormat

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

By default, the SmartFormat method formats selected text according to the smart formatting settings defined on the Tabs tab of the Options dialog box (Tools menu, Options command). However, you can apply custom smart formatting to selected text by using the Format Selection command (Edit menu, Advanced command).

Example

The following example formats text in a selection according to the current smart format settings:

ActiveDocument.Selection.SmartFormat


StartOfDocument Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to the beginning of the document.

Syntax

object.StartOfDocument [extend]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection. This is the same as pressing CTRL+SHIFT+HOME.

  • dsMove Does not extend the selection (the default).

Remarks

The StartOfDocument method has the same effect as pressing CTRL+HOME.

Example

The following example moves the insertion point to the beginning of the document and extends the selection:

ActiveDocument.Selection.StartOfDocument dsExtend

See Also EndOfDocument method.


StartOfLine Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point to the beginning of a line.

Syntax

object.StartOfLine [moveto][, extend]

Parameters

object

An expression that evaluates to a TextSelection object.

moveto

(Optional) A string constant of type DsStartOfLineOptions that represents the place to which the insertion point moves. Possible values are:

  • dsFirstColumn Moves the insertion point to the first column in the line (the default).

  • dsFirstText Moves the insertion point to the first text character in the line.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing SHIFT+HOME.

  • dsMove Does not extend the selection (the default).

Example

The following example moves the insertion point to the beginning of the line and extends the selection:

ActiveDocument.Selection.StartOfLine dsExtend

See Also EndOfLine method.


StepInto Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Steps into a called function, executing each instruction step by step.

Syntax

object.StepInto

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

During program debugging, if the next instruction is a function call, the StepInto method steps inside the function and then executes each instruction step by step. This continues until all instructions have executed or until you call the StepOut method.

Use the StepOver method to execute a called function without stepping through it.

Example

The following example steps into a called function:

Debugger.StepInto


StepOut Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Stops stepping through a called function, executes the remainder of the function, exits the function, and then breaks at the statement after the function call.

Syntax

object.StepOut

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

During program debugging, use the StepInto method to step through instructions in a called function. Use the StepOut method to stop stepping through the instructions, to execute the remainder of the function, to exit the function, and then to break at the statement after the function call.

Use the StepOver method to execute a called function without stepping through it.

Example

The following stops stepping through a called function, executes the remainder of the function, exits the function, and then breaks at the statement after the function call:

Debugger.StepOut


StepOver Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Executes a called function without stepping through it.

Syntax

object.StepOver

Parameters

object

An expression that evaluates to a Debugger object.

Remarks

During program debugging, use the StepInto method to step through instructions in a called function. Use the StepOut method to stop stepping through the instructions, to execute the remainder of the function, to exit the function, and then to break at the statement after the function call.

Use the StepOver method to execute a called function without stepping through it.

Example

The following example executes a called function without stepping through it:

Debugger.StepOver


Stop Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Stops execution of a program you are debugging.

Syntax

object.Stop

Parameters

object

An expression that evaluates to a Debugger object.

Example

The following example stops execution of a program you are debugging:

Debugger.Stop


Tabify Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Converts spaces to tabs in a selection.

Syntax

object.Tabify

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

This method applies only to the current selection, not to the whole document. To convert spaces to tabs in the entire document, select the whole document using the SelectAll method and then use the Tabify method.

Example

The following example converts spaces to tabs in a selection:

ActiveDocument.Selection.Tabify

See Also IndentSize property, TabSize property, Untabify method, VisibleWhitespace property.


Undo Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Document object, TextDocument object

Reverses previous editing actions on a document.

Syntax

object.Undo

Parameters

object

An expression that evaluates to a Document object or a TextDocument object.

Return Values

The Undo method returns one of the following values:

  • True If the operation was successful.

  • False If the operation was not successful.

Remarks

Use the Redo method to reapply editing actions that have been undone.

The Undo method has no effect on a document with the Generic type.

Example

The following example reverses previous editing actions on a document:

ActiveDocument.Undo


Unindent Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Removes one indent from all lines in a selection.

Syntax

object.Unindent

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

The Unindent method has the same effect as pressing SHIFT+TAB.

The Unindent method affects all lines whether they are completely or partially within the selection. The IndentSize and TabSize properties determine the number of columns that are unindented.

Example

The following example removes one indent from all lines in a selection:

ActiveDocument.Selection.Unindent

See Also DestructiveInsert method, Indent method, NewLine method, Overtype property, Text property.


Untabify Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Converts tabs to spaces in a selection.

Syntax

object.Untabify

Parameters

object

An expression that evaluates to a TextSelection object.

Remarks

This method applies only to the current selection, not to the whole document. To convert tabs to spaces in the entire document, select the whole document using the SelectAll method and then use the Untabify method.

Example

The following example converts tabs to spaces in a selection:

ActiveDocument.Selection.Untabify

See Also IndentSize property, Tabify method, TabSize property, VisibleWhitespace property.


WordLeft Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point one word to the left.

Syntax

object.WordLeft [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection.This is the same as pressing CTRL+SHIFT+LEFT ARROW.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

The WordLeft method has the same effect as pressing CTRL+LEFT ARROW.

Example

The following example moves the insertion point one word to the left and extends the selection:

ActiveDocument.Selection.WordLeft dsExtend

See Also CharLeft method, CharRight method, WordRight method.


WordRight Method

Home Page (Objects) | Overview | FAQ | Reference

Applies to: TextSelection object

Moves the insertion point one word to the right.

Syntax

object.WordRight [extend][, count]

Parameters

object

An expression that evaluates to a TextSelection object.

extend

(Optional) A string constant of type DsMovementOptions that specifies what to do with the selection. Possible values are:

  • dsExtend Extends the selection. This is the same as pressing CTRL+SHIFT+RIGHT ARROW.

  • dsMove Does not extend the selection (the default).

count

(Optional) A Long that specifies the number of times you want to repeat this action. The default is one.

Remarks

The WordRight method has the same effect as pressing CTRL+RIGHT ARROW.

Example

The following example moves the insertion point one word to the right and extends the selection:

ActiveDocument.Selection.WordRight dsExtend

See Also CharLeft method, CharRight method, WordLeft method.


Events

Home Page (Objects) | Overview | FAQ | Reference

An event is an action or occurrence, often generated by the user, to which a VBScript event handler, Developer Studio add-in, or other Automation controller can respond. For example, if a user clicks on a window, Developer Studio fires the WindowActivate event of the Application object.

The following events are available:

Event | Description
BeforeApplicationShutDown | Occurs before Developer Studio shuts down.
BeforeBuildStart | Occurs before a build starts.
BeforeDocumentClose | Occurs before a specified document closes.
BreakpointHit | Occurs when a breakpoint is hit.
BuildFinish | Occurs after a build completes.
DocumentOpen | Occurs after a specified document opens.
DocumentSave | Occurs after a specified document is saved.
NewDocument | Occurs after a specified document is created.
NewWorkspace | Occurs after a workspace is created.
WindowActivate | Occurs after a specified window becomes active.
WindowDeactivate | Occurs after a specified window becomes inactive.
WorkspaceClose | Occurs after a workspace closes.
WorkspaceOpen | Occurs after a workspace opens.

In a VBScript event handler, you can respond to an event by taking some action. For instance, you could change the size of a window by setting the Height and Width properties of the Window object.

To respond to an event, add the appropriate event handler to any loaded VBScript macro file. You can add this event handler to multiple VBScript macro files. For example, if you add an event handler for the WindowActivate event to two loaded VBScript macro files, when the user activates a window, both of these event handlers will be called — one at a time.

To add the event handler, find the appropriate event by using the previous table, copy the sample event handler from the example, paste the handler into your macro file, insert the appropriate code into the handler, and then reload the macro file.

For example, you could take some action just before Developer Studio quits by using the BeforeApplicationShutDown event. To use this event, go to the description of the event and copy the sample event handler:

sub    Application_BeforeApplicationShutDown()
   ' Insert code to handle the event here
end sub

Then, paste this code into your macro file, insert the code for handling the event, and then reload the macro file.

Tip To reload the macro file, open the file in the text editor, click the right mouse button, and then click Reload Macros in File.


BeforeApplicationShutDown Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs before Developer Studio shuts down.

Syntax

object_BeforeApplicationShutDown

Parameters

object

An expression that evaluates to an Application object.

Remarks

Developer Studio fires this event before Developer Studio ends.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the BeforeApplicationShutDown event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_BeforeApplicationShutDown()
   ' Insert code to handle the event here
end sub


BeforeBuildStart Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs before a build starts.

Syntax

object_BeforeBuildStart

Parameters

object

An expression that evaluates to an Application object.

Remarks

Developer Studio fires this event before a build starts.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the BeforeBuildStart event. Copy this into your macro file, and then insert the appropriate code.

sub Application_BeforeBuildStart()
   ' Insert code to handle the event here
end sub


BeforeDocumentClose Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs before a specified document closes.

Syntax

object_BeforeDocumentClose ( document )

Parameters

object

An expression that evaluates to an Application object.

document

The Document object that triggers this event.

Remarks

Developer Studio fires this event before the document closes.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the BeforeDocumentClose event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_BeforeDocumentClose(theDocument)
   ' Insert code to handle the event here
end sub

See Also DocumentOpen event, DocumentSave event.


BreakpointHit Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Debugger object

Occurs when a breakpoint is hit.

Syntax

object_BreakpointHit ( Brkpt_object )

Parameters

object

An expression that evaluates to a Debugger object.

Brkpt_object

The Breakpoint object representing the breakpoint that was hit.

Remarks

Developer Studio fires this event when a breakpoint occurs.

If you call the Go method in code for the BreakpointHit event, Developer Studio temporarily defers the call, executes the remaining instructions in the event code, and then executes the Go method when the event exits.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the BreakpointHit event. Copy this into your macro file, and then insert the appropriate code.

sub Debugger_BreakpointHit(theBreakpoint)
   ' Insert code to handle the event here
end sub


BuildFinish Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a build completes.

Syntax

object_BuildFinish ( NumErrors, NumWarnings )

Parameters

object

An expression that evaluates to an Application object.

NumErrors

A Long that specifies the number of errors found in the build.

NumWarnings

A Long that specifies the number of warnings found in the build.

Remarks

Developer Studio fires this event after the build completes. The BuildFinish event passes the number of build errors and warnings to the event handler.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the BuildFinish event. Copy this into your macro file, and then insert the appropriate code.

sub Application_BuildFinish(nNumErrors, nNumWarnings)
   ' Insert code to handle event here
end sub


DocumentOpen Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a specified document opens.

Syntax

object_DocumentOpen ( document )

Parameters

object

An expression that evaluates to an Application object.

document

The Document object that triggers this event.

Remarks

Developer Studio fires this event after the document opens.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the DocumentOpen event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_DocumentOpen(theDocument)
   ' Insert code to handle the event here
end sub

See Also BeforeDocumentClose event, DocumentSave event.


DocumentSave Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a specified document is saved.

Syntax

object_DocumentSave ( document )

Parameters

object

An expression that evaluates to an Application object.

document

The Document object that triggers this event.

Remarks

Developer Studio fires this event after the document is saved.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the DocumentSave event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_DocumentSave(theDocument)
   ' Insert code to handle the event here
end sub

See Also BeforeDocumentClose event, DocumentOpen event.


NewDocument Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a specified document is created.

Syntax

object_NewDocument ( document )

Parameters

object

An expression that evaluates to an Application object.

document

The Document object that triggers this event.

Remarks

Developer Studio fires this event after the document is created.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the NewDocument event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_NewDocument(theDocument)
   ' Insert code to handle the event here
end sub


NewWorkspace Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a workspace is created.

Syntax

object_NewWorkspace

Parameters

object

An expression that evaluates to an Application object.

Remarks

Developer Studio fires this event after the workspace is created.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the NewWorkspace event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_NewWorkspace()
   ' Insert code to handle the event here
end sub


WindowActivate Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a specified window becomes active.

Syntax

object_WindowActivate ( window )

Parameters

object

An expression that evaluates to an Application object.

window

The Window object that triggers this event.

Remarks

Developer Studio fires this event after the window becomes active.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the WindowActivate event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_WindowActivate(theWindow)
   ' Insert code to handle the event here
end sub

See Also WindowDeactivate event.


WindowDeactivate Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a specified window becomes inactive.

Syntax

object_WindowDeactivate ( window )

Parameters

object

An expression that evaluates to an Application object.

window

The Window object that triggers this event.

Remarks

Developer Studio fires this event after the window becomes inactive.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the WindowDeactivate event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_WindowDeactivate(theWindow)
   ' Insert code to handle the event here
end sub

See Also WindowActivate event.


WorkspaceClose Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a workspace closes.

Syntax

object_WorkspaceClose

Parameters

object

An expression that evaluates to an Application object.

Remarks

Developer Studio fires this event after a workspace closes.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the WorkspaceClose event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_WorkspaceClose()
   ' Insert code to handle the event here
end sub

See Also WorkspaceOpen event.


WorkspaceOpen Event

Home Page (Objects) | Overview | FAQ | Reference

Applies to: Application object

Occurs after a workspace opens.

Syntax

object_WorkspaceOpen

Parameters

object

An expression that evaluates to an Application object.

Remarks

Developer Studio fires this event after a workspace opens.

For an overview about using event code, see the introduction to events.

Example

Following is a sample event handler for the WorkspaceOpen event. Copy this into your macro file, and then insert the appropriate code.

sub    Application_WorkspaceOpen()
   ' Insert code to handle the event here
end sub

See Also WorkspaceClose event.


Home Page: Macros

You can use macros to greatly simplify your work in the Visual C++ Developer Studio. For example, you can use a macro to combine several commands, speed up routine editing, or automate a complex series of tasks.

Visual C++ provides two ways to record macros from within the environment. The Quick Macro option captures your actions from a particular session, keeping them available for playback until you record another Quick macro. Regular, or named macros enable you to name, save, and edit the actions you record. Both types of macros use the Visual Basic Scripting Edition language.

For information about using macros

  • Overviews

  • How Do I

  • Frequently Asked Questions

  • Reference

Related Home Pages

  • Developer Studio Objects

  • Add-ins for the Visual C++ Developer Studio

  • Customizing Visual C++


Overview: Macros

Home Page (Macros) | How Do I Topics | FAQ | Reference

With VBScript macros or Developer Studio add-ins, you can automate routine tasks. For example, you can update a project by automatically opening the project, changing some project files, saving the changes, and then rebuilding the project.

Visual C++ provides two ways to record macros. With Quick Macro recording, you by-pass the interface that lets you name and save a macro for later editing. Your Quick macro is recorded and persisted until you record another Quick macro. With regular macro recording, you give the macro a name and description, record it, and then edit the resulting VBScript file until the macro performs exactly as you want it to.

What do you want to know more about?

VBScript Macros

Differences between VBScript macros and Developer Studio add-ins

Macro files

The VBScript language

Automation

Developer Studio objects

What do you want to do?

Record a macro

Write a macro by hand

Edit a macro

Install a macro

Assign a macro to a toolbar button or key sequence

Run a macro

Debug a macro

Delete a macro

Rename a macro

Use the sample macros


VBScript Macros

A VBScript macro is a procedure that contains VBScript commands and takes no parameters. A VBScript macro begins with a Sub statement, continues with VBScript commands that represent tasks you want to accomplish, and ends with an End Sub statement.

You create a VBScript macro by recording it or writing it manually. The easiest way to create one is to record it. When you record a macro, the recorder tracks your actions, converts them into VBScript commands, and then inserts the commands into the macro.

When you finish recording the macro, it is stored in a text file known as a macro file. You choose this file before you start writing or recording.

To use a VBScript macro, you run it. If you expect to run it regularly, assign it to a toolbar button or to a key sequence. Then, you can run the macro by simply clicking the button or pressing the keys.


Differences Between VBScript Macros and Developer Studio Add-ins

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

VBScript macros differ from Developer Studio add-ins. The primary difference is that macros are procedures written in the Visual Basic Scripting Edition (VBScript) language, whereas add-ins are in-process COM components (DLLs) written in Visual C++ or Visual Basic.

You can create a VBScript macro more quickly and easily than you can an add-in. To create a macro, you simply record the macro, add extra code (if necessary), and then run the macro. To create an add-in, however, you must write it in a language such as Visual C++, compile it into a DLL, connect it to the Visual C++ Developer Studio environment, and then run its commands.

VBScript macros are not as versatile as add-ins. In macros, you can only use the VBScript language, and you can only access the Developer Studio object model. In add-ins, however, you can use a language of your choice, and you can access not only the object model but the resources of the entire computer system.

The following table summarizes the differences between macros and add-ins.

VBScript macros | Developer Studio add-ins
Are interpreted | Are compiled
Are easy to create | Are more difficult to create
Can only be written in VBScript | Can be written in different languages, such as Visual C++ and Visual Basic
Can only access the Developer Studio object model | Can access local computer resources as well as the Developer Studio object model
Can only use dialog boxes created by the VBScript InputBox and MsgBox commands | Can use arbitrary modal dialog boxes
Cannot directly read from or write to files on disk | Can directly read from or write to files on disk, using the Win32 API
Cannot access the Win32 API | Can access the Win32 API
Cannot use early binding | Can use early binding for better run-time performance
Cannot control another application (.EXE) | Can control another application (.EXE)


Macro Files

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

Visual C++ stores macros in text files called macro files. A macro file has a .DSM file extension and can contain one or more macros. The number of macros is up to you.

You install macro files from the Add-ins and Macro Files tab of the Customize dialog box (Tools menu, Customize command). Once installed, they load automatically whenever you start Visual C++. They are available to all projects, but they are independent of projects.

At the beginning of each macro file is a description of the file. You provide this description when you create the file. Following this description are the macro definitions.

Before you start writing or recording a macro, Visual C++ appends a macro stub to the file. This stub begins with a Sub statement containing the macro's name, continues with a description that you provide, and ends with an End Sub statement.

A macro's VBScript commands go between its Sub and End Sub statements. If you write the macro by hand, you must insert these commands. However, if you record the macro, Visual C++ automatically inserts the commands where they belong.

Sub MacroName()
'Description: The macro description goes here

'TODO: The VBScript commands go here

End Sub


How Do I ... Topics: VBScript Macros

How Do I ... Topics: Macros

Home Page (Macros) | Overview | FAQ | Reference

You can automate your work in Visual C++ by recording VBScript macros that perform routine tasks. You can quickly record and playback a macro, similar to the way previous versions of Visual C++ provided a keystroke recording feature. Or, you can save your macro with a unique name so that you can edit the resulting VBScript macro file and rerun the macro whenever you want.

What do you want to do?

Record a macro

Write a macro by hand

Edit a macro

Install a macro

Assign a macro to a toolbar button or key sequence

Run a macro

Quit a running macro

Debug a macro

Delete a macro

Rename a macro

Use the sample macros


Recording Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

You can record a macro in two ways. If you want to develop a complex macro that you can refine by editing the VBScript macro file, regular macro recording provides the interface to do so. The Quick Macro options by-pass this interface, enabling you to quickly record your actions without having to name a macro, provide a description for it, or review the resulting macro file. This also saves you some keystrokes whenever you want to run the Quick macro, as it remains available from the menu ¯ even if you close and reopen Visual C++ ¯ until you record another Quick macro.

You can also write a VBScript macro by hand.

During macro recording, you can temporarily pause to do something else. For example, you can pause to prepare for the next action. While you pause, the recorder does not track your keystrokes. When you are ready, you can resume recording where you stopped.

Note The recorder cannot record mouse actions when selecting text or moving the insertion point. You must use the keyboard to record these actions. However, you can use the mouse to click commands and options. The recorder does not always convert keystrokes into commands. If you are recording a named macro (not a Quick macro), examine the macro carefully when you stop recording to ensure it is complete. If you find something missing, add the appropriate code.

What do you want to do?

Record a Quick macro

Record a named macro that I can save and edit

To record a quick macro

  1. On the Tools menu, click Record Quick Macro.

  2. Perform the actions that you want to record.

  25. You can use the Pause button on the macro recorder toolbar as a toggle to temporarily interrupt and resume recording.

  26. When you have finished, click the Stop button on the macro recorder toolbar.

  27. To play back the macro, click Play Quick Macro on the Tools menu.

  28. This temporary macro remains available until you record another Quick macro, which writes over any existing Quick macro.

To record a named macro that you can save and edit

  1. On the Tools menu, click Macro.

  2. To add the macro to a new macro file, click the Options button, click the New File button, and then enter the file name in the Macro File box.

    -or-

    To add the macro to an existing file, select the file name from the Macro File box. If the name is not there, first install the file, then select it in the Macro File box.

  3. In the Macro Name box, enter a unique name for the macro.

  4. Click the Record button.

    Note You cannot record a macro that already exists or record to a file that is read-only.

  5. In the Add Macro box, enter a description of the macro, and then click OK.

  6. Perform the actions you want to record.

  7. To pause the recording, click the Pause button.

    (To resume recording, click the Pause button again.)

  8. To stop recording, click the Stop button.

    When recording stops, the selected macro file opens with the insertion point in the Sub block of the newly recorded macro.

If the recorder cannot match a VBScript command to the actual command you carry out, the recorder inserts an ExecuteCommand call to carry out the command. However, if the recorder substitutes ExecuteCommand for a command that causes a dialog box to display, when you run the macro, the dialog box will appear, but no user input will display.


Writing VBScrpt Macros by Hand

Writing VBScript Macros by Hand

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

You can write a VBScript macro manually by adding the code for the macro to a new or existing macro file.

To write a macro by hand

  1. On the Tools menu, click Macro.

  2. To add the macro to a new macro file, click the Options button, click the New File button, and then enter a name for the file, the path to the file, and a description of the file.

    -or-

    To add the macro to an existing file, select the file name in the Macro File box. If the name is not in the list, first install the file, then select it in the Macro File box.

  3. In the Macro Name box, enter a new name for the macro.

  4. Click the Edit button.

    Note You cannot create a new macro in a read-only file, but you can browse an existing macro in a read-only file.

  5. In the Add Macro dialog box, enter a description of the macro, and then click OK.

    Visual C++ opens the macro file, creates a Sub block (macro stub) for the new macro at the end of the file. For example, if the macro name were MyMacro, the Sub block would look like:

    Sub MyMacro()
'Description: The macro description goes here.

'TODO: Insert the macro code here.

End Sub

Tip It is good practice to declare variables used in a macro. You declare variables by using the VBScript Dim statement. You can be sure to declare variables before using them by adding the line, "Option Explicit" at the beginning of a macro file. For more information about the VBScript language, see the VBScript reference.

See Also Recording VBScript Macros


Editing VBScript Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

With the macro editor, you can edit an existing macro or add to a macro you just recorded.

To edit a macro

  1. On the Tools menu, click Macro.

  2. In the Macro File box, select the file containing the macro you want to edit. If this file is not in the list, first install the file, then select it in the Macro File box.

  3. In the Macro Name box, select the macro you want to edit.

  4. Click the Edit button.

  5. Make the appropriate changes.

  6. Save the macro.


Installing VBScript Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

A macro file contains one or more macros. To make these macros available in Visual C++, you must install the macro file.

To install a macro file

  1. On the Tools menu, click Customize.

  2. Click the Add-ins and Macro Files tab.

    The name of the macro file should appear in the window

  3. If the name of the macro file does not appear, click the Browse button to locate the file.

    Tip To avoid browsing, store macro files in the Macros subdirectory of the Visual Studio directory (Visual Studio\Common\MSDEV98\Macros). Visual C++ always searches the Macros directory first.

  4. Load the appropriate macro file by selecting the check box next to its name.

    Visual C++ adds a check mark, indicating that the file is loaded. This check mark also directs Visual C++ to automatically load the file when you start Visual C++ again.

Warning If you remove the check mark from a macro file, you unload it. When you unload it, all of the macros in the file lose their toolbar and keystroke assignments. Additionally, if you remove the check mark, Visual C++ will not automatically load the macro file when you start Visual C++ again.


Assigning VBScript Macros to Toolbar Buttons or Key Sequences

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

If you assign a macro to a toolbar button or key sequence, you can run the macro by clicking the button or pressing the assigned keys.

To assign a macro to a toolbar button

  1. On the Tools menu, click Customize.

  2. Click the Commands tab.

  3. In the Category box, click Macros.

  4. From the Commands box, drag the macro's name to the toolbar where you want a button for the macro.

  5. In the Button Appearance dialog box, select an image for the toolbar button, and then click OK.

    Visual C++ adds a button with that image to the toolbar.

To assign a macro to a key sequence

  1. On the Tools menu, click Customize.

  2. Click the Keyboard tab.

  3. In the Category box, click Macros.

  4. In the Commands box, select the macro you want to assign.

  5. Click in the Press new shortcut key box.

  6. Press the key sequence you want to use for the macro.

  7. Click the Assign button.

    Visual C++ assigns that key sequence to the macro.

Visual C++ provides other ways of using toolbar buttons and key sequences to customize your desktop environment. For details, see Customizing Visual C++.


Running VBScript Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

After installing a macro file, you can run the macros it contains. The easiest way to run them is to use the toolbar buttons or key sequences assigned to the macros.

Note While a VBScript macro is running, the Visual C++ user interface does not respond to mouse clicks or keystrokes. This design prevents unchecked program actions from being processed between macros, but may give the appearance that the user interface is frozen while processing a lengthy macro.

You can also run macros from the Macros dialog box (Tools menu, Macro command) or the command line.

To run a macro from the Macros dialog box

  1. On the Tools menu, click Macro.

  2. In the Macro File box, select the file containing the macro you want to run. If this file is not in the list, first install the file, then select it in the Macro File box.

  3. In the Macro Name box, double-click the name of the macro you want to run.

    -or-

    Select the macro's name and then click the Run button.

To run a macro from the command line.

  • Type msdev –ex Command

    where Command is the name of the macro. This syntax starts Visual C++, and after the Visual C++ main window appears, the macro starts running.

    After the macro completes, Visual C++ continues running. If you want Visual C++ to end, then the macro must call the Application object's Quit method when it completes.

    Additionally, you can run a macro according to a schedule. The following table shows how to schedule a macro with Windows NT or Windows 95.

    To schedule a macro Do this
    With Windows NT Use the AT command to run

    msdev –ex Command

    For example, to run the macro "MyMacro" at 1:00 A.M, use the command:

    AT 1:00am "msdev -ex MyMacro"

    The AT command is available only with Windows NT.
    With Windows 95 If you have the Plus Pack, use the System Agent to run

    msdev –ex Command

Visual C++ provides other ways of using toolbar buttons and key sequences to customize your desktop environment. For details, see Customizing Visual C++.


Quitting VBScript Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

While a VBScript macro runs, an icon representing the macro appears in the taskbar. If the macro runs quickly, the icon appears only briefly. If the macro runs for a while, the icon remains until the macro quits.

You can force a running macro to quit before it normally does.

To quit a VBScript macro

  • Double-click the macro's icon in the taskbar.

When you double-click the icon, Visual C++ displays a dialog box telling you that the macro will be terminated and then displays a red circle with a slash on top of the icon. Typically this circle appears for only a fraction of a second and disappears as soon as the macro quits. However, if the circle remains, it indicates that the macro is executing an instruction. As soon as the macro completes the instruction, the circle will disappear and the macro will quit. Note that you cannot interrupt or speed up execution of this instruction.

Caution If the macro does not quit, it might cause Visual C++ to stop responding. If this happens, press CTRL+ALT+DEL, and then end the Visual C++ task.


Debugging VBScript Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

Visual C++ includes some tools that can help you debug VBScript macros.

To debug a macro

  • Use the PrintToOutputWindow method to print diagnostic messages or values of variables at various points in the macro.

  • Use the VBScript MsgBox command to halt the macro so that you can inspect the messages printed with PrintToOutputWindow or MsgBox. When you are ready to continue the macro, dismiss the message box.


Deleting VBscript Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

When you no longer need a macro, you can delete it.

To delete a macro

  1. On the Tools menu, click Macro.

  2. In the Macro File box, select the file containing the macro you want to delete. If this file is not in the list, first install the file, then select it in the Macro File box.

  3. In the Macro Name box, select the macro you want to delete.

  4. Click the Edit button.

  5. Delete the Sub block containing the macro's code.


Renaming VBScript Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

If necessary, you can rename a macro in its code.

To rename a macro

  1. On the Tools menu, click Macro.

  2. In the Macro File box, select the file containing the macro you want to rename. If this file is not in the list, first install the file, then select it in the Macro File box.

  3. In the Macro Name box, select the macro you want to rename.

  4. Click the Edit button.

  5. Go to the Sub block containing the macro's code.

  6. On the line containing the macro's name, change the name of the macro.


Frequently Asked Questions: VBScript Macros

Home Page (Macros) | Overview | How Do I Topics | Reference

You can automate your work in the Visual C++ Developer Studio by writing VBScript macros to perform routine tasks. The following are some frequently asked questions about VBScript macros.

  • How do I debug a VBScript macro?

  • If I change an existing macro, when does that change become effective?

  • How do I handle events?

  • Can I create code that I can also use in Internet Explorer?

  • Can I write macros in languages other than VBScript?

  • Can a VBScript macro call functions or programs outside of Visual C++?

  • Are VBScript macros stored in projects?

  • In a VBScript macro, can I control builds on another computer?

  • Can I write VBScript macros that interact with a database?

  • Can I write VBScript macros that interact with Visual SourceSafe?

  • Where can I find sample VBScript macros?


How Do I Debug a VBScript Macro?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

You can debug a VBScript macro by using the PrintToOutputWindow method and the VBScript MsgBox command. For details, see Debugging VBScript Macros


If I Change an Existing Macro, When Does That Change Become Effective?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

To make changes effective when you run a macro, you must first reload the file containing the macro.

If the file is already loaded, Visual C++ will reload it the next time you run any macro in it. If you run a macro before saving the changes to it, Visual C++ will apply the changes as long as the file is open. However, if you close the file without saving the changes, they are lost.

If the file is not loaded, you can reload it in two ways. If the file is open in the text editor, you can reload it by clicking the right mouse button and choosing Reload Macro File. If the file is not open, you can reload it from the Add-ins and Macro Files tab in the Customize dialog box (Tools menu, Customize command).


How do I Handle Events?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

You must write all code that handles events. For examples of event-handling code, see the examples accompanying the descriptions of Developer Studio events.


Can I Create Code That I Can Also Use in Internet Explorer?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

Yes, you can create VBScript code that is usable in Internet Explorer. Such code goes between SCRIPT and /SCRIPT tags in Internet Explorer HTML files. For details about using VBScript in Internet Explorer, see the VBScript tutorial.


Can I Write Macros in Languages Other than VBScript?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

Currently, you can only write macros in the VBScript language. For details about VBScript, see the VBScript reference.


Can a VBScript Macro Call Functions or Programs Outside of Visual C++?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

No, a VBScript macro cannot call functions or programs outside of the Visual C++ Developer Studio. However, a Developer Studio add-in can call functions or programs outside of Visual C++. For details about add-ins, see Overview: Developer Studio Add-ins.


Are VBScript Macros Stored in Projects?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

No, VBScript macros are stored in macro files that are separate from projects. Macros are available to all projects, but are independent of projects.


In a VBScript Macro, Can I Control Builds on Another Computer?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

No, you cannot control builds on another computer with a VBScript macro. You can only control builds on your own computer.


Can I Write VBScript Macros That Interact with a Database?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

No, you cannot write VBScript macros that interact with a database.


Can I Write VBScript Macros that Interact with Visual SourceSafe?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

No, you cannot write VBScript macros that interact with Visual SourceSafe. Macros only act on the Visual C++ environment.


Where Can I Find Sample VBScript Macros?

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

You can find sample VBScript macros in MSDEV98\macros\Sample.dsm, which is in the Microsoft Visual Studio\Common directory. For descriptions of these macros, see Using the Sample Macros.


Reference: VBScript Macros

Home Page (Macros) | Overview | How Do I ... Topics | FAQ

In the Visual C++ Developer Studio, you can write, save and edit macros in the Visual Basic Scripting Edition language (VBScript).

Note You can also invoke the macro recorder for just a single session by using the Quick Macro options from the Tools menu.

What do you want to do?

Get acquainted with VBScript by using the VBScript tutorial and reference.

See some sample macros


Using the Sample Macros

Home Page (Macros) | Overview | How Do I Topics | FAQ | Reference

The Visual C++ Developer Studio includes sample macros that illustrate how to automate tasks by using VBScript and the Developer Studio object model. The samples are in MSDEV98\macros\Sample.dsm, which is in the Microsoft Visual Studio\Common directory.

The following table briefly describes some of the sample macros. For details about them, see Sample.dsm.

Macro name | Purpose
AddRevisionMarks | Adds comments to a macro file, describing the changes made to it.
CloseExceptActive | Closes all editor windows except the current one.
CommentOut | Comments out a selected block of text. The type of comments added depend on the file's extension. For example, if the file has the .cpp or .c extension, the macro adds /* and */ comments.
MultiplePaste | Pastes whatever is on the Clipboard the number of times you specify.
ToggleCommentStyle | Alternates between the /* and //" comment styles.


Home Page: Developer Studio Add-ins

Home Page: Add-ins for the Visual C++ Developer Studio

Developer Studio add-ins are in-process COM components (DLLs) that you write in Visual C++ or Visual Basic. With add-ins, you can automate tasks in Developer Studio by adding commands to perform these tasks, by adding toolbar buttons to carry out these commands, and by responding to Developer Studio events.

For information about Developer Studio add-ins

  • Overviews

  • How Do I ... Topics

  • Frequently Asked Questions

  • Reference

Related Home Pages

  • VBScript Macros

  • Developer Studio objects

  • Customizing Visual C++


Overview: Add-ins for the Visual C++ Developer Studio

Home Page (Add-ins) | How Do I ... Topics | FAQ | Reference

With add-ins or VBScript macros, you can automate routine tasks in the Visual C++ Developer Studio environment. For example, you can update a project by automatically opening the project, changing some project files, saving the changes, and then rebuilding the project.

You automate tasks by using Automation (formerly OLE Automation). With Automation, the Visual C++ environment and its components become objects you can control programmatically. For example, windows become objects you can activate and size programmatically. Similarly, documents become objects you can open, edit, and close programmatically.

With add-ins, you automate tasks by adding commands to the Visual C++ environment. Each add-in can add one or more commands, and each command can perform one or more tasks. The number of commands and tasks is up to you.

Optionally, add-ins can provide toolbar buttons and key sequences to carry out their commands. Without buttons or key sequences, however, you must carry out the commands from the command line.

Creating an add-in is a three-step process. First, you write the code for the add-in. Second, you write code for adding commands, toolbar buttons, and key sequences. And third, you build and test the DLL for the add-in.

After creating an add-in, you connect it to the environment. As it connects, the add-in adds its commands, toolbar buttons, and key sequences to the development environment. Later, if the add-in is not needed, you can remove its commands, buttons, and key sequences by disconnecting the add-in.

To use an add-in, you carry out its commands by running them from the command line or by using the toolbar buttons or key sequences assigned to the commands.

What do you want to know more about?

The differences between add-ins and VBScript macros

The VBScript language

Designing add-ins

The process for creating add-ins

How add-ins connect and disconnect

How add-ins add commands, toolbar buttons, and key sequences

How add-in commands are carried out

Controlling Developer Studio objects through dual interfaces

What do you want to do?

Create an add-in using Visual C++

Create an add-in using Visual Basic


Designing Add-ins

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Before you create an add-in, you should consider the following design issues:

  • What tasks will the add-in perform?

  • Could you use a VBScript macro to perform these tasks?

    You can write a macro more quickly and easily than you can write an add-in. Before you begin, carefully consider the differences between macros and add-ins.

  • What commands will the add-in use to perform its tasks?

  • Which Developer Studio objects will you reference in the add-in's commands?

  • Which Developer Studio methods and properties will you use in the add-in's commands?

  • How many add-ins will you need?

    If you need several, you can combine them in the same DLL.

  • Will the add-in display windows or dialog boxes?

    An add-in can display modal windows or dialog boxes; however, it cannot display modeless windows or dialog boxes. For details, see the EnableModeless method.

  • Will the add-in handle events?

    An add-in can handle events fired by Developer Studio objects. Additionally, an add-in can display a dialog box containing ActiveX controls that fire events in the add-in. The controls' container (the dialog box or add-in) can handle the events.

  • Will the add-in control another application?

    An add-in can control another executable file (.EXE) by serving as an out-of-process controller for the other application.

  • Will the add-in have more than one thread?

    If you create a multithreaded add-in, the results are unpredictable. An add-in can have multiple threads if none of them has a message pump and only one thread accesses the Developer Studio object model.

  • Will the add-in carry out another add-in's commands?

  • Will the add-in have a Help file?

    Visual C++ cannot display a Help file created for an add-in. The add-in must expose a dedicated command to display a Help file.


The Process for Creating Add-ins

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Following is a summary of the process for creating an add-in. For step-by-step instructions, see How Do I ... Topics: Add-ins to the Visual C++ Developer Studio.

Note ATL objects in a Developer Studio Add-in project will cause a project build to fail. Therefore, you should avoid using the New ATL Object option in the Insert menu in a Developer Studio Add-in project.

  1. Decide which language to use.

    You can use Visual C++ or Visual Basic versions 4.0 or later. If you use Visual C++, you can use the included Developer Studio Add-in Wizard, which does most of the work for you.

    If you use Visual Basic, you must use the Developer Studio type libraries to access the Developer Studio object model. The names and locations of these libraries on your computer are as follows:

    • Build system (Microsoft Visual Studio\Common\MSDEV98\Bin\Ide\Devbld.pkg)

    • Debugger (Microsoft Visual Studio\Common\MSDEV98\Bin\Ide\Devdbg.pkg)

    • Developer Studio shell (Microsoft Visual Studio\Common\MSDEV98\Bin\Devshl.dll)

    • Text editor (Microsoft Visual Studio\Common\MSDEV98\Bin\Devedit.pkg)
  2. Create a project for the add-in.

    If you create a Visual C++ add-in with the Developer Studio Add-in Wizard, a project is created for you. If you create a Visual Basic add-in, start with one of the sample Visual Basic add-ins. For details, see Creating Add-ins Using Visual Basic.

  3. Write additional code for the add-in.

    If you use the Developer Studio Add-in Wizard or the Visual Basic samples, most of the code is already written — including the code that adds a command to the Visual C++ environment.

  4. Build the DLL from the source files the Add-in Wizard creates.

    Remember that you can combine several add-ins into one DLL.

  5. Connect the add-in to the Visual C++ environment.

    When you connect the add-in, it adds its commands to the Visual C++ development environment. For details, see Connecting Add-ins to the Development Environment.

  6. Carry out the commands added to the environment.

    You can run these commands from the command line, or you can carry them out by clicking toolbar buttons or pressing keys associated with the commands. For details, see Carrying Out Add-in Commands.


How Add-ins Connect and Disconnect

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

When Visual C++ starts, it automatically loads all add-ins checked on the Add-ins and Macro Files tab of the Customize dialog box (Tools menu, Customize command). Visual C++ loads each add-in by calling the OnConnection method exposed by the add-in's DSAddIn object. This method also makes the commands exposed by the add-in available for the user to carry out, and it connects the add-in to Developer Studio events if the add-in contains event handlers.

When Visual C++ quits, it unloads each add-in by calling the OnDisconnection method exposed by the add-in's DSAddIn object.

The DSAddIn Object

Each add-in exposes a DSAddIn object and a Commands object. The Visual C++ Developer Studio environment uses the DSAddIn object to connect to or disconnect from an add-in, and it uses the Commands object to carry out a command added by the AddCommand method.

An add-in exposes the DSAddIn object by implementing the COM IDSAddIn interface or the IDispatch IDispDSAddIn interface. An add-in written in Visual Basic version 4.0 must implement the IDispatch interface.

The COM interface is early bound by Developer Studio, whereas the IDispatch interface is late bound. The advantage of using the COM interface is that its early binding makes all calls into the interface faster at run time.

Note IDSAddIn is not a dual interface because it does not derive from IDispatch. It derives from IUnknown.

If an add-in provides a COM interface to its DSAddIn object, Developer Studio chooses it; otherwise, Developer Studio chooses an IDispatch interface. If neither interface is available, Developer Studio does not connect to the add-in.

To implement the COM interface, add-ins must use the following predefined Interface ID (IID), which is declared in Microsoft Visual Studio\VC98\Include\ObjModel\AddGuid.h:

// {C0002F81-AE2E-11cf-AD07-00A0C9034965}
DEFINE_GUID(IID_IDSAddIn,
0xc0002f81, 0xae2e, 0x11cf, 0xad, 0x7, 0x0, 0xa0, 0xc9, 0x3, 0x49, 0x65);

If you use the Developer Studio Add-in Wizard, it automatically generates the code to implement the COM interface. Similarly, if you use Visual Basic version 5.0 or later, the sample add-in includes this code.

The Commands Object

Each add-in exposes a DSAddIn object and a Commands object. Developer Studio uses the DSAddIn object to connect to or disconnect from an add-in, and it uses the Commands object to carry out a command added by the AddCommand method.

The Commands object exposes a method for each command added by AddCommand. This method specifies what the command does. You must write the code for the method.

If you use Visual C++, you can implement the Commands object by using the Developer Studio Add-in Wizard. This wizard automatically generates code for one method; however, if you need more methods you must add the code for them. For details, see Adding Commands to the Visual C++ Developer Studio.

If you use Visual Basic version 4.0 or later, you can implement the Commands object by copying code from the samples provided. However, each sample includes code for only one method, which displays a simple message box. If you need more methods, you must add the code for them.


How Add-ins Add Commands, Toolbar Buttons, and Key Sequences

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

While connecting to the Visual C++ Developer Studio environment, an add-in adds its commands to the environment. Optionally, the add-in can add toolbar buttons and key sequences for carrying out these commands.

The following table summarizes how an add-in adds commands, toolbar buttons, and key sequences.

To add | An add-in calls
A command | The AddCommand method
A toolbar button | The AddCommandBarButton method
A key sequence (key binding) | The AddKeyBinding method

Caution Unless key sequences are necessary, do not add them because they might replace existing ones. For example, if a keystroke is assigned to a command and you assign the same keystroke to another command, your new assignment replaces the original. For best results, let the user assign key sequences to the commands added by an add-in.

See Also Adding Commands to the Visual C++ Developer Studio, Creating Toolbar Buttons for Add-in Commands Programmatically, Assigning Key Sequences to Add-in Commands Programmatically


How Add-in Commands Are Carried Out

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

When a user carries out a command provided by an add-in, Developer Studio calls a method associated with the command. This method specifies what the command is supposed to do and is exposed by the Commands object associated with the add-in.

Developer Studio finds the method's name in the add-in's call to the AddCommand method, which added the command to Developer Studio. Then, Developer Studio calls the method by communicating with the add-in through the dispatch interface (dispinterface) implemented by the Commands object.

See Also Carrying Out Add-in Commands


Controlling Developer Studio Objects Through Dual Interfaces

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Each Developer Studio object implements a dual interface through which you can control the object. Each object implements an IDispatch interface for Automation and a COM interface for direct access to object members (properties, methods, and events).

The following table shows the dual interface used by each Developer Studio object.

Object | Dual interface
Application | Iapplication
Breakpoint | Ibreakpoint
Breakpoints | Ibreakpoints
BuildProject | IbuildProject
Configuration | Iconfiguration
Configurations | Iconfigurations
Debugger | Idebugger
Document | IgenericDocument
Documents | Idocuments
Project | IgenericProject
Projects | Iprojects
TextDocument | ItextDocument
TextSelection | ItextSelection
TextWindow | ItextWindow
Window | IgenericWindow
Windows | Iwindows

Add-ins written in Visual C++ versions 5.0 or later, or in Visual Basic versions 4.0 or later can employ early binding by using the COM interface. Early binding makes all calls into interface members faster at run time.

Alternating Between Dual Interfaces

In Visual C++, you can switch from one dual interface to another by calling QueryInterface. For example, to switch from the COM IGenericDocument interface on a TextDocument object to the COM ITextDocument interface, use the following code:

IGenericDocument* pDoc;
pApplication->get_ActiveDocument(&pDoc);
BSTR bstrType;
pDoc->get_Type(&bstrType)
if (!wcscmp(bstrType, L"Text"))
{
   // It is a text document,
   // ..so QI for the right interface
   ITextDocument* pTextDoc;
   pDoc->QueryInterface(IID_ITextDocument, &pTextDoc)
   // Now, we can use text-specific
   //   members of pTextDoc
   pTextDoc->Release();
}
SysFreeString(bstrType)
pDoc->Release();

Tip The ActiveX Template Library (ATL) provides smart COM pointers that can help you. See the CComPtr and CComQIPtr classes for details.

Using Return Values from Dual Interfaces

If a property or method of a Developer Studio object returns a value of type T, then the corresponding dual interface method returns an HRESULT but accepts an additional argument of type "pointer to T" (or T*). This argument is at the end of the argument list. For example, if a property returns a value of type Long, then the corresponding dual interface method accepts an additional argument of type "pointer to Long" (or Long*).

When the method returns, Developer Studio stores the return value where the last parameter points. For example, the Close method of the ITextWindow interface returns a DsSaveStatus value. The dual interface version of this method is declared as HRESULT Close (VARIANT boolSaveChanges, DsSaveStatus* pSaved). The last parameter, which is declared as DsSaveStatus*, is where Developer Studio stores the return value.

The Visual C++ code to do this looks like the following:

DsSaveStatus saveStatus;
if (myTxtWindow->Close(VARIANT_TRUE, &saveStatus) == S_OK)
{
   //code here could check the value of    //saveStatusreturned by Close
}

If the function succeeds, the HRESULT returned by the dual interface method is a success code like S_OK. If the function fails, however, the function returns an error code instead. This error code has the same value as one thrown in a dispatch exception when you call the method through the dispatch interface.

Tip The Developer Studio error codes are in the *defs.h header files, located in Microsoft Visual Studio\VC98\Include\ObjModel.

Manipulating Properties of Objects Through Dual Interfaces

To get a property of an object, prepend "get_" to the property name. Alternatively, to set the property of an object, prepend "put_" to the property name.

For example, to get the height of the Application object, prepend "get_" to the Height property, as shown in the following code:

long nHeight;
if (pApp->get_Height(&nHeight) == S_OK)
{
   //code here references the Height property through    //nHeight
}

Alternatively, to set the value of the Height property to 40, you would use the following code:

pApp->put_Height(40);

Calling Methods of Dual Interfaces

Some dual interface methods use parameters called "Reserved" of type VARIANT, and other methods use parameters that are optional. With VBScript macros or add-ins authored in Visual Basic, you can omit such parameters. However, with add-ins authored in Visual C++, you must use these parameters, you must pass a VT_ERROR VARIANT for each parameter, and you must specify the scode of the VARIANT as DISP_E_PARAMNOTFOUND.

For example, with MFC you can call the AddToolSettings method of the Configuration object by using the following code:

COleVariant var(0L,VT_ERROR);
var.scode=DISP_E_PARAMNOTFOUND;
pConfig->AddToolSettings(bszTool, bszSettings, var);

Some interfaces have methods called "Reserved1," "Reserved2," and so on. Do not use these methods.


How Do I ... Topics: Developer Studio Add-ins

How Do I ... Topics: Add-ins for the Visual C++ Developer Studio

Home Page (Add-ins) | Overview | FAQ | Reference

With add-ins, you automate tasks by adding commands to perform the tasks. You can also add toolbar buttons and key sequences to carry out the commands — giving them the same ease of use as other commands in the Visual C++ environment.

To create an add-in, you can use Visual C++ or Visual Basic. If you use Visual C++, you can employ the Developer Studio Add-in Wizard, which will do most of the work for you.

What do you want to know more about?

Designing add-ins

The process for creating add-ins

The results of the Developer Studio Add-in Wizard

What do you want to do?

Create an add-in using Visual C++

Create an add-in using Visual Basic

Build the DLL for an add-in

Connect an add-in to Developer Studio

Carry out add-in commands

Disconnect an add-in from Developer Studio


Creating Add-ins Using Visual C++

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

With Visual C++ versions 5.0 and later, the easiest way to create an add-in is to use the Developer Studio Add-in Wizard. This wizard creates the basic code, which you can modify to suit your needs.

Note The code created uses the ActiveX Template Library and the Microsoft Foundation Classes.

To create an add-in with Visual C++

  1. Design the add-in.

  2. On the File menu, click New.

  3. In the New dialog box, click the Projects tab.

  4. Select Developer Studio Add-in Wizard.

  5. In the Project Name box, enter a project name for the add-in, and then click OK.

  6. In the Developer Studio Add-in Wizard — Step 1 of 1 dialog box, do the following:
    • Enter a name and description for your add-in.

    • If you want a toolbar for buttons that carry out commands added by the add-in, check the Provides a toolbar box.

    • If you want event-handling code for the Developer Studio objects, check the Responds to Developer Studio events box.

      The wizard adds a code stub for each event. Then, you must complete the code for the events you want.

    • Click the Finish button.
  7. In the New Project Information dialog box, note the files created by the wizard and the directory in which the project is stored. Then, click OK.

    The wizard ends and Developer Studio displays the classes created for the add-in. For details about the files and classes produced by the wizard, see Understanding the Results of the Add-in Wizard.

  8. Customize the add-in command or add new commands.

    The Developer Studio Add-in Wizard automatically creates the code to add one command to Developer Studio. However, if you need to customize this command or add additional commands, you must modify the code. For details, see Adding Commands to the Visual C++ Developer Studio.

  9. Build the DLL for the add-in.

Tip Always unregister an add-in before changing it. For example, if you want to move an add-in to a new directory on your computer, or if you want to change its programmatic identifier (progID), unregister it beforehand. To unregister an add-in, go to the command line, go to the directory containing the add-in, and then type the command regsvr32 /u myAddIn.dll, where myAddIn is the name of the add-in.


Understanding the Results of the Add-in Wizard

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

The Developer Studio Add-in Wizard creates only the source files for an add-in. When you complete the add-in by building its project, Developer Studio creates a DLL from these source files.

Additionally, the Developer Studio Add-in Wizard creates classes for each add-in. These classes appear in the ClassView pane of the Project Workspace window and are graphical representations of what the source files contain. If you edit the classes, Developer Studio automatically changes the corresponding files.

Files Created by the Developer Studio Add-in Wizard

The Developer Studio Add-in Wizard creates multiple files for each add-in. The following table describes these files. Note that Add-in_name represents the name of the add-in created.

File name | Description
Add-in_name.h | Includes the principal header information for the add-in.
Add-in_name.cpp | Contains the main source code for the add-in DLL. This file includes the OLE entry points required by in-process servers.
Add-in_name.odl | Includes the Object Description Language source code for the type library created by the add-in.
Add-in_name.rc | Lists all Windows resources that the add-in uses. For example, this file includes the sample toolbar bitmap stored in the RES subdirectory. You can edit this file Visual C++.
Add-in_name.rc2 | Contains all resources that you cannot edit Visual C++.
Add-in_name.def | Includes definitions required for the add-in to run with Windows. This file contains parameters such as the name and description of the add-in. This file also exports functions from the add-in.
Add-in_name.clw | Contains information used by ClassWizard to edit existing classes or add new classes. ClassWizard also uses this file to store information needed to create and edit message maps and dialog box data maps and to create prototype member functions.
Commands.cpp and Commands.h | Contain the Ccommands class that implements the command dispatch interface defined by the Commands object. This interface contains one method for each command the add-in adds to the environment.
Dsaddin.cpp and Dsaddin.h | Includes the CDSAddIn class that implements the IDSAddIn interface defined by the DSAddIn object. This interface contains handlers for connecting the add-in to the development environment and disconnecting it from the environment.
Resource.h | Defines new resource IDs. This is the standard header file, and Visual C++ reads and updates this file.
Stdafx.h and Stdafx.cpp | Build the precompiled header file Add-in_name.pch.

Classes Created by the Developer Studio Add-in Wizard

The Developer Studio Add-in Wizard creates multiple classes for each add-in. When you open the add-in, these classes appear in the ClassView pane, and they represent the source files produced for the add-in. You can change the add-in by modifying these files or by adding members to these classes.

The following table describes these classes. Note that Add-in_name represents the name of the add-in created.

Class name | Description
CCommands | Implements the Icommands interface. In the CCommands class, you add the methods that Developer Studio uses to carry out commands added by the add-in.
CDSAddIn | Implements the IDSAddIn interface declared in header files provided with Visual C++. This interface exposes the DSAddIn object that the add-in uses to communicate with the development environment.
C add-in_name App | Registers and initializes the add-in.
ICommands | Specifies the interface defined by the Commands object. Through this interface, Visual C++ carries out commands added by the add-in.


Creating Add-ins Using Visual Basic

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

In addition to creating add-ins with Visual C++, you can create them with Visual Basic version 4.0 or later. The easiest way to create an add-in with Visual Basic is to start with the sample provided. The sample for Visual Basic version 4.0 is called VB4AddIn, and the sample for Visual Basic versions 5.0 or later is called VB5AddIn.

Add-ins created with Visual Basic version 5.0 (or later) have the following advantages over Visual Basic version 4.0:

  • Your add-in can handle events fired by the Application object. (In the sample code, the m_app member variable points to this object.)

  • The DSAddIn object implements the COM interface IDSAddIn rather than a dispatch interface. This results in faster calls from Developer Studio to your add-in's DSAddIn object.

Creating an add-in with Visual Basic can be divided into the following steps:

  1. Copy the sample files

  2. Name and describe the add-in

  3. Reference the Visual C++ Type libraries

  4. Modify the add-in code:
    • For connecting and disconnecting

    • For the command the add-in will run

    • To add the command to the Visual C++ environment

    • To create event handlers (optional)
  5. Build the add-in .DLL

Optionally, after creating an add-in project, you can employ early binding to optimize the add-in's performance.

Copying the Sample Add-in Files

To copy the sample add-in files

  • In the Visual C++ online documentation, open the topic Visual C++ Developer Studio Add-in Samples, and click the link of any sample to copy its project files to a new directory. You can specify the directory.

Naming and Describing the Add-in

To name and describe the add-in

  1. In Visual Basic, open the sample add-in project.

    Note that this project in Visual Basic is a .DLL project type. When you build it, you will build a .DLL.

  2. On the Project Properties dialog box, General tab, give the project a unique name.

  3. On the Project Properties dialog box, Make tab, give the application a unique title.

  4. In the Visual Basic Object Browser, from the Project/Library drop-down, select the add-in project (for example, VB5AddIn).

  5. Select the DSAddIn class, click the right mouse button, and select Properties from the popup menu.

  6. On the Member Options properties page, enter a name in the Description box and click OK.

    Once the add-in project is built, this name appears in Visual C++ on the Add-ins and Macros Files tab of the Customize dialog box (Tools menu, Customize Command).

  7. With the DSAddIn class still selected, click the Description property in the Members list box.

  8. Click the right mouse button and select Properties from the popup menu.

  9. On the Procedure Attributes properties page, enter a description in the Description edit control.

    Once the add-in project is built, this description also appears on the Add-ins and Macros Files tab of the Customize dialog box.

Referencing the Visual C++ Type Libraries

To reference the Visual C++ type libraries

  1. In the Visual Basic References dialog box (Project menu, References command), select the check boxes next to the Visual C++ type libraries.

    For Visual C++ version 5.0, their names begin with "Visual Studio 97." For Visual C++ version 6.0, their names begin with "Visual C++ 6.0."

  2. Click OK.

Modifying the Add-in Code

To customize your add-in, you can modify the code in several ways:

  • Modify the connection and disconnection code

  • Specify the actions the add-in command will perform

  • Add the command to the Visual C++ Developer Studio environment

  • Add event handlers (Visual Basic 5.0 or later)

Some of these steps are optional, or contain optional parts.

Modifying connection and disconnection code

Your add-in will connect to and disconnect from Developer Studio by using the OnConnection and OnDisconnection methods implemented in the DSAddIn class.

  • To view this code in Visual Basic 4.0, look for the connection and disconnection code in the General methods of the DSAddIn class.

  • To view this code in Visual Basic 5.0 or 6.0, look for the connection and disconnection code in the IDSAddIn member of the DSAddIn class.

In the samples, the connection code adds one command to the Visual C++ environment. You add more commands by calling the AddCommand method for each command you want to add (see Adding commands to the Visual C++ environment for details).

In the samples, the disconnection code does nothing; however, you might want to modify it to add clean-up code that destroys the objects you create.

Specifying the actions the add-in command will perform

The Commands class defines the actions performed by the commands you add to the Visual C++ environment. The samples define one action, which is to display a message box.

  • To view or modify this code, open the code editor for the Commands class, and choose the General section.

Adding the command to the Visual C++ environment

This consists of two steps for every command you add: Adding a public procedure to the Commands class, and adding a call to the AddCommand method. Optionally, you can create a toolbar button for the command.

To add a public procedure to the Commands class

  1. Open the code editor for the Commands class, and choose the General section.

  2. From the Tools menu, choose Add Procedure.

  3. Enter a name for the procedure, select the Sub and Public radio buttons, and click OK.

  4. Type the procedure in the code window.

To add a call to the AddCommand method

  • In the OnConnection code, add a call to the AddCommand method. (For more information, see Modifying connection and disconnection code.)

To create a toolbar button for the command

  1. Add an image for the button to the files Tbarmedm.bmp and Tbarlrge.bmp (located in the directory where you copied the add-in sample files).

  2. Reference the bitmap locations in the AddCommand call.

  3. If you want the button to automatically appear on your add-in's toolbar when you first connect the add-in to the Visual C++ environment, in the OnConnection code call the AddCommandBarButton method when the bFirstTime parameter is True.

Add event handlers (Visual Basic 5.0 or later)

  1. Open the code editor for the Commands class, and choose General from the Object drop-down list

  2. For each event replace the MsgBox command with your event-handling code.

Creating the Add-in DLL

To create the add-in DLL

  1. On the File menu, click Make <AddIn_Name>.dll ….

  2. Copy the resulting DLL into the \MSDEV98\AddIns directory.

Now when you return to Visual C++, the add-in appears on the Add-ins and Macros Files tab of the Customize dialog box (Tools menu, Customize Command). You can select it to view its name and description. You can run the add-in by using the toolbar button or key sequence you assign to it. For more information, see Carrying Out Add-in Commands.

Employing Early Binding

An add-in can employ early binding by using the COM interface. Early binding makes all calls into the interface faster at run time. In Visual Basic, you use early binding by declaring object variables as the appropriate types. For example, the following code accesses text-specific members of an object by declaring the MyTextDoc variable as TextDocument.

Dim MyDoc as Document
set MyDoc = Application.ActiveDocument
if (MyDoc.Type = "Text") then
   Dim MyTextDoc as TextDocument
   ' VB does an implicit QueryInterface
   ' for the following set
   set MyTextDoc = MyDoc
   ' Now, you can use text-specific members of
   ' MyTextDoc
End If


Adding Commands to the Visual C++ Developer Studio

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically creates the code for adding one command to the Visual C++ environment. However, if you want to add other commands, you must write additional code.

To add a command

  1. Open the add-in's project.

  2. In ClassView, expand the project's classes.

  3. Select the ICommands interface, and then click the right mouse button.

  4. Click the Add Method command.

  5. In the Method Declaration box, enter the method that specifies what the command is supposed to do.

  6. In ClassView, expand the CCommands class, and then double-click the method name.

  7. In the Commands.cpp file, write the code for the method.

  8. In ClassView, expand the CDSAddIn class.

  9. Double-click the OnConnection method.

  10. Search for code that adds a command. This code calls the AddCommand method.

  11. For the new command, copy and customize the AddCommand call.

  12. Optionally, provide a toolbar button the user can press to carry out the command. If you used the Developer Studio Add-in Wizard and selected the Provides a toolbar option, then the wizard generated the code needed to provide a button. However, if you didn't select that option, you must add the necessary code. For details, see Creating Toolbar Buttons for Add-in Commands Programmatically.

  13. Optionally, create an image for the toolbar button. If you used the Developer Studio Add-in Wizard and selected the Provides a toolbar option, then the wizard automatically created an image for the button. For details, see Creating Images for Toolbar Buttons.

  14. Optionally, assign a key sequence to the command. For details, see Assigning Key Sequences to Add-in Commands_Programmatically.


Creating Toolbar Buttons for Add-in Commands Programmatically

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

The user can carry out an add-in command by clicking a toolbar button assigned to the command. The user can create a button through the user interface, or you can create the button programmatically.

If you use the Developer Studio Add-in Wizard and select the Provides a toolbar option, the wizard automatically generates the code for the button. However, if you add more commands to the add-in, and you want buttons for these commands, you must add code for these buttons.

The following procedure describes how to add the code for a button.

To create a toolbar button programmatically

  1. Open the project for the add-in.

  2. In ClassView, expand the project's classes, and then expand the CDSAddIn class.

  3. Double-click the OnConnection method.

  4. Search for the code that adds the appropriate command. This code calls the AddCommand method.

  5. After the Addcommand call, call the AddCommandBarButton method if the bFirstTime parameter of the OnConnection method has a value of VARIANT_TRUE.

    This parameter directs Developer Studio to call AddCommandBarButton only when the user first connects the add-in to Developer Studio.

When the user removes an add-in from the Visual C++ environment, the add-in does not have to remove the toolbar buttons created because they are removed automatically.

Visual C++ provides other ways of using toolbar buttons to customize your desktop environment. For details, see Overview: Customizing Visual C++.

See Also Assigning Key Sequences to Add-in Commands Visually, Creating Toolbar Buttons for Add-in Commands Visually


Creating Images for Toolbar Buttons

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you select the Provides a toolbar option while using the Developer Studio Add-in Wizard, the wizard automatically generates images for toolbar buttons. You can use these images as they are, you can alter them in some way, or you can use other images of your choosing.

To create an image for a toolbar button

  1. In ResourceView, expand the project's resources, and then expand Bitmap.

  2. Use the default bitmaps in IDR_TOOLBAR_LARGE and IDR_TOOLBAR_MEDIUM.

    -or-

    Use the Image editor to alter the default bitmaps.

    -or-

    Use the Image editor to append new bitmaps to IDR_TOOLBAR_LARGE and IDR_TOOLBAR_MEDIUM.

  3. If you append new bitmaps to IDR_TOOLBAR_LARGE and IDR_TOOLBAR_MEDIUM, note the offset of the new bitmaps, and then update the bitmap offsets in the corresponding AddCommand calls.

    For example, the first image in the default bitmap has an offset of 0, and the second image in the default bitmap has an offset of 1. If you append a new image to the default bitmap, the new image has an offset of 2. To use the new image, change the bitmap offset in the appropriate AddCommand call from 0 to 2.


Creating Toolbar Buttons for Add-in Commands Visually

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you are using an add-in created by someone else, and it does not have a toolbar button, you can create one through the user interface.

To create a toolbar button through the user interface

  1. Connect the add-in to Developer Studio.

  2. On the Tools menu, click Customize.

  3. Click the Commands tab.

  4. In the Categories box, click Add-ins.

  5. Select a toolbar button.

    Tip When you select the button, it displays a description of the command carried out by the button.

  6. Drag the appropriate button to an existing toolbar, or drag it elsewhere in the main window to create a new toolbar for the button.

Additionally, Visual C++ provides other ways of using toolbar buttons to customize your desktop environment. For details, see Overview: Customizing Visual C++.

See Also Assigning Key Sequences to Add-in Commands Visually, Creating Toolbar Buttons for Add-in Commands Programmatically


Assigning Key Sequences to Add-in Commands Programmatically

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

The user can carry out an add-in command by using a key sequence assigned to the command. The user can assign this key sequence through the user interface, or you can assign it programmatically.

To assign a key sequence programmatically

  1. Open the project for the add-in.

  2. In ClassView, expand the project's classes, and then expand the CDSAddIn class.

  3. Double-click the OnConnection method.

  4. Search for code that adds the command. This code calls the AddCommand method.

  5. After the AddCommand call, insert a call to the AddKeyBinding method so that Developer Studio calls AddKeyBinding only when the bFirstTime parameter of the OnConnection method has a value of VARIANT_TRUE.

    The bFirstTime parameter directs Developer Studio to call AddKeyBinding only when the user first connects the add-in to the development environment.

Caution Unless key sequences are necessary, do not add them because they might replace existing ones. For example, if a keystroke is assigned to a command and you assign the same keystroke to another command, your new assignment replaces the original. For best results, let the user assign key sequences to the commands added by an add-in.

Additionally, Visual C++ provides other ways of using key sequences to customize your desktop environment. For details, see Overview: Customizing Visual C++.

See Also Assigning Key Sequences to Add-in Commands Visually, Creating Toolbar Buttons for Add-in Commands Programmatically


Assigning Key Sequences to Add-in Commands Visually

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you assign a key sequence to an add-in command, you can carry out that command by pressing the keys in that sequence. You can assign this key sequence through the Visual C++ user interface.

To assign a key sequence through the user interface

  1. Connect the add-in to the development environment.

  2. On the Tools menu, click Customize.

  3. Click the Keyboard tab.

  4. In the Categories box, click Add-ins.

  5. In the Commands box, select the add-in command you want to assign.

  6. Go to the Press new shortcut key box by clicking inside it.

  7. Press the key sequence you want to use for the add-in command.

  8. Click the Assign button.

    Visual C++ assigns that key sequence to the command.

Additionally, Visual C++ provides other ways of using key sequences to customize your desktop environment. For details, see Overview: Customizing Visual C++.

See Also Assigning Key Sequences to Add-in Commands Programmatically, Creating Toolbar Buttons for Add-in Commands Programmatically


Building the DLL for the Add-in

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you use the Developer Studio Add-in Wizard to create an add-in, the wizard creates source files for the add-in but does not build the DLL from these files.

To build the DLL for an add-in

  1. Open the project for the add-in.

  2. On the Build menu, click Build dll, where dll is the name of the DLL.


Connecting Add-ins to Developer Studio

Connecting Add-ins to the Development Environment

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

To run the commands in an add-in, you must first connect the add-in to the Visual C++ Developer Studio environment.

To connect an add-in to the environment

  1. On the Tools menu, click Customize.

  2. Click the Add-ins and Macro Files tab.

  3. Click the Browse button to locate the appropriate DLL.

    Tip Browsing is unnecessary if you put all DLLs in the Add-ins subdirectory of the MSDEV98 directory.

  4. Load the appropriate add-in by clicking the box next to its name.

    A check mark indicates that the add-in is loaded. This check mark also directs Visual C++ to automatically load the add-in when you start Visual C++ again.

    Warning If you remove the check mark from an add-in, you will unload it. When you unload it, the add-in loses all of its toolbar and keystroke assignments. Additionally, if you remove the check mark, Developer Studio will not automatically load the add-in when you start Developer Studio again.

See Also Disconnecting Add-ins from the Development Environment , How Add-ins Connect and Disconnect


Carrying Out Add-in Commands

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

After connecting an add-in to the development environment, you can carry out the add-in's commands by using toolbar buttons or key sequences assigned to the commands.

Additionally, you can carry out commands by running them from the command line.

To run a command from the command line

  • Type msdev –ex Command

    where Command is the name of the add-in command. This syntax Visual C++, and after the Visual C++ main window appears the command starts running.

    After the add-in command completes, Visual C++ continues running. If you want Visual C++ to end, then the add-in command must call the Application object's Quit method when it completes.

    Additionally, you can run a command according to a schedule. The following table shows how to schedule a command with Windows NT or Windows 95.

    To schedule a command | Do this
    With Windows NT Use the AT command to run

    msdev –ex Command

    For example, to run the command "MyAddin" at 1:00 A.M, use the command:

    AT 1:00am "msdev –ex MyAddin"

    The AT command is available only with Windows NT.
    With Windows 95 | You must have the Plus Pack to schedule commands. With the Plus Pack, use the System Agent to run msdev –ex Command.

See Also How Add-in Commands Are Carried Out


Disconnecting Add-ins from Developer Studio

Disconnecting Add-ins from the Development Environment

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you no longer want to use an add-in, you can disconnect it from the Visual C++ Developer Studio environment.

To disconnect an add-in from the environment

  1. On the Tools menu, click Customize.

  2. Click the Add-ins and Macro Files tab.

    The names of the add-ins appear in the window.

  3. Clear the check boxes next to the add-ins you want to disconnect.

    When you start Visual C++ again, these add-ins will no longer be available.

    Warning If you remove the check mark from an add-in, you will unload it. When you unload it, the add-in loses all of its toolbar and keystroke assignments. Additionally, if you remove the check mark, Visual C++ will not automatically load the add-in when you start Visual C++ again.

See Also Connecting Add-ins to Developer Studio, How Add-ins Connect and Disconnect


Frequently Asked Questions: Developer Studio Add-ins

Frequently Asked Questions: Add-ins for the Visual C++ Developer Studio

Home Page (Add-ins) | Overview | How Do I ... Topics | Reference

With add-ins, you can automate tasks in the Visual C++ Developer Studio environment by adding commands that perform these tasks. Following are some frequently asked questions about add-ins.

  • Can I write an add-in that uses VBScript as its language?

  • Do I need to use the Developer Studio type libraries to create an add-in?

  • Can an add-in display a window or dialog box?

  • Can an add-in control another application (.EXE)?

  • Can I create an add-in using a language other than Visual C++?

  • Can I create a multithreaded add-in?

  • Can one add-in carry out commands added by another add-in?

  • Can one DLL contain several add-ins?

  • Can I use add-ins shared on another computer?

  • Can Visual C++ display a Help file created for an add-in?

  • Can one add-in access another through the Developer Studio object model?


Can I Write a Developer Studio Add-in That Uses VBScript as Its Language?

Can I Write an Add-in That Uses VBScript as Its Language?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

No, you cannot write an add-in using VBScript. You can only write an add-in with languages that can create in-process automation servers. Such languages include Visual C++ and Visual Basic.


Do I Need to Use the Developer Studio Type Libraries to Create an Add-in?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you write the add-in in Visual Basic, you must use the Developer Studio type libraries to access the Developer Studio object model. These libraries contain definitions of all the objects, properties, methods, and events in the model.

Below are descriptions of the libraries and their locations on your computer:

  • Build system (Microsoft Visual Studio\Common\MSDEV98\Bin\Ide\Devbld.pkg)

  • Debugger (Microsoft Visual Studio\Common\MSDEV98\Bin\Ide\Devdbg.pkg)

  • Developer Studio shell (Microsoft Visual Studio\Common\MSDEV98\Bin\Devshl.dll)

  • Text editor (Microsoft Visual Studio\Common\MSDEV98\Bin\Devedit.pkg)

If you write the add-in in Visual C++, all you need are the header files provided with Visual C++. These files are in Microsoft Visual Studio\VC98\Include\ObjModel.


Can an Add-in Display a Window or Dialog Box?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Yes, an add-in can display a window or dialog box; however, the window or dialog box must be modal. Modeless windows or dialog boxes are not allowed because the add-in cannot have its own message pump.

Before displaying your modal windows or dialog boxes, call EnableModeless(FALSE) to disable modeless Visual C++ windows so that the add-in can display its modal windows or dialog boxes on top. When the add-in's modal windows are dismissed, call EnableModeless(TRUE) to reenable the modeless windows.


Can an Add-in Control Another Application?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Yes, an add-in can control another application (.EXE). The add-in must serve as an out-of-process controller for the other application, and the add-in must communicate with the .EXE across the process boundary.


Can I Create an Add-in Using a Language Other than Visual C++?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Yes, you can create an add-in using Visual Basic version 4.0 or later. For details, see Creating an Add-in Using Visual Basic.


Can I Create a Multithreaded Add-in?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

If you create more than one thread that accesses Developer Studio objects, the results are unpredictable. You might be able to create multiple threads if none of the threads has a message pump and only one thread accesses the Developer Studio object model at a time.


Can One Add-in Carry Out Commands Added by Another Add-in?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Yes, an add-in can carry out commands added by another add-in by calling the ExecuteCommand method. To carry out these commands, the add-in does not require compile-time knowledge of the other add-in.


Can One DLL Contain Several Add-ins?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

Yes, one DLL can contain several add-ins; however, these add-ins must be written in the same language. To create such a DLL, you must ensure that DllRegisterServer registers all DSAddIn objects in the DLL so that each object has a different CLSID and ProgID.

If a DLL contains multiple add-ins, each one could manipulate objects in different object models. For example, one add-in could manipulate Developer Studio objects, and another could manipulate Visual Basic objects.


Can I Use Add-ins Shared on Another Computer?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

No, you cannot use add-ins shared on another computer. For example, you can only carry out an add-in's commands on the computer to which the add-in is connected.


Can Developer Studio Display a Help File Created for an Add-in?

Can Visual C++ Display a Help File Created for an Add-in?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

No, Visual C++ does not support Help files for add-ins. However, an add-in could expose a command and toolbar button that causes the add-in to display a Help file itself.


Can One Add-in Access Another Through the Developer Studio Object Model?

Home Page (Add-ins) | Overview | How Do I ... Topics | FAQ | Reference

No, an add-in cannot access another add-in through the Developer Studio object model. An add-in can call the ExecuteCommand method to carry out another add-in's commands, but the add-in cannot control or get information about the other add-in.

Add-ins that have compile-time knowledge of each other can expose custom interfaces through which they can communicate with each other.


Reference: Developer Studio Add-ins

Reference: Add-ins for the Visual C++ Developer Studio

Home Page (Add-ins) | Overview | How Do I Topics | FAQ |

With add-ins, you can automate tasks in Visual C++ by adding commands to perform these tasks. The sample add-ins provided with Visual C++ illustrate some tasks you can automate.

To load an add-in, the Visual C++ Developer Studio environment calls the add-in's OnConnection method. When the environment shuts down, it unloads each add-in by calling the OnDisconnection method. Both methods are in the add-in's DSAddIn object.

What do you want to know more about?

The OnConnection method

The OnDisconnection method

The DSAddIn object


The OnConnection Method

Home Page (Add-ins) | Overview | How Do I Topics | FAQ | Reference

To load an add-in, the Visual C++ Developer Studio environment calls the add-in's OnConnection method. If you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically creates the code that implements the OnConnection method. In this code, the OnConnection method is in the CDSAddIn class located in the Dsaddin.cpp file.

The syntax for the OnConnection method is:

VARIANT BOOL OnConnection ( Application* pApp, VARIANT BOOL bFirstTime, Long dwCookie )

Developer Studio first passes a pointer (Application*) to the dual interface on the Developer Studio Application object.

Additionally, Developer Studio provides a cookie. The add-in uses this cookie to identify itself in subsequent calls to Developer Studio. For example, the add-in uses this cookie to call the AddCommand method.

To connect, the add-in takes the following steps. If you use the Developer Studio Add-in Wizard, it automatically implements these steps:

  1. Uses the pApp parameter to ensure that required objects in the Developer Studio object model are installed. If required objects are not available, the add-in returns VARIANT_FALSE, indicating that it should not be loaded.

    Note Because OnConnection is a COM method, it does not use the typical Visual C++ BOOL type (TRUE or FALSE). Instead it uses the VARIANT_BOOL type (VARIANT_TRUE or VARIANT_FALSE).

  2. Uses the bFirstTime parameter to determine if this is the first time the add-in has been loaded into the environment. If it is the first time, bFirstTime is VARIANT_TRUE, and the add-in can add new toolbar buttons or key sequences for carrying out its commands. Note that if you disconnect the add-in and then reconnect it, bFirstTime is also VARIANT_TRUE.

    Tip You only need to add toolbar buttons and keybindings the first time an add-in is loaded because the environment keeps track of them in subsequent loads.

  3. Provides information about itself by calling the SetAddInInfo method. If the add-in fails to provide the required information, the environment unloads the add-in by calling the add-in's OnDisconnection method. Then, the environment displays a message box describing what the add-in failed to do.

  4. Connects to events. The add-in locates the appropriate Developer Studio objects and then connects to their events. The Developer Studio Add-in Wizard automatically generates the code for handling events if you choose the Responds to Developer Studio events option.

  5. Adds commands by calling the AddCommand method.

  6. Stores the cookie and the pointer (Application*) to the Application object for future use. To store the pointer, the add-in must explicitly call the AddRef function. Storing is recommended because the environment will not pass the pointer to the add-in again.

  7. Returns VARIANT_TRUE, indicating that the add-in loaded successfully.


The OnDisconnection Method

Home Page (Add-ins) | Overview | How Do I Topics | FAQ | Reference

When Visual C++ shuts down, the environment unloads each add-in by calling the OnDisconnection method. If you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically creates the code that implements the OnDisconnection method. In this code, the OnDisconnection method is in the CDSAddIn class located in the Dsaddin.cpp file.

The syntax for the OnDisconnection method is:

void OnDisconnection ( VARIANT_BOOL bLastTime )

To disconnect, the add-in does the following:

  1. Examines the bLastTime parameter to determine why it is unloading. VARIANT_TRUE means that the user is removing (uninstalling) it. VARIANT_FALSE means only that the Visual C++ environment is exiting.

  2. Disconnects from events.

  3. Releases the pointer (Application*) to the dual interface on the Developer Studio Application object — if it stored the pointer while connecting to the environment.

  4. Performs housekeeping tasks such as deallocating memory, freeing resources, and so on.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.