Copyright: Copyright © 1999 Inprise Corporation.                      All rights reserved.                                                 This Help file was compiled on   Wednesday, January 20, 1999 19:38:42.


Your first application--a brief tutorial
Your first application—a brief tutorial

Topic groups

The quickest way to introduce yourself to C++Builder is to write an application. This tutorial guides you through the creation of a program that navigates a marine-life database. After setting up access to the database, you’ll write an event handler that opens a standard Save As dialog box, allowing you to write information from the database to a file.


Starting a new application

Topic groups

Before beginning a new application, create a folder to hold the source files.

1	Create a folder called Marine in the Projects directory off the main C++Builder directory.

2	Open a new project.

Each application is represented by a project. When you start C++Builder, it opens a blank project by default. If another project is already open, choose File|New Application to create a new project.

When you open a new project, C++Builder automatically creates the following files.

Project1.CPP: a source-code file associated with the project.

Unit1.CPP: a source-code file associated with the main project form. This is called a unit file.

Unit1.DFM: a resource file that stores information about the main project form. This is called a form file.

Each form has its own unit and form files.

3	Choose File|Save All to save your files to disk. When the Save dialog appears, navigate to your Marine folder and save each file using its default name.

Later on, you can save your work at any time by choosing File|Save All.

When you save your project, C++Builder creates additional files, including a project (.BPR) file.

When you open a new project, C++Builder displays the project’s main form, named Form1 by default. You’ll create the user interface and other parts of your application by placing components on this form.

The default form has Maximize and Minimize buttons, a Close button, and a Control menu. If you run the form now by pressing F9, you’ll see that these buttons all work. (To return to design mode, click the X to close the form.)

Next to the form, you’ll see the Object Inspector, which you can use to set property values for the form and components you place on it.


Setting property values

Topic groups

When you use the Object Inspector to set properties, C++Builder maintains your source code for you. The values you set in the Object Inspector are called design-time settings.

Set the background color of Form1 to Aqua.

Find the form’s Color property in the Object Inspector and click the drop-down list displayed to the right of the property. Choose clAqua from the list.


Adding objects to the form

Topic groups

The Component palette represents components by icons grouped onto tabbed pages. Add a component to a form by selecting the component on the palette, then clicking on the form where you want to place it. You can also double-click a component to place it in the middle of the form.

Add a Table and a StatusBar to the form:

1	Drop a Table component onto the form.

Click the Data Access tab on the Component palette. To find the Table component, point at an icon on the palette for a moment; C++Builder displays a Help hint showing the name of the component.

When you find the Table component, click it once to select it, then click on the form to place the component. The Table component is nonvisual, so it doesn’t matter where you put it. C++Builder names the object Table1 by default. (When you point to the component on the form, C++Builder displays its name—Table1—and the type of object it is—TTable.)

Each C++Builder component is a class; placing a component on a form creates an instance of that class. Once the component is on the form, C++Builder generates the code necessary to construct an instance object when your application is running.

2	Set the DatabaseName property of Table1 to BCDEMOS. (BCDEMOS is an alias to the sample database that you’re going to use.)

Select Table1 on the form, then choose the DatabaseName property in the Object Inspector. Select BCDEMOS from the drop-down list.

3	Double-click the StatusBar component on the Win32 page of the Component palette. This adds a status bar to the bottom of the application.

4	Set the AutoHint property of the status bar to true. The easiest way to do this is to double-click on false next to AutoHint in the Object Inspector. (Setting AutoHint to true allows Help hints to appear in the status bar at runtime.)


Connecting to a database

Topic groups

The next step is to add database controls and a DataSource to your form.

1	From the Data Access page of the Component palette, drop a DataSource component onto the form. The DataSource component is nonvisual, so it doesn’t matter where you put it on the form. Set its DataSet property to Table1.

2	From the Data Controls page, choose the DBGrid component and drop it onto your form. Position it in the lower left corner of the form above the status bar, then expand it by dragging its upper right corner.

If necessary, you can enlarge the form by dragging its lower right corner.

3	Set DBGrid properties to align the grid with the form. Double-click Anchors in the Object Inspector to display akLeft, akTop, akRight, and akBottom; set them all to true.

4	Set the DataSource property of DBGrid to DataSource1 (the default name of the DataSource component you just added to the form).

Now you can finish setting up the Table1 object you placed on the form earlier.

5	Select the Table1 object on the form, then set its TableName property to BIOLIFE.DB. (Name is still Table1.) Next, set the Active property to true.

When you set Active to true, the grid fills with data from the BIOLIFE.DB database table. If the grid doesn’t display data, make sure you’ve correctly set the properties of all the objects on the form, as explained in the instructions above. (Also verify that you copied the sample database files into your ...\Borland Shared\Data directory when you installed C++Builder.)

The DBGrid control displays data at design time, while you are working in the IDE. This allows you to verify that you’ve connected to the database correctly. You cannot, however, edit the data at design time; to edit the data in the table, you’ll have to run the application.

6	Press F9 to compile and run the project. (You can also run the project by clicking the Run button on the Debug toolbar, or by choosing Run from the Run menu.)

In connecting our application to a database, we’ve used three components and several levels of indirection. A data-aware control (in this case, a DBGrid) points to a DataSource object, which in turn points to a dataset object (in this case, a Table). Finally, the dataset (Table1) points to an actual database table (BIOLIFE), which is accessed through the BDE alias BCDEMOS. (BDE aliases are configured through the BDE Administrator.)

This architecture may seem complicated at first, but in the long run it simplifies development and maintenance. For more information, see Developing database applications.


Adding support for a menu and a toolbar

Topic groups

When you run your project, C++Builder opens the program in a window like the one you designed on the form. The program is a full-fledged Windows application, complete with Minimize, Maximize, and Close buttons and a Control menu. You can scroll through the BIOLIFE data in the grid.

Though your program already has a great deal of functionality, it still lacks many features usually found in Windows applications. For example, most Windows applications implement menus and toolbars to make them easy to use.

In this section, you’ll prepare your application for additional graphical-interface elements by setting up an ActionList component. While you can create menus, toolbars, and buttons without using action lists, action lists simplify development and maintenance by centralizing responses to user commands.

1	Click the X in the upper right corner to close the application and return to the design-time view of the form.

2	From the Win32 page of the Component palette, drop an ImageList onto the form. This is a nonvisual component, so it doesn’t matter where you place it. The ImageList will contain icons that represent standard actions like Cut and Paste.

3	From the Standard page of the Component palette, drop an ActionList onto the form. This is another nonvisual component.

4	Set the action list’s Images property to ImageList1.

5	Double-click the action list to display the Action List editor.

6	Right-click on the Action List editor and choose New Standard Action. The Standard Actions list box is displayed.

7	Select the following actions: TDataSetFirst, TDataSetLast, TDataSetNext, TDataSetPrior, TEditCopy, TEditCut, and TEditPaste. (Use the Ctrl key to select multiple items.) Then click OK.

8	Click on the X to close the Action List editor.

You’ve added standard actions. Now you’re ready to add the menu and toolbar.


Adding a menu

Topic groups

In this section, you’ll add a main menu bar with three drop-down menus—File, Edit, and Record—and you’ll add menu items to each one using the standard actions in the action list.

1	From the Standard page of the Component palette, drop a MainMenu component onto the form. It doesn’t matter where you place it.

2	Set the main menu’s Images property to ImageList1.

3	Double-click the menu component to display the Menu Designer.

4	Type &File to set the Caption property of the first top-level menu item and press Enter.

5	Type &Save and press Enter to create a Save menu item under File.

6	Type a hyphen in the next item under the File menu and press Enter to create a separator bar on the menu.

7	Type E&xit and press Enter to create an Exit menu item under File.

8	Click on the second top-level menu item (to the right of File), type &Edit, and press Enter. The first menu item under Edit is selected.

In the Object Inspector, set its Action to EditCut1 and press Enter. The item’s caption is automatically set to Cut.

Select the next menu item (under Cut) and set its Action to EditCopy1.

Select the next menu item and set its Action to EditPaste1.

9	Click on the third top-level menu item (to the right of Edit), type &Record, and press Enter. The menu item under Record is selected.

In the Object Inspector, set its Action to DataSetFirst1.

Select the next menu item and set its Action to DataSetPrior1.

Select the next menu item and set its Action to DataSetNext1.

Select the next menu item and set its Action to DataSetLast1.

10	Click on the X to close the Menu Designer.

Press F9 to run your program and see how it looks.

Close the application when you’re ready to continue.


Adding a toolbar

Topic groups

1	On the Win32 page of the Component palette, double-click the ToolBar to add it to the form.

Set the toolbar’s Indent property to 4.

Set its Images property to ImageList1.

Set ShowHint to True.

2	Add buttons to the toolbar.

With the toolbar selected, right-click and choose New Button three times.

Right-click and choose New Separator.

Right-click and choose New Button four more times.

3	Assign actions to the first set of buttons.

Select the first button and set its Action to EditCut1.

Select the second button and set its Action to EditCopy1.

Select the third button and set its Action to EditPaste1.

4	Assign actions to the second set of buttons.

Select the first button and set its Action to DataSetFirst1.

Select the second button and set its Action to DataSetPrior1.

Select the third button and set its Action to DataSetNext1.

Select the last button and set its Action to DataSetLast1.

5	Press F9 to compile and run the project.

Check out the toolbar. The First, Prior, Next, and Last buttons work. Select text within a cell in the grid; the Cut, Copy, and Paste buttons work as well.

Close the application when you’re ready to continue.


Displaying images

Topic groups

Each record in the BIOLIFE database has a picture associated with it. In this section, we’ll expand our application to display pictures.

1	From the Standard page of the Component palette, drop a Panel component onto the form below the toolbar. C++Builder names this Panel1 by default.

2	In the Object Inspector, delete the Panel1 string from the panel’s Caption property. Leave the Caption property blank.

3	Align Panel1 to the top of the form by setting its Align property to alTop. Next, drag the bottom of the panel down so it fills the portion of the form between the toolbar and the grid.

4	Set the panel’s color to clBlue.

5	From the Data Controls palette page, drop a DBImage component on top of Panel1 and set its Align property to alRight. Size the DBImage by dragging out its left side so your form resembles the one shown in the following figure.

6	Set the DataSource property of DBImage to DataSource1. Then set its DataField property to Graphic. (In the Object Inspector, the drop-down list next to DataField shows the fields in the BIOLIFE table. Graphic is one of the field names.)

As soon as you set DataField to Graphic, the DBImage component displays the image of a fish corresponding to the first record of the table. This shows that you have correctly hooked up to the database.

7	Press F9 to compile and run your application.

Close the application when you’re ready to continue.


Adding text and memo objects

Topic groups

In this section, you’ll add two components that display individual text fields from the database.

1	Select Panel1.

2	From the Data Controls page of the Component palette, drop a DBMemo component onto Panel1 and position it so it occupies the upper left corner of the panel (below the menus and toolbar).

3	Resize the DBMemo by dragging its lower right corner. Extend the right edge of the DBMemo until it touches the left edge of the DBImage. Extend the bottom of the DBMemo to within a half inch or so of the bottom of Panel1.

4	In the Object Inspector, set the following properties for the DBMemo.

Set DataSource to DataSource1.

Set DataField to Notes.

Set ScrollBars to ssVertical.

5	Drop a DBText component on Panel1 under the DBMemo object. Enlarge the DBText so it fills the area under the DBMemo, then set its properties as follows.

Set DataSource to DataSource1.

Set DataField to Common_Name.

Set Alignment to taCenter.

6	Customize the Font property of the DBText component using the Font editor.

The Font editor is a property editor that you can access through the Object Inspector. Select the Font property in the Object Inspector; an ellipsis button appears on the right side of the property setting. Click the ellipsis button to display the Font editor.

Modify the following DBText settings using the Font editor, then click OK.

Set the Font Style to Bold.

Set the Color to Silver.

Set the Size to 12.

7	Compile and run your application by pressing F9.

You can view and edit the data in the DBMemo component. The DBText component displays data for reading only.

Close the application when you’re ready to continue.


Writing an event handler

Topic groups

Up to this point, you’ve developed your application without writing a single line of code. By using the Object Inspector to set property values at design time, you’ve taken full advantage of C++Builder‘s RAD environment. In this section, however, you’ll write functions called event handlers that respond to user input while the application is running. You’ll connect the event handlers to menu items, so that when a menu item is selected your application executes the code in the handler.

1	From the Dialogs page of the Component palette, drop a SaveDialog component onto the form. This is a nonvisual component, so it doesn’t matter where you place it. C++Builder names it SaveDialog1 by default. (When SaveDialog‘s Execute method is called, it invokes a standard Windows dialog for saving files.)

2	Choose File|Save from the menu at the top of your form. C++Builder creates a skeleton event handler for the event that occurs at runtime when the user selects Save from the File menu. The Code editor opens with the cursor inside the event handler.

This event handler is attached to the OnClick event of the main menu’s first menu item. The menu item is an instance of the class TMenuItem, and OnClick is its default event. Hence the Save1Click method is a default event handler.

3	Complete the event handler by adding the code shown below between the outermost pair of braces.

void __fastcall TForm1::Save1Click(Tobject *Sender)

{

  FILE *outfile;

  char buff[100];

  sprintf(buff, "Save Info For: %s", DBText1->Field->AsString.c_str());

  SaveDialog1->Title = buff;

  if (SaveDialog1->Execute())

  {

    outfile = fopen(SaveDialog1->FileName.c_str(), "wt");

    if (outfile)

    {

      fprintf(outfile, "Facts on the %s\n\n",

        DBText1->Field->AsString.c_str());

      for (int i=0; i < DBGrid1->FieldCount; i++)

        fprintf(outfile, "%s: %s\n",

          DBGrid1->Fields[i]->FieldName.c_str(),

          DBGrid1->Fields[i]->AsString.c_str());

      fprintf(outfile, "\n%s\n", DBMemo1->Text.c_str());

    }

    fclose(outfile);

  }

}

This event handler calls the Execute method in the SaveDialog component. When the dialog box opens and the user specifies a file name, it saves fields from the current database record into a file.

This code uses file I/O from the standard library. Before compiling it, add

#include <stdio.h>

to the top of the unit file.

4	To add code for the Exit command, choose File|Exit. C++Builder generates another skeleton event handler and displays it in the editor.

void __fastcall TForm1::Exit1Click(TObject *Sender)

{

}

Right where the cursor is positioned (between the braces), type

  Close();

5	Choose File|Save All to save your work. Then press F9 to run the application.

You can exit the program using the now functional File|Exit command.

Most components on the Component palette have events, and most components have a default event. A common default event is OnClick, which gets called whenever the component is clicked; for example, if you placed a Button component (TButton) on a form, you would almost certainly write an OnClick event handler for it. When you double-click certain objects on a form, C++Builder creates a skeleton handler for the default event.

You can also access all of a component’s events through the Object Inspector. Select an object on a form, then click the Events tab on the object Inspector; you’ll see a list of the object’s events. To create a skeleton handler for any event, double-click in the space to its right.

For more information about events and event handlers, see Developing the application user interface.


Related topic groups

Quick Start Tutorial

•	Your first application: a brief tutorial


Your first application: a brief tutorial

Related topic groups

•	Your first application--a brief tutorial

•	Starting a new application

•	Setting property values

•	Adding objects to the form

•	Connecting to a database

•	Adding support for a menu and a toolbar

•	Adding a menu

•	Adding a toolbar

•	Displaying images

•	Adding text and memo objects

•	Writing an event handler


Breakpoint List

See also

The Breakpoint List shows all breakpoints currently set in the loaded project. (If no project is loaded, it shows all breakpoints set in the active Code editor page or in the CPU window.) The Breakpoint List shows:

For Source Breakpoints:	The file name and line number location along with any condition and pass count associated with each breakpoint.

For Address Breakpoints:	The file name and line number + a hex offset. The offset is the number of bytes from the source line the address breakpoint is. If no corresponding file line number is found, a raw address is used.

For Data Breakpoints:	The data name or address location and length.

The Breakpoint List also shows conditions associated with the breakpoint and the pass count (including the total pass count and the current pass count).

The Breakpoint List also lets you add, edit, delete, and enable or disable breakpoints. A breakpoint appears grayed if it is either disabled or invalid.

To display the Breakpoint List, choose View|Debug Windows|Breakpoints. Right-click in the Breakpoint List to display the context menu commands.


Breakpoint List context menu

See also

Use the Breakpoint List context menu to access commands that enable you to manipulate breakpoints. The context menu offers two sets of commands depending on whether or not you have highlighted a listed breakpoint.

The following commands appear on the Breakpoint List context menu:

Add	Opens dialog boxes where you can create new breakpoints.

Delete All	Removes all breakpoints

Disable All	Disables all enabled breakpoints

Enable All	Enables all disabled breakpoints

Dockable	Toggles whether the Breakpoint List is dockable

The following commands are available when you right-click on a defined breakpoint:

Enabled	Enables a disabled breakpoint

Delete	Removes a breakpoint

View Source	Locates a breakpoint in your source code quickly

Edit Source	Locates a breakpoint in your source code quickly and activates the Code editor

Properties	Opens dialog boxes, where you can modify breakpoints

Dockable	Toggles whether the Breakpoint List is dockable

To display the Breakpoint List context menu:

Choose View|Breakpoints to display the Breakpoint List, then do one of the following:

Right-click anywhere in the Breakpoint List.

Press Alt+F10 when the Breakpoint List is active.


Add Breakpoint (Breakpoint List context menu)
Add (Breakpoint List context menu)

See also

Choose Add from the Breakpoint List context menu to open dialog boxes where you can create new breakpoints.

Add opens a different dialog box, as follows:

For Source Breakpoints:	Opens the Add Source Breakpoint dialog box.

For Address Breakpoints:	Opens the Add Address Breakpoint dialog box.

For Data Breakpoints:	Opens the Add Data Breakpoint dialog box.

An alternate way to perform this command is choose Run|Add Breakpoint.


Delete Breakpoint (Breakpoint List context menu)
Delete (Breakpoint List context menu)

See alsot

Choose Delete from the Breakpoint List context menu to remove the selected breakpoint.

When you no longer need to examine the code at a breakpoint location, you can delete the breakpoint from the debugging session. This command is not reversible.


Enable Breakpoint (Breakpoint List context menu)
Enabled (Breakpoint List and Code editor context menu)

See alsot

Choose Enabled from the Breakpoint List or Code editor context menu to toggle a breakpoint on or off. The breakpoint is enabled when the option is checked.

Disabling a breakpoint hides the breakpoint from the current program run. When you disable a breakpoint, its settings remain defined, but the breakpoint does not cause your program to stop. When you set a breakpoint, it is enabled by default. Disabling is useful when you temporarily do not need a breakpoint but want to preserve its settings.


View Source (Breakpoint List context menu)

See alsot

Choose View Source from the Breakpoint List context menu to locate a breakpoint in your source code or an address breakpoint in the CPU window.

The View Source command scrolls the Code editor to the location of the source breakpoint that is selected in the Breakpoint List, or it scrolls the CPU window to the location of the address breakpoint that is selected in the Breakpoint List.


Edit Source (Breakpoint List context menu)

See alsot

Choose Edit Source from the Breakpoint List context menu to locate a source breakpoint in your source code or an address breakpoint in the CPU window.

If a source breakpoint is selected in the Breakpoint List, the Edit Source command scrolls the Code editor to the location of the breakpoint and activates the Code editor. If an address breakpoint is selected in the Breakpoint List, the Edit Source command scrolls the CPU window to the location of the breakpoint and activates the CPU window.


Disable All Breakpoints (Breakpoint List context menu)
Disable All (Breakpoint List context menu)

See alsot

Choose Disable All from the Breakpoint List context menu to disable all enabled breakpoints.

Disabling a breakpoint hides the breakpoint from the current program run. When you disable a breakpoint, its settings remain defined, but the breakpoint does not cause your program to stop. When you set a breakpoint, it is enabled by default. Disabling is useful when you temporarily do not need a breakpoint but want to preserve its settings.


Enable All Breakpoints (Breakpoint List context menu)
Enable All (Breakpoint List context menu)

See alsot

Choose Enable All to enable all disabled breakpoints.

Disabling a breakpoint hides the breakpoint from the current program run. When you disable a breakpoint, its settings remain defined, but the breakpoint does not cause your program to stop. When you set a breakpoint, it is enabled by default.

Disabling is useful when you temporarily do not need a breakpoint but want to preserve its settings.


Delete All Breakpoints (Breakpoint List context menu)
Delete All (Breakpoint List context menu)

See alsot

Choose Delete All from the Breakpoint List context menu to remove all breakpoints.

When you no longer need to examine the code at a breakpoint location, you can delete the breakpoint from the debugging session. This command is not reversible.


Edit Breakpoint (Breakpoint List context menu)
Properties (Breakpoint List context menu)

See alsot

Choose Properties from the Breakpoint List context menu to open dialogs that allow you to modify or add new breakpoints:

For source breakpoints	Opens the Source Breakpoint Properties

For address breakpoints	Opens the Address Breakpoint Properties.

For data breakpoints	Opens the Data Breakpoint Properties.


Call Stack window

See also

The Call Stack window displays the function calls that brought you to your current program location and the arguments passed to each function call.

The top of the Call Stack window lists the last function called by your program. Below this is the listing for the previously called function. The listing continues, with the first function called in your program located at the bottom of the list. If debug information is available for a function listed in the window, it is followed by the arguments that were passed when the call was made.

The Call Stack window also shows the names of member functions (or methods). Each member function is prefixed with the name of the class that defines the function.

Call Stack commands

Use the Call Stack context menu to access commands that enable you to examine previous function calls.

The commands on the Call Stack List context menu are:

View Source	Locates a function call in your source code quickly

Edit Source	Locates a function call in your source code quickly, and activates the Code editor

Stay On Top	Keeps the Call Stack window visible when out of focus

Dockable	Toggles the Call Stack window so that it can be docked or not

To display the Call Stack context menu:

Choose View|Debug Windows|Call Stack to display the Call Stack window, then do one of the following:

Right-click anywhere in the Call Stack window.

Press Alt+F10 when the Call Stack window is active.


View Source (Call Stack context menu)

See alsot

Choose View Source from the Call Stack context menu to locate a function call in your source code quickly.

The View Source command scrolls the Code editor to the location of the function call that is selected in the Call Stack window but does not give the Code editor focus.


Edit Source (Call Stack context menu)

See also

Choose Edit Source from the Call Stack context menu to locate a function call in your source code quickly.

The Edit Source command scrolls the Code editor to the location of the function call that is selected in the Call Stack window, and makes the Code editor active.


About the Component palette

See also

Components are the building blocks of every VCL-based application, and the basis of the Visual Component Library. Each page tab in the Component palette displays a group of icons representing the components you can use to design your application interface. To add a component to an open form, double-click it, then set its properties and code its event handlers.

The Component palette’s Help Hints feature displays a small pop-up window containing the name or brief description of the button when your cursor is over the button for longer than one second. To enable Help Hints, choose Show Hints from the Component palette context menu.

Components may be either visual or nonvisual. Each component has specific attributes that enable you to control your application: Properties, Events, and Methods.

To get Help on a specific component, click the component and press F1.

The default page tabs divide components into the following functional groups:

Standard components

Additional components

Win32 components

System components

Internet components

Data Access components

Data Controls components

MIDAS components

Decision Cube components

QReport components

Dialogs components

Win 3.1 components

Samples components

ActiveX components


Standard page components

See also	Other Palette pages

The components on the Standard page of the Component palette make the standard Windows control elements available to your applications:

MainMenu	Creates menu bar menus for your form. To access events for items in a main menu, add the MainMenu component to a form and double-click it to open the Menu Designer

 	PopupMenu	Creates popup menus that appear when the user right-clicks. To access events for items in a popup menu, add the PopupMenu component to a form and double-click it to open the Menu Designer.

Label	Displays text that the user cannot select or manipulate, such as title text or control labels. See About Label.

Edit	Displays an editing area where the user can enter or modify a single line of text. Edit is one of several Text controls.

Memo	Displays an editing area where the user can enter or modify multiple lines of data. See About Memo.

Button	Creates a pushbutton control that users choose to initiate actions. See About Button.

CheckBox	Presents an option that a user can toggle between Yes/No or True/False. Use check boxes to display a group of choices that are not mutually exclusive. Users can select more than one check box in a group. See About CheckBox.

RadioButton	Presents an option that a user can toggle between Yes/No or True/False. Use radio buttons to display a group of choices that are mutually exclusive. Users can select only one radio button in a group. See About RadioButton.

ListBox	Displays a scrolling list of choices. See About ListBox and Properties common to list controls.

ComboBox	Displays a list of choices in a combined list box and edit box. Users can enter data in the edit box area or select an item in the list box area. See About ComboBox.

ScrollBar	Provides a way to change the viewing area of a list or form. You can also use a scroll bar to move through a range of values by increments. See About Scrollbar.

GroupBox	Provides a container to group-related options on a form. See About GroupBox.

 	RadioGroup	Creates a group box that contains radio buttons on a form. See About RadioGroup.

Panel	Creates panels that can contain other components on a form. You can use panels to create toolbars and status-lines. See About Panel.

ActionList	Creates collections of actions that centralize your application’s responses to user actions. See Using action lists.


Additional page components

See also	Other Palette pages

The components on the Additional page of the Component palette make specialized Windows control elements available to your applications:

BitBtn	Creates a button component that can display a bitmap. See Bitmap Buttons.

SpeedButton	Provides a button that can display a glyph but not a caption. Speed buttons can be grouped within a panel to create a tool palette. See Speed Buttons.

MaskEdit	Allows user to enter and edit data, similar to an edit component, but provides a means to specify particular formats, such as a postal code or phone number. MaskEdit shares the properties of other Text controls.

StringGrid	Creates a grid that you can use to display string data in columns and rows. StringGrid.is a superset of the features provided by the DrawGrid component. See String grids.

DrawGrid	Creates a grid that you can use to display data in columns and rows. See Draw Grids.

Image	Displays a bitmap, icon, or metafile. See Adding an image control.

Shape	Draws geometric shapes including an ellipse or circle, a rectangle or square, or a rounded rectangle or rounded square. See About Shape.

Bevel	Creates lines or boxes with a three-dimensional, chiseled appearance. See About Bevel.

ScrollBox	Creates a resizeable container that automatically displays scrollbars when necessary. See About ScrollBox.

CheckListBox	Displays a scrollable list similar to ListBox except that each item has a check box next to it. See List boxes and Properties common to list controls.

Splitter	Add a splitter to a form between two aligned controls to allow users to resize the controls at runtime by clicking and dragging the split line. See About Splitter.

StaticText	A non-editable text component like Label, except that it has its own window handle, which is useful when the component’s accelerator key must belong to a windowed control. Use StaticText to provide users with feedback on the current state of the application.

ControlBar	A layout manager for toolbar components. Use a control bar as a convenient docking site for toolbars.

  	Chart	The chart equivalent of TTable. Place the component on a form and right-click it to display the third-party developer’s Help topics.


Win32 page components

See also	Other Palette pages

The components on the Win32 page of the Component palette provide access to 32-bit Windows user interface common controls available to your applications.

TabControl	Analogous to a divider in a file cabinet or notebook, this component provides a set of mutually exclusive notebook style tabs.

PageControl	A page set used to make a multipage dialog box. Use this control to define multiple logical pages or sections of information within the same window. See About PageControl.

ImageList	An image list is a collection of same-sized images, each of which can be referred to by its index. Image lists are used to efficiently manage large sets of icons or bitmaps. All images in an image list are contained in a single, wide bitmap in screen device format. An image list may also include a monochrome bitmap that contains masks used to draw images transparently (icon style). To create an image list, add the ImageList component to the form and double-click it to display the Image List Editor. Also see Properties common to list controls

RichEdit	Rich Text Format memo control. By default, the rich text editor supports font properties, such as typeface, size, color, bold, and italic format. It also supports format properties, such as alignment, tabs, indents, numbering, and automatic drag and drop of selected text. See About RichEdit and Text controls.

TrackBar	A bar that defines the extent or range of the adjustment, and an indicator that both shows the current value for the control and provides the means for changing the value. You can set the trackbar orientation as vertical or horizontal, define the length and height of the slide indicator and the slide bar component, define the increments of the trackbar, and whether to display tick marks for the control. See About TrackBar.

ProgressBar	A rectangular bar that “fills” from left to right, like that shown when you copy files in the Windows Explorer. Use this control to provide visual feedback to the user about the progress of long operations or background processes. See About ProgressBar.

UpDown	Up and down arrow buttons to increment and decrement values. See About UpDown.

HotKey	Attaches a hot key to any component. See About HotKey.

Animate	A Windows animation control window that silently displays an Audio Video Interleaved (AVI) clip, a series of bitmap frames like a movie. See Adding silent video clips to an application.

DateTimePicker	Displays a list box for entering dates or times. Users can select a date from the calendar or select dates or times by scrolling with Up and Down arrows and by typing. You must have the latest version of COMCTL32.DLL, usually located in the Windows\System or Windows\System32 directory.

MonthCalendar	Displays a calendar that represents a single month. Set the Date property to display a particular month and highlight a date within that month. You can also display a range of dates by setting MultiSelect to True and supplying an EndDate. Optionally, the current date can be displayed below the calendar, even if it does not fall within the month represented by the calendar.

TreeView	Lets you control and display a set of objects as an indented outline based on their logical hierarchical relationship. The control includes buttons that allow the outline to be expanded and collapsed. Use a tree view component to display the relationship between a set of containers or other hierarchical elements. See About TreeView.

ListView	Provides a way to display a list in columns. List views display data in a variety of views. See Properties common to list controls

HeaderControl	Displays a heading above columns of text or numbers. You can divide the control into two or more parts to provide headings for multiple columns. You can align the title elements left, right, or centered. You can configure each part to behave like a command button to support a specific function when the user clicks it. See About HeaderControl.

StatusBar	Area to post the status of actions at the bottom of the screen. See About StatusBar.

ToolBar	 Manages tool buttons and other controls, arranging them in rows and automatically adjusting their sizes and positions. See About ToolBars and Designing toolbars and cool bars.

CoolBar	Displays a collection of windowed controls (CoolBand objects) within movable, resizable bands. The user positions the controls by dragging the sizing grip to the left of each band. See Adding a cool bar component and Designing toolbars and cool bars.

PageScroller	Contains other objects in a client area that can scroll either horizontally or vertically. Users scroll the contents of the page scroller using large arrows on either end rather than using a scroll bar.


System page components

See also	Other Palette pages

The components on the System page of the Component palette make specialized system control elements available to your applications.

Timer	Timer is a nonvisual component that triggers a one-time or repeated event after a measured interval. You write the code that you want to occur at the specified time inside the timer component's OnTimer event. See About Timer.

 	PaintBox	Specifies a rectangular area on a form that provides boundaries for application painting. See About PaintBox.

MediaPlayer	Displays a VCR-style control panel for playing and recording multimedia video and sound files. See About MediaPlayer and Adding audio and/or video clips to an application.

OleContainer	Creates an Object Linking and Embedding (OLE) client area in a form. See About OleContainer.

DdeClientConv	Establishes a client connection to legacy Dynamic Data Exchange (DDE) server application. See About DdeClientConv.

DdeClientItem	Specifies the Dynamic Data Exchange (DDE) client data to transfer during a DDE conversation. See About DdeClientItem.

DdeServerConv	Establishes a server connection to legacy Dynamic Data Exchange (DDE) client application. See About DdeServerConv.

DdeServerItem	Specifies the Dynamic Data Exchange (DDE) server data to transfer during a DDE conversation. See About DdeServerItem.


Internet page components

See also	Other Palette pages

The components on the Internet page (not available in all versions) of the Component palette offer a variety of internet access protocols for your applications:

ClientSocket	Add to a form or data module to turn an application into a TCP/IP client. ClientSocket specifies a desired connection to a TCP/IP server, manages the open connection, and terminates the completed connection. See Using client sockets and Working with sockets.

ServerSocket	Add to a form or data module to turn an application into a TCP/IP server. ServerSocket listens for requests for TCP/IP connections from other machines and establishes connections when requests are received. See Using server sockets and Working with sockets.

WebDispatcher	Converts an ordinary data module to a Web module and enables the Web server application to respond to HTTP request messages. See About WebDispatcher and The Structure of a Web server application.

PageProducer	Converts an HTML template into a string of HTML commands that can be interpreted by a client application such as a Web browser. The commands and HTML-transparent tags are replaced with customized content by the OnHTMLTag event. See Using page producer components.

QueryTableProducer .	Assembles a sequence of HTML commands to generate a tabular display of the records from a TQuery object, which obtains its parameters from an HTTP request message. See Setting up a query table producer and Using dataset table producers.

DataSetTableProducer	Assembles a sequence of HTML commands to generate a tabular display of the records from a TDataSet object. This allows an application to create images of a dataset for an HTTP response message. See Setting up a dataset table producer and Using dataset table producers.

DataSetPageProducer	Converts an HTML template that contains field references into a string of HTML commands that can be interpreted by a client application such as a Web browser. Special HTML-transparent tags are replaced with field values. See Using dataset page producers.

NMDayTime	Gets the date and time from an internet/intranet daytime server.

NMEcho 	Sends text to an internet echo server, and echoes it back to you.

NMFinger	Gets information about a user from an internet finger server, using the Finger protocol described in RFC 1288.

NMFTP	Implements file transfer protocol	 Invisible ActiveX control provides easy access for Internet File Transfer Protocol (FTP) services for transferring files and data between a remote and local machine.

NMHTTP	Invisible ActiveX control implements the HTTP Protocol Client, allowing users to directly retrieve HTTP documents if no browsing or image processing is necessary.

NMMsg	Sends simple ASCII text messages across the internet or intranet using TCP/IP protocol.

NMMsgServ 	Receives messages sent with the TNMMsg component.

NMNNTP	Invisible ActiveX Client Control allows applications to access Networking News Transfer Protocol (NNTP) news servers. It provides news reading and posting capabilities.

NMPOP3	Invisible ActiveX control that retrieves mail from UNIX or other servers supporting POP3 protocol.

NMUUProcessor	MIME encodes or UUEncodes files and decodes MIME-encoded or UUEncoded files.

NMSMTP	ActiveX control that gives applications access to SMTP mail servers and mail posting capabilities.

NMStrm 	Sends streams to a stream server across the internet or an intranet.

NMStrmServ 	Receives streams sent with the TNMStrm component.

NMTime 	Gets the date and time from Internet time servers, as described in RFC 868.

NMUDP	Invisible WinSock ActiveX Control provides easy access to User Datagram Protocol (UDP) network services. It implements WinSock for both client and server and represents a communication point utilizing UDP network services. It can also be used to send and retrieve UDP data.

PowerSock 	Serves as a base for creating controls for dealing with other protocols, or for creating custom protocols.

NMGeneralServer 	Serves as a base class for developing multi-threaded internet servers, such as custom servers or servers that support RFC standards.

HTML	Invisible ActiveX control implements an HTML viewer, with or without automatic network retrieval of HTML documents, and provides parsing and layout of HTML data, as well as a scrollable view of the selected HTML page. The HTML component can also be used as a nonvisual HTML parser to analyze or process HTML documents.

NMURL 	Decodes URL data into a readable string, and encodes standard strings into URL data format.


Data Access page components

See also	Other Palette pages

The components on the Data Access page of the Component palette make specialized database access functionality available to your applications:

DataSource	Acts as a conduit between a dataset component such as TTable and data-aware components such as TDBGrid. See Using data sources

Table	Retrieves data from a physical database table via the BDE and supplies it to one or more data-aware components through a DataSource component. Conversely, it also sends data received from a component to a physical database via the BDE. See Working with tables

Query	Uses SQL statements to retrieve data from a physical database table via the BDE and supplies it to one or more data-aware components through a TDataSource component. Conversely, uses SQL statements to send data from a component to a physical database via the BDE. See Working with queries

StoredProc	Enables an application to access server stored procedures. Sends data received from a component to a physical database via the BDE. See Working with stored procedures

Database	Sets up a persistent connection to a database, especially a remote database requiring a user login and password. See Connecting to databases

Session	Provides global control over a group of Database components. A default TSession component is automatically created for each C++Builder database application. You must use the TSession component only if you are creating a multithreaded database application. Each database thread requires its own session component. See Managing database sessions

BatchMove	Copies a table structure or its data. Can be used to move entire tables from one database format to another. See Creating a batch move component

UpdateSQL	Lets you use cached updates support with read-only datasets. For example, you could use a TUpdateSQL component with a "canned" query to provide a way to update the underlying datasets, essentially giving you the ability to post updates to a read-only dataset. You associate a TUpdateSQL component with a dataset by setting the dataset's UpdateObject property. The dataset automatically uses the TUpdateSQL component when cached updates are applied. See About UpdateSQL

NestedTable	Retrieves the data in a nested dataset field and supplies it to data-aware controls through a datasource component.


Data Controls page components

See also	Other Palette pages

The components on the Data Controls page of the Component palette make specialized database control elements available to your applications:

DBGrid	Data-aware custom grid that enables viewing and editing data in a tabular form similar to a spreadsheet. Makes extensive use of TField properties (set in the Fields editor) to determine a column's visibility, display format, ordering, and so on. See Viewing and editing data with TDBGrid

DBNavigator	Data-aware navigation buttons that move a table's current record pointer forward or backward. The navigator can also place a table in Insert, Edit, or Browse state, post new or modified records, and retrieve updated data to refresh the display. See Navigating and manipulating records

DBText	Data-aware label that displays a field value in the current record. See Displaying data as labels

DBEdit	Data-aware edit box that displays or edits a field in the current record. See About DBEdit See About DBEdit

DBMemo	Data-aware memo box that displays or edits BLOB text in the current record. See About DBMemo

DBImage	Data-aware image box that displays, cuts, or pastes bitmapped BLOB images to and from the current record. See About DBImage

DBListBox	Data-aware list box that displays a scrolling list of values from a column in a table. See About DBListBox

DBComboBox	Data-aware combo box that displays or edits a scrolling list of values from a column in a table. See About DBComboBox

DBCheckBox	Data-aware check box that displays or edits a Boolean data field from the current record. See About DBCheckBox

DBRadioGroup	Data-aware group of radio buttons that display or set column values. See About DBRadioGroup

DBLookupListBox	DBLookupListBox is a data-aware list box that derives its list of display items from either a Lookup field defined for a dataset or a secondary data source, data field, and key. In either case, a user is presented with a restricted list of choices from which to set a valid field value. When a user selects a list item, the corresponding field value is changed in the underlying dataset. See About DBLookupListBox.
To specify list box items using a lookup field, the dataset to which you link the control must already define a lookup field. See Defining a lookup field

DBLookupComboBox	DBLookupComboBox is a data-aware combo box that derives its drop-down list of display items from either a lookup field defined for a dataset or a secondary data source, data field, and key. In either case, a user is presented with a restricted list of choices from which to set a valid field value. When a user selects a list item, the corresponding field value is changed in the underlying dataset. See About DBLookupComboBox.
To specify combo box list items using a lookup field, the dataset to which you link the control must already define a lookup field. See Defining a lookup field

DBRichEdit	A multiline edit control that can display and edit a rich text memo field in a dataset. See About DBRichEdit

DBCtrlGrid	A DBCtrlGrid control displays multiple fields in multiple records in a tabular grid format. Each cell in the grid displays multiple fields from a single record. See About DBControlGrid.

DBChart	Place the component on a form and right-click it to display the third-party developer’s Help topics.


Decision Cube page components

See also	Other Palette pages

The components on the Decision Cube page of the Component palette (not available in all versions) add multidimensional data analysis features to your applications. The Decision Cube components provide cross tabulation of data, letting you drill down, pivot, and summarize database information to help users visualize data for decision-making purposes:

DecisionCube	A multidimensional data store. See Using decision cubes.

DecisionQuery	Specialized form of TQuery used to define the data in a decision cube. See Creating decision datasets with the Decision Query editor.

DecisionSource	Defines the current pivot state of a decision grid or a decision graph. See Using decision sources.

DecisionPivot	Use to open or close decision cube dimensions or fields by pressing buttons. See Using decision pivots.

DecisionGrid	Displays single and multidimensional data in table form. See Creating and Using decision grids.

DecisionGraph	Displays fields from a decision grid as a dynamic graph that changes when dimensions are modified. See Using decision graphs.


QReport page components

See also

The Quick Report components on the QReport page of the Component palette enable you to visually design Quick Reports. You build reports with bands, adding titles, page headers and footers, multiple detail sets, summaries, group headers and footers. You can report from any DataSource, including TTable, TQuery, lists, arrays, and so on. Use the on-screen preview to check your results. Automatically perform calculations like summary and counting of fields. You can reset calculations at group level.

To see the third-party developer’s help, place the component on a form and right-click it.

QuickRep	The basic report form on which you build all your reports. It is a visual component that takes the shape of the currently selected paper size. Create reports by dropping bands and printable components on the TQuickRep component and connecting it to a dataset.

QRSubDetail	Links additional datasets into a report. Typically you would set up a master/detail relationship between table or query components and create a similar relationship with TQRSubDetail components.

QRStringsBand	Drops bands containing strings onto a report.

QRBand	Drop bands on a TQuickRep component and set the BandType property to tell how the band will behave during report generation.

QRChildBand	If you have bands with expanding components and want other components to be moved down accordingly you can create a child band and put the moving components on it. It’s also useful if you have very long bands that span multiple pages.

QRGroup	Allows you to group bands together and provides control for headers, footers, and page breaks.

QRLabel	Prints static or other non-database text. Enter the text to be displayed in the Caption property. You can split text on multiple lines and even multiple pages.

QRDBText	A data-aware version of the TQRLabel that prints the value of a database field. Calculated fields and text field types can be printed, including String fields, various numeric fields, date fields and memo fields. Text can span multiple lines and pages. You connect the component to the data field by setting the DataSource and DataField properties. Unlike regular data-aware components, TQRDBText works even with dataset controls disabled to improve speed.

QRExpr	Prints database fields, calculations, and static text. Input a valid QuickReport expression in the Expression property.

QRSysData	Prints system information such as report title, current page number, and so on. Select the data to print in the Data property. Set any preceding text in the Text property.

QRMemo	Prints a large amount of text that does not come from a database field. It can be static text or you can change it during report generation. You can set the field to expand vertically as needed and then span multiple pages if necessary.

QRExprMemo	Allows you to programmatically generate contents using Quick Report expressions.

QRRichText	Allows you to embed rich text into your report.

QRDBRichText	Provides a Quick Report wrapper for accessing DBRichText fields in your reports.

QRShape	Draws simple shapes like rectangles, circles, and lines on a report.

QRImage	Displays a picture on a report. Supports all image formats supported by the TPicture class.

QRDBImage	Prints images stored in binary (BLOB) fields. Prints all graphics formats supported by C++Builder.

QRCompositeReport	Allows you to combine more than one report together.

QRPreview	Brings up a form that allows you to preview a report on the screen and print it.

QRTextFilter	Lets you export the contents of your report into text format.

QRCSVFilter	Lets you export the contents of your report into a comma-delimited database source file.

QRHTMLFilter	Lets you export the contents of your report into HTML.

QRChart	Allows you to take a TChart component and drop it onto your Quick Report form.


Dialogs page components

See also	Other Palette pages

The components on the Dialogs page of the Component palette make the Windows common dialog boxes available to your applications. The common dialog boxes provide a consistent interface for file operations such as opening, saving, and printing files:

A common dialog box opens when its Execute method is called. Execute returns one of the following Boolean values:

true, if the user chooses OK to accept the dialog box

false, if the user chooses Cancel or escapes from the dialog box without saving any changes.

Each common dialog box component (except the PrinterSetup component) has an Options property that affects its appearance and behavior. To display the various Options in the Object Inspector, double-click the Options property.

To close a dialog box programmatically, use the CloseDialog method.

To manipulate the position of a dialog box at runtime, use the Handle, Left, Top, and Position properties.

OpenDialog	Displays a Windows common Open dialog box. Users can specify the name of a file to open in this dialog box

SaveDialog	Displays a Windows common Save dialog box. Users can specify the name of a file to save in this dialog box

OpenPictureDialog	Displays a modal Windows dialog box for selecting and opening graphics files. Identical to Open dialog box except that it has an image preview region.

SavePictureDialog	Displays a modal Windows dialog box for entering file names and saving graphics files. Identical to Save dialog box except that it has an image preview region.

FontDialog	Displays a Windows common Font dialog box that lets users can specify font, size, and style information.

ColorDialog	Displays a Windows common Color dialog box that lets users specify color information.

PrintDialog	Displays a Windows common Print dialog box that lets users specify printing information, such as a range of pages and the number of copies.

PrinterSetupDialog	Displays a Windows common Printer Setup dialog box that lets users change and set up printers.

FindDialog	Displays a Windows common Find dialog box that lets users specify a string to search for.

ReplaceDialog	Displays a Windows common Replace dialog box that lets users specify a search string and a replacement string.


Windows 3.1 Components
Windows 3.1 page components

See also	Other Palette pages

The components on the Windows 3.1 page of the Component palette provide Windows 3.1 control elements for backward compatibility with Windows 3.1 applications built with older applications. Many of these older controls implement the same behavior as more recent specialized 32-bit Windows controls.

When creating new applications, do not use these controls.
The following table indicates which control should be used instead:

Win 3.1 control	Replace with	Palette page of new control

DBLookupList	DBLookupListBox	Data Controls

DBLookupCombo	DBLookupComboBox	Data Controls

TabSet	TabControl	Win32

Outline	TreeView	Win32

TabbedNoteBook	PageControl	Win32

NoteBook	PageControl	Win32

Header	HeaderControl	Win32

DBLookupList	Data-aware list box that displays values looked up from columns in another table at runtime.

DBLookupCombo	Data-aware combo box that displays values looked up from columns in another table at runtime.

TabSet	Creates notebook-like tabs. You can use the TabSet component with the Notebook component to enable users to change pages.

Outline	Displays information in a variety of outline formats.

TabbedNotebook	Creates a component that contains multiple pages, each with its own set of controls. Users select a page by clicking the tab at the top of the page

Notebook	Creates a component that can contain multiple pages. Used with the Notebook component, it enables users to change pages.

Header	Creates a sectioned region for displaying data. Users can resize each section of the region to display different amounts of data.

FileListBox	Displays a scrolling list of files in the current directory.

DirectoryListBox	Displays the directory structure of the current drive. Users can change directories in a directory list box.

DriveComboBox	Displays a scrolling list of available drives.

FilterComboBox	Specifies a filter or mask to display a restricted set of files.


Samples page components

See also	Other Palette pages

The components on the Sample page of the Component palette are examples of customized components that you can build and add to the Component Palette. Source code to these sample components is included in the \EXAMPLES\CONTROLS\SOURCE directory of the default installation.

Pie

Performance Graph

CSpinButton

CSpinEdit

CGauge

CDirectoryOutline

CColorGrid

CCalendar

IBEVentAlerter


ActiveX page components

See also	Other Palette pages

The components on the ActiveX page of the Component palette are ActiveX objects. They are complete, portable working applications created by third-party developers.

To use these components, you must first open an ActiveX form with a current ActiveX library project. After placing a component on the ActiveX form, right-click it to display Properties and other commands or dialog boxes for configuring the component’s functionality or setting its values. The Properties dialog box or other controls contain Help buttons that display the developer’s Help system for the component.

Chartfx	Lets you create highly customized charts. Choose Properties to display a tabbed control panel that lets you define the values, appearance, and end-user functionality of the chart component.

VSSpell	Visual Speller, lets you customize a spelling checker.

F1Book	Formula One, lets you design a spreadsheet with its full-featured Designer.

VtChart	Lets you create true 3D charts.

Graph	Pinnacle Graph, lets you create 2D graphs.


MIDAS page components

See also	Other Palette pages

The components on the MIDAS page of the Component palette (not available in all versions) enable you to build multi-tiered database applications:

ClientDataSet	Implements a database-independent dataset that can be used independently in a single-tiered application, or to represent data received from a server in a multi-tiered database application. See Creating and using a client dataset

DCOMConnection	Establishes a DCOM connection to a remote server in a multi-tiered database application. See Connecting to the application server

SocketConnection	Establishes a TCP/IP connection to a remote server in a multi-tiered database application. See Connecting to the application server

OLEnterpriseConnection	Establishes an OLEnterprise connection to a remote server in a multi-tiered database application. See Connecting to the application server

DataSetProvider	Encodes data from a dataset into packets than can be sent to client applications and applies updates that are received from client applications to that dataset. See Creating a data provider for the application server and Providing from and resolving to a dataset

Provider	Encodes data from a dataset into packets than can be sent to client applications and applies updates that are received from client applications to a dataset or database server. See Creating a data provider for the application server.

SimpleObjectBroker	Locates a server for a connection component from a list of available application servers. See Brokering connections.

RemoteServer	(For backward compatibility only) Establishes a DCOM connection to a remote server in a multi-tiered application.

MIDASConnection	(For backward compatibility only) Establishes a DCOM, TCP/IP, or OLEnterprise connection to a remote server in a multi-tiered application.


Common component tasks

See also

When designing your application interface, there are procedures you might want to perform that are not specific to a particular component. The list below represents a sampling of such procedures. Choose a topic for more information.

Tasks

Programming with VCL objects

Handling user events

Setting the component focus in a form

Managing layout

Setting the tab order

Disabling components

Using action lists

Implementing drag-and-drop

Implementing drag-and-dock

Working with text

Adding graphics to controls


Using the Form component

See also

An application usually contains multiple forms: A main form, which is the primary user interface, and other forms such as dialog boxes, secondary windows (for instance, those that display OLE 2.0 data), and so on. You can begin your form design from one of the many Form templates provided with C++Builder. You can save any form you design as a template that you can reuse in other projects.

Creating Forms

Making your form a component

Controlling When Forms Reside In Memory

Tasks

To make the form stay on top of other open windows (for instance, the Project Manager or Alignment Palette) at runtime, set the FormStyle property to fsStayOnTop.

To remove the form's default scrollbars, change the value of the HorzScrollBar and VertScrollBar properties.

To make the form an MDI frame or MDI child, use the FormStyle property.

To change the form's border style, use the BorderIcons and BorderStyle properties. (The results are visible at runtime.)

To change the icon for the minimized form, use the Icon property.

To specify the initial position of a form in the application window, use the Position property.

To specify the initial state of the form, (e.g., minimized, maximized or normal) use the WindowState property.

To define the working area of the form at runtime, use the ClientHeight and ClientWidth properties. (Note that ClientHeight and ClientWidth represent the area within the form's border; Height and Width represent the entire area of the form.)

To specify which control has initial focus in the form at run-time, use the ActiveControl property.

To pass all keyboard events to form, regardless of the selected control, use the KeyPreview property.

To specify a particular menu, if your form contains more than one menu, use the Menu property.


About user events

See also

In event-driven programming, user events are a key part of your application logic. User events correspond to the elements in your Graphical User Interface (GUI). For example, most components contain an OnClickevent that can be programmed to respond when the user clicks the component. Other events, such as the form's OnActivate are not triggered by the user, but by your program code. The code you write to respond to events is called an event handler.

For information about handling user events, choose from the following topics.

Defining the handler type

Keyboard events

Mouse events

Drag and drop events


About keyboard events

See also

C++Builder provides three events that enable you to capture user keystrokes:

OnKeyDown

OnKeyPress

OnKeyUp

You can write event handlers for these events to respond to any key or key combination the user might press at runtime.

Note:	Responding when the user presses short-cut or accelerator keys, such as those provided with menu commands, does not require writing event handlers.

There are several important considerations when handling keyboard events. Choose a topic for more information.

Keyboard event processing order

Processing keystrokes

Redirecting keyboard events to the form


Keyboard event processing order

See also	Example

Keyboard events are received at several levels:

The application level, with an Application->OnMessage event.

You will rarely need to intercept keystrokes at the application level, but it is important to know that this first level is available.

The "shortcut-key" level

When you specify a short-cut key, such as those provided as a property of menu items, the keystroke is intercepted before the form sees it.

The form level

The form contains a KeyPreview property that enables you to code "global" keystroke events.

The component level

When you program key-press event handlers at the component level, the component with focus intercepts the keystroke.


Example

The following code uses two buttons in a form to demonstrate the order in which keyboard events are processed by your application.

When you first run the program and press Alt+Ctrl, the form turns purple, because Button1 had focus and therefore receives the keystrokes. If you click Button1 to disable it, or click Button2 to set the form's KeyPreview on, and then press Ctrl+Alt again, the form turns aqua because the form receives the keystrokes.

void __fastcall TForm1::FormKeyDown(TObject *Sender, word &key,

 	TShiftState Shift)

{

 if (shift == ([ssAlt, ssCtrl])) then form1.color = clAqua;

}

void __fastcall TForm1::Button1KeyDown(TObject *Sender, word &key

  TShiftState Shift)

{

   if (shift == ([ssAlt, ssCtrl])) then form1.color = clPurple;

}

void __fastcall TForm1::Button1Click(TObject *Sender)

{

 button1.enabled = false;

}

void __fastcall TForm1::Button2Click(TObject *Sender)

{

 Form1.Keypreview = true;

}


Processing keystrokes

See also	Example

Every keystroke generates an OnKeyDown and OnKeyUp event. In addition, keys that have an ASCII equivalent generate an OnKeyPress event. Naturally, your code does not need to capture each keystroke, but it is important to know the order in which keystroke events are processed. See the attached example for an explicit demonstration.

Your application can capture each event at several levels (see KeyBoard event processing order). OnKeyPress returns a single ASCII character, while OnKeyDown and OnKeyUp contain parameters that reflect information about whether control keys such as Alt, Ctrl and Shift keys were pressed at the time the last keystroke occurred.

For instance, here is the OnKeyDown, OnKeyPress and OnKeyUp keystroke sequence generated when the user presses Shift+D:

KeyDown (Shift)

KeyDown (Shift+D)

KeyPress (D)

KeyUp (Shift+D)

KeyUp

When keys are pressed in combination, the OnKeyDown event passes the key for each previous OnKeyDown to the next OnKeyDown. The OnKeyPress event, by contrast, merely returns the last key pressed. However, OnKeyPress returns a different ASCII character for 'd' and 'D,' but OnKeyDown and OnKeyUp do not make a distinction between uppercase and lowercase alpha keys.


Example

The following code uses a list box to display the keystroke processing order of the OnKeyUp, KeyDown, and OnKeyPress events of the form and the Edit component for any key you press.

Note:	By adding a Default and Cancel button to the form (buttons whose Default and Cancel properties are set to true) you can view how the Esc and Enter keystrokes are processed when such buttons exist.

void __fastcall TForm1::Edit1KeyDown(TObject *Sender, Word &Key,

  TShiftState Shift);

{

 Listbox1->Items->Add('Edit1->KeyDown'+ShortCutToText(ShortCut(Key, Shift)));

}

void __fastcall TForm1::Edit1KeyPress(TObject *Sender, Char &Key)

{

   Listbox1->Items->Add('Edit1->KeyPress'+ Key);

}

void __fastcall TForm1::Edit1KeyUp(TObject *Sender, Word &Key,

  TShiftState Shift);

{

 Listbox1->Items->Add('Edit1->KeyUp'+ShortCutToText(ShortCut(Key, Shift)));

}

void __fastcall TForm1::FormKeyDown(TObject *Sender, Word &Key,

  TShiftState Shift)

{

  Listbox1->Items->Add('Form1->KeyDown'+ShortCutToText(ShortCut(Key, Shift)));

}

void __fastcall TForm1::FormKeyPress(TObject *Sender, Char &Key)

{

   Listbox1->Items->Add('Form1->KeyPress'+ Key);

}

void __fastcall TForm1::FormKeyUp(TObject *Sender, Word &Key,

  TShiftState Shift);

{

  Listbox1->Items->Add('Form1->KeyUp'+ShortCutToText(ShortCut(Key, Shift)));

}


Responding to the OnKeyPress event

See also	Example

The OnKeyPress event is the simplest of the three events, in that it returns only a single character the user presses. The character must fall within the ASCII character set.

OnKeyPress interprets key combinations only insofar as they evaluate to a single ASCII-character. So, for example, OnKeyPress recognizes the result of Shift+A (a capital 'A'), but not the individual keys pressed. OnKeyPress does not otherwise evaluate keys combinations, and does not recognize function keys or non-ASCII keys such as Ctrl, Alt, Insert, Page Down, and so on.

Default or Cancel buttons in the form will intercept the Enter and Escape key press for both the OnKeyPress and OnKeyDown events, (unless used in combination with Alt for the OnKeyDown.)


Example

The following example demonstrates how OnKeyPress and OnKeyDown can be coded to handle keyboard events.

The OnKeyPress event contains a key parameter of type Char. Therefore if you want to test for which key the user pressed, you simply enter the character.

void __fastcall TForm1::FormKeyPress(TObject *Sender, Char &Key)

{

 switch (key)
 {

   'I': Panel1->Caption == 'Shift+I was pressed';

   'c': Panel1->caption == 'c was pressed';

   ' ': Panel1->caption == 'the space bar was pressed';

 }

}

With OnKeyDown, the key parameter is of type Word. Therefore if you want to test for which key the user pressed, you must refer to the equivalent Virtual Key Codes (see the Win32 Programmer's Reference ).

void __fastcall TForm1::FormKeyDown(TObject *Sender, Word &Key,

  TShiftState Shift)

{

  switch (key)

  {

   vk_Insert: Panel1->Caption == 'INS';

   vk_Capital: Panel1->caption == 'CAP';

   vk_Numlock: Panel1->caption == 'NumLock';

 }

}


Responding to the OnKeyUp and OnKeyDown events

See also	Example

Use the OnKeyDown and OnKeyUp events when you want to interpret key combinations such as whether the SHIFT, CTRL, or ALT key is pressed at the time the active control receives the key event; and to handle keys that have no ASCII equivalent, such as function keys. The F1 key, for example, does not get captured by the OnKeyPressevent because it has no alphanumeric value. See Responding To The OnKeyPress Event

While both key events return the value of the keys pressed, the OnKeyDown event is much more commonly used. You might use OnKeyUp when you want to initiate a background process inbetween the key-down and key-up. When the user presses and holds down a key, the key returns repeated OnKeyDown events until the user releases it, at which time a single OnKeyUp is returned. In programs such as games, these specific keyboard interactions become more useful. 'Vk_Insert' is the virtual key code for the Insert key.

Note:	To use OnKeyDown or OnKeyUp to test for keys the user presses, you must use Virtual key codes (see the Win32 Programmer's Reference ) to specify the key. This is because the parameter key is of type word. For example, the following event handler specifies that when the user presses the Insert key, the panel in the form displays 'INS.' '

void __fastcall TForm1::FormKeyDown(TObject *Sender, Word &Key,

    TShiftState Shift)

{

  if key == vk_Insert then Panel1->Caption = 'INS';

}


Example

The following two event handlers respond to the OnKeyDown and OnKeyUp events by zooming and shrinking a graphical image with the user presses and releases the 'Z' key.

void __fastcall TForm1::FormKeyDown(TObject *Sender, Word &Key,

    TShiftState Shift)

{

  if chr(Key) == 'Z' then Image1->Stretch = true;

}

void __fastcall TForm1.FormKeyUp(TObject *Sender, Word &Key,

    TShiftState Shift)

{

  if chr(Key) == 'Z' then image1->Stretch = false;

}


Redirecting keyboard events to the form

See also	Example

Set the KeyPreview property of a form to true.

You can now handle keyboard events at the form level, rather than having to write separate event handlers for every component in the form that might have focus when the keyboard event occurs. The form can receive any keystrokes that the focused component can receive. Also, by using KeyPreview, you can then code unique keyboard event handlers for specific components.

KeyPreview is like having an automatic call to the form-level keyboard event handler at the start of every component-level keyboard handler. The component still sees the event, but the form has an opportunity to handle it first. For example, you could write an event handler for the FormKeyDown that performs key mappings so that a ButtonKeyDown receives the mapped key instead of the key originally pressed.


Example

The following example demonstrates how the form KeyPreview property intercepts keystrokes.

Place a button on a form, and write the following handler for the form OnKeyDown event:

void __fastcall TForm1.FormKeyDown(TObject *Sender, Word &Key,

    TShiftState Shift)

{

 if (shift == ([ssAlt, ssCtrl])) then Form1->color = clAqua;

}

Run the application and press Alt+Ctrl.

Nothing happens -- this is because the control with focus receives the keyboard events, and in this case no keyboard event handler was written for the button.

You could solve this by disabling the button, or by putting the code in the button event handler. But by setting KeyPreview for the form to true, you can intercept keystrokes at the form level instead of writing additional code.

Set the form's KeyPreview to true, and run the program again. This time the form receives the keystrokes -- when you press Ctrl+Alt, the form turns aqua.


Creating a Select File dialog box

1. Place the following controls on a form:

DriveComboBox named DriveCombo1

DirectoryListBox named DirList1

Edit component named FileEdit1

FilterComboBox named Filter1

FileListBox name FileList1

Label component named PathLabel

2. Select DriveCombo1 and set the DirList = DirList1.

3. Select DirList1. Set DirLabel = PathLabel. and FileList = FileList1.

4. Select Filter1. Set FileList = FileList1 and set the Filter property as desired.

5. Select FileList1. Set the FileEdit = FileEdit1. If you want to select multiple file names, set MultiSelect = true.

6. Code the event handlers for each of the following:

Form OnCreate event

Filter1 OnChange event

DriveCombo1 OnChange event

FileList1 OnChange event


Event handler code for Form OnCreate event

{

  FileList1->Mask = Filter1->Mask;

  Filter1Change(Filter1);

  PathLabel->Caption = DirList1->Directory;

}


Event handler code for Filter1 OnChange event

{

  FileEdit->Text = FileList1->Mask;

  PathLabel->Caption = DirList1->Directory;

}


Event handler code for DriveCombo1 Onchange Event

{

  PathLabel->Caption = DirList1->Directory;

}


Event handler code for FileList1 OnChange event

{

  PathLabel->Caption = DirList1->Directory + '\' + FileList1->Filename;

}


About the Timer component

TTimer reference	Common component tasks

Purpose

Use the Timer component to trigger an event, either one time or repeatedly, after a measured interval. Write the code that you want to occur at the specified time inside the timer component's OnTimer event.

Tasks

To specify the amount of elapsed time before the timer event is triggered, use the Interval property.

To discontinue a timed event, set the timer component's Enabled property to False.

Displaying a SplashScreen


Displaying a SplashScreen

The following two event handlers display and close a form called SplashScreen before the application's main form opens. The constant Startup is declared in Form1's unit header. The first event handler calls the Show method of SplashScreen from Form1's OnActivate event.

void __fastcall TForm1::FormActivate(TObject &Sender)

{

  if (Startup)

  {

    Startup = false;

    SplashScreen->Show;

  }

}

SplashScreen contains a Timer component whose Interval property is set to 3000, so the form is displayed for three seconds and then closes. The form's Close method is attached to the timer component's OnTimer event.

void __fastcall TForm2::Timer1Timer(TObject &Sender);

{

  Close;

}


About the PaintBox component

TPaintBox reference	Common component tasks

Purpose

Provides a means of limiting drawing on a form to the specific rectangular area encompassed by the PaintBox.

Tasks

To access the drawing "surface" of the PaintBox, use the Canvas property.

To draw on the canvas of the PaintBox, write appropriate code in the event handler for the OnPaint event.


About the MediaPlayer component

See also	TMediaPlayer reference

Purpose

Use the MediaPlayer component to enable your application to control a media playing or recording device such as a CD-ROM player, video player/recorder, or MIDI sequencer.

Deciding how to use the MediaPlayer

How you use and configure the media player component depends largely on the type of device you want to control with it, and whether you want to use all the capabilities of the device or limit your application to certain capabilities.

For example, if you are controlling a video cassette recorder and do not want your user to accidentally erase the tape, you could disable or hide the Record segment of the MediaPlayer component.

If the medium has tracks, as does a compact disc, you might not need to use the Rewind capability of the MediaPlayer; whereas you would need this for a video tape or Digital Audio Tape (DAT) device.

Tasks for controlling component functions

To show or hide individual button segments on the MediaPlayer component, use the VisibleButtons property.

To enable or disable individual segments on the Media Player component, use the EnabledButtons property.

To control whether or not the device automatically rewinds at the end of the medium before playing or recording, use the AutoRewind property.

To determine whether or not other components or applications can access the device, use the Shareable property.

Tasks for controlling device access

To specify or change the type of device controlled by the MediaPlayer component, use the DeviceType property.

To specify or change the starting position within the currently loaded medium, use the Start property.

To specify or change the current position of the medium, use the Position property.

Tasks for accessing information on the medium

To specify or change the media file to play or record, use the FileName property

To determine the ID of the current device, use the run-time/read-only property DeviceID.

To determine the position within the currently loaded medium from which playing or recording will start, use the run-time/read-only property StartPos.

To determine the number of tracks on the open multimedia device, use the run-time/read-only property Tracks.

To determine the length of a track, use the run-time/read-only property TrackLength for the current TrackNum index.

To determine the length of a track, use the run-time/read-only property TrackPosition for the current TrackNum index.

Tasks for controlling device operation

The MediaPlayer component provides a number of methods for controlling the operation of a media play or record device. Some of these correspond to one of the button segments of the component (indicated by an asterisk (*)). You have the option of calling any of these methods in your program code as well.

Here are the methods (listed alphabetically) for controlling a device:

*Back	*Pause	Rewind

Close	PauseOnly	*StartRecording

*Eject	*Play	*Step

*Next	*Previous	*Stop

Open	Resume


About the OLEContainer component

TOLEContainer reference	Creating an AutomationController

Purpose

Use the OLEContainer component to provide your application with the ability to link and embed objects from an OLE server.

When you activate an object inside the OLE container, control transfers to the OLE server application, so the user can access all the functionality of the server application from within your container application.


About the DDEClientConv component

TDDEClientConv reference

Purpose

DDE is an older technology for interapplication communication. For new projects that need not access legacy DDE server applications, you should instead use Automation or other COM technology.

Use the DDEClientConv component to provide your application with the ability to establish a DDE conversation with a legacy DDE server application. When you place this component on your form, your application becomes a DDE client.

This component works in conjuction with the DDEClientItem component to make your application a complete DDE client.

Important properties

To specify the topic of a DDE conversation, use the DDETopic property.

To specify the DDE server application, use the DDEService property.  Depending on the server, the server application name is usually but not always the executable.

To specify the executable name for the DDE server application, use the ServiceApplication property.

To define whether the connection to the DDE server application is established automatically when the form runs, use the ConnectMode property.

To filter characters out of the text data transfer from a server application, use the FormatChars property.


About the DDEClientItem component

TDDEClientItem reference

Purpose

DDE is an older technology for interapplication communication. For new projects that need not access legacy DDE server applications, you should instead use Automation or other COM technology.

Use the DDEClientItem component to define the item of a DDE conversation.. Use it in conjunction with a DDEClientConv component to make your application a DDE client to access legacy DDE server applications. If you will need only one item, the DDEClientConv is not necessary.

Important properties

To specify the DDE client conversation component, use the DDEConv property.

To specify the item of the DDE conversation, use the DDEItem.

To find out what the DDE Server sent, read the Lines property.


About the DDEServerConv component

TDDEServerConv reference

Purpose

DDE is an older technology for interapplication communication. For new projects that need not support legacy DDE client applications, you should instead use Automation or other COM technology.

Use the DDEServerConv component to provide your application with the ability to establish a DDE conversation with DDE client applications. When you place this component on your form, your application becomes a DDE server.

This component works in conjunction with the DDEServerItem component to make your application a complete DDE server.


About the DDEServerItem component

TDDEServerItem reference

Purpose

DDE is an older technology for interapplication communication. For new projects that need not support DDE client applications, you should instead use Automation or other COM technology.

Use the DDEServerItem component to define the topic of a DDE conversation with another application.

Use it in conjunction with a DDEServerConv component to make your application a DDE server.

To specify the DDE server conversation component, use the ServerConv property.


Customizing the Component palette

See also

To customize the layout of the Component palette, choose the Palette page from the Environment Options dialog box.


 Saving a customized Component palette

1.	Open the Preferences page of the Environment Options dialog box.

2.	Check Desktop from the Autosave options.

3.	Click OK.


Rearranging Component palette pages

1.	Open the Palette page of the Environment Options dialog box.

2.	Select a page from the Pages list box.

3.	Click the up arrow or down arrow, or drag and drop the page to its new location.

4.	Click OK for your changes to take effect.


Rearranging components on the Component palette

1.	Open the Palette page of the Environment Options dialog box.

2.	Select a component from the Components list box.

3.	Click the up arrow or down arrow, or drag and drop the component into its new location.

4.	Click OK for your changes to take effect.


Moving a component to a different Component palette page
Moving components to a different Component palette page

1.	Open the Palette page of the Environment Options dialog box.

2.	Drag and drop the component from the Components list box onto a page in the Pages list box.

3.	Click OK for your changes to take effect.

Note:	When you move a component to a new page, the component is added as the last item on the page.


Renaming Component palette pages

1.	Open the Palette page of the Environment Options dialog box.

2.	Select the page from the Pages list box.

3.	Click Rename to open the Rename Page dialog box.

4.	Enter a new name.

5.	Click OK to close the Rename Page dialog box.

6.	Click OK for your changes to take effect.


Adding pages to the Component palette

1.	Open the Palette page of the Environment Options dialog box.

2.	Click the Add button to open the Add Page dialog box.

3.	Enter a new page name.

4.	Click OK to close the Add Page dialog box.

5.	Click OK for your changes to take effect.


Removing pages from the Component palette

1.	Open the Palette page of the Environment Options dialog box.

2.	Select the page from the Pages list box

3.	Press Delete.

4.	Click OK for your changes to take effect.

Note:	Before you can remove a page, it must be empty of components.


Removing components from the Component palette

1.	Open the Palette page of the Environment Options dialog box.

2.	Select the component you want to remove.

3.	Press Delete.

4.	Click OK for your changes to take effect.


Find Header File dialog box
Find file dialog box

See also

Borland C++Builder was unable to locate a file (header or library) associated with a component on a form. This situation most likely occurred because you added a component (such as one from an outside vendor) to a component palette, but did not place its header file or library in a directory specified in your include path.

Enter the name of the missing file (including its directory location) or click the Browse button to find it yourself. The path will then be added to your current project path. To avoid having to resolve paths for individual projects, add the path to the global setting in the Tools|Environment Options|Library page.


CPU window

See also

The CPU window consists of five separate panes. Each pane gives you a view into a specific low-level aspect of your running application.

Disassembly pane displays the assembly instructions that have been disassembled from your application's machine code. In addition, the Disassembly pane displays the original program source code above the associated assembly instructions.

Memory Dump pane displays a memory dump of any memory accessible to the currently loaded executable module. By default, memory is displayed as hexadecimal bytes.

Machine Stack pane displays the current contents of the program stack. By default, the stack is displayed as hexadecimal longs (32-bit values).

Registers pane displays the current values of the CPU registers.

Flags pane displays the current values of the CPU flags.

Right-click anywhere on the CPU window to access commands specific to the contents of the current pane.

Opening the CPU window

To open the CPU window anytime during a debugging session,

Choose View|Debug Windows|CPU or right-click the Code editor and choose Debug|CPU View to open the Disassembly pane at the location of the execution point.

The CPU window opens automatically whenever program execution stops at a location for which source code is unavailable. For example, the debugger cannot open the source file if you link a DLL built with debug information but do not include its source file in your project, or if you place the source file in a directory not specified in your project.

Resizing the CPU window panes

You can customize the layout of the CPU window by resizing the panes within the window. Drag the pane boarders within the window to enlarge or shrink the windows to your liking.


Disassembly pane

The Disassembly pane is part of the CPU Window.

The left side of the Disassembly pane lists the address of each disassembled instruction. A green arrow to the left of the memory address indicates the location of the current execution point. To the right of the memory addresses, the Disassembly pane displays the assembly instructions that have been disassembled from the machine code produced by the compiler. If you make the Disassembly pane wide enough, the debugger displays the instruction opcodes following the listing of the instruction memory addresses.

When you click an address in the Disassembly pane,

the upper left corner shows the effective address (when available) and the value it stores. For example, if you select an address containing an expression in brackets such as [eax+edi*4-0x0F], the top of the Disassembly pane shows the location in memory being referenced and its current value.

the upper right corner shows the current thread ID.

If you are viewing code that has debug information available, the debugger displays the source code that is associated with the disassembled instructions.

Press Ctrl+Left Arrow and Ctrl+Right Arrow to shift the starting point of the display up or down one byte. Beware that changing the starting point of the display in the Disassembly pane changes where the debugger begins disassembling the machine code.

Disassembly pane commands

Right-click the Disassembly pane to access the following commands:

Enabled - This menu option is only available by right clicking in the gutter.

Breakpoint Properties - This menu option is only available by right clicking in the gutter.

Run to Current

Toggle Breakpoint

Go to Address

Go to Current EIP

Follow

Caller

Previous

Search

View Source

Mixed

Change Thread

New EIP


Enabled command (Disassembly pane)
Enabled

Enabled is a toggle menu item that enables and disables a breakpoint. This menu option is only available by right-clicking in the gutter on an address which has a breakpoint.


Breakpoint Properties command (Disassembly pane)
Breakpoint Properties

Choose Properties from the CPU Dissassembly pane context menu to open an Address Breakpoint Properties or a Source Breakpoint Properties dialog box that allows you to modify address or source breakpoints. This menu option is only available by right-clicking in the gutter on an address which has a breakpoint.


Run to Current command (Disassembly pane)
Run to Current

The Run To Current command lets you run your program at full speed to the instruction that you have selected in the Disassembly pane. After your program is paused, you can use this command to resume debugging at a specific program instruction.


Toggle Breakpoint command (Disassembly pane)
Toggle Breakpoint

This command adds or removes a breakpoint at the selected instruction in the Disassembly pane. When you choose Toggle Breakpoint, the debugger sets an unconditional (simple), breakpoint at the instruction that you have selected in the Disassembly pane. A simple breakpoint has no conditions, and the only action is that it will pause the program's execution.

If a breakpoint exists on the selected instruction, then Toggle Breakpoint will delete the breakpoint at that code location.


Go to Address command (Disassembly pane)
Go to Address

The Go to Address command prompts you for a new area of memory to display in the Disassembly pane of the CPU window. Enter any expression that evaluates to a program memory location. Be sure to precede hexadecimal values with 0x.

The debugger displays dashes if you view a program memory location in which nothing is loaded.

You can also press Ctrl+Left Arrow and Ctrl+Right Arrow to shift the starting point of the display up or down one byte.


Go to Current EIP command (Disassembly pane)
Go to Current EIP

This command positions the Disassembly pane at the location of the current program counter (the location indicated by the EIP register). This location indicates the next instruction to be executed by your program.

This command is useful when you have navigated through the Disassembly pane, and you want to return to the next instruction to be executed.


Follow command (Disassembly pane)
Follow

This command positions the Disassembly pane at the destination address of the instruction currently highlighted.

Use the Follow command in conjunction with instructions that cause a transfer of control (such as CALL, JMP, and INT) and with conditional jump instructions (such as JZ, JNE, LOOP, and so forth). For conditional jumps, the address is shown as if the jump condition is TRUE. Use the Previous command to return to the origin of the jump.


Caller command (Disassembly pane)
Caller

This command positions the Disassembly pane at the instruction past the one that called the current interrupt or subroutine.

If the current interrupt routine has pushed data items onto the stack, the debugger might not be able to determine where the routine was called from.

Note:	Caller will not work unless you turn on stack frames (Project|Options Compiler page).


Previous command (Disassembly pane)
Previous

This command restores the Disassembly pane to the display it had before you issued the last Follow command.


Search command (Disassembly pane)
Search

This command searches forward in the Disassembly pane for an expression or byte list that you supply. Supply a byte list to search for two or more values located in a specific order. Be sure to precede hexadecimal values with 0x

For example, if you enter

0x5D 0xC3

the debugger goes to the following location:

004013AB 5D

004013AC C3

You can also search for DWords, but you must reverse the order of the bytes.

For example, if you enter

0x1234

the debugger positions the pane at the following location in memory:

34 12


View source command (Disassembly pane)
View source

This command activates the Code editor and positions the insertion point at the source code line that most closely corresponds to the disassembled instruction selected in the Disassembly pane. If there is no corresponding source code (for example, if you are examining Windows kernel code), this command has no effect.


Mixed command
Mixed

Switches the display format of the Disassembly pane:

When Mixed is….	The Disassembly pane displays….

checked	source code lines before the first disassembled instruction relating to that source line.

unchecked	disassembled instructions without source code.


Change Thread command (Disassembly pane)
Change thread

This command opens the Select a Thread dialog box. Select the thread you want to debug from the threads listed. When you choose a new thread from the Disassembly pane, all panes in the CPU window reflect the state of the CPU for that thread.


Select a Thread dialog box

The Select a Thread dialog box is displayed when you right-click in any of the panes in the CPU window. It lists processes and threads so you can change the current process or thread directly from the CPU window.

Select the thread you want to debug from the threads listed. When you choose a new thread from the Disassembly pane, all panes in the CPU Window reflect the state of the CPU for that thread.


New EIP command (Disassembly pane)
New EIP

This command changes the location of the instruction pointer (the value of EIP register) to the line currently highlighted in the Disassembly pane. Use this command when you want to skip certain machine instructions. When you resume program execution, execution starts at this address.

This command is not the same as stepping through instructions; the debugger does not execute any instructions that you might skip.

Use this command with extreme care; it is easy to place your system in an unstable state when you skip over program instructions.


Memory Dump pane

The Memory Dump pane is part of the CPU Window.

The Memory Dump pane displays the raw values contained in addressable areas of your program. The pane has three sections: the memory addresses, the current values in memory, and an ASCII representation of the values in memory.

The Memory Dump pane displays the memory values in hexadecimal notation. The leftmost part of each line shows the starting address of the line. Following the address listing is an 8-byte hexadecimal listing of the values contained at that location in memory. Each byte in memory is represented by two hexadecimal digits. Following the hexadecimal display is an ASCII display of the memory. Non-printable values are represented with a period.

The format of the memory display depends on the format selected with the Display As command. If you choose one of the floating-point display formats (Floats or Doubles), a single floating-point number is displayed on each line. The Bytes format (default) displays 8 bytes per line, Words displays 4 words per line, and DWords displays 2 long words per line.

You can press Ctrl+Left Arrow and Ctrl+Right Arrow to shift the starting point of the display up or down one byte. Using these keystrokes is often faster than using the Go to Address command to make small adjustments to the display.

Memory Dump pane commands

Right-click the Memory Dump pane to access the following commands:

Go to Address

Change Thread

Search

Next

Change

Follow

Previous

Display As


Go to Address command (Memory Dump pane)
Go to Address

The Go to Address command prompts you for a new area of memory to display in the Memory Dump pane of the CPU window. Enter any expression that evaluates to a program memory location. Be sure to precede hexadecimal values with 0x.

The debugger displays dashes if you view a program memory location in which nothing is loaded.

You can also press Ctrl+Left Arrow and Ctrl+Right Arrow to shift the starting point of the display up or down one byte.


Change Thread command (Memory Dump pane)
Change thread

This command opens the Select a Thread dialog box. Select the thread you want to debug from the threads listed. When you choose a new thread from the Memory Dump pane, all panes in the CPU window reflect the state of the CPU for that thread.


Search command (Memory Dump pane)
Search

This command searches forward in the Memory Dump pane for an expression or byte list that you supply. Supply a byte list to search for two or more values located in a specific order. Be sure to precede hexadecimal values with 0x.

For example, if you enter

0x5D 0xC3

the debugger positions the pane at the following location:

004013AB 5D

004013AC C3

You can also search for DWords, but you must reverse the order of the bytes.

For example, if you enter

0x1234

the debugger positions the pane at the following location in memory:

34 12


Next command (Memory Dump pane)
Next

Finds the next occurrence of the item you last Searched for in the Memory Dump pane.


Change command (Memory Dump pane)
Change

Lets you modify the bytes located at the current cursor location and prompts you for an item of the current display type.

You can invoke this command by typing directly in the Dump pane.


Follow command (Memory Dump pane)
Follow

Lets you choose the following commands:

Near Code	Positions the Disassembly pane at the address currently selected in the Memory Dump pane.

Offset to Data	Lets you follow DWord-pointer chains (near and offset only) and positions the Memory Dump pane at the address specified by the DWord currently highlighted.


Previous command (Memory Dump pane)
Previous

This command restores the Memory Dump pane of the CPU window to the location displayed before you issued the last Follow command.


Display As command (Memory Dump pane)
Display as

Use the Display As command to format the data listed in the Memory Dump pane of the CPU window. You can choose any of the data formats listed in the following table:

Data type	Display format

Bytes	Hexadecimal bytes

Words	2-byte hexadecimal numbers

DWords	4-byte hexadecimal numbers

Singles	4-byte floating-point numbers using scientific notation

Doubles	8-byte floating-point numbers using scientific notation

Extendeds	10-byte floating-point numbers using scientific notation


Machine Stack pane

The Machine Stack pane is part of the CPU Window.

The Machine Stack pane displays the raw values contained in the your program stack. The pane has three sections: the memory addresses, the current values on the stack, and an ASCII representation of the stack values.

A green arrow indicates the value at the top of the call stack.

The Machine Stack pane displays the memory values in hexadecimal notation. The leftmost part of each line shows the starting address of the line. Following the address listing is a 4-byte listing of the values contained at that memory location. Each byte is represented by two hexadecimal digits. Following the hexadecimal display is an ASCII display of the memory. Non-printable values are represented with a period.

The format of the memory display depends on the format selected with the Display As command. If you choose one of the floating-point display formats (Floats or Doubles), a single floating-point number is displayed on each line. The Bytes format displays 4 bytes per line, Words displays 2 words per line, and DWords (the default) displays 1 long word per line.

You can press Ctrl+Left Arrow and Ctrl+Right Arrow to shift the starting point of the display up or down one byte. Using these keystrokes is often faster than using the Go to Address command to make small adjustments to the display.

Machine Stack pane commands

Right-click the Machine Stack pane to access the following commands:

Go to Address

Change Thread

Top of Stack

Follow

Previous

Change

Display As


Go to Address command (Machine Stack pane)
Go to Address

The Go to Address command prompts you for a new area of memory to display in the Machine Stack pane of the CPU window. Enter any expression that evaluates to a program memory location. Be sure to precede hexadecimal values with 0x.

The debugger displays dashes if you view a program memory location in which nothing is loaded.

You can also press Ctrl+Left Arrow and Ctrl+Right Arrow to shift the starting point of the display up or down one byte.


Change Thread command (Machine Stack pane)
Change thread

This command opens the Select a Thread dialog box. Select the thread you want to debug from the threads listed. When you choose a new thread from the Machine Stack pane, all panes in the CPU window reflect the state of the CPU for that thread.


Follow command (Machine Stack pane)
Top of stack

Positions the Machine Stack pane at the address of the stack pointer (the address held in the ESP register).


Follow command (Machine Stack pane)
Follow

Lets you choose the following commands:

Offset to stack	Lets you follow DWord-pointer chains (near and offset only) on the call stack and positions the Machine Stack pane at the address location of the value currently selected in the Machine Stack pane.

Near Code	Positions the Disassembly pane at the address location of the value currently selected in the Machine Stack pane.

Offset to Data	Lets you follow DWord-pointer chains (near and offset only) and position the Memory Dump pane at the address location of the value currently selected in the Machine Stack pane.


Previous command (Machine Stack pane)
Previous

This command restores the Machine Stack pane in CPU window to the location displayed before you issued the last Follow command.


Change command (Machine Stack pane)
Change

Lets you enter a new value for the stack word currently highlighted.

You can invoke this command by typing directly in the Machine Stack pane.


Display As command (Machine Stack pane)
Display as

Use the Display As command to format the data that’s listed in the Machine Stack pane of the CPU window. You can choose any of the data formats listed in the following table:

Data type	Display format

Bytes	Displays data in hexadecimal bytes

Words	Displays data in 2-byte hexadecimal numbers

DWords	Displays data in 4-byte hexadecimal numbers

Singles	Displays data in 4-byte floating-point numbers using scientific notation


Registers pane

The Registers pane is part of the CPU Window.

The Registers pane displays the contents of the CPU registers of the 80386 and greater processors. These registers consist of eight 32-bit general purpose registers, six 16-bit segment registers, the 32-bit program counter (EIP), and the 32-bit flags register (EFL).

After you execute an instruction, the Registers pane highlights in red any registers that have changed value since the program was last paused.

Registers pane commands

Right-click the Registers pane to access the following commands:

Increment Register

Decrement Register

Zero Register

Change Register

Change Thread


Increment Register command
Increment register

Increment Register adds 1 to the value in the currently highlighted register. This option lets you test “off-by-one” bugs by making small adjustments to the register values.


Decrement Register command
Decrement register

Decrement Register subtracts 1 from the value in the currently highlighted register. This option lets you test “off-by-one” bugs by making small adjustments to the register values.


Zero Register command (Registers pane)
Zero register

The Zero Register command sets the value of the currently highlighted register to 0.


Change Register command (Registers pane)
Change register

Lets you change the value of the currently highlighted register. This command opens the Change Register dialog box where you enter a new value. You can make full use of the expression evaluator to enter new values. Be sure to precede hexadecimal values with 0x.


Change Thread command (Registers pane)
Change thread

This command opens the Select a Thread dialog box. Select the thread you want to debug from the threads listed. When you choose a new thread from the Registers pane, all panes in the CPU window reflect the state of the CPU for that thread.


Flags pane

The Flags pane is part of the CPU Window.

The Flags pane shows the current state of the flags and information bits contained in the 32-bit register EFL. After you execute an instruction, the Flags pane highlights in red any flags that have changed value since the program was last paused.

The processor uses the following 15 bits in this register to control certain operations and indicate the state of the processor after it executes certain instructions:

Letters in pane	Flag/bit name	EFL register bit number

CF	Carry flag	0

PF	Parity flag	2

AF	Auxiliary carry flag	4

ZF	Zero flag	6

SF	Sign flag	7

TF	Trap flag	8

IF	Interrupt flag	9

DF	Direction flag	10

OF	Overflow flag	11

IO	I/O privilege level	12 and 13

NF	Nested task flag	14

RF	Resume flag	16

VM	Virtual 8086 mode	17

AC	Alignment check	18

Flags pane commands

Right-click the Flags pane to access the following commands:

Toggle Flag

Change Thread


Toggle Flag command (Flags pane)
Toggle flag

The flag and information bits in the Flags pane can each hold a binary value of 0 or 1. This command toggles the selected flag or bit between these two binary values.


Change Thread command (Flags pane)
Change thread

This command opens the Select a Thread dialog box. Select the thread you want to debug from the threads listed. When you choose a new thread from the Flags pane, all panes in the CPU window reflect the state of the CPU for that thread.


Event Log

The event log shows process control messages, breakpoint messages, OutputDebugString messages, and window messages. Using the right-click menu, you can clear the event log, save the event log to a text file, add a comment to the event log and set options for the event log. To display the event log, select View|Debug Windows|Event Log.

The context menu (right click) displays the following menu options:

Clear Events

Save Events to File

Add Comments

Properties

Dockable - Toggles whether the Event Log Window is enabled for docking

To set the properties for the Event Log, right click in the Event Log and select Properties or select Tools|Debugger Options. The properties include which messages to display in the event log and how many events to show in the event log.

COM options

When the Enable COM cross-process support option on the Distributed Debugging page of the Debugger Options dialog box is checked, COM events are added to the event log. There are three types of COM events: ClientStart, ServerStart, and ClientEnd. Each event shows the GUID, the method number, and the HResult of the COM RPC.

CORBA options

When the Enable CORBA cross-process support option on the Distributed Debugging page of the Debugger Options dialog box is checked, you can step into remote CORBA processes while debugging. When checked, the controls in the ORB events list box are enabled and you can set options for each ORB event that the debugger sends notifications for. For each event, you can define any number of action sets. Events for which you set options are added to the event log.


Clear Events
Clear Events (Event Log context menu)

See also

Select Clear Events to remove all messages from the event log window. Clear events is disabled when the Event Log is empty.

To save the current messages to a text file before clearing the event log, use Save Events To File.

To limit the size of the event log so that earlier messages are automatically cleared, use Properties.


Save Events to File
Save Events to File (Event Log context menu)

See also

Select Save Events to File to save the messages in the event log window to a text file. Choosing this command displays the Save Events to File dialog, where you can specify the name of a text file that will contain the current contents of the Event Log.

Save Events to File is disabled when the Event Log is empty.


Add Comment
Add Comment (Event Log context menu)

See also

Select Add Comment to add a message to the event log. This command displays the Add Comment to Event Log dialog, where you can type in any message. The message then appears at the end of the event log.


Options
Properties (Event Log context menu)

See also

Select Properties to display the Event Log page of the Tools|Debugger Options dialog. Use the Event Log page to:

Limit the number of messages that can appear in the event log (Length), allow the event log to grow until you manually clear it (Unlimited), or clear the event log (Clear log on run). When debugging multiple processes, only the first process loaded will cause the event log to be cleared.

Instruct the debugger to send messages to the event log when.

It encounters breakpoints (Breakpoint messages).

Changes occur to the process state (Process messages).

OutputDebugStrings .is called (Output messages).

The process receives Windows messages (Window messages).


Edit Breakpoint dialog box
Add Source Breakpoint dialog box (Run|Add Breakpoint|Source Breakpoint or Add|Source Breakpoint)

See also

The Source Breakpoint command displays the Add Source Breakpoint dialog box where you can set a breakpoint on a specific line location in your source code. When you run your program, the execution point in the Code editor indicates the breakpoint location. The breakpoint appears in the Code editor and the Breakpoint List.

Filename

Specifies the source file for the source breakpoint. Enter the name of the source file for the breakpoint.

Line Number

Sets or changes the line number for the breakpoint. Enter or change the line number for the breakpoint.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location. Functions are valid if they return a Boolean type.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes (set to 0 by default).

The debugger increments the pass count each time the line containing the breakpoint is encountered. When the pass count equals the specified number, the debugger pauses program execution.

Because the debugger increments pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. The debugger increments the pass count only when the conditional expression is true.


Source Breakpoint Properties dialog box
Source Breakpoint Properties dialog box (Breakpoint List context menu)

See also

Use the Source Breakpoint Properties dialog box to change a source breakpoint or set a new one.

Keep existing Breakpoint

Check “Keep existing Breakpoint” to keep the old breakpoint and create a new one. If you do not check “Keep existing Breakpoint”, the breakpoint will be changed and the old breakpoint will not be saved.

Filename

Specifies the source file for the source breakpoint. Enter the name of the source file for the breakpoint.

Line Number

Sets or changes the line number for the breakpoint. Enter or change the line number for the breakpoint.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes.

The debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, the debugger pauses program execution.

Because the debugger decrements pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. the debugger decrements the pass count only when the conditional expression is true.


Edit Source Breakpoint dialog box
Source Breakpoint Properties dialog box (Run|Add Breakpoint|Source Breakpoint or Add|Source Breakpoint)

See also

Use the Source Breakpoint Properties dialog box to modify the condition or pass count of source breakpoint.

Filename

Grayed out.

Line Number

Grayed out.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes.

The debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, the debugger pauses program execution.

Because the debugger decrements pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. the debugger decrements the pass count only when the conditional expression is true.


Add Address Breakpoint dialog box
Add Address Breakpoint dialog box (Run|Add Breakpoint|Address Breakpoint or Add|Address Breakpoint)

See also

The Address Breakpoint command displays the Add Address Breakpoint dialog box which you can use to set a breakpoint on a specific machine instruction. When you run your program, the execution point in the CPU window Disassembly pane indicates the breakpoint location. The breakpoint appears in the Code editor, if the address corresponds to a source line, and the Breakpoint List.

Address

Specifies the address for the address breakpoint. Enter the address for the breakpoint. When the address is executed, the program execution halts as modified by the condition and pass count. If the address can be correlated to a source line number, the address breakpoint is created as a source breakpoint. When the breakpoint is inspected in the Breakpoint Properties dialog, a Source Breakpoint Properties dialog will be displayed.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes.

The debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, the debugger pauses program execution.

Because the debugger decrements pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. the debugger decrements the pass count only when the conditional expression is true.


Address Breakpoint Properties dialog box;breakpoints
Address Breakpoint Properties dialog box (Breakpoint List context menu)

See also

Use the Address Breakpoint Properties dialog box to change an address breakpoint or set a new one.

Keep existing Breakpoint

Check “Keep existing Breakpoint” to keep the old breakpoint and create a new one. If you do not check “Keep existing Breakpoint”, the breakpoint will be changed and the old breakpoint will not be saved.

Address

Specifies the address for the address breakpoint. Enter the address for the breakpoint. When the address is executed, the program execution halts as modified by the condition and pass count. If the address can be correlated to a source line number, the address breakpoint is created as a source breakpoint. When the breakpoint is inspected in the Breakpoint Properties dialog, a Source Breakpoint Properties dialog will be displayed.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location, and the expression cannot contain function calls.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes.

The debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, the debugger pauses program execution.

Because the debugger decrements pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. the debugger decrements the pass count only when the conditional expression is true.


Edit Address Breakpoint dialog box
Address Breakpoint Properties dialog box (Code editor or CPU window context menu)

See also

Use the Address Breakpoint Properties dialog box to change the condition or pass count of an address breakpoint.

Address

Grayed out.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location, and the expression cannot contain function calls.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes.

The debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, the debugger pauses program execution.

Because the debugger decrements pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. the debugger decrements the pass count only when the conditional expression is true.


Add Data Breakpoint dialog box
Add Data Breakpoint dialog box (Run|Add Breakpoint)

See also

Use the Add Data Breakpoint dialog box to set a breakpoint on a specific address that halts execution when that address is written to. The breakpoint appears in the Code editor and the Breakpoint List, and, if there is a watch set in the watch view, the item will appear in red.

A data breakpoint is only valid for the current debug session. On the next debug session you must go to the Breakpoint view (Breakpoint List) and re-enable the data breakpoint. You can also re-select Break When Changed from the Watch view (Watch List).

Address

Specifies the address for the data breakpoint. Enter the variable name or address for the data breakpoint. When the address (up to the specified length) is written to, the program execution halts. Valid data names may be entered. For example, if you have an Integer variable X, you can enter X as the address.

Length

Specifies the length of the data breakpoint, beginning at “Address”. This is automatically calculated for standard data types.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location, and the expression cannot contain function calls.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes.

The debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, the debugger pauses program execution.

Because the debugger decrements pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. The debugger decrements the pass count only when the conditional expression is true.


Data Breakpoint Properties dialog box
Data Breakpoint Properties dialog box (Breakpoint List context menu)

See also

Use the Add Data Breakpoint dialog box to add a data breakpoint. The breakpoint appears in the Code editor if the address corresponds to a source line, and the Breakpoint List.

A data breakpoint is only valid for the current debug session. On the next debug session you must go to the Breakpoint view (Breakpoint List) and re-enable the data breakpoint. You can also re-select Break When Changed from the Watch view (Watch List).

Address

Specifies the variable name or address for the data breakpoint. Enter the address for the data breakpoint. When the address (up to the specified length) is written to, the program execution halts.

Length

Specifies the length of the data breakpoint, beginning at “Address”.

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to True. Enter a conditional expression to stop program execution.

You can enter any valid language expression. However, all symbols in the expression must be accessible from the breakpoint's location, and the expression cannot contain function calls.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes.

The debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, the debugger pauses program execution.

Because the debugger decrements pass counts with each pass, you can use them to determine which iteration of a loop fails. Set the pass count to the maximum loop count and run your program. When the program fails, you can calculate the number of loop iterations by examining the pass count number.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. The debugger decrements the pass count only when the conditional expression is true.

Keep existing Breakpoint

Check “Keep existing Breakpoint” to keep the old breakpoint and create a new one. If you do not check “Keep existing Breakpoint”, the breakpoint will be changed and the old breakpoint will not be saved.


Watch Properties dialog box

See also

Use the Watch Properties dialog box to add a watch or to change the properties of an existing watch. The watch appears in the Watch List.

In addition to changing the properties of a watch, you can change the value of a watch expression. Use the Evaluate/Modify dialog box to change the value of a watch expression.

To open the Watch Properties dialog box, do one of the following:

Choose Debug|Add Watch At Cursor from the Code editor context menu.

Choose Run|Add Watch.

Choose Add Watch from the Watch List context menu.

Right-click an existing watch in the Watch List and choose Edit Watch from the Watch List context menu.

Watch Properties

You can set the following properties for a watch expression:

Expression

Specifies the expression to watch. Enter or edit the expression you want to watch. Use the drop-down button to choose from a history of previously selected expressions.

Repeat Count

Specifies the repeat count when the watch expression represents a data element, or specifies the number of elements in an array when the watch expression represents an array.

When you watch an array and specify the number of elements as a repeat count, the Watch List displays the value of every element in the array.

Digits

Specifies the number of significant digits in a watch value that is a floating-point expression. Enter the number of digits.

This option takes affect only when you select Floating Point as the Display format. For more information, see Formatting watch expressions.

Enabled

Enables or disables the watch. Disabling a watch hides the watch from the current program run. When you disable a watch, its settings remain defined, but the debugger does not evaluate the watch. Disabling watches improves performance of the debugger because it does not monitor the watch as you step through or run your program. When you set a watch, it is enabled by default.

Allow Side Effects

When set, the watch is evaluated even if doing so would cause side effects. This option is off by default for all watches. When off, watches that would have side effects are not evaluated but instead generate the error message “Side effects not allowed.”

Display format radio buttons

To format the display of a watch expression, select a radio button.

For more information, see Formatting watch expressions.

To format the display of a watch expression,

Select a radio button to specify the format of the display.

See Watch properties format types for complete information.


Watch Properties format types

See also

By default, the debugger displays the result of a watch in the format that matches the data type of the expression. For example, integer values are normally displayed in decimal form. If you select the Hexadecimal radio button in the Watch Properties dialog box for an integer type expression, the display format changes from decimal to hexadecimal.

Character

Shows special display characters for ASCII 0 to 31 (displayed as #$0, #$1F, and so on). This format type affects characters and strings.

String

Shows characters for ASCII 0 to 31 in the Pascal #nn notation (#$0, and so on.) This format type affects characters and strings.

Decimal

Shows integer values in decimal form, including those in data structures. This format type affects integers.

Hexadecimal

Shows integer values in hexadecimal with the 0x prefix, including those in data structures. This format type affects integers.

Ordinal

Shows integer values as ordinals.

Pointer

Shows pointers in segment:offset notation with additional information about the address pointed to. It tells you the region of memory in which the segment is located and the name of the variable at the offset address. This format type affects pointers.

Record/Structure

Shows both field names and values such as (X:1;Y:10;Z:5) instead of (1,10,5).

Default

Shows the result in the display format that matches the data type of the expression. This format type affects all.

Memory dump

Shows the size in bytes starting at the address of the indicated expression. By default, each byte displays two hex digits. Use the memory dump with the character, decimal, hexadecimal, and string options to change the byte formatting.


Evaluate/Modify dialog box

See also

Use the Evaluate/Modify dialog box to evaluate or change the value of an existing expression or property. You can evaluate any valid language expression, except those that contain:

Local or static variables that are not accessible from the current execution point.

Function calls

The debugger enables you to change the values of variables and items in data structures during the course of a debugging session. You can test different error hypotheses and see how a section of code behaves under different circumstances by modifying the value of data items during a debugging session.

When you modify the value of a data item through the debugger, the modification is effective for that specific program run only. Changes you make through the Evaluate/Modify dialog box do not affect your source code or the compiled program. To make your change permanent, you must modify your source code in the Code editor, then recompile your program.

Modifying values (especially pointer values and array indexes), can have undesirable effects because you can overwrite other variables and data structures. Use caution whenever you modify program values from the debugger.

Keep these points in mind when you modify program data values:

You can change individual variables or elements of arrays and data structures, but you cannot change the contents of an entire array or data structure.

The expression in the New Value box must evaluate to a result that is assignment-compatible with the variable you want to assign it to. A good rule of thumb is that if the assignment would cause a compile-time or run-time error, it is not a legal modification value.

You cannot directly modify untyped arguments passed into a function, but you can typecast them and then assign new values.

Formatting values

When you evaluate an expression, the current value of the expression is displayed in the Result field of the dialog box. If you need to, you can format the result by adding a comma and one or more format following specifiers to the end of the expression entered in the Expression edit box. See Evaluate/modify format specifiers for more information.

To open the Evaluate/Modify dialog box, do one of the following:

Choose Run|Evaluate/Modify.

Choose Debug|Evaluate/Modify from the Code editor context menu.

Dialog box options

Expression

Specifies the variable, field, array, or object to evaluate or modify. Enter the variable, field, array, or object to evaluate or modify.

By default, the word at the cursor position in the Code editor is placed in the Expression edit box. You can accept this expression, enter another one, or choose an expression from the history list of previously evaluated expressions.

Result

Displays the value of the item specified in the Expression text box after you choose Evaluate or Modify.

New value

Assigns a new value to the item specified in the Expression edit box. Enter a new value for the item if you want to change its value.

Evaluate toolbutton

Evaluates the expression in the Expression edit box and displays its value in the Result edit box.

Modify toolbutton

Changes the value of the expression in the Expression edit box using the value in the New Value edit box.


Evaluate/Modify format specifiers

See also

By default, the debugger displays the result in the format that matches the data type of the expression. Integer values, for example, are normally displayed in decimal form. To change the display format, type a comma (,) followed by a format specifier after the expression.

Example

Suppose the Expression box contains the integer value z and you want to display the result in hexadecimal:

1.	In the Expression box, type z,h.

2.	Choose Evaluate.

Format specifiers

The following table describes the Evaluate/Modify format specifiers.

Specifier	Types affected	Description

,C	Char, strings	Character. Shows characters for ASCII 0 to 31 in the Pascal #nn notation.

,S	Char, strings	String. Shows ASCII 0 to 31 in Pascal #nn notation.

,D	Integers	Decimal. Shows integer values in decimal form, including those in data structures.

,H or ,X	Integers	Hexadecimal. Shows integer values in hexadecimal with the $ prefix, including those in data structures.

,Fn	Floating point	Floating point. Shows n significant digits where n can be from 2 to 18. For example, to display the first four digits of a floating-point value, type ,F4. If n is not specified, the default is 11.

,P	Pointers	Pointer. Shows pointers as 32-bit addresses with additional information about the address pointed to. It tells you the region of memory in which the pointer is located and, if applicable, the name of the variable at the offset address.

,R	Records, classes,

objects	Records/Classes/Objects. Shows both field names and values such as (X:1;Y:10;Z:5) instead of (1,10,5).

,nM	All	Memory dump. Shows n bytes, starting at the address of the indicated expression. For example, to display the first four bytes starting at the memory address, type 4M. If n is not specified, it defaults to the size in bytes of the type of the variable. By default, each byte is displayed as two hex digits. Use memory dump with the C, D, H, and S format specifiers to change the byte formatting.


See also

Evaluate/modify dialog box


Inspector window
The Inspector window

See also

The number of tabs and the appearance of the data in the Inspector window depends on the type of data you inspect. You can inspect the following types of data: arrays, classes, constants, functions, pointers, scalar variables integer, and so on), and interfaces. The Inspector window contains three areas:

The top of the Inspector window shows the name, type, and address or memory location of the inspected element, if available.

The middle pane contains one or more of the following views depending on the type of data you inspect. To change the view, click its tab.

Data	Shows data names (or class data members) and current values.

Methods	This view appears only when you inspect a class, or interface and shows the class methods (member functions) and current address locations.

Properties	This view displays only when you inspect an Object class with properties (such as a VCL Object) and shows the property names and current values.

 	The inspector does not automatically report the values of all properties because a function called to evaluate certain properties may have side effects that can affect the behavior of the program you are debugging. For example, if you evaluate certain properties before an object is fully constructed or before the object's associated window is created, some of the functions called will actually try to create the window. When your program actually creates the window, the app will likely throw an exception.

 	Therefore, for a property whose getters are member functions, the inspector window shows the value as <dynamic> on the properties page. To see the value of the property, click the ? button that appears next to <dynamic>. The debugger will continue to recalculate the value of the property each time the process stops (such as after a step or at a breakpoint). If you click the ? button again, the debugger stops recalculating the value of the property and again will show <dynamic> as the property's value each time the process stops.

The bottom of the Inspector window shows the data type of the item currently selected in the middle pane.

Inspector window commands

Right-click the Inspector window to access the following commands:

Change	Lets you assign a new value to a data item. An ellipsis (…) appears next to an item that can be changed. You can click the ellipsis as alternative to choosing the change command.

Show Inherited	Switches the view in the Data, Methods, and Properties panes between two modes: one that shows all intrinsic and inherited data members or properties of a class, or one that shows only those declared in the class.

Inspect	Opens a new Inspector window on the data element you have selected. This is useful for seeing the details of data structures, classes, and arrays.

Descend	Same as the Inspect command, except the current Inspector window is replaced with the details that you are inspecting (a new Inspector window is not opened). To return to a higher level, use the history list.

Type Cast	Lets you specify a different data type for an item you want to inspect. Type casting is useful if the Inspector window contains a symbol for which there is no type information, and when you want to explicitly set the type for untyped pointers.

New Expression	Lets you inspect a new expression.

Multiple process debugging

Inspectors are associated with the thread that was active when they were created. When a thread terminates, only the inspectors that were created while the thread was active are destroyed.


Decision Query Editor dialog box

The Decision Query Editor dialog box defines queries for the active decision query component. This dialog box specifies the database, tables, available fields, dimensions, and summaries for decision cubes bound to the decision query. It also displays the defined query in ANSI-92 SQL syntax.

To display the Decision Query Editor dialog box, apply a decision query component to a form, then right-click and choose Decision Query Editor from the menu.

Dialog box options

Dimensions/Summaries tab

Specifies the database, tables, available fields, dimensions, and summaries for decision cubes bound to the decision query.

SQL Query tab

Displays the defined query in ANSI-92 SQL syntax. You can edit the query by editing the ANSI-92 SQL statements.

Query Builder button

Displays the Visual Query Builder to select and join data tables.


Dimensions/Summaries tab (Decision Query editor)

Use this tab of the Decision Query Editor dialog box to define queries for the active decision query component. This tab specifies the database, tables, available fields, dimensions, and summaries for decision cubes bound to the decision query.

To display the Decision Query Editor dialog box, apply a decision query component to a form, then right-click and choose Decision Query Editor from the menu. Then, click the Dimension/Summaries tab if it isn't already visible.

To display a text version of the defined query, click the SQL Query tab.

Dialog box options

List Of Available Fields

Fields available for use in the decision query. If you're using more than one table and need to create a join, you can click the Query Builder button to launch the Visual Query Builder.

All Fields/Query Fields button

Toggles between displaying all fields in the selected table and only fields selected by the active query.

Dimensions

Lists fields selected as decision cube dimensions. To add a field to the Dimensions list, select a field in the List Of Available Fields, then click the right-arrow. To remove a field from the Dimensions list, select it in the list, then click the left-arrow.

Summaries

Lists fields selected as decision cube summaries.

To add a field to the Summaries list, select a field in the List Of Available Fields, then click the right-arrow. You will then see a list of summary operators (sum, count, or average). Choose the operator that you want to use to summarize the field values. If the selected operator is not appropriate for the type of the selected field, you will see an error message. If you want to let the decision cube compute averages (allowing for averaged summaries that can be subtotaled, drilled, and pivoted correctly), you must add both a count and a sum summary for the field. If you are creating several averages (over fields that do not contain blank values), you can check the Count (*) for averages check box instead of adding a count summary for each field you will average.

To remove a field from the Summaries list, select it in the list, then click the left-arrow.

Table

Shows the active table from those included in the active database. You can select a different table from this dropdown list.

Database

Shows the active database from those included in the query. You can select a different database from this dropdown list. If you are using local tables, you can type in the path to the directory that contains the tables.


SQL Query tab (Decision Query editor)

Use this tab of the Decision Query Editor dialog box to display SQL queries for the active decision query component.

If a query hasn't yet been defined, you can enter one directly in ANSI-92 SQL. Or, you can define it visually by selecting a database, tables, and fields on the Dimensions/Summaries tab.

To display the Decision Query Editor dialog box, apply a decision query component to a form, then right-click and choose Decision Query Editor from the menu. Then, click the SQL Query tab.

Dialog box options

Query Text

Displays SQL statements that define the current decision query. The defined query apears in ANSI-92 SQL syntax. You can edit the query directly by editing the ANSI-92 SQL statements; they are automatically converted to and from any appropriate dialect used to communicate with the server.

Edit Query/Edit Done button

When the Edit Query button is active, text appears in the Query Text window. You can type over it to edit it.

When you begin typing, button text changes to Edit Done. Click the button when your edit is complete. You can click Cancel Edit to restore the original query text.

Cancel Edit button

Cancels the current text edit and restores the original query.


Decision Cube Editor dialog box

The Decision Cube Editor dialog box defines active dimensions and summaries for the active decision cube component. These settings are reflected in decision pivots bound to the decision cube.

To display the Decision Cube Editor dialog box, apply a decision cube component to a form, bind it to a decision query, then right-click the decision cube and choose Decision Cube Editor from the menu.

Dialog box options

Dimension Settings tab

Specifies the display name, type, active type, format, grouping, and initial value for fields supplied to the decision cube from the decision query component.

Memory Control tab

Displays the following settings for memory protection:

Decision cube dimension, summary, and cell maximums

Designer data display choices


Dimension Settings tab (Decision Cube editor)

Use this tab of the Decision Cube Editor dialog box to specify the display name, type, active type, format, grouping, and initial value for fields supplied to the decision cube from the decision query component.

To display the Decision Cube Editor dialog box, apply a decision cube component to a form, bind it to a decision query, then right-click the decision cube and choose Decision Cube Editor from the menu. Then, click the Dimension Settings tab if it isn't already visible.

Dialog box options

Available Fields

Fields supplied to the decision cube component by the decision query component. When a field in the list is highlighted, its settings appear in the text boxes and lists on the right side of the dialog box.

Display Name

The name to appear in decision pivot, decision grid, and decision graph labels for the highlighted field.

Type

Whether the highlighted field is a dimension or a summary (for information only, not editable).

Active Type

When the information for the highlighted field is loaded: As Needed, when required for display; Active, all the time; Inactive, never.

Format

The format string that describes how to display values for the highlighted field.

Grouping

Whether to display all values or ranges of values. Use None to display all values. Use Year, Quarter, or Month to display a range of dates. Use Single Value for a single-dimension display. If custom ranges have been added by an application developer, they also appear in the list.

Initial Value

The starting value for a date or custom range, or the single value to display.


Memory Control tab (Decision Cube editor)

Use this tab of the Decision Cube Editor dialog box to change the following settings for memory protection:

Decision cube dimension, summary, and cell maximums

Designer data display choices

To display the Decision Cube Editor dialog box, apply a decision cube component to a form, bind it to a decision query, then right-click the decision cube and choose Decision Cube Editor from the menu. Then, click the Memory Control tab.

Dialog box options

Cube Maximums

Sets maximums and displays current values for decision cube dimensions, summaries, and cells.

Maximum

Sets the maximum allowable dimensions, summaries, and cells for the selected decision cube. The lower the number, the less memory is used.

Current

The current number of dimensions, summaries, and cells in use by the decision cube (for information only, not editable).

Active+Needed

The number of dimensions and summaries that have Active Type set to Active or As Needed on the Dimension Settings tab of the Decision Cube Editor dialog box, and the number of cells required to display them (for information only, not editable).

Active

The number of dimensions and summaries that have Active Type set to Active on the Dimension Settings tab of the Decision Cube Editor dialog box, and the number of cells required to display them (for information only, not editable).

Get Cell Counts button

When clicked, runs a query to estimate the number of cells used.

Designer Data Options

Saves time and memory by displaying only the specified data at design time.

Display Dimension Names

When checked, displays only dimension and summary names at design time. No values appear.

Display Names And Values

When checked, displays dimension and summary names and values at design time. No totals appear.

Display Names, Values, And Totals

When checked, displays dimension and summary names, values, and totals at design time.

Runtime Display Only

When checked, displays dimension and summary names, values, and totals only at runtime. None of this data appears at design time.


Response Editor dialog box

See Also

This dialog box lets you to define the contents and format of an HTTP response message for the TQueryTableProducer or TDataSetTableProducer component.

To display the Response Editor dialog box, place a query table producer or dataset table producer on a form. Right-click the component and choose Response Editor from the menu.

Dialog box options

Field list

The field list in the upper center of this dialog box shows the Field Name and Field Type for each field in the response table. You can use the Object Inspector to change properties for the highlighted field.

Table Properties

These are the properties of the overall response table.

Align

THTMLTableAttributes.Align, the horizontal alignment of the table within the HTML document.

Border

THTMLTableAttributes.Border, the width of the table border; -1 indicates no border will be drawn.

BgColor

THTMLTableAttributes.BgColor, the background color of the HTML table.

Cellpadding

THTMLTableAttributes.CellPadding, the amount of space to leave around the contents of each cell in the HTML table. A value of -1 indicates that the web browser should decide how to pad the cells of the HTML table.

Cellspacing

THTMLTableAttributes.CellSpacing, the amount of space to leave between cells in the HTML table. A value of -1 indicates that the web browser should decide how to separate the cells of the HTML table.

Width

THTMLTableAttributes.Width, the width of the entire HTML table as a percentage of the width of the web browser window. The default, 100, means the table will span the entire browser window.

Add button

Adds a column to the response table. Use the Object Inspector to enter the title and choose a field.

Delete button

Removes the selected column from the table.

Move Up/Down buttons

Change the order of columns in the table by moving the selected column up (toward the left edge of the table) and down (toward the right).

Add All Fields button

Creates a column for every field in the dataset (query) bound to the query table producer.

Restore Defaults

Restores default property settings for the selected column.


Code editor window

See Also

The Code editor window contains one or more Code editor pages. The Code editor window cannot be empty -- once you close the last page in the Code editor window, the window is closed.

You can open multiple files in the Code editor. Each file opens on a new page of the Code editor, and each page is represented by a tab at the top of the window. For example, when you open a project, it becomes the first tab in the window. Any other files that you open, such as unit files, become subsequent tabs in the window.

You can open a copy of any editor page, which opens a separate window.

To open the Code editor, you can do one of the following:

Click on the name of a file in the Project Manager.

With a project open, choose Project|View Source.

Open a file using File|Open.

Choose View|New Edit Window.

The New Edit Window command opens a copy of the current page in the Code editor.

If you have modified the code and not saved the changes, C++Builder opens the Save As dialog box, where you can enter a file name.


Code browser

See also

In the Code editor, hold down the Ctrl key while passing the mouse over the name of any class, variable, property, method, or other identifier. The mouse pointer turns into a hand and the identifier appears highlighted and underlined; click on it, and the Code editor jumps to the declaration of the identifier, opening the source file if necessary. You can do the same thing by right-clicking on an identifier and choosing Find Declaration.

Use Tooltip Symbol Insight to see where an identifier is declared before you jump to it.

Use the navigation buttons in the upper right corner of the Code editor to browse forward and backward through the files you’ve opened.

The Code browser can find and open only units in the project’s Search path or Debug Source path, or in C++Builder’s Browsing or Library path. Directories are searched in the following order:

1. The project Search path (Project|Options|Directories/Conditionals).

2. The project Source path (Project|Options|Directories/Conditionals).

3. The global Browsing path (Tools|Environment Options|Library).

4. The global Library path (Tools|Environment Options|Library). The Library path is searched only if there is no project open in the IDE.

The Code browser cannot find identifiers declared in new, unsaved unit files.

Note:	Code browsing does not work in package projects.


Getting Help in the Code editor

See also

Context-sensitive Help is available from nearly every portion of the Code editor. The context is determined by the current position of the cursor.

To get context-sensitive Help from the Code editor window, do one of the following:

Place the cursor on the property, event, method, property, procedure or type for which you want Help, then press F1.

Right-click the Code editor, then choose Topic Search from the context menu.

If Help is not available for the specific topic you selected, Help displays a message reading, "Help Topic Not Found." If this message appears, you have the three options:

Return to the main Help screen.

Select another topic for Help to search.

Return to a previously viewed topic.


Viewing pages in the Code editor

See also

When a page of the Code editor is displayed, you can scroll through all the data it contains, not just particular sections of your code.

To view a page in the Code editor, do one of the following,

If the Code editor is already the active window, click the tab corresponding to the page you want to view.

Choose View|Units


Code editor context menu

See also

The Code editor context menu contains commands for navigating, modifying, and debugging your source code. This menu is unique to the Code editor, and the commands contained in the menu pertain only to the Code editor.

All possible context menu commands are listed below (some appear only at certain times). To view detailed information on a Code editor context menu command, click that command:

Enabled

Breakpoint Properties

Open Source/Header file

Find Declaration

Close Page

Open File At Cursor

New Edit Window

Topic Search

Add to Interface

Toggle Bookmarks

Goto Bookmarks

Debug

View As Form

Read Only

Message View

View Explorer

Properties

To display the Code editor context menu, do one of the following:

Right-click anywhere in the Code editor window.

Press Alt+F10 when the Code editor window is active.


Enabled (Code editor context menu)

Enabled context menu

Enabled is a toggle menu item that enables and disables a breakpoint.


Breakpoint properties (Code editor context menu)

Breakpoint properties context menu

Choose Properties from the Code editor context menu to open the Source Breakpoint Properties dialog that allows you to modify source breakpoints.


Open Source/Header file (Code editor context menu)

See Also

Choose Open Source/Header file from the Code editor context menu to open or display the header or source file related to the currently viewed file.

For example, if you have Unit1.cpp open and choose Open Source/Header file, Unit1.h will be opened if it is not already, or will be switched to become the active file in the edit window.


Close Page (Code editor context menu)

Code editor context menu

Choose Close Page from the Code editor context menu to close the current page in the Code editor window.

If you have modified code, not saved the changes, and this is the last page open in a file, C++Builder opens the Save AsIDH_ dialog box, where you can enter a new file name.

If you are closing the last page in the project and have not saved it yet, C++Builder opens the Save Project As dialog box, where you can enter a name for the project.


Open File At Cursor (Code editor context menu)

Code editor context menu

Choose Open File At Cursor from the Code editor context menu to open the file at the current cursor position.

C++Builder searches for files with the default extension of .CPP, unless another file extension is explicitly specified. Similarly, C++Builder uses the directory settings for unit and include files specified in the Directories/Conditionals page of the Options|Project dialog box.

To change directory settings for unit and include files,

1.	Choose Options|Project from the main C++Builder menu.

2.	Click the Directories/Conditionals page.

3.	Set unit and include directories as you want.

4.	Choose OK to put your choices into effect.


New Edit Window (Code editor context menu)

Choose View|New Edit Window to open a new Code editor that contains a copy of the active page from the original Code editor.

Any changes you make to either the original or the copy are reflected in both files.

So that you can distinguish between the windows, the caption in the original window is postfixed with a 1, the first copy with a 2, the second copy with a 3, and so on.


Topic Search (Code editor context menu)

Choose Topic Search from the Code editor context menu to display a Help window for the word or token at the cursor in the Code editor.

If no Help topic exists, the Search dialog box is displayed, with the closest match highlighted.


Toggle Bookmarks (Code editor context menu)

Choose Toggle Bookmarks from the Code editor context menu to set or clear up to 10 bookmarked locations In each file you have open in the Code editor. Bookmarks let you save your place within a long text file. You can also press Ctrl+K and the number of the bookmark to set or change the location of a bookmark. When a bookmark is set, you see a gray box in the left margin of the Code editor with the bookmark number in it.


Goto Bookmarks (Code editor context menu)

Choose Goto Bookmarks from the Code editor context menu to display a list of bookmarked locations you can jump to in the Code editor. You can also jump to bookmarks by typing CTRL+the number of the bookmark.


Message View (Code editor context menu)

Choose Message View to toggle the message window at the bottom of the Code editor. When you compile an application, errors or warning messages are displayed in the message window; and when you conduct a search, search results are displayed in the message window.

The message window context menu commands are listed below.

View Source	Scrolls the Code editor to the location of the error message or search result that is selected in the message window.

Edit Source	Scrolls the Code editor to the location of the error message or search result that is selected in the message window, and makes the Code editor active.

Clear Compiler Messages	Clears only compiler messages from the message window.

Clear Search Results	Clears only search result messages from the message window.

Save messages	Lets you save the messages in a file.

View editor	Displays the editor (useful if the Message View is undocked).

Dockable	Lets you make the Message View either dockable or not. It’s docked to the Code editor by default.


Debug (Code editor context menu)

Choose Debug from the Code editor context menu to select the following debugger commands:

Toggle Breakpoint

Run to Cursor

Inspect

Goto Address

Evaluate/Modify

Add Watch at Cursor

ViewCPU


Toggle Breakpoint (Code editor context menu)
Debug|Toggle Breakpoint (Code editor context menu)

See also	Code editor context menu

Choose Toggle Breakpoint from the Code editor context menu to toggle a breakpoint on and off at the current cursor position.

If no breakpoint is set when you choose this command, C++Builder sets one and turns it on. If a breakpoint is already set, choosing this command toggles the breakpoint off.

To modify breakpoint properties right click in the gutter (left margin of code editor) and choose Breakpoint Properties. You can also choose Properties from the Breakpoint List window context menu.


See also

Setting breakpoints

Using breakpoints

About the integrated debugger


Run To Cursor (Code editor context menu)
Debug|Run To Cursor (Code editor context menu)

See also	Code editor context menu

Choose Run To Cursor to run the loaded program up to the location of the cursor in the Module window.

When you run to the cursor, your program is executed at full speed, then pauses and places the execution point on the line of code containing the cursor.

You can use Run To Cursor to run your program and pause before the location of a suspected problem. You can then use Run|Step Over or Run|Trace Into to control the execution of individual lines of code.

An alternative way to perform this command is:

Choose Run|Run To Cursor.


See also

Controlling program execution

About the integrated debugger


Inspect (Code editor context menu)
Debug|Inspect (Code editor context menu)

Code editor context menu

Choose Inspect to open an Inspector window for the term highlighted (or at the insertion point) in the Code editor. If the insertion point is on a blank space when you choose this command, an Inspect input dialog displays where you can enter an expression you want to inspect.

This command is only available when the integrated debugger is paused in a program you are debugging, such as when

You are stepping through code.

Your program is stopped at a breakpoint.

You first choose Run|Run and then choose Run|Pause.

An alternate way to open the Inspect input dialog is to choose Run|Inspect.


Goto Address (Code editor context menu)
Debug|Goto Address (Code editor context menu)

The Go to Address command prompts you for a new area of memory to display in the Disassembly pane of the CPU window. Enter any expression that evaluates to a program memory location. Be sure to precede hexadecimal values with $. This command will only show the address in the editor if the source for the address entered can be found. It will open the CPU view, if source cannot be found. If the CPU view is already open, it becomes the active view.

Note: This command is available only while you run your program from the IDE.


Evaluate/Modify (Code editor context menu)
Debug|Evaluate/Modify (Code editor context menu)

See also	Code editor context menu

The Evaluate/Modify command opens the Evaluate/Modify dialog box, which lets you evaluate or change the value of an existing expression. From the code editor, this context menu will use highlighted text, or text at the cursor position, and automatically evaluate it.

An alternate way to perform this command is:

Choose Run|Evaluate/Modify.


See also

Evaluating and modifying expressions

About the integrated debugger


Add Watch At Cursor (Code editor context menu)
Debug|Add Watch At Cursor (Code editor context menu)

See also	Code editor context menu

The Add Watch At Cursor command opens the Watch Properties dialog box, where you can create and modify watches. After you create a watch, use the Watch List to display and manage the current list of watches.

Watch Properties only open if the cursor is on whitespace. Otherwise, the expression highlighted, or at the cursor position, is automatically added as a watch.

Alternate ways to perform this command are:

Choose Run|Add Watch from the Code editor context menu.

Choose Add Watch from the Watch List context menu.

Right-click an existing watch in the Watch List and choose Edit Watch from the Watch List context menu.


See also

Watching expressions

About the integrated debugger


CPU view (Code editor context menu)
Debug|View CPU (Code editor context menu)

Code editor context menu

The View CPU command opens the CPU Window, for debugging a specific low-level aspect of an application such as a contents of the program stack, registers or CPU flags, memory dumps, or assembly instructions disassembled from the application’s machine code.


Read Only (Code editor context menu)

Code editor context menu

Choose Read Only from the Code editor context menu to make the current open file read only. When a file is read only, you cannot make any changes to the file.

When you mark a file as read only this command is checked on the Code editor context menu and "Read only" is displayed in the Code editor status line.


Write Block To File dialog box

See also

This dialog box enables you to specify the filename and location of an operating system file in which you want to write a block of text you have selected in the Code editor Window.

When using default key mapping, access this dialog box with: Ctrl+K+W


Read File As Block dialog box

See also

This dialog box enables you to specify the filename and location of an operating system file containing a block of Object Pascal source code which you want to insert in the Code editor Window at the current cursor position.

When using default key mapping, access this dialog box with: Ctrl+K+R


ImageList Editor

Use the ImageList Editor at design time to add bitmaps and icons to a TImageList component. To display the ImageList editor, double-click a TImageList component or right-click it and choose ImageList Editor

Selected Image

Displays information about the image selected in Images. Controls in this group are grayed if there are no images available or the selected image was added in a previous use of the editor.

Transparent Color

Determines which color is used to create a mask for drawing the image transparently. The default transparent color is the color of the bitmap's left-most pixel in the bottom line. Transparent Color is set to clNone for an icon image (icons are already masked).

Fill Color

Used when an image is smaller than the TImageList component to specify what color the empty area of the image is filled with when it is cropped or centered. Fill Color is set to clNone for an icon image.

Options

Specifies how to adjust a newly added bitmap image whose width or height don't match the imagelist's width or height. (Disabled for icons.)

Setting	Description

Crop	Displays the section of the image beginning at the top-left, extending the imagelist width and height towards the bottom-right (default)

Stretch	Causes the entire image to stretch so that it fits the imagelist width and height

Center	Centers the image within the imagelist width and height. If the image width or height is larger than the imagelist width or height, the image may be clipped.

Images

Contains a preview list view of all the images in the imagelist, and controls for adding or deleting images from the list. Each image is displayed within a 24x24 area for easier viewing of multiple images. Beneath each image is a caption that indicates the zero-based position of the image within the imagelist. You can edit the caption to change an images position in the list or drag the image to its new position.

Add

Displays the Add Images dialog box, which lets you select one or more bitmaps or icons to add to the imagelist. The images then appear highlighted in the preview list view and their captions are assigned sequential values in the imagelist.

If a bitmap is larger than the imagelist width or height by even increments, a prompt appears asking whether the ImageList editor should divide the bitmap into several images. This is useful for toolbar bitmaps, which are usually composed of several small images in a sequence and stored as one larger bitmap.

Delete

Removes the selected images from the imagelist. All images left after clicking Delete are repositioned so they are a contiguous zero-based list.

Clear

Removes all images from the imagelist.


Glossary

A

accelerator key

actual parameter

actual variable

alias

ancestor

application

array

ASCII

B

base type

batch operation

BDE

BDE Adminstrator

BDE Configuration Utility

BLOB

block

bool

Borland Database Engine

breakpoints

byte

C

callback routines

call stack

canvas

char

child

class

client

client area

closure

column

COM

compile

compiler directive

compile time

compile-time error

complete evaluation

component

conditional symbol

connection component

const

constant

constant address expression

container application

container component

context menu

control

CORBA

D

data

data access component

data-aware

data control component

data module

data type

database

database server

dataset

DDE client

DDE conversation

DDE server

declaration

default ancestor

default event

default new form

default new project

derive

descend

descendant

design time

design-time package

detail table

dispatch

drag

dynamic

dynamic data exchange (DDE)

dynamic-link library (DLL)

E

embedding

encapsulate

end user

enumerated data type (enum)

exception

exception handler

execution point

expressions

event

event handler

F

file buffer

file type

filter

filter program

focus

form

formal parameter

function

function header

G

global heap

global variable

glyph

grandchild

grandparent

grid

H

handling exceptions

heap

heap suballocator

help context

Hint

host type

IJK

IDAPI

identifier

IDL

include file

index

index type

inheritance

instance

int

integrated debugger

interface

key

L

language driver

late binding

linking

literal value

local heap

local symbol information

local variable

lock

logic error

long

lookup table

loop

M

main form

marshaling

master table

method

method identifier

MDI application

MIDAS

modal

modeless

module

N

nonvisual component

nonwindowed control

null

O

object file (.OBJ)

object instance variable

object type

OLE

OLE container

OLE object

OLE server

ORB

override

owner

P

package

parameter

parent

passing by reference

passing by value

pixel

pointer

power set

primary index

private

program

project

project directory

project file

project group

property

protected

protected block

public

published

pure virtual

Q

qualified identifier

qualified method identifier

qualifier

query

R

raise

real

record

recursion

relational database

report

root class

routine

row

runtime

runtime error

runtime library

runtime only

runtime package

S

scope

separator

separator bar

service

set

short-circuit evaluation

short int

sizing handles

skeleton

source code

SpeedMenu

splash screen

SQL

SQL table

stack

statement

static

static method

step over

string

string list

stub

symbol

symbol table

T

table

tag property

template

trace into

typecasting

type compatibility

typedef

type definition

type library

U

unit

untyped file

unqualified identifier

use count

user-defined

V

variable

virtual

visual component

VOID pointer

W

warning

watches

window handle

windowed control

wizard

word

wrapper

XYZ

z-order


pure virtual

A method that is declared but not implemented. Descendant types must override the pure virtual method.


accelerator key

Accelerator keys enable the user to access a menu command or component from the keyboard, by pressing Alt+ the appropriate letter, indicated in your code by the preceding ampersand. The letter after the ampersand appears underlined in the menu or component caption.


actual parameter

A variable, expression, or constant that is substituted for a formal parameter in a function call.


actual variable

A variable that a program can use at runtime, as distinguished from the definition of that variable within the program. A location in memory used for storage purposes, as distinguished from an identifier.


alias

A name that specifies the location of database tables. If the database is on a server, an alias also specifies connection parameters for the server.


ancestor

An class from which another class is derived. An ancestor class can be a parent or a grandparent. See default ancestor.


application

An application is the executable file and all related files that a program needs to function which serve a common purpose or purposes, as distinguished from the design and source code of the project. Often used synonymously with 'program'. Compare with program and project.


array

A group of data elements identical in type that are arranged in a single data structure and are randomly accessible through an index.


ASCII

An acronym for "American Standard Code for Information Interchange" and used to describe the byte values assigned to specific characters. Examples: The capital letter A has an ASCII value of 65. The ASCII code for a space is 32.


base type

The type referred to in a pointer declaration, an array declaration, or the enumeration type used in a set declaration. A type declaration builds a new type by combining or referencing one or more other base types.


batch operation

Operations that you perform with the TBatchMove component on groups of records, or on datasets, to add, delete, or copy groups of records in a single operation.


BDE

Borland Database Engine; also referred to in some documentation as IDAPI. C++Builder uses this database engine to access and deliver data. BDE maintains information about your PC's environment in the BDE configuration file (usually called IDAPI.CFG). Use the BDE Administrator to change the settings in this configuration file.


BDE Administrator

A program that enables you to change the settings in the BDE configuration file, usually called IDAPI.CFG. The executable file is named BDEADMIN.EXE. Formerly called the BDE Configuration Utility.


BDE Configuration Utility

See BDE Administrator.


BLOB

Binary large object. BLOB data is indeterminate in size and is not stored directly in the records of the database table.

Many database tables use specific field types to contain BLOB data. For example, C++Builder lets you access BLOB data that exists as plain text with the TDBMemo component, and BLOB data that exists as a graphic with the TDBImage component.


block

The associated declaration and statement parts of a program or subprogram, often enclosed in curly braces ({}).

Examples: the body of a while loop  defines a block of code that is executed only if the condition is true. A try..catch statement contains a try block of code that may generate an exception, and a catch block to where execution continues if an exception is thrown.


bool

A keyword representing a data type that can take only the value false or true. The keywords false and true are Boolean literals with predefined values. false is numerically zero and true is numerically one. These Boolean literals are rvalues; you cannot make an assignment to them.


Borland Database Engine

See BDE.


breakpoints

A place in your code where you want the program to pause or perform an action so that you can examine the current values of program variables and data structures, or the call stack.

Breakpoint behavior falls into two categories:

Unconditional (or simple). The breakpoint is activated whenever the debugger reaches the line in your source or the machine instruction where you set the breakpoint.

Conditional. The breakpoint is activated only when it satisfies the conditions that you specify.


byte

An 8-bit wide data type capable of holding a value from 0 to 255.


callback routines

Routines in your application that are passed to a function and called from within that function’s body. For example, EnumFonts is a Windows routine that calls a given callback function for every font installed in the system.


call stack

The list of calls that were made to reach the present location, and which consequently show the path by which the program must return. Available during debugging.


canvas

The graphical drawing surface of an object. The canvas has a brush, a pen, a font, and an array of pixels. The canvas encapsulates the Windows device context.


char

A type specifier that defines a character data type. A char can be signed, unsigned, or unspecified. By default, signed char is assumed. This data type is used for very small numbers and ASCII characters.


child

1.	A child class is any class that is descended from another. For example, in "type B = class(A)", B is a child of A. Compare with grandchild.

2.	The child of a window appears inside that window and cannot draw outside of its bounds. This is called a child or child window.


class

A list of features representing data and associated code assembled into single entity. A class includes not only features listed in its definition but also features inherited from ancestors.

A list of features representing data and associated code assembled into single entity. A class includes not only features listed in its definition but also features inherited from ancestors.


client

Generically, any thing that requests the services of something else. In Windows, a client is code that makes use of the Windows API.

In database systems, a workstation connected to an intelligent "back-end" server from which it can request data. The client workstation can process the data locally and write it back to the server.

In distributed applications, a client is an application that initiates communication with a server application on a remote system.


client area

In Windows, the area of a control which a program (that is, a client of Windows' services) is allowed to draw on. A client area might appear on a window, for example, that would usually exclude the frame and title bar.


closure

A pointer to a member function that contains an object pointer. Unlike when using regular C++ member function pointers, you can assign a derived class’s member function to a base class’s member function pointer if that member function is a closure. Use the __closure keyword to declare a closure.


column

The vertical component of a table, sometimes called a field. A column contains one value for each row in a table. See also row.


COM

Component Object Model. COM is Microsoft’s client/server object-based model designed to enable interaction between software components and applications. The key aspect of COM is that it enables communication between clients and servers through interfaces. Information about these interfaces is usually included in a type library.


compile

The act of translating a block of source code into machine instructions. (As opposed to "interpret" which is the line-by-line translation of source code to machine instructions.)

Also see linking.


compiler directive

An instruction to the compiler that is embedded within the program.


compile time

The period of time when the compiler is actively compiling source code.


compile-time error

An error detected by the compiler during compilation, such as a syntax error or unknown identifier.


complete evaluation

Every operand in a boolean expression built from the and (&&) and or (|) operators evaluates, even if the expression result can be determined before the entire expression is evaluated. This is useful when operands are routines that can alter the meaning of a program. Opposite of short-circuit boolean evaluation.


component

1.	The elements of a C++Builder application, iconized on the Component palette. Components, including forms, are objects you can manipulate. Forms and data modules are components that can contain other components (forms and data modules are not iconized on the Component palette).

2.	In C++Builder, any class descended from TComponent is, itself, a component. In the broader sense, a component is any class that can be interacted with directly through the Form Designer. A component should be self-contained and provide access to its features through properties.


conditional symbol

Used with conditional compiler directives to specify a condition that is either true or false. You define (set to true) or undefine (set to false) conditional symbols with the #define and #undef directives.


connection component

Any descendant of TCustomRemoteServer. This family of components allow clients in a multitier database application to locate and establish connections to remote data modules on MIDAS servers.


constant

An identifier with a fixed value in a program. At compile time, all instances of a constant in source code are replaced by the fixed value.


constant address expression

An expression that takes the address, the offset, or the segment of a global variable or a function.

Constant address expressions cannot reference local variables (stack-based) or dynamic (heap-based) variables, because their addresses cannot be computed at compile time.


const

Use the const modifier to assign an initial value to a variable that cannot be changed by the program. Any future assignments to a const result in a compiler error.


container application

An application that contains an embedded OLE object. (See OLE.)


container component

Any of several component classes that have the inherent ability to contain other components. Examples include TForm, TPanel, TControlBar, and TGroupbox. A container component is the parent of the components it contains.


context menu

A local menu on an object which you access by right-clicking with a pointing device.


control

A visual component (one that appears at runtime). Specifically, any descendant of TControl.


CORBA

Common Object Request Broker Architecture. CORBA is a specification adopted by the Object Management Group (OMG) to address the complexity of developing object applications. It defines an IDL for defining object interfaces, the protocols for remote communication, and a number of standard service interfaces. The CORBA standard has been adopted on multiple platforms.


data

1.	Information stored in a database. Data may be a single item in a field, a record that consists of a series of fields, or a set of records. C++Builder applications can retrieve, add, modify, or delete data in a database.

2.	Generally, any information that has intrinsic value regardless of the means used to access it.


data access component

A VCL component that enables you to connect to a database and access its data. Data access components are visible on a form only at design time, not at runtime.


data-aware

Able to display and update data stored in an underlying table. All VCL data control components are data-aware.


data control component

A VCL component that enables you to create the interface of a database application. Many data controls are data-aware versions of component classes available on the Standard page of the Component palette.


data module

A repository for non-visual components. At design time, a data module looks like an empty window. You can place any non-visual components in the data module. Use data modules to organize business logic separately from the UI of an application.


data type

A fundamental unit of data definition that defines what kind of data can be stored in memory or in data tables, and what operations can be performed on that data.


database

A collection of data in tables.


database server

A system that manages relational databases. For example, SQL Server is a type of database server.


dataset

A logical view of the data from a database. A dataset is a collection of data determined by a TDataSet descendant such as TClientDataSet, TTable, TQuery, or TStoredProc.

A dataset defined by TTable includes every row in a database able. A dataset defined by a TQuery contains a selection of rows and columns from one or more tables.


DDE client

In a DDE conversation, the client is the application that requests data. The DDE client is often called the destination.


DDE conversation

A link between a DDE client application and a DDE server application which provides a means for both applications to continuously and automatically send data back and forth.


DDE server

In a DDE conversation, the server is the application that updates the DDE client. The DDE server is often called the source.


declaration

Text that gives the name of a routine followed by a list of formal parameters, followed by the function's return type. In a unit, a routine may have a header entered into the interface part, and then again in the implementation part. The second appearance of the header may be an exact duplicate of the header in the interface part, or may be only the name of the routine.


default ancestor

The ancestor of any class that does not specify an ancestor: In the VCL source code, the default ancestor is TObject.


default event

For a given component, the event whose event handler is automatically generated or displayed in the source code when you double-click the component at design time. For example, the OnClick event is the default event for a Button component.


default new form

The Form Template that is used to create a new form in the IDE at design time when you choose File | New Form. In a new installation, the Blank Form template is used. You can change the specified Form Template in the Object Repository dialog box (Tools | Repository).


default new project

The Project Template that is used to open a new project in the IDE at design time when you choose File | New Project. In a new installation, the Blank Project template is used. You can change the specified Project Template in the Object Repository dialog box (Tools | Repository).


derive

To create a new class based on an existing class. The new class inherits all of the features of the existing class, which is called its parent or, more generically, an ancestor.


descend

To acquire, in the process of being created, all the characteristics of another class. A class that descends from another is a descendant of the parent class. The process of creating a descendant class is deriving.

See also ancestor, derive, descendant, inheritance, and parent.


descendant

An class derived from another class. A descendant is type compatible with all of its ancestors.


design time

Phase when you can use the IDE to design your application, using the form, the Object Inspector, Component palette, Code editor, and so forth; as opposed to runtime, when the application you design is actually running.


design time package

A special dynamic-link library used by the IDE to install components and to create special property editors for custom components.


detail table

1. In multi-table relationships, the table whose records are subordinate to those of the master table. In a data model, the detail table is the one being pointed to by another table. For example, in the following data model, all of the tables except CUSTOMER.DB are detail tables.

2. In Oracle 8, a nested dataset. That is, a field that consists of an entire table. By extension, a nested dataset in TClientDataSet component.


dispatch

The means of resolving calls to object methods. Dispatching can be either static, virtual, or dynamic.

Do not confuse with TObject::Dispatch which dispatches message procedure calls, not virtuals.


drag

To move an object from one location to another by using your mouse.

To drag an object, click it and continue to hold down the left mouse button while you move the mouse pointer to a new location on your screen. When you are satisfied with the new location, release the mouse button.

Dragging can be part of either a drag-and-drop or a drag-and-dock operation.


dynamic

For Object Pascal only: A form of virtual method which is more space efficient (but less speed efficient) than simple virtual.


dynamic data exchange (DDE)

The process of sending data to and receiving data from other applications through a predefined message protocol. You can use this to exchange data with other applications, or you can control other applications through the use of commands and macros.


dynamic-link library (DLL)

An executable module (extension .DLL) that contains code or resources that can be accessed by other DLLs or applications. In the Windows environment, DLLs permit multiple applications to share code and resources.


embedding

The act of placing one thing within another. In Windows, specifically the capability of one application to provide some or all of the services of another application integrated with its own services. For example, a word processor might allow a spreadsheet to be embedded into a document, allowing the user to write text around the spreadsheet and perhaps even change the spreadsheet while still working in the word processor. See OLE Container.


encapsulate

To provide access to one or more features through an interface that protects clients from relying upon or having to know the inner details of the implementation.


enumerated data type (enum)

enum is a keyword used to define a set of constants of type int, called an enumeration data type. An enumeration data type provides mnemonic identifiers for a set of integer values. An enum is 32 bits wide and must be in the range -2,147,483,648 to -2,147,483,647 and is used for ordered sets of values.


end user

A member of an application's intended audience and, by extension, everyone in that audience. Synonymous with user, but emphasizes the fact that the programmer is not the user.

In C++Builder documentation, end user refers to a user of an application you develop using C++Builder unless otherwise noted.


exception

An event or condition that, if it occurs, breaks the normal flow of execution. Also, an exception is an object that contains information about what error occurred and where it happened.


exception handler

Code designed to resolve the situation in the runtime environment that threw the exception and/or to restore the environment to a stable state afterwards.


execution point

The execution point indicates the next executable line in your source code or machine instruction that will be executed when you run your program through the integrated debugger. The execution point is indicated by the highlighted line of code in the Code editor or address location in the CPU window Disassembly Pane.


expressions

Part of a statement that represents a value or can be used to calculate a value.


event

A user action, such as a button click, or a system occurrence such as a preset time interval, recognized by a component.

Each component has a list of specific events to which it can respond. Code that is executed when a particular event occurs is called an event handler.


event handler

A form method attached to an event. The event handler executes when that particular event occurs.

When you use the Object Inspector to attach code to a component event, C++Builder generates a code block for you. For example, this is the code C++Builder generates for a button click event:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

}

The code you write inside the code block executes whenever Button1 is clicked.


file buffer

An area of memory set aside to expedite the transfer of data to and from a file.


file type

A file type refers to the specific data type that a file holds.


filter

Anything used to check or alter data. For example, the file filter in the Save dialog box can be set to show only .CPP files.


filter program

A program that takes output from another program as input and produces an altered, reduced, or verified version of that output.


focus

The component or window that is active in a running application is said to have "focus." Any keyboard input the user enters is directed to that component or window.


formal parameter

An identifier in a procedure or function declaration heading that represents the arguments that will be passed to the subprogram when it is called.

See parameter name for information on a given parameter.


form

To an end user, a form is merely another window. In C++Builder, a form is a window that receives components (placed by the programmer at design time, or created dynamically with code at runtime), regardless of the intended runtime functionality of the window.

A form is a descendant of TForm.


function

A subroutine that computes and returns a value.


function header

Code that gives the prototype of a routine followed by a list of formal parameters, preceded by the function's return type. The prototype will be found in a header file. The corresponding .c or .cpp file will have the implementation unless the function is inline. If the function is inline, the implementation is in the header.


global heap

Memory available to all applications.

Although global memory blocks of any size can be allocated, the global heap is intended only for large memory blocks (256 bytes or more). Each global memory block carries an overhead of at least 20 bytes, and under the Windows standard and 386 enhanced modes, there is a system-wide limit of 8192 global memory blocks, only some of which are available to any given application.

Note:	C++Builder suballocates small allocations from large global memory blocks to reduce the likelihood of hitting the system limit. (See HeapLimit, HeapBlock.)


global variable

A variable used by a routine (or the main body of a program) that was not declared by that routine is considered a global variable by that code.


globally unique identifier (GUID)

A GUID is a specific type of universally unique identifier (UUID).  It is a 16 byte (128-bit) binary value that is guaranteed to be unique. GUIDs are used to identify COM interfaces.


glyph

A bitmap that displays on a BitBtn or SpeedButton component with the component's Glyph property.


grandchild

A class descended from another through one or more intermediate classes. Example: In the following type definition "class E: public D", E is the child of D. If D is descended from class C, then E is a grandchild of class C, as well as C's parent, C's parent's parent, and so on, until the root class is reached. C and its ancestors are E's grandparents.


grandparent

A class from which others are descended through one or more intermediate classes. See grandchild.


grid

1.	The evenly spaced dots on the form that aid in placing components during design time (not visible at runtime). Control through Tools | Environment Options | Preferences.

2.	An object on a form that enables you to view and edit information in a spreadsheet-like format. You create a grid with a TDBGrid, TStringGrid, or TDrawGrid component.


handling exceptions

Making a specific response to an exception, which then clears the error condition and destroys the exception object.


heap

An area of memory reserved for the dynamic allocation of variables.


heap suballocator

When allocating a memory large block, the heap manager simply allocates a global memory block using the Windows GlobalAlloc routine.

When allocating a small block, the C++Builder heap manager allocates a larger global memory block and then divides (suballocates) that block into smaller blocks as required. Allocations of small blocks reuse all available suballocation space before the heap manager allocates a new global memory block, which, in turn, is further suballocated.


help context

A number assigned individually to the controls and menu items in a program so that when the user activates Help, the Help system can query the focused control and use the help context as a reference to supply information appropriate to what the user is doing.


hint

Pop-up text that appears when the mouse pointer passes over an object in the user interface at runtime. Specified in the Hint property of many visual components.


host type

The particular server being used for a process or series of processes, hence "hosting" the activities.


IDAPI

See BDE.


identifier

A programmer-defined name for a specific item (a constant, type, variable, function, program, or data member).


IDL

Interface definition Language. An interface definition language is a syntax for defining the interfaces of objects or routines that are used in distributed applications. Although the parts of distributed applications may be written in different development languages (such as C++, Java, or Object Pascal), IDL provides a common language that all developers can use to describe the interfaces.

There are three separate dialects of IDL, each of which is specific to a communications protocol:

Microsoft IDL (MIDL), used to describe COM interfaces.

CORBA IDL, used to describe CORBA interfaces.

DCE IDL, used for DCE-based remote procedure calls (such as those supported by Entera).


include file

An include file is a source-code file that is included in a compilation using the "#include" compiler directive.

Include files can have any extension but usually end in ".h" or ".hpp".


index

1.	A position within a list of elements.

2.	In database terminology, a sort order for a table associated with a specific field or fields, used to locate records quickly. An index performs the following tasks:

Determines the location of records.

Keeps records in sorted order.

Speeds up search operations.


index type

Specifies the type of elements in an array.


inheritance

The assumption of the features of one class by another.


instance

A variable of class. More generally, a variable of any type. Actual memory is allocated.


int

A numeric variable type that is a whole number in the range -2,147,483,648 to +2,147,483,647. Used for counting, small numbers, and loop control.


integrated debugger

The integrated debugger is contained within the Integrated Development Environment. This debugger lets you debug your source code without leaving C++Builder. The functionality of this debugger can be reached through the Run and View menus.


interface

1. The set of methods supported by a COM object. Applications obtain an instance of an interface by calling QueryInterface, and use this to interact with the COM object.

2. An abstract class (a class whose methods are all pure virtual) that represents a common set of properties and methods implemented by a server object.


key

A field or group of fields in a table, used to order records. A key has three effects:

The table is prevented from containing duplicate records.

The records are maintained in sorted order based on the key fields.

A primary index is created for the table.


language driver

Determines a table's sort order and available character set. The BDE Administrator enables you to specify the default language driver for tables. Language drivers correspond to locales.


late binding

1. When the addess used to call virtual methods or dynamic methods is determined at runtime.

2. When a method call in a distributed application is resolved at runtime, for example by using QueryInterface (COM) or the dynamic invocation interface (CORBA).


linking

The process of turning compiled source code into an executable file. At the linking stage resources are bound into the executable.


literal value

A value that appears in the actual source code, such as the string "Hello, World" or the numeral 1 (as opposed to a calculated value or a declared constant).


local heap

Memory available only to your application or library. It exists in the upper part of an application's or library's data segment.

It exists in the upper part of an application's or library's data segment.

The total size of local memory blocks that can be allocated on the local heap is 64K minus the size of the application's stack and static data. For this reason, the local heap is best suited for small memory blocks (256 bytes or less). The default size of the local heap is 4K, but you can change this in the application's DEF file.


local symbol information

Information used by the IDE to debug a routine. Local symbol information must be enabled in the Project Options dialog box (Project | Options). Enabled by default in new C++Builder installations.


local variable

A variable declared within a function.


lock

A device that prevents other users from viewing, changing, or locking a table while one user is working with it.


logic error

Logic errors occur when your program statements are valid, but the actions they perform are not the actions you intended. For example, logic errors occur when variables contain incorrect values, when graphic images don’t look right, or when the output of your program is incorrect.


long

A 4-byte integer, able to store integers in the range -2,147,483,648 to +2,147,483,647.


lookup table

A secondary table that enables database systems to use a small code field to enable many records in a primary table to refer to information stored in the lookup table.

This can be used as a means of ensuring that values entered in a primary table are legitimate values, thus safeguarding data integrity.


loop

A statement or group of statements that repeat until a specific condition is met.


main form

At design time, the first form created in or added to a project. The form designated as the main form can be changed in the Project Options dialog box (Project | Options | Forms). The main form is usually the first displayed at runtime, and usually the principal form displayed throughout the execution of the program.


marshaling

The mechanism by which remote method and procedure calls are executed in distributed applications. Marshaling transfers arguments from one process space to another and makes a method or function that is implemented in one process space available in another.


master table

In a multi-table relationship, the primary table of your data model. If you have only one table in your data model, that table is the master table. In a multi-table data model, the master table is the one pointing to other tables. For example, in the following data model, all of the tables except VENDORS.DB are master tables.


method

Member function associated with a particular class.


method identifier

The identifying string or dynamic index of a method.


MIDAS

Multi-tier Distributed Application Services Suite. MIDAS defines a mechanism by which client applications and application servers communicate database information. Data is encoded in special data packets that are passed between the client and server applications.


multiple document interface (MDI) application

An application whose interface consists of a main application window, called the frame window, that can contain multiple child windows, or documents. The child window's document title merges with the parent window's title bar when the child window is maximized.


modal

The runtime state of a form designed as a dialog box which the user must close before continuing with the application. A modal dialog box restricts access to all other areas of the application. See Help for the ShowModal method for more information.


modeless

The runtime state of a form designed as a dialog box in which the user can switch focus away from the dialog box without first closing it. See Help for the Show method for more information.


module

A self-contained routine or group of routines.


NULL

A pointer value referencing nothing. NULL pointers can’t be dereferenced: A pointer must be assigned a memory address in order to be meaningfully and safely used.

Note:	Dereferencing a pointer having a NULL value causes a General Protection Fault exception.


nonvisual component

A component that appears at design time as a small picture on the form, but either has no appearance at runtime until it is called (like TSaveDialog) or simply has no appearance at all at runtime (like TTimer).


nonwindowed control

A nonwindowed control is a control that cannot receive the focus, that cannot be the parent of other controls, and which does not have its own window.


object files (.OBJ)

An intermediate machine-code file that is produced when you compile (or assembler) your source code. The linker combines object files and libraries to produce your final executable application.


object instance variable

The identifier created internally for an instance of an object.


object type

A class.


OLE

Object Linking and Embedding is a method for sharing complex data among applications. With OLE, data from a server application is stored in a container application. The data is stored in an OLE Object.


OLE container

An application that can contain an OLE object. In C++Builder, an OLE container application has a TOLEContainer component.


OLE object

The data shared by an OLE server and OLE container. An OLE object can be linked or embedded in the container application. The data for linked objects are stored in an external file; embedded objects are stored in the container application.

Examples of OLE objects are documents, spreadsheets, pictures, and sounds.


OLE server

An application that can create and edit an OLE object.


ORB

Object Request Broker. The runtime software that handles communication in a CORBA application. Client and server applications communicate by passing messages through the ORB. The ORB is not a single executable, but rather a coordinated set of utilities running on different machines.


override

Redefine a virtual object method in a descendant object type.


owner

An object responsible for freeing the resources used by other (owned) objects.


package

A special dynamic-link library used by C++Builder applications, the IDE, or both. Runtime packages provide functionality when a user runs an application. Design-time packages are used to install components in the IDE and to create special property and component editors for custom components.


parameter

A variable or value that is passed to a function or procedure.


parent

1.	The immediate ancestor of a class, as seen in its declaration. Example: In "class B: public A", class A is the parent of class B.

2.	Parent property: the component that provides the context within which a component is displayed. A parent component is responsible for writing its child component to a stream when forms are saved.


passing by reference

A subroutine parameter that is passed by reference. Changes made to a parameter passed by reference remain in effect after the subroutine has ended. See passing by value.


passing by value

A function parameter that is passed by value; that is, the value of a parameter is copied to the local memory used by the routine and therefore, changes made to that parameter are local. See passing by reference.


pixel

Any of the individual colored dots that make up an image on the screen. Derived from the words "picture element."


pointer

A variable that contains the address of a specific memory location.


power set

The set of all possible subsets of values of a base type, including the empty set.


primary index

An index on the key fields of a table. An index performs the following tasks:

Determines the location of records.

Keeps records in sorted order.

Speeds up search operations.

A primary index typically has a requirement of uniqueness--that is, no duplicate keys can exist.


private

An access specifier. Private members can be used only by member functions and friends of the class in which it is defined.


program

An executable file. Less formally, a program and all the files it needs to run. Contrast with application.


project

The complete catalogue of files and resources used in building an application or DLL. More specifically, the main source code file of the programming effort, which lists the units that the application or DLL depends on.


project directory

The directory in which the project files reside.


project file

The file that contains the source code for a C++Builder project. This file has a .BPR extension. It lists all the header files used by the project and contains the code to launch the application.


project group

A collection of related projects, such as an executable and its associated DLLs or a client application and its associated server application. The project manager organizes projects into project groups.


property

A feature that provides controlled access to methods or data members of a class. A published property may also be stored to a file.


protected

The member can be used only by member functions and friends of the class in which it is declared. Also, the member can be used by member functions and friends of classes derived from the declared class, but only in objects of the derived type.


protected block

A block of code that is enclosed within an exception handling routine.


public

The member can be used by any function.


published

The __published keyword is used to specify the properties that you want to be displayed in the Object Inspector.


qualified identifier

An identifier that contains a qualifier (such as a scope operator). A qualified identifier forces a particular feature (of a class, struct, or namespace) to be used regardless of other features of the same name that may also be visible within the current scope.


qualified method identifier

An object-type identifier, followed by a scope operator (::), followed by a method identifier.


qualifier

An identifier, followed by a scope operator (::), that precedes a method or other identifier to specify a particular symbol reference.


query

A way to retrieve data from your tables. A query can examine the data in a single table or in several tables.


raise

Also known as "throwing" and exception. Raising an exception means constructing an exception object to signal an error or other exception condition. The application then must handle the exception.


real

A number represented by floating-point or scientific notation.


record

In database terminology, a horizontal row in a table that contains a group of related fields of data.


recursion

A programming technique in which a subroutine calls itself. Use care to ensure that a recursion eventually exits. Otherwise, an infinite recursion will cause a stack fault.


relational database

A database management model in which data is stored as rows (records) and columns (fields), and in which the data in one table can access the data in other tables by means of a common data field. The database structure can be used to create one-to-many and many-to-one relationships with data elements.


report

Organized summary or detail information that is presented to the end user either as a printed document or an online display.


root class

A class that itself has no ancestors, and from which all other classes are descended. In C++Builder, the root class is TObject.


routine

A function.


row

The horizontal component of a table, sometimes called a record. A row contains one value for each column in a related group of columns in a table. See also column.


runtime

Period when the application you design is running.


runtime error

An error that occurs when the application runs, as opposed to a compile-time error.


runtime library

The standard procedures and functions available to all C++ programs.


runtime only

Routines, properties, events, or components that can be modified, called, or seen only while your application is running (as opposed to design time).


runtime package

A special dynamic-link library used by C++Builder applications to provide functionality when a user runs an application.


scope

The visibility of an identifier to code within a program.


separator

A blank (space) or a comment. Comments are treated as spaces.


separator bar

A line inserted between menu items. A dash character (-) entered in the Caption property of a new item in the menu designer creates a separator bar at the current position.


service

1. A utility implemented as an NT service application. NT services are accessed via the Service Control Manager and can be started automatically at system boot, through the Services control panel, or from an application through the service API.

2. The use of an HTTP (Web server) application. The service of an application is usually associated with a specific port number so that client applications can initiate the service. Examples of predefined services include ftp, http, finger, and time.


set

A collection of zero or more elementes of a base type. Set classes are implemented using the Set template.


short-circuit evaluation

Strict left-to-right evaluation of a boolean expression where evaluation stops as soon as the result of the entire expression is evident. This model guarantees minimum code execution time, and usually minimum code size.


short int

A 16-bit data type capable of holding any whole number value from -32,768 to +32,767. Used for counting, small numbers, and loop control.


sizing handles

The small black rectangles that appear on the perimeter of a component, form or window when selected. You drag them to resize the object.


skeleton

An automatically generated class in a CORBA server application. The skeleton handles marshaling of incoming method calls. CORBA server applications implement objects that correspond to the automatically generated skeleton classes.

The implementation classes may either be descendants of skeleton classes, or independent classes to which the skeleton classes pass method calls.


source code

The line-by-line statements written by the developer of a computer program using an appropriate editing tool and following the syntax rules for a particular programming language.


splash screen

A form you design to "introduce" your application, and which appears immediately at runtime while the application main form and secondary forms are being loaded in memory, or while a database server connection is being established. See also main form.


SpeedMenu

A local menu on an object which you can access by right-clicking with a pointing device. Also called a context menu.


SQL

Structured Query Language, abbreviated SQL and commonly pronounced "sequel." A relational database language used to define, manipulate, search, and retrieve data in databases.


SQL table

A table on a database server that can be accessed using SQL.


stack

An area of memory reserved for storing local variables. Also keeps track of program execution and subroutine calls.


statement

The simplest unit in a program; statements are separated by semicolons.


static

Resolved at compile time, as are calls to routines and methods.


static method

Static methods provide behavior for a class that is global in nature, or otherwise does not require instance data. A static method is called by using the class name followed by the method (TClass::SomeMethod) and can be called with an instance or without. As such, a static method cannot rely on any properties, fields or instance methods in its executions.


step over

A debugger command that executes a program one line at a time, stepping over procedures while executing them as a single unit. Contrast with trace into.


string

A sequence of characters that can be treated as a single unit of data.


string list

A flexible collection of strings and (potentially) the objects associated with them.


stub

1. Under CORBA, an automatically generated class in the client application. The stub handles marshaling of outgoing method calls, acting as a proxy for the CORBA object on the server application.

2. A routine or method that has not been fully implemented. Stubs serve as placeholders that can be called by application code while it is under development.


symbol

Any identifier. Symbols include keywords.


symbol table

A list of the identifiers used by the debugger to track all variables, constants, types, and function names used in a program. Each executable program and DLL has its own symbol table.

The IDE automatically generates symbolic debug information. To manually choose to turn on debug information for your project, choose Options|Project, click the Compiler tab, and check Debug Information.


table

A structure made up of rows (records) and columns (fields) that contains data.


tag property

A 32-bit value that can be used in every VCL class derived from TComponent or lower.


TDBDataset

A descendant of TDataset that includes the functionality needed to connect to a database, handle passwords, and perform other tasks associated with database connectivity.

You cannot instantiate an object of TDataset directly; you instantiate TTable, TQuery, or another TDataset descendant.


template

A predesigned project or form that serves as a starting point for your application design.

2. A parameterized type.


trace into

A debugger command that executes a program one line at a time, tracing into procedures which were compiled with debug information and following the execution of each line. Contrast with step over.


typecasting

The forcing of the compiler to treat an expression of type X as though it were an expression of type Y.

Normal typecasts are evaluated at compile time and are not validated at runtime. Dynamic casts are evaluated at runtime.


typedef

A description of how data should be stored and accessed. Contrast with variable--the actual storage of the data.


type compatibility

An instance may be used in place of or assigned to another type it is said to be compatible with.

Integer types are all cross-compatible. A descendant class instance is type-compatible with a variable of an ancestor type. Sibling classes are not type-compatible, nor are ancestors type-compatible with their descendants.


type definition

The specification of a non-predefined type. Defines the set of values a variable can have and the operations that can be performed on it.


type library

Files that include information about data types, interfaces, member functions, and object classes exposed by an ActiveX control or server. C++Builder lets you view and edit type libraries using the type library editor.


unit

A independently compileable code module consisting of a header file and a .CPP file.

Every form in C++Builder has an associated unit.

The source code of a unit is stored in a CPP and .H file pair that is maintained by the IDE. A unit is compiled into a binary symbol file with a .OBJ extension. The link process combines .OBJ files into a single .EXE or .DLL file.


untyped file

Low-level I/O (input/output) channels that let you directly access any disk file regardless of its internal format.


unqualified identifier

An identifier with no qualifier. The semantics of an unqualified identifier depend on the current scope. Example: "FlipChildren" is an unqualified identifier that will call any routine called "FlipChildren" within the current scope (or cause a compile error if no such routine is visible) but "TForm::FlipChildren" will call the specific "FlipChildren" method which is a feature of TForm. See qualifier.


use count

An internal variable that Windows uses to determine whether or not a DLL should stay in memory. A DLL stays in memory while its use count is greater than zero.

Windows increments Use Count every time an application loads a DLL and decrements whenever an application frees the DLL.


user-defined

Said of a type that is defined by a programmer and not inherently part of the C++ language. This includes any type definitions you may code or definitions provided by the VCL, or any other source.


variable

An identifier that represents an address in memory, the contents of which can change at runtime.


virtual

Use the virtual keyword to allow derived classes to provide different versions of a base class function. Once you declare a function as virtual, you can redefine it in any derived class, even if the number and type of arguments are the same. The redefined function overrides the base class function.


visual component

A component that is visible, or can be made visible on a form at runtime.


void pointer

A pointer that does not point to any specific type. A void pointer cannot be referenced without a typecast. (Also see typecast.)


warning

A message that appears in the Message window that does not stop your code from compiling, but indicates areas you might want to examine for problems. For example, a warning can alert you to code that

is inefficient

is not portable

violates the proposed ANSI standard


watches

A watch expression lets you track the values of program variables or expressions as you step over or trace into your code. Use the Watch List to view the currently set watches.

As you step through your program, the value of the watch expression will change if your program updates any of the variables contained in the watch expression.


window handle

A number assigned by Windows to a control that must be used to request services for that control from the Windows API.


windowed control

A control that can receive the focus, that can contain other controls, and which has its own window.


wizard

A dialog or set of dialogs that obtain information about an object you want to create and then generate code to implement that object.


word

A location in memory occupying 2 adjacent bytes; the storage required for a variable of type short or word. Also, a predefined data type with a range of 0 to 65535.


wrapper

1. An object, routine, group of objects, or group of routines designed to encapsulate some functionality for the programmer usually for some perceived benefit. VCL is an object-oriented wrapper for the Windows API.

2. In CORBA, an object wrapper is a descendant class of generated stub and skeleton classes that lets you define methods which are called when client applications call methods or server classes receive them. They perform much the same function as interceptors (which are used in remote debugging), except that they are called before operations are marshaled.


z-order

The conceptual distance of an object from the surface of the screen. Whether or not a control is covered by other controls depends on its z-order relative to those controls.


Dockable tool windows

Docking allows you to make full and efficient use of your screen space as you work on your project. From the View menu, you can bring up any tool window and then dock it directly onto the Code editor for use while coding and debugging. You can also dock two or more tool windows together to form tabbed tool windowsto save screen space while retaining fast one-step access to these tools.

Changing the docking state

Most tool windows in the IDE are dockable. You can recognize dockable windows because they have

A thinner title bar than the code editor.

A Dockable property on the context menu. Uncheck this property to turn off the drag-and-dock capability of a tool window.

A drag outline that appears when you move the tool window with the mouse.

Saving the docking state

You can save the state of many dockable windows so that it is used when you start a new application. To save the current docking state

1.	Choose Project | Options to display the project options dialog, and check the Default checkbox. Click OK. This saves the file Default.BPR in your BIN directory.

2.	Choose Tools | Environment Options to display the environment options dialog. On the Preferences page, set Autosave Desktop to ON.

3. Choose Project | Open Project and open DEFAULT.BPR, which was saved to your BIN directory in step 1.

4.	 Configure the docking state the way you want it. This state is saved when you exit and will be used when you start a new project.


Docking tool windows onto the Code editor

See also

If you want to dock one or more tool windows onto the Code editor:

1.	Choose the View menu and the name of the tool you want to dock. For example, if you want to dock the breakpoints tool choose View|Breakpoints.

2.	When the tool window appears onscreen, drag it by clicking on the title bar. When the tool window is over a docking site, its drag outline narrows and changes shape to show how the window would dock.

3.	Release the mouse to dock the tool window.

For example, to dock the Breakpoint List window onto the Code editor, click on the Breakpoint List title bar and drag the rectangle around the Code editor window until the drag outline narrows.

To undock a tool window from the Code editor:

1.	Drag the tool window away from the Code editor by clicking on the title bar. When the tool window is no longer over a docking site, its drag outline widens.

2.	Release the mouse. The tool window becomes a floating window.

For example, to undock the Breakpoint List window from the Code editor, drag the Breakpoint List window away from the Code editor using its title bar. The narrow drag outline widens when you are no longer over a docking.


Docking tool windows together to form tabbed tool windows

See also

If you want to dock two or more tool windows together:

1.	Choose the View menu and the names of the tools you want to dock together. For example, to dock together the Call Stack tool and the Watches tool, choose View|Call Stack then View|Watches.

2.	When the tool windows appear onscreen, drag one tool window by clicking on its title bar and move it onto the other tool window.

3.	When the drag outline narrows, release the mouse. The two windows dock together.

For example, to dock the Call Stack and Watch List windows together, drag the Watch List over the Call Stack window and drop it when the outline narrows.

4.	To view the hidden windows, click the tab with its name on it. For example, to view the Call Stack window, click the Call Stack.

To undock a tool window from the tabbed tools window:

1.	Choose the window you want to undock by clicking its tab. For example, to undock the Watch list window, click the Watch List tab.

2.	Drag the tool window away from tools window until the drag outline widens and then release the mouse. The tool window becomes a floating window.

For example, to undock the Watch List window from the tools window, drag the Watch List window away from the tools window. The narrow drag outline widens when you are no longer over a tools window docking site.


System (Brief)

See also

These system keyboard shortcuts apply to the Brief keystroke mapping scheme.

Shortcut	Action or command

F7	Records a keyboard macro

F8	Plays back a keyboard macro

F9	Run|Run

F10	Accesses the menu bar

F11	View|Object Inspector

F12	View|Toggle Form/Unit

Alt+F2	Zooms window

Alt+F7	Displays previous error in Message view

Alt+F8	Displays next error in Message view

Alt+F9	Displays a context menu

Alt+F10	Project|Make

Alt+F11	File|Include Unit Hdr

Alt+F12	View|Toggle Form/Unit

Ctrl+F1	Topic search

Ctrl+F2	Run|Program Reset

Ctrl+F3	View|Call Stack

Ctrl+F6	Open Source/Header file

Ctrl+F7	Evaluate/modify

Ctrl+F8	Toggle breakpoint

Ctrl+F9	Project|Make

Ctrl+F11	Run|Step over

Ctrl+D	Descends item (replaces Inspector window)

Ctrl+N	Opens a new Inspector window

Ctrl+S	Search| Incremental Search

Ctrl+T	Displays the Type Cast dialog

Shift+F3	View|Call Stack

Shift+F7	Run|Trace To Next Source Line

Shift+F8	Run|Trace Into

Shift+F10	Project|Add To Project

Shift+F11	View|CPU

Ctrl+Hyphen	File|Close

Ctrl+F12	View|Units

Shift+ F12	View|Forms

Alt+B	View|Window list

Alt+E	File|Open(Note: opens Open dialog box, even when Code editor window does not have focus)

Alt+H	Displays context-sensitive Help

Alt+N	Displays the next page

Alt+O	File|Save As(Note: opens Save As dialog box, even when Code editor window does not have focus)

Alt+-	Displays the previous page

Alt+W	File|Save

Alt+X	File|Exit

Alt+Z	Accesses the File menu


Clipboard control (Brief)

See also

These Clipboard keyboard shortcuts apply to the Brief keystroke mapping scheme.

Shortcut	Command

Ins	Edit|Paste

Plus (+)	Edit|Copy

Minus (-)	Edit|Cut


Editor (Brief)

See also

These editor keyboard shortcuts apply to the Brief keystroke mapping scheme.

Shortcut	Action or command

F5	Search|Find (forward from cursor position)

F6	Search|Replace (forward from cursor position)

Alt+F5	Search|Find (backward from cursor position)

Alt+F6	Search|Replace (backward from cursor position)

Alt+F9	Displays the local menu

Shift+F4	Tiles windows horizontally

Shift+F5	Search|Search Again

Shift+F6	Repeats the last Search|Replace operation

Esc	Cancels a command at the prompt

Del	Deletes a character or block at the cursor

*	Edit|Undo

Backspace	Deletes the character to the left of the cursor

Shift+Backspace	Deletes the character to the left of the cursor

Tab	Inserts a tab character

Enter	Inserts a new line with a carriage return

Ctrl+B	Moves to the bottom of the window

Ctrl+C	Centers line in window

Ctrl+D	Moves down one screen

Ctrl+E	Moves up one screen

Ctrl+K	Deletes to the beginning of a line

Ctrl+M	Inserts a new line with a carriage return

Ctrl+S	Performs an incremental search

Ctrl+T	Moves to the top of the window

Ctrl+U	Edit|Redo

Ctrl+Backspace	Deletes the word to the left of the cursor

Ctrl+Enter	Inserts an empty new line

Ctrl+- (dash)	Closes the current page

Alt+A	Marks a non-inclusive block

Alt+B	Displays a list of open files

Alt+C	Mark the beginning of a column block

Alt+D	Deletes a line

Alt+G	Search|Go to line number

Alt+I	Toggles insert mode

Alt+K	Deletes of the end of a line

Alt+L	Marks a line

Alt+M	Marks an inclusive block

Alt+N	Displays the contents of the next page

Alt+P	Prints the selected block

Alt+Q	Causes next character to be interpreted as an ASCII sequence

Alt+R	Reads a block from a file

Alt+S	Search|Find

Alt+T	Search|Replace

Alt+U	Edit|Undo

Alt+Backspace	Deletes the word to the right of the cursor

Alt+Hyphen	Jumps to the previous page

Ctrl+Q+[	Finds the matching delimiter (forward)

Ctrl+Q+Ctrl+[	Finds the matching delimiter (forward)

Ctrl+Q+]	Finds the matching delimiter (backward)

Ctrl+Q+Ctrl+]	Finds the matching delimiter (backward)

Ctrl+O+A  	Open file at cursor

Ctrl+O+O  	Toggles the case of a selection

Ctrl+F1	Help keyword search

Ctrl+F5	Toggles case-sensitive searching

Ctrl+F6	Toggles regular expression searching


Block commands (Brief)

See also

These block command keyboard shortcuts apply to the Brief keystroke mapping scheme.

Shortcut	Action

Alt+A	Marks a non-inclusive block

Alt+C	Marks a column as a block

Alt+L	Marks a line as a block

Alt+M	Marks an inclusive block

Alt+P	Prints the contents of a block

Alt+R	Reads a block from a file


Bookmark operations (Brief)

See also

These bookmark operations keyboard shortcuts apply to the Brief keystroke mapping scheme.

Shortcut	Action

Alt+0	Sets bookmark 0

Alt+1	Sets bookmark 1

Alt+2	Sets bookmark 2

Alt+3	Sets bookmark 3

Alt+4	Sets bookmark 4

Alt+5	Sets bookmark 5

Alt+6	Sets bookmark 6

Alt+7	Sets bookmark 7

Alt+8	Sets bookmark 8

Alt+9	Sets bookmark 9

Alt+J+0	Goes to bookmark 0

Alt+J+1	Goes to bookmark 1

Alt+J+2	Goes to bookmark 2

Alt+J+3	Goes to bookmark 3

Alt+J+4	Goes to bookmark 4

Alt+J+5	Goes to bookmark 5

Alt+J+6	Goes to bookmark 6

Alt+J+7	Goes to bookmark 7

Alt+J+8	Goes to bookmark 8

Alt+J+9	Goes to bookmark 9


Cursor movement (Brief)

See also

These cursor movement keyboard shortcuts apply to the Brief keystroke mapping scheme.

Shortcut	Action

UpArrow	Moves up one line in the same column position

DownArrow	Moves down one line in the same column position

Home	Moves to the start of a line

End	Moves to the end of a line

Left Arrow	Moves one character to the left

Right Arrow	Moves one character to the right

PgDn	Moves down one screen in the current window

PgUp	Moves up one screen in the current window

Ctrl+Left Arrow	Moves one word to the left

Ctrl+Right Arrow	Moves one word to the right

Ctrl+PgDn	Moves to the end of a file

Ctrl+PgUp	Moves to the beginning of a file

Shift+Tab	Moves backward one tab stop

Shift+Home	Moves to the first column in a window

Shift+End	Moves to the last column in a window

Ctrl+Home	Moves to the top of a screen in the same column position

Ctrl+End	Moves to the bottom of a screen in the same column position

Ctrl+B	Moves to the bottom of the window

Ctrl+C	Moves to the center of the window

Ctrl+D	Scrolls down one screen

Ctrl+E	Scrolls down one screen


System (classic)

See also

These system keyboard shortcuts apply to the Classic keystroke mapping scheme.

Shortcut	Action or command

F1	Displays context-sensitive Help

F2	File|Save

F3	File|Open

F4	Run to Cursor

F5	Zooms window

F6	Displays the next page

F7	Run|Trace Into

F8	Run|Step Over

F9	Run|Run

F11	View|Object Inspector

F12	View|Toggle Form/Unit

Alt+F2	View|CPU

Alt+F3	File|Close

Alt+F7	Displays previous error in Message view

Alt+F8	Displays next error in Message view

Alt+F10	Displays a context menu

Alt+F11	File|Include Unit Hdr

Alt+F12	Displays the Code editor

Alt+X 	File|Exit

Alt+0 	View|Window List

Ctrl+F1	Topic Search

Ctrl+F2	Run|Program Reset

Ctrl+F3	View|Call Stack

Ctrl+F4	Evaluate/Modify

Ctrl+F6	Open Source/Header file

Ctrl+F7	Add Watch at Cursor

Ctrl+F8	Toggle Breakpoint

Ctrl+F9	Project|Make project

Ctrl+F11	File|Open Project

Ctrl+F12	View|Units

Shift+F7	Run|Trace To Next Source Line

Shift+F11	Project|Add To Project

Shift+F12	View|Forms

Ctrl+D	Descends item (replaces Inspector window)

Ctrl+N	Opens a new Inspector window

Ctrl+S	Incremental search

Ctrl+T	Displays the Type Cast dialog

Ctrl+Shift+P	Plays back a keyboard macro

Ctrl+Shift+R	Records a keyboard macro

Ctrl+Shift+S	Performs an incremental search

Ctrl+K+D	Accesses the menu bar

Ctrl+K+S	File|Save


Clipboard control (classic)

See also

These Clipboard control keyboard shortcuts apply to the Classic keystroke mapping scheme.

Shortcut	Command

Ctrl+Ins	Edit|Copy

Shift+Del	Edit|Cut

Shift+Ins	Edit|Paste

Plus (+)	Edit|Copy

Minus (-)	Edit|Cut

Start (*)	Edit|Paste


Editor (classic)

See also

These editor keyboard shortcuts apply to the Classic keystroke mapping scheme.

Shortcut	Action or command

F1	Topic Search

Ctrl+F1	Topic Search

F6	Displays the next page

Shift+F6	Displays the previous page

Ctrl+A	Moves one word left

Ctrl+C	Scrolls down one screen

Ctrl+D	Moves the cursor right one column, accounting for the autoindent setting

Ctrl+E	Moves the cursor up one line

Ctrl+F	Moves one word right

Ctrl+G	Deletes the character to the right of the cursor

Ctrl+H	Deletes the character to the left of the cursor

Ctrl+I	Inserts a tab

Ctrl+L	Search|Search Again

Ctrl+N	Inserts a new line

Ctrl+P	Causes next character to be interpreted as an ASCII sequence

Ctrl+R	Moves up one screen

Ctrl+S	Moves the cursor left one column, accounting for the autoindent setting

Ctrl+T	Deletes a word

Ctrl+V	Turns insert mode on/off

Ctrl+W	Moves down one screen

Ctrl+X	Moves the cursor down one line

Ctrl+Y	Deletes a line

Ctrl+Z	Moves the cursor up one line

Ctrl+Shift+S	Performs an incremental search

End 	Moves to the end of a line

Home	Moves to the start of a line

Enter	Inserts a carriage return

Ins 	Turns insert mode on/off

Del 	Deletes the character to the right of the cursor

Backspace	Deletes the character to the left of the cursor

Tab 	Inserts a tab

Space	Inserts a blank space

Left Arrow	Moves the cursor left one column, accounting for the autoindent setting

Right Arrow	Moves the cursor right one column, accounting for the autoindent setting

Up Arrow	Moves up one line

Down Arrow	Moves down one line

Page Up	Moves up one page

Page Down	Moves down one page

Ctrl+Left Arrow	Moves one word left

Ctrl+Right Arrow	Moves one word right

Ctrl+Home	Moves to the top of a screen

Ctrl+End 	Moves to the end of a screen

Ctrl+PgDn	Moves to the bottom of a file

Ctrl+PgUp	Moves to the top of a file

Ctrl+Backspace	Move one word to the right

Ctrl+Del 	Deletes a currently selected block

Ctrl+Space	Inserts a blank space

Ctrl+Enter	Opens file at cursor

Ctrl+Tab	Moves to the next page

Shift+Tab 	Deletes the character to the left of the cursor

Shift+Backspace	Deletes the character to the left of the cursor

Shift+Left Arrow	Selects the character to the left of the cursor

Shift+Right Arrow	Selects the character to the right of the cursor

Shift+Up Arrow	Moves the cursor up one line and selects from the left of the starting cursor position

Shift+Down Arrow	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+PgUp	Moves the cursor up one screen and selects from the left of the starting cursor position

Shift+PgDn	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+End 	Selects from the cursor position to the end of the current line

Shift+Home	Selects from the cursor position to the start of the current line

Shift+Space	Inserts a blank space

Shift+Enter	Inserts a new line with a carriage return

Shift+Ctrl+Tab	Moves to the previous page

Ctrl+Shift+Left Arrow	Selects the word to the left of the cursor

Ctrl+Shift+Right Arrow	Selects the word to the right of the cursor

Ctrl+Shift+Home	Selects from the cursor position to the start of the current file

Ctrl+Shift+End 	Selects from the cursor position to the end of the current file

Ctrl+Shift+PgDn	Selects from the cursor position to the bottom of the screen

Ctrl+Shift+PgUp	Selects from the cursor position to the top of the screen

Ctrl+Shift+Tab	Moves to the previous page

Alt+Backspace	Edit|Undo

Alt+Shift+Backspace	Edit|Redo

Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Alt+Shift+Right Arrow	Selects the column to the right of the cursor

Alt+Shift+Up Arrow	Moves the cursor up one line and selects the column from the left of the starting cursor position

Alt+Shift+Down Arrow	Moves the cursor down one line and selects the column from the left of the starting cursor position

Alt+Shift+Page Up	Moves the cursor up one screen and selects the column from the left of the starting cursor position

Alt+Shift+Page Down	Moves the cursor down one line and selects the column from the right of the starting cursor position

Alt+Shift+End	Selects the column from the cursor position to the end of the current line

Alt+Shift+Home	Selects the column from the cursor position to the start of the current line

Ctrl+Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Ctrl+Alt+Shift+Rght Arrow	Selects the column to the right of the cursor

Ctrl+Alt+Shift+Home	Selects the column from the cursor position to the start of the current file

Ctrl+Alt+Shift+End	Selects the column from the cursor position to the end of the current file

Ctrl+Alt+Shift+Page Up	Selects the column from the cursor position to the bottom of the screen

Ctrl+Alt+Shift+Page Down	Selects the column from the cursor position to the top of the screen


System (default)

See also

These system keyboard shortcuts apply to the Default keystroke mapping scheme.

Shortcut	Action or command

F1	Displays context-sensitive Help

F4	Run|Go to Cursor

F5	Run|Toggle Breakpoint

Ctrl+F6	Open Source/Header file

F7	Run|Trace Into

F8	Run|Step Over

F9	Run|Run

F11	View|Object Inspector

F12	View|Toggle Form/Unit

Alt+0	View|Window List

Alt+F2	View|Debug Windows|CPU

Alt+F7	Displays previous error in Message view

Alt+F8	Displays next error in Message view

Alt+F10	Displays a context menu

Alt+F11	File|Include Unit Hdr

Alt+F12	Displays the Code editor

Ctrl+F1	Help|Topic Search

Ctrl+F2	Run|Program Reset

Ctrl+F3	View|Debug Windows|Call Stack

Ctrl+F4	Closes current file

Ctrl+F5	Add Watch at Cursor

Ctrl+F6	Displays header file in Code editor

Ctrl+F7	Evaluate/Modify

Ctrl+F9	Project|Make project

Ctrl+F11	File|Open Project

Ctrl+F12	View|Units

Ctrl+D	Descends item (replaces Inspector window)

Ctrl+E	View|ClassExplorer

Ctrl+N	Opens a new Inspector window

Ctrl+S	Incremental search

Ctrl+T	Displays the Type Cast dialog

Shift+F7	Run|Trace To Next Source Line

Shift+F11	Project|Add To Project

Shift+F12	View|Forms

Ctrl+Shift+P	Plays back a key macro

Ctrl+Shift+R	Records a key macro

Ctrl+K+D	Accesses the menu bar

Ctrl+K+S	File|Save


Clipboard control (default)

See also

These Clipboard keyboard shortcuts apply to the Default keystroke mapping scheme.

Shortcut	Command

Ctrl+Ins	Edit|Copy

Shift+Del	Edit|Cut

Shift+Ins	Edit|Paste

Ctrl+C	Edit|Copy

Ctrl+V	Edit|Paste

Ctrl+X	Edit|Cut


Editor (default)

See also

These editor keyboard shortcuts apply to the Default keystroke mapping scheme.

Shortcut	Action or command

F1	Help|Topic Search

Ctrl+F1	Help|Topic Search

F3	Search|Search Again

Ctrl+E	Search|Incremental Search

Ctrl+F	Search|Find

Ctrl+I	Inserts a tab character

Ctrl+j	Templates pop-up menu

Ctrl+N	Inserts a new line

Ctrl+P	Causes next character to be interpreted as an ASCII sequence

Ctrl+R 	Search|Replace

Ctrl+S	File|Save

Ctrl+T	Deletes a word

Ctrl+Y	Deletes a line

Ctrl+Z	Edit|Undo

Ctrl+<space bar>	Code Completion pop-up window

Ctrl+Shift+I	Indents block

Ctrl+Shift+U	Outdents block

Ctrl+Shift+Y	Deletes to the end of a line

Ctrl+Shift+Z	Edit|Redo

Ctrl+Shift+<space bar>	Code Parameters pop-up window

Alt+[	Finds the matching delimiter (forward)

Alt+]	Finds the matching delimiter (backward)

End 	Moves to the end of a line

Home	Moves to the start of a line

Enter	Inserts a carriage return

Ins 	Turns insert mode on/off

Del 	Deletes the character to the right of the cursor

Backspace	Deletes the character to the left of the cursor

Tab 	Inserts a tab

Space	Inserts a blank space

Left Arrow	Moves the cursor left one column, accounting for the autoindent setting

Right Arrow	Moves the cursor right one column, accounting for the autoindent setting

Up Arrow	Moves up one line

Down Arrow	Moves down one line

Page Up	Moves up one page

Page Down	Moves down one page

Ctrl+Left Arrow	Moves one word left

Ctrl+Right Arrow	Moves one word right

Ctrl+Tab 	Moves to the next code page (or file)

Ctrl+Shift+Tab	Moves to the previous code page (or file)

Ctrl+Backspace	Deletes the word to the right of the cursor

Ctrl+Home	Moves to the top of a file

Ctrl+End 	Moves to the end of a file

Ctrl+Del 	Deletes a currently selected block

Ctrl+Space	Inserts a blank space

Ctrl+PgDn	Moves to the bottom of a screen

Ctrl+PgUp	Moves to the top of a screen

Ctrl+Up Arrow	Scrolls up one line

Ctrl+Down Arrow	Scrolls down one line

Ctrl+Enter	Opens file at cursor

Shift+Tab 	Moves the cursor to the left one tab position

Shift+Backspace	Deletes the character to the left of the cursor

Shift+Left Arrow	Selects the character to the left of the cursor

Shift+Right Arrow	Selects the character to the right of the cursor

Shift+Up Arrow	Moves the cursor up one line and selects from the left of the starting cursor position

Shift+Down Arrow	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+PgUp	Moves the cursor up one screen and selects from the left of the starting cursor position

Shift+PgDn	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+End 	Selects from the cursor position to the end of the current line

Shift+Home	Selects from the cursor position to the start of the current line

Shift+Space	Inserts a blank space

Shift+Enter	Inserts a new line with a carriage return

Ctrl+Shift+Left Arrow	Selects the word to the left of the cursor

Ctrl+Shift+Right Arrow	Selects the word to the right of the cursor

Ctrl+Shift+Home	Selects from the cursor position to the start of the current file

Ctrl+Shift+End 	Selects from the cursor position to the end of the current file

Ctrl+Shift+PgDn	Selects from the cursor position to the bottom of the screen

Ctrl+Shift+PgUp	Selects from the cursor position to the top of the screen

Ctrl+Shift+Tab	Moves to the previous page

Alt+Backspace	Edit|Undo

Alt+Shift+Backspace	Edit|Redo

Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Alt+Shift+Right Arrow	Selects the column to the right of the cursor

Alt+Shift+Up Arrow	Moves the cursor up one line and selects the column from the left of the starting cursor position

Alt+Shift+Down Arrow	Moves the cursor down one line and selects the column from the left of the starting cursor position

Alt+Shift+Page Up	Moves the cursor up one screen and selects the column from the left of the starting cursor position

Alt+Shift+Page Down	Moves the cursor down one line and selects the column from the right of the starting cursor position

Alt+Shift+End	Selects the column from the cursor position to the end of the current line

Alt+Shift+Home	Selects the column from the cursor position to the start of the current line

Ctrl+Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Ctrl+Alt+Shift+Right Arrow	Selects the column to the right of the cursor

Ctrl+Alt+Shift+Home	Selects the column from the cursor position to the start of the current file

Ctrl+Alt+Shift+End	Selects the column from the cursor position to the end of the current file

Ctrl+Alt+Shift+Page Up	Selects the column from the cursor position to the bottom of the screen

Ctrl+Alt+Shift+Page Down	Selects the column from the cursor position to the top of the screen


System (Epsilon)

See also

These system keyboard shortcuts apply to the Epsilon keystroke mapping scheme.

Shortcut	Action or command

F1	Displays context-sensitive Help

F5	Toggle Breakpoint

F7	Run|Trace Into

F8	Run|Step Over

F9	Run|Run

F10	Edit|Redo

F11	View|Object Inspector

F12	View|Toggle Form/Unit

Alt+0	View|Window List

Alt+F3	View|CPU

Alt+F7	Displays previous error in Message view

Alt+F8	Displays next error in Message view

Alt+F9	Project|Make project

Alt+F10	Displays a context menu

Alt+F11	File|Include Unit Hdr

Alt+F12	Displays the Code editor

Ctrl+F2	Run|Program Reset

Ctrl+F5	Run|Add Watch

Ctrl+F6	Displays the next page

Ctrl+Shift+F6	Displays the previous page

Ctrl+F7	File|Save As

Ctrl+F9	Project|Make project

Ctrl+F12	View|Units

Ctrl+D	Descends item (replaces Inspector window)

Ctrl+N	Opens a new Inspector window

Ctrl+S	Incremental search

Ctrl+T	Displays the Type Cast dialog

Shift+F3	View|Call Stack

Shift+F6	Displays header file in Code editor

Shift+F7	Run|Trace To Next Source Line

Shift+F11	Project|Add To Project

Shift+F12	View|Forms

Ctrl+X+(	Records a keyboard macro

Ctrl+X+)	Ends a keyboard macro recording

Ctrl+X+e	Plays back the last keyboard macro recorded

Ctrl+X+E	Plays back the last keyboard macro recorded

Ctrl+X+b	Displays a list of open files

Ctrl+X+B	Displays a list of open files

Ctrl+X+s	File|Save As

Ctrl+X+S	File|Save As

Ctrl+X+Ctrl+F	File|Open

Ctrl+X+Ctrl+S	File|Save

Ctrl+X+Ctrl+W	File|Save


Clipboard control (Epsilon)

See also

These Clipboard keyboard shortcuts apply to the Epsilon keystroke mapping scheme.

Shortcut	Action or command

Ctrl+Y	Edit|Paste

Alt+w	Edit|Copy

Esc+w	Edit|Copy

Ctrl+Alt+w	Edit|Copy (appends to current contents)

Esc+Ctrl+w	Edit|Copy (appends to current contents)


Editor (Epsilon)

See also

These editor keyboard shortcuts apply to the Epsilon keystroke mapping scheme.

Shortcut	Action or command

Ctrl+H	Deletes the character to the left of the current cursor position

Backspace	Deletes the character to the left of the current cursor position

Alt+Del	Deletes all text in the block between the cursor and the previous matching delimiter (cursor must be on ')', '}' or ']')

Esc+Del	Deletes all text in the block between the cursor and the previous matching delimiter (cursor must be on ')', '}' or ']')

Ctrl+Alt+H	Deletes the word to the left of the current cursor position

Alt+Backspace	Deletes the word to the left of the current cursor position

Esc+BackSpace	Deletes the word to the left of the current cursor position

Esc+Ctrl+H	Deletes the word to the left of the current cursor position

Ctrl+D	Deletes the currently selected character or character to the right of the cursor

Del	Deletes the currently selected character or character to the right of the cursor

Alt+\	Deletes spaces and tabs around the cursor on the same line

Esc+\	Deletes spaces and tabs around the cursor on the same line

Ctrl+Alt+K	Deletes all text in the block between the cursor and the next matching delimiter (cursor must be on ')', '}' or ']')

Esc+Ctrl+K	Deletes all text in the block between the cursor and the next matching delimiter (cursor must be on ')', '}' or ']')

Ctrl+X+0	Deletes the contents of the current window

Alt+d	Deletes to word to the right of the cursor

Esc+@d	Deletes to word to the right of the cursor

Ctrl+K	Cuts the contents of line and places it in the Clipboard

Ctrl+Alt+B	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Esc+Ctrl+B	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Alt+)	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Esc+)	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Alt+Shift+O	Locates the next matching delimiter (cursor must be on ')', '}' or ']')

Ctrl+Alt+F	Locates the previous matching delimiter (cursor must be on ')', '}' or ']')

Esc+Ctrl+F	Locates the previous matching delimiter (cursor must be on ')', '}' or ']')

Alt+c	Capitalizes the first letter of the current word

Esc+@c	Capitalizes the first letter of the current word

Ctrl+L	Centers the active window

Ctrl+M	Inserts a carriage return

Ctrl+X+i	Inserts the contents of a file at the cursor

Ctrl+X+I	Inserts the contents of a file at the cursor

Ctrl+O	Inserts a new line after the cursor

Alt+x	Invokes the specified command or macro

Esc+@x	Invokes the specified command or macro

F2	Invokes the specified command or macro

Ctrl+X+Ctrl+X	Exchanges the locations of the cursor position and a bookmark

Ctrl+Shift+-	Displays context-sensitive Help

Alt+Shift+/	Displays context-sensitive Help

Alt+?	Displays context-sensitive Help

Esc+?	Displays context-sensitive Help

Ctrl+_	Displays context-sensitive Help

Tab	Inserts a tab

Alt+Tab	Indents to the current line to the text on the previous line

Esc+Tab	Indents to the current line to the text on the previous line

Alt+l	Converts the current word to lowercase

Esc+@l	Converts the current word to lowercase

Ctrl+X+m	Project|Make project

Ctrl+X+M	Project|Make project

Esc+End	Displays the next window in the buffer list

Ctrl+X+n	Displays the next window in the buffer list

Ctrl+X+N	Displays the next window in the buffer list

Esc+Home	Displays the previous window in the buffer list

Ctrl+X+p	Displays the previous window in the buffer list

Ctrl+X+P	Displays the previous window in the buffer list

Ctrl+X+Ctrl+E	Invoke a command processor

Ctrl+Q	Interpret next character as an ASCII code

Ctrl+X+r	Edit|Redo

Ctrl+X+R	Edit|Redo

F10	Edit|Redo

Ctrl+F10	Edit|Redo

Ctrl+X+Ctrl+R	Edit|Redo

Ctrl+X+u	Edit|Undo

Ctrl+X+U	Edit|Undo

F9	Edit|Undo

Ctrl+F9	Edit|Undo

Ctrl+X+Ctrl+U	Edit|Undo

Ctrl+S	Incrementally searches for a string entered from the keyboard

Ctrl+R	Incrementally searches backward through the current file

Ctrl+Alt+S	Search|Find (using regular expressions)

Esc+Ctrl+S	Search|Find (using regular expressions)

Ctrl+Alt+R	Search|Find (using regular expressions; backward from cursor)

Esc+Ctrl+R	Search|Find (using regular expressions; backward from cursor)

Alt+Shift+5	Search|Replace

Alt+Shift+7	Search|Replace

Alt+&	Search|Replace

Esc+&	Search|Replace

Alt+%	Search|Replace

Esc+%	Search|Replace

Alt+*	Search|Replace (using regular expressions)

Esc+*	Search|Replace (using regular expressions)

Ctrl+X+g	Search|Go To Line Number

Ctrl+X+G	Search|Go To Line Number

Crl+T	Transposes the two characters on either side of the cursor

Ctrl+X+Ctrl+T	Transposes the two lines on either side of the cursor

Alt+t	Transposes the two words on either side of the cursor

Esc+t	Transposes the two words on either side of the cursor

Esc+T	Transposes the two words on either side of the cursor

Alt+U	Converts a word to all uppercase

Esc+U	Converts a word to all uppercase

Esc+@u	Converts a word to all uppercase

Ins	Toggles insert mode on/off


Block commands (Epsilon)

See also

These block command keyboard shortcuts apply to the Epsilon keystroke mapping scheme.

Shortcut	Action

Ctrl+Alt+\	Indents a block

Esc+Ctrl+\	Indents a block

Ctrl+X+Ctrl+I	Indents a block

Ctrl+X+Tab	Indents a block

Ctrl+W	Cuts a block and places its contents in the Clipboard

Ctrl+X+w	Writes a block to a file

Ctrl+X+W	Writes a block to a file


Bookmark operations (Epsilon)

See also

These bookmark operations keyboard shortcuts apply to the Epsilon keystroke mapping scheme.

Shortcut	Action

Ctrl+@	Sets a bookmark at the current cursor position

Alt+@	Sets a bookmark at the current cursor position

Esc+@@	Sets a bookmark at the current cursor position

Ctrl+2	Sets a bookmark at the current cursor position

Alt+2	Sets a bookmark at the current cursor position

Ctrl+X, Ctrl+X	Toggles between bookmark and current position


Cursor movement (Epsilon)

See also

These cursor movement keyboard shortcuts apply to the Epsilon keystroke mapping scheme.

Shortcut	Action

Ctrl+B	Moves to the left one character

Left Arrow	Moves to the left one character

Ctrl+F	Moves to the right one character

RightArrow	Moves to the right one character

Alt+m	Moves the cursor to the end of the indentation

Esc+m	Moves the cursor to the end of the indentation

Esc+M	Moves the cursor to the end of the indentation

Alt+b	Moves the cursor to the left one word

Esc+@b	Moves the cursor to the left one word

Ctrl+LeftArrow	Moves the cursor to the left one word

Alt+f	Moves to the cursor to the right one word

Esc+@f	Moves to the cursor to the right one word

Ctrl+RightArrow	Moves to the cursor to the right one word

Ctrl+A	Moves to the beginning of the current line

Esc+LeftArrow	Moves to the beginning of the current line

Ctrl+E	Moves to the end of the current line

Esc+RightArrow	Moves to the end of the current line

Alt-,	Moves to the top of the current window

Esc+,	Moves to the top of the current window

Home	Moves to the top of the current window

Alt-.	Moves to the bottom of the current window

Esc+.	Moves to the bottom of the current window

End	Moves to the bottom of the current window

Ctrl+P	Moves the cursor up a line

UpArrow	Moves the cursor up a line

Ctrl+N	Moves the cursor down a line

DownArrow	Moves the cursor down a line

Alt+Shift-,	Goes to the start of the file

Alt+<	Goes to the start of the file

Esc+<	Goes to the start of the file

Ctrl+Home	Goes to the start of the file

Alt+Shift-.	Goes to the end of the file

Alt+>	Goes to the end of the file

Esc+>	Goes to the end of the file

Ctrl+End	Goes to the end of the file

Ctrl+V	Moves down one page in the current file

PgDn	Moves down one page in the current file

Ctrl+F6	Moves down one page in the current file

Shift+Ctrl+F6	Moves up one page in the current file

Alt+v	Moves up one page in the current file

Esc+@v	Moves up one page in the current file

PgUp	Moves up one page in the current file

Alt+Z	Scrolls the contents of the active window down a line

Esc+Z	Scrolls the contents of the active window down a line

Ctrl+Z	Scrolls the contents of the active window up a line


System (Visual Studio)

See also

These system keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Action or command

Ctrl+R	Records a keyboard macro

Ctrl+P	Plays back a keyboard macro

F1	Displays context-sensitive Help

F4	Run|Go to Cursor

F5	Run|Run

F7	Project|Build project

F9	Toggle breakpoint

F10	Run|Step over

F11	Run|Trace Into

F12	View|Toggle Form/Unit

Alt+0	View|Window list

Alt+3	View|Debug Windows|Watches

Alt+4	View|Debug Windows|Local Variables

Alt+7	View|Debug Windows|Call Stack

Alt+8	View|Debug Windows|CPU

Alt+F2	View|Debug Windows|CPU

Alt+F5	Run|Inspect

Alt+F7	Project|Options

Alt+F10	Displays a context menu

Alt+F11	File|Include Unit Hdr

Alt+F12	View|Toggle Form/Unit

Alt+Enter	View|Object Inspector

Shift+F5	Run|Program Reset

Shift+F7	Run|Trace To Next Source Line

Shift+F9	Run|Add Watch

Shift+ F11	Project|Add To Project

Shift+ F12	View|Forms

Ctrl+F1	Topic search

Ctrl+F2	Evaluate/modify

Ctrl+F3	View|Debug Windows|Call Stack

Ctrl+F6	Open Source/Header file

Ctrl+F7	Project|Make

Ctrl+F10	Run|Go to Cursor

Ctrl+F12	View|Units

Ctrl+a	Edit|Select All

Ctrl+B	View|Breakpoints

Ctrl+E	View|ClassExplorer

Ctrl+n	File|New

Ctrl+N	File|New Application

Ctrl+o	File|Open

Ctrl+O	File|Open Project

Ctrl+s	File|Save

Ctrl+S	File|Save All

Ctrl+<space bar>	Code Completion pop-up window

Ctrl+Shift+<space bar>	Code Completion pop-up window

Ctrl+Tab	Displays the next page

Ctrl+Shift+Tab	Displays the previous page

Ctrl+Q+W	Displays next error in Message view

Ctrl+Alt+E	View|Debug Windows|Event Log

Ctrl+Alt+M	View|Debug Windows|Modules


Clipboard control (Visual Studio)

See also

These Clipboard keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Command

Ctrl+Ins	Edit|Copy

Shift+Del	Edit|Cut

Shift+Ins	Edit|Paste

Ctrl+C	Edit|Copy

Ctrl+V	Edit|Paste

Ctrl+X	Edit|Cut


Editor (Visual Studio)

See also

These editor keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Action or command

F3	Search|Search Again

Ctrl+F	Search|Find

Ctrl+g	Search|Go to line number

Ctrl+G	Open file at cursor

Ctrl+h	Search|Replace

Ctrl+I	Search|Incremental Search

Ctrl+j	Templates pop-up menu

Ctrl+L	Deletes a line

Ctrl+P	Causes next character to be interpreted as an ASCII sequence

Ctrl+s	File|Save

Ctrl+T	Deletes the word to the left of the cursor

Ctrl+y	Deletes a line

Ctrl+Y	Deletes to the end of a line

Ctrl+z	Edit|Undo

Ctrl+Z	Edit|Redo

Ctrl+Tab	Displays the next window in the buffer list

Ctrl+Shift+Tab	Displays the previous window in the buffer list

Ctrl+F4	Closes the current page

Ctrl+K+E	Converts the word under the cursor to lower case

Ctrl+K+F	Converts the word under the cursor to upper case

Ctrl+Q+A	Search|Replace

Ctrl+Q+F	Search|Find

Ctrl+Q+Y	Deletes to the end of a line

Ctrl+Q+[	Finds the matching delimiter (forward)

Ctrl+Q+Ctrl+[	Finds the matching delimiter (forward)

Ctrl+Q+]	Finds the matching delimiter (backward)

Ctrl+Q+Ctrl+]	Finds the matching delimiter (backward)

Alt+F3	Search|Find

Alt+[	Finds the matching delimiter (forward)

Alt+]	Finds the matching delimiter (backward)

Delete	Deletes a character or block at the cursor

Backspace	Deletes the character to the left of the cursor

Shift+Backspace	Deletes the character to the left of the cursor

Ctrl+Backspace	Deletes the word to the left of the cursor

Tab	Inserts a tab character

Enter	Inserts a new line character

Insert	Toggles insert mode

Shift+Left Arrow	Selects the character to the left of the cursor

Shift+Right Arrow	Selects the character to the right of the cursor

Shift+Up Arrow	Moves the cursor up one line and selects from the left of the starting cursor position

Shift+Down Arrow	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+PgUp	Moves the cursor up one screen and selects from the left of the starting cursor position

Shift+PgDn	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+End 	Selects from the cursor position to the end of the current line

Shift+Home	Selects from the cursor position to the start of the current line

Shift+Space	Inserts a blank space

Shift+Enter	Inserts a new line character

Ctrl+Shift+Left Arrow	Selects the word to the left of the cursor

Ctrl+Shift+Right Arrow	Selects the word to the right of the cursor

Ctrl+Shift+Home	Selects from the cursor position to the start of the current file

Ctrl+Shift+End 	Selects from the cursor position to the end of the current file

Ctrl+Shift+PgDn	Selects from the cursor position to the bottom of the screen

Ctrl+Shift+PgUp	Selects from the cursor position to the top of the screen

Alt+Backspace	Edit|Undo

Alt+Shift+Backspace	Edit|Redo

Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Alt+Shift+Right Arrow	Selects the column to the right of the cursor

Alt+Shift+Up Arrow	Moves the cursor up one line and selects the column from the left of the starting cursor position

Alt+Shift+Down Arrow	Moves the cursor down one line and selects the column from the left of the starting cursor position

Alt+Shift+Page Up	Moves the cursor up one screen and selects the column from the left of the starting cursor position

Alt+Shift+Page Down	Moves the cursor down one line and selects the column from the right of the starting cursor position

Alt+Shift+End	Selects the column from the cursor position to the end of the current line

Alt+Shift+Home	Selects the column from the cursor position to the start of the current line

Ctrl+Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Ctrl+Alt+Shift+Right Arrow	Selects the column to the right of the cursor

Ctrl+Alt+Shift+Home	Selects the column from the cursor position to the start of the current file

Ctrl+Alt+Shift+End	Selects the column from the cursor position to the end of the current file

Ctrl+Alt+Shift+Page Up	Selects the column from the cursor position to the bottom of the screen

Ctrl+Alt+Shift+Page Down	Selects the column from the cursor position to the top of the screen


Block commands (Visual Studio)

See also

These block command keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Action or command

Ctrl+K+B	Marks the beginning of a block

Ctrl+K+C	Copies a selected block

Ctrl+K+H	Hides/shows a selected block

Ctrl+K+I	Indents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box

Ctrl+K+K	Marks the end of a block

Ctrl+K+L	Marks the current line as a block

Ctrl+K+N	Changes a block to uppercase

Ctrl+K+O	Changes a block to lowercase

Ctrl+K+P	Prints selected block

Ctrl+K+R	Reads a block from a file

Ctrl+K+T	Marks a word as a block

Ctrl+K+U	Outdents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box.

Ctrl+K+V	Moves a selected block

Ctrl+K+W	Writes a selected block to a file

Ctrl+K+Y	Deletes a selected block

Ctrl+I	Indents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box

Ctrl+U	Outdents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box.

Ctrl+Del	Deletes a selected block

Ctrl+Q+B	Moves to the beginning of a block

Ctrl+Q+K	Moves to the end of a block


Cursor movement (Visual Studio)

See also

These cursor movement shortcuts apply to the Visual Studio keystroke mappings scheme.

Shortcut	Action

UpArrow	Moves up one line in the same column position

DownArrow	Moves down one line in the same column position

Home	Moves to the start of a line

End	Moves to the end of a line

Left Arrow	Moves one character to the left

Right Arrow	Moves one character to the right

PgDn	Moves down one screen in the current window

PgUp	Moves up one screen in the current window

Shift+Tab 	Moves the cursor to the left one tab position

Ctrl+Left Arrow	Moves one word to the left

Ctrl+Right Arrow	Moves one word to the right

Ctrl+PgDn	Moves to the bottom of the screen

Ctrl+PgUp	Moves to the top of the screen

Ctrl+UpArrow	Scrolls the screen up one line.

Ctrl+DownArrow	Scrolls the screen down one line.

Ctrl+Home	Moves to the top of a file

Ctrl+End 	Moves to the end of a file

Ctrl+Q+B	Moves to the beginning of a block

Ctrl+Q+C	Moves to end of a file

Ctrl+Q+D	Moves to the end of a line

Ctrl+Q+E	Moves to the top of the window

Ctrl+Q+K	Moves to the end of a block

Ctrl+Q+P	Moves to previous position

Ctrl+Q+R	Moves to the beginning of a file

Ctrl+Q+S	Moves to the beginning of a line

Ctrl+Q+T	Moves to the top of the window

Ctrl+Q+U	Moves to the bottom of the window

Ctrl+Q+X	Moves to the bottom of the window


About keyboard shortcuts

See also

Keyboard shortcuts are two- or three-keystroke combinations you can press, while in the Code editor, to perform a command or access a dialog box. The function of specific keyboard shortcuts depends on which keystroke mapping scheme you select.

Code editor available keyboard mapping schemes are:

Default	Key bindings that match the CUA standard

Classic	Key bindings that match the C++ programming environment

Brief	Key bindings that emulate most of the standard Brief keystrokes

Epsilon	Key bindings that emulate a large part of the Epsilon editor

Visual Studio	Key bindings that emulate a large part of the Visual Studio editor

To select a keymapping:

1.	Choose the Editor display page of the Environment Options dialog box.

2.	Select a keyboard mapping scheme from the list of available schemes.

3.	Click OK.

To use SpeedSettings to set your keymappings:

1.	Choose the Editor options page of the Environment Options dialog box.

2.	Select a keyboard mapping scheme from the Editor SpeedSettings options.

3.	Click OK.

Note:	Using the Keystroke Mapping list box or the Editor SpeedSettings to change the mapping of your keystrokes can create conflicts with standard Windows keyboard commands.

For example, the Brief keystroke mapping defines Alt+E as File|Open, while the standard Windows action for Alt+E is to activate the Edit menu. The mapped key takes precedence so that Alt+E allows you to open a file.


Default keystroke mapping

The Default keystroke mapping scheme provides key bindings that match the CUA standard. For detailed information, choose one of the topics below for a list of keyboard shortcuts:

Clipboard control

Debugger

Editor

Block commands

Bookmark operations

Cursor movement

Miscellaneous commands

System


Classic keystroke mapping

The Classic keystroke mapping scheme provides key bindings that match the C++Builder programming environment. For detailed information, choose one of the topics below for a list of keyboard shortcuts:

Clipboard control

Debugger

Editor

Block commands

Bookmark operations

Cursor movement

Miscellaneous commands

System


Brief keystroke mapping

The Brief keystroke mapping scheme provides key bindings that emulate the Brief editor. For detailed information, choose one of the topics below for a list of keyboard shortcuts:

Clipboard control

Debugger

Editor

Block commands

Bookmark operations

Cursor movement

System


Epsilon keystroke mapping

The Epsilon keystroke mapping scheme provides key bindings that emulate most of the Epsilon editor. For detailed information, choose one of the topics below for a list of keyboard shortcuts:

Clipboard control

Debugger

Editor

Block commands

Bookmark operations

Cursor movement

System


Visual Studio keystroke mapping

The Visual Studio keystroke mapping scheme provides key bindings that emulate most of the Visual Studio editor. For detailed information, choose one of the topics below for a list of keyboard shortcuts:

Clipboard control

Debugger

Editor

Block commands

Bookmark operations

Cursor movement

System


Debugger (default, classic, Brief, Epsilon, and Visual Studio)

See also

The Debugger keyboard shortcuts apply to all keystroke mapping schemes:

Default

Classic

Brief

Epsilon

Breakpoint view

Ctrl+V	View Source

Ctrl+S	Edit Source

Ctrl+E 	Edit Breakpoint

Enter	Edit Breakpoint

Ctrl+D	Delete Breakpoint

Del	Delete Breakpoint

Ctrl+A 	Add Breakpoint

Ins	Add Breakpoint

Ctrl+N	Enable Breakpoint

Call stack view

Ctrl+V	View Source

Ctrl+S	Edit Source

Space	View Source (Epsilon only)

Ctrl+Enter	Edit Source (Epsilon only)

Message view

Ctrl+V	View Source

Space	View Source

Ctrl+S 	Edit Source

Ctrl+Enter	Edit Source

Watch view

Ctrl+E	Edit Watch

Enter	Edit Watch

Ctrl+A 	Add Watch

Ins	Add Watch

Ctrl+D	Delete Watch

Del	Delete Watch


Block commands (default and classic)

See also

These block command shortcuts apply to the Default and Classic keystroke mappings schemes.

Shortcut	Action or command

Ctrl+K+B	Marks the beginning of a block

Ctrl+K+C	Copies a selected block

Ctrl+K+H	Hides/shows a selected block

Ctrl+K+I	Indents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box

Ctrl+K+K	Marks the end of a block

Ctrl+K+L	Marks the current line as a block

Ctrl+K+N	Changes a block to uppercase

Ctrl+K+O	Changes a block to lowercase

Ctrl+K+P	Prints selected block

Ctrl+K+R	Reads a block from a file

Ctrl+K+T	Marks a word as a block

Ctrl+K+U	Outdents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box.

Ctrl+K+V	Moves a selected block

Ctrl+K+W	Writes a selected block to a file

Ctrl+K+Y	Deletes a selected block

Ctrl+O+C	Marks a column block

Ctrl+O+I	Marks an inclusive block

Ctrl+O+K	Marks a non-inclusive block

Ctrl+O+L	Marks a line as a block

Ctrl+Q+B	Moves to the beginning of a block

Ctrl+Q+K	Moves to the end of a block


Bookmark operations (default, classic, and Visual Studio)

See also

The following bookmark operations shortcuts apply to the Default, Classic, and Visual Studio keystroke mappings schemes.

Shortcut	Action

Ctrl+K+0 	Sets bookmark 0

Ctrl+K+1 	Sets bookmark 1

Ctrl+K+2 	Sets bookmark 2

Ctrl+K+3 	Sets bookmark 3

Ctrl+K+4 	Sets bookmark 4

Ctrl+K+5 	Sets bookmark 5

Ctrl+K+6 	Sets bookmark 6

Ctrl+K+7 	Sets bookmark 7

Ctrl+K+8 	Sets bookmark 8

Ctrl+K+9 	Sets bookmark 9

Ctrl+K+Ctrl+0	Sets bookmark 0

Ctrl+K+Ctrl+1	Sets bookmark 1

Ctrl+K+Ctrl+2	Sets bookmark 2

Ctrl+K+Ctrl+3	Sets bookmark 3

Ctrl+K+Ctrl+4	Sets bookmark 4

Ctrl+K+Ctrl+5	Sets bookmark 5

Ctrl+K+Ctrl+6	Sets bookmark 6

Ctrl+K+Ctrl+7	Sets bookmark 7

Ctrl+K+Ctrl+8	Sets bookmark 8

Ctrl+K+Ctrl+9	Sets bookmark 9

Ctrl+Q+0 	Goes to bookmark 0

Ctrl+Q+1 	Goes to bookmark 1

Ctrl+Q+2 	Goes to bookmark 2

Ctrl+Q+3 	Goes to bookmark 3

Ctrl+Q+4 	Goes to bookmark 4

Ctrl+Q+5 	Goes to bookmark 5

Ctrl+Q+6 	Goes to bookmark 6

Ctrl+Q+7 	Goes to bookmark 7

Ctrl+Q+8 	Goes to bookmark 8

Ctrl+Q+9 	Goes to bookmark 9

Ctrl+Q+Ctrl+0	Goes to bookmark 0

Ctrl+Q+Ctrl+1	Goes to bookmark 1

Ctrl+Q+Ctrl+2	Goes to bookmark 2

Ctrl+Q+Ctrl+3	Goes to bookmark 3

Ctrl+Q+Ctrl+4	Goes to bookmark 4

Ctrl+Q+Ctrl+5	Goes to bookmark 5

Ctrl+Q+Ctrl+6	Goes to bookmark 6

Ctrl+Q+Ctrl+7	Goes to bookmark 7

Ctrl+Q+Ctrl+8	Goes to bookmark 8

Ctrl+Q+Ctrl+9	Goes to bookmark 9

These shortcuts apply only to the Default and Visual Studio schemes:

Shortcut	Action

Shift+Ctrl+0	Sets bookmark 0

Shift+Ctrl+1	Sets bookmark 1

Shift+Ctrl+2	Sets bookmark 2

Shift+Ctrl+3	Sets bookmark 3

Shift+Ctrl+4	Sets bookmark 4

Shift+Ctrl+5	Sets bookmark 5

Shift+Ctrl+6	Sets bookmark 6

Shift+Ctrl+7	Sets bookmark 7

Shift+Ctrl+8	Sets bookmark 8

Shift+Ctrl+9	Sets bookmark 9

Ctrl+0	Goes to bookmark 0

Ctrl+1	Goes to bookmark 1

Ctrl+2	Goes to bookmark 2

Ctrl+3	Goes to bookmark 3

Ctrl+4	Goes to bookmark 4

Ctrl+5	Goes to bookmark 5

Ctrl+6	Goes to bookmark 6

Ctrl+7	Goes to bookmark 7

Ctrl+8	Goes to bookmark 8

Ctrl+9	Goes to bookmark 9


Cursor movement (default and classic)

See also

These cursor movement shortcuts apply to the Default and Classic keystroke mappings schemes.

Shortcut	Action

Ctrl+Q+B	Moves to the beginning of a block

Ctrl+Q+C	Moves to end of a file

Ctrl+Q+D	Moves to the end of a line

Ctrl+Q+E	Moves to the top of the window

Ctrl+Q+K	Moves to the end of a block

Ctrl+Q+P	Moves to previous position

Ctrl+Q+R	Moves to the beginning of a file

Ctrl+Q+S	Moves to the beginning of a line

Ctrl+Q+T	Moves to the top of the window

Ctrl+Q+U	Moves to the bottom of the window

Ctrl+Q+X	Moves to the bottom of the window


Miscellaneous commands (default and classic)

See also

These miscellaneous commands shortcuts apply to the Default and the Classic keystroke mapping schemes.

Shortcut	Action or command

Ctrl+K+D	Accesses the menu bar

Ctrl+K+E	Changes a word to lowercase

Ctrl+K+F	Changes a word to uppercase

Ctrl+K+S	File|Save (default and classic only)

Ctrl+Q+A	Search|Replace

Ctrl+Q+F	Search|Find

Ctrl+Q+Y	Deletes to the end of a line

Ctrl+Q+[ 	Finds the matching delimiter (forward)

Ctrl+Q+Ctrl+[	Finds the matching delimiter (forward)

Ctrl+Q+] 	Finds the matching delimiter (backward)

Ctrl+Q+Ctrl+]	Finds the matching delimiter (backward)

Ctrl+O+A  	Open file at cursor

Ctrl+O+G  	Search|Go to line number

Ctrl+O+O  	Inserts compiler options and directives

Ctrl+O+U	Toggles case


Keyboard shortcuts by function

See also

Chose one of these topics for shortcuts for some common menu commands. The shortcuts are different for each keystroke mapping scheme.

Build commands

Debug commands

Edit commands

File commands

Search commands


Keyboard shortcuts for the File menu

See also

The table below lists keyboard shortcuts for file commands.

Command	Shortcut	Mapping

File|New	Ctrl+n	Visual Studio

File|New Application	Ctrl+N	Visual Studio

File|Open	F3	Classic

Alt+E 	Brief

Ctrl+X+Ctrl+F	Epsilon

Ctrl+o	Visual Studio

File|Open Project	Ctrl+O	Visual Studio

Open File At Cursor	Ctrl+O+A	Default, Classic, Brief

Ctrl+G	Visual Studio

File|Save	Ctrl+K+S	Default, Classic

Ctrl+S	Default

Ctrl+s	Visual Studio

F2	Classic

Alt+W	Brief

Ctrl+X+Ctrl+S	Epsilon

Ctrl+X+Ctrl+W	Epsilon

File|Save As	Alt+O 	Brief

Ctrl+F7	Epsilon

Ctrl+X+s	Epsilon

Ctrl+X+S	Epsilon

File|Save All	Ctrl+S 	Visual Studio

File|Close	Alt+F3	Classic

Ctrl+Hyphen	Brief

Close Active Window	Alt+F4	Default, Classic, Brief, Epsilon

File|Close	Alt+F3	Classic

Ctrl+Hyphen	Brief

File|Include Unit Hdr	Alt+F11	Default, Classic, Epsilon, Brief, Visual Studio

File menu	Alt+Z	Brief

For more information about C++Builder's keystroke mapping schemes, choose one of the following topics:

Default keystroke mapping

Classic keystroke mapping

Brief keystroke mapping

Epsilon keystroke mapping

Visual Studio keystroke mapping


Keyboard shortcuts for the Edit menu

See also

The table below lists the keyboard shortcuts for commands on the Edit menu.

Command	Shortcut	Mapping

Edit|Cut	Shift+Del	Default, Classic, Visual Studio

Ctrl+X	Default, Visual Studio

Minus (-)	Brief

Edit|Copy	Ctrl+Ins	Default, Classic, Visual Studio

Ctrl+C	Default, Visual Studio

Plus (+)	Brief

Alt+w	Epsilon

Esc+@w	Epsilon

Ctrl+Alt+w	Epsilon

Esc+Ctrl+w	Epsilon

Edit|Paste	Shift+Ins	Default, Classic, Visual Studio

Ctrl+V	Default, Visual Studio

Ins	Brief

Ctrl+Y	Epsilon

Edit|Delete	Ctrl+Del	Default, Classic, Visual Studio

Edit|Redo	Ctrl+Shift+Z	Default, Visual Studio

Alt+Shift+Backspace	Default, Classic, Visual Studio

Ctrl+U	Brief

Ctrl+X+r	Epsilon

Ctrl+X+R	Epsilon

F10	Epsilon

Ctrl+F10	Epsilon

Ctrl+X+Ctrl+R	Epsilon

Edit|Undo	Alt+Backspace	Default, Classic, Visual Studio

Ctrl+Z	Visual Studio

Star	Brief

Alt+U	Brief

Ctrl+X+u	Epsilon

Ctrl+X+U	Epsilon

F9	Epsilon

Ctrl+F9	Epsilon

Ctrl+X+Ctrl+U	Epsilon

Edit|Select All	Ctrl+A	Visual Studio

For more information about C++Builder's keystroke mapping schemes, choose one of the following topics:

Default Keystroke Mapping

Classic Keystroke Mapping

Brief Keystroke Mapping

Epsilon Keystroke Mapping

Visual Studio keystroke mapping


Search commands keyboard shortcuts

See also

The table below lists the keyboard shortcuts for commands on the Search menu.

Command	Shortcut	Mapping

Find	Ctrl+Q+F	Default, Classic

Ctrl+F	Default, Visual Studio

F5	Brief

Alt+F5	Brief

Alt+S	Brief

Ctrl+Alt+S	Epsilon

Esc+Ctrl+S	Epsilon

Ctrl+Alt+R	Epsilon

Esc+Ctrl+R	Epsilon

Alt+F3	Visual Studio

Replace	Ctrl+Q+A	Default, Classic

Ctrl+R 	Default

Ctrl+H 	Visual Studio

Alt+T	Brief

F6	Brief

Alt+F6	Brief

Alt+&	Epsilon

Esc+&	Epsilon

Alt+%	Epsilon

Esc+%	Epsilon

Alt+*	Epsilon

Esc+*	Epsilon

Search Again	F3	Default, Visual Studio

Ctrl+L	Classic

Shift+F5	Brief

Incremental Search	Ctrl+I	Visual Studio

Go To Line Number	Ctrl+O+G	Default, Classic, Brief

Alt+G	Brief

Ctrl+X+g	Epsilon

Ctrl+X+G	Epsilon

Ctrl+g	Visual Studio

For more information about C++Builder's keystroke mapping schemes, choose one of the following topics:

Default Keystroke Mapping

Classic Keystroke Mapping

Brief Keystroke Mapping

Epsilon Keystroke Mapping

Visual Studio keystroke mapping


Debug commands keyboard shortcuts

See also

The table below lists the keyboard shortcuts for debug operations.

Command	Shortcut	Mapping

Run|Run	F9	Default, Classic, Brief, Epsilon

F5	Visual Studio

Run|Go to Cursor	F4	Default, Classic, Visual Studio

Ctrl+F10	Visual Studio

Alt+F7	Brief

Run|Add Breakpoint	F5	Default

Run|Trace Into	F7	Default, Classic

F11	Visual Studio

Run|Step Over	F8	Default, Classic, Epsilon

F10	Visual Studio

Run|Program Reset	Ctrl+F2	Default, Classic, Brief, Epsilon

Shift+F5	Visual Studio

Run|Add Watch	Ctrl+F5	Epsilon

Shift+F9	Visual Studio

Add Watch at Cursor	Ctrl+F5	Default

Ctrl+F7	Classic

Alt+F2	Brief

Evaluate/Modify	Ctrl+F7	Default, Brief

Ctrl+F4	Classic

Ctrl+F2	Visual Studio

Toggle Breakpoint	Ctrl+F8	Classic, Brief

F5	Epsilon

F9	Visual Studio

Inspect	Alt+F5	Visual Studio

For more information about C++Builder's keystroke mapping schemes, choose one of the following topics:

Default Keystroke Mapping

Classic Keystroke Mapping

Brief Keystroke Mapping

Epsilon Keystroke Mapping

Visual Studio keystroke mapping


Build commands keyboard shortcuts

See also

This table lists the keyboard shortcuts for build operations:

Command	Shortcut	Mapping

Project|Make project	Ctrl+F9	Default, Classic, Brief

Alt+F9	Default, Classic, Epsilon

Alt+F10	Brief

Ctrl+X+m	Epsilon

Ctrl+X+M	Epsilon

Ctrl+F7	Visual Studio

Project|Build project	F7	Visual Studio

For more information about C++Builder's keystroke mapping schemes, choose one of the following topics:

Default Keystroke Mapping

Classic Keystroke Mapping

Brief Keystroke Mapping

Epsilon Keystroke Mapping

Visual Studio keystroke mapping


Keyboard support in the IDE

See also

IDE keyboard shortcuts are two- or three-keystroke combinations you can press to perform a command or access a dialog box directly without having to open any menu. To learn about shortcuts in the Code editor, see Keyboard shortcuts.

To learn about shortcuts in the other windows, select one of the topics listed below:

Form keyboard shortcuts

Project Manager keyboard shortcuts

Object Inspector keyboard shortcuts

Package editor keyboard shortcuts

CPU window keyboard shortcuts


Form keyboard shortcuts

See also

Listed below are keyboard shortcuts for working with forms.

The IDE supports the movement and resizing of components on a form using the keyboard. The following table shows the keystrokes for selection and move and resize operations. Remember that you must select a component in order to move or resize it.

Keyboard command	Description

Tab	Selects the next component

Shift+Tab	Selects the previous component

Arrow Keys	Selects the nearest component in the direction pressed

Ctrl+Arrow Keys	Moves the selected component one pixel at a time

Shift+Arrow Keys	Moves the selected component one pixel at a time

Ctrl+Shift+Arrow Keys	Moves the selected component one grid at a time (when Snap to Grid is enabled)

Del	Deletes the selected component

Esc	Selects the containing group (usually the form or group box)

F11	Toggles control between the Object Inspector and the last active form or unit

F12	Toggles between the form and its associated unit

Ctrl+F12	Displays the View Unit dialog box

Shift+F12	Displays the View Form dialog box

To add components to a form using the keyboard,

1.	Press Alt+V+L to display the Component List dialog box

2.	Type the first letter of the name of the component you want to place on the form or press Tab. Then you can use the arrow keys to scroll through the list and make a selection.

3.	Press Alt+A or Enter to add the component to the form. Pressing Enter will close the Component List dialog box.

Keys to navigate in the component list

Home	Displays the first component in the list

End	Displays the last component in the list

To change properties of a component using the keyboard,

1.	Select the component you want to modify using Tab or the arrow keys.

2.	Press Enter to switch to the Object Inspector.

3.	Use the arrow keys to select the property you want to change.

4.	Type the new value for that property and press Enter.

5.	To return to the form, press Alt+V+F and select it from the list.


Project Manager keyboard shortcuts

See also

Listed below are keyboard shortcuts for working with the Project Manager.

Keyboard command	Description

Arrow Keys	Selects forms and units

Alt+A	Adds a form or unit to the project

Alt+R	Removes a form or unit from the project

Alt+U	Views the selected unit

Alt+F	Views the selected form

Alt+O	Displays the Project Options dialog box

Alt+D	Updates the current project

Enter	Views the selected unit

Shift+Enter	Views the selected form

Ins	Adds a file to the project

Del	Removes a file from the project


Object Inspector keyboard shortcuts

See also

Listed below are keyboard shortcuts for working with the Object Inspector.

Keyboard command	Description

Ctrl+I	Opens the Object Selector

Up and Down Arrow Keys	Selects properties or event handlers

Left and Right Arrow Keys	Edits the value in the value or event column

Tab	Toggles between the property and value columns in the Object Inspector

Tab+<letter>	Jumps directly to the first property beginning with the letter

Ctrl+Tab	Toggles between the properties and events tabs in the Object Inspector

Page Up	Moves up one screen of properties

Page Down	Moves down one screen of properties

Alt+F10	Toggles expand and contract

Alt+Down	Opens a drop-down list for a property.

Ctrl+Down	Opens the object list drop-down.

Ctrl+Enter	Selects the ellipsis button (if available) in a selected property.

To change properties of a component using the keyboard,

1.	Select the component you want to modify using Tab or the arrow keys.

2.	Press Enter to switch to the Object Inspector.

3.	Use the arrow keys to select the property you want to change.

4.	Type the new value for that property and press Enter.

5.	To return to the form, press Alt+V+F and select it from the list.


Package editor keyboard shortcuts

See also

Listed below are keyboard shortcuts for working in the package editor.

Keyboard command	Description

Enter	Lets you view the selected unit’s source code.

Ins	Adds a unit to the current folder (Contains or Requires).

Del	Removes the selected item from the package.

Ctrl+B	Compiles the current package. If changes to the package are required, a dialog box appears that lists the changes that will be made to the package before it is compiled.

Ctrl+I	Installs the current package as a design time package. If changes to the package are required, a dialog box appears that lists the changes that will be made to the package before it is compiled.


CPU Window keyboard shortcuts

See also

Listed below are keyboard shortcuts for navigating in the CPU window.

Keyboard command	Description

Shift+Left Arrow	Move left one pane.

Shift+Right Arrow	Move right one pane

Shift+Up Arrow	Move up one pane.

Shift+Down Arrow	Move down one pane.


Working with projects

See also

When you're working in C++Builder, you're working on a project. These topics describe the files that make up a project and then provide information on working with projects. The topics covered here include

What is a project?

Creating a project

C++Builder file types

Viewing a project's contents

Saving projects and individual project files

Managing projects

Sharing objects

Creating a project group

Specifying a default project, new form, and main form

Managing multiple project versions and team development

Compiling, building, and running projects


What is a project?

See also

A project is a collection of all the files that together make up a C++Builder application or dynamic-link library. Some of these files are generated as you work on a project at design time. Others are created when you compile the project source code.

You can combine projects that work together into a single project group. Project groups allow you to organize and work on interdependent projects such as separate tiers in a multi-tiered application or DLLs and executables that work together.

You can view the files that make up a project in the Project Manager (see Viewing a project’s contents). To manage projects effectively, you need to understand the various files and file types that make up a C++Builder project (see C++Builder file types). In most cases, you won't need to deal with the individual files unless you want to. Although you can edit many of these files directly as source code or scripts, it's easier and more reliable to use the visual tools in C++Builder.

A project typically contains source files and binary object files. As your application grows, it will include more and more intermediate files as its complexity increases. A Windows program can be composed of resource scripts, import libraries, object libraries, and source code, with each file type requiring a special setup to be compiled and linked into the final executable image. Although C++Builder takes care of the complexities of creating Windows applications, understanding the files that make up your C++Builder projects helps you better understand the applications you create.

Single project files, which describe individual projects, have a .BPR extension. Project files (or makefiles) contain the directions on how to build the project. When you add and remove files from a project using the Project Manager, C++Builder updates the project make file (.BPR). The project group file contains make commands to build the projects in the project group, has a .BPG extension. Any time you add a project to the project group, a reference to that project is added to the .BPG file. You can specify the .BPG file on the command line for MAKE, making it easier to compile your projects in batch mode.


Creating a project

See also

To create and name a new project:

1.	Choose File|New to display the New Items dialog.

2.	Select the type of project you want to create and click OK.

To add a project to the current project group:

1.	Choose Project|Add New Project to display the New Items dialog.

2.	Select the type of project you want to create* and click OK.

3.	Choose View|Project Manager to display the Project Manager, if it is not yet displayed.

The new project appears in the Project Manager. Expand the project to see all the files created.

4.	Select the project, right-click, and choose Save to supply a new name to the project.

C++Builder gives all three project files the same project name.

Following are the target types of projects you can create in C++Builder:

Extension	Target Description

EXE	Any type of application such as Windows, console, or service applications.

DLL	Dynamic link library, a collection of routines that can be called by applications and other DLLs. DLLs contain sharable code or resources.

Use File|New|DLL to create a VCL DLL

Use File|New|Console wizard to create a non-VCL DLL

OCX	ActiveX control, a component that integrates into and extends the functionality of any host application that supports ActiveX controls, such as C++Builder, Delphi, Visual dBASE, Visual Basic, Internet Explorer, and Netscape Navigator.

BAT	Batch file.

LIB	Static library that can be linked into your applications.


C++Builder project files
C++Builder file types

See also

To manage projects effectively, familiarize yourself with the different file types that can make up a C++Builder project. By default, C++Builder generates several sets of files with each new project you create. Project files can be organized into the file groups shown in the following table.

File group	Files types in group	Description
Project files	.bpr, .bpg, .cpp, and .res files	Files that contain information about building the project  .bpr  contains the instructions for building the project (a makefile containing flags and settings).  .bpg  contains instructions for building all the projects contained in a project group.  project.cpp contains the WinMain() function; it is the entry point to your program execution.  project.res  is the Windows resource file for the application.
Form files	.cpp, .h, and .dfm files	For each form you create in C++Builder, C++Builder generates a .cpp file to specify event handlers, its associated header file, and a .dfm file that defines the graphical components.
Package files	.bpl, .bpi, and .bpk files	If you choose, you can use packages, which are special DLLs, in your project. When you rebuild any project that contains a package, the package is automatically recompiled, if necessary. .bpl a C++Builder package library. .bpi a C++Builder package.  .bpk package make files (default.bpk contains default project values).
Unit files	.cpp and .h files	C++Builder refers to the separate modules you create for organizing your application into logical, sharable units as unit files.
Desktop file	.dsk file	A .dsk file stores information about the state of your desktop. (Choose Tools|Environment Options and check Desktop under Autosave options.)
Library files	.lib	Static or import libraries included in a project. (You can also create a static library as the target type of a project. This type of project also has a .lib extension.)
Type library files	.tlb files	A type library file contains type information for a COM server. For details, see Working with type libraries.
IDL files	.idl files	CORBA IDL files. CORBA object interfaces are defined using the CORBA Interface Definition Language (IDL). IDL files define objects that can be shared. Refer to Defining object interfaces for details.
In C++Builder, you don't need to deal directly with most of the files in your project; C++Builder generates and maintains many of the files for you. Although you can edit most files directly in the C++Builder Code editor, it's usually easier and more reliable to edit these files using the visual editors and tools integrated with C++Builder.


Project files

See also

When you create a new project, C++Builder automatically creates the following three files:

Project1.CPP

Project1.BPR

Project1.RES

These files are called project files because their names are derived from the name you give your project. When you name the project .BPR file, C++Builder updates the three files, giving them all the same file name.

C++Builder creates the project files automatically when you create and name a new project.


Project1.CPP

See also

The project’s .CPP file is the main area for each project's source code. When you create a new project, C++Builder names this file Project1.CPP by default.

This file contains the entry point for your executable image, the WinMain() function for applications. This is where the resulting program begins execution. In addition, the project .CPP file coordinates the other forms and units contained in your application.

Although a very simple project could contain nothing besides the project1.CPP file, a C++Builder project usually contains references to the forms and units that it uses. When you load, save, or compile a project, C++Builder knows which other files to act on by looking at the project .CPP file.

Anytime you add new forms or units to a project, C++Builder updates the .CPP file as well as the project (.BPR) file.


Project1.BPR

See also

Project1.BPR is the project file, which is a text file that contains the project option settings and the build rules for the project. C++Builder uses this file to determine how the different source files and target file are combined to make your final executable images.

This .BPR file is similar to .MAK files in that it contains build rules for the project; however, C++Builder supports only a subset of the standard MAKE utility and it requires some rules specific to the C++Builder environment. That is why C++Builder uses the .BPR extension. (Previous versions of C++Builder named this file with the .MAK extension.)

For most projects, you can let C++Builder generate and maintain this file. To view the project makefile, choose View|Project Makefile. For more information on setting advanced project options, see project option settings.


Project1.RES

See also

C++Builder uses standard Windows-format resource files to include items such as the application icon in a project. You can edit the project resource file with a resource editor to add other resources, such as bitmaps, cursors, icons, or strings to the application.

By default, each C++Builder application you create has a resource file with the same name as the project file, but with the extension .RES. This file contains a binary image of the program icon.


Form files

See also

For each form that you create in C++Builder, C++Builder generates three files, assigning the following names by default:

Unit1.DFM

Unit1.CPP

Unit1.h

When you first save a new form, C++Builder prompts you to enter a name for the form .CPP file. C++Builder uses the file name you supply to name all three form files.


Unit1.DFM

See also

The .DFM file is the programmatic representation of the graphical user interface components of your application. It contains the instructions of how to actually draw your form -- such as where to locate each component, and what colors and fonts to use.

C++Builder takes the burden away from you having to specify the form programmatically, you simply create the form by selecting components from C++Builder’s Component palette, and customizing the components to suit your needs by setting properties and events with the Object Inspector.

When you create a form, C++Builder stores the image of the form in this binary file with the file extension of .DFM. You can convert this binary file to text, if desired.

To view .DFM files as text in the Code editor,

1.	Select the form.

2.	Right-click and choose View As Text.

To return the .DFM file to binary form, follow the above steps and choose View As Form.

At the command line, you can convert all your .DFM files to text or binary form by using the CONVERT.EXE utility. This makes it easy for you to translate your form files to text versions for maintenance and version control.

Tip:	You may want to archive your forms as text as they are less susceptible to data corruption.


Unit1.CPP and Unit1.h

See also

For each form you create, C++Builder generates a C++ source file and an associated header file. A form .CPP file contains the event handlers that you write to handle the events of the components you place on the associated formit is within the form .CPP files that you do most of your C++Builder programming.

A .CPP file that is associated with a form is sometimes called the form unit or simply a unit.

The .H file contains the include files required for that form.

The Project Manager displays the .CPP file.

To view the header file from the Project Manager:

1.	Select the form’s .CPP file (Unit1.CPP), right-click, and choose Open.

The .CPP file appears in the Code editor.

2.	In the Code editor, right-click and choose Open Source/Header File.

To return to the source file, follow the above steps.


Unit files

See also

You can also create unit files that are not associated with forms, to divide your application in modules for housing global functions, classes, constants, data types, etc., as well as functions that you plan to share across projects.

Unit files are not associated with a form; they are simply a pair of .CPP and .h files.

See About form and unit files and Unit files for forms for more information on these file types.


Unit files for forms

See also

Whenever you create a new form, C++Builder creates the following default form unit code:

//------------------------------------------------------------

#include <vcl.h>

#pragma hdrstop

#include "Unit1.h"

//-------------------------------------------------------------

#pragma package(smart_init)

#pragma resource "*.dfm"

TForm1 *Form1;

//-------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

}

//--------------------------------------------------------------

The statement TForm1 *Form1; creates the Form1 object from the TForm1 class. To this form unit file, you add event handlers and support code for each component event that you need to handle for this particular application form.


Package files

See also

C++Builder packages are specially compiled dynamic-link libraries. You can create runtime packages to allow code sharing among applications. You can create design-time packages to easily manipulate components in the IDE. You use design-time packages to create special property editors for custom components.

Packages have file extensions of .BPL and package make files have the extension .BPK. When you rebuild any project that contains a package, the package is implicitly recompiled, if necessary.

The file default.bpk contains default project values and is saved in the ..\BIN directory when you click OK on the Package Project Options page with the "Default" checkbox checked. All subsequent new Package projects will pick up the settings saved in default.bpk. Deleting this file returns new package projects to default settings.

Packages are described in detail in About packages.


Desktop file

See also

C++Builder can generate a desktop file that maintains the state of your desktop, such as which windows are open and in what positions. This allows you to restore your project’s workspace whenever you reopen the C++Builder project.

The desktop-settings file has the same name as the project file, but with the extension .DSK.

To generate and automatically save a desktop file:

1.	Choose Tools|Environment Options…

2.	On the Preferences page, look for Autosave options, and check the Desktop box.

C++Builder generates and saves a project .DSK file whenever you close the project. The file is stored in your main project directory.

When you create a desktop file for your projects, C++Builder opens the project with the same window setup that you had when you last closed the project.


About form and unit files

See also

C++Builder supports separately compiled modules of code called units. Using units promotes structured, reusable code across projects. The most common units in C++Builder projects are form units, which contain the event handlers and other code for each form you create in your C++Builder projects.

Form unit files are the building blocks of the graphical elements of your C++Builder applications; they contain the C++ source code (and binary representation) of all your application forms and all the functions that are called through your program event handlers. For every form you create, C++Builder generates a .CPP source code file, its associated .h header file, and the binary representation of the form in a .DFM file.

You can create unit files initially as part of a project, but this is not required. You can also create and save units and form units as standalone files that any project can use. Standalone unit files can contain any kind of C or C++ code you want to write, such as global functions and functions that you want to share across forms. For example, you can write your own functions, .DLLs, and components, and put their source code in a separate unit file that has no associated form. Or you can create a form as standalone units and share them across projects.

When you compile a unit, the C++Builder compiler produces a binary object file with the same file name as the unit source file, but with an .OBJ file extension. You do not need to open these binary files, and you do not need to distribute them with your completed application.


Resource files

See also

C++Builder uses standard Windows-format resource files to include items such as the application icon in a project. You can edit these resource files (or create your own with a resource editor) to add other resources, such as bitmaps, cursors, icons, or strings to the application.

By default, each C++Builder project that compiles into an application has a resource file with the same name as the project file, but with the extension .RES.


Other files

See also

C++Builder generates other files in conjunction with maintaining and compiling your project, most of which you never need to consider.These include the following:

File Extension	Description

~??	Indicates most recent backup of the default Project Options file. So, for example, if you save a DEFAULT.BPR and want to return to your most recent default state, copy DEFAULT.~BP to DEFAULT.BPR.

#nn	Precompiled header external type OBJs (command-line option -He, which is ON by default when -H is ON ). If you don't specify your own precompiled header, the default is used ( ..\LIB\VCL40.#nn ). (You can delete these to be sure that the compiler regenerates these files.)

DEFAULT.BPR	Default Project Options file. Created the first time you go to the Options dialog with a package project open and click OK with the default checkbox  clicked ON. Deleting this file returns the IDE to default defaults. Delete this file if you find that all "New Applications" are picking up settings, flags, or options that you do not really want. This file is also installed when you install a design time package.

DEFAULT.BPK	Default Project Options file for package projects. Created the first time you go to the Options dialog and click OK with the default checkbox is clicked ON. Deleting this file returns the IDE to default defaults. Delete this file if you find that new packages are picking up settings, flags, or options that you do not really want.

CSM	Precompiled header file (command-line option -H). If you don't specify your own precompiled header, the default is used ( ..\LIB\VCL40.CSM ) (You can delete these to be sure that the compiler regenerates these files.)

DCI	Holds Code Insight changes you make in the IDE.

DCT	Holds component template changes you make in the IDE.

DMT	Holds changes you make to menu templates in the IDE (may cause a "Stream Read Error" if corrupt; deleting it will lose your changes to menu templates but resolve the error ).

DRO	Holds changes when things are added to the repository. Can be deleted but your additions to the repository will lost. Can be restored to default by copying the default ..\bin\bcb.dro from the product CD.

DSK	Desktop settings. Saves the current state of the desktop, such as which windows are open, and in what positions. Used when Tools|Environment Options|Preferences Autosave Desktop is checked. Depending on where you’re working, you’ll save desktop settings for the project (Project.dsk), project group (Group.dsk), or IDE (..\bin\bcb.dsk). Delete these if you do not want to save the desktop settings.

IL?	Used by the incremental linker when "Generate and use incremental state files" is ON. (You can delete these files to make sure that the linker regenerates them.)

TDS	Holds the external debug symbol table.


Naming unit and project source code files

See also

As you open new units in a project, C++Builder gives them default names: UNIT1.CPP UNIT2.CPP, UNIT3.CPP, and so on. You can change a unit's default name to a meaningful (and unique) name when you save the project.

C++Builder also supplies a default name for the project file (PROJECT1.BPR) which you can rename when you save the project.

You can also create unit files that are not associated with forms, to divide your application in modules for housing global functions, classes, constants, data types, etc., as well as functions that you plan to share across projects.

Unit files are not associated with a form; they are simply a pair of .CPP and .h files. See About form and unit files for more information on these file types.

All unit and project file names must be legal C++ identifiers. When the compiler looks for a unit or project file, it first searches for a file with the full name of the unit or project identifier. If it does not find that file, it will then search for a version of the identifier name, truncated to eight characters. This is for backward compatibility and for compatibility with file servers that store only short file names. You should not manually truncate your file names.


Storing a project

See also

You should store each project in its own directory. By default, projects are stored in the Projects directory. Projects can share forms, files, and resources located in almost any directory, but it's best to keep the central project file and any other files specific to the project in a dedicated directory. See Sharing objects for more information about project templates and shared forms.


Viewing a project's contents

See also

The Project Manager displays the contents of your current project group and any project it contains. It allows you to navigate among various projects and the projects’ constituent files. You can perform project management tasks using its toolbar and context (right-click) menus.

To display the Project Manager:

1.	Open a project.

2.	Choose View|Project Manager.

To view a unit, form or other file, double-click it. It is displayed in the Code editor.

The Project Manager gives you a high-level view of the projects contained in a project group, and of the form, unit files, resource, object, and library files contained in the project file. You can use the Project Manager to open, add, save, and remove project files. You can also use the Project Manager to access the Project Options dialog box, which lets you configure your default project settings.

The Project Manager is an invaluable tool if you share files among different projects because it lets you quickly find each file in the project (see Adding existing forms and units to a project and Sharing objects). It is also useful when backing up all the files in your project (see Backing up a project).

Certain operations, such as commands available on context menus, operate on the active project. The active project is the one that is highlighted in bold in the Project Manager and is the project you are currently working on. The active project is also shown in the project selector which is the top left of the Project Manager. See Selecting a project to work on.

To make a project the active project:

1.	Display the Project Manager.

2.	Select the project you want to make active and click Activate.

When you view a project item, such as a form or source code, the Project Manager automatically makes the project it belongs to the active project. Projects you select using the project selector automatically become the active project.


Managing projects

See also

You can use the Project Manager to manage multiple projects within a project group. The Project Manager displays information about the status and file content of the current project and provides a convenient way to open, add, save, and remove project files (you can do some of these tasks from the File menu as well). You can also create new projects to add to the current project group.

You can perform the following tasks from the Project Manager:

Selecting a project to work on

Searching for files

Removing items in the Project Manager

Copying in the Project Manager

Getting project path and unit information

Adding projects to the project group

Adding existing forms and units to a project

Removing forms and units from a project

Copying a project


Using the Project Manager

See also

The Project Manager window displays information about the status and file content of the currently open project. If the project is part of a project group, it displays information about all projects within the project group.

With the Project Manager, you can easily visualize how all your project files are related. Also, you can select any file displayed, right-click, and perform various project management tasks, such as opening, adding or removing files, and compiling your projects.

Also, with the Project Manager you can add related projects to a project group. This way, you can compile multiple executables at the same time.

Use the Project Manager to perform project-related tasks such as adding and removing projects rather than editing the project’s makefile because C++Builder tracks and updates the affected files in your project.

If you save your desktop settings, you can have the Project Manager window opened by default when you open any project. The Project Manager is dockable (right-click and choose Dockable) so it can be docked or placed alongside other dockable windows.

The main elements of the Project Manager window are the

Project Manager file view

Project Selector

Project Manager toolbar

Project Manager status bar

Project Manager context menu


Project Manager file list
Project Manager file view

See also

The main area of the Project Manager provides a tree view of all the files in your project or project group. The file view displays all the source files (which end with a .C, .CPP, .IDL or .RC file extension) and binary object files (which can have a .RES, .LIB, or .OBJ file extension) in your project and the paths to the files. You can also add other file types to your C++Builder project (*.HTM, *.HTML, and *.TXT files, for example). However, C++Builder will not handle these files in any special way.

As you add and remove files from a project using the Project Manager, you can see that C++Builder updates the project  makefile (.BPR) and source file (.CPP).

If you have multiple projects, you can easily see all the related projects contained in the project group.

The Project Manager displays the currently active project in bold and displays its name in the project selector. See Viewing a project's contents for how to make a different project the active project.

Caution:	C++Builder has mechanisms for automatically tracking the files that make up a project and for keeping the project file updated. Avoid editing project files manually unless you have a thorough understanding of this process and its ramifications. By editing a project file, you circumvent C++Builder's automated project management and risk maintaining inaccurate information about project components. Compilation failures and other problems can result. If you edit the project file manually, you must close the file and reopen it to update the Project Manager display.


Project Manager toolbar

See also

You can display the toolbar (if it is not already displayed) by right-clicking in the Project Manager and choosing Toolbar. The toolbar displays buttons that provide quick access to common project tasks. You can also perform these tasks by using a context menu or choosing a menu command.

Button	Context menu command	Menu  command	Function	Comment
New	Add New Project	File|New or Project|Add New Project	Displays the New Items dialog so that you can add a new project to the current project group.	To add an existing project to this project group, select the project group, right-click, and choose Add Existing Project.
Remove	Remove Project	Project|Remove from Project	Removes the selected project from the current project group.	To remove individual files from a project, select the file, right-click, and choose Remove From Project. You can also use the Delete key. See Removing items in the Project Manager.
Activate	Activate	NA	Makes the selected project active so that you can make changes to the project.	You can activate a project in the Project Manager by double-clicking on it. You can also choose a project from the current project group using the project selector in the Project Manager.


Project Manager status bar

See also

You can display the status bar (if it is not already displayed) by right-clicking in the Project Manager and choosing Status Bar. The area at the bottom of the Project Manager window displays the full path name of the selected file.

The project file path name can be a useful reference if you are bringing many forms and units that reside in locations other than the main project directory into the current project.


Project Manager context menus

See also

The Project Manager allows you quick access to commands by right-clicking on any selected item in the file view. You get a different context menu depending on what type of file you select. Note that all of the context menus include the choices Toolbar, Status Bar, and Dockable. These options apply to the Project Manager.

File Type	Provides commands that	Available Commands
Project Group	Act on the project group as a whole.	Add new project, Add existing project, Save Project Group, Save Project Group As, View Project Group Source.
Project	Act on the current project.	Add, Remove File, Save, Options, Activate, Make, Build, View Source, View Project Makefile, Close, Remove Project, Build Sooner, Build Later.
File	Act on the current file. Which commands are available depends on the type of file selected.	Can be all or some of the following: Open, Remove from Project, Save, Save As, Compile.


Creating a project group

See also

Create project groups to handle related projects at once. For example, you can create a project group that contains multiple executable files such as a .DLL and an .EXE. By organizing them into a group, you can compile them at the same time. You may want to add a batch file to a project group to manage the build process, such as handling intermediate files (.OBJs) or incremental compiles (.ILS).

To create a project group:

1.	Choose View|Project Manager to display the Project Manager, if necessary.

If no project is currently loaded, the Project Manager lists <No Project Group>.

If a project is currently loaded, the Project Manager lists <ProjectGroup1>.

2.	Select the project group, right-click, and choose either:

Add New Project to open the New Items dialog box to add a new project.

Add Existing Project to add an existing project to this project group.

3.	When you have completed adding projects, select ProjectGroup1, right-click, and choose Save to rename the project group to a meaningful name.

To manage a project group:

 Select the project group, right-click, and a context menu appears.

For more information on project groups, see the topic, Example of using project groups.

Whenever you open a project that is not currently part of a project group, C++Builder displays the project as ProjectGroup1. You may choose to save the Project Group, thereby creating a project group for this project. However, it is not necessary.


Example of using project groups

See also

This topic guides you through the process of creating a few projects in a project group to show you one way a project group can be used. This example also demonstrates other features of C++Builder, such as managing intermediate files (such as OBJs), stepping into a DLL, creating console applications. The example walks you through creating four types of projects that could be contained in a project group. The projects you will create are

A batch file, to demonstrate how to handle intermediate files.

A DLL, to demonstrate how you can step into a DLL from your executable.

A console application, which does not contain any VCL objects.

A form-based VCL application.

To follow this example:

1.	Create a folder to contain the application’s source files.

2.	Create each type of project:

 Batch file

 DLL

 Console application

 VCL application.

3.	Build the project group example to see how project groups ease some aspects of the build process.


Example of creating a batch file

See also

The first task to complete in creating our project group example is to create a batch file. This batch file creates a subdirectory that will contain the intermediate (.OBJ) files generated during the build process.

To create a batch file:

1.	Choose File|New and choose batch file to create a batch file.

2.	In the Project Manager, select the project, right-click, and choose Options.

3.	In the Commands, type the following batch file commands:

@echo OFF

mkdir OBJS

@echo ON

pause

4. From the Project Manager, right-click and choose Save to name the batch file.

5. In the File name box, type CreateOutputDirs.

Notice the batch file automatically suggests the .BAT extension.

To name the project group,

1. From the Project Manager, select Project Group, right-click and choose Save Project Group As to name the project group.

2. In the file name box, type TestProjectGroup.

Notice the project group has the .BPG extension.


Example of creating a DLL

See also

The second task to complete in creating our project group example is to create a DLL. You put the DLL above the executable programs in the project group, because the EXEs will be using the DLL library produced by the DLL build.

C++Builder compiles the projects in the project group in the order in which they appear. To change the order of projects in a project group, select a project, right-click, and choose the Build Sooner or Build Later options.

To create a DLL:

1.	Select TestProjectGroup, right-click, and choose Add New Project.

The New dialog box appears, choose DLL to create a DLL project.

2.	In the Project Manager, select the project you just created and save it as HelloDLL.

3.	Add the following code to the HelloDLL.CPP file above the DLLEntryPoint function:

#include “HelloDLL.h”

char FileName[256];

void SayHello()

{

GetModuleFileName( NULL,FileName, sizeof (FileName) );

MessageBox ( NULL, FileName, “Hello from…”, MB_OK );

}

4.	Select the project in the Project Manager, right-click, and choose save, specifying a project name HelloDLL.

Notice the project file has the .BPR extension. Be sure to save the file in the same directory as TestProjectGroup.

5.	Select the project, right-click, and choose Options to view project options for the DLL. Select the Directories/Conditionals tab and enter in Intermediate Output:OBJS.

C++Builder places the intermediate .OBJ in the directory, which is created when the batch file runs.

6.	Enter in the Conditionals defines field: __BUILDING_THE_DLL.

This conditional will get invoked when C++Builder is building the DLL file, and not when it is building executable files as defined in the DLL header file which you create next.

 Notice C++Builder sets the Linker Project Option, Generate import library to true because we are generating a library.

7.	Create the DLL header file.

8.	Select the project, right-click, and choose Build to compile the library.

9.	Save the project and project group.


Example of creating a DLL header file

See also

After creating a DLL project, you need to create a corresponding DLL header file.

To create the DLL header file:

1.	Choose File|New and click Text to create a text file.

2.	Add the following code to the file:

#ifdef __BUILDING_THE_DLL

#define __EXPORT_TYPE __export

#else

#define __EXPORT_TYPE __import

#endif

void __EXPORT_TYPE SayHello();

3.	Right-click in the Code editor and choose Close Page to Save and save the file in the TestProjectGroup directory with the name, HelloDLL.h.


Example of creating a console application

See also

After creating the DLL in the TestProjectGroup, create a console application. The console application is a simple application, requiring no VCL application objects. This console application calls the DLL created earlier.

To create a console application:

1.	Select TestProjectGroup, right-click, and choose Add New Project.

The New dialog box appears.

2.	Choose Console wizard and click Finish as the wizard creates a console application by default.

3.	Select the project in the Project Manager, right-click, and choose save, specifying a project name ConsoleApp.

Notice the project file has the .BPR extension. Be sure to save the file in the same directory as TestProjectGroup.

4.	Add the following code to the ConsoleApplication so that the file looks like this:

#include <iostream>

#include <conio>

#include “HelloDLL.h”

int main (int argc, char **argv)

{

cout << “Calling the DLL…” << endl;

SayHello();

cout << “Hit any key to close…” << endl;

getch();

return 0;

}

5.	Select the project, right-click, and choose Add to Project to add the DLL library to the project. In the Add to Project dialog box, choose File of Type: *.lib to get a list of library files, and select HelloDLL.lib. Notice C++Builder updates ConsoleApp.cpp to include HelloDLL.lib.

6. In the project options, select the Directories/Conditionals tab and set the intermediate output to OBJDCUS.

C++Builder places the intermediate .OBJs in the specified directory, which is created when the batch file runs.

 Notice the Project Options|Conditionals defines _NO_VCL. C++Builder supplied this when it created the console application.

7. Save the project.

Building a console application that is a .C file

The extra steps required to build an application that has main() in a .C ( not .CPP) file are as follows:

1) in project source, add

#define main

2) in project source, remove

main()

3) Add the .C file that contains main()


Example of creating a form-based (VCL) application

See also

After creating the console application in the TestProjectGroup, create a form-based application. This application calls the DLL created earlier.

To create a form-based application:

1. Select TestProjectGroup, right-click, and choose Add New Project.

The New dialog box appears.

2. Choose Application.

3. Select the project in the Project Manager, right-click, and choose save, specifying the unit name as BuilderAppUnit, and the project name as BuilderApp.

Be sure to save the file in the same directory as TestProjectGroup.

4. Select the project, right-click, and choose Add to add the DLL library to the project. In the Add to Project dialog box, choose Files of Type: *.lib to get a list of library files, and select HelloDLL.lib.

5. In the form, select the button component on the Standard page of the Component palette and create two buttons as shown. Set the caption in Button1 to Get the DLL. Set the caption in Button2 to OK as shown:.

BuilderApp Form

6. Add the following headers and event handlers to BuilderAppUnit.CPP:

#include “BuilderAppUnit.h”

#include “HelloDLL.h”

void __fastcall TForm1::Button1Click(TObject *Sender)

{

SayHello();

}

void __fastcall TForm1::Button2Click(TObject *Sender)

{

Close();

}

7. In the project options, select the Directories/Conditionals tab and set the intermediate output to OBJs.

C++Builder places the intermediate .OBJs in the specified directory, which is created when the batch file runs.

8. Save the project.


Building the project group example

See also

Upon creating the four projects in the project group, build the projects to see the advantage of using project groups.

To build the project group:

1.	Choose Project|Build All Projects to build all projects.

2.	Set a couple of breakpoints before running the applications:

In HelloDLL.h, set a breakpoint at the SayHello( ) function.

In the HelloDLL.CPP, set a breakpoint at the GetModuleFilename function.

In ConsoleApp.CPP, set a breakpoint at the cout function.

3.	Select the ConsoleApp and press F9 to run the application.

When the program stops at the breakpoint, hit F7 to single step through the program execution.

4.	Select the BuilderAPP and press F9 to run the application.

When the program stops at the breakpoint, hit F7 to single step through the program execution.

 To set a breakpoint, display the file in the Code editor and click in the first column of the gutter.

Note:	When debugging applications and DLLs that reside in different source directories, set the Debug source path (Project|Options|Directories/Conditionals) and ensure that the debug info (.TDS) resides in the same directory as the EXE and DLL.


Selecting a project to work on

See also

The project selector is the list box at the top left of the Project Manager. You can select a project from the project group using the project selector. A drop-down list shows all projects in the current project group. The project you select becomes the active project. The active project is the one that is highlighted in bold in the Project Manager and is the project you are currently working on.


Searching for files

See also

You can locate files in large projects using an incremental search within the Project Manager. With the Project Manager displayed, start typing the name of a file and the Project Manager moves to the nearest match. Press the Spacebar to repeat the last search.

If you share files among different projects, using the Project Manager is highly recommended because you can quickly and easily tell the location of each file in the project. This is especially helpful to know when creating backups that include all files the project uses. (See Backing up a project for more information.)


Removing items in the Project Manager

See also

You can remove selected items in the Project Manager in the following ways:

Click the Remove button in the Project Manager.

Press the Delete key on the keyboard.

Choose Project|Remove from Project from the main menu.

The Project|Remove from Project dialog allows you to multiselect and remove multiple items from the project.

If a project is selected, the whole project including all it contains is deleted from the current project group. If one file is selected, only that file is deleted. Realize that the files are not deleted from disk, they are only disassociated from the current project or group. The Project Manager verifies that you want to remove the project or item before doing so.

Note	If you copy a file from one project to another then remove the first project without saving the second one, the copied item is removed from both projects. The Project Manager prompts you save the project before removing the item. If you save the project when prompted to do so, the copied item is retained.

The section Removing forms and units from a project provides more details about removing forms from projects.


Copying in the Project Manager

See also

You can addy items into projects in the Project Manager from other Windows folders using drag and drop. You can also copy and paste items from one project to another within a project group.

For information on copying an entire project, see Copying a project.

Note:	When you copy items in the Project Manager, you are not making a physical copy on the disk. You are including the file or item as part of the active project.

Drag and drop

You can drag one or more selected items from any Windows folder and drop them into a project in the Project Manager:

1.	Activate the project where you want the item to be added. The active project appears in bold in the Project Manager.

2.	In any Windows folder (such as the Windows Explorer or My Computer), select one or more items to copy.

3.	Drag the item or items onto the name of a project in the Project Manager.

4.	Drop the items.

You are asked to verify that you want to add the item or items, and if you click Yes, the items are added to the active project.

1.	Save the project where you added the items

Copying files between projects

You can copy any project item from one project to another:

1.	Select the project item you want to copy.

2.	Choose Edit|Copy (or type Ctrl+C).

3.	Select the project where you want to place the copy (or move the cursor where you want to place the copy).

4.	Paste the copy using Edit|Paste (or Ctrl+V).

1.	Save the project where you placed the copy.

You can also use drag and drop to copy items from one project to another.

Note	If you copy a file from one project to another then remove the first project without saving the second one, the copied item is removed from both projects. The Project Manager prompts you save the project before removing the item. If you save the project when prompted to do so, the copied item is retained.


Getting project path and unit information

See also

The status bar at the bottom of the Project Manager window displays the full path name of the project file. You can display and hide the status bar by right-clicking and choosing Status Bar.

The project file path name can be a useful reference if you are bringing many forms and units that reside in locations other than the main project directory into the current project.


Adding projects to the project group

See also

To add a new project to this project group, select the project group, right-click, and choose New. You can also use the New button on the Project Manager toolbar. Types of projects you can add are shown in the Object Repository. You can choose Project|Add Existing Project to add a project that was already created to the current project group.


Adding existing forms and units to a project

See also

A project can share any existing form and unit file including those which reside outside the project directory tree. This includes custom procedures and functions that have been written as standalone routines.

If you add a shared file to a project, realize that the file is not copied to the current project directory; it remains in its current location. Adding the shared file to the current project registers the file name and path in the project file. C++Builder automatically does this as you add units to the project.

Note:	The path that C++Builder uses for the shared file is either absolute or relative, depending on where the file is located. If the shared file is located on the same disk drive as your project, the C++Builder uses a relative path for the file; otherwise, it uses an absolute path.

When you compile your project, it does not matter whether the files that make up the project reside in the project directory, a subdirectory of the project directory, or any other location. The compiler treats shared files the same as those created by the project itself.

To add a shared file to the current project, do one of the following:

Choose Project|Add to Project.

Choose the Add File to Project button on the toolbar.

Choose Add from the Project Manager context menu.

Any of these actions displays the Add To Project dialog box, in which you can select the file you want the current project to use. The Path column of the Project Manager's file list displays the path to the shared file.

Using Borland C++, C, or Pascal source code units

If you have existing source code units for custom procedures or functions written in Borland C++, C, or Pascal, you can use these units in a C++Builder project. You add these files in the same way as files created in C++Builder.

Note:	Because C++Builder does not set file-specific options (the project options you set affect all the source files in your project), you might need to take an extra step to include routines that require specific compiler or linker settings. To do so, you must compile the desired module into a binary format (as an .OBJ file, a .DLL file, or an .LIB file) outside the project, then link or call the routines from there.You can also use the #pragma option to specify options within the .CPP source module.


Removing forms and units from a project

See also

You can remove forms and units from a project at any point during project development. The removal process deletes the reference to the file from the .BPR file. Using the procedures in Removing items in the Project Manager to remove a unit that has an associated form also removes the form from the project.

You can remove multiple items from a project with the dialog that displays after selecting Project|Remove from Project.

Removing a file from the project ends its association with the project; it does not delete the file from disk.

Caution:	Do not use Windows file management programs to delete C++Builder project files from disk until you have performed the preceding removal process in every project that uses the files. Otherwise, the project file of each project using the deleted files retains references to them. When you open the project again, C++Builder will attempt to locate the deleted files and display error messages for each file it cannot find. When the project opens, the information about its constituent files in the Project Manager is inaccurate.


Toggling between form image and unit source code

To switch between viewing the current form and its unit source code, use any of the following methods:

Press F12.

Choose View|Toggle Form/Unit.

Click the Toggle Form/Unit button on the toolbar.

In the Project Manager, double-click either the form or the source file.


Bringing a window to the front

If you have a number of windows open, and you want to bring one of them to the front:

1.	Choose View|Window List or press Alt+0 (zero).

1.	Double-click the name of the window you want to bring to the front.

You can also use command on the View menu to bring the Project Manager, ClassExplorer, Object Inspector, and other windows to the top. Additionally, you can use docking to keep preferred windows on top.


Viewing forms and units

See also

To display a list of forms or units associated with the current project, choose View|Forms or View|Units. Select a form or unit from the dialog box that appears, and choose OK.

The Project Manager also provides commands that let you quickly navigate to the source code and form images contained in your projects.

To view a specific form, double-click on the form listing in the Project Manager; C++Builder gives focus to that form image. Double-clicking a unit listing in the Project Manager opens the Code editor and displays the selected unit source file. If the file is not currently open, C++Builder opens it for you.


Saving projects and individual project files

See also

At any time during project development, you can save an open project in its current state to the project directory. You can optionally save a copy of the project in a different directory under the same or a different name.

You can also add your project to the Object Repository so that you or others can use it as a template. For more information, see Adding items to the Object Repository.

You are not limited to saving a project as a whole; you can save individual constituent files of a project, including saving a copy of a file to a different directory or with a different file name.


Saving a project

See also

Note:	If the project was begun from a project template, the Object Repository selection process creates the project directory. Otherwise, C++Builder saves projects by default to the \Projects directory if you start from the Start menu (Windows 95 and Windows NT). If you start C++Builder by clicking a shortcut icon, the default is \BIN which you can change to your preferred default location by right-clicking on the icon and choosing Properties. On Windows 98, you cannot customize the default location.

To save all open project files to the project directory, use one of the following methods:

Choose File|Save All.

Choose the Save All button on the toolbar.

Right-click in the Project Manager with a project selected, and choose Save.

From here, the save process for projects varies somewhat depending on whether you have previously saved the project:

If you have not previously saved the project, C++Builder displays the Save Unit As dialog box. This dialog box prompts you to supply a name for each open unit file that has been created in the current project. (You are not prompted for any shared files you might have added to the project. See Sharing objects.)

After you name the unit file, C++Builder prompts you to name the project file before saving it to disk. This processing order ensures that the unit and form file names you just specified are correctly registered in the project file's source code.

If you have previously saved the project, all open files that reside in the project directory are saved to disk if they have been modified.

If you have created any new forms or units in the project since the last save, the Save Unit As dialog box appears and prompts you to name those unit files before saving them.

The project file is then updated to reflect any new units and any newly shared files that you have specified for the project to use.

To save the project group file, select the project group in the Project Manager, right-click and choose Save Project Group or Save Project Group As. The group is saved in the project group file projectgroup.BPG. This is the makefile for the project group. It invokes a make on all of the projects in the group.


Copying a project

See also

You can save a separate version of an open project in a directory other than the project directory by choosing File|Save Project As. However, because the open project might use shared files in addition to files that were created as part of the current project, the Save Project As command saves a copy of just the project file, project options file, and the project resource file to the new location.

Important:	No unit files are saved to the new location. When you open the copied version, the Project Manager displays all units in the copied project as shared files; that is, none of them reside in the directory you copied the project to.

To copy an open project:

1.	Choose File|Save Project As to display the Save projectname As dialog box.

You are prompted for the new name and the location of the project file.

2.	Select the directory where you want to copy the project file.

3.	To save the project file under a different name, enter the new name in the File Name edit box.

If a project file with the same name exists in the directory you specify, you're asked if you want to overwrite the existing file. (This allows you to rename the individual .BPR, .CPP, and .DFM files in the project.)

4.	Choose OK.

The open project is now the project you just saved.

In addition to saving the project file, project options file, and project resource file to the new name/location, C++Builder also saves any modified unit files (in their current location). Therefore, you won't be prompted to save these changes again when you close the project. When you open either version of the project, all changes saved with the Save As operation are reflected in both places.

If you check the file list in the Project Manager, you will see that all the files in the currently open version of the project reside in a directory other than the current project directory. If you want separate copies of any of those files in the new project directory, you need to save them individually to the new location using File|Save As. (See Backing up a project for more information.)

If you leave the new project unchanged, it continues to use the files in their present (that is, old) location as shared files, which may or may not be what you want. If you don't understand how the new project is using its files, you can run into problems later.

Caution:	Do not use file management tools other than those in C++Builder to save a copy of a project to a new location.


Saving individual files

See also

You can save individual files in a project, or non-project files (such as text files) that you might have open in the Code editor.

To save an individual file:

1.	Bring the file to the front of the Code editor by selecting its tab.

2.	Choose File|Save As. If this is the first time you've saved the file, you're prompted to name it.

3.	If necessary, name the file and choose OK.

C++Builder saves the file.

Note:	Each file must have a unique prefix, even if their extensions are different. For example, if you specify About as the file name for both the form and project file, C++Builder displays the following error message:

The project already contains a module named About.

If you see this error message, C++Builder won't save the project file (or whichever file you named secondly). Save the file again with a different name.

To save a file under a different name or location:

1.	Bring the file to the topmost level of the Code editor by selecting its tab.

2.	Choose File|Save As.

The Save File As dialog box appears.

3.	Specify the new file name, or location, or both, and choose OK.

C++Builder saves a copy of the file under the name and location you specify.

Note:	This changes the name of the file, and if it is already part of the project, includes the file with the new name in the project. The older file still exists, but isn't included in the project any longer.

Caution:	If using shortened windows long file names, do so consistently. C++Builder views the shortened name and the full long file name as two different files.


Backing up a project

See also

Backing up a project can be a simple matter of copying directories or can involve some additional steps. This depends on how your project directories are structured and whether the project uses files from outside its own directory tree.

The project directory isn't encoded into the project file. The project file does, however, record the location of all the other files in the project. If these files reside in subdirectories of the main project directory, all path information is relative, which makes backup easy. You could back up such a project by copying (not moving) the directory tree to another location. If you open the project at the backup location, all the project files that reside within that structure are present, and the project will compile.

If this project uses files that reside outside the project directory tree, the project might or might not compile at the backup location. Check the Project Manager's file list to see if these outside files are accessible from the backup location. If they are, the project will compile. If other backup processes already preserve these outside files, then there is probably no need to make separate copies of them in the backup project directory.


Sharing objects

See also

The Object Repository (Tools|Repository) is a versatile tool that makes it possible to easily share (or copy) forms, dialog boxes, and data modules across projects and within a single project. It also provides project templates as starting points for new projects. By adding forms, dialog boxes, and data modules to the Object Repository, you make them available to other projects. In fact, you can add an entire project to the Object Repository as a template for future projects.

You'll also see wizards in the Object Repository. Wizards are small applications that lead you through a series of dialog boxes to create a form or project. C++Builder provides a number of wizards, and you can also create and add your own customized wizards to simplify and standardize your work.

The repository stores settings in a text file named BCB.DRO in the \BIN directory that contains references to the items that appear in the Object Repository dialog box and the New Items dialog box. You can open this file in any text editor.


Sharing items within a project

See also

It's also easy for you to share items within a project without having to add them to the Object Repository: when you open the New Items dialog box (File|New), you'll see a page tab with the name of your project. If you click that page tab, you'll see all the forms, dialog boxes, and data modules in your project. You can then derive a new item from an existing item, and customize it as needed.


Sharing objects in a team environment

See also

To share objects in a team environment, you need to specify a directory that's available to team members. After you do this, another BCB.DRO file is created in the specified directory as soon as you add an item to the Object Repository. The new BCB.DRO text file contains pointers to the objects you want to share.

To specify a shared repository directory:

1.	Choose Tools|Environment Options.

2.	On the Preferences page, locate the Shared Repository panel.

3.	In the Directory edit box, enter the name of the directory where you want to locate the shared repository.

The location of your shared directory is stored in the Windows registry. Changing the location in the Environment Options dialog box changes it in the registry as well.

To share Object Repository items among team members, every member's Directory setting in the Environment Options dialog box must point to the same location.


Copy, Inherit, or Use?

See also

To gain access to items in the Object Repository, choose File|New. The New Items dialog box appears, showing you all the items in the Object Repository. You have three options for adding an item to your project:

Copy

Inherit

Use

Copy option

Select Copy to make an exact copy of the selected item and add the copy to your project. Future changes made to the item in the Object Repository will not be reflected in your copy, and alterations made to your copy will not affect the original Object Repository item.

Copy is the only option available for using project templates.

Inherit option

Select Inherit to derive a new class from the selected item in the Object Repository and add the new class to your project. The Inherit option creates a link to the ancestor item in the repository. When you recompile your project, any changes that have been made to the item in the Object Repository are reflected in your derived class. These changes apply in addition to any changes or additions you make to the item in your project. Changes made to your derived class do not affect the shared item in the Object Repository.

Inherit is available as an option for forms, dialog boxes, and data modules, but not for project templates. It is the only option available for reusing items from within the same project.

Use option

Select Use when you want the selected item itself to become part of your project. In this case, you are not making a copy of the item; you are using the item itself, "live." Using an item is like reverse inheritance: instead of inheriting changes others make to an item, they inherit your changes when they use the item in the repository. Changes to the item appear in all projects that have added the item with the Inherit or Use options selected.

Caution:	The Use option is available for forms, dialog boxes, and data modules, but you should use it carefully. Make sure the changes you make to an item are thoroughly tested before letting others copy it into their applications from the repository.

Note:	The Use option is the only option available for experts, whether form experts or project experts. Using an expert doesn't actually add shared code, but rather runs a process that generates its own code.


Using project templates

See also

Project templates are predesigned projects you can use as starting points for your own projects.

To start a new project from a project template:

1.	Choose File|New to display the New Items dialog box.

2.	Choose the Projects tab.

3.	Select the project template you want and choose OK.

4.	In the Select Directory dialog box, specify a directory for the new project's files. If you specify a directory that doesn't exist, C++Builder creates it for you.

C++Builder copies the template files to the project directory. You can then modify the project, adding new forms and units, or use it by adding only your event-handler code. In any case, your changes affect only the open project. The original project template is unaffected and can be used again.


Adding items to the Object Repository

See also

You can add your own projects, forms, and data modules to those already available in the Object Repository.

To add an item to the Object Repository:

1.	If the item is a project or is in a project, open the project.

2.	For a project, choose Project|Add To Repository. For a form or data module, right-click the item and choose Add To Repository from the context menu.

3.	Type a description, title, and author.

The title will appear in the Object Repository window and in the New Items dialog box (File|New).

4.	Decide where you want this item to appear in the New Items dialog box, and select that page from the Page combo box. Or, type the name of the page.

If you type the name of a page that doesn't exist, C++Builder creates a new page for you, and your new page name will appear on a tab of the New Items dialog box.

5.	Choose Browse to select an icon to represent the object in the Object Repository.

6.	Choose OK.


Modifying a shared form

See also

If several projects share a form in the Object Repository, then modifications you make to the form can affect all projects, depending on how the form is imported into each project. If a project copies a form from the Object Repository, then later modifications to the form in the Object Repository have no effect on the project.

If a project inherits a form from the Object Repository, then each time the project is compiled, it inherits the latest version of the form from the Object Repository, including any changes made since the project was last compiled. If a project "uses" a form from the Object Repository, then any time you make changes to the form in the project, the changes are stored in the Object Repository directly where other applications can copy or inherit them.

If you know that other projects inherit a form in the Object Repository, but you do not want to replicate your changes to those projects, there are several ways to prevent inheritance:

Save the form under a different name and use the renamed form in your project instead of the original.

Make the changes to the form at runtime instead of at design time.

Make the shared form a component that can be installed onto the Component palette. This has the added advantage of enabling users to customize the form at design time.

If you expect to be the only user of the form, and you don't plan extensive or frequent changes, runtime customization is probably acceptable. If you plan on using the form in many different applications, runtime customization involves more coding for you and other developers. In this case, it's usually more convenient, whenever possible, to make the form a component that other users or developers can install onto their Component palette.


Specifying a default project, new form, and main form

See also

You can specify defaults for a new project, a new form, and a main form. You always have the option to override the defaults by choosing File|New and selecting from the New Items dialog box.


Specifying the default new project

See also

The default new project opens whenever you choose File|New Application. If you haven't specified a default project, C++Builder creates a blank project with an empty form. You might want to specify a project you're using as a template to be the default new project.

You can also designate a project wizard to run by default when you start a new project. A project wizard is a program that enables you to build a project based on your responses to a series of dialog boxes.

To specify the default new project:

1.	Choose Tools|Repository to display the Object Repository dialog box.

2.	Choose Projects in the Pages list.

3.	Select the project you want as the default new project from the Objects list.

4.	With the project you want selected, check New Project.

5.	Choose OK to register the new default setting.


Specifying the default new form

See also

The default new form opens whenever you choose File|New Form or use the Project Manager to add a new form to an open project. If you haven't specified a default form, C++Builder uses a blank form. You can specify any form as the default new form. Or you can designate a form wizard to run by default when a new form is added to a project.

To specify the default new form for new projects:

1.	Choose Tools|Repository to display the Object Repository dialog box.

2.	Choose Forms in the Pages list.

3.	Select the form you want as the default new form from the Objects list.

4.	With the form you want selected, check New Form.

5.	Choose OK to register the new default setting.


Specifying the default main form

See also

Just as you can specify a form template or expert to be used whenever a new form is added to a project, you can also specify a form template or expert that you want to use as the default main form whenever you begin a new project.

To specify the default main form for open projects:

1.	Choose Tools|Repository to display the Object Repository dialog box.

2.	Choose Forms in the Pages list.

3.	Select the form you want as the default main form from the Objects list.

4.	With the form you want selected, check Main Form.

5.	Choose OK to register the new default setting.


Setting project options

See also

You can change project settings in the Project Options dialog box. To open this dialog box, do one of the following:

Choose Project|Options.

With a project selected in the Project Manager right-click and choose Options.

The settings you change affect only the current open project, unless you check the Default check box (see the next topic). If you change any of the default settings, an options file DEFAULT.BPR is created in the project directory the next time you save the project. So when you reopen the project in future work sessions, the project options you set are in effect.

Note:	For package projects, options are saved in a file called DEFAULT.BPK.

These topics discuss only those project options that pertain to project management. For detailed information about the options on any given page of the dialog box, click the Help button on that page.


Setting options that affect all new projects

See also

The Project Options dialog box contains a check box labeled Default. Checking this control writes the current settings from the Compiler, Linker, Directories/Conditionals, Packages, and VersionInfo pages of the Project Options dialog box to a file called DEFAULT.BPR. C++Builder creates this file when you check the Default box and choose OK in the Project Options dialog box. C++Builder then uses the project options settings stored in this file as the default for any new projects you create.

Note:	For packages, a file called Default.BPK is created when you change project options Package Project Options page with the "Default" checkbox checked ON. All subsequent new Package projects will pick up the settings saved to DEFAULT.BPK. Deleting this file will return new package projects to default settings.

If you create a project from a template in the Object Repository that has its own options file, those settings will override the default settings in DEFAULT.BPR.

To learn about information on all of the Project Options pages, choose Project|Options and display any page. Click Help or press F1 for Help on setting the options.

Caution:	Only keep the DEFAULT.BPR when you intend to create new applications of the same type. For example, do not save a DEFAULT.BPR with a VCL appllication open then create a console application. Deleting DEFAULT.BPR returns you to the default for all types of projects.


Restoring C++Builder's original default settings

See also

To restore C++Builder's original default project settings, delete, or rename the DEFAULT.BPR file. For packages, delete the DEFAULT.BPK file.


Setting environment preferences

See also

In addition to changing project settings you can customize the C++Builder environment (editor, designer, debugger, and compiler). Preferences you set in the Environment Options dialog box affect all C++Builder projects.

To specify environment settings, choose Tools|Environment Options. Click the Help button on any page of the Environment Options dialog box for help with that page.

Note:	If you share your installation of C++Builder with other users, it's possible that another user has modified the default option settings. In a shared-installation situation, it's a good idea to check environment options before creating a new project.


Managing multiple project versions and team development

See also

When you are developing a complex programming project in a team setting, or managing several development projects, you might soon develop the need for a version control system (VCS). A version control system can archive files, control access to project files, and track multiple versions of your projects.

Some versions include a built-in interface for Intersolv's PVCS Version Manager. Because C++Builder uses an Open Tools API, it can also be used with any commercially available version-control utility. Some versions of C++Builder include both the PVCS interface and PVCS itself.

Enabling team development support

Before using C++Builder's built-in team development support, you need to have PVCS installed on your system, and the several files must reside in your \WINDOWS\SYSTEM directory.

For information on using the team development support features of C++Builder, choose WorkgroupsIBrowse PVCS Projects to display the PVCS Project window, then click the Help icon to open the PVCS Help system for details on version control tasks.. You can also read the online Help for PVCS by opening the file PVCS.HLP.


Compiling, building, and running projects

See also

All projects have as a target a single distributable executable file, either an .EXE or a .DLL file. You can view or test your application at various stages of development by compiling, building, or running it. You can also test the validity of your source code without attempting to compile the project.

If you have grouped several projects together, you can compile or build all projects in a single project group at once. Choose Project|Make All Projects or Project|Build All Projects with the project group selected in the Project Manager.


Compiling a project

See also

To compile all the source-code files that have changed since the last time you compiled them,
Choose Project|Make projectname.

Once all the modules that make up the project have been compiled, C++Builder compiles the project file and creates an executable file (or dynamic-link library). This file is given an .EXE (or .DLL) file extension and the same file name as the project source code file. This file now contains all the compiled code and forms found in the individual units, and the program is ready to run.

Obtaining compile status information

You can get information about the compile status of your project by displaying the Information dialog box (Project|Information). This dialog box displays information about the number of lines of source code compiled, the byte size of your code and data, the stack and file sizes, and the compile status of the project.

You can get status information from the compiler as a project compiles by checking the Show Compiler Progress box in the Environment Options dialog box, Preferences page.


Building a project

See also

To compile all the source-code files in your project, regardless of when they were last compiled,
Choose Project|Build projectname.

The result of this command is similar to that of the Project|Make command, except that all units in the project are compiled, regardless of whether or not they have changed since the last compile. This technique is useful when you are unsure of exactly which files have or have not been changed, or when you simply want to ensure that all files are current and synchronized. It's also important to use Build when you've changed global compiler directives, to ensure that all code compiles in the proper state.


Running a project

See also

You can test run a project from within C++Builder, or you can run the compiled .EXE file from the Windows operating environment without having to run C++Builder.

To compile and then run your application from within C++Builder, either:

Choose Run|Run.

Choose the Run button on the toolbar.

These actions are identical to choosing the Project|Make command, except that C++Builder runs your application immediately if the compile operation succeeds.

Executing a project from Windows

Because the compiler always creates a fully compiled standalone executable file (.EXE), you can run your application from the Windows operating environment using the same techniques as you would for any other Windows application.

If you have specified an icon for your project, it will appear beside the file name in the Windows Explorer, in a shortcut on the desktop, on the Windows Start menu, and on the taskbar when you minimize the application while it is running.


Database menu

The Database menu commands enable you to create, modify, track, and view databases.

Explore

SQL Monitor

Form wizard


Database | Explore

Choose Database|Explore to open the Database Explorer or SQL Explorer, depending on your version of C++Builder. Both tools let you create, view, and edit data and BDE aliases. In addition, the SQL Explorer lets you query local and remote databases.


Database | SQL Monitor

Choose Database|SQL Monitor to open the SQL Monitor.

This tool, available only in some versions of C++Builder, lets you monitor SQL resource allocation and see the actual statement calls made through SQL Links to a remote server or through the ODBC socket to an ODBC data source.


Database | Form Wizard

See also

Choose Database|Form Wizard to use the Database Form wizard to create a form that displays data from a local or remote database.


Using the Form wizard
Using the Database Form wizard

See also

Use the Database Form wizard to easily generate a form that displays data from any database that has a valid BDE alias.

Select the type of database forms to create:

Simple database form

Master/detail form

Select the DataSet option:

TTableObject

TQueryObject

The tool automates such form building tasks as:

Connecting the form to Table and Query components

Writing SQL statements for Query components

Placing interactive and non-interactive components on a form

Defining a tab order

Connecting DataSource components to interactive components and Table/Query components


Creating a form using the Form wizard

You can use the Form wizard to create a simple database form.

To build a database form by using the Form wizard:

1.	Open the Form wizard by choosing Database|Form Wizard.

2.	Select a Form Option.

3.	Select a DataSet and click Next.

4.	From the Drive or Alias Name list, select an alias.

Note:	If you have not created an alias, you can still enter a local database name by specifying the path to a database in the Form Wizard dialog box.

5.	Select the fields to use on the generated form.

To use only some of the fields:

1.	Press and hold Ctrl.

2.	Select each field you want from the Available Fields list.

3.	Choose the > button.

To use all of the fields from the Available Fields list:

Click the button marked >>.

To remove fields from the Selected Fields list:

Click the buttons marked < or <<.

To reorder the fields in the Selected Fields list:

1.	Select a field to move.

2.	To change the field's position in the list, choose the Up or Down button.

For the purposes of this exercise, use all the fields from the Available Fields list. Choose Next to proceed.

3.	The next Form wizard screen presents options for displaying the selected fields on the form. The wizard explains and illustrates each of your choices.

For the purposes of this exercise, choose the Vertical option.

4.	The Form wizard generates text labels for each of the data entry components in the generated form when you opt for a vertical layout. You can choose the way these labels are displayed in relation to the data entry fields. The screen explains and illustrates your choices.

For this exercise, choose the Left option, then choose Next to proceed.

5.	Choose the Create button to generate the form.

The Form wizard generates a database form based on your choices.


Update SQL editor

Use the Update SQL editor to create SQL statements for updating a dataset.

The TUpdateSQL object must be associated with a TQuery object by setting the TQuery property UpdateObject to the name of the TUpdateSQL object used to contain the SQL statements.  A datasource, and database name must be selected for the TQuery object . In addition, the SQL property must include an SQL statement defining a table.

To open the SQL editor:

1.	Select the TUpDateSQL object in the form.

2.	Right-click and choose Update SQL editor.

The Update SQL editor has two pages, the Options page and the SQL page.

The Options page

The Options page is visible when you first invoke the editor.

Table Name 	Use the Table Name combo box to select the table to update. When you specify a table name, the Key Fields and Update Fields list boxes are populated with available columns.

Key Fields 	The Key Fields list box is used to specify the columns to use as keys during the update. Generally the columns you specify here should correspond to an existing index, especially for local Paradox and dBASE tables, but having an index is not a requirement.

Update Fields 	The Update Fields list box indicates which columns should be updated. When you first specify a table, all columns in the Update Fields list box are selected for inclusion. You can multi-select fields as desired.

Get Table Fields	Read the table fields for the table name entered and list the fields.

Dataset Defaults	Use this button to restore the default values of the associated dataset. This will cause all fields in the Key Fields list and the Update Fields list to be selected and the table name to be restored.

Select Primary Keys 	Click the Primary Key button to select key fields based on the primary index for a table.

Generate SQL 	After you specify a table, select key columns, and select update columns, click the Generate SQL button to generate the preliminary SQL statements to associate with the update component’s ModifySQL, InsertSQL, and DeleteSQL properties.

Quote Field Names 	Check the box labeled Quote Field Names to specify that all field names in generated SQL be enclosed by quotation marks.

The SQL page

To view and modify the generated SQL statements, select the SQL page. If you have generated SQL statements, then when you select this page, the statement for the ModifySQL property is already displayed in the SQL Text memo box. You can edit the statement in the box as desired.

Note:	Keep in mind that generated SQL statements are intended to be starting points for creating update statements.  You may need to modify these statements to make them execute correctly. Test each of the statements directly yourself before accepting them.

Use the Statement Type radio buttons (Modify, Insert, and Delete) to switch among generated SQL statements and edit them as desired.

To accept the statements and associate them with the update component’s SQL properties, click OK.


Index Files editor

For dBASE tables that use non-production indexes set the IndexFiles property to the name of the index file(s) to use before you set IndexName. At design time you can click the ellipsis button in the IndexFiles property value in the Object Inspector to invoke the Index Files editor.

To see a list of available index files, choose Add, and select one or more index files from the list. A dBASE index file can contain multiple indexes. To select an index from the index file, select the index name from the IndexName drop-down list in the Object Inspector. You can also specify multiple indexes in the file by entering desired index names, separated by semicolons.


Field Link designer

The Field Link Designer provides a visual way to link (join) master and detail tables.

At design time, drop a TDataSource object on the form and define a datasource. Select the TTable component and double-click the MasterFields property in the Object Inspector to invoke the Field Link designer.

Available Indexes combo box

The Available Indexes combo box shows the currently selected index used to join the tables. Unless you specify a different index name in the table’s IndexName property, the default index used for the link is the primary index for the table. Other available indexes defined on the table can be selected from the drop-down list.

To link master and detail tables:

1	Select the field to use to link the detail table in the Detail Fields list

2	Select the field to link the master table in the Master Fields list.

3	Choose Add.

The selected fields are be displayed in the Joined Fields list box. For example,

OrderNo -> OrderNo

Note:	For tables on a database server, the Available Indexes combo box will not appear, and you must manually select the detail and master fields to join in the Detail Fields and Master Fields list boxes.


Edit menu

Use the Edit menu commands to manipulate text and components at design time.

Undo/Undelete 	Undoes your last action or last deletion

Redo	Reverses an undelete or undo.

Cut	Removes a selected item and places it on the Clipboard

Copy	Places a copy of the selected item on the Clipboard, leaving the original in place

Paste	Copies the contents of the Clipboard into the Code editor window or form

Delete	Removes the selected item

Select All	Selects all the components on the form

Align To Grid	Aligns the selected components to the closest grid point

Bring To Front	Moves the selected component to the front

Send To Back	Moves the selected component to the back

Align	Aligns components

Size	Resizes components

Scale	Resizes all the components on the form

Tab Order	Modifies the tab order of the components on the active form

Creation Order	Modifies the order in which nonvisual components are created

Flip Children	Invert the layout controls into a right-to left mirror image.

Lock Controls	Secures all components on the form in their current position

Add to interface	Define a new method, event, or property for an ActiveX component.

CORBA Refresh	Update all existing CORBA implementation classes to reflect changes made to the IDL files.

Use CORBA Object	Add code to a CORBA client application that binds to a CORBA object and obtains a stub instance for working with an object on the server.


Edit|Undelete
Edit | Undo/Undelete

See also

Choose Edit|Undo in the Code editor to undo your most recent keystrokes or mouse actions. Choose Edit|Undelete when working with a form to replace an item you just deleted.

Using Undo in the Code editor

Undo can reinsert any characters you delete, delete any characters you insert, replace any characters you overwrite, or move your cursor back to its prior position.

You can undo multiple successive actions by choosing Undo repeatedly. This removes your changes by "stepping back" through your actions and reverting to their previous state. You can specify an undo limit on the Editor Options page of the Tools|Environment Options dialog box.

If you undo a block operation, your file appears as it was before you executed the block operation.

Note:	The Undo command does not change an option setting that affects more than one window.

To undo a group of actions,

1. Choose Tools|Environment Options|Editor

2. Check Group Undo.


Edit|Redo

See also

Choose Edit|Redo to reverse the effects of your most recent Undo.

Redo has an effect only immediately after an Undo command.

Redo is not available for reversing the effects of the Undelete command.


Edit|Cut

See also

Choose Edit|Cut to remove the following items from their current position and place them on the Clipboard:

Selected text from the Code editor.

Components from the active form.

Menus from the Menu designer.

Cut replaces the current Clipboard contents with the selected item.

To insert the contents of the Clipboard elsewhere:
Choose Edit|Paste.


Edit|Copy

See also

Choose Edit|Copy to place an exact copy of the selected text, component, or menu on the Clipboard and leave the original untouched. Copy replaces the current Clipboard contents with the selected items.

To paste the contents on the Clipboard elsewhere:
Choose Edit|Paste.


Edit|Paste

See also

Choose Edit|Paste to insert the contents of the Clipboard into the active Code editor page, the active form, or active menu in the Menu designer.

Note: You can paste only text into the Code editor window, only components onto the form, and only menu items into the Menu designer.

When pasting into the Code editor window, the text is inserted at the current cursor position.

When pasting onto the form, nonvisual components are pasted into the upper left corner of the form, and visual components are pasted into the exact position from which they were cut or copied.

When pasting into the Menu designer, menu items are inserted at the cursor position.

You can paste the current contents of the Clipboard as many times as you like until you cut or copy a new item onto the Clipboard.


Edit|Delete

See also

Choose Edit|Delete to remove the selected text or component without placing a copy on the Clipboard.

Even though you cannot paste the deleted item, you can restore it by immediately choosing Edit|Undelete.

Delete is useful if you want to remove an item but you do not want to overwrite the contents of the Clipboard.


Edit|Select All

Edit|Select All selects every item (where appropriate) in the active window.

In the Form Designer, choose Edit|Select All to select every component on the active form. When you select multiple components, only those properties which the components have in common appear in the Object Inspector.

In the Code editor, choose Edit|Select All to select all the text in the currently displayed file.


Edit|Align To Grid

See also

Choose Edit|Align To Grid to align the selected components to the closest grid point.

To select more than one component, hold down Shift while clicking each one.

You can specify the grid size on the Preferences page of the Tools|Environment Options dialog box.

You can also invoke Align to Grid by right clicking in an active form.


Edit|Bring To Front

See also

Choose Edit|Bring To Front to move a selected component in front of all other components on the form. This is called changing the component's z-order.

Note:	The Bring To Front and Send To Back commands do not work if you are combining windowed and non-windowed controls. For example, you cannot change the z-order of a label in relation to a button.

You can also invoke Bring to Front by right clicking in an active form.


Edit|Sent to Back
Edit|Send To Back

See also

Choose Edit|Send To Back to move a selected component behind all other components on the form. This is called changing the component's z-order.

Note:	The Send To Back and Bring To Front commands do not work if you are combining windowed and non-windowed controls. For example, you cannot change the z-order of a label in relation to a button.

You can also invoke Send to Back by right clicking in an active form.


Edit|Align

See also

Choose Edit|Align to open the Alignment dialog box.

Alignment dialog box

Use this dialog box to line up selected components in relation to each other or to the form.

The Horizontal alignment options align components along their right edges, left edges, or midline.

The Vertical alignment options align components along their top edges, bottom edges, or midline.

The options for horizontal or vertical alignment are:

Option	Description

No Change	Does not change the alignment of the component

Left Sides	Lines up the left edges of the selected components (horizontal only)

Centers	Lines up the centers of the selected components

Right Sides	Lines up the right edges of the selected components (horizontal only)

Tops	Lines up the top edges of the selected components (vertical only)

Bottoms	Lines up the bottom edges of the selected components (vertical only)

Space Equal	Lines up the selected components equidistant from each other

Center In Window	Lines up the selected components with the center of the window

You can also invoke Align by right clicking in an active form.


Edit|Size

See also

Choose Edit|Size to open the Size dialog box.

Size dialog box

Use this dialog box to resize multiple components to be exactly the same height or width.

The Width options change the horizontal size of the selected components.

The Height options align the vertical size of the selected components.

The options for horizontal or vertical sizing are:

Option	Description

No Change	Does not change the size of the components.

Shrink To Smallest	Resizes the group of components to the height or width of the smallest selected component.

Grow To Largest	Resizes the group of components to the height or width of the largest selected component.

Width	Sets a custom width for the selected components.

Height	Sets a custom height for the selected components.

You can also invoke Size by right clicking in an active form.


Edit|Scale

See also

Choose Edit|Scale to open the Scale dialog box.

Scale dialog box

Use this dialog box to proportionally resize the form and all the components on that form.

Scaling Factor, In Percent

Enter a percentage to which you want to resize the form. The scaling factor must be between 25 and 400.

Percentages over 100 grow the form.

Percentages under 100 shrink the form.

You can also invoke Scale by right clicking in an active form.


Edit|Tab Order

See also

Choose Edit|Tab Order to open the Edit Tab Order dialog box. You can also invoke Tab Order dialog box by right clicking in an active form.

Edit Tab Order dialog box

Use this dialog box to modify the tab order of the components on the form or within the selected component if that component contains other components.

Controls	Lists the components on the active form in their current tab order. The first component listed is the first component in the tab order. The default tab order is determined by the order in which you placed the components on the form.

Up	Click Up to move the component selected in the Controls list box higher in the tab order.

Down	Click Down to move the component selected in the Controls list box lower in the tab order.

To change the tabs order of a component:

1.	Select the component name.

2.	Click the up button to move the component up in the tab order, or click the down arrow to move it down in the tab order.

You can also drag the selected component to its new position in the tab order.

3.	To save your changes, click OK.


Edit|Creation Order

See also

Choose Edit|Creation Order to open the Creation Order dialog box. You can also invoke the Creation Order dialog box by right clicking in an active form.

Creation Order dialog box

Use this dialog box to specify the order in which your application creates nonvisual components. when you load the form at design time or runtime.

The list box displays only those nonvisual components on the active form, their type, and their current creation order. The default creation order is determined by the order in which you placed the nonvisual components on the form.

To change the creation order:

1.	Select a component name.

2.	Click the up button to move the component creation order up, or click the down arrow to move its creation order down.

You can also drag the selected component to its new position in the creation order.

3.	To save your changes, click OK.


Edit|Flip Children

See also

Edit|Flip Children allows you to reverse the layout of controls in the current form to a right-to-left mirror image. This lets developers quickly change a form created for an audience that reads left to right so that it appears natural in environments where users read from right to left.

All	Reverses the position of all children of the form. Also flips the alignment of any controls aligned to the left or right of the form.

Selected	Reverses the position of all children of the selected controls. Also flips the alignment of any controls aligned to the left or right of the selected controls.


Edit|Lock Controls

Choose Edit|Lock Controls to secure all components on the active form in their current position. When this command is checked, you cannot move or resize a control. However, you can use the Object Inspector to edit the Height, Left, Top, and Width properties for a selected control.

When this command is checked, controls are locked. When controls are locked, you can choose Lock Controls to unlock them.

Note:	Lock Controls has no effect on the form, itself. When you select Lock Controls, you can still resize or move the form.


Add To Interface
Edit|Add to Interface

See also

Choose Edit|Add to Interface to define a new procedure, function, or property for an ActiveX component.  These elements will be added to the ActiveX component’s interfaces, making them available to other applications. This command is a short-cut for declaring an interface member to be used by an ActiveX component.

Alternatively, you can right-click in an ActiveX implementation file and choose Add to Interface from the context menu.

The Edit|Add to Interface command displays the Add to Interface dialog box that lets you choose an interface member type (such as property, method, or event) and then quickly enter the declaration for the selected type.

To automatically check the syntax of what you type in the declaration box,
Click the Syntax Helper checkbox.

When you click OK, the declaration you entered is automatically stored in the three required locations:

The current ActiveX Implementation unit

The ActiveX Type Library (TLB file)

The Type Library (DTL file)

Now you can simply write the actual code for the method or set the property in your implementation unit.


CORBA Refresh
Edit|CORBA Refresh

See also

Choose Edit|CORBA Refresh to update existing CORBA implementation classes so that they reflect any changes to the IDL files contained in the project. When you choose CORBA Refresh, C++Builder

Compiles your IDL files, creating new server and client units.

Checks for the interfaces that correspond to existing implementation classes. If C++Builder can’t find an interface, it will ask if the interface was renamed, and if so, prompt you for the new interface name.

Reflects changes to interfaces by adding new methods to existing implementation classes. Note that if attributes or operations are removed from an interface, the corresponding methods are not removed. Instead, they become local methods that are only available within the server application but which are not available to clients. Similarly, if renaming a method or attribute is treated like an insertion and a deletion, so that you end up with the old method or attribute as well as the new one.

Displays the Project Updates dialog so that you can preview and edit any of the automatically generated changes to your implementation, depending on the setting on the CORBA page of the Environment Options dialog.

Note:	CORBA Refresh only updates existing implementation classes for interfaces that you have modified. To generate implementation classes for new interfaces, use the CORBA Object wizard instead.


Renamed Interfaces dialog

The Renamed Interfaces dialog appears when you attempt to update your CORBA implementation classes and C++Builder can’t find the interface that corresponds to an existing implementation class.

Original Name

In the control labeled Original Name, indicate the name of the interface as it existed when the CORBA Object Wizard generated the implementation class (or when you last updated the implementation class using Edit|CORBA Refresh).

New Name

In the control labeled New Name, select the current name of the interface that used to have the name listed under Original Name.  If you do not find the current name of the interface in the drop-down list, check that the appropriate IDL file is still included in your project.


Use CORBA Object
Edit|Use CORBA Object

See also

Choose Edit|Use CORBA Object to automatically generate code that binds to a CORBA object and obtains a stub instance for working with an object on the server.

When you choose Use CORBA Objects, C++Builder

Compiles your IDL files, creating new server and client units.

Displays the Use CORBA Object Wizard, where you can specify the object you want to use and where you will use it.


Use CORBA Object Wizard

See also

Choose Edit|Use CORBA Object to display the Use CORBA Object Wizard. This wizard generates code that instantiates a stub object and binds to an available server object so that your CORBA client can interact with the object on the server.

CORBA Object

IDL File	Choose the IDL file that defines the interface for the object you want to use. Click the drop-down arrow for a list of all IDL files contained in the project. If the desired IDL file is not already in the project, click the ellipses button to browse for the desired file. The Wizard will add this IDL file to your project.

Interface Name	Select the interface of the object you want to use. This interface must be in the IDL file specified in the IDL File control.

Object Name	Specify the name of the object instance on the CORBA server. This is the name that is passed as a parameter to the constructor on the server. If Object Name is blank, the generated code will bind to any implementation of the specified interface that is available on a running CORBA server.

The Use CORBA Object wizard includes tabbed pages that describe how you want to instantiate the stub when binding to the server object. Select only one of these pages and provide the indicated information.

Use in Form (available only for Windows applications)

Form Name	Specify the name of an existing form. The wizard adds a property to this form that contains an instance of the stub class for the specified interface.

New Property Name	Specify the name of the property that the wizard adds to your form.

Use in main()

New Variable Name	Specify the name of the variable that the wizard generates in your main() or WinMain() function.

Use in class()

Unit name	Specify the name of the unit that defines the class where you want a property for the CORBA object reference.

Class name	Specify the name of the class within the specified unit that you want to get the new property. You can choose an existing class name or type in a new name and the wizard will create a new class that you can complete.

New Variable Name	Specify the name of the class member that holds a CORBA object reference.

Declare Get Method	When checked, the wizard generates a method that returns the CORBA reference, performing the bind if necessary.

Declare Set Method	When checked, the wizard generates a set method to assign a CORBA object reference to the class member specified by New Variable Name.

Declare Property	When checked, the wizard adds a property to the class that provides public access to the new variable through the get and set methods.

Show Updates

Check the box labeled Show Updates to view and edit all changes introduced by the Use CORBA Object wizard. If you check Show Updates, you will see the Project Updates dialog when you click OK.


File menu

See also

Use the File menu to open, save, close, and print new or existing projects and files, and to add new forms and units to the open project.

File commands	Description

New	Opens the New Items dialog box, which contains objects that are stored in the Object Repository and Wizards for creating new objects.

New Application	Creates a new project containing an empty form, a unit, and a project file.

New Form	Creates and adds a blank form to the current project.

Open	Displays the Open dialog box for loading an existing project, form, unit, or text file into the Code editor.

Open Project	Displays the Open Project dialog box for loading an existing project (.BPR or .BPK file).

Reopen	Displays a cascading menu containing a list of most recently closed projects and modules.

Save	Saves the current file using its current name.

Save As	Saves the current file using a new name, including modifications made to project files

Save Project As	Saves the current project using a new name.

Save All	Saves all open files, both current project and modules.

Close	Closes the current project and its associated units and forms.

Close All	Closes all open files.

Include Unit Hdr	Adds the selected unit to the active module with an #include statment.

Print	Sends the active file to the printer.

Exit	Closes the open project and exits C++Builder.


File|New

See also

The New Items dialog box provides access to the templates and the Forms, Dialogs, Projects, and Business pages of the Object Repository. The New Items dialog box contains pages for each category of template or Object Repository page.

The Object Repository contains forms, projects, and wizards. For information about including these objects in your projects, see Including objects from the Object Repository.


Including objects from the Object Repository

See also

To include an object from the Object Repository, you can:

Copy the item

Inherit from the item

Use the item directly

Copying Items

When you copy an item, you make an exact duplicate of the item and add it to your project if it is a form or data module. Any changes to the item in the Object Repository will not be reflected in your copy. Alterations you make to your copy will not affect the original Repository item.

Note: 	Copying is the only option available for using project templates or project wizards. Using a wizard does not add shared code; it runs a process that generates its own code.

Inheriting Items

Inheriting items is the most flexible and powerful way to use a Repository object.  Inheriting lets you reuse items within the same project.

When you inherit an item, a new class is derived from the item and is added to your project. When you recompile your project, any changes made to the item in the Object Repository are reflected in your derived class, unless you have changed a particular aspect.

Changes made to your derived class do not affect the shared item in the Object Repository.

Note:	You can inherit forms, dialog boxes, and data modules but not project templates. This is the only option available for reusing items from within the same project.

Using Items Directly

You use the Using Items Directly option primarily with data modules. When you use an item directly, the item is added to your project as if you had created it as part of the project. Design-time changes made to the item appear in all projects that directly use the item as well as any projects that inherit from the item.

Note:	Using Items Directly is an option for forms, dialog boxes, and data modules. Modify these items only at runtime to avoid making changes that affect other modules.


File|New Application

See also

Choose File|New Application to create a new C++Builder project group with a single application in it.

Instead of the standard blank project, you can specify a custom project template as the default project.

If a project is open when you choose File|New Project, C++Builder prompts you to save any changes to the project, closes the current project group, and creates a new project group. You can use Project|Add New Project to add a new project to the current project group.

A new project consists of:

A new project makefile (PROJECT1.BPR) and its associated source code (PROJECT1.CPP).

A new form file (FORM1.DFM), and its associated header (UNIT1.H) and source file (UNIT1.CPP).

A resource file (PROJECT1.RES).

Tip:	Change the names of the project, header, and .cpp files to more meaningful names before continuing.

To redefine the default project:

1.	Choose Tools|Repository to open the Object Repository dialog box.

2.	In the Pages list box, click Projects.

A list of projects appears in the Objects list box.

3.	Select the project that you want to become the default project.

4.	Select the New Project check box.

5.	Click OK.

The default project specified in the steps above will be now be used when you use the New Application command.


File|New Form

See also

Choose File|New Form to create a default form and a new unit and add them to the project.

When you create a new form, C++Builder adds the new form and associated unit files to the list of files included in the open project. If no project is open, a blank form is created.

If you did not redefine the default form (or if you selected a blank form from the New Items dialog), the new form is titled FormXX and the new unit is UnitXX.CPP, where XX represents the form/unit number, that is, the first form is Form1, the second Form2.

To change the name of the form:
Edit the Name property from the Object Inspector.

To change the unit name:
Save the file by using File|Save File As or save the entire project by using File|Save Project As.

Changes made to any form or unit name are reflected throughout the source code anywhere that name appears within that unit.

You can specify a custom form as the default form.

To redefine the default form:

1.	Choose Tools|Repository to open the Object Repository dialog box.

2.	In the Pages list box, click Forms or Dialogs.

A list of items appears in the Objects list box.

3.	Select the form that you want to become the default form.

4.	Select the New Form check box.

5.	Click OK.

The default form specified in the steps above will be now be used when you use the New Form command.


File|Open

See also

Choose File| Open to display the Open dialog box.

Open dialog box

Use the Open dialog box to load an existing project, form, unit, or text file into the Code editor.

Opening a file does not add it to your current project. To add a file to a project, choose File|Add To Project.

You can open multiple forms, units, or text files but you can have only one project open at any time. If a project is open when you select File|Open, C++Builder prompts you to save any changes made to the current project.

Look In 	Lists the current directory. Use the drop down list to select a different drive or directory.

Files 	Displays the files in the current directory that match the wildcards in File Name or the file type in Files Of Type. You can display a list of files (default) or you can show details for each file.

File Name 	Enter the name of the file you want to load or type wildcards to use as filters in the Files list box.

Files of Type 	Choose the type of file you want to open; the default file type is unit file (.CPP). All files in the current directory of the selected type appear in the Files list box.

Up One Level	Click this button to move up one directory level from the current directory.

Create New Folder	Click this button to create a new subdirectory in the current directory.

List	Click this button to view a list of files and directories in the current directory.

Details	Click this button to view a list of files and directories along with time stamp, size, and attribute information.


Open File dialog box

Use the Open File dialog box to specify the type of file you want to create when you enter a new file name into the File Name edit box.

You can create a:

Form

Unit

Text file

To choose a type of file to create, select the file type and click OK. C++Builder creates a file of the selected type but does not add it to the project.

If you are creating a file that you want to include in the current project, use one of the following methods:

Choose Project|Add to Project.

Choose View|Project, then right-click on the Project Manager window and choose Add File.


File|Open Project

See also

Choose File|Open Project to open an existing project.

If a project currently open, you are prompted to save your changes and the currently open project is closed before you open another project.


File|Reopen

See also

Choose File|Reopen to reopen a recently closed project or module.

When you close a project or a module, it is added to the Reopen list.

To Reopen a project or module:

1.	From the File menu, choose Reopen.

2.	Click the project or module that you want to reopen.

Note:	Only projects or modules that have been closed with the File|Close command appear in the Reopen list. Saved Items do not appear in the list.


File|Save

See also

Choose File|Save to store changes made to all files included in the open project using the current name for each file.

If you try to save a project that has an unsaved project file or unit file, C++Builder opens the Save As dialog box where you enter the new file name.

Note:	Open files that are not included in the project file are not saved. To save these files, select each file in the Code editor and choose File|Save.

Note	 If you modify a .C/.CPP file or a .H, the other corresponding file is saved automatically.


File|Save As

See also

Choose File|Save As to save the active file with a different name or in a different location.

Note 	C++Builder tightly couples unit .CPP and .h files. When you open a unit in a project, C++Builder also references that unit’s .h file. If you then use Save As to rename either the unit .CPP file or the unit .h file, C++Builder renames both the .CPP and the .h files.

Save As dialog box

Use the Save As dialog box to change a unit’s file name or to save the unit in a new location. If the file name already exists, C++Builder asks if you want to replace the existing file.

Look In 	Lists the current directory. Use the drop down list to select a different drive or directory.

File Name	Enter a name for the file you are saving.

Files	Displays the files in the current directory that match the file type in the Save File as Type combo box.

Save File As Type	Choose a file extension. All files in the current directory of the selected type appear in the Files list box. Note that saving a project file with a different extension does not change the format of the file.

Up One Level	Click this button to move up one directory level from the current directory.

Create New Folder	Click this button to create a new subdirectory in the current directory.

List	Click this button to view a list of files and directories in the current directory.

Details	Click this button to view a list of files and directories along with time stamp, size, and attribute information.


This form must have .CPP extension

see also

You will see this message if you enter a filename with an extension other than .CPP when trying to save a form unit’s source file.

When you select Save As from the file menu when a project is open, .it saves the form unit’s source file and header file. You must give the source file a .CPP extension, and the header is automatically given the corresponding name with a .h extension.

If you are trying to save the project, use File | Save Project As instead.


File|Save Project As

See also

Choose File|Save Project As to save the project file (.BPR file) to a new name or location. In addition to copying and/or renaming the .BPR file, this command saves the project source file to the same name as the .BPR with a .CPP extension.

Tip:	If you have modified forms or units that are used by other projects, and you do not want the current modifications reflected in those other projects, use File|Save As to copy/rename each unit file before choosing this command to save the project.

Save Project As dialog box

Use the Save Project As dialog box to change the project file name or to save the project in a new location. If the file name already exists, C++Builder asks if you want to replace the existing file.

Look In 	Lists the current directory. Use the drop down list to select a different drive or directory.

File Name	Enter a name for the project file you are saving.

Files	Displays the files in the current directory that match the file type in the Save File As Type combo box.

Save File As Type	Choose a file extension; the default is .DPR. All files in the current directory of the selected type appear in the Files list box. Note that saving a project file with a different extension does not change the format of the file.

Up One Level	Click this button to move up one directory level from the current directory.

Create New Folder	Click this button to create a new subdirectory in the current directory.

List	Click this button to view a list of files and directories in the current directory.

Details	Click this button to view a list of files and directories along with time stamp, size, and attribute information.


Projects must have .BPR extension

see also

You will see this message if you enter a filename with an extension other than .BPR when trying to save a project’s BPR file. BPR files are a special form of makefile and must have the .BPR extension so that C++Builder knows how to interpret them.

Check that you entered the extension correctly. If you are trying to save some other type of file, cancel from the save as dialog.


File|Save All

See also

Choose File|Save All to save all open files, including the current project and modules.

To save all files:

1.	From the File menu, choose Save All.

If you are saving the files for the first time, the Sae All dialog box appears with a defualt name for the item to be saved.

1.	Type in a new file name if you do not want to use the default name.

2.	Click Save.

The Save As dialog appears again with a default name for the next item to be saved.

3.	Repeat previous steps until all modules are saved.


File|Close

See also

Choose File|Close to close the active window.

Note:	File|Close typically closes only a single file. However, if the file is a form, it closes the associated unit file. If the Project Manager is the active window, it closes all files in the project.

Before closing the file, C++Builder prompts you to save any changes. If you have not previously saved the project, or any file, C++Builder opens the Save As dialog box, where you can enter the new file name.

You can close the entire project by choosing File|Close when the Project Manager is the active window. If you close the project file (.BPR)  from the Code editor, you also close the entire project.


File|Close All

See also

Choose File|Close all to close all open files. The project file and all modules are closed.

Tip:	Another way to close all files is to close the project file (with the .BPR extension) in the Code editor.


File|Include Unit Hdr

See also

Choose File|Include Unit Hdr to add an #include statement for an existing unit to the current unit in the Code editor. This command lets you access public objects, methods, functions, and procedures in the chosen unit from the current unit.

Use this command after adding a form to a project to add the related unit header file for that form.


Include Unit dialog box

Use this dialog box to make the contents of the specified unit available to the current unit.

To include a unit:

1.	From the File menu, select Include Unit Hdr.

The Include Unit Hdr dialog box appears. It displays a list of all units in the project that are not currently included by the current unit. You can only use units when they are part of the current project. If the current project contains no more units, a message box appears instead.

2.	In the Include Unit list, click the name of the unit you want to add.

3.	Click OK to add the unit to the current unit.


File|Print

Choose File|Print to print the active page in the Code editor or the active form. When you choose File|Print, C++Builder displays one of two dialog boxes depending on whether the Code editor or the form is the active window.

When the Code editor is active, C++Builder displays the Print Selection dialog box.

When the form is active, C++Builder displays the Print Form dialog box.


Print Form dialog box

See also

Use this dialog box to specify any scaling options when printing a form. The scaling options depend on the size of the printer paper. You can change the size of the paper using the Paper Size option in the Printer Setup dialog box.

To display this dialog box, select File|Print when a form is active.

There are three scaling options:

Proportional: Scales the form using value of the PixelsPerInch property. Depending on the value of PixelsPerInch, your form may print on more than one page.

Print To Fit Page: Scales the form so that it will fit onto one page.

No Scaling: Prints the form using its current onscreen size. If you choose this option, your form might print on more than one page.

Setup

To display the Printer Setup dialog box, click the Setup button.


Print Selection dialog box

See also

Use this dialog box to print the active file from the Code editor.

File To Print 	Lists the file that you are going to print. The file listed is the active page in the Code editor when you chose File|Print.

Print Selected Block	Sends only the selected block of text to the printer. This option is available only when you have text selected in the file. If this option is not checked, the entire file will print.

Header/Page Number	Includes the name of the file, current date, and page number at the top of each page.

Line Numbers	Places line numbers in the left margin.

Syntax Print	Uses bold, italic, and underline characters to indicate elements with syntax highlighting.

Use Color	Prints colors that match colors onscreen (requires a color printer).

Wrap Lines	Uses multiple lines to print characters beyond the page width. If not selected, code lines are truncated and characters beyond the page width do not print.

Left Margin	Specifies the number of character spaces used as a margin between the left edge of the page and the beginning of each line.

Setup 	Click the Setup to display the Printer Setup dialog box.


Printer Setup dialog box
Printer Setup

See also

Changes printer options and selects a printer from a list. To display this dialog box, click Setup from the Print Selection dialog box or the Print Form dialog box.

For more information about setting printer options, see your Windows documentation.

Name	Selects a printer from the list box.

Portrait	Prints text across the narrowest side of the paper (such as, 8.5" x 11").

Landscape	Prints text along the widest side of the paper (such as, 11" x 8.5").

Paper Size	Specifies the paper size.

Paper Source	Specifies the paper tray or paper feeding method your printer uses.

Properties	Displays the Printer properties page for the currently selected printer.


File|Exit

Choose File|Exit to close the open project and then close C++Builder.

If you exit before saving your changes, C++Builder asks you if you want to save them.


New Items dialog box

See also

Use the New Items dialog box to select a form, project template, or wizard that you can use as a starting point for your application. The New Items dialog box provides a view into the Object Repository. The Object Repository contains forms, projects, and wizards. You can use the objects directly, copy them into your projects, or inherit items from existing objects.

The New Items dialog box tabs

Each tabbed page in the New Items dialog box contains items that you can include in your project. Four of these pages are fixed, providing standard C++Builder components:

New

ActiveX

Multitier

Your project

The remaining pages are user-defined pages containing forms, projects, data modules, or wizards from the Object Repository. You can create your own objects and store them in these pages to use as templates for your projects.

When shipped, the New Items dialog box contains these additional pages:

Forms

Dialogs

Data Modules

Projects

Business

Right-click the page and choose View Details to read a description of each item.

To add a new form from the New Items dialog box:

1.	Choose File|New to open the New Items dialog box.

2.	Choose the tab that contains the item you want add from the Forms or Dialogs page.

3.	Select the item in the list view that represents the kind of form you want to add.

4.	Choose whether you want to copy, inherit, or use the new form.

To start a new project from a project template:

Choose File|New to display the New Items dialog box.

1.	Choose the Projects tab.

2.	Select the project template you want and choose OK. Or select the Application wizard to define a custom template.

3.	In the Select Directory dialog box, specify a directory for the new project’s files.

A copy of the project template opens in the specified directory. Or the Application wizard will prompt you to enter a directory name.

To view the item description:

1.	From the File menu select New.

2.	Select an item in the New Items dialog box.

3.	Right-click the mouse.

4.	Select View Details from the context menu.

The item description appears in the Description column.

To edit, add pages to, or rename items in the Object Repository:

Right-click the New Items dialog box to display the speed menu. The speed menu allows you to customize the display.

Note:	To open the Object Repository dialog box, select Properties from the context menu. You can use this dialog box to edit, add pages to, and rename items in the Object Repository.

Usage Options

There are three ways to include a Repository Object in your project. The options are dimmed if unavailable for a specific object.

Copy the item

Inherit from the item

Use the item directly

For more information about usage options, see Including objects from the Object Repository.


Select Directory dialog box

Use the Select Directory dialog box to choose a working directory for your new project.

To open the Select Directory dialog box:
Select File|New, select the Projects tab, and then select a non-blank project template.

Directory Name 	Displays the current directory. If you enter a directory that does not exist, C++Builder creates it.

Directories 	Lists the current directory.

Files (*.*)	List all the files in the current directory. You cannot select any of these files. C++Builder displays this file list so you know the contents of the current directory.

Drives 	Lists all the available drives. You can select one of the available drives.


New page

See also

The New page contains many pre-built components that you can use in your application development.

New Item	Description

Application	Creates a new project containing a form, a unit (.CPP and .H files), and a .BPR, or provides a way for you to select a template.
Batch file	Creates a new batch file project with a .BAT extension that allows you to specify batch commands. The project is not associated with any forms or code editor.
Component	Creates a new component using the Component wizard.
Console Wizard	Creates a new console application project.
Data Module	Creates a new data module that can be used as a repository for nonvisual components and business rules.
DLL	Creates a new DLL project.
Form	Creates and adds a blank form to the current project, or lets you select a form template.
Library	Creates a library.
Package	Creates a new package. Displays the New Package dialog box where you specify the file name and description of the new package. The package is added to the current project, and the source for the new package appears in the code editor.
Project Group	Creates a new Project Group to contain related projects. By adding associated projects to a Project Group, you can build all the projects with one command. The Project Group has the extension .BPG.
Report	Creates a Quick report that helps you create visually design effective reports for your database applications.  Note: you can also use the QuickReport wizard on the Business page.
Resource DLL wizard	Starts up a wizard to help you generate a resource DLL that contain localized versions of your application forms.
Service	Adds a new service to an existing NT service application. Do not add services to an application that is not a service application. While a TService object can be added, the application will not generate the requisite events or make the appropriate Windows calls on behalf of the service.
Service Application	Creates a new NT service application. Once you have created a service application, You will see a window in the designer that corresponds to a service (TService). Implement the service by setting its properties and event handlers in the Object Inspector.
Text	Creates a new ASCII text file.
Thread Object	Creates a new thread object.
Unit	Creates and adds a new unit to the current project.
Web Server Application	Creates a new Web server application DLL or EXE.


New Web Server Application dialog box

See also

Use the New Web Server Application dialog box to specify the type of server your Web server application will work with. After choosing the type of Web server application, click OK to create a new project configured to use Internet components and containing an empty Web module.

To bring up the New Web Server Application dialog box:

1	Choose File|New to open the New Items dialog box.

2	Choose the tab labeled New.

3	Select the Web Server Application item in the list view.

The New Web Server Application Options

ISAPI/NSAPI Dynamic Link Library

ISAPI and NSAPI Web server applications are DLLs that are loaded by the Web server. Client request information is passed to the DLL as a structure and evaluated by TISAPIApplication. Each request message is handled in a separate execution thread.

Selecting this type of application sets up your project as a DLL with the exported methods expected by the Web server. It also includes the appropriate header files for generating your application.

CGI standalone executable

A CGI standalone Web server application is a console application that receives client request information on standard input and passes the results back to the server on standard output. This data is evaluated by TCGIApplication. Each request message is handled by a separate instance of the application.

Selecting this type of application sets up your project as a console application and includes the appropriate header files.

Win-CGI standalone executable

A Win-CGI standalone Web server application is a Windows application that receives client request information from a configuration settings (INI) file written by the server and writes the results to a file that the server passes back to the client. The INI file is evaluated by TCGIApplication. Each request message is handled by a separate instance of the application.

Selecting this type of application sets up your project as a Windows application and includes the appropriate header files.


New Thread dialog box
New Thread Object dialog box

See also

Use the New Thread Object dialog box to define a thread class that encapsulates a single execution thread in a multi-threaded application.  Type the name of the class you wish to define in the Class Name edit control.  Click OK to create a new unit that defines a thread class with the name supplied in the dialog. You must then supply the code that executes when the thread is run by writing the Execute method.

Note: Unlike some other dialogs in C++Builder, the New Thread Object dialog does not prepend a T to the supplied class name.  You will want to type a class name such as TMyThread, rather than typing MyThread and expecting the T to be added implicitly.

To bring up the New Thread Object dialog box:

1	Choose File|New to open the New Items dialog box.

2	Choose the tab labeled New.

3	Select the Thread Object item in the list view.


Resource DLL wizard

See also

Use the Resource DLL wizard to create a resource DLL project. Resource DLLs contain all the forms and strings for your application, including those generated by VCL components. Resource DLLs are useful for creating localized versions of your application. You must have a separate DLL for each locale supported.

Typically, you generate localized resource DLLs when you are ready to deploy your application. You can translate the DFM and RC files either before or after creating the resource DLL project.

Note: The Resource DLL wizard creates a resource DLL; it does not perform the translations.

To use the Resource DLL wizard,

1	Save and build your project

2	With your project open, choose File|New|Resource DLL wizard

C++Builder displays a list of files containing all forms and strings that require translation, including those forms generated by VCL components (such as login-forms).

The wizard provides Add and Remove buttons to add or remove additional forms located elsewhere, if needed.

3	Choose Next when you have all the desired forms listed.

The wizard prompts you for any additional DRC files you might want to add.

If your project references other RC files that are not listed here, you can add them by hand using the Add button. However, the wizard automatically detects all strings used by your application, and places them in a generated resource file. Therefore, do not add additional RC files that contain only string table resources.

4	Choose Next and select the desired language for your resource DLL.

Each Windows locale has a specific file extension. The wizard supplies the default name and extension, generates a project for a DLL, and places the project in a subdirectory with the same name as the language extension. The DLL has the name of the project with the language extension. For example, the project myproject now has a subdirectory called fra that contains the localized DLL, myproject.fra.

Note:	Use the default language extension whenever possible because that is what C++Builder expects. On a French system, C++Builder looks for an extension .FRA. If you use something else, it won't be found.

5	When you finish, the wizard closes the open project (or project group) and then opens the new Resource DLL project. You must now compile the project to create the Resource DLL.

6	To deploy your application, copy the DLL from the subdirectory into your project directory that contains the executable. You need only ship this localized DLL with your application .EXE and .DLL files.


Console application wizard
Console wizard

See also

To customize the project, specify the desired project parameters below.

Choose New|Console wizard to open the Console wizard dialog box. You customize how C++Builder creates your project by choosing whether the project:

 Is either a console or Window GUI application

 Is either a .DLL or .EXE

 Includes the VCL

C++Builder creates a project including only those elements specified.


Batch file projects

With batch file, you can create a project with the .BAT extension to run batch files. Right-click on the batch file project and choose Edit/Options to enter the commands in your batch file project and to indicate how commands are invoked.

The Command Execution radio buttons indicate how the batch file is executed.

Use Command Interpreter
C++Builder invokes the command-line interpreter as specified. Typically, this is $(COMSPEC), which evaluates to the command-line interpreter defined in the environment variable (such as windows\command.com or 4dos\4dos.com). You can specify another command interpreter by typing its name in the edit box or browsing for it by clicking on the ellipsis button.

Use Windows Shell
C++Builder executes each command in the batch file (using CreateProcess). It waits until each command terminates before executing the next, therefore, it handles executable programs only.

Note: If you have specified that the batch file uses the command-line interpreter, C++Builder adds a line to the top of the file, “REM CommandInterpreter: $(COMSPEC),” to tell the IDE to start the command-line interpreter upon invoking this batch file. Do not remove this line from the batch file.

Note: When using a command interpreter, C++Builder automatically passes a “/c” command-line parameter to the command interpreter. This switch is valid for most popular shells. If, however, your shell requires a different switch, specify that switch in the Windows registry. Under HKEY_CURRENT_USER\Software\Borland\BCB\4.0\Compiling, add a string key called “InterpreterOptions,” and set the value of that key to the switches you want passed to the command interpreter.

Note:	If your batch file requires a command-line interpreter, you must set this option before invoking the batch file.

To create a new batch file target,

1. Choose File|New and select the Batch file icon from the New page.

C++Builder creates a new project with no source code editor.

2. In the Project Manager, select the project, right-click and choose Edit/Options. The Batch file options dialog box appears.

3. In the Commands edit box, type the commands to include in the batch file.

4. Choose the method for invoking the batch file commands.

If you want to specify a different command interpreter, type its name in the edit box.

5. Click OK.

C++Builder saves the file using the batch file extension, .BAT. It also adds code to the project group file (project.BPG).

To load an existing batch file,

1. Choose File|Open.

2. In Files of type, select Batch file (*.bat) to display batch files.

3. Double-click the desired .BAT file to open it.

4. Right-click and choose Edit/Options to choose the method for invoking the batch file commands.


ActiveX page

Click the objects in this page to create new COM objects, Active Forms, ActiveX controls, property pages for ActiveX controls, and type libraries for Active X controls or Automation objects.

New Item	Description

Active Form	Create a new Active form, which is a simpler ActiveX control (descended from TActiveForm) preconfigured to run on a Web browser. The ActiveX Control wizard appears to guide you through the creation process, allowing you to add controls to the form. The wizard creates an ActiveX Library project (if needed), a type library, a form, an implementation unit, and a unit containing corresponding type library declarations. Note: Unlike other ActiveX controls, you cannot modify the properties of a built Active form in a development environment unless you add code to publish the properties.
ActiveX Control	Create a new ActiveX control. The ActiveX Control wizard guides you through the creation process, choosing the VCL object on which you want to base the new control.  Note that ActiveX controls need an ActiveX library to expose their interfaces and method arguments to client applications. If an ActiveX Library project is not open before you try to create an ActiveX control, C++Builder opens one.
ActiveX Library	Create a new ActiveX library. A template file named Project1.bpr is created as a starting point for you. If an ActiveX Library project is not open before you try to create an ActiveX control, C++Builder opens one.
Automation Object	Create a new Automation object. The Automation Object wizard allows you to enter a class name for the new Automation object and set the threading model. If an ActiveX Library project is not open before you try to create an ActiveX control, C++Builder opens one.
COM Object	Create a new COM object for simple, lightweight objects such as a shell extension. The COM Object wizard allows you to enter a class name for the new Automation object.
Property Page	Create a file that sets up an ActiveX property page. The property page appears in design mode, ready for you to add private and public declarations.  You can design a dialog box in the form window, grouping properties to make it easy for developers to modify the control when implementing it in an application.
Type Library	Create or edit a library of type information for an ActiveX control or an Automation object. The Type Library editor appears.


ActiveX Control Wizard

See also

Use the ActiveX Control Wizard to add an ActiveX control or Active Form to an ActiveX Library project. The wizard creates an ActiveX Library project (if needed), a type library, a form, an implementation unit, and a unit containing corresponding type library declarations. Note that ActiveX controls need an ActiveX library to expose their interfaces and method arguments to client applications.

To bring up the ActiveX Control Wizard:

1	Choose File|New to open the New Items dialog box.

2	Choose the tab labeled ActiveX.

3	Select the Active Form or ActiveX Control icon.

In the Wizard, you can specify the following:

VCL ClassName

Specify the class on which your ActiveX control is based. For example, to create an ActiveX control that allows client applications to use a TButton object, specify TButton. When creating Active forms, this control is disabled because active forms are always based on TActiveForm.

New ActiveX Name

The wizard provides a default name that clients will use to identify your ActiveX control or Active form. Change this name to provide a different OLE class name.

Implementation Unit

The wizard a default name for the .CPP and .H files that contain the code that implements the behavior of the ActiveX control or Active form. You can accept the default name or type in a new name.

Project Name

ActiveX controls and Active forms must be added to an ActiveX library project. If you currently don't have an ActiveX Library project open, a fourth field allows you to specify which ActiveX Library project to add the ActiveForm control. A default Project Name is provided. This control is disabled if you have an ActiveX Library open.

ActiveX control options

Include Design-Time License

A design-time license ensures that users of the control can’t open the control for design purposes unless they have a license key for the control. With Include Design-Time License checked, the wizard creates a key for the control which is stored in a .LIC file with the same name as the project. The user of the control must have a copy of the .LIC file to open the control in a development environment. Each control in the project that has Include Design-Time License checked will have a separate key entry in the .LIC file.

Include Version Information

This option includes version information in the .OCX file. Adding this resource to your control allows your control to expose information about the module, such as copyright and file description, which can be viewed in the browser. Version information can be specified by choosing Project|Options and selecting the Version Info page. Some clients, such as Visual Basic 4.0, require version information for registering controls.

Include About Box

When this box is checked, an About box is included in the project. The user of the control can display the About box in a development environment. The About box is a separate form that you can modify. By default, the About box includes the name of the ActiveX control, an image, copyright information, and an OK button.


Multitier page

See also

Click the objects in this page to create servers that are part of a multi-tiered application.

New Item	Description

CORBA Client	Create a CORBA client project. The CORBA client wizard generates code to initialize the ORB (and BOA optionally) and adds IDL files to your CORBA client project. You can then use the Use CORBA Object wizard to bind to objects defined in those IDL files.
CORBA IDL File	Create a blank IDL file and add it to the current project. Type in the interfaces for your CORBA server using CORBA IDL. Once you have defined your interfaces, choose Project|Compile Unit with the IDL file active in the code editor to compile the IDL file into server and client units.
CORBA Server	Create a CORBA server project. The CORBA Server wizard generates the code to initialize the BOA and ORB and adds IDL files to your CORBA server project. You can then use the CORBA Object wizard to create implementation classes for the interfaces in those IDL files.
CORBA Object Implementation	Create a CORBA server object. The CORBA Object wizard appears to generate the initial implementation of an interface, including code to instantiate objects and tie classes.
MTS Data Module	Create a new MTS Data Module to act as an application server in a multi-tiered database application. The MTS Data Module wizard appears to generate the initial implementation, defining an implementation class for the data module with the specified threading and transaction options.
MTS Object	Create a new MTS object. The MTS wizard allows you to create an Automation object that runs in the MTS runtime environment.
Remote Data Module	Create an application server in a multi-tiered database application.  The Remote Data Module wizard appears to generate the initial implementation, defining an implementation class for the data module with the specified threading options.


Remote Data Module wizard

See also

Use the Remote Data Module wizard to create a data module that can be accessed remotely as a dual-interface Automation server.  A remote data module resides in the application server between a client and server in a multi-tiered database environment.

To bring up the Remote Data Module wizard:

1	Choose File|New to open the New Items dialog box.

2	Choose the tab labeled Multitier.

3	Select the Remote Data Module item in the list view.

The Remote Data Module wizard Options

CoClass Name

Enter the base name for the Automation interface and your remote data module.  The class name for your remote data module (a descendant of TDataModule) will be this name with a T prepended. The implementation class will descend from an interface named using this base name with an I prepended. To enable a client application to access this interface, set the ServerName property of the client application’s connection component to the base name you specify here.

Threading Model

If you are creating the remote data module in an active library (DLL), use the threading combo box to indicate how client calls are passed to your remote data module’s interface. The following table lists the possible values:

Value	Meaning

Single	The library only receives one client request at a time. Because all client requests are serialized by COM, you don’t need to deal with threading issues.

Apartment	Each instance of your remote data module services one request at a time. However, the DLL may handle multiple requests on separate threads if it creates multiple COM objects. Instance data is safe, but you must guard against thread conflicts on global memory.

Free	Your remote data module instances can receive simultaneous client requests on several threads. You must protect instance data as well as global memory against thread conflicts.

Both	The same as Free except that all callbacks to client interfaces are serialized.

Description

Enter the text that appears in the registry next to the ProgID for the application server interface. This text also acts as a help string for the interface in the type library.

Options

Generate Event Support Code	The implementation class descends from an interface with a name of the form IBaseClassNameEvents. This interface descends, in turn, from IEvents. This allows your application to fire events, broadcasting a message when they occur.


MTS Data Module wizard

See also

Use the MTS Data Module wizard to create the server in a multi-tiered database application that uses MTS.  MTS data modules must exist within an Active Library (DLL), so that they can be instantiated as needed by the MTS proxy.

To bring up the Remote Data Module wizard

1. Choose File|New to open the New Items dialog box.

2. Choose the tab labeled Multitier.

3. Select the MTS Data Module item in the list view.

The MTS Data Module wizard Options

Class Name edit control

Enter the base name for the Automation interface and your remote data module.  The class name for your remote data module (a descendant of TDataModule) will be this name with a T prepended. The implementation class will descend from an interface named using this base name with an I prepended. To enable a client application to access this interface, set the ServerName property of the client application’s connection component to the base name you specify here.

Threading model

Use the threading combo box to indicate how client calls are passed to your remote data module’s interface. The following table lists the possible values:

Value	Meaning

Single	The implementation class only receives one client request at a time. Because all client requests are serialized by MTS, you don’t need to deal with threading issues.

Apartment	Any implementation class instance receives one request at a time, but not always on the same thread. Instance data is thread-safe, but global memory must be explicitly protected against thread conflicts.

Free	For MTS data modules, Free is the same as Apartment.

Both	The same as Apartment except that all callbacks to client interfaces are serialized.

Transaction Model

Use the Transaction Model radio buttons to indicate the MTS transaction attributes of your application server interface. The following table lists the possible values:

Value	Meaning

Requires a transaction	Every time a client calls the implementation class’s interface, the call is enlisted in an MTS transaction. If the caller supplies a transaction context, a new transaction need not be created.

Requires a new transaction	Every time a client calls the implementation class’s interface, a new transaction context is automatically created for that call.

Supports transactions	The application server can be enlisted in an MTS transaction, but the client must supply the transaction context.

Does not support transactions	The application server interface can’t participate in MTS transactions.

Options

Generate Event Support Code	The implementation class descends from an interface with a name of the form IBaseClassNameEvents. This interface descends, in turn, from IEvents. This allows your application to fire events, broadcasting a message when they occur.


CORBA Server Wizard

See also

Use the CORBA Server wizard to start a new CORBA server project.

To bring up the CORBA Server wizard:

1. Choose File|New to open the New Items dialog box.

2. Choose the tab labeled Multitier.

3. Select the CORBA Server item in the list view.

Application Type

Choose Console Application or Windows application to determine the type of executable you want to build. If you select Console Application, you can choose whether Enable the VCL.

Enable VCL

When Enable VCL is unchecked, generated code does not include any dependencies on the VCL. All generated code is portable (can be compiled for other platforms).

Add IDL Files

List the IDL files that your server project uses. These include the IDL files that define the CORBA objects you are implementing, as well as any IDL files that contain definitions your project must use.

Add Button	Allows you to browse for IDL files.

Remove Button	Removes an IDL file from the list.

Add New IDL File	Adds a blank IDL file to the project so that you can define new interfaces.

When you choose OK, the CORBA Server Wizard creates a new server project of the specified type, adding the CORBA libraries to the project file and adding startup code to initialize the ORB (Object Request Broker) and BOA (Basic Object Adaptor).


CORBA Client Wizard

See also

Use the CORBA Client wizard to start a new CORBA client project.

To bring up the CORBA Client Wizard:

1. Choose File|New to open the New Items dialog box.

2. Choose the tab labeled Multitier.

3. Select the CORBA Client item in the list view.

Application Type

Choose Console Application or Windows application to determine the type of executable you want to build. If you select Console Application, you can choose whether Enable the VCL.

Enable VCL

When Enable VCL is unchecked, generated code does not include any dependencies on the VCL. All generated code is portable (can be compiled for other platforms).

Initialization

Check the BOA init checkbox if you want the wizard to add code that initializes the BOA (Basic Object Adapter).

Add IDL Files

List the IDL files that your client project uses. These include the interfaces for CORBA objects that your client application calls. If you do not include any IDL files, you must add a client unit (which was generated when an IDL file was compiled) to your project.

Add Button	Allows you to browse for IDL files.

Remove Button	Removes an IDL file from the list.

When you choose OK, the CORBA Client Wizard creates a new client project of the specified type, adding the CORBA libraries to the project file and adding startup code to initialize the ORB (Object Request Broker) and, if requested, the BOA (Basic Object Adaptor).


Add Included IDL Files

See also

When you compile an IDL file that has an #include statement, the included IDL file is not compiled as well. Because the #include statement generates an #include for the header (.hh) file associated with the included IDL file, your project must contain one of the following in order to compile and link successfully:

The included IDL file.

The header compiled from the IDL file. If the header file contains more than type definitions, you must also include the .cpp, .obj, or .lib file containing any implementations declared in that header file.

The Add Included IDL Files dialog appears when you add an IDL file with an #include statement that includes one or more IDL files that are not part of your project. You can use this dialog to add these files to your project automatically.

In the list of implicitly included IDL files, deselect any files that you do not want added to the project. For any files that are not selected, you must manually add header and implementation files.

If you do not want to add any of the listed IDL files to your project, click the Cancel button. The IDL file you explicitly added is still part of your project but no additional files are added.

If you do not want C++Builder to ever add any implicitly included IDL files, check the box that says “Do not show this dialog again”. You can reenable this feature using the CORBA page of the Environment Options dialog.


CORBA Object Implementation wizard

See also

Use the CORBA Object Implementation wizard to create a server object that can be accessed remotely by CORBA clients.

To bring up the CORBA Object Implementation wizard:

1. Choose File|New to open the New Items dialog box.

2. Choose the tab labeled Multitier.

3. Select the CORBA Object Implementation item in the list view.

Note:	The CORBA Object Implementation wizard will not appear if the project’s IDL files contain compile errors. If there are no IDL files in the project, C++Builder prompts you to add one.

The CORBA Object Implementation wizard Options

IDL Interface

IDL File	Choose the IDL file that contains the interface you want to implement. Click the drop-down arrow for a list of all IDL files contained in the project. If the desired IDL file is not already in the project, click the ellipses button to browse for the desired file. The Wizard will add this IDL file to your project.

Interface Name	Select the interface for which you are creating an implementation. This interface must be in the IDL file specified in the IDL File control.

Implementation Class

Unit Name	Enter the name of the unit that will contain the new implementation class for your CORBA object. You can enter a new unit name or choose an existing unit.

Class name	Enter the name of class that will implement the interface specified by Interface Name.

Delegation (Tie)	Check Delegation (Tie) if you don’t want the implementation class to be a descendant of the skeleton class. If you choose to use the delegation model, you must also check the compiler option for generating Tie classes on the CORBA page of the project options dialog.

Data Module	Check Data Module if you are using the delegation model and you want your implementation class to be a descendant of TDataModule. When you check Data Module, the Wizard adds a data module descendant to your project into which you can visually place components that you want to use when implementing the CORBA object.

Note: To use a data module (or any other VCL object) as a base class, you must specify Enable VCL in the Corba Server Wizard and you must use delegation (VCL classes do not support multiple inheritance).

Instantiation

In main()	Check the box labeled Instantiate In main() if you want the Wizard to add code that instantiates your CORBA object at startup. Clients can bind to objects that are instantiated at startup. If the object is not instantiated at startup, you must provide a mechanism that can return instances of the object to client applications (such as a factory object or other interface that returns a reference to an object instance).

Object Names	If you want clients to bind to your CORBA object, you must provide an Object Name for the object instance. This name is passed to the object’s constructor and specified by clients when binding to the object. You can enter multiple names in the Object Names edit box, separated by semicolons. The Wizard creates a separate instance for each name in the list. You can click the elipses button next to the edit box to use the List entry dialog to insert or modify the list of names.

Show Updates

Check the box labeled Show Updates to view and edit all changes introduced by the CORBA Object wizard. If you check Show Updates, you will see the Project Updates dialog when you click OK.


Preview changes dialog
Project Updates dialog

See also

Use the Project updates dialog to view and modify changes that are created automatically by any of the CORBA wizards or when you choose Edit|CORBA Refresh.

Changes List

Along the left side of the dialog, you see a list of changes, in order, that will be made to your project. You can check or uncheck the box next to each change to include or exclude the changes to that file. If you uncheck a change on which later changes depend (for example the creation of a file to which later changes add code), the later changes are automatically unchecked.

Details Pages

On the right side of the dialog, you see a set of one or more tabbed pages that display all the changes that will be added to implement the currently selected change. Each tabbed page reflects a different file that must be changed, and contains an edit control that you can use to edit the automatically generated code. When you click OK, the changes in this edit window, including any modifications you make within the dialog, are added for every update checked in the Changes List.

If an update consists of new code that is added to a file, the Details page shows a single edit control that displays the new code. If the update modifies existing code, the Details page shows two text windows: the first is the new code that reflects the modifications, and the second shows the original code that has been changed.

File Name

Below the Details Pane is the name of the file that will be created or changed. This value reflects the current tabbed page of detail information.

Show Changes

Show Changes indicates whether this dialog should appear the next time you use a CORBA wizard or the CORBA Refresh command. You can re-enable this dialog by checking the Show Changes checkbox in a CORBA wizard, or by using the check box in the CORBA page of the Environment Options dialog.


Project page

If a project is open, the New Items dialog box includes a project page with the same name as the current project. The current project page contains all the forms of the project. You can create an inherited form from any existing project forms.

For information about including these forms in your projects, see Including objects from the Object Repository.


Dialog wizard

Use the Dialog wizard to design a dialog box for your application.

To display this wizard, choose File|New to display the Object Repository. Click the Dialogs tab and select Dialog wizard.

Follow the instructions in the wizard and click Next. Once you get to the last screen, click Finish. The wizard then creates the dialog box form. You can modify the form to customize it further if needed.

The wizard prompts you to select the type of dialog box (single or multi-page) and the button placement for the standard OK, Cancel, and Help buttons.


Automation Object Wizard

See also

Use the Automation Object Wizard to create an Automation server.

To bring up the Automation Object Wizard:

1. Choose File|New to open the New Items dialog box.

2. Choose the tab labeled ActiveX.

3. Select the Automation Object icon.

In the Wizard, you can specify the following:

CoClassName

Specify the class whose properties and methods you want to expose as an Automation object.

Threading Model

Indicate how client applications can call your object’s interface. This is the threading model that you commit to implementing in the Automation object. Automation Objects can have one of the following:

Single	Your code has no thread support. Only one client thread can be serviced at a time.

Apartment	Clients can call the object’s methods only from the thread on which the object was created. Different objects from the same server can be called on different threads, but each object is called only from that one thread.

Free	Your code is fully thread-safe. Objects can handle any number of threads at any time.

Both	Your server supports clients that use either the Apartment or Free threading model.

Note: The threading model you choose determines how the object is registered. You must make sure that your object implementation adheres to the model selected.

Description

Enter a description string that appears in the type library for the object.

Generate Event support code

Check this box to tell the wizard to implement a separate interface for managing events of your Automation object.

This option makes the user’s object derive from template TEvents_CoClassName(TEvents_Printing<class name>) which implements functions to fire each event. The functions are always named Fire_EventName.

When you complete this procedure, a new unit is added to the current project that contains the definition for the Automation object. In addition, the wizard adds a type library project and opens the type library. Now you can expose the properties and methods of the interface through the type library editor.


Help menu

Use the Help menu to access the online Help system, which is displayed in a special Help window.

The Help system provides information on virtually all aspects of the C++Builder environment and libraries.

Help options	Description

Contents	Display a master table of contents for the available C++Builder help files.

Index	Opens the Help Topics dialog with the Index tab selected.

Inprise Home Page	Opens your Web browser and points it to Inprise World Wide Web site.

C++Builder Home Page	Opens your Web browser and points it to the C++Builder Web page where you can find information about C++Builder, including news and announcements, feature descriptions, and product downloads.

Inprise Programs and Services	A direct link to the Programs and Services page on Inprise’s World Wide Web site. Provides information about educational, consulting, technical support, and other services offered by Inprise.

C++Builder Direct	A direct link to the C++Builder web page where you can find out more about downloading software that will automatically inform you of C++Builder and Inprise news and announcements.

Customize	Launches OpenHelp, a utility that lets you configure which help topics you want available in the help contents and index.

About	Shows copyright and version information for C++Builder.


Help|Contents

Choose Help|Contents to display the Help Topics dialog box.

To find a topic in Help,

Click the Contents tab to browse through topics by category.

Click the Index tab to see a list of index entries: either type the word you're looking for or scroll through the list.

Click the Find tab to search for words or phrases that may be contained in a Help topic.


Help| Index command
Help|Index

Choose Help|Index to get

help about the selected term.

a list of available topics when there are multiple topics to choose from.

a dialog displaying the closest match if no related topics are found.

You can get Help this way for most language elements such as

reserved words

global variables

functions in the runtime, class, and Visual Component Library.

Windows API.

  You can also start a keyword search in the Code editor: Place the insertion point on or next to a term (such as a class, function, member, or property) or highlight one or more terms and press F1.


Help|Inprise Home Page

Choose Help|Inprise Home Page to open your web browser and point it to Inprise’s World Wide Web page.


Help|C++Builder Home Page

Choose Help|C++Builder Home Page to open your web browser and display Inprise’s C++Builder home page.


Help|Inprise Programs and Services

Choose Help|Inprise Programs and Services to open your Web browser and point it to Inprise’s Programs and Services World-Wide Web page. It provides information about educational, consulting, technical support, and other services offered by Inprise.


Help|C++Builder Direct

A direct link to the C++Builder web page where you can find out more about downloading software that will automatically inform you of C++Builder and Inprise news and announcements.


Help|Customize

Choose Help|Customize to lauch the OpenHelp utility.

With OpenHelp, you can add or remove help files from C++Builder. This allows you to limit the number of files listed in the Contents and Index.

By default, C++Builder is configured with all the help files contained in its help directory.

  If you configure OpenHelp with additional help files, you may exceed the capacity of the Index.


Help|About

Choose Help|About to display the About C++Builder dialog box that shows copyright and version information.


Project menu

Use the Project menu to compile or build your application. You must have a project open.

Add To Project	Add a file to a project.

Remove From Project	Remove a file from a project.

Import Type Library	Import a type library to a project.

Add To Repository	Add a project to the Object Repository.

View Source	Display the project file in the Code editor.

View Makefile	Open the project .BPR file in the Code editor

Add New Project	Open the New Items dialog box, which contains wizards and objects that are stored in the Object Repository. You can either generate a new object or start with any preexisting object stored in the Object Repository.

Add Existing Project	Use the Open Project dialog box to add an existing project (.BPR file) to the project manager.

Compile Unit	Compile any source code that has changed since the last compile.

Make project	Compile only those files in the current project that have changed since it was last built.

Build project	Compile everything in the project, regardless of whether any source has changed.

Information for project	Displays all the build information and build status for your project.

Compile All Projects	Compile any source code that has changed since the last compile in all projects in the project group.

Build All Projects	Compile everything in the project group, regardless of whether the source has changed.

Web Deployment Options	Make necessary settings to deploy a finished ActiveX control or ActiveForm.

Web Deploy	After setting the web deployment options and compiling the project, deploy your finished ActiveX control or ActiveForm.

Options	Display the Project Options dialog box, where you set options for compiling, linking, default forms, version information, and so forth.


Project|Add to Project

See also

Choose Project|Add to Project to open the Add To Project dialog box.

Add To Project dialog box

Use the Add To Project dialog box to add an existing unit and its associated form to the C++Builder project. When you add a unit to a project, C++Builder automatically references that unit by adding an #include statement to the project .BPR file.

Look In	Select the drive or directory in which to look for files to add to the project. The File window displays the subdirectories of the current drive or directory, as well as all the files that match the filter specified in the Files of Type combo box.

File Window	Displays the subdirectories of the current directory as well as the files in the current directory that match the current filter. Select a file to add to the project by clicking with the mouse or using the arrow keys. Right-click on the files to bring up a context menu.

File Name	Enter the name of the file you want to add to the project, or a filter expression to limit the files that appear in the file window.

Files of Type	See "Look In" above.

Up One Level	Click this button to move up a level from the current directory.

Create New Folder	Click this button to create a new subdirectory in the current directory.

List	Click this button to display the files as a list of files with associated icons.

Details	Click this button to display files in a tabular format that includes detailed information about each file's size, type, time stamp, and other attributes.


Project|Remove From Project

See also

Choose File|Remove From Project remove a unit from the current project.

Remove From Project dialog box

Use this dialog box to select one or more units to remove from the current project. When you select a unit and click OK, C++Builder removes the selected unit (.CPP file and header) from the current project file but does not delete any files from your disk. If you have manually-coded references to the unit in your source code, you must manually remove those references. Use the Ctrl or Shift key to select more than one unit.

If you have modified the file you are removing during this editing session, C++Builder prompts you to save your changes, to preserve the unit in another project. If you have not modified the file, C++Builder removes that file from the project without prompting you.

Caution:	Remove the file from your project first before deleting the file from disk so that C++Builder can update project file accordingly.


Import Type Library
Project|Import Type Library

See also

The Import Type Library dialog box displays the type libraries registered on your system so you can add them to your projects. You can generate C++ declarations in a .CPP file that let you use these types as though they were native VCL objects. In effect, the type library is placed within a VCL wrapper.

The top part of the dialog is a list of type libraries that are currently registered and thus available to be imported. This list lets you extract the declarations from an existing control or free-standing type library. You can also conveniently register a new type library from this dialog box so that it is available to be imported.

To add and register a new type library:

1.	Click Add. The Register OLE Control dialog box appears.

2.	In the Register OLE Control dialog box, navigate to the disk or network location of the library file you want to add.

3.	Select the new type library. It is automatically registered on your system for C++Builder and immediately appears in the list of available libraries in the Import Type Library dialog.

Add button 	Locate a new type library and register it in the Windows Registry, so that it will appear in the list of registered objects available to be imported into C++Builder.

Remove button 	Remove a registered type library. The library is removed from the Windows Registry and from this list.

Class names 	Shows only the control classes in the selected library.

Unit dir name 	Shows the name of the directory that contains the unit (module) using this library. Only the path root is shown; no file name appears. The unit name is derived from the internal type library name. Click the Browse button to move up the directory tree.

The Import type library is one way to create an Automation controller.


Add To Repository
Project|Add To Repository

See also

Choose Project|Add To Repository to open the Add to Repository dialog box. Use this command to add projects, units, and forms to the Object Repository.

By adding your own projects, units, and forms to those already available in the Object Repository, you can share objects across your organization. This is helpful in situations where you want to enforce a standard framework for programming projects.


Save Project Template dialog box

Use this dialog box to save a project template to the Object Repository. After saving an application as a template, use the Edit Object Info dialog box to edit the description, delete the template, or change the icon.

Dialog box options

Title	Enter the name of the template. This is the full path of the object you are adding. The maximum length for a title is 40 characters.

Description	Enter a description of the template. The description appears under the template name on the Select Template dialog box. The maximum length for a description is 255 characters.

Page	From the drop down list box, choose the name of the page (probably Projects) on which you want the template to appear.

Author	Enter text identifying the author of the application. Author information appears only when you select View Details form the context menu.

Template Icon	Click the Browse button to open the Select Icon dialog. You can use a bitmap of any size, but it will be cropped to 60 x 40 pixels.


Project|View Source

See also

Use Project|View Source to display the project file for the current project and make it the active page in the Code editor. If the project source file is not currently open when you choose this command, C++Builder opens it for you.


View|Project Makefile
Project|View Makefile

See also

Choose Project|View Makefile to open and display the project makefile (.BPR) file for the current project in the Code editor. If the BPR file is not currently open when you choose this command, C++Builder opens it for you.


Project|Add New Project

Use Project|Add New Project to add a new item (such as a new application, DLL, or package) to the project group. This command opens the New Items dialog box to create a new target from the templates provided in the Object Repository.

Typically, a project group consists of at least one project, which contains the source of your application. You can choose to add additional projects to a project group to contain other targets associated with your application. For example, you may have one project for your .EXE, another for your .DLL, and another for your application resources.

This command works the same as in the Project Manager, selecting a project group, right clicking, and choosing Add New Project.

For details on project groups, see creating a project group.


Project|Add Existing Project

Choose Project|Add Existing Project to add an existing project to the current project group. This command opens the Open dialog box for you to specify the path to the project that you want to add to this project group.

Typically, a project group consists of at least one project, which contains the source of your application. You can choose to add additional projects to a project group to contain other targets associated with your application. For example, you may have one project for your .EXE, another for your .DLL, and another for your application resources.

This command works the same as in the Project Manager, selecting a project group, right clicking, and choosing Project|Add Existing Project.

For details on project groups, see creating a project group.


Project|Create New Target
Create New Target

Choose Create New Target from the Project Manager context menu to add a new target to the current Project Group. This command opens the New Items dialog box to create a new target from the templates provided in the Object Repository.

Typically, a Project Group consists of at least one project, which contains the source of your application. You can choose to add additional projects to a Project Group to contain other targets associated with your application. For example, you may have one project for your .EXE, another for your .DLL, and another for your application resources.

This command works the same as Project|Add New Project.


Project|Open New Target
Open New Target

Choose Open New Target from the Project Manager context menu to add an existing project to the current Project Group. This command opens the Open dialog box for you to specify the path to the project that you want to add to this Project Group.

Typically, a Project Group consists of at least one project, which contains the source of your application. You can choose to add additional projects to a Project Group to contain other targets associated with your application. For example, you may have one project for your .EXE, another for your .DLL, and another for your application resources.

This command works the same as Project|Add Existing Project.


Project|Compile Unit

See also

Use this command to compile a single unit in your project. To do so:

1.	Select the unit that you want to compile in the Code editor or Project Manager window.

2.	Choose Project|Compile Unit.

The hourglass cursor appears (or the Progress dialog box displays if you checked Show Compiler Progress on the Preferences page on the Tools|Environment Options dialog box) and indicates that a compile is in progress. The cursor returns to normal if the compiler finds no errors.

If an error is found when the Code editor is not open, the Message window displays an error message. If you double-click the message, the Code editor displays the source file positioned at the line where the error occurred.

If an error is found when the Code editor is open, then the Code editor window comes to the front, highlighting the line that contains the error.

The Code editor message pane displays the error message.

Press F1 to get help regarding the error message.


Project|Make project

See also

Use Project|Make project to compile all files in the current project that have changed since the last build into a new executable file (.EXE),. dynamic link library (.DLL), resource file (.RES), or so on. This command is similar to the Build command, except that Project|Make builds only those files that have changed since the last compile, whereas Build rebuilds all files whether they have changed or not.

When you choose this command

The compiler compiles source code for each unit if the source code has changed since the last time the unit was compiled.

If a unit contains an include (.H) file, and the include file is newer than the unit’s .OBJ file, the unit is recompiled.

Once all the units that make up the project have been compiled, C++Builder links them into an executable file (or dynamic link library). This file is given an .EXE (or .DLL) file extension and the same file name as the project source code file. This file now contains all the compiled code and forms found in the individual units, and the program is ready to run.

If you checked Show Compiler Progress from the Preferences page on the Tools|Environment Options dialog box, the Progress dialog box displays information about the compilation progress and results. When your application successfully compiles, choose OK to close the Progress dialog box.

You can also invoke this command from the Project Manager. Right click and choose Make.

If you have multiple projects within a Project Group, you can make all projects within a Project Group by using the Project|Make All Projects command.


Project|Build project

See also

Choose Project|Build project to rebuild all the components of a project regardless of whether they have changed. This command is useful when you’ve changed global compiler directives or compiler options, to ensure that all code compiles in the proper state.

This option is identical to Project|Make project except that it rebuilds everything, whereas Project|Make rebuilds only those files that have changed since the last build. When you choose Build project, precompiled headers and files generated by the incremental linker are deleted and regenerated.

You can also invoke this command from the Project Manager. Right click and choose Build.

If you have multiple projects within a Project Group, you can build all projects within a Project Group by using the Project|Build All Projects command.


Project|Information for project

Choose Project|Information for project to open the Information dialog box.

Information dialog box

Use this dialog box to view the program compilation information and compilation status for your project.

Program Information

The Program Information options provide you with information about your project.

Options	What it lists

Source Compiled	Total number of lines compiled

Code Size	Total size of the executable or DLL without debug information

Data Size	Memory needed to store the global variables

Initial Stack Size	Memory needed to store the local variables

File size	Size of final output file.

Status Information

The Status Information line displays whether or not your last compile succeeded or failed.


Project|Compile All Projects

See also

Use Project|Compile All Projects to compile all files in the current project group that have changed since the last build. This command is similar to Project|Build All Projects, except that Project|Compile All Projects builds only those files that have changed since the last compile, whereas Project|Build All Projects rebuilds all files.

The Project|Compile All Projects command recompiles changed files from top to bottom as they are listed in the Project Manager. (For example, if a project group includes a DLL on which the executable file depends, list the DLL first to compile most effectively.)

If you checked Show Compiler Progress from the Preferences page of the Tools|Environment Options dialog box, the Progress dialog box displays information about the compilation progress and results. When your application successfully compiles, choose OK to close the Progress dialog box.

To compile a single project within a Project Group, choose Project|Make.


Project|Build All Projects

See also

Choose Project|Build All Projects to rebuild all the projects in your Project Group regardless of whether they have changed. This command is useful when you’ve changed global compiler directives or compiler options, to ensure that all code compiles in the proper state.

This option is identical to Project|Compile All Projects except that it rebuilds everything, whereas Project|Compile All Projects rebuilds only those files that have changed since the last build. When you choose Build All Projects, precompiled headers and files generated by the incremental linker are deleted and regenerated.

The Project|Build All Projects command recompiles all files included in the project group from top to bottom as they are listed in the Project Manager. Be sure to list projects in the order you want them compiled. You can reorder projects within a project group by right-clicking in the Project Manager with a project selected and choosing Build Sooner or Build Later.

To build a single project within a Project Group, choose Project|Build.


Project|Web Deployment Options

Choose Project| Web Deployment Options to configure a finished ActiveX control or ActiveForm for deployment to your Web server.  First, set web deployment options, compile the project, then choose Project|Web Deploy to deploy the current ActiveX project.

See Deploying ActiveX controls or ActiveForms on the Web

Default checkbox	If checked, saves the current settings from the dialog box’s Project, Packages, Additional Files, and Code Signing pages as the default options. To restore the default properties to the original state, delete default.bpr from your bin directory.

The Web Deployment Options dialog box contains four tabbed pages of settings:

Project page

Specifies locations of files and the URL.  Also, allows you to set configuration settings for CAB file compression.

Packages Page	Specifies packages used by this project

Additional Files Page	Specifies other files associated with this project.

Code Signing Page	Lets end users view information about the control such as its author, company URL, and whether the control has been modified since it was signed by the author.


Project|Web Deploy

Choose Project|Web Deploy to deploy a finished ActiveX control or ActiveForm to your web server. Use this command only after setting the Web Deployment Options and then compiling your project.

The ActiveX library (.OCX) is placed in the target directory specified in the Web deployment options. An HTML file (.HTM) that contains a URL reference to the ActiveX library in the target directory is created in the HTML directory specified in the Web Deployment options. When this HTML file is viewed in a Web browser, your ActiveX control or ActiveForm runs as an embedded application within the browser.

See also, Deploying ActiveX controls or ActiveForms on the Web.


Project|Options

See also

Choose Project|Options to display the Project Options dialog box. Use the pages of this dialog box to specify form, application, compiler, and linker options for your project, and to manage project directories. You can change the options of the current project, or the default properties for new projects. If there is no project currently open, you can only change the default properties.

The pages of the Project Options dialog box are:

Forms	Controls which forms are created automatically

Application	Specifies the title, help file name, and icon name associated with the application

Compiler	Specifies the general options for the C++ compiler switches that detemine how code is compiled

Advanced Compiler	Specifies additional options for the C++ compiler

C++	Specifies C++ language-specific compiler options

Pascal	Specifies Object Pascal compiler options

Linker	Manages how your program files are linked

Directories/Conditionals	Specifies the location of files needed to compile and link your program

VersionInfo	Specifies the types of product identification information

Packages	Specifies the design-time and runtime packages to install for your project

ATL	Specifies options for ATL calls in projects that contain COM servers. This page does not appear unless the project implements an ActiveX control or OLE automation object.

TLIB	Specifies options for a static library. This page appears only for projects that are library.

Tasm	Sets the parameters and scope for the turbo assembler.

CORBA	Controls how IDL files are compiled into .CPP files containing stub and skeleton classes and how CORBA libraries are linked to the project.

Tabs

You can change the page displayed by clicking the tabs at the top of the dialog box.

Default check box	saves the current settings as the default for each new project.

C++ Compiler Options and VCL Applications

Three pages provide all of the possible options for setting compiler switches:

Compiler dialog

Advanced Compiler dialog

C++ dialog

You can safely modify some compiler options to customize the compilation of any application. Use the Compiler page to adjust the basic compiler options.

However, other compiler options default to settings that are necessary to build VCL applications. You can reset these options, but you risk compilability with VCL libraries. Use the Advanced Compiler page and the C++ page to manipulate these options.


Default checkbox
Default checkbox (Project|Options) or (Project|Web Deployment Options)

See also

Both the Project Options and the Web Deployment Options dialog boxes have a checkbox in the lower left- corner labeled Default.  Checking this box saves the settings selected in the dialog as the default settings for every new project you create.

This check box is disabled if there is no current project open, because in that case you can only change the default properties.

To restore the default properties to the original state, delete default.bpr (or default.bpk for package projects) from your bin directory.


Project|Options - Forms
Forms (Project|Options)

See also

Use the Forms page of the Project Options dialog box to select the main form for your current project and to choose which of the available forms are automatically created when your application begins.

Main Form	Displays the form users see when they start your application. Use the drop-down list to select which form is the main form for the project. The main form is the first form listed in the Auto-Create Forms list box.

Auto-Create Forms	Lists forms that are automatically added to the startup code of the project file and created at runtime. These forms are automatically created and displayed when you first run your application. You can rearrange the create order of forms by dragging and dropping forms to a new location. To select multiple forms, hold down the Shift key while selecting the form names.

Available Forms	Lists those forms that are used by your application but are not automatically created. If you want to create an instance of one of these forms, you must call its Create method.

Arrow buttons	Use the arrow buttons to move files from one list box to the other.

To move all the files from one list box into the other:

Click the double arrow buttons ( >> or << ).

Drag and drop the files from one list box into the other.

To move only the selected file or files from one list box into the other:

Click the single arrow buttons ( > or < ).

Drag and drop the file from one list box into the other.

Default check box

Check Default to save the current settings in all the Project Options pages as the default options. C++Builder will use the default options for each new project you create.


Project|Options - Application
Application (Project|Options)

See also

Use the Application page of the Project Options dialog box to specify a title, a Help file, an icon, and an extension for your application.

Application Settings

Title	Specify a title to appear under the application's icon when the application is minimized. The character limit is 255 characters.

Help File	Specify the name of the Help file (.HLP) your application automatically calls when invoking Help. The Help file name is passed to the WinHelp function call. If you are unsure of the Help file name, you can click the Browse button to display the Application Help File dialog box.

Icon	Displays the icon file (.ICO) that will represent the application in the Program Manager and when the application is minimized.  To change the icon, click Load Icon and C++Builder displays the Application Icon dialog box, where you can select an icon.

Output Setting

Target file extension	Specify the file extension to be used for the target executable file. If the project is an ActiveX application or DLL the standard file extension can be specified, such as .ocx for an ActiveX file.

Default check box

Check Default to save the current settings in all the Project Options pages as the default options. Every new project will use the default options.


Application Icon dialog box

Use the Application Icon dialog box to select an icon that represents your application in the Program Manager and when your application is minimized.

To display this dialog box:

Select Project|Options, select the Application page of the Project Options dialog box, and click Load Icon.

File Name	Enter the name of the file you want to use, or enter or wildcards to use as filters in the Files window.

Files	Displays subdirectories of the current directory as well as all files in the current directory that match the filter in the File Name edit box or the file type in the Files Of Type combo box. Select an icon file for your application's icon using the mouse or arrow keys. Right-click on a file to bring up a context menu.

Files Of Type	Choose the type of file you want to use; the default file type is an icon (.ICO). All files in the current directory of the selected type appear in the Files list box.

Look In	Select the drive or directory in which to look for the icon file. The Files window displays the subdirectories of the current drive or directory as well as all files that match the current filter.


Application Help File dialog box

Use the Application Help File dialog box to select a Help file (.HLP) to use as the Help file for your application. The Help file you specify here is entered into the Help File edit box on the Applicaton page of the Project Options dialog box.

To display this dialog box:

Select Project|Options, select the Application page and click Browse

File Name	Enter the name of the file you want to use, or enter or wildcards to use as filters in the Files window.

Files Window	Displays all subdirectories in the current directory as well as files in the current directory that match the filter in the File Name edit box or the file type in the Files Of Type combo box. Select a Help file for your application using the mouse or arrow keys. Right-click on a file to bring up a context menu.

Files Of Type	Choose the type of file you want to use; the default file type is a Help file (.HLP). All files in the current directory of the selected type appear in the Files list box.

Look In	Select the drive or directory in which to look for the Help file. The Files window displays the subdirectories of the current drive or directory as well as all files that match the current filter.


Project|Options - Compiler
Compiler (Project|Options)

See also

Use the Compiler page of the Project Options dialog box to set options for how you want your program to compile.

The Compiler page has the following option groups:

Option group	Option types

Speed settings	enable aggregate sets of compiler and linker options for developing or releasing your application

Code optimizations	enable aggregate sets of optimization options

Warnings	enable/disable the warning messages

Debugging	determines the type of debugging information generated when you compile your code

Pre-compiled headers	set the use of pre-compiled headers

Compiling	sets general C++Builder compiler behavior

Default check box

Check Default to save the current project options so that every new project you create will use those options.

C++ Compiler Options and VCL Applications

Three pages provide all of the possible options for setting compiler switches:

Compiler dialog

Advanced Compiler dialog

C++ dialog

You can safely modify some compiler options to customize the compilation of any application. Use the Compiler page to adjust the basic compiler options.

However, other compiler options default to settings that are necessary to build VCL applications. You can reset these options, but you risk losing the ability to compile with VCL libraries. Use the Advanced Compiler page and the C++ page to manipulate these options.


Speed settings (Compiler options)

See also

The Speed Setting buttons enable an aggregate set of compiler and linker options for standard applications (these buttons do not affect compiling ActiveX/Ole applications). If you use these speed setting options, you shouldn’t need to use the individual option settings on the Compiler, Advanced Compiler, Pascal, Linker, and Tasm pages of the Project Options dialog box. However, you may set those individual Project|Options options which are not affected by the either the Full debug or the Release buttons. The following lists which options are reset if you click the Speed settings buttons.

Full debug lets you set the recommended set of options to use while you are developing your application. The Full Debug button sets the following options:

Compiler options

Enables Code optimizations|None

Enables Debugging|Debug information

Enables Debugging|Line number information

Enables Debugging|Disable inline expansions

Enables Compiling|Stack frames

Advanced Compiler options

Enables Register Values|None

Pascal options

Disables Code generation|Optimization

Enables Code generation|Stack frames

Enables Debugging|Debug information

Enables Debugging|Local symbols

Enables Debugging|Symbol info

Linker options

Enables Linking|Include debug information

Tasm options

Enables Debug Information|Full

Release sets the compiler and linker options that you should use when you have finished developing and debugging your application. The Release button sets the following options (this button reverses the settings made by the Full Debug button):

Compiler options

Enables Code optimizations|Speed with scheduling

Disables Debugging|Debug information

Disables Debugging|Line number information

Disables Debugging|Disable inline expansions

Disables Compiling|Stack frames

Advanced Compiler options

Enables Register Variables|Automatic

Pascal options

Enables Code generation|Optimization

Disables Code generation|Stack frames

Disables Debugging|Debug information

Disables Debugging|Local symbols

Disables Debugging|Symbol info

Linker options

Disables Linking|Include debug information

Tasm options

Enables Debug Information|None


Code optimizations (Compiler options)
Code optimization (Compiler options)

See also

The Code Optimization settings enable an aggregate set of compiler options.

Default = None

None turns off all code optimizations. This is normally the best optimization to use when you are developing and debugging your application-the debugger will not skip around due to code that has been “optimized away” by the compiler.

Speed sets the following compiler switches designed to optimize your code for speed:

Inline intrinsic functions, which generates the code for common memory functions like strcpy() within the calling function’s scope, eliminating the need for a separate function call. The resulting code executes faster, but is larger.
(-Oi commandline switch)

Induction variables, which optimize code containing loops
(-Ov commandline switch)

Optimize common subexpressions, which eliminates duplicating common subexpressions within an entire function. This eliminates duplicate expressions throughout the target scope and stores the calculated value of those expressions once (instead of recalculating the expression).
(-Oi commandline switch)

Although this optimization could theoretically reduce code size, it optimizes for speed and rarely results in size reductions. Use this option if you prefer to reuse expressions rather than create explicit stack locations for them.

Selected allows you to select one or more of the speed optimizations and to enable Pentium scheduling. Select the Selected radio button and then click on the Optimizations button to display the Optimizations  dialog box.


Optimizations dialog box

You can selectively specify from among an aggregate of compiler switches designed to optimize your code for speed, along with code that is optimized for Pentium processors (do not use this setting if you plan to use your application on systems with processors less than a Pentium).

Pentium scheduling rearranges instructions to minimize delays that can be caused by Address Generation Interlocks (AGI) which occur on the i486 and Pentium processors. This option also optimizes the code so that it takes advantage of the Pentium parallel pipelines
(-OS commandline switch)

Scheduled code is more difficult to debug at the source level because instructions from a particular source line may be mixed with instructions from other source lines. Stepping through the source code is still possible, although the execution point might make unexpected jumps between source lines as you step. Also, setting a breakpoint on a source line may result in several breakpoints being set in the code. This is especially important to note when inspecting variables, since a variable may be undefined even though the execution point is positioned after the variable assignment.

Inline intrinsic functions generates the code for common memory functions like strcpy() within the calling function’s scope, eliminating the need for a separate function call
(-Oi) commandline switch)

Induction variables optimize code containing loops
(-Ov commandline switch)

Optimize common subexpressions eliminates duplicating common subexpressions within an entire function
(-Og commandline switch)

Defaults button restores all optimizations to their default state.


Warnings (Compiler options)

See also

The Warnings compiler options enable/disable which messages the compiler displays when a warning condition occurs.

Default = All

None diables all warning messages

All enables all potential warning messages

Selected allows you to select one-or-more warning messages. Select the Selected radio button and then click on the Warnings button.


Compiler Warnings dialog box
Compiler Warnings dialog box (Compiler options)

See also

This dialog box lets you select which compiler warnings you want to view when compiling a project. Click on the warnings that you want to display. Selecting Default sets all the warnings back to the compiler defaults. For a list of compiler defaults, see Message options.

Note	 When you select Default, two warnings that are normally turned off for VCL applications are turned on. These options are -wpar (Parameter ‘parameter’ is never used) and -winl (Functions containing reserved words are not expanded inline).

You can look up detailed descriptions of the messages in the alphabetical list of errors and warnings.


Debugging (Compiler options)

See also

The debugging options let you generate different types of debugging information when you compile your code. When linking larger .OBJ files, you may need to turn these options off to increase the available system resources. Remember to review these options before your final build of the project.

Default = all three selected

Debug information adds debug information to your compiled .OBJ files.

Line number information adds line numbers to your .OBJ files.

Disable inline expansions causes the compiler to expand C++ inline functions inline. See Out-of-line Inline Functions for more information.

To have debug information added to your final executable file, you must also check Include Debug Information on the Linker page of the Project Options dialog.


Pre-compiled headers (Compiler options)

See also

This section contains the general-use pre-compiled heading options. Pre-compiled headers can dramatically increase compilation speeds, although they require a considerable amount of disk space. Pre-compiled headers increase compilation speeds by storing an image of the symbol table on disk in a file, then later reloading that file from disk instead of parsing all the header files again. Directly loading the symbol table from disk is much faster than parsing the text of header files, especially if several source files include the same header file.

Default = Cache pre-compiled headers

None does not generate pre-compiled headers.

Use pre-compiled headers causes the compiler to generate and use pre-compiled headers. The default file name is VCL.CSM for C++Builder projects.

Cache pre-compiled headers causes the compiler to cache the pre-compiled headers it generates. This is useful when you are pre-compiling more than one header file.

File Name lets you specify the name of your pre-compiled header file. The compilers set the name of the precompiled header to the filename you enter. Select either the Use pre-compiled headers radio button or the Cache pre-compiled headers radio button to enable this text box.
Default = $(BCB)\lib\vcld.csm

Stop After terminates compiling the pre-compiled header after the compiler compiles the file specified as the filename you enter. You can use this option to reduce the amount of disk space used by pre-compiled headers. Select either the Use pre-compiled headers radio button or the Cache pre-compiled headers radio button to enable this text box.

When you use this option, the file you specify must be included from a source file for the compiler to generate a .CSM file.

You cannot specify a header file that is included from another header file. For example, you cannot list a header included by windows.h because this would cause the pre-compiled header file to be closed before the compilation of windows.h was competed.


Compiling (Compiler options)

See also

The Compiling options control general C++Builder compiler behavior. These options reflect what you need to set for most C++Builder applications. If you need to set more advanced compiler options, refer to Advanced Compiler.

Default = Stack frames

Merge duplicate strings causes the compiler to merge two literal strings when one matches another. This produces smaller programs (at the expense of a slightly longer compile time), but can introduce errors if you modify one string.

Stack frames causes the compiler to generate a standard stack frame (standard function entry and exit code). This is helpful when debugging, since it simplifies the process of stepping through the stack of called subroutines.

When this option is off, any function that does not use local variables and has no parameters is compiled with abbreviated entry and return code. This makes the code smaller and faster.

The Standard Stack Frame option should always be on when you compile a source file for debugging.

Show general msgs shows general compiler and linker messages (these messages are not warnings or error messages).


Project|Options - AdvancedCompiler
Advanced Compiler (Project|Options)

See also

The Advanced Compiler page of the Project Options dialog box specifies additional options for the C++ compiler (modify only with non-VCL applications). The default settings on this page are necessary to build VCL applications.

The Advanced Compiler page has the following option groups:

Option group	Option types

Instruction Set	determines the specific architecture targeted by the compilation.

Data Alignment	sets the block-size starting boundaries for storing data in active memory.

Calling Convention	determines which calling sequences to generate for function calls.

Register Variables	requests local variables be stored in registers at runtime.

Output	determines whether to include Makefile information in the generated object files, and whether to prefix function names with an underscore.

Floating Point	enables optimizing performance or precision.

Language Compliance	determines which keywords are recognized in your programs.

Source	enables/disables nested comments, guarantee MFC compatibility, and set the unique length for identifying variables in your code.

Default check box

Check Default to save the current settings in all the Project Options pages as the default options. C++Builder will use the default options for each new project you create.

C++ Compiler Options and VCL Applications

Three pages provide all of the possible options for  setting compiler switches:

Compiler dialog

Advanced Compiler dialog

C++ dialog

You can safely modify some compiler options to customize the compilation of any application. Use the Compiler page to adjust the basic compiler options.

However, other compiler options default to settings which are necessary to build VCL applications. You can reset these options, but you risk compilability with VCL libraries. Use the Advanced Compiler page and the C++ page to manipulate these options.


Instruction Set (Advanced Compiler options)

See also

The Instruction Set options determine the specific architecture targeted by the compilation:

80386

i486

Pentium

Pentium Pro

Default = 80386


Data Alignment (Advanced Compiler options)

See also

The Data Alignment options let you choose how the compiler aligns data in stored memory. Word, double-word, and quad-word alignment force  items to be aligned on memory addresses that are a multiple of the type chosen. Extra bytes are inserted in structures to ensure that members align correctly.

Default = Double Word (32-bit)

Byte aligns to 8-bit boundaries.

Word aligns to 16-bit boundaries.

Double Word aligns to 32-bit boundaries. Data with type sizes of less than 4 byes are aligned on their type size.

Quad Word aligns to 64-bit boundaries. Data with type sizes of less than 8 bytes are aligned on their type size.


Calling Convention (Advanced Compiler options)

See also

The Calling Convention options determine which calling sequences to generate for function calls. The C, Pascal, and Register calling conventions differ in the way each handles stack cleanup, order of parameters, case, and prefix of global identifiers.

Default = C

C tells the compiler to generate a C calling sequence for function calls (generate underbars, case sensitive, push parameters right to left, calling function cleans stack). This is the same as declaring all functions with the _ _cdecl keyword. Functions declared using the C calling convention can take a variable parameter list (the number of parameters does not need to be fixed).

You can use the _ _pascal,  _ _fastcall, or _ _stdcall keywords to specifically declare a function using another calling convention.

Pascal tells the compiler to generate a Pascal calling sequence for function calls (do not generate underbars, all uppercase, pushes parameters left to right). This is the same as declaring all functions with the _ _pascal keyword. The resulting function calls are usually smaller and faster than those made with the C (-pc) calling convention. Functions must pass the correct number and type of arguments.

You can use the _ _cdecl, _ _fastcall, or _ _stdcall keywords to specifically declare a function using another calling convention.

Register forces the compiler to generate all functions using the Register parameter-passing convention, which is equivalent to declaring all functions with the _ _fastcall keyword. With this option enabled, functions or routines expect parameters to be passed in registers where possible.

You can use the _ _pascal, _ _cdecl, or _ _stdcall keywords to specifically declare a function using another calling convention.

Standard Call  tells the compiler to generate a Stdcall calling sequence for function calls (does not generate underscores, preserve case, called function pops the stack, and pushes parameters right to left). This is the same as declaring all functions with the _ _stdcall keyword. Functions must pass the correct number and type of arguments.

You can use the _ _cdecl, _ _pascal, or _ _fastcall keywords to specifically declare a function or subroutine using another calling convention.


Register Variables (Advanced Compiler options)

See also

The Register Variables options determine whether local variables be stored in registers at runtime.

Default = None

None tells the compiler not to use register variables even if you use the register keyword.

Automatic tells the compiler to automatically assign register variables if possible, even when you do not specify a register variable by using the register keyword.

Register Keyword tells the compiler to use register variables only if you use the register keyword and a register is available. Use this option or the Automatic option to optimize the use of registers.

Generally, you can keep this option set to Automatic unless you are interfacing with preexisting assembly code that does not support register variables.


Output (Advanced Compiler options)

See also

The Output options determine whether to include Makefile information in the generated object files, and  whether to prefix function names with an underscore.

Default = Both selected

Autodependency Information automatically checks Makefile dependencies for every target that has a corresponding source file in the project list.

Generate Underscores prefixes function names with an underscore.


Floating Point (Advanced Compiler options)

See also

The Floating Point options enable optimizing performance or precision.

Default = No selections

None indicates that you are not using floating point arithmetic. No floating-point libraries are linked when this option is enabled. If you enable this option and use floating-point calculations in your program, you will get link errors.

Fast allows floating-point operations to be optimized without regard to explicit or implicit type conversions. Calculations can be faster than under ANSI operating mode. When this option is unchecked, the compiler follows strict ANSI rules regarding floating-point conversions.

Correct Pentium FDIV flaw Some early Pentium chips do not perform specific floating-point division calculations with full precision. Although your chances of encountering this problem are slim, this switch inserts code that emulates floating-point division so that you are assured of the correct result. This option decreases your program's FDIV instruction performance.

Use of this option only corrects FDIV instructions in modules that you compile. The run-time library also contains FDIV instructions which are not modified by the use of this switch. To correct the run-time libraries, you must recompile them using this switch.

The following functions use FDIV instructions in assembly language which are not corrected if you use this option:

acos	cosh	pow10l

acosl	coshl	powl

asin	cosl	sin

asinl	exp	sinh

atan	expl	sinhl

atan2	fmod	sinl

atan2l	fmodl	tan

atanl	pow	tanh

cos	pow10	tanhl

tanl

In addition, this switch does not correct functions that convert a floating-point number to or from a string (such as printf or scanf).


Language Compliance (Advanced Compiler options)

See also

The Language Compliance options tell the compiler which C/C++ programming language keywords to use.

Default = Borland

If you get declaration syntax errors from your source code, check that this option is set to Borland (the default).

Borland honors Inprise's extensions to the C language keywords, including near, far, huge, asm, cdecl, pascal, interrupt, _export, _ds, _cs, _ss, _es, and the register pseudovariables (_AX, _BX, and so on). For a complete list of keywords, see the keyword index.

ANSI compiles C and C++ ANSI-compatible code, allowing for maximum portability. Non-ANSI keywords are ignored as keywords.

Unix V recognizes only UNIX V keywords and treat any of Inprise's C++ extension keywords as normal identifiers.

K & R recognize only the K&R extension keywords and treat any of Inprise's C++ extension keywords as normal identifiers.


Source (Advanced Compiler options)

See also

The Source options set source code interpretation.

Default = No selections; Identifier Length = 0

Nested Comments enables nesting comments in your C and C++ source files. Nested comments are not allowed in standard C implementations, and they are not portable.

MFC Compatibility Turn this option on to compile code that is compatible with the Microsoft foundation classes (MFC). Among other things, the compiler makes the following adjustments to be compatible with MFC:

Accepts spurious semicolons in a class scope

Allows anonymous structs

Uses the old-style scoping resolution in for loops

Allows methods to be declared with a calling convention, but leaves off the calling convention in the definition

Tries the operator new if it cannot resolve a call to the operator new[ ]

Lets you omit the operator & on member functions

Allows a const class that is passed by value to be treated as a trivial conversion, not as a user conversion

Allows you to use a cast to a member pointer as a selector for overload resolution, even if the qualifying type of the member pointer is not derived from the class in which the member function is declared

Accepts declarations with duplicate storage in a class, as in

extern "C" typedef

Accepts and ignores #pragma comment(linker, "...") directives

Identifier Length lets you use the Identifier Length input box to specify the number of significant characters (those which will be recognized by the compiler) in an identifier.

Except in C++, which recognizes identifiers of unlimited length, all identifiers are treated as distinct only if their significant characters are distinct. This includes variables, preprocessor macro names, and structure member names.

Valid numbers for n are 0, and 8 to 250, where 0 means use the maximum identifier length of 250.

By default, C++Builder uses 250 characters per identifier. Other systems (including some UNIX compilers) ignore characters beyond the first eight. If you are porting to other environments, you might want to compile your code with a smaller number of significant characters, which helps you locate name conflicts in long identifiers that have been truncated.


Project|Options - C++
C++ (Project|Options)

See also

The C++ page provides C++ language-specific compiler options (modify only with non-VCL applications). The default settings on this page are necessary to build VCL applications.

Member Pointers	determines the storage layout of class members and their inherited members.

Compatibility	provides for backward compatibility with earlier ANSI versions.

Virtual Tables	optimizes the size of virtual function tables.

Templates	controls how the compiler instantiates templates.

Exception Handling	enables/disables exception handling and runtime type information.

General	Set this option to be compatible with objects from libraries that implement empty base classes with zero size.

Default check box

Check Default to save the current C++ options as the default options. C++Builder will use the default options for each new project you create.

C++ Compiler Options and VCL Applications

Three pages provide all of the possible options for  setting compiler switches:

Compiler dialog

Advanced Compiler dialog

C++ dialog

You can safely modify some compiler options to customize the compilation of any application. Use the Compiler page to adjust the basic compiler options.

However, other compiler options default to settings which are necessary to build VCL applications. You can reset these options, but you risk compilability with VCL libraries. Use the Advanced Compiler page and the C++ page to manipulate these options.


Member Pointers (C++ options)

The Member Pointers options determine the storage layout of class member pointers.

Default = All cases

All cases tells the compiler to place no restrictions on where member pointers can point. Member pointers use the most general (but not always the most efficient) representation.

Multiple Inheritance allows member pointers to point to members of multiple inheritance classes (with the exception of virtual base classes).

Single Inheritance restricts member pointers to point only to members of base classes that use single inheritance.

Smallest forces member pointers to use the smallest possible representation that allows member pointers to point to all members of their particular class. If the class is not fully defined at the point where the member pointer type is declared, the most general representation is chosen by the compiler and a warning is issued.

Honor member precision forces the compiler to use the declared precision for member pointer types. Use this option when a pointer to a derived class is explicitly cast as a pointer-to-member of a simpler base class (when the pointer is actually pointing to a derived class member).


Compatibility (C++ options)

The Compatibility options provide for backward compatibility with earlier ANSI versions. This option is provided for backward compatibility only; it lets you compile old library files that you cannot otherwise recompile.

Default = No selections

Don’t restrict for loop scope upgrades the scope of local variables that are declared within a loop by one block level.

No distinct ‘char’ type allows only signed and unsigned char types. The C++Builder compiler allows for signed char, unsigned char, and char data types. This option treats char as signed.

Don’t mangle code modifiers disables the distinction of function names where the only possible difference is incompatible code generation options. For example, with this option enabled, the linker will not detect if a call is made to a _ _fastcall member function with the cdecl calling convention.


Virtual Tables (C++ options)

The Virtual Tables options can optimize the size and performance of virtual function tables.

Default = Smart

Smart generates common C++ virtual tables and out-of-line inline functions across the modules in your application. As a result, only one instance of a given virtual table or out-of-line inline function is included in the program. The Smart option generates the smallest and most efficient executables, but produces .OBJ and .ASM files compatible only with Borland linkers and assemblers.

Local generates local virtual tables (and out-of-line inline functions) so that each module gets its own private copy of each virtual table or inline function it uses. The Local option uses only standard .OBJ and .ASM constructs, but produces larger executables.

External generate external references to virtual tables. If you don’t want to use the Smart or Local options, use the External and Public options to produce and reference global virtual tables. When you use this option, one or more of the modules comprising the program must be compiled with the Public option to supply the definitions for the virtual tables.

Public produces public definitions for virtual tables. When using the External option (-V0), at least one of the modules in the program must be compiled with the Public option to supply the definitions for the virtual tables. All other modules should be compiled with the External option to refer to that Public copy of the virtual tables.


Templates (C++ options)

The Templates option specifies how the compiler generates template instances in C++.

Default = Smart is ON

Smart generates public (global) definitions for all template instances. If more than one module generates the same template instance, the linker automatically merges duplicates to produce a single copy of the instance. To generate the instances, the compiler must have available the function body (in the case of a template function) or the bodies of member functions and definitions for static data members (in the case of a template class), typically in a header file. This is a convenient way of generating template instances. (Command-line option: -Jgd)

If this option is OFF, the compiler generates external references to all template instances. All template instances that need to be linked must have an explicit instantiation directive in at least one other module. (Command-line option: -Jgx)


Exception Handling (C++ options)

The Exception Handling options enable/disable exception handling and runtime type information; disabling exception handling decreases the code size. If you use exception handling constructs in your code and compile with exceptions disabled, you'll get an error.

Default = Enable RTTI, Enable Exceptions, and Destructor Cleanup

Enable RTTI generates code that allows run-time type identification.

Enable Exceptions enables exception handling. Disabling this option makes it easier for you to remove exception handling information from programs; this might be useful if you are porting your code to other platforms or compilers. Disabling this option turns off only the compilation of exception handling code; your application can still include exception code if you link .OBJ and library files that were built with exceptions enabled (such as the  standard C++ libraries).

Location Information makes run-time identification of exceptions available because the compiler provides the file name and source-code line number where the exception occurred. This enables the program to query file and line number from where a C++ exception was thrown.

Destructor Cleanup enabled and an exception is thrown, destructors are called for all automatically declared objects between the scope of the catch and throw statements.

In general, when you enable this option, you should also set Enable Runtime Type Information (RTTI) as well.

Destructors are not automatically called for dynamic objects allocated with new, and dynamic objects are not automatically freed.

Fast exception prologs inline code is expanded for every exception handling function. This option improves performance at the cost of larger executable file sizes.

If you select both Fast Exception Prologs and Enable Compatible Exceptions, fast prologs will be generated but Enable Compatible Exceptions will be disabled (the two options are not compatible).


General (C++ options)

The General (C++) option enables/disables compatibility with objects from those libraries that implement empty base classes with zero size; e.g., some MFC libraries. (Empty base classes have a size in C++Builder).

Default = Zero length is selected

Zero length empty base classes renders your code compatible with included libraries that implement empty base classes with zero-length size.


Project|Options - Pascal
Pascal (Project|Options)

See also

Use the Pascal page of the Project Options dialog box to set Object Pascal compiler options.

These options correspond to switch directives that you can set directly in your Object Pascal program code. Selecting an Object Pascal option is equivalent to setting the switch directive to its positive (+) state.

Code generation

The Code Generation options effect the code output by the Object Pascal compiler.

Default = Optimization and Aligned record fields

Optimization enables compiler optimizations.
   This setting corresponds to the {$O} Pascal compiler directive.

Aligned record fields aligns elements in structures to 32-bit boundaries.
Corresponds to {$A}

Stack frames forces compiler to generate stack frames on all procedures and functions.
Corresponds to {$W}.

Pentium-safe FDIV generates floating-point code that is safe for all Pentium processors.
Corresponds to {$U}.

Syntax options

These options control how the Object Pascal compiler handles language syntax.

Default = Strict var-strings, Extended syntax, Open parameters, Huge strings, and Assignable typed constants

Strict var-strings sets up string parameter error checking. (If the Open parameters option is selected, this option is not applicable.)
 This setting corresponds to the {$V} Pascal compiler directive.

Complete boolean eval evaluates every piece of an expression in Boolean terms, regardless of whether the result of an operand evaluates as false.
 Corresponds to {$B}.

Extended syntax enables you to define a function call as a procedure and to ignore the function result. Also enables Pchar support.
 Corresponds to {$X}.

Typed @ operator controls the type of pointer returned by the @ operator.
Corresponds to {$T}.

Open parameters enables open string parameters in procedure and function declarations. Open parameters are generally safer, and more efficient.
 Corresponds to {$P}.

Huge strings enables new garbage collected strings. The string keyword corresponds to the new AnsiString type when this option is enabled. Otherwise the string keyword corresponds to the ShortString type.
 Corresponds to {$H}.

Assignable typed constants is used for backward compatibility with Delphi 1.0. When enabled, the compiler allows assignments to typed constants.
 Corresponds to {$J}.

Runtime errors

These options specify how Object Pascal handles errors generated at run time.

Default = I/O checking

Range checking checks that array and string subscripts are within bounds.
Corresponds to {$R}.

I/O checking checks for I/O errors after every I/O call.
Corresponds to {$I}.

Overflow checking checks overflow for integer operations.
Corresponds to {$Q}.

Debugging

Set these options to specify what type of debug information you want included in your .OBJ files.

Default = Debug Information, Local Symbols, and Assertions

Debug information puts debug information into the unit (.DCU) file.
Corresponds to {$D}.

Local symbols generates local symbol information.
Corresponds to {$L}.

Symbol info generates symbol information.
Corresponds to {$Y}.

Assertions generates assertions information.
Corresponds to {$C}.

Messages

These options specify the level of messages generated by the Object Pascal compiler.

Default = No selections

Show hints causes the compiler to generate hint messages.

Show warnings causes the compiler to generate warning messages.

Default check box

Check Default to save the current Pascal options as the default options. C++Builder will use the default options for each new project you create.


Project|Options - Linker
Linker (Project|Options)

See also

Use the Linker page of the Project Options dialog box to specify how your program files are linked. The linker options let you control how intermediate files (.OBJ, .LIB, and .RES) are combined into executable (.EXE) files and/or dynamic-link library (.DLL) files. The IDE uses an incremental linker, ILINK32.

For most options in this section, you usually want to keep the default settings.

Linking

The options in the Linking page specify general linker options.

Default = Include debug information, Use dynamic RTL, Don’t generate state files.

In-memory .EXE causes C++Builder to compile and link an executable image of your .EXE in RAM; the .EXE is not written to disk. Use this option for faster compile/link cycles on systems with smaller amounts of RAM. Be sure to disable this option when you want to create an .EXE image on disk. (This option is disabled if you are running on Windows 95.)

Create debug information adds debug information to the final executable image. Debug information is used by both the integrated debugger and by Turbo Debugger 32-bit (TD32.EXE).

Use dynamic RTL means to use the RTL DLL, which is the DLL version of the Runtime Library in your application (or dll/package/activeX control).  If you enable the option, the RTL code isn’t linked into your application, resulting in a smaller image, but you must distribute the RTL DLL with your application.

Use debug libraries causes C++Builder to link the debug version of the VCL (VCLD.LIB). This option does not work if you are using packages. To turn off the packages, go to the Packages page and turn off Use Packages. Turn on Use debug libraries only when you want to step into the library source code; it will greatly increase the size of your executable files (but it will not effect application performance).

Generate import library only applies to DLL and Package targets.  This option controls whether or not the linker creates an import library (for DLLs - .lib) or package import (for Packages - .bpi) along with your target.  The import file is needed to use the DLL/package from an application. For example, if an application wanted to use your DLL, it would add the import library for your DLL to its project.  Or if a user had your package installed and wanted to use a component from it, there would have to be a .bpi available.

Generate .lib file only applies to Package targets. This option tells the linker to create a .LIB file as an import library instead of a .BPI file. This allows applications to link to your runtime packages like DLLs.

Don’t generate state files suppresses generation of linker state files, disabling incremental linking. If you select this option, subsequent links will take just as long as the first one.

Max errors causes linking to stop after the specified number of errors has been detected. You can enter any number from 0 to 255.

Map file

Select the type of map file produced, if any. The map file is placed in the Output Directory specified on the Directories/Conditionals page, and it has a .MAP extension.

Default = Off

Option	Effect

Off	Does not produce map file.

Segments	Linker produces a map file that includes a list of segments, the program start address, and any warning or error messages produced during the link.

Publics	Linker produces a map file that includes a list of segments, the program start address, any warning or error messages produced during the link, and a list of alphabetically sorted public symbols.

Detailed	Linker produces a map file that includes a list of segments, the program start address, any warning or error messages produced during the link, a list of alphabetically sorted public symbols, and an additional detailed segment map. The detailed segment map includes the segment address, length in bytes, segment name, group, and module information.

Show Mangled Names	prints the mangled C++ identifiers in the map file, not the full name. This can help you identify how names are mangled (mangled names are needed as input by some utilities).

For details on the map files produced, see Map File Options.

Warnings

The Warnings settings specify the type of warning messages given when you are building your project.

All enables all potential warning messages.

Selected allows you to select one-or-more warning messages. Select the Selected radio button and then click on the Warnings button, which displays the Warnings dialog box.

 	Default = No stack defined (-wstk)
Application has no entry point (-went)
Duplicate symbols (-wdup)
Basing a DLL may cause malfunction (-wbdl)
Self relative fixup overflow (-wsrf)
EXE built with DLL extension (-wdll)
Multiple stack segments found (-wmsk)

PE File Options

Use these edit boxes to specify the minimum and maximum stack size and heap image base for the compiled executable.

Min stack size specifies the minimum size of the stack in hexadecimal. The minimum allowable value for this field is 4K (0x1000).

Default = 0x00004000

Max stack size specifies the maximum size of the stack in hexadecimal.

Min heap size specifies the minimum size of the heap in hexadecimal. The minimum allowable value for this field is 0.

Max heap size specifies the maximum size of the heap in hexadecimal.

Image base gives your executable an image base address. If this setting is turned on, internal fixes are removed from the image and the requested load address of the first object in the application is set to the number you specify. All successive objects are aligned on 64K linear address boundaries. This option makes applications smaller on disk and improves both load-time and run-time performance (the operating system no longer has to apply internal fixes).

Although this option can greatly reduce the size of your final application module; it is not recommended for producing a DLL.

The recommended setting for true Win32 systems: 0x400000

Do not use the default setting of 0x400000 if you intend to run your application on Win32s systems.

Subsystem Major lets you specify the major portion of Windows version ID on which you expect your application will be run. The linker sets the Subsystem version field in the .EXE header to the number you specify in the input box. To generate the version ID, “4.2,” set the Subsystem Major to 4 and the Subsystem Minor to 2.

Subsystem Minor lets you specify the minor portion of Windows version ID on which you expect your application will be run. The linker sets the Subsystem version field in the .EXE header to the number you specify in the input box. To generate the version ID, “4.2,” set the Subsystem Major to 4 and the Subsystem Minor to 2.

Default

Check Default to save the current project options so that every new project you create will use those options.


Linker Warnings dialog box

See also

Duplicate symbols in library
{-wdpl commandline equivalent}

Off by default.The linker warns you if a symbol appears in a library file and an object file. The linker uses the definition from the .OBJ file in preference to the definition in the library. This augments the Duplicate symbols warning, which does not check library files. Be sure to include the Duplicate symbols warning if you turn this warning on.

No stack defined
{-wstk commandline equivalent}

On by default. The linker emits the "No stack" warning if no stack segment is defined in any of the object files or in any of the libraries included in the link. Except for .DLLs, this indicates an error. If a C++Builder program produces this error, make sure you are using the correct C0x startup object file.

Application has no entry point
{-went commandline equivalent}

On by default.This warning appears if no starting execution point was defined in the application. This usually happens if you forget to link in the startup code.

Duplicate symbols
{-wdup commandline equivalent}

On by default The linker warns you if it finds the same symbol in more than one .OBJ file. The linker uses the first one it encounters.

No module definition file specified
{-wdef commandline equivalent}

Off by default. This warning appears if the .DEF file is missing from the project.

Import record does not match
{-wimt commandline equivalent}

Off by default. This warning usually occurs if an IMPDEF record appears in an import library when the import in question is also imported from a .DEF file. If the description of the imports differ in internal name or ordinal, this warning appears, and the first definition is used.

Basing a DLL may cause malfunction
{-wbdl commandline equivalent}

On by default. The linker gives this warning occurs if it encounters the /B (image base) switch when linking a DLL. In almost every case, this is an error that will prevent the application from running.

Self relative fixup overflow
{-wsrf commandline equivalent}

On by default.This message appears if a self-relative reference (a call or a jump) is made from one physical segment to another. This often happens when employing assembler code, but can occur if you use the segment-naming options in the compiler. If the reference is from one code segment to another, you are safe. If, however, the reference is from a code segment to a data segment, you have probably made a mistake in some assembler code.

EXE built with DLL extension
{-wdll commandline equivalent}

On by default. The linker generates this warning when an executable file has been generated and stored in a file with a .DLL extension. This usually occurs when you intended to build a .DLL but forgot to specify a .DLL target.

Multiple stack segments found
{-wmsk commandline equivalent}

Off by default. This warning occurs when two stack segments of different names are defined in the object modules. The startup code defines a stack segment for the application.


Project|Options - Directories/Conditionals
Directories/Conditionals (Project|Options)

See also

Use the Directories/ Conditionals page of the Project Options dialog box to specify the location of files needed to compile, link, and distribute your program. In addition, you can specify compiler defines on this page. Click the down arrow next to any edit box to choose from a list of previously entered directories or symbols.

The Directories settings tell C++Builder where to find C++ header and library files, and where to store intermediatefiles.

Include Path specifies the directories with the header files used by your project.

Default = $(BCB)\include;$(BCB)\include\vcl

Library Path specifies the directories with the libraries, resource files, and the source path for the unit files.

Default = $(BCB)\lib\obj;$(BCB)\lib

Debug source path specifies the directories where the debugger looks for source code. You do not need to specify the source path for any source code that is compiled as part of your project or project group.

Default = $(BCB)\source\vcl

Intermediate output specifies the directory where intermediate files (.OBJ and generated .ASM files) are placed. Note that other intermediate files such as .RES files are not put in the Intermediate output directory.

Default = no default

Final output .Specifies where your final target (.EXE, .BPL, or .DLL) is placed.

Default = no default. If not specified, the target is placed in the same directory as the project file (.BPR).

BPI/LIB output .specifies where the .BPI and/or .LIB files are placed when creating a package or DLL. (You need to specify the Generate import library or .lib file options on the Linker page of the Project|Options dialog box.)

Default = no default. If left blank, the global library path specified in the Tools|Environment Options Library page is used instead.

You can specify multiple directories (except for the intermediate output directory) by separating them with a semicolon. See Search Directories for more information on setting these options in C++Builder.

You can enter a path relative to your C++Builder root directory using the $(BCB) environment macro.

Conditionals

Conditionals define the conditions used by the pre-processor to determine which bracketed code to compile.

Conditional defines specify symbolic defines for the C++, Object Pascal, and Resource compilers. You can include multiple definitions by separating each define with a semicolon (;). Assign values with an equal sign (=). For example:

xxx;yyy=1;zzz=NO MYFILE.C

For more information on bracketing code with these compiler defines, see #ifdef, and #ifndef, under Preprocessor directives.

Default = _ATL_SINGLE_THREADED

Aliases

Useful for backwards compatibility.

Unit aliases specify alias names for Object Pascal units that may have changed names or were merged into a single unit. The syntax format is <oldunit>=<newunit>. You can separate multiple aliases with semicolons.

Default = no default

Default

Check to save the current project options so that every new project you create will use those options.


List entry dialogs

These dialog boxes help you manage what can be lengthy lists of paths, conditionals, names, or unit aliases. They appear when you click the ellipses next to a listing edit control on another dialog such as the Directories/Conditionals page of the Project Options dialog.

Use these dialogs to add and remove strings from a semicolon-delimited list.

The list appears in the listbox at the top. As you scroll through the list, an edit control beneath the list displays the selected entry. Use this edit control to modify the current entry or enter a new entry. After editing the value in the edit control, click Replace to modify the current entry or Add to add the value as a new entry to the list. Click the Delete button to remove the current entry from the list.

Use the arrow buttons at the right side of the dialog to rearrange the entries in the list.


Version Info (Project|Options)

See also

Use this page to enable the version information option and to specify version information for the project.

Include version information in project determines whether the user can view product identification information.

Module Version Number sets hierarchical nested version, release, and build identification.

Module Attributes indicates the intent of this version: whether for debugging, pre-release, or other purposes.

Language indicates the natural language (locale) the application displays.

Key/Value list box sets typical product identification properties.

Default check box

Check Default to save the current settings in all the Project Options pages as the default options. Each new project begins with these default options.


Include version information in project (Version Info options)
Include version information (Version info options)

See also

The include version information in projects checkbox enables version information to be entered. This information is then included in the compiled code. When version information is included, a user can right-click the program icon and select properties to display the version information.


Module Version Number (Version info options)

See also

Major, Minor, Release, and Build each specify an unsigned integer between 0 and 65,535.  The combined string defines a version number for the application, for example 2.1.3.5.

Check Auto-increment build number to have the build number incremented each time the Project | Build <Project> menu is selected. (Other compilations do not change the build number.)


Module Attributes (Version info options)

See also

Module attributes are flags that can be included in the version information for informational use only.  If a project is compiled in debug mode, the debug flag will be included in the version information.  You can select each of the remaining flags as needed.

Attribute	Effect

Debug Build	Included to indicate that the project was compiled in debug mode.

Pre-Release	Include to indicate the version is not the commercially released product.

DLL	Include to indicate that the project includes a dynamic-link library.

Special Build	Include to indicate that the version is a variation of the standard release.

Private Build	Include to indicate that the version was not built using standard release procedures.


Key/Value list box (Version info options)

See also

The Key/Value list box options provide appropriate values for typical product identification attributes. A default set of keys are included.

Key	Value indicates

CompanyName	The company that produced the file. Required.

FileDescription	File description. You can display this string in a list box during

installation. Required

FileVersion	File version number. Required.

InternalName	File internal name. If file does not have internal name, use original filename, without extension. Required.

LegalCopyright	File copyright notices. Optional.

LegalTrademarks	Trademarks and registered trademarks that apply to file. Optional.

OriginalFilename	Original file name, not including path. Required.

ProductName	Name of product that file is distributed with. Required.

ProductVersion	Version of product that file is distributed with. Required.

Comments	Additional information for diagnostic purposes. Optional.

Key entries can be edited by selecting the key and re-entering the name. Key entries can be added by right-clicking within the Key/Value table and selecting Add Key.


Language (Version info options)

See also

The Language indicates which Code Page the users system will require to run the application, that is, it indicates which language the application displays. The following languages are supported.

Constant	Language	Constant	Language

0x0401	Arabic	0x0415	Polish

0x0402	Bulgarian	0x0416	Brazilian Portuguese

0x0403	Catalan	0x0417	Rhaeto-Romanic

0x0404	Traditional Chinese	0x0418	Romanian

0x0405	Czech	0x0419	Russian

0x0406	Danish	0x041A	Croato-Serbian (Latin)

0x0407	German	0x041B	Slovak

0x0408	Greek	0x041C	Albanian

0x0409	U.S. English	0x041D	Swedish

0x040A	Castilian Spanish	0x041E	Thai

0x040B	Finnish	0x041F	Turkish

0x040C	French	0x0420	Urdu

0x040D	Hebrew	0x0421	Bahasa

0x040E	Hungarian	0x0804	Simplified Chinese

0x040F	Icelandic	0x0807	Swiss German

0x0410	Italian	0x0809	U.K. English

0x0411	Japanese	0x080A	Mexican Spanish

0x0412	Korean	0x080C	Belgian French

0x0413	Dutch	0x0C0C	Canadian French

0x0414	Norwegian - Bokml	0x100C	Swiss French

0x0810	Swiss Italian	0x0816	Portuguese

0x0813	Belgian Dutch	0x081A	Serbo-Croatian (Cyrillic)

0x0814	Norwegian - Nynorsk


Project|Options - Packages
Packages page (Project|Options, Component|Install packages)

See also

Use this page to specify the design-time packages installed in the IDE and the runtime packages required by your project.

Design-time packages	Lists the design time packages available to the IDE and to all projects.

Runtime packages	 Determines which run-time packages to use when the executable file is created.

Default

Check the "Default" box in the lower left corner of the dialog to turn the current package configuration into the default configuration for all new projects.


Design Packages in project (Packages options)
Design packages (Packages options)

Design packages lists the design time packages available to the IDE. Items with a check mark are installed in the current project. When a package is installed, it may register components that appear on the Component palette, experts that appear on the menu bar and New Items (File|New) dialog, and property editors for custom components.

Warning:	Take care when uninstalling packages, whether by using the Remove button or by unchecking the package's check box. When a package is removed, any components registered by it become unavailable in the IDE. If a project contains forms that use unavailable components, you will not be able to load the forms; if this happens, reinstall the package and reload the unit.

The following buttons manipulate entries in the list.

Button	Description

Add	Installs a design time package. The package will be available in all projects.

Remove	Deletes the selected package. The package becomes unavailable in all projects.

Edit	Opens the selected package in the Package editor if source is available.

Components	Displays a list of the components included in the selected package.

As packages are installed and uninstalled, you may notice that the runtime package list is updated. C++Builder automatically adds runtime packages that are required by installed design-time packages.


Runtime Packages in project (Packages options)
Runtime packages (Packages options)

The Runtime Packages option determines which run-time packages to use when the executable file is created. A runtime package is a special dynamic-link library used by C++Builder to provide functionality when a user runs an application.

Build with runtime packages check box

Check this to include runtime packages in your project and to enable the runtime packages edit box.

Runtime packages edit box

Use this to change the packages included in your project. you can add a package to your project by

 Clicking Add and specifying a package to add to the list of runtime packages in the Add runtime package dialog box.

Or,

 Typing a list of packages to use as run-time packages, separated by semicolons (VCL40;VCLDB40;VCLDBX40), into the edit box.

When a project uses a package, C++Builder must find the package's .BPI file in order to compile. When C++Builder cannot find the .BPI, it is often because the .BPI’s directory is not included in the global Library Search Path. To edit the Library Search Path, choose Tools|Environment Options and select the Library tab.


Add Design Package

See also

Use the Add Design Package dialog box to specify the name of a design time package to add to the Design packages list. This is a standard Windows Open dialog.


Add Runtime Package

See also

Use the Add Runtime Package dialog box to specify the name of a runtime package to add to the Design packages list.

Package Name	Type the name of the package to add to the Runtime Packages list, or click the Browse button to search for the package using the Package File Name dialog. If the package is in the Search Path, a full path name is not required. (If the package directory is not in the Search Path, it will be added at the end.)

Search Path	If you haven't included a full directory path in the Package Name edit box (see above), make sure the directory where your package resides is in this list. If you add a directory in the Search Path edit box, you are changing the global Library Search Path. You can also change this path on the Tools|Environment Options Library page.


Package package will be built then installed. Continue?

This message appears when adding a component or ActiveX control to a package. Click Yes to rebuild the package to reflect the new component or control.


Package(s) <package list> will also be uninstalled because they require package <package name>. Continue uninstall?

Appears when installed packages rely on packages that you’re trying to uninstall. Click Yes to uninstall the dependent packages.


Components

See also

Lists components in the selected package, along with the icons for those components that appear on the Component palette if the package is installed.


Package editor

See also

The Package editor lists the units in a package, and the other packages it requires. You can save your changes with File|Save or Save As.

Contains list	The Contains list shows the units included in the package. To add a unit to the package, click the Add button. To edit a unit's source code, double-click it.

Requires list	The Requires list shows the other packages required by the current package. To add a package, click Add. To display a package in its own Package editor, double-click it.

Package editor SpeedBar

Button	Description

Compile	Compiles the current package. If changes to the package are required, a dialog box appears that lists the changes that will be made to the package before it is compiled.

Add	Adds an item (see the Contains list and Requires list for details).

Remove	Removes the selected item from the package.

Options	Displays the Project Options Dialog Box.

Install	Installs the current package as a design time package. If changes to the package are required, a dialog box appears that lists the changes that will be made to the package before it is compiled.

Package editor context menu

To display the Package editor context menu, right-click an item within either Package editor page.

Command	Description

Add 	Equivalent to Add button on SpeedBar.

Remove File	Equivalent to Remove button on SpeedBar.

Open	If a unit is selected, loads the unit in the code editor. If a package is selected, opens the Opens the package in a new Package Editor window.

Save	Saves the current package.

Remove From Project	Equivalent to Remove button on SpeedBar.

View Unit	Lets you view the selected unit’s source code.

View Source	Lets you view the package source code (.BPK file)

Options	Equivalent to Options button on SpeedBar.

Install	Equivalent to Install button on SpeedBar.

Make	Check all units which the file being compiled contains and only compile those units that have been modified or any compiler directives specifies that the file be compiled.

Build	Compile all units which the package contains.

Add to Project Group	Add the package to the current project group.

Toolbar	Displays the Package Editor toolbar when checked.

Status Bar	Displays the Package Editor status bar when checked.

Dockable	Allows the Package Editor to be docked onto other windows (and vice versa) when checked.


Add Unit

Enter the name of the unit file to add in Unit File Name (or select it using Browse). If you enter a name, C++Builder searches the paths specified in Search path.

Unit File Name	The name of the unit to add. If the unit is in the Search Path, a full path name is not required. If the unit directory is not in the Search Path, it will be added to the end.

Search Path	If you haven't included a full directory path in the Unit File Name edit box (see above), make sure the directory where the unit resides is in this list. If you add a directory in the Search Path edit box, you will be changing the global Library Search Path.


Add Package
Requires

Enter the name of the package to add in Package name (or select it using Browse). If you enter a name, C++Builder searches the paths specified in Search path.

Package Name	Enter the name of the package to add. If the package is in the Search Path, a full path name is not required. (If the package directory is not in the Search Path, it will be added to the end.)

Search Path	If you haven't included a full directory path in the Package Name edit box (see above), make sure the directory where your package resides is in this list. If you add a directory in the Search Path edit box, you will be changing the global Library Search Path.


Description page
Description page (Project Options dialog box)

See also

The Description page lets you specify a description for the package, the uses of the package, and how the package is built.

Description	A brief description that appears when the package is installed.

Usage options	Select Design Package if you want the package to be installable on the Component palette.

Select Runtime Package if you want the package to be deployable with an application.

Select both Design Package and Runtime Package if you want the package to be both installable and deployable.

Note:	If your package uses custom property editors, it's a good idea to compile separate design-time and runtime versions of it. The deployed runtime package will be smaller than the design-time version, since it won't contain code for the property editors.


Change Package dialog box
Change Package dialog box (Package editor)

See also

The Change dialog appears when the Package editor tries to compile a package and detects that the package cannot be built or is incompatible with another package currently loaded by the IDE. This occurs because the package uses a unit or units that are found in another package; select View Details to see which units are causing the problem.

The solution is to add the other package to the "requires" clause of the package you are editing, or simply not use the problem units at all. Click OK to let the Package editor make the proposed changes and continue compiling. Click Cancel to leave the package as it is.


duplicate file name error
Duplicate file name error (Package editor)

See also

This error message appears when a file in the directory of the package has the same name as a file in a different location specified by the user. Because the directory of the package .BPK file is searched first when building a package, the naming conflict prevents the compiler from finding the intended file.

This problem can arise when creating a component, installing a component, importing an ActiveX control, or adding a contained unit or required package to a package.

The problem can be solved by saving the package .BPK file to a different directory.


Project|Options - ATL
ATL (Project|Options)

See also

The ATL options are available when the project contains a COM server (an ActiveX control or an OLE automation object). These options apply to every COM server in the project.

Instancing

Instancing indicates whether client applications operate on dedicated instantiations of the COM server object or whether all clients share a single instance. The following table lists the possible values:

Value	Meaning

Single use	The ATL creates multiple instances of the COM server object. Each client operates on its own instance.

Multiple use	All clients operate on a single instance of the COM server object.

Threading

Threading indicates what type of threading is used when implementing the COM server object. The value of Threading determines how ATL functions used to implement the object are called.

Value	Meaning

Single threaded	All COM server objects are implemented using a single thread.

Apartment threaded	The project may be multi-threaded, but each instance of the COM server object must have its own dedicated thread for OLE calls. Container objects must call an object instance from within a single thread.

For more information about writing multi-threaded applications, see Using Threads.

Debugging

Debugging options control what information is sent to the debugger by the ATL when debugging an ActiveX control or OLE automation object. Use Run|Parameters to start a debugging session from the host application.

Trace Query Interface specifies that a message is sent to the event log whenever a client makes a QueryInterface call. The event log also shows the status (success or failure) of the call.

Check Ref Counts specifies that a message is sent to the event log whenever the reference count of a COM server object is increased or decreased. When Check Ref Counts is enabled, an assertion occurs if the project attempts to release the object from memory with a nonzero reference count.

General Tracing specifies that messages are sent to the event log whenever an ATL function is called.

Default check box

Check Default to save the current settings in all the Project Options pages as the default options. C++Builder will use the default options for each new project you create.


Project|Options - TLIB
TLIB (Project|Options)

See also

You can set the following TLIB options when the project is a library:

Case-sensitive library	Because some linkers are not case-sensitive, TLIB rejects symbols that differ only in case (for example, lookup and LOOKUP are treated as duplicates). ILINK32, however, can distinguish case, so if you use your library only with ILINK32, you can use the TLIB case-sensitive option to add a module to a library that includes symbols differing only in case.

Create extended library
Creates an extended library. To increase the linker’s capacity for large links, you can use TLIB to create an extended dictionary and append it to the library file. This dictionary contains, in compact form, information that is not included in the standard library dictionary and that lets the linker preprocess library files so that any unnecessary modules are not preprocessed.

If you set this option for a library that contains a C++ class with a virtual function, you will get the error message, Library contains COMDEF records—extended dictionary not created.

Purge comment records
Removes comment records from the library. By setting this option, you reduce the size of a library. For example, you might have debugging or browsing information in a library, but you no longer need to use that information.

Page size	Sets the library page size. Every DOS library file contains a dictionary that appears at the end of the .LIB file, following all object modules. For each module in the library, the dictionary contains a 16-bit address of that particular module within the .LIB file; this address is given in terms of the library page size (by default, the size is 16 bytes).

The library page size determines the maximum combined size of all object modules in the library, and cannot exceed 65,536 pages. The default (and minimum) page size of 16 bytes allows a library of about 1 MB in size. To create a larger library, set this option. The page size must be a power of 2, and it cannot be smaller than 16 or larger than 32,768.

All modules in the library must start on a page boundary. For example, in a library with a page size of 32 (the lowest possible page size higher than the default page size of 16), an average of 16 bytes is lost per object module padding. If you attempt to create a library that is too large for the given page size, you will get an error message.


Project|Options - Tasm
Tasm (Project|Options)

See also

The Tasm options set the parameters and scope for the turbo assembler.

Debug Information	enables/disables debug information in the object file.

Case sensitivity	treats symbol names as case-sensitive.

Selections	calibrates the initialization and scoping of the assembler.

Warnings	sets how Tasm generates warnings.

Generate Listing	generates a listing file, which has the same name as the source file with the .LST extension.

Default check box

Check Default to save the current settings in all the Project Options pages as the default options. C++Builder will use the default options for each new project you create.


Debugging information in project (Tasm options)
Debug Information (TASM options)

See also

The Debug Information options enable debug information in the object file.

 	Default = Line Number

None disables debug information in the object file.

Line Number tells Tasm includes line-number records to synchronize source code display and data type information.

Full lets you use all the features of the debugger to step through your program and examine or change data items.


Case sensitivity in project (Tasm options)
Case sensitivity (TASM options)

The Case sensitivity options determine whether Tasm treats symbol names the as case sensitive/insensitive.

 	Default = Globals

None disables case sensitivity; treats symbol names as case-insensitive.

Globals treat only external and public symbols as case-sensitive.

All treats as uppercase all symbols used within the source file.


Selections in project (Tasm options)
Selections (TASM options)

The Selections options are as follows:

Hash table capacity sets the maximum number of symbols an assembler file (.ASM) can use. The minimum allowable Hash table capacity is 8,192 bytes. The maximum allowable Has table capacity is 32,768 bytes.

 	Default = 8192

Maximum passes sets the maximum number of assembly passes. This is useful if you want Turbo Assembler to remove NOP instructions that were added because of forward references.

 	Default = 1

Maximum symbol length sets the maximum length of symbols that Tasm can distinguish between. The minimum number allowed is 12.

 	Default = 12

Add directive defines an assembler startup directive. This directive is assembled before the first line of the source file.

 	Default = False


Warnings in project (Tasm options)
Warnings (TASM options)

The Warnings options determines when Tasm generates warnings.

bmc prcarrow.bmp} 	Default = Level 1

None disables warnings.

Level 1 generates mild warnings that indicate how you can improve your code’s efficiency.

Level 2 generates all warnings.


Generate listing in project (Tasm options)
Generate Listing (TASM options)

The Generate Listing options generate a listing representing the assembler code, which is filed with the same basename as the source file with the .LST extension.

bmc prcarrow.bmp} 	Default = Normal Listing

Normal Listing generates a listing for whatever you select in the check boxes:

bmc prcarrow.bmp} 	Default = none selected

Cross reference

Symbol Tables Information

Include false conditionals

Include Error Messages

Expanded Listing generates the normal listing and includes the subset of C/C++ that generated the .ASM file.

Cross Reference enables cross-reference in listing file. Tasm adds the cross-reference information to the symbol table at the end of the listing file.

Symbol Tables Information suppresses the symbol table in the listing file.

Include false conditionals includes false conditionals in listing. If a conditional (such as #if, #ifndef, #ifdef) evaluates to False, this option causes the statements inside the conditional block to appear in the listing file.

Include Error Messages displays source lines along with error messages.


Optimizing C++Builder compile times

C++Builder has been engineered to give you the fastest possible edit/run turnaround time. Even though, there are a number of user-controlled factors that can help make your turnaround times even faster.

Overview of compilation cycle

When you press F9 (or choose Project|Run) C++Builder does the following:

1. 	C++Builder first does a dependency check on the files in your project to see which target files need rebuilding.

2. 	C++Builder then compiles any out-of-date .CPP, .PAS, .ASM and .RC files.

3. 	After compiling, C++Builder links all the objects into an executable image.

4. 	After linking, C++Builder loads the program for running.

Fast turn-around times

C++Builder employs several technologies to speed up the compilation cycle:

Dependency file caching

Cached pre-compiled headers

Incremental and smart linking

Incremental images

Optimizing your edit/run cycles

Below is a checklist of things you can do to ensure you are getting the fastest possible edit/run turnaround times with C++Builder:

Use Project Make

Know when to use linker-state files

Use in-memory .EXE files

Turn debug information off

Turn off the integrated debugger

Link with the non-debug version of VCL

Add more memory (RAM) to your system


Dependency file caching

After the first build of your project in a session, C++Builder remembers the time-stamp of each file so it doesn't have to query the OS for it until it has detected a change. This information is rebuilt any time you move focus to another application and then back to C++Builder.


CachedPrecompiledHeaders
Cached pre-compiled headers

A program being compiled can specify that a certain set of #include (header) files are to be pre-compiled and stored in a single file. This "pre-compiled header" file is then loaded by the next compile that uses it, thereby avoiding the recompilation of the same header files.

In addition, C++Builder caches the pre-compiled header files in memory, so that subsequent compiles don't have to reload the pre-compiled headers for each compile.


Incremental and smart linking

The incremental linker stores the current linker-state in a set of files so that the linker can quickly load all information about the target executable during the next link. By saving the linker state, C++Builder has to link only the files (and dependencies) that have changed. The smart linking feature links only those functions and symbols that are actually referenced in your source code. This means that even though you link in the entire VCL.LIB, only those functions that you use will be linked.


Incremental images

Known as "in memory .EXEs," the incremental linker has the ability to link a target .EXE directly into memory. This saves the time it takes to save the .EXE to disk, and then reload it when the .EXE is run. This also has the effect of using a smaller working set which, on machines with limited memory, benefits other aspects of the turnaround process.


Use Project Make

Use "make" (F9, Project|Run) rather than "build all" whenever possible. Doing a "build all" will take significantly longer because it:

Deletes your project's linker-state files

Deletes your project's pre-compiled header file

Compiles all source files (.CPP, .PAS, .RC)

Links your program from scratch (no incremental linker support)


When to use linker-state files

By default, the incremental linker uses linker-state files to track which OBJs and libraries have to be reread with each build. These files consume substantial amounts of disk space, but they can speed up linking. To disable linker-state files, choose Project|Options, select the Linker tab, and check Don’t Generate State Files.

The following points should help you to decide when to save linker-state files.

Linker-state files speed up linking during the first build after a project is reopened. Subsequent builds will be just as fast whether or not the linker-state files are saved, because linker-state information is kept in memory as long as the project remains open in the IDE. However,

If you have two or more projects open at once and you build one project and then another, linker-state files will save you a lot of time—even on successive builds. This is because the linker has to discard (and, if there are no state files, reconstruct) the state information it has in memory each time you switch projects.

The very first build of a new project will take approximately the same amount of time whether or not linker-state files are generated.

The In-mem EXE option requires linker-state files.


Use in-memory .EXE files

If your are running Windows NT with 32 megabytes or less of memory, try using the In-memory .EXE linker option (Options|Project|Linker) to build and run .EXE files in memory.

This should always improve the turnaround time, especially in low-memory situations or when the .EXE is fairly large.

Try using this option whenever the link step seems to take long or cause a lot of hard disk activity.

Windows 95 does not support this option.


Turn debug information off

On large projects, compiling and linking with debug information on can slow down the turnaround process. If you are in a phase of development where you are not using the debugger often, you should try turning off debug information (use the Release button on the Compiler page of the Project Options dialog box) and see if your turnaround time improves.


Turn off the integrated debugger

With large projects, running the project under the integrated debugger can take a few seconds for the debugger to load the project. If you are in a phase of development where you are not using the debugger often, you should try turning off the integrated debugger (use Options|Environment|Integrated Debugging) and see if your turnaround time improves.


Link the non-debug version of the VCL library

It takes significantly longer (and also takes a larger working set) to link the debug version of VCL. Avoid this whenever possible. (Do not check the Link Debug Version of VCL on the Linker page of the Project Options dialog box.)


Add more memory (RAM) to your system

In general, adding more RAM to your system will benefit a number of the other factors which will speed up edit/run cycles. If you are working with large projects and want the fastest turnaround times possible, it is recommended that you have 48-64 megabytes of RAM (memory).


Project|Options - IDL
CORBA (Project|Options)

See also

Use the CORBA page to set the flags that control how IDL files are compiled to create server files (that contain skeleton classes), and client files (that contains the stub classes). The CORBA page also allows you to indicate what CORBA library support should be linked into the project.

For more information about these options, see the documentation for the VisiBroker IDL2CPP utility.

Code Generation

Use the Code Generation options to influence what code is included in the generated server and client units.

Object Wrappers	When checked, the IDL compiler generates stubs and skeletons with object wrapper support. It also generates the base typed object wrapper from which all other object wrappers inherit, and a default object wrapper that performs untyped object wrapper calls.

Tie	When checked, the IDL compiler generates Tie classes that support the delegation model.

Virtual Impl. Inheritance	When checked, the server class interfaces allow virtual inheritance to allow inheritance between server implementations.

Typecode Information	When checked, server classes include type code information that is required by clients using the dynamic invocation interface. If unchecked, server classes must register with the Interface Repository for clients to access them using DII.

Include Files Code	When checked, the IDL compiler generates code for all IDL in files referenced by an #include statement. When unchecked, the included files are parsed, but no code is generated for the definitions they contain.

Stream Operators	When checked, the IDL compiler generates class stream operators with standard iostream classes in their signature.

File Extensions

Use File Extensions to control the names of the files that are generated when IDL files are compiled.

Header Extension	The file extension for generated header files.

Source Extension	The file extension for generated source files.

Additional IDL

Use Additional IDL to add IDL compiler flags that are not available in the Code Generation section.

Options	List any additional flags that should be sent to the IDL compiler. For details, see the documentation for IDL2CPP.

IDL Compilation

Use IDL Compilation to determine which files get added to a project when the IDL files are compiled. By default, CORBA server projects include only the server unit and CORBA client projects include only the client unit.

Add Server Unit to Project	When IDL files are compiled, the generated server files (containing the skeleton classes and related definitions) are added to the project.

Add Client Unit to Project	When IDL files are compiled, the generated client files (containing stub classes and related definitions) are added to the project.

Precompiled Header support	Inserts code that takes advantage of precompiled headers into the generated client and server files, speeding up compile times. This option is not available when compiling IDL files from the command line.

Corba.h options

Use Corba.h options to determine what functionality from the CORBA libraries is included in the CORBA header files.

Include IR	Allows applications to link to and use the CORBA objects methods that access the interface repository. See the VisiBroker reference for details on these objects and methods.

Include DSI	Allows applications to link to and use the CORBA objects methods that access the dynamic skeleton interface. See the VisiBroker reference for details on these objects and methods.

Default

Check Default to save the current settings in all the Project Options pages as the default options. C++Builder will use the default options for each new project you create.


Run menu

The Run menu commands help you debug your program from within C++Builder. The following commands form the core functionality of the integrated debugger.

Run	Compiles and executes your application

Attach to Process	Provides a list of currently running processes that you can debug

Parameters	Specifies startup parameters for your application, a host executable for DLLs, or a computer for remote debugging

Register ActiveX Server	Adds a Windows registry entry for your ActiveX control Available when the current project is an ActiveX project

Unregister ActiveX Servers	Removes the project from the Windows registry. Available when the current project is an ActiveX project

Install MTS Objects	Installs MTS objects in the current project into an MTS package. Available when the current project is an MTS object

Step Over	Executes a program one line at a time, stepping over functions while executing them as a single unit

Trace Into	Executes a program one line at a time, tracing into functions and following the execution of each line

Trace To Next Source Line	Executes the program, stopping at the next executable source line in your code

Run To Cursor	Runs the loaded program up to the location of the cursor in the Code editor

Run Until Return	Runs the process until execution returns from the current function

Show Execution Point	Positions the cursor at the execution point in an edit window

Program Pause	Temporarily pauses the execution of a running program

Program Reset	Ends the current program run and releases it from memory

Inspect	Open an Inspector window, where you can enter an item you want to inspect

Evaluate/Modify	Displays the Evaluate/Modify dialog box, where you can evaluate or change the value of an existing expression

Add Watch	Opens the Watch Properties dialog box, where you can create and modify watches

Add Breakpoint	Opens the Edit Breakpoint dialog box, where you can create and modify breakpoints


Run|Run

See also

Choose Run|Run to compile and execute your application, using any startup parameters you specified in the Parameters dialog box.

If you have modified the source code since the last compilation, the compiler recompiles those changed modules and relinks your application.

If the compiler encounters an error, it displays an Error dialog box. When you choose OK to dismiss the dialog box, the Code editor places the cursor on the line of code containing the error.

The compiler builds .EXE files according to the following rules:

The project file is always recompiled.

If the source code of a unit has changed since the last time the unit was compiled, the unit is compiled. When a unit is compiled, C++Builder creates a file with a .OBJ extension for that unit.

If C++Builder cannot locate the source code for a unit, that unit is not recompiled.

If a unit contains an Include file. and the Include file has changed, the unit is recompiled.


Run|Attach to Process

Choose Run|Attach to Process to debug a process that is currently running. A list of processes running on the local computer is displayed. Select a process from the list and either double-click it or click on Attach to start debugging. The debugger is ‘attached’ to the process.

You will not be allowed to attach to a process you are already debugging, nor will you be able to attach to the IDE itself.

You can also list processes on a remote machine by entering the remote computer name in the Run|Attach to Process dialog box and clicking Refresh. The remote debug server must be running on the remote computer. For more information, see Remote debugging.


Run|Parameters

See also

Choose Run|Parameters to open the Run Parameters dialog.

Use this dialog to pass command-line parameters to your application when you run it (just as if you were starting the application from the Program Manager File|Run menu), specify a host executable for testing a DLL, run your program on a remote machine, or load any executable into the debugger.

Click OK to save the settings you’ve entered and close the Run Parameters dialog.

Local tab

Use this page to run and debug projects on the computer you are working at.

Host application

Enter the path to an .EXE file. (Click Browse to bring up a file-selection dialog.)

If the current project is a DLL, use this edit box to specify a host application that calls the DLL.

You can also enter the name of any executable that you want to run in the debugger. Then press Load to load the executable. The executable will be paused at its entry point. If there is no debug information at the entry point, the CPU window will be opened. Select Run|Run (F9) to run the executable.

If you want to run the project that you have open in C++Builder, there is no need to enter anything in the Host Application edit box.

Parameters

Enter the command-line arguments you want to pass to your application (or the Host application) when it starts. You can use the drop-down button to choose from a history of previously specified parameters.

Do not enter the application name in this edit box.

Remote tab

Use this page to run an application on a remote computer.

Remote path

Enter the path to an .EXE file as the remote host will see it. If you are debugging a DLL, specify an application that calls the DLL.

You can also enter the name of any executable that you want to run in the debugger. Then press Load to load the executable. The executable will be paused at its entry point. If there is no debug information at the entry point, the CPU window will be opened. Select Run|Run (F9) to run the executable.

Remote host

Enter the name or IP address of the computer on which you want to run the application. The remote host must have the debug server running on it.

Parameters

Enter the parameters you want to pass to the application when it starts.

You can use these parameters with the ParamCount and ParamStr() functions.

Do not enter the application name in this edit box.

Select the “Debug project on remote machine” check box to enable remote debugging.

The Load button loads the application, meaning that the process is loaded and stopped. The OK button accepts the settings, but does not load the application. On the Remote page, the Load button loads a source view of the remote application, but does not load the project (that is, the Project menus do not reflect that project).


RunRegister ActiveX server
Run|Register ActiveX server

See also

Choose Run|Register ActiveX Server to add a Windows registry entry for your ActiveX control.

Building the project creates an .OCX file that contains the ActiveX control. You must register the control so that it can be used by other applications such as Visual Basic, Delphi applications, other C++ applications, or Paradox for Windows. Registering the control adds an entry for it in the Windows registry.

To register the ActiveX control from the IDE, choose Run|Register ActiveX Server.


Run|Unregister ActiveX Server

Choose Run|Unregister ActiveX Server to remove the Windows registry entry for your ActiveX control.

To remove an ActiveX control from your system, it is recommended that you first remove its entry from the Windows registry. To unregister the ActiveX control from the IDE, choose Run|Unregister ActiveX Server.


Run|Install MTS Objects

See also

Choose Run|Install MTS Objects to allow the MTS objects in your application to be run in the MTS runtime environment. Before choosing this command,

Your project must be an MTS object.

The Microsoft transaction server (MTS) must installed on your machine.

Install MTS Objects displays a dialog that allows you to install your components into an MTS package.

Note:	Packages can contain components from multiple DLLs and components from a single DLL can be installed into different packages. However, a single component cannot be distributed among multiple packages.


Install Object Into New Package

See also

Choose Into New Package to create a new package in which to install your MTS object.

Package Name	Supply a name for the new MTS package.

Description	Provide a description of the MTS object.

Click OK to update the MTS catalog which makes the MTS objects available at runtime.


Install Object Into Existing Package

See also

Choose Into Existing Package to install your MTS object into an existing MTS package.

Package Name	Choose the MTS package from the list.

Description	Provide a description of the MTS object.

Click OK to update the MTS catalog which makes the MTS objects available at runtime.


Run|Step Over

See also

Choose Run|Step Over to execute a program one line at a time, stepping over procedures while executing them as a single unit.

The Step Over command executes the program statement highlighted by the execution point and advances the execution point to the next statement.

If you issue the Step Over command when the execution point is located on a function call, the debugger runs that function at full speed, then positions the execution point on the statement that follows the function call.

If you issue Step Over when the execution point is positioned on the closing brace of a function, the function returns from its call, and the execution point is placed on the statement following the function call.

The debugger considers multiple program statements on one line of text as a single line of code; you cannot individually debug multiple statements contained on a single line of text. The debugger also considers a single statement that spans several lines of text as a single line of code.

By default, when you initiate a debugging session with Run|Step Over, C++Builder moves the execution point to the first line of code that contains debugging information.

In addition to stepping over procedures, you can trace into them, following the execution of each line. Use Run|Trace Into to execute each line of a function.

An alternative way to perform this command is:

Choose the Step Over button on the toolbar.


Run|Trace Into

See also

Choose Run|Trace Into to execute a program one line at a time, tracing into functions and following the execution of each line.

The Trace Into command executes the program statement highlighted by the execution point and advances the execution point to the next statement.

If you issue the Trace Into command when the execution point is located on a function call, the debugger traces into the function, positioning the execution point on the function’s first statement.

If you issue Trace Into when the execution point is positioned on the closing brace of a function, the function returns from its call, and the execution point is placed on the statement following the function call.

If the execution point is located on a function call that does not have debugging information, such as a library function, the debugger runs that function at full speed, then positions the execution point on the statement following the function call.

By default, when you initiate a debugging session with Run|Trace Into, C++Builder moves the execution point to the first line of code that contains debugging information (this is normally a location that contains user-written code). To trace into start-up code that C++Builder automatically generates, see Stepping through code.

In addition to tracing into functions, you can step over them, executing each function as a single unit. Use Run|Step Over to execute functions as a single unit.

An alternative way to perform this command is:

Choose the Trace Into button on the toolbar.


Trace to Next Source Line
Run|Trace To Next Source Line

See also

Use this command to stop on the next source line in your application, regardless of the control flow. For example, if you select this command when stopped at a Windows API call that takes a callback function, control will return to the next source line, which in this case is the callback function.


Run|Run To Cursor

See also

Choose Run|Run To Cursor to run the loaded program up to the location of the cursor in the Code editor.

When you run to the cursor, your program is executed at full speed, then pauses and places the execution point on the line of code containing the cursor.

You can use Run To Cursor to run your program and pause before the location of a suspected problem. You can then use Run|Step Over or Run|Trace Into to control the execution of individual lines of code.

An alternate way to perform this command is:

Right-click the Code editor and choose Debug|Run to Cursor.


Run|Run Until Return

Choose Run|Run Until Return to run the loaded program until execution returns from the current function. The process stops on the instruction immediately following the instruction that called the current function.

Run Until Return is only available when your process is stopped in the debugger, and can be directed at a thread anytime it is stopped. When it is issued, the thread's stack is examined and the call-site of the current function is determined. Execution then resumes and stops when the thread attempts to return to the call site of the current function.


Run|Show Execution Point

See also

Choose Run|Show Execution Point to position the cursor at the execution point in an edit window. If you closed the edit window containing the execution point, C++Builder opens an edit window displaying the source code at the execution point.

If the execution point is at a location where there is no source code, the CPU window will be opened at the execution point and show the machine instructions.


Run|Program Pause

See also

Choose Run|Program Pause to temporarily pause the execution of a running program.

The debugger pauses program execution and positions the execution point on the next line of code to execute. You can examine the state of your program in this location, then continue debugging by running, stepping, or tracing.

In addition to temporarily pausing a program running in the debugger, you can also stop a program and release it from memory. Use Run|Program ResetIDH_MRunProgramReset to stop a running program and release it from memory.


Run|Program Reset

See also

Choose Run|Program Reset to end the current program run and release it from memory.

Use Program Reset to restart a program from the beginning, such as when you step past the location of a bug, or if variables or data structures become corrupted with unwanted values.

When you reset a program, C++Builder performs the following actions:

Closes all open program files

Releases resources allocated by calls to the VCL

Clears all variable settings

Resetting a program does not delete any breakpoints or watches you have set, which makes it easy to resume a debugging session.

Windows resources

Resetting a program does not necessarily release all Windows resources allocated by your program. In most cases, all resources allocated by VCL routines are released. However, Windows resources allocated by code which you have written might not be properly released.

If your system becomes unstable, through either multiple hardware or language exceptions or through a loss of system resources as a result of resetting your program, you should exit C++Builder before restarting your debugging session.


Run|Inspect command$ Inspect command
Run|Inspect

See also

Choose Inspect to open an Inspector window for the term highlighted (or at the insertion point) in the Code editor. If the insertion point is on a blank space when you choose this command, an empty Inspector window displays where you can enter an item you want to inspect.

After you enter a valid expression, choosing OK opens an Inspector window.

This command is only available when the integrated debugger is paused in a program you are debugging, such as when

you are stepping through code.

your program is stopped at a breakpoint.

you first choose Run|Run and then choose Run|Pause.

An alternate way to perform this command is:

Right-click, not on an expression, the Code editor and choose Debug|Inspect.


Run|Evaluate/Modify

See also

The Evaluate/Modify command opens the Evaluate/Modify dialog box, where you can evaluate or change the value of an existing expression.

An alternate way to perform this command is:

Right-click in the Code editor and choose Debug|Evaluate/Modify.


Run|Add Watch

See also

The Add Watch command opens the Watch Properties dialog box, where you can create and modify watches. After you create a watch, use the Watch List to display and manage the current list of watches.

Alternate ways to perform this command are:

Choose Debug|Add Watch at Cursor from the Code editor context menu.

Choose Add Watch from the Watch List context menu.

Right-click an existing watch in the Watch List and choose Edit Watch.


Run|Add Breakpoint

See also

Use the Run|Add Breakpoint menu commands to add breakpoints:

Source Breakpoint	Opens the Add Source Breakpoint dialog box where you can set a breakpoint on a specific line location in your source code. When you run your program, the execution point in the Code editor indicates the breakpoint location.

Address Breakpoint	Opens the Add Address Breakpoint dialog box where you can set a breakpoint on a specific machine instruction. When you run your program, the execution point in the CPU window Disassembly pane indicates the breakpoint location.

Data Breakpoint	Opens the Add Data Breakpoint dialog box where you can set a breakpoint on a specific address that halts execution when that address is written to.

Module Load Breakpoint	Opens the Add/Edit Module dialog box where you can halt execution on a module when it is loaded.

To edit these breakpoints:

Right-click and choose Add Breakpoint from the Breakpoint List context menu to bring up the Source, Address, and Data Breakpoint menus.

Choose View|Debug Windows|Modules and right-click in the Modules List Window. Right-click and choose Add Module from the Module window context menu.


Search menu

See also

Use the Search menu commands to locate text, objects, units, variables, and symbols in the Code editor.

Find	Searches for specific text, and highlights first occurrence in the code editor.

Find In File	Searches for specific text, displays each occurrence in a window at the bottom of the code editor.

Replace	Searches for specific text and replace it with new text.

Search Again	Repeats the last search.

Incremental Search	Searches for text as you type.

Go to Line Number	Moves cursor to specific line number

Go to Address	Goes to the specified address.


Search|Find

See also	Find In Files Tab

Choose Search|Find to display the Find Text dialog box.

Find Text dialog box

Select the Find tab to specify text you want to locate and to set options that affect the search. Find locates the line of code containing the first occurrence of the string and highlights it.

Dialog box options

Text to find

Enter a search string or click the down arrow next to the input box to select from a list of previously entered search strings.

Options	Specified attributes for the search string

Case sensitive	Differentiates uppercase from lowercase when performing a search.

Whole words only	Searches for words only. (With this option off, the search string might be found within longer words.)

Regular expressions	Recognizes regular expressions in the search string.

Direction	Direction to search, starting from the current cursor position

Forward	From the current position to the end of the file. Forward is the default.

Backward	From the current position to the beginning of the file.

Scope	How much of the file is searched

Global	Searches the entire file, in the direction specified by the Direction setting. Global is the default scope.

Selected text	Searches only the selected text, in the direction specified by the Direction setting. You can use the mouse or block commands to select a block of text.

Origin	Where the search starts

From cursor	The search starts at the cursor's current position, and then proceeds either forward to the end of the scope, or backward to the beginning of the scope depending on the Direction setting. From Cursor is the default Origin setting.

Entire scope	The search covers either the entire block of selected text or the entire file (no matter where the cursor is in the file), depending upon the Scope options.


Search | Find in file
Search|Find in files

See also	Find Tab

Choose Search|Find in files to list occurrences of a specified string.

Find in file dialog box

Select the Find in Files tab to specify text you want to locate and to set options that affect the search. Each occurrence of the string is listed in a box at the bottom of the Code editor. Double-click a list entry to move to that line in the code file.

Text to find

Enter a search string.  To select from a list of previously entered search strings, click the down arrow next to the input box.

Options	Attributes for the search string:

Case sensitive	Differentiates uppercase from lowercase when performing a search.

Whole words only	Searches for words only. (With this option off, the search string might be found within longer words.)

Regular expressions	Recognizes regular expressions in the search string.

Where	Which files to search:

Search all files in project	Searches all files in the open project.

Search all open files	Searches files that are currently open.

Search in directories	When selected, the Search Directories options are available. The search proceeds through all files indicated.

Search directory options	Defines the full path to file(s) to be searched:

File masks	Specify the path of the files to be searched. By default, only .CPP, .C, .H, .HPP, and .BPR files are searched. To search other files, use a wildcard entry (such as *.* or *.txt) at the end of the path. To enter multiple masks, separate the masks with semicolons.

Include subdirectories	If selected, subdirectories from the directory path specified are also searched.


Search|Replace

See also

Choose Search|Replace to display the Replace Text dialog box.

Replace Text

Use this dialog box to specify text you want to search for and then replace with other text (or with nothing).

Most components of the Replace Text dialog box are identical to those in the Find Text dialog box.

Text to find

Enter a search string. To select from a list of previously entered search strings, click the down arrow next to the input box

Replace with

Enter the replacement string. To select from a list of previously entered search strings, click the down arrow next to the input box. To replace the text with nothing, leave this input box blank.

Options	Attributes for the search strings:

Case sensitive	Differentiates uppercase from lowercase when performing a search.

Whole words only	Searches for words only. (With this option off, the search string might be found within longer words.)

Regular expressions	Recognizes specific regular expressions in the search string.

Prompt on replace	Prompts you before replacing each occurrence of the search string. When Prompt on replace is off, the editor automatically replaces the search string.

Direction	Which direction to search the file

Forward	From the current cursor position, to the end of the file. Forward is the default Direction setting.

Backward	From the current cursor position, to the beginning of the file.

Scope	How much of the file is searched:

Global	The entire file, in the direction specified by the Direction setting. Global is the default scope.

Selected text	Only the selected text, in the direction specified by the Direction setting. To select a block of text, use the mouse or block commands.

Origin	Where the search should start:

From cursor	The search starts at the cursor's current position, and proceeds either forward to the end of the scope, or backward to the beginning of the scope depending on the Direction setting. From cursor is the default Origin setting.

Entire scope	The search covers either the entire block of selected text or the entire file (no matter where the cursor is in the file), depending upon the Scope options.

Replace All

Click Replace all to replace every occurrence of the search string. If you check Prompt on replace, the Confirm dialog box appears on each occurrence of the search string.


Search|Search Again

See Also

Choose Search|Search Again to repeat the last Find or Replace command.

The settings last made in the Find Text or Replace Text dialog box remain in effect when you choose Search Again. For instance, if you have not cleared the Replace Text settings, the Search Again command searches for the string you last specified and replaces it with the text specified in the Replace Text dialog box.


Search|Incremental Search

See Also

Choose Search|Incremental Search to bypass the Find Text dialog box by moving the cursor directly to the next occurrence of text that you type.

When you are performing an incremental search, the Code editor status line reads "Searching For:" and displays each letter you have typed.

For example, if you type "class" the cursor moves to the next occurrence of the word, highlighting each letter as you type it. This behavior continues until a new occurrence of the string is not found, the editor loses focus, or you press Enter or Esc.

Here are some Incremental Search keystroke options:

Option	Effect

Backspace	Remove the last character from the search string and move to the previous match.

F3	Repeat search   (Default keybinding)

Ctrl+L	Repeat search   (Classic keybinding)

Ctrl+S	Repeat search   (Epsilon keybinding)

Shift+F5	Repeat search   (Brief keybinding)


Search|Go to Line Number

Choose Search|Go to Line Number to display the Go To Line Number dialog box.

Go to Line Number dialog box

This dialog box prompts you for number of the line you want to find. The current line number and column number are displayed in the Line and Column Indicator on the status bar of the Code editor.

When this dialog box first appears, the current line number is in the input box.

Enter New Line Number	 Specify the line number of the code you want to go to. To select from a list of previously entered line numbers, click the down arrow next to the input box.


Search|Go to Address

Choose Search|Go to Address to display the Goto Address dialog box.

Note that this option is only available while debugging your program.

Goto Address dialog box

Use this dialog box to specify the address of the most recent runtime error during an integrated debugging session or an address that you want to jump to.

Address

Enter the address you want to jump to and click OK. You can enter the address in decimal or hexadecimal, or you can enter a function name that will evaluate to an address (for example, WinMain).

When you click OK, C++Builder displays the address location in the source file or it displays the CPU window with the address highlighted in various panes. You can view low-level information about the program in the CPU window.


Regular expressions

See also

Regular expressions are characters that customize a search string. C++Builder recognizes these regular expressions:

Character	Description

 ^	A circumflex at the start of the string matches the start of a line.

 $	A dollar sign at the end of the expression matches the end of a line.

 .	A period matches any character.

 *	An asterisk after a string matches any number of occurrences of that string followed by any characters, including zero characters. For example, bo* matches bot, bo and boo but not b.

 +	A plus sign after a string matches any number of occurrences of that string followed by any characters except zero characters. For example, bo+ matches boo, and booo, but not bo or be.

[ ]	Characters in brackets match any one character that appears in the brackets, but no others. For example [bot] matches b, o, or t.

[^]	A circumflex at the start of the string in brackets means NOT. Hence, [^bot] matches any characters except b, o, or t.

[-]	A hyphen within the brackets signifies a range of characters. For example, [b-o] matches any character from b through o.

{ }	Braces group characters or expressions. Groups can be nested, with a maximum number of 10 groups in a single pattern. . For the Replace operation, the groups are referred to by a backslash and a number according to the position in the “Text to find” expression, beginning with 0. For example, given the text to find and replacement strings, Find: {[0-9]}{[a-c]*}, Replace: NUM\1, the string 3abcabc is changed to NUMabcabc.

  \  	A backslash before a wildcard character tells the Code editor to treat that character literally, not as a wildcard. For example, \^ matches ^ and does not look for the start of a line.

Note:	C++Builder also supports Brief regular expressions if you are using Brief keystroke mappings.


Brief regular expressions

See also

Use these symbols to produce Brief regular expressions:

 <	A less than at the start of the string matches the start of a line.

 %	A percent sign at the start of the string matches the start of a line.

 $	A dollar sign at the end of the expression matches the end of a line.

 >	A greater than at the end of the expression matches the end of a line.

  ?	A question mark matches any single character.

 @	An at sign after a string matches any number of occurrences of that string followed by any characters, including zero characters. For example, bo@ matches bot, boo, and bo.

 +	A plus sign after a string matches any number of occurrences of that string followed by any characters, except zero characters. For example, bo+ matches bot and boo, but not b or bo.

  |	A vertical bar matches either expression on either side of the vertical bar. For example, bar|car will match either bar or car.

  ~	A tilde matches any single character that is not a member of a set.

[ ]	Characters in brackets match any one character that appears in the brackets, but no others. For example [bot] matches b, o, or t.

[^]	A circumflex at the start of the string in brackets means NOT. Hence, [^bot] matches any characters except b, o, or t.

[-]	A hyphen within the brackets signifies a range of characters. For example, [b-o] matches any character from b through o.

{ }	Braces group characters or expressions. Groups can be nested, with the maximum number of 10 groups in a single pattern.

  \  	A backslash before a wildcard character tells the IDE to treat that character literally, not as a wildcard. For example, \^ matches ^ and does not look for the start of a line.


Tools menu

See also

Use the Tools menu to:

View and change environment settings

View and change debugger settings

Modify items in the Object Repository.

Start the Visibroker SmartAgent.

Update an interface repository to include CORBA IDL files from the current project.

Modify the list of programs on the Tools menu

Create and modify local database tables.

Create and edit package collections.

Create and edit images.

Default Tools menu commands:

Environment Options	Specifies Editor, Browser, and configuration preferences, and customizes the appearance of the Component palette.

Debugger Options	Displays the Debugger Options dialog box.

Repository	Displays the Object Repository dialog box.

Visibroker SmartAgent	Starts or stops the Visibroker SmartAgent.

IDL Repository	Displays the Update IDL Repository dialog box.

Configure Tools	Displays the Tools Options dialog box. Use this dialog box to add commands to, delete commands from, or edit commands on the Tools menu.

Optional tools:

DataBase Desktop	Displays the database desktop where you can create, view, sort, modify, and query tables in Paradox, dBASE, and SQL formats.

Package Collection Editor	Create and edit package collections. Package collections are a convenient way to bundle packages and associated files for distribution to other developers.

Image Editor	Create and edit resource files, icons, bitmaps, and cursor files for use in applications.

Items representing other installed or custom tools may also appear on this menu.


Tools|Environment Options

Choose Tools|Environment Options to display the Environment Options dialog box. Use the pages of this dialog box to specify editor and configuration preferences, and to customize the way components and pages are arranged on the Component palette.

The pages of the Environment Options dialog box are:

Preferences

Library

Editor

Display

Colors

Palette

Code Insight

ClassExplorer

CORBA

To change pages in the dialog box:

Click the tab at the top of the dialog box that represents the page you want to use.

Note:	Program arguments are specified in the Tools|Environment Options dialog box and are passed when the program is invoked. If a program requires arguments to be entered at runtime, you can supply them on the Tool Properties dialog box.


Tools|Environment Options - Preferences options
Preferences (Tools|Environment Options)

See also	Environment options

Use the Preferences page of the Environment Options dialog box to specify your configuration preferences.

Compiling options

Check box	When checked

Show compiler progress	A progress report dialog box appears while your program compiles.

Beep on completion	C++Builder beeps when your compilation is finished.

Cache headers on startup	Compiled header files are placed in memory on startup. These pre-compiled header files are then available for all C++Builder compiles you make in that session.

Warn on package rebuild	A warning appears when packages are rebuilt during compile.

Autosave options

Specify which files and options are saved automatically by the environment or when you run your program. A check mark means it is enabled.

Check box	When checked

Editor Files	Saves all modified files in the Code editor when you choose Run|Run, Run|Trace Into, Run|Step Over, Run|Run To Cursor, or when you exit C++Builder.

Desktop	Saves the arrangement of your desktop when you close a project or exit C++Builder. When you later open the same project, all files opened when the project was last closed are opened again regardless of whether they are used by the project.

Form designer

Set grid preferences that make it easier to design forms.

Option	Effect

Display Grid	Displays dots on the form to make the grid visible.

Snap To Grid	Automatically aligns components on the form with the nearest gridline. You cannot place a component "in between" gridlines.

Grid Size X	Sets grid spacing in pixels along the x-axis. Specify a higher number (between 2 and 128) to increase grid spacing.

Grid Size Y	Sets grid spacing in pixels along the y-axis. Specify a higher number (between 2 and 128) to increase grid spacing.

Show Component Captions	Select this option to display component captions.

Show Designer Hints	Toggles help hints on the surface of the form designer. Note that this option only affects hints that appear when you pause the mouse over a component in a form or data module: help hints are always enabled in the component palette.

Running

Check box	When checked

Minimize On Run	Minimizes C++Builder when you run your application by choosing Run|Run. When you close your application C++Builder is restored.

Hide Designers On Run	Hides designer windows, such as the Object Inspector and Form window, while the application is running. The windows reappear when the application closes.

Shared Repository

Option	Effect

Directory	Specifies the location where C++Builder looks for the Object Repository file. If this field is empty, C++Builder looks for the file in the BIN directory.


Tools|Environment Options - Library
Library page (Tools|Environment Options)

See also	Environment options

Use this page to specify directories, compiler, and linker options for all packages. Click the down arrow next to the edit boxes to choose from a list of previously entered symbols.

Directory	Description

Library path	Specifies where to find C++ header and library files for installed components and packages. Include in this path:

Include Path for the header files used by the VCL

Library Path for VCL object files, resource files, and Delphi unit files

Path to libraries you want all of your projects to find.

BPL output directory	Where the compiler should put compiled packages (.BPL) files.

BPI/LIB output path	Specifies where Package BPI and LIB files are placed by default. The default specified here can be overridden in individual packages by using the package options

Browsing path	Specifies directories where the Code Browser looks for files when it cannot find an identifier on the project Search path or Source path.

Edit controls that permit multiple values have an ellipses button to the right. Click this button to add multiple values using a List Entry dialog. Alternately, you can specify multiple values by separating them with semicolons. See Search Directories for more information on setting search directories in C++Builder.

Note:	You can enter a path relative to your C++Builder root directory using the $(BCB) environment macro.


Tools|Environment Options - Editor Options
Editor (Tools|Environment Options)

See also	Environment options

Use the Editor page of the Environment Options dialog box to customize the behavior of the code editor.

Editor SpeedSetting

Use the Editor SpeedSettings to configure the editor. The drop-down list includes pre-configured default settings that can be customized.

Note:	this provides a quick way to set the Editor options. To set the keyboard mappings in the editor, use the Display page.

Option	Automatically sets

Default Keymapping	Auto Indent Mode, Insert Mode, Smart Tab, Backspace Unindents, Group Undo, Overwrite Blocks, Use Syntax Highlight

IDE Classic	Auto Indent Mode, Insert Mode, Smart Tab, Backspace Unindents, Cursor Through Tabs, Group Undo, Persistent Blocks, Use Syntax Highlight

Brief Emulation	Auto Indent Mode, Insert Mode, Smart Tab, Backspace Unindents, Cursor Through Tabs, Cursor Beyond EOF, Keep Trailing Blanks, Brief Regular Expressions, Force Cut And Copy Enabled, Use Syntax Highlight

Epsilon Emulation	Auto Indent Mode, Insert Mode, Smart Tab, Backspace Unindents, Cursor Through Tabs, Group Undo, Overwrite Blocks, Use Syntax Highlight

Visual Studio Emulation	Auto Indent Mode, Insert Mode, Smart Tab, Backspace Unindents, Cursor Through Tabs, Group Undo, Overwrite Blocks, Use Syntax Highlight

Editor Options check boxes

Use the following editor options to control text handling in the Code editor. Check the option to enable it.

Check box	When selected

Auto Indent Mode	Positions the cursor under the first nonblank character of the preceding nonblank line when you press Enter.

Insert Mode	Inserts text at the cursor without overwriting existing text. If Insert Mode is disabled, text at the cursor is overwritten. (Use the Ins key to toggle Insert Mode in the Code editor without changing this default setting.)

Use Tab Character	Inserts tab character. If disabled, inserts space characters. If Smart Tab is enabled, this option is off.

Smart Tab	Tabs to the first non-whitespace character in the preceding line. If Use Tab Character is enabled, this option is off.

Optimal Fill	Begins every autoindented line with the minimum number of characters possible, using tabs and spaces as necessary.

Backspace Unindents	Aligns the insertion point to the previous indentation level (outdents it) when you press Backspace, if the cursor is on the first nonblank character of a line.

Cursor Through Tabs	Enables the arrow keys to move the cursor to the logical spaces within each tab character.

Group Undo	Undoes your last editing command as well as any subsequent editing commands of the same type, if you press Alt+Backspace or choose Edit|Undo.

Cursor Beyond EOF	Positions the cursor beyond the end-of-file character.

Undo After Save	Allows you to retrieve changes after a save.

Keep Trailing Blanks	Keeps any blanks you might have at the end of a line.

Brief Regular Expressions	Uses Brief regular expressions.

Persistent Blocks	Keeps marked blocks selected even when the cursor is moved, until a new block is selected.

Overwrite Blocks	Replaces a marked block of text with whatever is typed next. If Persistent Blocks is also selected, text you enter is appended following the currently selected block.

Double Click Line	Highlights the line when you double-click any character in the line. If disabled, only the selected word is highlighted.

Find Text At Cursor	Places the text at the cursor into the Text To Find list box in the Find Text dialog box when you choose Search|Find. When this option is disabled you must type in the search text, unless the Text To Find list box is blank, in which case the editor still inserts the text at the cursor.

Force Cut And Copy Enabled	Enables Edit|Cut and Edit|Copy, even when there is no text selected.

Use Syntax Highlighting	Enables syntax highlighting. To set highlighting options, use the Colors page.

Other options	When selected

Block Indent 	Specify the number of spaces to indent a marked block. The default is 2; the upper limit is 16. If you enter a value greater than 16, you will receive an error.

Undo Limit 	Specify the number of keystrokes that can be undone. The default value is 32,767 (32K).

Note:	The undo buffer is cleared each time C++Builder generates code.

Tab Stops 	Set the character columns that the cursor will move to each time you press Tab. If each successive tab stop is not larger than its predecessor, you will receive an error.

Syntax Extensions 	Specify, by extension, which files will display syntax highlighting information. The default extensions are .CPP, .C, .HPP, .H, .HH, .CXX, and .HXX.


Tools| Environment Options - Display
Display (Tools|Environment Options)

See also	Environment options

Use the Display page of the Environment Options dialog box to select display and font options for the Code editor. The sample window displays the selected font.

The new settings take effect when you click OK.

Display and File check boxes

Configure the editor's display and choose how it saves files.

Check box	Effect

Brief Cursor Shapes	Uses Brief cursor shapes.

Create Backup File	Creates a backup file that replaces the first letter of the extension with a tilde (~) when you choose File|Save.

Preserve Line Ends	Preserves end-of-line position.

Zoom To Full Screen	Maximizes the Code editor to fill the entire screen. When this option is off, the Code editor does not cover the main window when maximized.

Keystroke Mapping

Enables you to quickly switch key bindings.

Mapping	Effect

Default	Uses key bindings that match CUA mappings (default)

Classic	Uses key bindings that match Borland Classic editor keystrokes

Brief	Uses key bindings that emulate most of the standard Brief keystrokes

Epsilon	Uses key bindings that emulate a large part of the Epsilon editor

Visual Studio	Uses key bindings that emulate a large part of the Visual Studio editor

Visible Right Margin 	Check to display a line at the right margin of the Code editor.

Right Margin 	Set the right margin of the Code editor. The default is 80 characters. The valid range is 0 to 1024. If you enter a value larger than 1024, an error message appears.

Visible gutter 	Check to display the gutter on the left edge of the Code editor.

Gutter width 	Set the width of the gutter, default is 32.

Editor Font 	Select a font type from the available screen fonts installed on your system (shown in the list). The Code editor displays and uses only monospaced screen fonts, such as Courier. Sample text is displayed below the combo box.

Size 	Select a font size from the predefined font sizes associated with the font you selected in the Font list box. Sample text is displayed below the combo box.

Sample text 	Displays a sample of the select editor font and size.


Tools|Environment Options - Color
Colors (Tools|Environment Options)

See also	Environment options

Use the Color page of the Environment Options dialog box to specify how the different elements of your code appear in the Code editor.

You can specify foreground and background colors for anything listed in the Element list box. The sample Code editor shows how your settings will appear in the Code editor.

Color SpeedSettings

Enables you to quickly configure the Code editor display using predefined color combinations. The sample Code editor shows how your settings will appear in the Code editor.

Option	Effect

Defaults	Displays reserved words in bold. Background is white.

Classic	Displays reserved words in light blue and code in yellow. Background is dark blue.

Twilight	Displays reserved words and code in light blue. Background is black.

Ocean	Displays reserved words in black and code in dark blue. Background is light blue.

Element

Specifies syntax highlighting for a particular code element. You can choose from the Element list or click the element in the sample Code editor.

The element options are:

Whitespace	Marked block

Comment	Search match

Reserved Word	Execution point (for debugging)

Identifier	Enabled break (for debugging)

Symbol	Disabled break (for debugging)

String	Invalid break (for debugging)

Integer	Error line

Float	Preprocessor

Ocatal	Illegal char

Hex	Plain text

Character	Right margin

Color Grid

Sets the foreground (FG) and background (BG) colors for the selected code element.

To select a color using the mouse, choose one of the following methods:

Click a color to select it as the foreground color.

Right-click a color to select it as the background color.

If you choose the same color for the foreground and the background, it is marked as FB (this is not recommended, as you will be unable to read any text).

To select the color using the keyboard:

1.	Use the arrow keys to highlight a color.

2.	Press F to select it as the foreground color, or B to select it as the background color.

Text Attributes check boxes

Specify format attributes for the code element. The attribute options are:

Bold

Italic

Underline

Use defaults for check boxes

Display the code element using default Windows system colors (foreground, background, or both).

Unchecking either option restores the previously selected color or, if no color has been previously selected, sets the code element to the Windows system color.

Note: To change the Windows system colors, use the Windows Control Panel.


Using syntax highlighting

See also

Syntax highlighting changes the colors and attributes of your text in the Code editor, making it easier to quickly identify parts of your code.

To enable syntax highlighting:

On the Editor page of the Tools|Environment Options dialog box, check the Use Syntax Highlight option.

To change the syntax highlighting colors for elements of your code:

Use the Colors page of the Tools|Environment Options dialog box.


Tools|Environment Options - Palette
Palette (Tools|Environment Options, Component|Configure Palette)

See also	Environment options

Use the Palette page of the Environment Options dialog box to customize the way the component palette appears. You can rename, add, remove, or reorder pages and components.

Pages	Lists the pages in the component palette, in the order in which they currently appear. You can rearrange these pages or view and rearrange their components in the Components list. The last item in the Pages list is [All]; when you select [All], the Components list shows components from every page as well as hidden components.

Components 	Lists the components on the currently selected Component-palette page in the Pages list. Components may come from installed packages or they may be component templates created with the Component|Create Component Template command. Components appear in their current order on the palette. You can rearrange components, or move them to a different page, by dragging them. When [All] is selected in the Pages list, you can sort by component name, package, or palette page by clicking on the appropriate column heading.

Use the following buttons when an item is selected in the Pages list.

Add 	Click Add to display the Add Page dialog box, where you can create new pages on the Component palette. Once you have created a new Component palette page, you can move components from other pages onto it or add new components to it using Component|Install.

Delete 	To remove the selected page from the palette, click Delete. Before you can delete a page, it must be empty of components. If you accidentally delete a component, select [All] in the Pages list and press Default Pages, or use Component|Install to re-add it.

Rename 	Click Rename to display the Rename Page dialog box, where you can rename the selected page.

Default Pages	Click Default Pages to restore pages to their default order and replace all components on their default pages. This button is available when [All] is selected on the Pages list.

Move Up / Move Down	To change the position of the selected page, click Move Up or Move Down. You can also drag pages to a new position.

Use the following buttons when an item is selected in the Components list.

Hide / Show	To prevent an installed component from appearing on the Component palette, click Hide. To redisplay a hidden component, select [All] on the Pages list, select the hidden component on the Components list, then click Show.

Delete	To delete a component template, click Delete. This button is available only when a component template is selected.

Move Up / Move Down	To change the position of a component on a page, click Move Up or Move Down. You can also drag components to a new position.


Rename Page dialog box

See also

Use this dialog box to specify a new name for a page on the Component Palette.

To open this dialog box:

On the Palette page of the Tools|Environment Options dialog box, select the page to rename and click the Rename button.

Page Name	Enter the new name for the page in the Page Name edit box. When you click OK, the new name is reflected in the Pages list box, but the new name is not reflected in the Component palette until you click OK in the Environment Options dialog box.

To exit this dialog box without changing the page name, choose Cancel.


Add Page dialog box

See also

Use this dialog box to add a new page to the Component palette.

The new page is added to the end of the Pages list. You can change the position of the page using the Palette page of the Tools|Environment Options dialog box.

To open this dialog box:

Click the Add button on the Palette page of the Tools|Environment Options dialog box.

Page Name	Enter the new name for the page in the Page Name edit box. When you click OK, the new name is added in the Pages list box, but the new page is not added to the Component palette until you click OK in the Environment Options dialog box.

To exit this dialog box without changing the page name, choose Cancel.


About Code Insight

See also

Code Insight is a set of tools that support you while you are writing code by doing the following:

Display information in the Code editor to help you with code syntax and arguments

Provide common programming statements for you to insert in your code

Display classes, functions, methods, arguments, and events parameter lists

Show you the value of a variable while debugging

Display declaration information for identifiers

The information displayed by these tools is created dynamically from your code. This means that Code Insight can display information about a method or declaration that you just finished writing. Code Insight references compiled code in binary files and the non-compiled code that you are currently typing into the editor.

Some of the features can be set for automatic display and others are instigated by pressing a key combination. To enable and configure Code Insight features, select Tools|Environment Options and display the Code Insight page.

Code Insight provides five tools:

Code completion

Code completion displays a list box that includes the names of the methods and fields of an object. When enabled, the Code completion list box is automatically displayed after you enter

The name of a class object followed by a period
For example, type
TRect test;
test.
then the list of members of the class is automatically displayed.

For pointers to objects, the arrow
For example, type this-> to display the list.

The list of properties, methods, events, and variables belonging to the class, function, or struct are displayed. Select the item to be entered in your code and press Enter.

You can also use code completion to list the variables that can be legally inserted after an assignment operator. Type the name of an object, and then Press Ctrl+-Space to see a list of the methods it supports. Select an argument to be entered in your code. Similarly, you can display a list of arguments when typing a function or method call and need to add an argument, or when you are typing an array property (not a genuine array) and you need to type an index expression.

Note:	Code completion and code parameter features work best when you have already built your application and have created a precompiled header. Otherwise, you need to wait for the compiler to generate the required information.

Code parameters

This tool displays a dialog that tells you the names and types of the parameters for a function or method. Therefore, you can view the required arguments for a function or method as you enter it into your code. If automatic Code parameters is enabled, a list box appears when you enter a routine or method call followed by the opening parenthesis; the syntax for the arguments is displayed. Press Shift+Ctrl+Spacebar to display the list box at any time, whether or not Code parameters is on automatic.

Code templates

A set of code templates is available to insert commonly used programming statements into your source code. C++Builder comes with a set of templates for basic code constructs that can be easily inserted into your code. Some of the constructs covered by the default templates include class declarations, if statements, for statements, and while loops.

While working in the Code editor, press Ctrl+J to display the code templates defined. Double-click on any one of them to insert it into your code.

Many default templates with C++Builder, and you can add as many as you like. Templates can be edited and added from the Code Insight page (Tools|Environment Options).

Tooltip expression evaluation

To make it easy to see the value of a variable at any point, enable Tooltip expression evaluation. (To enable Tooltip expression evaluation, use the Code Insight dialog box.) When you are debugging and you’re stopped, you can point to a variable to display its value at that time. If the compiler must determine the value, you may see a blinking bubble that says "Evaluating" rather than showing the value immediately.

Tooltip Symbol Insight

Tooltip Symbol Insight displays declaration information for any identifier when you pass the mouse over it in the Code editor. A pop-up window shows the kind identifier (function, type, constant, variable, unit, and so forth) and the unit file and line number of its declaration.

Warning:	Code Insight is not enabled unless you have a project open in the IDE. For example, when working on a package, you can’t use Code Insight.


Tools|Environment Options - Code Insight
Code Insight (Tools|Environment Options)

See also	Environment options

Use the Code Insight page to configure Code Insight options. Code Insight tools are available while you are working in the Code editor.

Automatic Feature	When Enabled

Code completion	When you enter a class name followed by a period or a pointer followed by an arrow in the Code editor, the list of properties, methods and events appropriate to the class or struct is displayed. You can then select the item and press Enter to add it to your code.

Enter an assignment statement and press Ctrl+Spacebar. A list of arguments that are valid for the variable is displayed. Select an argument to be entered in your code.

Code parameters	View the syntax of a prototype method as you enter it into your code.

Tooltip expression evaluation	When the compiler is stopped while debugging, you can view the value of a variable by pointing to it with your cursor.

Tooltip symbol insight	Display declaration information (in a pop-up window) for any identifier by passing the mouse over it in the Code editor.

Delay	Set the duration of the pause before a Code Insight dialog box is displayed.

Code templates	Available code templates are listed by name with a short description. Click a template name to display the code that will be entered in your file when that template is selected. Code displayed in the code window can be edited.

Templates	The Templates box includes a name and short description of each template.

Code	The code box displays the code that will be inserted into a file when the template is selected. The code displayed can be edited.

Adding, editing, and deleting code templates

You can add, edit or delete code templates from the Code Insight page of the Environment Options dialog box:

To edit a template’s name and description:
Select the name you want to edit. Click Edit. Edit the name and description fields as needed and click OK.

To edit a template:
When a name is selected, the code to be inserted in the file when the template is selected is displayed in the edit list box. Edit the text as needed.

To define the insertion point for a template:
Place a vertical bar in the code statement to define the point to begin insertion when the template is inserted in a code file. The cursor will be placed in the location defined by the vertical bar.

To add a template:
Click Add. After entering a Name and Description in the dialog box displayed, click OK. The cursor will move to the code window for you to define the code that will be entered in a file when the template is selected.

To delete a template:
Select the name of the template you want to delete. Click Delete.

Warning:	Code Insight is not enabled unless you have a project open in the IDE. For example, when working on a package, you can’t use Code Insight.


Code completion

See also

The code completion list box lists the valid properties, methods, and events for the name of a class object that you entered. You can right-click on the list to sort the items by name or by scope.

Arguments that are valid for assignment to the variable entered are listed. Select an item from the list followed by the ellipsis (…) to open a second list of related arguments compatible with the variable entered in the assignment statement.

Select an item to be entered in your code file in either of two ways:

Scroll through the list if necessary and double-click the item.

Type until the characters entered refer to the entry in the list you want to include and press Enter.

Preferences for code completion are configured by selecting Tools|Environment Options to open the Environment Options dialog box. Select the Code Insight page.


Code templates

Code templates include commonly used programming statements (such as if, while, and for statements) that you can insert into your code. The templates defined for your installation and some provided by default are listed. Select a code template to be entered in your code file in one of these ways:

Use the scroll bar as necessary then double-click on the template to insert in your code.

Type the name of the template until the characters entered refer to the entry in the list you want to include. Press Enter.

Use the scroll bar as necessary then double-click on the template to insert in your code.

Code templates are defined using the Environment Options dialog box. Select Tools|Environment Options and select the Code Insight page.


Tools|Environment Options - CORBA
CORBA (Tools|Environment Options)

See also	Environment options

Use the CORBA page to specify whether certain CORBA dialogs appear.

Update Object Options

These options affect the way C++Builder responds when you choose CORBA Refresh.

Show Updates	If checked, when you refresh your implementation classes to reflect changes in the IDL files, C++Builder displays the Project Updates dialog so that you can view and edit any changes before they are committed. When Unchecked, your implementation units are automatically updated without showing the Project Updates dialog.

IDL File Options

These options affect the way C++Builder responds when you add an IDL file to your project.

Verify IDL include files	If checked, when you add an IDL file to your project, C++Builder checks whether it contains any #include statements, and if so, checks that the included IDL files are also included in the project. If implicitly included IDL files are not already part of the project, C++Builder displays the Add Included IDL files dialog, so that you can add them.


Tools|Environment Options - Explorer
ClassExplorer (Tools|Environment Options)

See also	Environment options

The ClassExplorer contains a tree diagram that shows all the classes, properties, methods, and global routines defined in the unit that is currently displayed in the Code editor. Use the ClassExplorer page of the Environment Options dialog box to select options for the ClassExplorer. The new settings take effect when you click OK.

General

Check box	Effect

Automatically show Explorer	ClassExplorer appears docked onto the Code editor. When unchecked, use View|ClassExplorer to display.

Show Warnings	ClassExplorer shows messages on non critical errors, e.g. when a source file could not be read.

Class view

Check box	Effect

Show Field Types	The tree view of classes (Class view) displays type information on fields.

Show method Arguments	The tree view of classes (Class view) displays the arguments for all methods.


Tools|Debugger Options
Debugger Options (Tools|Debugger Options)

Choose Tools|Debugger Options to display the Debugger Options dialog box containing several tabbed pages of settings:

General

Event Log

Language Exceptions

OS Exceptions

Distributed Debugging

Integrated debugging check box: Check to set the Integrated Debugger to active.


Debugger|Options - General
General (Tools|Debugger Options)

Use the General page of the Debugger Options dialog box to set general debugger options primarily for the user interface. Check the options you want to use.

Option	Description

Map TD32 keystrokes on run	Allows you to use the keystrokes from TD32 in the IDE. It will automatically turn on Mark buffers read-only on run.

Mark buffers read-only on run	Marks all editor files, including project and workgroup files, read-only when the program is run. When this option is selected, it will not change the attributes of the files after the program terminates. If the file was not marked read-only before running the program, C++Builder will change the attributes of the file back to their original configuration after the program terminates.

Inspectors stay on top	Keeps all debugger inspector windows visible when they are not active.

Rearrange editor local menu on run	Moves the Debugger area of the Code editor context menu to the top when you run a program from the IDE to more easily access the Debugger commands. Display the Code editor context menu by right-clicking anywhere in the Code editor window.

Allow side effects in new watches	Causes the watch to be evaluated even if doing so would cause side effects. Can be set for individual watches using the Watch Properties dialog. By default, this option is not set.

Disable multiple evaluators	Invokes only the C++ evaluator. If not set, both the C++ and Pascal evaluators are used as needed.

Debug spawned processes	Automatically debugs process which are spawned by the process you are debugging. If not checked, spawned processes are run but are not under control of the debugger.


Debugger|Options - Distributed Debugging
Distributed Debugging (Tools|Debugger Options)

See also

Use the Distributed Debugging page of the Debugger Options dialog box to set debugger options for remote debugging (available only when using the Enterprise edition).

Option	Description

Enable COM cross-process support	Cross-process stepping option that lets you step into remote COM processes while debugging. Also, adds COM events to the event log. This option is off by default.

Enable CORBA cross-process support	Cross-process stepping option that lets you step into remote CORBA processes while debugging. When checked, the controls in the ORB events list box are enabled and you can set options for each ORB event that the debugger sends notifications for. For each event, you can define any number of action sets. This option is off by default.

ORB Events list box	Set options for different ORB events that the debugger knows about. The Enable CORBA cross-process support option must be checked to access ORB events. Click the event you want to set options for and add/remove actions using the Actions list box.

Actions list box	Lists relevant actions for the selected ORB event. Add or remove actions for selected ORB events.

Integrated debugging check box	Check to set the Integrated Debugger to active. This option is on by default.


ORB events

See also

When the Enable CORBA cross-process support option is checked on the Tools|Debugger Options|Distributed Debugging page, the controls in the ORB events list box are enabled. You can set options for each ORB event that the debugger sends notifications for. All of these events are automatically logged in the event log if the CORBA option is checked.

For each event, you can define any number of action sets. An action set consists of one or two actions and one or more optional conditions.

Actions

The possible actions are

Action	Description

Log Event	Adds the event to the event log. On by default for all ORB events.

Break on Event	Stops the process when the event occurs.

ORB Events and Conditions

You can set specified conditions for the ORB events listed below in Conditions for each ORB event. The possible conditions depend on which event is selected.

For example, on the client side, you could set interface, object, and operation conditions for SendRequest. You could specify that the interface=Account, the object=Jack B. Quick (the instance of Account or a person’s account), and the operation =balance. If you check Break on Event when setting these conditions, processing stops when a request is sent from a client to a server to get Jack B. Quick’s account balance).

To set actions and conditions for an ORB event:

1.	Check the Enable COM cross-process support option on the Distributed Debugging page of the Debugger Options dialog box.

2.	Select the event for which you want to set conditions.

3.	Click Add.

The ORB event dialog box with appropriate conditions is displayed. (Some events have no conditions, others have one, two, or three.) The name of the ORB event is in the header.

4.	Specify one or two actions (Log Event or Break on Event) you want to perform when the event occurs.

5.	Optional: Specify under what conditions you want the specified action to take place for that ORB event. Type the name of a valid interface, object, and/or operation (depending on which fields are available in the dialog box).

6.	Click OK.

7.	Continue adding as many actions and conditions as you want for each ORB event (repeat steps 3-6) until you are tracing and breaking on the events you want.

The current actions for that event are then listed in the Actions list box.

Conditions for each ORB event

Following are the ORB events that the debugger tracks and the conditions that you can set for each:

ORB event	Conditions

Bind	Interface, Object

BindExceptionOccurred	Interface, Object

Bind Failed	Interface, Object

Bind Succeeded	Interface, Object

ClientExceptionOccurred	Interface, Object

ClientPrepareRequest	Interface, Object, Operation

ClientReceiveReply	Interface, Object

ClientReceiveReplyFailed	Interface, Object

ClientSendRequest	Interface, Object, Operation

ClientSendRequestFailed	Interface, Object, Operation

ClientSendRequestSucceeded	Interface, Object, Operation

Rebind	Interface, Object

RebindFailed	Interface, Object

RebindSucceeded	Interface, Object

ServerExceptionOccurred	Operation

ServerLocate	None

ServerLocateFailed	None

ServerLocateForwarded	None

ServerLocateSucceeded	None

ServerPrepareReply	Interface, Object, Operation

ServerReceiveRequest	Interface, Object, Operation

ServerRequestCompleted	Interface, Object, Operation

ServerSendReply	Interface, Object, Operation

ServerSendReplyFailed	Interface, Object, Operation

ServerShutdown	None

For more information on the specific ORB events, look up “interceptors” in the VisiBroker documentation.


ORB event dialog box

See also

This dialog box is displayed when setting actions or conditions for an ORB event. The name of the ORB event for which you are setting options appears in the header of the dialog box.

You can set the following actions for each ORB event.

Action	Description

Log Event	Adds the event to the event log. On by default for all ORB events.

Break on Event	Stops the process when the event occurs.

In addition, you can set none, some, or all of the following conditions for each ORB event. If conditions are set, you’ll only break or log the specific event when one or more conditions trigger the action to occur. See Conditions for each ORB event for which conditions apply to each event or just look at the dialog box to see which conditions are available.

Condition	Description

Interface	Name of the CORBA interface that will trigger the trace or break

Object	The specific instance of the CORBA interface that will trigger the trace or break

Operation	The method that will trigger the trace or break


Debugger|Options - Event Log
Event Log (Tools|Debugger Options)

See also

Use the Event Log page of the Debugger Options dialog box to set event log options. The event log shows process control messages, breakpoint messages, OutputDebugStrings messages, and window messages. By right-clicking, you can bring up the context menu to clear the event log, save the event log to a text file, add a comment to the event log and set options for the event log. By setting options, you can control how many messages to display and how many events to show.

General	Effect

Clear log on run	Causes the event log to be purged at the start of each debug session. If this option is checked while debugging multiple processes, the event log view is cleared when the very first process is started. However, any process started while at least one process is already being debugged will not cause the event log view to be cleared.

Unlimited Length	Removes the limit on the length of the event log. When this option is unchecked, set the maximum length of the event log in the Length field.

Length	Displays the maximum length of the event log. If the Unlimited Length check box is checked, this option is inactive. For multiple process debugging, length is the total for the event log, not for a process.

Messages	Effect

Breakpoint messages	Enabling writes a message to the event log each time a breakpoint or First-chance exception is encountered. The message includes the current EIP address of the program being debugged in addition to information about the breakpoint (pass count, condition, source file name, and line number) or exception.

Process messages	Enabling writes a message to the event log each time a process loads or terminates, whenever a module is loaded or unloaded by the process.

Output messages	Enabling writes a message to the event log each time your program or one of its modules call OutputDebugString.

Window messages	Enabling writes a message to the event log for each window message that is sent or posted to one of your application's windows. The log entry will have details about the message, including the message’s name and any relevant data encoded in its parameters. Messages are not immediately written to the log if your process is running and not stopped in the debugger. As soon as you pause the process in the debugger (by encountering a breakpoint or using Run| Pause) the messages will be written to the event log.

Integrated debugging check box	Check to set the Integrated Debugger to active.

The default settings for these options is:

Length (100)

Unlimited Length (ON)

Clear Log on Run (ON)

Breakpoint Messages (ON)

Process Messages (ON)

Output Messages (ON)

Window Messages (OFF)

Integrated debugging (ON)

COM options

When the Enable COM cross-process support option on the Distributed Debugging page of the Debugger Options dialog box is checked, COM events are added to the event log. There are three types of COM events: ClientStart, ServerStart, and ClientEnd. Each event shows the GUID, the method number, and the HResult of the COM RPC.

CORBA options

When the Enable CORBA cross-process support option on the Distributed Debugging page of the Debugger Options dialog box is checked, you can step into remote CORBA processes while debugging. When checked, the controls in the ORB events list box are enabled and you can set options for each ORB event that the debugger sends notifications for. For each event, you can define any number of action sets. Events for which you set options are added to the event log.


Debugger|Options - LanguageExceptions
Language Exceptions (Tools|Debugger Options)

Use the Language Exceptions page of the Debugger Options dialog box to configure how the debugger handles language exceptions when they are raised by the program you are debugging.

Exception Types to Ignore	Lists types of exceptions you want the debugger to ignore (checked) or not (unchecked) while debugging.

The debugger does not halt execution of your program if the exception thrown is listed and checked. It will not halt execution if the exception thrown is derived from any exception listed in the list box and checked.

You can add and remove additional types of exceptions to the list box using the Add and Remove buttons.

For example, if you add EMathError to the list and check it, and your program raises an EMathError exception, the debugger will not stop your program at that point. Additionally, if your program raises an EOverflow exception, the debugger will not stop because EOverflow is derived from EMathError.

Stop on Delphi Exceptions 	Check the "Stop On Delphi Exceptions" checkbox if you want the debugger to halt execution of your program when your program throws a Delphi exception. By default, this checkbox is checked. If checked, you can tell the debugger to ignore specific exception types by using the "Exception Types to Ignore" listbox. The default for this setting is ON.

Stop on C++ Exceptions 	Check the "Stop On C++ Exceptions" checkbox if you want the debugger to halt execution of your program when your program throws a C++ exception. By default, this checkbox is checked. If checked, you can tell the debugger to ignore specific exception types by using the "Exception Types to Ignore" listbox. The default for this setting is ON.

Add button	Click the Add button to bring up the Add Exception dialog.

Remove button	Click to remove a selected item from the list. Select the item you want to remove and click Remove.

Integrated debugging	Check to set the Integrated Debugger to active. This option is on by default.


Exception Types to Ignore

The following default exception types are listed in the Exception Types to Ignore list box on the Language Exceptions page of the Debugger Options dialog box.and cannot be removed from the list:

Exception type	Default	Maps to

VCL Eabort Exception 	Ignored	EAbort and EAbort

Microsoft DAO Exceptions 	Ignored	CDaoException

Visibroker Internal Exceptions 	Ignored	IODictionary<IOUniqueId,dpIOHandler*>
::OBJECT_NOT_EXIST

CORBA System Exceptions 	Ignored	CORBA_SystemException and CORBA_SystemException*

CORBA User Exceptions	Not ignored	CORBA_UserException and CORBA_UserException *

You can add more exceptions to the list box by clicking Add and typing the name of the exception. Added exceptions will include a check box that lets you check the items you want to ignore and uncheck items you want the debugger to stop on.


Debugger|Options - OSExceptions
OS Exceptions (Tools|Debugger Options)

The scroll box on the top lists exceptions, and in the fields on the bottom you specify how the exception will be handled. To change the options for handling exceptions, highlight the exception you want to change and adjust the Handled By and On Resume options.

Handled By specifies whether the exception will be handled by the Debugger or by your program. If you have added exception handling to your project, select User Program.

On Resume specifies whether C++Builder will continue to handle the exception, or whether the project will run unhandled.

Add button bringsup the Add Exception Range dialog box. This allows you to add user-defined exceptions to be handled by the debugger.

Remove button removes a selected item from the list. Select the item you want to remove and click Remove. This allows you to remove a user-defined exception from the list. Currently, you can only remove exceptions that you have added. This button will be gray anytime a default exception is selected. You can only remove user-defined exceptions.

Integrated debugging check box sets the Integrated Debugger to active. This option is on by default.


Add Exception Range (Tools| Debugger Options - OS Exceptions)
Add Exception Range dialog (Tools| Debugger Options|OS Exceptions)

Choose Add from the Tools| Debugger Options| OS Exceptions tab Add button to bring up the Add Exception range dialog to specify a range of exceptions that you want to break on. If you give a low and high value, C++Builder stops on any OS exception with a value in the specified range. To stop on a single value, specify the same value for the low and high range. Specify the lower and upper range of the exception in the Range Low and Range High fields.


Add Language Exception (Tools| Debugger Options - Language Exceptions)
Add Language Exception dialog (Tools| Debugger Options|Language Exceptions)

Choose Add from the Tools| Debugger Options| Language Exceptions tab Add button to add types to the list by entering the type name in the edit window of the Exception Type drop-down listbox.


MTools Repository
Tools|Repository

See also

Choose Tools|Repository to display the Object Repository dialog box. Use the Object Repository dialog box to add, delete, and rename pages in the Object Repository. In addition, you can edit and delete Object Repository items. You can also specify template and expert options for forms and projects

Pages included on the Object Repository correspond to the User Defined pages in the New Items dialog box displayed by File|New. The objects listed are available from the New Items dialog box.


Object Repository dialog box

See also

Choose Tools|Repository to display the Object Repository dialog box.

Object Repository Options

The settings in the Object Repository Options dialog box affect the behavior of C++Builder when you begin a new project or create a new form in an open project. When you select an item in the Objects list box, the appropriate options become available at the bottom of the Objects list box. Depending on the item you select, one or more of the options listed below become available.

New form

Main form

You have the option to override these defaults by choosing File|New and selecting from the New Items dialog box.

By default, opening a new project displays a blank form. You can change this default behavior by changing Object Repository options. For more information see Customizing the Object Repository.

Object Repository
Options	Description

Pages	This list box displays the pages in the Object Repository. When you select a page, the items on that page appear in the Objects list box. Select [Object Repository] to view all items in the Object Repository. The pages in the Object Repository correspond to the user defined pages in the New Items dialog box.  Select File|New to display the New Items dialog box.

Objects	The Objects list box displays the items on the currently selected page of the Object Repository.

Add Page button	To add a new blank page, click the Add Page button. The Add Page  dialog box appears. Type the name of the page you want to add and click OK.

Delete Page button	To remove an empty page from the Object Repository, in the Pages list box, select the name of the page you want to delete and click the Delete Page button

Rename Page button	To rename an item in the Object Repository, in the Pages list box, select the name of the page you want to rename and click the Rename Page button. The Rename Page dialog box appears. Type the name of the page you want to rename and click OK. The renamed page appears in the Pages list box.

Edit Object	To edit the properties of items in the Object Repository, from the Objects list box, select the item you want to edit and click the Edit Object button. The Edit Object Info dialog box appears. Edit the information as desired and click OK.

Delete Object	Use the Delete Object button to remove the selected object from the Object Repository page.

Up/Down arrows	To change the position of the selected page, click the up arrow or the down arrow. You can also move pages by using a drag-and-drop operation.

There are three ways to add an object to a page:

Right click in a form, select Add to repository from the speed menu.

Select Project|Add to repository.

Drag an object listed in the Object column to a page listed in the Page column of the Object Repository.


Add Page dialog box

Use the Add Page dialog box to add a page to the Object Repository. You access the Add Page dialog box from the Object Repository dialog box.

Page name

Type the name of the new page into the Page name text box.


Rename Page dialog box

Use the Rename Page dialog box to rename a page in the Object Repository. You access the Rename Page dialog box from the Object Repository dialog box.

Page name	Type the new name of the page into the Page name text box.


Edit Object Info dialog box

Use the Edit Object Info dialog box to edit information of Object Repository items.

Options	Description

Title 	Displays the title of the selected item.

Description	Displays the description of the selected item.

Page	Displays the current page containing the selected item. To change the page on which the item appears, select a different page from the Page drop-down list.

Author	Displays the name of the Author of the selected item.

Browse button	The icon of the selected item is displayed to the left of the Browse button. Use the Browse button to select a different icon.

To view the item description:

1.	From the File menu select New.

2.	Select an item in the New Items dialog box.

3.	Right-click the mouse.

4.	Select View Details from the context menu.

The item description appears in the Description column.


Tools|Visibroker SmartAgent

See also

Choose Tools|Visibroker SmartAgent to start or stop the Smart Agent on your system. This is especially useful if the Smart Agent (osagent) is not installed as an NT service.

This menu item appears with a check mark if the Smart Agent is running. Check Visibroker SmartAgent to start the SmartAgent. Uncheck Visibroker SmartAgent to stop it.

Note:	You can’t stop the Smart Agent using this menu item if it is installed as an NT service.

A Smart Agent must be running for CORBA client applications to locate and form connections to CORBA server applications.


Tools|IDL Repository

See also

Choose Tools|IDL Repository to register the IDL files in your project with a CORBA Interface Repository. This command displays the Update IDL Repository dialog box.

Update IDL Repository dialog box

Repository Name	Use the Repository Name control to select the Interface Repository with which you want to register your interfaces. The Interface Repository must be running on your local network before you can register your IDL files. If the Interface Repository you want is not in the drop-down list, Click the Add IRep button to start it.

Add IRep	Click the Add IRep button to display the Start IRep dialog box. Use this dialog to start an Interface Repository with a specified name.

IDL Files	The IDL Files control lists all the IDL files in your project. Check all IDL files that you want to add to the Interface Repository. If you want to add an IDL file that is not listed, Click the Add File button to add that IDL file to your project.

Add File	Click Add File to display a browser where you can locate and select an IDL file to add to your current project. When you return, the selected IDL file appears in the IDL Files control.

Replace Definitions	Click Replace Definitions to indicate that any interfaces already registered with the Interface Repository that have the same names as the interfaces in your selected IDL files should be replaced by the interfaces in your IDL files. If you do not check Replace Definitions and one of your IDL files contains any interfaces that have the same name as an already-registered interface, the entire IDL file is rejected.

When you have specified the Interface Repository and IDL files, click OK to register the IDL files and exit the dialog. Click Apply to register the IDL files without exiting the dialog. For example, if you want to register your interfaces with more than one Interface Repository, choose Apply, and then select a new repository using the Repository Name control.

Warning:	The Update IDL Repository dialog does not warn you if the Interface Repository rejects one or more of your IDL files. You may wish to apply the IDL files and then check whether you were successful before exiting the dialog.


Start IREP dialog
Start IREP dialog box

See also

The Start IREP dialog box starts a CORBA Interface Repository and assigns it a specified name. To display this dialog, choose Add IRep from the Update IDL Repository dialog box.

Start IREP dialog box

Repository Name	Specify a name for the Interface Repository you are starting. This name is used to identify the Interface Repository when registering interfaces or by clients that bind to the repository in order to use DII or to obtain information about available interfaces.

Storage File	Specify a file that describes the initial contents of the Interface Repository. This file, which uses the .IDL extension, is a special file that is saved from the Interface Repository to preserve its contents. If you do not specify a file name, the Interface Repository starts out empty. You can subsequently add interfaces using the Update IDL Repository dialog or using the interface of the Interface Repository application.

Console	Starts the Interface Repository as a Console application. When unchecked, the Interface Repository runs as a Windows application where you can add interfaces or save a snapshot of the current contents to a file.


Tools|Import RC Scripts

The RC Import Tool enables you to convert resource scripts into C++Builder forms and automatically adds the converted forms to the open project.

1.	Start the Resource Expert.

2.	Click Next.

3.	In the Resource edit box, enter the name of the RC, DLG, or MNU file containing dialog resources you want to convert. You can use the directory tree and the files list box to graphically navigate to the location of the resource scripts.

You can Ctrl+Click in the files list box to select multiple resource scripts to convert.

4.	Click Next.

Note:	You can click Prev at anytime to view the preceding page of the RC Import Tool.

5.	In the Include edit box, enter the path to any .H, .PAS, or .INC files that are needed by the specified .RC files. Many .RC files refer to WINDOWS.H. If you do not know what include files the resource script uses, open the file and check the #include statements at the top of the .RC file.

6.	Click Next.

7.	To display each form after it is converted, check the Show All Forms While Converting.

If the RC file contains a large number of dialog resources, you should disable Show All Forms While Converting to avoid running out of Windows resources. Disabling Show All Forms While Converting will also make the expert run faster.

8.	Click Convert to import the selected resource scripts.

Note:	Your entire resource script may not convert as designed. See the implementation notes for the RC Import Tool for more information.


 Implementation notes for the RC Import tool

The following is a list of issues you might encounter while using the RC Import Tool.

BWCC buttons

Unknown control types and wndclass types

Error handling

BWCC Buttons

The RC Import Tool has a few limitations when converting BWCC buttons. You should keep these items in mind while doing your conversion.

Bitmaps referred to by BWCC buttons and icon controls are converted into the corresponding VCL TBitBtns and TImage components in the form.

The raised bevels in BWCC button bitmaps are redundant in TBitBtn components, so you might see double-wide bevels on such converted controls.

BWCC uses three bitmaps to draw the button in up, focused, and pressed states. TBitBtns use only one bitmap and synthesize the other states. Consequently, only the first (up) bitmap associated with a BWCC button is imported into the corresponding TBitBtn component.

BWCC resizes buttons to match the dimensions of the bitmap. Resource Expert does not resize the TBitBtns to match the bitmap dimensions.

Unknown Control Types and Wndclasses

Control statements for unknown control types/wndclasses are converted into TPanel components containing the unknown control's position and size in the name and caption of the panel. Such unknowns can come from VBX controls or any other custom control installed into RW.

Error Handling

The RC Import Tool assumes the resource script contains valid syntax, as defined by the Borland Resource Compiler (BRC). Make sure you can compile your resource script using the BRC or the Microsoft Resource Compiler before submitting it to RC Import Tool for conversion.

If a syntax error is encountered, the RC Import Tool will skip to the next control statement (if in a dialog statement) or the next resource statement. The control or resource that contained the syntax error will not appear in the converted form. Depending on the severity of the syntax error, several control or resource statements may be skipped before a suitable recovery point is found.

When a syntax error forces the resource expert to skip to the next resource statement, the name of the next resource statement will be lost. The next resource may still be converted, but it will not have a meaningful name.

If any errors occur during conversion, the RC Import Tool will open a file named ERRORLOG.TXT in the Code Editor at the end of the conversion process. ERRORLOG.TXT lists the location and nature of the syntax errors encountered. After correcting any syntax errors, you can reconvert the entire resource script/project.

If you edit your resource scripts to resolve syntax errors, you should close the current project without saving and open a new project before reimporting the modified resource scripts.

The RC Import Tool expands tab characters embedded in the resource script text to five spaces. The column numbers reported in error messages reflect this tab expansion. If your resource scripts contain embedded tabs, and you need to locate a syntax error, you should set the your editor's tab size to 5 when viewing the RC script file. You can modify the Code Editor tab sets using the Editor Options page of Tools|Environment Options.

If the RC Import Tool encounters an error more serious than a syntax error (for example, a disk read error or out of memory), the RC Import Tool will display the error message onscreen and abort the conversion process.


Tools|Configure Tools

Choose Tools|Configure Tools to display the Tools Options dialog box.

Use the Tools Options dialog box to add, delete, or edit programs on the Tools menu.


Tools Options dialog box

Choose Tools|Configure Tools to open the Tools Options dialog box.

Use this dialog box to add programs to, delete programs from, or edit programs on the Tools menu.

Tools Options dialog box

Tools	Lists the programs currently installed on the Tools menu. When two or more programs you have added to the Tools menu have conflicting shortcuts, a red star appears to the left of the program’s entry in the list on the left.

Add	Click Add to display the Tool Properties dialog box, where you can specify a menu name, a path, and startup parameters for the program.

Delete	Click Delete to remove the currently selected program from the Tools menu.

Edit	Click Edit to display the Tool Properties dialog box, where you can edit the menu name, the path, or the startup parameters for the currently selected program.

Arrow	Use the arrow buttons to rearrange the programs in the list. The programs appear on the Tools menu in the same order they are listed in the Tool Options dialog box.

Close

Click Close to return to the IDE.

To add a program to the tools menu:

1.	Choose Add.

The Tool Properties dialog box appears.

2.	Specify a title for the program. The title you specify will be listed on the Tools menu.

3.	Specify the program file or choose Browse to select it from a list.

4.	Specify the working directory for the program, if necessary.

5.	Specify startup parameters for the program, if necessary. You can type the parameters or use the Macros button to supply startup parameters. You can specify multiple parameters and macros.

6.	Choose OK.

The Tool Properties dialog box closes. The new program is on the Tools list in the Tool Options dialog box.

7.	Choose Close.

The Tool Options dialog box closes. The new program is on the Tools menu.

To delete a program from the tools menu:

Select the program to delete, and choose Delete. C++Builder prompts you to confirm the deletion.

To change a program on the tools menu:

Select the program to change, and choose Edit. The Tool Properties dialog box appears with information for the selected program.


Tool Properties dialog box

Use the Tool Properties dialog box to enter or edit the properties for a program listed on the Tools menu.

To display the Tool Properties dialog box:

Click Add or Edit in the Tools Options dialog box.

Tool Properties	Description

Title 	Enter a name for the program you are adding. This name will appear on the Tools menu. To add an accelerator to the menu command, precede that letter with an ampersand (&). If you specify a duplicate accelerator, The Tool Options dialog box displays a red asterisk (*) next to the program names.

Program	Enter the location of the program you are adding. Include the full path to the program.  To search your drives and directories to locate the path and file name for the program, click the Browse button

Working Dir	Specify the working directory for the program. C++Builder specifies a default working directory when you select the program name in the Program Edit Box. You can change the directory path if needed.

Parameters	Enter parameters to pass to the program at startup. For example, you might want to pass a file name when the program launches. Type the parameters or use the Macros button to supply startup parameters. You can specify multiple parameters and macros.

Macros	Click Macros to expand the Tool Properties dialog box to display a list of available macros.  You can use these macros to supply startup parameters for your application. Select a macro and click Insert to add the macro to the Program, Working dir, or Parameters text box above.

Browse	Click Browse to select the program name for the Program edit box. When you click Browse, the Select Transfer Item dialog box opens.

To add a macro to the list of parameters:

Select a macro from the list and click Insert.


Transfer macros

Use transfer macros to supply startup parameters to a program on the Tools menu.

To display the macros:

Click the Macros button on the Tool Properties dialog box.

Macro	Description

$COL	Expands to the column number of the cursor in the active Code editor window.

For example, if the cursor is in column 50, at startup C++Builder passes "50" to the program.

$ROW	Expands to the row number of the cursor in the active Code editor window.

For example, if the cursor is in row 8, at startup C++Builder passes "8" to the program.

$CURTOKEN	Expands to the word at the cursor in the active Code editor window.

For example, if the cursor is on the word Token, at startup C++Builder passes "Token" to the program.

$PATH	Expands to the directory portion of a parameter you specify. When you insert the $PATH macro, C++Builder inserts $PATH() and you specify a parameter within the parentheses.

For example, if you specify $PATH($EDNAME), at startup C++Builder passes the path for the file in the active Code editor window to the program.

$NAME	Expands to the file name portion of a parameter you specify. When you insert the $NAME macro, C++Builder inserts $NAME() and you specify a parameter within the parentheses.

For example, if you specify $NAME($EDNAME), at startup C++Builder passes the file name for the file in the active Code editor window to the program.

$EXT	Expands to the file extension portion of a parameter you specify. When you insert the $EXT macro, C++Builder inserts $EXT() and you specify a parameter within the parentheses.

For example, if you specify $EXT($EDNAME), at startup C++Builder passes the file extension for the file in the active Code editor window to the program.

$EDNAME	Expands to the full file name of the active Code editor window.

For example, if you are editing the file C:\PROJ1\UNIT1.PAS, at startup C++Builder passes "C:\PROJ1\UNIT1.PAS" to the program.

$EXENAME	Expands to the full file name of the current project executable.

For example, if you are working on the project PROJECT1 in C:\PROJ1, at startup C++Builder passes "C:\PROJ1\PROJECT1.EXE" to the program.

$PARAMS	Expands to the command-line parameters specified in the Run Parameters dialog box.

$PROMPT	Prompts you for parameters at startup. When you insert the $PROMPT macro, C++Builder inserts $PROMPT() and you specify a default parameter within the parentheses.

$SAVE	Saves the active file in the Code editor.

$SAVEALL	Saves the current project.

$TDW	Sets up your environment for running Turbo Debugger. For example, this macro saves your project, ensures that your project is compiled with debug info turned on, and recompiles your project if it is not compiled with debug info turned on. Be sure to use this macro if you add Turbo Debugger to the Tools menu.


Select Transfer Item dialog box

Use the Select Transfer Item dialog box to search drives and directories for a program to add to the Tools menu.

To locate a transfer item:

Click the Browse button on the Tool Properties dialog box.

File Name	Enter the name of the file you want to load, or enter wildcards to use as filters in the Files list box.

Files	Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List Files Of Type	Choose the type of file you want to open. The default file types are .EXE, .COM, and .PIF files. All files in the current directory of the selected type appear in the Files list box.

Directories	Select the directory whose contents you want to view. Files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box appear in the Files list box.


Tools|Optional tools on the tools menu

The bottom of the Tools menu is customizable. You can remove the tools listed there or add other installed or custom tools you want to access while using C++Builder.

Choose Tools|Configure Tools to display the Tools Options dialog box where you can add, delete, or edit programs on the Tools menu.

The following tools are displayed by default:

DataBase Desktop	Displays the database desktop where you can create, view, sort, modify, and query tables in Paradox, dBASE, and SQL formats.

Package Collection Editor	Create and edit package collections. Package collections are a convenient way to bundle packages and associated files for distribution to other developers.

Visual C++Project Conversion Utility	Converts Microsoft Visual C++ projects into C++Builder project files.

Image Editor	Create and edit resource files, icons, bitmaps, and cursor files for use in applications.

Any other tools you have added to the Tools menu will also appear.


Tools|Database Desktop

Choose Tools|Database Desktop to display the Database Desktop. Database Desktop is a database tool where you can create or restructure database tables, or browse and edit their data. You can work with tables in Paradox, dBASE, and SQL formats. For details on using Database Desktop, click on dbddesk.hlp in the Borland\Database Desktop directory. A complete Database Deskop Help system is displayed.


 Tools|Image Editor

Choose this command to invoke the Image Editor. The Image editor is a program that lets you create and edit images to use in your application.


View menu

Use the View menu commands to display or hide different elements of the C++Builder environment and open windows that belong to the integrated debugger.

Project Manager	Displays the Project Manager

Object Inspector	Displays the Object Inspector

Alignment Palette	Displays the Alignment Palette

ClassExplorer	Displays the ClassExplorer

Component List	Displays the Components dialog box

Window List	Displays a list of open windows

Debug Windows	Displays the Debugger submenu

Toggle Form/Unit	Toggles between a form and its unit window

Units	Displays the View Unit dialog box

Forms	Displays the View Form dialog box

Type Library	Displays the Type Library editor window

New Edit Window	Opens a new Code editor

Toolbars	Hides or shows the toolbars or Component palette


View|Project Manager

See also

Choose View|Project Manager to display the Project Manager. If the Project Manager is already open, it becomes the active window.

Use the Project Manager window to view a project group, projects in a project group, and to navigate among a project’s files. You can use the Project Manager to add projects to a project group or delete projects, or to activate a project if your project group consists of more than one project. You can also use the Project Manager to add, delete, save, or copy a file to the current project. The Project Manager lists all the units and associated forms in projects within the current project group.

You can position the Project Manager anywhere on your desktop. You can also dock it with other windows such as the Code editor or other tool windows.


View|Object Inspector

See also

If you have closed the Object Inspector, choose this command to reopen it. You can also choose View|Object Inspector to toggle between the InspectorObject Inspector and the last active form or Code editor file.

Use the Object Inspector to edit property values and event-handler links.


View|Alignment Palette

Choose View|Alignment Palette to display the Alignment Palette, which you can use to align components to the form, or to each other.

Note:	You can also align components by using the Alignment dialog box.


Alignment palette

See also

Use the Alignment palette to align components to the form, or with each other.

The Alignment palette has Tool Help for each button.

Icon	Effect
	Aligns the selected components to the left edge of the component first selected. (Not applicable for single components.)
	Moves the selected components horizontally until their centers are aligned with the component first selected. (Not applicable for single components.)
	Aligns the selected component(s) to the center of the form along a horizontal line.
	Horizontally aligns three or more selected components so that the middle components are equidistantly spaced between the outer components.
	Aligns the selected components to the right edge of the component first selected. (Not applicable for single components.)
	Aligns the selected components to the top edge of the component first selected. (Not applicable for single components.)
	Moves the selected components vertically until their centers are aligned with component first selected. (Not applicable for single components.)
	Aligns the selected component(s) to the center of the form along a vertical line.
	Vertically aligns three or more selected components so that the middle components are equidistantly spaced between the outer components.
	Aligns the selected components to the bottom edge of the component first selected. (Not applicable for single components.)

If you are unsure of how a particular button on the Alignment palette acts, click and hold on the button. The icon on the button changes to show you how it will align the selected components. To apply the button’s alignment to a selection, release the button. To prevent alignment after you click and hold the button, drag the mouse off the palette before releasing the mouse button.

Note:	You can also use the Alignment dialog box to align components.


View|ClassExplorer

See also

By default, the ClassExplorer is docked to the left of the Code editor. If this window is closed, you can reopen it by choosing View|ClassExplorer.

The ClassExplorer makes it easy to navigate through your unit files and automates the creation of classes.

To close the ClassExplorer, undock it and click the upper right corner.

To reopen the ClassExplorer, choose View|ClassExplorer.

The ClassExplorer contains a tree diagram that shows all the types, classes, properties, methods, global variables, and global routines defined in your unit.  You can expand or collapse the nodes on the tree. Whichever unit file is open in the Code editor is also open in the ClassExplorer.


View|Component List

Choose View|Component List to display the Components window.

Components window

Use this window to add components to your forms using the mouse or keyboard.

Options	Description

Search By Name	Enter the name of the component you want to add. This list box performs an incremental search so that the cursor moves to the first component containing the letters you type.

Component list box	Select the component you want to add. Components are listed in alphabetical order, and their button representation is on the left.

Search edit box	When you select a component, its name appears in the Search edit box.

Add To Form	Click Add To Form to place an instance of the selected component in the center of the form. To select Add To Form from the keyboard, press Enter.

To add the component you selected in the Component list box, do one of the following:

Press Enter.

Double-click the component name.

Click the Add to Form button.

Note:	When you add a component to a form by using the keyboard, C++Builder uses the default component size and adds the component to the center of the form unless a container component (such as a group box or panel) is selected.

If a container component is selected, C++Builder places the component you are adding in the center of that container. To add a component into a container, you must select the container before selecting Add To Form.


View|Toggle Form/Unit

See also

Choose View|Toggle Form/Unit switch between the current form or its unit file.

Alternative ways to perform this command are:

Choose the Toggle Form/Unit button from the toolbar.


View|Units

See also

Choose View|Units to display the View Unit dialog box.

View Unit dialog box

Use this dialog box to view the project file or any unitin the current project. When you choose a unit, it becomes the active page in the Code editor.

If the unit you want to open is not currently open, C++Builder opens it.

Alternative ways to perform this command:

Choose the View Units button on the toolbar.


View|Forms

See also

Choose View|Forms to display the View Form dialog box.

View Form dialog box

Use this dialog box to view any form in the current project. When you select a form, it becomes the active form, and its associated unit becomes the active module in the Code editor.

If the associated unit is not open when you select a form, C++Builder opens it.

Alternative ways to perform this command:

Choose the Select Form From List button from the toolbar.


View|Window List

Choose View|Window List to display the Window List dialog box.

Window List dialog box

Use this dialog box to make an inactive C++Builder window active. If you have a lot of windows open, this is the easiest way to locate a specific window. The Windows List dialog box displays all open C++Builder windows.

To select a window, do one of the following:

Double-click the window name.

Select the window name and click OK.


View|Debug Windows

Use the View|Debug Windows menu commands to open windows that belong to the integrated debugger. These windows show the process and/or thread ID of the process or thread being viewed.

Breakpoints	Displays the Breakpoints List dialog box

Call Stack	Displays the Call Stack dialog box

Watches	Displays the Watch List dialog box

Local Variables	Shows the current function’s local variables while in debug mode

Threads	Displays the threads status box

Modules	Displays the Modules window

CPU 	Displays the CPU window

Event Log	Displays the event log window


View|Breakpoints
View|Debug Windows|Breakpoints

Choose View|Debug Windows|Breakpoints to open the Breakpoint List window

The Breakpoint List window lists all currently set breakpoints.

Each breakpoint listing shows the following:

For Source breakpoints, this is the file in which the breakpoint is set. For Data breakpoints set on a specific variable, this shows the name of the variable. For Address breakpoints, this is the address at which the breakpoint is set, unless the address can be correlated to a source line in which case this is the source filename. In that case, it shows the file in which the breakpoint is set.

For Source breakpoints, this is the line number of the breakpoint. For Data breakpoints, this is the length of the breakpoint. For Address breakpoints, this is empty unless the address can be correlated to a source line. If so, it shows the source line number and a hex offset of the address from the beginning of the line.

Any condition associated with the breakpoint

Any pass count associated with the breakpoint


View|Call Stack
View|Debug Windows|Call Stack

Choose View|Debug Windows|Call Stack to open the Call StackWindow.

The Call Stack window lists the current sequence of routines called by your program. In this listing, the most recently called routine is at the top of the window, with each preceding routine call listed beneath.

Each entry in the Call Stack window displays the procedure name and the values of any parameters passed to it.


View|Watches
View|Debug Windows|Watches

Choose View|Debug Windows|Watches to open the Watch List.

The Watch List displays all the currently set watch expressions.

If you keep this window open during your debugging sessions, you can monitor how your program updates the values of important variables as the program runs.


Run|Inspect Local Variables command
View|Debug Windows|Local Variables

See also

Choose View|Debug Windows|Local Variables to show the current function’s local variables while in debug mode.

This command is always available, but the view will be empty unless the debugger is paused. If you keep this window open during your debugging sessions, you can monitor how your program updates the values of important variables as the program runs.


View|Debug Windows|Threads

Choose View|Debug Windows|Threads to view the Threads status box which displays the status of all the threads currently executing in the application being debugged. Multiple process debugging is also supported via the Threads view.


View|Debug Windows|Modules

See also

Choose View|Debug Windows|Modules to open the Modules window to view a list of modules that are loaded into memory when the current project is run. A module can be an executable file, DLL, or package that the current project needs loaded into memory during runtime. The Modules window shows each module’s name, its runtime image base address, and a path indicating the location from which the module is loaded.

Normally, you would open this window after you have compiled a project and are debugging it. It is also helpful when optimizing to improve load time by specifying preferred image base offsets for each required module.

Note:	The runtime image base address is the memory offset, in hexadecimal, where the module actually loads, as distinct from the preferred image base address you may have specified in the Project Options window.

The Modules window has three parts:

Module pane (upper left)

Source pane (lower left)

Entry point pane (right)

The Module pane lists each module name and the address at which it is loaded. If the module has debug information, the Source pane shows a tree view of the source files that contain code that was used to build the module. If the module has debug information, the Entry point pane shows a list of all global symbols. If the module does not have debug information, the Entry point pane lists the function entry points into the module.

Multiple process debugging

For multiple-process debugging each process and its associated modules are shown. The current process is denoted by a green arrow glyph.


View|Debug Windows|CPU

Choose View|Debug Windows|CPU to display the CPU window for debugging a specific low-level aspect of an application such as a contents of the program stack, registers or CPU flags, memory dumps, or assembly instructions disassembled from the application’s machine code.


View|Debug Windows|Event Log

Choose View|Event to display the event log. The event log shows process control messages, breakpoint messages, and window messages. Right-click on the event log to display the context menu to clear the event log, save the event log to a text file, add a comment to the event log, and set options for the event log.

By setting options, you can control how many messages to display and what kind of events to show.


View|New Edit Window

Choose View|New Edit Window to open a new Code editor window that contains a copy of the active page from the original Code editor.

Any changes you make to either the original or the copy are reflected in both files.

So that you can distinguish between the windows, the caption in the original window is postfixed with a 1, the first copy with a 2, the second copy with a 3, and so on.


View|Toolbars

See also

Choose View|Toolbars to show or hide the following in the IDE:

Toolbar	Icons on toolbar by default

Standard	New, Open, Save, Save All, Open Project, Add File to Project,
Remove File from Project

View	View Unit, View Form, Toggle Form/Unit, New Form

Debug	Run, Pause, Trace Into, Step Over

Custom	Any commands you add. Contains Help Contents, by default;
see View|Toolbars|Customize.

Component palette	Tabbed pages of commonly used objects

CORBA	New CORBA Object Implementation, CORBA refresh, Use CORBA object

Check the items you want to display and uncheck those you want to hide. The toolbars provide icons as shortcuts for actions you can perform. The Component palette has several tabs each of which displays icons representing components you can use to design your application.

You can also customize all of the toolbars adding or removing items from the toolbars according to your needs.


View|Toolbars|Customize (Customize dialog box)

See also

Choose View|Toolbars|Customize to change the toolbar configuration. The Customize dialog box is displayed.

The pages of the Customize dialog box are

Toolbars

Command

Options

These pages let you customize which toolbars are displayed, what commands are on the toolbars, and how tooltips are displayed.

When any of the pages of the Customize dialog box is displayed, you can delete or rearrange any of the buttons currently on the toolbar. However, none of the buttons on the toolbar is active.


Toolbars (Customize dialog box)

See also

The Toolbars page of the Customize dialog box lets you choose which toolbars to display. It includes a Reset button that you can use to return any toolbar to its default (factory) configuration.

Check all the toolbars that you want to display.

Reset	Select one or more of the toolbars to reset (multiselect using Ctrl or Shift). Then choose Reset to reset the toolbars to the default configuration (deleting any added buttons and adding any deleted buttons). The Reset button is only active when one or more toolbars is selected.

When the Toolbars page of the Customize dialog box is displayed, you can delete or rearrange any of the buttons currently on the toolbar. However, none of the buttons on the toolbar is active.


Commands (Customize dialog box)

See also

The Commands page of the Customize dialog box lets you add or delete buttons on the toolbar. It has two list boxes:

Categories	Select a menu whose commands you want to add as buttons to the toolbar. The commands associated with each category are shown in the Commands list box.

Command	Drag and drop a command from this list box onto the toolbar. The Commands list box displays all the commands available for the category selected in the Categories list box. The icon to the left of the menu command shows the button that will appear on the toolbar.

Choose Reset on the Toolbars page of the Customize dialog box to reset any toolbar to its default configuration (deleting any added buttons and adding any deleted buttons).

When the Commands page of the Customize dialog box is displayed, you can delete or rearrange any of the buttons currently on the toolbar. However, none of the buttons on the toolbar is active.


Options (Customize dialog box)

The Options page of the Customize dialog box lets you choose whether or not to display tooltips for toolbar buttons. You can include shortcut keys in the tooltip text or not. Choose the options you prefer.

When the Options page of the Customize dialog box is displayed, you can delete or rearrange any of the buttons currently on the toolbar. However, none of the buttons on the toolbar is active.


Type Library editor
View|Type Library

See also

The Type Library editor lets you examine and create type information for ActiveX controls, Automation servers, MTS objects, and other COM objects. You can provide type information with an object either stand-alone in a type library (.TLB) file or you can integrate it into the EXE or ActiveX library as a resource.

By including the type library with an application or ActiveX library, you are making information contained in the library, such as its object interfaces, properties, methods, and events, available to other to other applications and programming tools.

When you use the wizards to create an ActiveX control or Automation object, a type library is automatically created for you. You can then use the Type Library editor to examine or modify the type information created by the wizard. Use the Type Library editor to add additional functionality, such as new properties, methods, or events, to your type library.


Type Library editor

See also

Use the Type Library editor to make changes to your type library. The Type Library editor generates the required IDL syntax automatically. Any changes you make in the editor are reflected in the corresponding control.

To open the Type Library editor,

  Choose View|Type Library.

The Type Library option is available only for projects that contain a type library. An ActiveX control and Automation object will contain a type library if you create it using a wizard.

The main elements of the Type Library editor are:

Toolbar
These buttons add instances of new information types to the current type library. When you click a button, its icon is added to the object list pane.

Status Bar pane
Syntax and translation errors and warnings appear here when you edit, save, or load a type library.

Object list pane
Each instance of an information type in the current type library appears in the object list, represented by a unique icon.  Select an icon to see its data pages displayed in the information pane at the right.

Pages of type information. For each object selected in the object list pane, the Type Library editor displays tabbed pages of the object’s attributes, flags, if any, and text. Some objects have additional pages.

You can view and edit the following Type Library information:

Type library information

Interface pages

Dispatch type information

CoClass pages

Enumeration type information

Alias type information

Record type information

Union type information

Module type information


Type library attributes page
Type Library attributes

Edit the attributes in the Type Library to change information about the type library itself.

To edit the type library attributes,

In the Type Library Editor object list pane, select the type library, which has the icon:

The attributes page displays type information about the currently selected type library.


Type Info attributes

Type info is a general term for the types of information available in a type library such as interfaces, dispinterfaces, coclasses, enumerations, and so on. You can change information about each type by modifying its attributes page.

To edit type info attributes,

In the Type Library Editor object list pane, select the type you want to edit and its attributes page appears.

   See the following topics for details on modifying the attributes of each type info:

Interface attributes

Dispinterface attributes

CoClass attributes

Enumeration attributes

Alias attributes

Record attributes

Union attributes

Module attributes


Members attributes
Member attributes

You can add or remove members to each type info.

To modify type member attributes,

1.	In the Type Library Editor object list pane, select the type you want create or modify.

The toolbar displays the members available for this type to the left of the vertical bar.

2.	Choose the member you want to modify and its attributes page appears.

For interfaces and dispinterfaces, you can add methods or properties.

For enumerations, you can add constants.

Records, are comprised of fields.

A union defines a C-style union.

A module can be comprised of methods and constants.


Text

All type library elements have a text page that displays the IDL syntax for the element. Any changes you make in other pages of the element are reflected here. If you add IDL code directly in the text page, changes are reflected in the other pages of the Type Library editor.

The Type Library editor generates syntax errors if you add IDL identifiers that are currently not supported by the editor; the editor currently supports on those IDL identifiers that relate to type library support (not RPC support).


CoClass implements

You specify the globally unique identifier (GUID) and supported interfaces on the CoClass implements page.

For each interface, specify the following information.


Type library uses

The uses page lists any other type libraries that this type library references.


Parameters

The parameters page allows you to specify the parameters and return values for the functions contained in your type library.

You can specify the following information.


Type library flags

The type library flags specify how other applications must use the server associated with this type library. You can set the following flags:

Flag	Meaning
Restricted	Prevents the library from being used by a macro programmer.
Control	Indicates that the library represents a control.
Hidden	Indicates that the library exists but should not be displayed in a user-oriented browser.


Type info flags

You can set the following flags for type info. The same flags menu appears for all type info (interfaces, CoClasses, enumerations and so on). Unavailable flags are dimmed.

For details, see:

Interface and dispinterface flags

CoClass flags


Type member flags

The following menu of flags appears when you have a type member (properties, methods, constants and fields). Unavailable flags are dimmed.

For details, see:

Method flags

Property flags


Parameter flags

The parameters flags dialog box allows you to specify parameters and return values for your functions.

To get to this dialog box,

1.	In the Type Library Editor, select a method or property.

2.	In the Parameters page, click in the flags field.

An ellipsis appears.

3.	Click on the ellipsis to display this Parameter Flags dialog box.

For details on the flags, see Property and method parameters page


String List editor

See also

Use the String List editor at design time to add, edit, load, and save strings into any property that has been declared as TStrings.

To open the String List editor,

1.	Place a component that uses a string list on the form.

2.	With that component selected, do one of the following:

Click the ellipsis in the Value column for any properties that has been declared as TStrings.

Double-click the word (TStrings) in the Value column for any property that has been declared as TStrings.

The String List context menu contains the following commands:

Load

Click Load to display the Load String List dialog box, where you can select an existing file to read into the String List editor.

Save

Click Save to write the current string list to a file. C++Builder opens the Save String List dialog box, where you can specify a directory and file name.


Load String List Dialog Box

See also

Use the Load String List dialog box to select a text file to load into a property of type TStrings.

To open this dialog box,

1. Bring up the String List editor.

2. Right-click and choose Load.

Dialog box options

File Name

Enter the name of the file you want to load or wildcards to use as filters in the Files list box.

Files

Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List Files Of Type

Choose a filter to display the different types of files. By default the text files (*.TXT) for the current directory are displayed in the Files list box.

Directories

Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box appear in the Files list box.

Drives

Select the current drive. The directory structure for the current drive appears in the Directories list box.


Save String List dialog box

Use the Save string list dialog box to store the string list from the String List editor into a text file.

To open this dialog box,

1. Bring up the String List editor.

2. Right-click and choose Save.

Dialog box options

File Name

Enter the name of the file you want to save or wildcards to use as filters in the Files list box.

Files

Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List Files Of Type

Choose a filter to display the different types of files. By default, the text files (*.TXT) in the current directory are displayed in the Files list box.

Directories

Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box appear in the Files list box.

Drives

Select the current drive. The directory structure for the current drive appears in the Directories list box.


Picture editor

See also

Use the Picture editor to select an image to add to any of the graphic-compatible components and to specify an icon for your form.

To open the Picture editor,

1.	Place a graphic-compatible component on the form.

2.	With that component selected, do one of the following:

Click the ellipsis button in the Value column for any of the properties listed below.

Double-click the Value column for any of the properties listed below.

Note:	To open the Picture editor from an Image component, you can also double-click the component in the form.

The Picture editor provides the following commands:

Load

Display the Load Picture dialog box, where you can select an existing file to read into the Picture editor. For more information about loading images into the Picture editor, see Loading an image at design time.

Save

Display the Save Picture As dialog box, where you can specify a directory and file name in which to store the image.

Clear

Remove the association between the current image and the selected component.


Loading an image at design time

See Also

Use the Picture editor to load images onto any of several graphic-compatible components and to specify an icon to represent a form when it is minimized at run time.

Each graphic-compatible component has a property that uses the Picture editor.

To load an image at design time,

1.	Add a graphic-compatible component to your form.

2.	To automatically resize the component so that it fits the graphic, set the component's AutoSize property to true before you load the graphic.

3.	In the Object Inspector, select the property that uses the Picture editor.

4.	Either double-click in the Value column, or choose the ellipsis button to open the Picture editor.

(To open the Picture editor from an Image component, you can also double-click the component in the form.)

5.	Choose the Load button to open the Load Picture dialog box.

6.	Use the Load Picture dialog box to select the image you want to display, then choose OK.

The image you choose is displayed in the Picture editor.

7.	Choose OK to accept the image you have selected and exit the Picture Editor dialog box.

The image appears in the component on the form.

Note:	When loading a graphic into an Image component, you can automatically resize the graphic so that it fits the component by setting the Image component's Stretch property to true. (Stretch has no effect on the size of icon (.ICO) files.)


Load Picture dialog box

See Also

Use the Load Picture dialog box to select an image to add to any of the graphic-compatible components and to specify an icon for your form.

To open the Load Picture dialog box,

In the Picture editor, click Load.

Dialog box options

File Name

Enter the name of the file you want to load or wildcards to use as filters in the Files list box.

Files

Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List Files Of Type

Choose a filter to display the different types of image files. By default, the icon files (*.ICO) for the current directory are displayed in the Files list box.

Directories

Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box appear in the Files list box.

Drives

Select the current drive. The directory structure for the current drive appears in the Directories list box.


Save Picture As dialog box

See also

Use the Save Picture As dialog box to store the image loaded in the Picture editor into a new file or directory.

To open the Save Picture As dialog box,

In the Picture editor, click Save As.

Dialog box options

File Name

Enter the name of the file you want to load or wildcards to use as filters in the Files list box.

Files

Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List Files Of Type

Choose filter to display the different types of image files. By default the icon files (*.ICO) for the current directory are displayed in the Files list box.

Directories

Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box appear in the Files list box.

Drives

Select the current drive. The directory structure for the current drive appears in the Directories list box.


Notebook editor

See also

Use the Notebook editor to add, edit, remove, or rearrange pages in either a TabbedNotebook component or Notebook component. You can also use the Notebook editor to add or edit Help context numbers for each notebook page.

The Notebook editor displays the current pages of the notebook in their current order, and it also displays the Help context associated with that page.

To open the Notebook editor,

1.	Place a Notebook component or TabbedNotebook component on the form.

2.	With that component selected, do one of the following:

Click the ellipsis button in the Value column for the Pages property.

Double-click the Value column for the Pages property.

Edit

Click Edit to open the Edit Page dialog box, where you can modify the page name and Help context number for the selected notebook page.

Add

Click Add to open the Add Page dialog box, where you can create a new notebook page.

Delete

Click Delete to remove the selected page from the notebook.

Move Up/Move Down

Click Move Up or Move Down to rearrange the order of the selected page or pages.


Edit Page dialog box

See also

Use the Edit Page dialog box to edit existing notebook pages from either the Notebook component or the TabbedNotebook component.

To open this dialog box,

In the Notebook editor, click Edit.

Dialog box options

Page Name

Enter the name of the notebook page. There is a 255-character limit on page names.

Help Context

Enter the context ID number for the notebook page. This number is significant if you want to have context-sensitive help for the individual pages of the notebook. The Help context is optional.


Add Page dialog box

See also

Use the Add Page dialog box to add notebook pages to either the Notebook component or the TabbedNotebook component.

To open this dialog box,

In the Notebook editor, click Add.

Dialog box options

Page Name

Enter the name of the notebook page. There is a 255-character limit on page names.

Help Context

Enter the context ID number for the notebook page. This number is significant if you want to have context-sensitive Help for the individual pages of the notebook. The Help context is optional.


Input Mask editor

See also

Use the Input Mask editor to define an edit box that limits the user to a specific format and accepts only valid characters. For example, in a data entry field for telephone numbers you might define an edit box that accepts only numeric input. If a user then tries to enter a letter in this edit box, your application will not accept it.

Use the Input Mask editor to edit the EditMask property of the MaskEdit component.

To open the Input Mask editor,

1.	Place a MaskEdit component on the form.

2.	With that component selected, do one of the following:

Click the ellipsis button in the Value column for the EditMask property.

Double-click the Value column for the EditMask property.

Input Mask

Define your own masks for the edit box. You can use special character to specify the mask; for a listing of those characters, see the EditMask property.

The mask consists of three fields separated by semicolons. The three fields are

The mask itself; you can use predefined masks or create your own.

The character that determines whether or not the literal characters of the mask are saved as part of the data.

The character used to represent a blank in the mask.

Save Literal Characters

Check to store the literal characters from the edit mask as part of the data. This option affects only the Text property of the MaskEdit component. If you save data using the EditText property, literal characters are always saved.

This check box toggles the second field in your edit mask.

Character For Blanks

Specify a character to use as a blank in the mask. Blanks in a mask are areas that require user input.

This edit box changes the third field of your edit mask.

Test Input

Use Test Input to verify your mask. This edit box displays the edit mask as it will appear on the form.

Sample Masks

Select a predefined mask to use in the MaskEdit component. When you select a mask from this list, C++Builder places the predefined mask in the Input Mask edit box and displays a sample in the Test Input edit box. To display masks appropriate to your country, choose the Masks button.

Masks

Choose Masks to display the Open Mask File dialog box, where you choose a file containing the sample masks shown in the Sample Masks list box.


Masked Text editor

See also

Use the Mask Test editor to enter Values into the edit mask.

Use the Masked Text editor to edit the Text property of the MaskEdit component.

To open the Masked Text editor,

1.	Place an MaskEdit component on the form.

2.	With that component selected, do one of the following:

Click the ellipsis button in the Value column for the Text property.

Double-click the Value column for the Text property.

Input Text edit box

Enter initial values for the MaskEdit component. You can overwrite these values at runtime.

Edit Mask label

Displays the mask definition for the current component.


Font editor

See also

Use the Font editor to specify, at design time, a font and other font attributes for the selected component or form. Changes you make using the Font editor are reflected in the Font property for a component.

To open the Font editor,

1.	Select any component or the form.

2.	Do one of the following:

Click the ellipsis button in the Value column for the Font property or one of the other properties listed below that use the Font editor.

Double-click the Value column for the Font property or one of the other properties listed below that use the Font editor.

Font

Select a font from the list of all the available fonts you can use in your application.

Font Style

Select a style for the font. This combo box displays only those styles that are available for the selected font. For most of the available fonts, there are four possible styles:

Regular

Italic

Bold

Bold Italic

Size

Select a size for the font (in points). This combo box displays only those font sizes that are available for the selected font.

Effects

Check these options to make the text strike-through or underlined.

Color

Select a color for the font. This combo box lists all the available colors for the selected font.

Sample area

Displays a sample of the selected font before you apply it to the components. The font within this area is updated with every change you make to the font settings.

Script

Lists the available language scripts for the selected font.


Color editor

Use the Color editor to specify or define a color for the selected component. Changes you make using the Color editor are reflected in the Color property for a component.

To open the Color editor,

1.	Select any component or the form.

2.	Double-click the Value column for the Color property or one of the other properties listed below that use the Color editor.

Basic Colors grid

Displays selection of standard colors. Click a color to apply it to the selected component.

Custom Colors grid

Displays the colors that you have created. You can create custom colors by clicking Define Custom Colors.

Define Custom Colors

Click Define Custom Colors to expand the Color editor to show options that enable you to create your own colors.

Color field

Displays the spectrum of available colors. The crosshairs indicate the current color. For example, the crosshairs look like this when the color is a shade of yellow:

Click anywhere or drag in the color field to select a color. When you select a color here and then click Add To Custom Color, the selected color is added to one of the Custom Color boxes so you can use it again.

Color|Solid

Displays the currently selected color and its closest solid color. Double-click the solid color to make it the current color.

Hue

Enter a value for the hue. Hue is the "actual" color, for example, red, yellow-green, or purple. Hue refers to the color without regard to saturation or brightness (luminosity).

Sat(uration)

Enter a value for the saturation. Saturation refers to how much gray is in the color. The Sat(uration) field shows the saturation from 0 (medium gray) to 240 (pure color).

Note:	Saturation affects how clear the color is. Luminosity affects how bright the color is.

Lum(inosity) and the Luminosity Slider Control

Enter a value for the luminosity, or drag the pointer on the slide to set the luminosity. Luminosity is the brightness of a color. The Lum(inosity) field shows the luminosity from 0 (black) to 240 (white). The column to the right of the color field shows the range of luminosity for the current color. Slide the arrow to the right of the column up or down to adjust the luminosity. When you change the luminosity, the Red/Green/Blue color values also change.

Red/Green/Blue

Enter values for the proportion of red, green, and blue you want in your color. The values in these fields show the balance of red, green, and blue in the current color. This is sometimes called the RGB color. The range of available values for an RGB color is 0 to 255.

Add To Custom Colors

Click to add the color you have defined to the Custom Color grid on the Color editor.


Insert Object dialog box

Use the Insert Object dialog box at design time to insert an OLE object into an OLEContainer component. The OLEContainer component enables you to create applications that can share data with an OLE server application. After you insert an OLE server object in your application, you can double-click the OLEContainer component to start the server application.

Select whether or not you want to create a new file using the associated OLE server or use an existing file. If you use an existing file, it must be associated with an application that can act as an OLE server.

Create New

Choose Create New to specify that you want to launch a server application to create a new OLE object. After choosing Create New, the ObjectType list box is displayed.

Create From File

Choose Create From File to specify that the OLE object has already been saved as a file.  After choosing Create From File, the  File, Browse and Link controls are displayed.

Object Type

Select an application that you want to use as the OLE server. This list box displays all available applications that can be used as an OLE server. After you select an application, C++Builder launches that application.

File

Enter the fully qualified path for the file you want to insert into your application. The file you choose must be associated with an application that can be used as an OLE server.

Note: This option is available only when you have selected the Create From File radio button.

Browse

Click Browse to display the Browse dialog box, where you can select a file to use as the OLE server.

Note: This option is available only when you have selected the Create From File radio button.

Link

Check Link to link the object on the form to a file. When an object is linked, it is automatically updated whenever the source file is modified. When Link is unchecked, you are embedding the object, and changes made to the original are not reflected in your container.

Display As Icon

Check to display the inserted object as an icon on the form. When this option is checked, the Change Icon button is displayed.

Change Icon

Click Change Icon to open the Change Icon dialog box, where you can specify an icon and label for the object you inserted onto the form.

Note:	This option is available only when you have selected the Create From File radio button.


Browse dialog box

The Browse dialog box has multiple uses depending on where you open it. You can use the Browse dialog box for either of the following:

To load an existing file into the OLE container. The file you select must be associated with an application that can be used as an OLE server.

To select an icon to represent an OLE object on the form.

To open the Browse dialog box, do one of the following:

Click Browse in the Insert Object dialog box when you have Create From File selected.

Click Browse in the Change Icon dialog box.

Dialog box options

Source

Enter the name of the file you want to load or wildcards to use as filters in the Files list box.

Files

Displays the files in the current directory that match the wildcards in the Source edit box or the file type in the List Files Of Type combo box.

List Files Of Type

Choose the type of file you want to use as the OLE server. By default all files in the current directory are displayed in the Files list box.

Directories

Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the Source edit box or the file type in the List Files Of Type combo box appear in the Files list box.

Drives

Select the current drive. The directory structure for the current drive appears in the Directories list box.


Change Icon dialog box

Use the Change Icon dialog box to specify an icon and a label for the object you are placing on the form.

To open the Change Icon dialog box,

1.	On the Insert Object dialog box, check Display As Icon.

2.	Click Change Icon.

Icon Radio

Select which icon you want to use. There are three options:

Option	When selected

Current	Uses the current icon.

Default	Uses the default icon.

From File	Enables you to specify an icon using a fully qualified path name. If you do not know the icon name or the path, click Browse to open the Browse dialog box. The display box below the edit box shows all the available icons in the specified file. To choose an icon, select it.

Label

Enter a label that will appear below the icon on the form.

Browse

Click Browse to open the Browse dialog box, where you can select an icon to represent the inserted object on the form.

Sample Icon display

Displays how the icon and label will appear on the form.


Paste Special dialog box

Use the Paste Special dialog box to insert an object from the Windows Clipboard into your OLE container.

Source label

Displays the path of the file you are going to paste.

Paste/Paste Link Radio

Select Paste to embed the object on the form. When you embed an object on a form, your container application stores all the information for the object. It is not necessary to have an external file.

Select Paste Link to link the object to the form. When you link an object to a form, the main source is stored in a file so that when you update the object, the source file is also updated.

As

Lists the type of application object you are pasting. The application listed is the source application from which you received the object that you are pasting.


DDE Info dialog box

Use the DDE Info dialog box to specify, at design time, a DDE server application and a topic for a DDE conversation.

To open the DDE Info dialog box,

1.	Place a DDEClientConv component on the form.

2.	With the component selected, do one of the following:

Click the ellipsis button in the Value column for the DdeService property or DdeTopic property.

Double-click the Value column for the DdeService property or DdeTopic property.

Dialog box options

Dde Service

Specify the server application for the DDE conversation. The application you specify is entered into the Value column for the DdeService property.

You do not need to specify an extension for the server application.

If the directory containing the application is not on your path, you need to specify a fully qualified path.

Dde Topic

Enter the topic for a DDE conversation. The topic is a unit of data, identifiable to the server, containing the linked text. For example, the topic could be the file name of a spreadsheet.

When the server is a VCL-based application, the topic is the name of the form containing the data you want to link.

If the directory containing the topic is not on your path, you need to specify a fully qualified path.

Paste Link

Click Paste Link to paste the application name and file name from the contents of the Clipboard into the App and File edit boxes.

This button is active only when the Clipboard contains data from an application that can be a DDE server.


Filter editor

See also

Use the Filter editor to define filters for the OpenDialog component and the SaveDialog component. These common dialog boxes use the value of Filters in the List Files Of Type combo box to display certain files in the Files list box.

Use the Filter editor to edit the Filter property.

To open the Filter editor,

1.	Place an OpenDialog component or SaveDialog component on the form.

2.	With that component selected, do one of the following:

Click the ellipsis button in the Value column for the Filters property.

Double-click the Value column for the Filters property.

Filter Name column

Enter the name of the filter you want to appear in the Files Of Type combo box.

Filter column

Enter wildcards and extensions that will define your filter. For example, *.TXT would display only files with the .TXT extension.

To apply multiple file extensions to your filter, separate them using a semicolon (;).


Open dialog box

See also

Use the Open dialog box at design time to load a multimedia file into the MediaPlayer component.

To open the Open dialog box,

1.	Place a MediaPlayer component on the form.

2.	With that component selected, do one of the following:

Click the ellipsis button in the Value column for any of the properties listed below.

Double-click the Value column for either of the properties listed below.

Dialog box options

File Name

Enter the name of the file you want to load or wildcards to use as filters in the Files list box.

Files

Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List Files Of Type

Choose the type of file you want to load. When you are loading a report, the default file extenstion is .RPT. When you are loading a multimedia file, all files in the current directory are displayed. However, you can limit the display to wave files, midi files, or Windows video files.

Directories

Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box appear in the Files list box.

Drives

Select the current drive. The directory structure for the current drive appears in the Directories list box.


Viewing nested properties

Properties can have properties of their own, called nested properties. For example, the Font property of the Label component has nested properties, one of which is Style; the Style property in turn has its own nested properties.

Properties with nested properties show a plus (+) sign on their left side in the Object Inspector. You need to view these nested properties to set them.

To view nested properties,

Choose one of the following methods:

Double-click any property with a plus sign next to it.

The plus sign next to the top-level property changes to a minus (-) sign, and the nested properties are displayed.

To hide nested properties,

Double-click a property with a minus sign next to it.


ListView Items Editor

Use the ListView Items editor at design time to add or delete the items displayed in a listview component. You can add or delete new items and sub-items, and you can set the caption, image index, and state index for each item in the ListView Items editor.

To display the ListView Items editor,

Select the TListView object and double-click the Items property value in the Object Inspector.

Using the ListView Items editor

The ListView Items editor contains an Items group box with an Items list box, a New Item button, a New SubItem button, and a Delete button. When you first add a listview control to a form, the Items list box is empty and the New SubItem and Delete buttons are disabled. When you enter or change item properties for a selected item, the Apply button is enabled so that you can activate changes immediately.

The ListView Items editor also contains an Item Properties group box for setting the properties of the listview item currently selected in the Items list box. The Item Properties group box contains a Caption edit box, an Image Index edit box, and a State Index edit box.

Items group box

Create and delete listview items and subitems in the Items group box. To create a new item, click New Item. A default item caption appears in the Items list box. Specify an item's properties, including its caption, in the Items Properties group box. When you create a new item, or select an existing item, the New SubItem button is enabled so that you can nest items within other items in the listview. If the Items list box contains items, the Delete button is also enabled. To delete an item, select it in the Items list box and click Delete.

Item Properties group box

Set the properties for a selected item in the Item Properties group box. Enter a name for the item in the Caption edit box. As you enter the name, it changes in the Items list box.

To display an image to the left of an item that is not currently selected, specify the index number of the image in the Image Index edit box. To suppress image display, set Image Index to -1 (the default).

To display an image to the left of an item that is currently selected, specify the index number of the image in the State Index edit box. The index number represents an index into the StateImages property of the listview component. To suppress image display, set State Index to -1 (the default).


TreeView Items Editor

Use the TreeView Items editor at design time to add items to a treeview component, delete items from a treeview component, or load images from disk into a treeview component. You can specify the text associated with individual treeview items, and set the image index, selected index, and state index for items.

To display the TreeView Items editor:

Select the TTreeView object and double-click the Items property value in the Object Inspector.

Using the TreeView Items editor

The TreeView Items editor contains an Items group box with an Items list box, a New Item button, a New SubItem button, a Delete button, and a Load button. When you first add a treeview control to a form, the Items list box is empty, and the New SubItem and Delete buttons are disabled. When you enter or change item properties for a selected item the Apply button is enabled so that you can activate changes immediately.

The TreeView Items editor also contains an Item Properties group box for setting the properties of the treeview item currently selected in the Items list box. The Item Properties group box contains a Text edit box, and Image Index edit box, a Selected Index edit box, and a State Index edit box.

Items group box

Create, load, and delete treeview items and subitems in the Items group box. To load a set of existing treeview items from disk, click Load. To create a new item, click New Item. Default text for the item appears in the Items list box. Specify an item's properties, including its text, in the Items Properties group box.

When you create a new item, or select an existing item, the New SubItem button is enabled so that you can nest items within other items in the treeview. If the Items list box contains items, the Delete button is also enabled. To delete an item, select it in the Items list box and click Delete.

Item Properties group box

Set the properties for a selected item in the Item Properties group box. Enter text for the item in the Caption edit box. As you enter the name, it changes in the Items list box.

To display an image to the left of an item that is not currently selected, specify the index number of the image in the Image Index edit box. To suppress image display, set Image Index to -1 (the default).

To display an image to left of a selected item, specify the index number of the image in the Selected Index edit box. The index is zero-based. To suppress image display, set Selected Index to -1 (the default).

To display an additional image to the left of an item , specify the index number of the image in the State Index edit box. The index number represents an index into the StateImages property of the listview component. The index is zero-based. To suppress image display, set State Index to -1 (the default).


Collection Editor dialog box

See also

The Collection Editor dialog box is used to edit the items maintained by a collection object.  A collection object is a descendant of TCollection. The Collection Editor displays information about the items in the collection, and allows you to add, remove, or rearrange the individual items.  For some types of collection, additional buttons are provided to allow other manipulations of the list.

The items displayed in the list window of the Collection Editor can be selected using the mouse.  Once an item is selected, its properties and events can be set using the object inspector.  The following table indicates what properties of the items are displayed in the list window for each type of collection item, and how the collection is used.

Collection	Item type	Properties displayed	Use
TCheckConstraints	TCheckConstraint	ImportedConstraint, or, if no ImportedConstraint is blank, CustomConstraint	Represents record-level constraints for the data in a BDE dataset. (Constraints property)
TCoolBands	TCoolBand	Text	Represents a set of bands in a CoolBar component.  (Bands property)
TDBGridColumns	TColumn	FieldName	Represents the field binding and display properties of a column in a data-aware grid.  (Columns property)
THeaderSections	THeaderSection	Text	Represents the display properties of the sections in a HeaderControl object.  (Sections property)
TListColumns	TListColumn	Caption	Represents the columns of a report-style List View component.  (Columns property)
TStatusPanels	TStatusPanel	Text	Represents the individual panels of a StatusBar component.  (Panels property)
TWebActionItems	TWebActionItem	Name, PathInfo, Enabled, and Default	Represents the action items that create the responses to HTTP request messages for a Web dispatcher or Web module. (Actions property)

To display the Collection Editor dialog box, first place the component that uses the collection on a form. Select the property that is implemented using the collection (listed in parentheses in the preceding table), and click on the ellipsis.  For some components, the Collection Editor may also be displayed by right-clicking the component, and selecting the appropriate editor from the context menu.

Dialog box options

Item list

The Item list displays the properties listed in the third column of the preceding table for each item in the collection. The properties for a selected item are displayed in the Object Inspector and are edited there.

Add button

Adds a new item to the collection. You can select the item and edit its parameters in the Object Inspector.

Delete button

Removes the selected item from the collection.

Move Up/Down buttons

Change the order of the items. For most collections, the order determines the order in which items are displayed or used by the object that maintains the collection.

Add All Fields button (TDBGridColumns only)

Add a column for every field in the dataset to which the data-aware grid is bound.  This button is only enabled if the data-aware grid is bound to an active dataset.

Restore Defaults button (not for all collections)

Restore the default properties (obtained from the field component) of the currently selected column.  This button is enabled if the currently selected column is bound to a field (the FieldName property is set).

Read From Dictionary button (TCheckConstraints only)

Add a CheckConstraint object for every record-level constraint in the data dictionary.  Each CheckConstraint object will have its ImportedConstraint property set to the constraint from the dictionary.


ImageList Editor

Use the ImageList Editor at design time to add bitmaps and icons to a TImageList component.

While working in the image list editor, you can click Apply to save your current work without exiting the editor, or click OK to save your changes and exit the dialog. Using the Apply button is especially useful because once you exit the dialog, you can’t make any more changes to the existing images.

To display the ImageList editor:

Select the TImageListobject and double-click the component or right-click and select ImageList Editor.

Selected Image

The selected image control displays the currently selected image. This image can be changed by clicking on another image in the Images list view below. When an image is selected, you can delete it from the list of images. If the image was not added to the image list before the current invocation of the editor, you can use the other controls to alter its properties. However, once the image list editor is closed, these properties are fixed and the selected image controls are grayed if the ImageList Editor is again displayed and that image is selected.

Transparent color

Use the Transparent color drop-down to specify which color is used to create a mask for drawing the image transparently. The default transparent color is the color of the bitmap's left-most pixel in the bottom line. You can also change the transparent color by clicking directly on a pixel in the selected image.

When an image has a transparent color, any pixels in the image of that color are not rendered in that color, but instead appear transparent, allowing whatever is behind the image to show through.

If the image is an icon, Transparent color appears greyed and the transparent color is set to clNone. This is because icons are already masked.

Fill color

Use the Fill color drop-down to specify a color that is added around the edges of the selected image when it is smaller than the dimensions indicated by the Height and Width properties of the image list control.

This control is grayed if the selected image completely fills the dimensions specified by the image list (that is, if it is at least as big as the Height and Width properties). This control is also grayed for icon images, because icons act like masks with any outer boundaries transparent.

Options

Use the Options radio buttons to indicate how the image list should render the selected image if it does not fit exactly in the dimensions specified by the image list’s Height and Width properties. (These buttons are disabled for icons)

Setting	Description

Crop	Displays the section of the image beginning at the top-left, extending the image list width and height towards the bottom-right.

Stretch	Causes the entire image to stretch so that it fits the image list width and height

Center	Centers the image within the image list width and height. If the image width or height is larger than the imagelist width or height, the image may be clipped.

Images

Contains a preview list view of all the images in the image list, and controls for adding or deleting images from the list. Each image is displayed within a 24x24 area for easier viewing of multiple images. Beneath each image is a caption that indicates the zero-based position of the image within the image list. You can edit the caption to change an image’s position in the list or drag the image to its new position.

Add

Displays the Add Images dialog box, which lets you select one or more bitmaps or icons to add to the image list. The images then appear highlighted in the preview list view and their captions are assigned sequential values in the image list.

If a bitmap is larger than the image list width or height by even increments, a prompt appears asking whether the ImageList editor should divide the bitmap into several images. This is useful for toolbar bitmaps, which are usually composed of several small images in a sequence and stored as one larger bitmap.

Delete

Removes the selected images from the image list. All images left after clicking Delete are repositioned so they are a contiguous zero-based list.

Clear

Removes all images from the imagelist.

Export

Allows you to save the selected image to a file. This file contains the bitmap in it’s currently altered state, including any cropping or stretching.


ActionList Editor

Use the ActionList Editor at design time to add actions to a TActionList component.

To display the ActionList editor:

Select the TActionListobject and double-click the component or right-click and select ActionList Editor.

Tool bar

At the top of the ActionList editor is a tool bar containing 4 buttons. These are as follows

Button	When clicked

New Action	Inserts a new action into the list. By clicking the drop-down arrow next to the button, you can choose whether to add a new action that you define, or a standard (predefined) action. If you choose Standard Action, you will be presented with a dialog where you can choose the predefined action.

Delete	Deletes the action currently selected in the list boxes.

Arrow buttons	Moves the currently selected action up or down to change its position in the list.

Right click the Tool bar to display the ActionList tool bar context menu. This contains one item:

Command	When clicked

Text labels	Displays or hides the labels on the buttons in the toolbar.

List boxes

The lower portion of the ActionList editor contains two list boxes that represent the current list of actions. The first list indicates the value of the Category property of the action. You can change this value by selecting the action and changing the value of the Category property in the Object Inspector.

The second list indicates the name of the action. You can change this value by selecting the action and changing the value of the Name property in the Object Inspector.

Right click in the lower portion of the ActionList editor to display the ActionList context menu. This contains the following items:

Command	When clicked

New Action	Adds a new (not predefined) action to the Action List editor. You can then use the object Inspector to edit its properties.

New Standard Action	Displays the Standard Actions dialog box, where you can select a predefined action.

Move Up	Moves the currently selected action toward the beginning of the list.

Move Down	Moves the currently selected action toward the end of the list.

Cut	Cuts the currently selected action to the clipboard, removing it from the list.

Copy	Copies the currently selected action to the clipboard without removing it from the list.

Paste	Pastes an action from the clipboard above the currently selected action.

Delete	Deletes the currently selected action.

Select All	Selects all actions in the list.

Panel Descriptions	Displays or hides labels over the listbox indicating their purpose.

Toolbar	Displays or hides the toolbar.


Remote debugging

The debugger supports remote debugging of EXEs, DLLs, and packages that are built with debug symbols. The remote debug server is not supported on Windows 95 or Windows 98 as a service. The main components of remote debugging are:

The "client" IDE, which provides the UI for the debugging session (BCB.exe).

The "debug server" on the remote machine (bordbg41.exe). The server's function is to control the debuggee and interact, via a network connection, with the IDE. The debug server must have access to the debug kernel dll (bordbk41.dll) and an evaluator dll (dcc40.dll). To install you will need to run setup.exe located in the RDEBUG directory.

Starting the debug server

To start the server, you need either adminstration rights or debugging rights on the remote machine. The client IDE will not be able to connect to the remote debug server unless the latter is running.

There are two ways to start the debug server, manually, using the BORDBG41.EXE or via an NT service: On Windows 95 or 98, NT services are not available and the debug server must be started manually.

To start the server manually, run BORDBG41.EXE -listen from the command line (the only option for Windows95/98).

Installing the debug server as an NT service should be done via the remote debug setup program. You can use the Services applet from the Control Panel to check whether the "Borland Remote Debugging Service" is installed and running. (NT only).

Setting the client IDE

1.	Under Remote tab of the Run|Parameters menu, set the Remote path to directory and EXE name as the server will see it.

2.	Set remote host to the server machine name or IP address.

3.	Click Debug project in the IDE.

Note: The server needs to be able to see the EXE and the symbols. If you run the server as a service, the server will not have access to network shared drives. In this case, you have to either copy the symbols and EXE to the server machine, or set the output directory to be on the server. IDE needs to find the source. For example:

Set the Remote Path on the Remote tab of the Run|Parameters menu relative to the remote system, that is, as the remote system sees it.

Set the Final output (on the Directories/Conditionals page of the Project Options dialog) relative to the local machine (IDE). Use the shared drive+path to identify this output directory.

Connecting to the remote machine

Before starting remote debugging the IDE needs to connect to the remote machine. To do this, it needs to specify a machine name and, optionally, a port number and password.

The local and remote machines must be linked by TCP/IP. Communication for remote debugging uses a TCP socket and relies on standard internet name resolution to establish this connection (DNS). This means the local machine must be able to obtain an IP address for the remote machine. The command "nslookup name" utility can be used to confirm the IP address bound to a particular name. Note that the DNS and Microsoft networking names for a machine can be different. Both names can be obtained from the networking applet in the control panel.

The client IDE and debug server currently use port 8000 as a connection point.

BORRDBG41.EXE has three command-line options:

1.	-listen (have the server wait for a connection; non-service mode)

2.	-install (installs the service (as an NT service only) does not start service)

1.	-remove (removes the service, stopping it if necessary)

Using the server under Windows 95 or Windows 98

On Windows 95 or Windows 98, the Remote Debugging service can only be run as a program. To run as a program, run Bordbg41.exe -listen from the command line or a shortcut.


Multiple process debugging

The integrated debugger supports multiple process debugging on NT. You can select and debug a process in one of several ways:

Project Manager	Add the projects you want to debug to the Project Manager. You cannot compile while debugging multiple processes, so choose Project|Build All before you begin debugging.

Thread Status box	Choose View|Debug Windows|Threads to use the Thread Status box to set and change the current process. The green arrow indicates the current process. The blue arrow indicates non-current processes.

Run|Parameters dialog	Use the Run|Parameters to start a new process debugging.

Run|Attach to Process	Use the Run|Attach to Process to attach to an already running process.

Debug toolbar Run button	Use the Debug toolbar drop down Run button to select a process from the drop down list. Selecting the process will make it active.

Multiple process debugging includes remote debugging. For example, the IDE can be used to debug three processes on machine "A", two on machine "B", and one local process. For more information, see Remote debugging.

Because processes may share common files, you should always do a Project|Build All projects before starting a multi-process debugging session

Inspectors are associated with the thread that was active when they were created. When a thread terminates, only the inspectors that were created while the process was active are destroyed.

Multi-process debugger views

Most of the debugger views, from the View|Debug Windows menu, are multi-process aware and display the current process EXE name and thread ID in the caption of the windows. No additional information is show for single process, single-threaded processes. The thread ID is shown for single process, multi-threaded processes. The process name and ID is included for multiple processes; multi-threaded processes also include the thread ID.

While debugging multiple processes, you can temporarily set debugger options for specific processes from the Thread Status box. See Setting debugging options for specific processes.


Multiple Evaluators
Multiple evalutors

Multiple evalutor support is intended for developers debugging processes written in more than one language. Currently, evaluators for C/C++ and Pascal are available.

Summary of how it works

Each thread has a current evaluator which is responsible for handling "evaluate", "inspect", "watch" and other debugger requests addressed to the thread. When a process starts, the initial thread is bound to the IDE's "default" evaluator. For C++Builder the default is the C/C++ evaluator and for Delphi the default is the Pascal evaluator. If the process loads a symbol table that contains debug-information for another evaluator, an additiobal evaluator is added to the process. From that point on, each time a thread stops its current evaluator is determined from its execution point. If there is debug information at the current execution point and if that debug information corresponds to an evaluator other than the one to which the thread is bound, the thread's evaluator is switched to the one matching the debug-information.

Switching evaluators: Evaluator switching can be disabled by checking the "Disable multiple evaluators" option. If this is enabled all the process' s threads will remain bound to the default evaluator.

Inspectors: Inspectors are bound to the evaluator used to create them. If a thread is currently bound to the C/C++ evaluator, an inspector created when the thread was previously bound to the Pascal evaluator will refresh correctly.

Watches: The Watch List depends on the current evaluator. Thus, unlike the inspector example above, a watch of a Pascal expression may not refresh correctly if the thread's evaluator switches to the C/C++ evaluator.

Local variables: Like the Watch view, the contents of the Local Variables window also depend upon the current evaluator.


Distributed debugging

See also

The integrated debugger supports distributed debugging on NT for both:

COM Cross-Process Support

CORBA Cross-Process Support

Cross-process debugging is not supported on Windows 95/98 because those operating systems do not have multiple-process debugging support.

Stack support

When both the source and target of a cross-process remote procedure call (RPC) are under debugger control (for both the COM and CORBA case), it is assumed that the stack of the source only includes a line pointing to the stack of the target. If the target is not under debugger control, the source thread's stack is augmented with any additional information that can be obtained from the event trace.


COM cross-process support

This support is provided to help developers debug processes that exchange COM cross-process remote procedure calls (RPCs). When you enable "COM Cross-Process Support" in the IDE, three features are activated: remote process attach, call tracing and cross-process stepping.

Cross-process attach

The debugger attempts to gain control of the target of a cross-process remote procedure call (RPC) when the call begins. If this attempt succeeds, the list of debugger processes under your control will increase by one. If the target process is on another machine, the attempt will suceed only if remote debugging has been enabled on that machine. The event log and the process/Thread Status box can be inspected to see whether the list of debuggee processes has grown. The "target" of a cross-process RPC is the server if the process originally being debugged was a client or the client if the process originally debugged was the server.

Call tracing

A trace of all cross-process RPC calls is added to the event log. Up to three entries are created for each call:

a client-side entry indicating the client is calling the server

a server-side entry indicating the server is starting to work on the call

a client-side call indicating completion of the call

Each entry includes the IID (interface identifier) and the zero-based index of the method being called.

Cross-process stepping

When "Cross-Process Support" has been enabled, step-into operations will follow the "distributed" thread of control, rather than the actual thread, and thus may terminate in a process and thread other than the one where they originated. This behavior can be by-passed by issuing a "step-to-next-source" command (SHIFT-F7) rather than a simple Step-Into command (F7). The following conditions must occur for the step-into operation to complete in another thread:

The debugger must be successfully attached to the target process

The method being invoked must include debug information for the call-site being returned to

The stack view indicates that the source thread is blocked until completion of code excuting in the target thread.


CORBA cross-process support

This support is intended to help debug applications that use the VisiBroker ORB. Enabling "CORBA Cross-Process Support" provides the same functionality described for COM Cross-Process Support and extends this support with two additional features:

Trace-Only Processes

ORB-Event Breakpoints

When setting a breakpoint on an event while debugging a CORBA application, it is useful to keep the Call Stack and Event Log windows open. They can provide useful information, such as indicating what initiated the event break.

ORB-event breakpoints

The event trace generated from CORBA remote procedure calls (RPCs) is more detailed than that available for COM RPCs. For a list of the ORB events that may be generated, see ORB Events.

Relevant information is included with each of these events; for example, the operation name and transaction id for receive/reply events, the interface and host name for bind events.

In addition to event tracing, you can stop on each occurrence of these events. The decision to stop can be augmented with additional conditions based on the information available for each event. For example, stop if the operation name is "X" or the host name is "Y".

Trace-only processes

The debugger may not always be able to obtain control of the process that is the target of a cross-process remote procedure call (RPC). This can happen if the target is executing on a non-Win32 platform on a host where remote debugging is not enabled, or because of access restrictions on the target process. In the case of a COM RPC, no information about the target will be available from the debugger. However, in the case of a CORBA RPC, an event stream is generated from the target even when that target cannot be brought under debugger control. Processes which cannot be debugged but which generate an event trace are called "Trace-Only Processes".

Information about trace-only processes is limited to their event log trace. In particular, no information about threads or libraries is available.

Operations on trace-only processes are as follows. If the process is stopped because of an event breakpoint, it may be continued or its current thread may be stepped. Stepping the current thread of a trace-only process is synonymous with running until a particular event occurs:

If a StepInto command is issued and the current event is ClientPrepareRequest or ClientSendRequest the debugger will stop the process that services that request when it generates a ServerReceiveRequest event.

If a StepOver command is issued and the current event is ClientPrepareRequest or ClientSendRequest the debugger will stop the current process when it generates a ClientSendRequestFailed, ClientSendRequestSucceeded, ClientReceiveReply, or ClientReceiveReplyFailed for the same request.

Because no stack is available for the current thread of a trace-only process, the stack of the thread that initiated the RPC activity will show additional entries that describe the status of the RPC call.

Exceptions

You can set the IDE under Tools|Debugger|Options, Language Exceptions to either handle (stop execution of the process) or ignore the following exceptions:

VisiBroker exceptions

Internal exceptions

CORBA system exceptions

CORBA user exceptions


Setting debugging options for specific processes

When debugging multiple processes, you can set process-specific options.

To set a particular process’s debugging options:

1.	Run the application containing the process you want to debug.

2.	Choose View|Debug Windows|Threads to display the Thread Status box.

3.	Select the process for which you want to set local debugging options.

4.	Right-click and choose Process Properties.

The Temporary Process Options dialog box is displayed where you can set debugger options similar to setting them globally using Tools|Debugger Options. Those options which are relevant to debugging specific processes are included in the Temporary Process Options dialog box.


Working with string lists

See also

There are numerous occasions when a C++Builder application needs to deal with lists of character strings. Among these lists are

The items in a list box or combo box

The lines of text in a memo field

The list of fonts supported by the screen

A row or column of entries in a string grid.

Although applications use these lists in various ways, C++Builder provides a common interface to all of them through an object called a string list, and goes even farther by making them interchangeable, meaning you can, for example, edit a string list in a memo field and then use it as the list of items in a list box.

You have probably already used string lists through the Object Inspector. A string-list property appears in the Object Inspector with [TStrings] in the Value column. When you double-click [TStrings], you get the String List editor, where you can edit, add, or delete lines.

You can also work with string lists at runtime. These are the most common types of string-list tasks:

Manipulating the strings in a list

Loading and saving string lists

Creating a new string list

Adding objects to a string list

Operating on objects in a string list


Manipulating the strings in a list
Manipulating strings in a list

See also

Quite often, you need to write code to work with strings in an existing string list. The most common case is that some component in the application has a string-list property, and you need to change it or get strings from it.

These are the common operations you might need to perform:

Counting the strings in a list

Accessing a particular string

Finding the position of a string

Adding a string

Moving a string

Deleting a string

Copying a complete string list

Iterating the strings in a list


Counting the strings in a list

See also

Example

To find out how many strings are in a string list, use the Count property.

Count is a read-only property that indicates the number of strings in the list. Since the indexes used in string lists are zero-based, Count is one more than the index of the last string in the list.


Example

The following example returns the number of different fonts the current screen supports.

FontCount = Screen->Fonts->Count;


Accessing a particular string

See also	Example

Each string list has an indexed Strings, property which you can treat like an array of strings. For example, the first string in the list is Strings[0].

To access a particular string in a string list,

Refer to it by its ordinal position, or index, in the list.

The string numbers are zero-based, so if a list has three strings in it, the indexes cover the range 0..2.

To determine the maximum index,

Check the Count property.

If you try to access a string outside the range of valid indexes, the string list throws an exception.


Example

The following example sets the first line of text in a memo field to be "This is the first line."

Memo1->Lines->Strings[0] = "This is the first line.";


Finding the position of a string within a list

See also	Example

If you have a list of strings, you can easily determine its position in a string list, or whether it is even in the list.

To locate a string in a string list,

Use the string list's IndexOf method.

IndexOf takes a string as its parameter, and returns the index of the matching string in the list, or -1 if the string is not in the list.

Note:	IndexOf works only with complete strings. That is, it must find an exact match for the whole string passed to it, and it must match a complete string in the list. If you want to match partial strings (for instance, to see if any of the strings in the list contains a given series of characters), you need to iterate the list yourself and compare the strings.


Example

The following example uses IndexOf to determine whether a given file name is in the list of files in a file list box:

if (FileListBox1->Items->IndexOf("AUTOEXEC.BAT") > -1)

  // you're in the root directory


Adding a string to an existing list

See also	Example

There are two ways to add a string to a string list:

Add it to the end of the list

Insert it in the middle of the list

To add a string to the end of the list,

Call the Add method, passing the new string as the parameter. The added string becomes the last string in the list.

To insert a string into the list,

Call the Insert method, passing two parameters: The index where you want the inserted string to appear, and the string.

If the list does not already have at least two strings, you will get an index-out-of-range exception.


Example

The following example inserts the string 'Three' as the third string in a list:

Insert(2, "Three");

Note:	If the list doesn't already have at least two strings, C++Builder throws an index-out-of-range exception.


Moving a string within a list

See also	Example

You can move a string to a different position in a string list, such as when you want to sort the list. If the string has an associated object, the object moves with the string.

To move a string in the list,

Call the Move method, passing two parameters: the current index of the item and the index where you want to move the item to.


Example

The following example moves the third string in a list to the fifth position.

Move(3, 5);


Deleting a string from a list

See also	Example

When you have an existing list of strings, you might often want to remove a string from that list.

To delete a string from a string list,

Call the string list's Delete method, passing the index of the string you want to delete.

If you do not know the index of the string you want to delete, use the IndexOf method to locate it.

To delete all the strings in a string list,

Use the Clear method.


Example

The following example uses IndexOf to determine the location of a string in a list, and deletes that string if present:

int RedTape = ListBox1->Items->IndexOf("bureaucracy");

if (RedTape > -1)

  ListBox1->Items->Delete(RedTape);


Copying a complete string list

See also	Example

Copying the strings from one list to another overwrites the strings that were originally in the destination list.

To copy a list of strings from one string list to another,

Assign the source list to the destination list.

Even if the lists are associated with different kinds of components (or no components at all), C++Builder handles the copying of the list for you.

However, sometimes you want to append a new string list to an existing list.

To add a list of strings to the end of another list,

Call the AddStrings method, passing as a parameter the list of strings you want to add.


Examples

The following example copies the items from a combo box into a memo:

Memo1->Lines = ComboBox1->Items;

The following example adds all the items from the combo box to the end of the memo:

Memo1->AddStrings(ComboBox1->Items);


Iterating the strings in a list

See also	Example

Many times you need to perform an operation on each string in a list, such as searching for a particular substring or changing the case of each string.

To iterate through each string in a list,

Use a for loop with an Integer-type index. Inside the loop you can access each string and perform the desired operation.

The loop should run from zero up to one less than the number of strings in the list (Count - 1).


Example

The following example iterates the strings in a list box and converts each one to all uppercase characters in response to a button click:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  for (int Index = 0; Index < ListBox1->Items->Count; i++)

    ListBox1->Items->Strings[Index] = UpperCase(ListBox1->Items->Strings[Index]);

}


Loading and saving string lists

See also	Example

You can easily store any string list in a text file and load it back again (or load it into a different list).

You can also use the same mechanism to save lists of items for list boxes or complete outlines.

To load a string list from a file,

Call the LoadFromFile method and pass the name of the text file to load from.

LoadFromFile reads each line from the text file into a string in the list.

To store a string list in a text file,

Call the SaveToFile method and pass it the name of the text file to save to.

If the file does not already exist, SaveToFile creates it. Otherwise, it overwrites the current contents of the file with the strings from the string list.


Example

The following example loads a copy of the AUTOEXEC.BAT file from the root directory of the C drive into a memo field and makes a backup copy called AUTOEXEC.BAK:

void __fastcall TForm1::FormCreate(TObject *Sender)

{

  AnsiString FileName;	//storage for file name

  FileName = "C:\\AUTOEXEC.BAT";	// set the file name

  Memo1->LoadFromFile(FileName); // load from file

  Memo1->SaveToFile(ChangeFileExt(FileName, "BAK")); // save to backup

}


Creating a new string list

See also

Most of the time when you use a string list, you use one that is part of a component, so you do not have to construct the list yourself. However, you can also create standalone string lists that have no associated component. For instance, your application might need to keep a list of strings for a lookup table.

When you create your own string list you must remember to free the list when you finish with it. There are two distinct cases you might need to handle:

A list that the application creates, uses, and destroys all in a single routine

A list that the application creates, uses throughout runtime, and destroys before it shuts down

The way you create and manage a string list depends on the string list type. It can be either of the following:

Long-term string lists

Short-term string lists


Short-term string lists

See also	Example

Short-term string lists are useful if you need to use a string list only for the duration of a single routine. You can create it, use it, and destroy it all in one place. This is the safest way to use string list objects.

Because the string list object allocates memory for itself and its strings, it is important that you protect the allocation by using a try..__finally block to ensure that the object frees its memory even if an exception occurs.

The basic outline of the use of a short term string list, then, is to

1.	Construct the string-list object.

2.	In the try part of a try..__finally block, use the string list.

3.	In the __finally part, free the string-list object.


Example

The following event handler responds to a click on a button by constructing a string list, using it, and then destroying it again.

void __fastcall TForm1::Button1Click(TObject *Sender)

{

  TStrings *TempList = (TStrings)new TStringList;

  try
  {

    // use the string list

  }

  __finally

  {

    delete TempList;

  }

}


Long-term string lists

See also

Long-term string lists are useful when you need a string list that is available at any time while your application runs. You need to construct the list when the application is first executed, then destroy it before the application terminates.

To create a string list that is available throughout runtime,

1.	Add a field of type TStrings to the application's main form object, giving it the name you want to use.

2.	Create a handler for the main form's OnCreate event. The create-event handler is executed before the form appears onscreen at runtime.

3.	In the create-event handler, construct the string-list object.

4.	Create a handler for the main form's OnDestroy event. The destroy-event handler is executed just after the main form disappears from the screen before the application stops running.

Any other event handlers can then access the string list by the name you declared in the first step.


Adding objects to a string list

See also	Example

In addition to its list of strings, stored in the Strings property, a string list can also have a list of objects, which it stores in its Objects property. Like Strings, Objects is an indexed property, but instead of an indexed list of strings, it is an indexed list of objects.

If you are just using the strings in the list, it does not matter whether you have objects: The list does nothing with the objects unless you specifically access them. Also, it does not matter what kind of object you assign to the Objects property. C++Builder just holds the information; you manipulate it as you need to.

Note:	Some string lists do not allow objects, because it does not make sense to have them. For example, the string lists representing the lines in a memo or the pages in a notebook cannot have associated objects.

To associate an object with an existing string,

Assign the object to the Objects property at the same index.

Although you can assign any type of objects you want to Objects, the most common use is to associate bitmaps with strings for owner-draw controls. The important thing to remember is that strings and objects in a string list work in pairs. For every string, there is an associated object, although by default, that object is nil.

It is also important to understand that the string list does not own the objects associated with it. That is, destroying the string-list object does not destroy the objects associated with the strings.


Operating on objects in a string list

See also

For every operation you can perform on a string list with a string, you can perform a corresponding operation with a string and its associated object. For example, you can access a particular object by indexing into the Objects property, just as you would the Strings property. The biggest difference is that you cannot omit the name Objects, since Strings is the default property of the string list.

The following table summarizes the properties and methods you use to perform corresponding operations on strings and objects in a string list.

Operation	For strings	For objects

Access an item	Strings property	Objects property

Add an item	Add method	AddObject method

Insert an item	Insert method	InsertObject method

Locate an item	IndexOf method	IndexOfObject method

Methods such as Delete, Clear and Move operate on items as a whole. That is, deleting an item deletes both the string and the corresponding object. Also note that the LoadFromFile and SaveToFile methods operate on only the strings, since they work with text files.

Accessing associated objects

You access objects associated with a string list just as you access the strings in the list. For example, to get the first string in a string list, you access the string list's Strings property at index 0: Strings[0]. The object corresponding to that string is Objects[0].


Example

The following example associates a bitmap called AppleBitmap with the string 'apple' in the string list named Fruits.

Fruits->Objects[Fruits->IndexOf("apple")] = AppleBitmap;

You can also add objects at the same time you add the strings, by calling the string list's AddObject method instead of Add, which just adds a string. AddObject takes two parameters, the string and the object. For example,

Fruits->AddObject("apple", AppleBitmap);


StringTable editor

See also

There are two columns in the StringTable editor, the Identifier column and the Text column. The Identifier column is read-only and lists the unique identifier of the string listed in the Text column. To edit a string in the Text column, just place the cursor in the cell you want to change and edit. The Text column is always in edit mode when you enter it.

Strings can contain escape sequences, but the StringTable editor will not accept invalid escape sequences. If the escape sequence is invalid, the StringTable editor will automatically insert the backslash character.

Note:

The strings in the Text column must be within quotation marks in order for you to edit the strings. The StringTable editor will not allow you to proceed until the string is formatted correctly with double quotes.

To edit longer strings, select the string and open the Multi-line editor. There are four ways of opening the Multi-line editor:

Click the Multi-line editor button on the toolbar.

Double-click the string’s Identifier code.

Select the string’s Identifier code and press Enter.

Press Ctrl+E.

To enter a carriage return in the Multi-line editor, press Ctrl+Enter. The code (/012) for a carriage return will be entered at the cursor position.

Saving .RC files in the StringTable editor

When you press the Save button on the toolbar, your data is saved and compiled. The editor calls Brcc32.exe to compile the .RC file. When Brcc32.exe is called to compile your .RC file, it uses your project’s search path (Brcc32.exe equivalency: include path), conditional defines, and unit output directory (Brcc32.exe equivalency: output file name).

Note:

If you specify a unit output directory, the StringTable editor appends the name of the .RC file to the end of the unit output directory to complete the output file name.

Warning:

The StringTable editor always uses the .RC file name to generate the .RES file. So, if the .RC file names is File1.rc, the generated filename will be File1.res. If the names of the .RC and .RES files do not match in the $R directive, C++Builder will use the incorrect .RES file. This is done to keep the compiled files in sync with the source files.


Watch List

To display the Watch List, choose View|Debug Windows|Watches. The Watch List displays the current value of the watch expression based on the scope of the execution point.

The Watch List shows the process and/or thread ID of the process or thread being viewed. The process ID is only shown if more than one process is loaded in the debugger. The thread ID is only shown if the process whose state you are examining contains more than one thread.

The left side of the Watch List shows the expressions entered as watches. Corresponding data types and values appear on the right. Values of compound data objects (such as arrays and structures) appear between braces { }.

The Watch List will be blank if you have not added any watches.

If the execution point moves to a location where any of the variables in an expression is undefined (out of scope), the entire watch expression becomes undefined. If the execution point returns to a location where the watch expression can be evaluated (that is, if the execution point re-enters the scope of the expression), the Watch List again displays the current value of the expression.

Watch List commands

Right-click the Watch List to access the following commands that enable you manipulate watch points:

Edit Watch	Opens the Watch Properties dialog box that lets you modify the properties of a watch

Add Watch	Opens the Watch Properties dialog box that lets you create a watch

Enable Watch	Enables a disabled watch expression

Disable Watch	Disables an enabled watch expression

Delete Watch	Removes a watch expression

Enable All Watches	Enables all disabled watch expressions

Disable All Watches	Disables all enabled watch expressions

Delete All Watches	Removes all watch expressions

Stay On Top	Keepsthe window visible when out of focus

Break When Changed	Add a new Data Watch breakpoint

Dockable	Toggles the window for docking


Edit Watch (Watch List context menu)

Choose Edit Watch from the Watch List context menu to open the Watch Properties dialog box, where you can create and modify watches. After you create a watch, use the Watch List to display and manage the current list of watches.

Alternate ways to perform this command are:

Choose Run|Add Watch.

Choose Add Watch At Cursor from the Code editor context menu.

Right-click an existing watch in the Watch List and choose Edit Watch from the Watch List context menu.


Add Watch (Watch List context menu)

Choose Add Watch from the Watch List context menu to open the Watch Properties dialog box, where you can create and modify watches. After you create a watch, use the Watch List to display and manage the current list of watches.

Alternate ways to perform this command are:

Choose Run|Add Watch.

Choose Add Watch At Cursor from the Code editor context menu.


Enable Watch (Watch List context menu)

Choose Enable Watch from the Watch List context menu to enable a disabled watch expression.

Disabling a watch hides the watch from the current program run. When you disable a watch, its settings remain defined, but the IDE does not evaluate the watch.

Disabling watches improves performance of the debugger because it does not monitor the watch as you step through or run your program. When you set a watch, it is enabled by default.


Disable Watch (Watch List context menu)

Choose Disable Watch from the Watch List context menu to disable an enabled watch expression.

Disabling a watch hides the watch from the current program run. When you disable a watch, its settings remain defined, but the IDE does not evaluate the watch.

Disabling watches improves performance of the debugger because it does not monitor the watch as you step through or run your program. When you set a watch, it is enabled by default.


Delete Watch (Watch List context menu)

Choose Delete Watch from the Watch List context menu to remove a watch expression.

When you no longer need to examine the value of an expression, you can delete the watch from the debugging session. This command is not reversible.


Enable All Watches (Watch List context menu)

Choose Enable All Watches from the Watch List context menu to enable all disabled watch expressions.

Disabling a watch hides the watch from the current program run. When you disable a watch, its settings remain defined, but the IDE does not evaluate the watch.

Disabling watches improves performance of the debugger because it does not monitor the watch as you step through or run your program. When you set a watch, it is enabled by default.


Disable All Watches (Watch List context menu)

Choose Disable All Watches from the Watch List context menu to disable all enabled watch expressions.

Disabling a watch hides the watch from the current program run. When you disable a watch, its settings remain defined, but the IDE does not evaluate the watch.

Disabling watches improves performance of the debugger because it does not monitor the watch as you step through or run your program. When you set a watch, it is enabled by default.


Delete All Watches (Watch List context menu)

Choose Delete All Watches from the Watch List context menu to remove all watch expressions.

When you no longer need to examine the value of an expression, you can delete the watch from the debugging session. This command is not reversible.


Stay On Top

When this option is checked, the Watch List stays visible when not in focus.


Break When Changed

Select Break When Changed to add a new Data breakpoint on the selected watch. A data breakpoint is only valid for the current debug session. After the process is terminated, the breakpoint is disabled. At the start of the next debug session you can re-enable the breakpoint by selecting Break When Changed again. You can also use the Enable command in the breakpoint view.


Thread Status box

Choose View|Debug Windows|Threads to view the Thread Status box.

Use this status box to view the status of all processes and threads of execution that are executing in each application being debugged.

Thread status box

Thread ID	Displays the OS assigned thread ID and process name.

State	The thread state is Runnable, Stopped, Blocked, or None; for processes, the state indicates how the process was created: Spawned, Attached, or Cross-process Attach.

Location	Displays the source position. Displays the address if there is no source location available. If the process is remote, the name of the remote machine is shown.

Status

The thread status displays one of the following:

Breakpoint	The thread stopped due to a breakpoint.

Faulted	The thread stopped due to a processor exception.

Unknown	The thread is not the current thread so its status is unknown.

Stepped	The last step command was successfully completed.

Threads and multiple process debugging

The threads shown in the thread status box can be running in the same process or in different processes. The first process loaded appears at the top of the list and additional processes get added to the bottom of the list. As a process terminates, it is removed from the list. Each process can have one or more threads which it owns. These threads are shown in the list directly under their owning process. The main thread is directly under its owning process and new threads which the process creates get added to the bottom of that process' thread list. As threads terminate, they are removed from the list

There is the concept of current process and current thread. The current process and current thread become the context for the next user action (run, pause, reset, etc.) Also, most debugger views show information pertinent to the current process and current thread. The current process is denoted using a green arrow glyph. Non-current processes are denoted using a light blue arrow glyph.

You can change the current process by selecting a non-current process or thread and choosing 'Make current' from the popup menu. When invoked on a process, that process and its current thread become current. When invoked on a thread which is not owned by the current process, the thread's owning process become current.

When a debug event occurs (breakpoint, exception, paused), the thread status view indicates the status of each thread as it executes. Using the context menu, you can make a different thread or process current. When a thread is marked as current, the next step or run operation is relative to that thread.

For more information, see Multiple Process Debugging, Setting debugging options for specific processes, and RunUntilReturn.

Thread Status box commands

Right-click the Thread Status box to access the following commands:

View Source	Displays the Code editor at the corresponding source location of the selected thread ID, but does not make the Code editor the active window.

Go to Source 	Displays the Code editor at the corresponding source location of the selected thread ID and makes the Code editor the active window.

Make Current	Makes the selected thread the active thread process if it is not so already. Iif the thread is not already part of the active process, its process also becomes the active process.

Terminate	Terminates the process, if a process is selected, or the process that the thread is part of, if a thread is selected.

Process Properties	Lets you set debugger options temporarily for a particular process during the debugging session.


Modules window

See also

Use the context menus (right-click) in the Modules window to add modules to the Modules window, halt program execution when a module is loaded, or navigate to entry points or display a module’s source file in the Code editor.

In the Module pane (upper left)

Choose Break On Load to halt the execution of the application when it loads the selected module into memory.

If the selected module is already loaded, choose Add Module to add a new module to the Modules window. Add Module displays the Add Module dialog box.

If the selected module is not yet loaded, choose Edit Module to replace it with a different module. Edit Module displays the Edit Module dialog box.

In the Source pane (lower left)

Choose Edit Source to display the source code for the module in the code editor. Edit Module transfers focus to the code editor so that you can edit the source.

Choose View Source to display the source code for the module in the code editor without changing focus away from the Modules window.

If a file cannot be found, add the path to the file to the Debugger Source path on the Project|Options|Directories/Conditionals option page.

In the Entry point pane (right)

Choose Go to Entry Point (Enter is the shortcut key) to display the module’s entry point and address in the CPU window. The entry point is only shown if the source for it can found.

You can sort the modules listed by entry point name or by address by clicking either column header.

Note:	The runtime image base address is the memory offset, in hexadecimal, where the module actually loads, as distinct from the preferred image base address you may have specified in the Project Options window.

Modules and multiple process debugging

The Modules window shows a list of all processes under control of the debugger as well as a list of the modules currently loaded by each process. The first process loaded appears at the top of the list and additional processes get added to the bottom of the list. As a process terminates, it is removed from the list. Each process can have one or more modules which it loads. These modules are shown in the list directly under their owning process. The first module loaded by a process appears directly under its owning process and additional modules loaded by a process get added to the bottom of that process' module list. As modules get unloaded, they are removed from the list.

The current process is indicated by a green arrow glyph in the gutter next to it. Noncurrent processes have no glyphs next to them.

Module load breakpoints are not process specific and will get encountered by any process which loads a module which has a breakpoint set on it.


Add or Edit Module dialog box

See also

Choosing Run|Add Breakpoint|Module Load Breakpoint displays the Add Module dialog box.

Use the Add or Edit Module dialog box to add a module to the Modules window. Modules are automatically added to the Modules window when they are loaded into memory, but if you want to halt execution for debugging when the module first loads into memory, you must add it to the modules window first and then choose BreakOnLoad from its context menu.

Type the module name (usually a .DLL or .BPL) into the edit box, or click the browse button to locate the module with an explorer dialog.


About the toolbars

See also

The toolbars in the IDE provide shortcuts for menu commands. Commands are organized into several toolbars, which can be independently repositioned or pulled into floating tool windows by dragging with the mouse.

You can display or remove toolbars from the display using View|Toolbars.

The toolbars that can appear in the IDE are

Standard

View

Debug

CORBA

Custom

ComponentPalette

The Toolbars have Help Hints. To enable Help Hints, select Show Hints from the Options page of the Customize Toolbar dialog. When Help Hints are enabled, you can point to any of the tools on the toolbar and pause to see what the tool is used for.


Standard toolbar

See also

The Standard toolbar contains the following buttons by default:

Button	Meaning

New	Opens the New Items dialog box.

Open	Displays the File Open dialog box. The Open button has a drop-down button that allows you to select from a list of the most recently opened files.

Save	Lets you store changes to all files included in the open project using the current name for each file. This is the same as selecting File|Save from the menu.

Save All	Lets you save all open files, including the current project and modules. This is the same as selecting File|Save All from the menu.

Open Project	Lets you open an existing project. This is the same as selecting File|OpenProject from the menu.

Add file to project	Opens the Add to Project dialog box.

Remove file from project	Opens the Remove from Project dialog box.


View toolbar

See also

The View toolbar contains the following buttons by default:

Button	Meaning

View Unit	Opens the View Unit dialog box.

View Form	Displays the View Form dialog box.

Toggle Form/Unit	Toggles between a form and its unit window.

New Form	Creates and adds a blank form to the current project. This is the same as choosing File|New Form from the menu.


Custom toolbar

See also

The Custom toolbar contains a single button (help contents) which brings up the contents and index for accessing on-line help.

You can add your own command buttons to this tool bar using the toolbar Customize dialog.


Debug toolbar

See also

The Debug toolbar contains the following buttons by default:

Button	Meaning

Run	Compiles and executes your application. This is the same as choosing Run|Run from the menu. This button also has a drop down list that lets you change the active project or process. If you are debugging more than one project and you want to switch to a process that is not currently active, click on the little down arrow in the Run Button and select the exe you want to make active.  This will not run the exe, just activate it.  If the exe is not currently stopped in the debugger, selecting it makes its project the active project in the project manager.

Pause	Temporarily pauses the execution of a running program. This is the same as the Run|Program Pause menu command.

Trace Into	Executes a single program line, tracing into any procedures or functions. This is the same as the Run|Trace Into menu command.

Step Over	Executes a single program line, without tracing into any procedures or functions. This is the same as the Run|Step Over menu command.


CORBA toolbar

See also

The CORBA toolbar contains the following buttons by default:

Button	Meaning

New CORBA Object Implementation	Displays the CORBA Object wizard, which you can use to generate the initial implementation of an interface, including code to instantiate objects and tie classes.

CORBA Refresh	Updates CORBA implementation classes to reflect changes to the project’s IDL files. This is the same as the Edit|CORBA Refresh menu command.

Use CORBA Object	Compiles all IDL files and displays the Use CORBA Object Wizard, where you can specify the CORBA object you want to use and where you will use it.


Configuring the toolbars

See also

The toolbars in the IDE are configurable. That is, you can do any of the following:

Add buttons to a toolbar

Remove buttons from a toolbar

Rearrange the buttons on a toolbar

Before you can configure the toolbar, you must display the Customize dialog box by choosing View|Toolbars|Customize or choosing Customize from the toolbar context menu.

To add buttons to the toolbar:

1.	Display the Commands page of the Customize dialog box.

2.	Enlarge the toolbar area by dragging the grabber on the toolbar to the right.

2.	Select a menu from the Categories list box. The commands associated with the selected category are displayed in the Commands list box.

3.	Drag the menu command you want to add from the Commands list box and drop it on any toolbar in an open space.

To remove a button from the toolbar:

Display any page of the Customize dialog box. Drag the button off the toolbar.

To rearrange the buttons on the toolbar:

Display any page of the Customize dialog box. Drag and drop the button to a new position.


About the integrated debugger

See Also

No matter how careful you are when writing code, your programs are likely to contain errors, or bugs, that prevent them from running the way you intended. Debugging is the process of locating and fixing errors in your programs. The IDE provides debugging features, collectively referred to as the integrated debugger, that let you find and fix errors in your programs. The integrated debugger is a full-featured debugger that enables you to

Control the execution of your program

Monitor the values of variables and items in data structures

Modify the values of data items while debugging

Types of errors

There are three basic types of program errors:

Compile-time

Logical errors

Runtime errors

The integrated debugger can help you track down both runtime errors and logic errors. By running to specific program locations and viewing the state of your program at those places, you can monitor how your program behaves and find the areas where it is not behaving as you intended.


Compile-time errors

Errors that violate a rule of language syntax. You cannot compile your program unless it contains valid statements.

The most common causes of compile-time (syntax) errors are

Typographical mistakes

Missing semicolons

References to undeclared variables

Wrong number or type of arguments passed to a function

Wrong type of values assigned to a variable


Runtime errors

Runtime errors occur when your program contains valid statements, but the statements cause errors when they are executed. For example, your program might try to open a nonexistent file, or it might try to divide a number by zero. The operating system detects runtime errors and stops program execution when they occur.

Using the debugger, you can run to a specific program location. From there, you can execute your program one statement at a time, watching the behavior of your program with each step. When you execute the statement that causes your program to fail, you can fix the source code, recompile the program, and resume testing.


Logic errors

Logic errors occur when your program statements are valid, but the actions they perform are not the actions you intended. For example, logic errors occur when variables contain incorrect values, when graphic images do not look right, or when the output of your program is incorrect.

Logic errors are often the difficult to find because they can show up in unexpected places. You need to thoroughly test your program to ensure that it works as designed. The debugger helps you locate logic errors by monitoring the values of variables and data objects as your program executes.


Fixing syntax errors

If your code has compile-time (syntax) errors and you try to compile it, the Message View of the Code editor opens and displays the errors and warnings generated.

To correct syntax errors,

1.	In the Message View, double-click the error or warning that you want to fix. (If the Message View is not open, right-click the Code editor and choose Message View.)

The IDE positions your cursor on the line in your source code that caused the problem.

2.	Make your correction.

3.	If your code has more than one problem, double-click another error or warning in the Message window.

4.	Choose Project|Build All or Project|Make to recompile your program.

5.	Choose Run|Run to verify that your program is operating correctly.


Planning a debugging strategy

After program design, program development consists of a continuous cycle of coding and debugging. Only after you thoroughly test your program should you distribute it to your end users. To ensure that you test all aspects of your program, it is best to have a thorough plan for your debugging cycles.

One good debugging method involves dividing your program into different sections that you can debug systematically. By closely monitoring the statements in each section, you can verify that each area is performing as designed. If you do find a programming error, you can correct the problem in your source code, recompile the program, and resume testing.


Using the integrated debugger

Although there are many ways to debug code, you will typically use one or more of the following steps:

1.	Preparing your project for debugging by compiling and linking your program with debug information.

2.	Control Program Execution by running to a program location you would like to examine.

3.	Examine the state of the program data values and view the program output.

4.	Modify program data values to test bug fixes.

5.	Reset or pause the debugging session.

6. Fix the error.


Preparing your project for debugging

If you find a runtime or logic error in your program, you can begin a debugging session by running your program under the control of the debugger:

1.	Compile and link your program with debug information.

2.	Run your program from the IDE.

Generating debug information for your project

The IDE automatically generates debug information. To manually choose to turn on debug information for your project,

1.	Choose Project|Options.

2.	Click the Compiler tab.

1.	From the Debugging pane click Debug information to include symbolic debug information. To view variables local to procedures and functions click Local Symbols.

2.	If you are using remote debugging, check “Include remote debug symbols” on the EXE and DLL options pane of the Linker tab. The “Debug project on remote machine” checkbox on the Run|Parameters Remote tab is automatically linked to the “Include remote debug symbols” checkbox. These options are only linked in one direction, meaning that changing the “Debug project on remote machine” checkbox has no effect on the “Include remote debug symbols” checkbox.

Enabling the debugger

The debugger is enabled automatically. To manually choose to enable the debugger,

1.	Choose Tools|Debugger Options.

2.	Check Integrated Debugging. This option is on by default.

3.	Choose Tools|Environment Options and check Minimize On Run from the Preferences tab if you want to minimize the IDE when you run your program.

1.	From the Preferences tab click Hide Designers On Run to close the Object Inspector and Form Designer when you run your program.

Note: If you are using TD32 or have a console mode application, you should choose the appropriate checkboxes on the EXE and DLL options pane of the Linker tab.

Turning debugging information off

Adding debug information increases the file size of your program. When you have fully debugged your program, be sure to build the final executable files with debugging information turned off to reduce the final size of your program files.

To turn off debugging information

1.	Choose Project|Options

2.	Click the Compiler tab and from the Debugging pane uncheck Debug information and Local symbols.


Running your program in the IDE

After you compile your program with debug information, you can begin a debugging session by running your program from the IDE. Doing so lets you control when your program runs and when it pauses. Whenever your program is paused in the IDE, the debugger takes control.

When you run your program under the control of the debugger, it behaves as it normally would; your program creates windows, accepts user input, calculates values, and displays output. When your program is not running, the debugger has control, and you can use its features to examine the current state of the program. By viewing the values of variables, the functions on the call stack, and the program output, you can ensure that the area of code you are examining is performing as it was designed to.

Note:	When debugging applications and DLLs that reside in different source directories, set the Debug source path (Project|Options|Directories/Conditionals) and ensure that the debug info (.TDS) resides in the same directory as the EXE and DLL.

As you run your program through the debugger, you can watch the behavior of your application in the windows it creates.

For best results, arrange your screen so you can see both the Code editor and your application window as you debug.

Debugging with program arguments

To pass runtime arguments to the program you want to debug,

1. 	Choose Run|Parameters.

2. 	In the Run Parameters dialog box, type the arguments to pass to your program when you run it under debugger control and click OK. If you are using remote debugging, add the argument to the control on the remote tab.


Controlling program execution

The most important aspect of a debugger is that it lets you control the execution of your program. You can control whether your program will execute a single line of code, an entire function, or an entire program block. By specifying when the program should run and when it should pause, you can quickly move over the sections that you know work correctly and concentrate on the sections that are causing problems.

The debugger treats multiple program statements on one line as a single line of code; you cannot individually debug multiple statements contained on a single line of text. In addition, the debugger treats a single statement that spans several lines of text as a single line of code.

The debugger lets you control program execution in the following ways:

Running to the cursor

Stepping through code

Running to a breakpoint location

Pausing your program

Execution point

The execution point indicates the next line of source code or machine instruction in your program that will be executed when you run your program through the integrated debugger. Whenever you pause program execution, the debugger highlights a line of source code or machine instruction, marking the location of the execution point.


Running to the cursor

See also

When beginning a debugging session, you often run your program to a spot just before the suspected location of the problem. At that point, use the debugger to ensure that all data values are as they should be. If everything appears to be correct, you can run your program to another location, and again check to ensure things are functioning correctly.

You can tell the debugger you want to execute your program normally (not step-by-step) until a certain spot in your code is reached. In the Code editor or CPU window, position the cursor on the line where you want to begin (or resume) debugging. Then either:

1.	Right-click the Code editor and choose Debug|Run to current.

2.	Right-click in the Disassembly pane of the CPU window and choose Run To Current.

3.	Choose Run|Run to Current from the main menu.

4.	Use F4, under the default keymapping.


Stepping overview

Stepping is the simplest way to move through your code one statement or machine instruction at a time. Stepping lets you run your program one line (or instruction) at a time – the next line of code (or instruction) will not execute until you tell the debugger to continue. After each step, you can examine the state of the program, view the program output, and modify program data values. Then, when you are ready, you can continue executing the next program statement.

You can step through code in two basic ways:

Trace Into	The Trace Into command causes the debugger to walk through your code one statement or instruction at a time. If the execution point is located on a function call, the debugger moves to the first line of code or instruction that defines that function. From here, you can execute that function, one statement or instruction at a time. When you step past the return of the function, the debugger resumes stepping from the point where the function was called. (Stepping through your program one statement at a time is known as single stepping.)

Step Over	The Step Over command is the same as Trace Into, except that when the execution point is on a function call, the debugger executes the function at full speed and then pauses on the line of code or instruction following the function call.

You can also use Run|Run Until Return to run the loaded program until execution returns from the current function. The process stops on the instruction immediately following the instruction that called the current function.

Statement stepping and instruction stepping

The debugger lets you step through either

statements in your source code viewed in the Code editor.

machine instructions viewed in the CPU window.

The debugger automatically steps through your code at the instruction level and displays the CPU window in the following situations:

If the CPU window has focus when you choose the Trace Into or Step Over command.

If you pause the program in a spot where there is no debug information available.

When an exception is raised at a point where there is no debug information, and the user checks the view CPU checkbox from the exception dialog box that appears.

If the debugger stops at an address or data breakpoint.

Statement Stepping granularity

The debugger steps over single lines of lines of code based on the following rules:

If you string several statements together on one line, you cannot debug those statements individually; the debugger treats all statements as a single line of code.

If you spread a single statement over multiple lines in your source file, the debugger executes all the lines as a single statement.


Stepping over code

See also	Overview of Stepping

To Step Over, choose the Run|Step Over or press F8 (default key mapping).

When you choose the Step Over command, the debugger executes the code highlighted by the execution point. If the execution point is highlighting a function call, the debugger executes that function at full speed, including any function calls within the function highlighted by the execution point. The execution point then moves to the next complete line of code or executable instruction.

As you debug, you can choose to Trace Into some functions and Step Over others. Step Over is good to use when you have fully tested a function, and you do not need to single step through its code.


Tracing into code

See also	Overview of stepping

To Trace Into code, choose either of the following commands:

Run|Trace Into or press F7 (default key mapping)

Run|Trace To Next Source Line or press Shift+F7 (default key mapping).

When you choose Run|Trace Into, the debugger executes the code highlighted by the execution point. If the execution point is highlighting a function call, the debugger moves the execution point to the first line of code or instruction that defines the function being called. If the executing statement calls a function that does not contain debug information, the debugger runs the function at full speed (as if you had chosen the Step over command).

When you choose Run|Trace To Next Source Line, the debugger moves to the next source line in your application, regardless of the control flow. For example, if you select this command when stopped at a Windows API call that takes a callback function, control will return to the next source line, which in this case is the callback function.

When you step past a function return statement (in this case, the end statement), the debugger positions the execution point on the line following the original function call.

As you debug, you can choose to Trace Into some functions and Step Over others. Use Trace Into when you need to fully test the function highlighted by the execution point.

You can also use Run|Run Until Return to run the loaded program until execution returns from the current function. The process stops on the instruction immediately following the instruction that called the current function.


Running to a breakpoint

See also

You set breakpoints on lines of source code or address locations (machine instructions) where you want program execution to pause during a run. Using a breakpoint is similar to using the Run to Cursor command in that the program runs at full speed until it reaches a certain point. Unlike Run to Cursor, however, you can have multiple breakpoints and you can choose to stop at a breakpoint only under certain conditions. Once your program’s execution is paused, you can use the debugger to examine the state of your program.


Interrupting program execution

See also

Sometimes while debugging, you will find it best to stop program execution or to start the debugging session from the beginning of the program.

Choose…	To…

Run|Program Pause	temporarily pause the execution of a running program.

Run|Program Reset	terminate the current debugging session, and start with a fresh slate.


Pausing your program

See also

Instead of stepping through code, you can use a simpler technique to pause your program:

Choose Run|Program Pause and your program will stop executing.

You can then examine the value of variables and inspect data at this state of the program. When you are done, choose Run|Run to continue the execution of your program.

In most cases, the CPU window will display when you pause your program, such as when the current instruction does not have corresponding source code.


Restarting your program
Restarting a program

See also

Sometimes while debugging, you might need to start over from the beginning of your program. For example, it might be best to restart the debugging session if you have executed past the point where you believe there is a bug, or if variables or data structures become corrupted with unwanted values.

To restart your program, choose Run|Program Reset.

When you terminate the process, the IDE

resets the integrated debugger so that running or stepping, begins at the start of the program.

does not change the location of the source code displayed in the Code editor so that you can easily position the cursor to run your program to the line you were on when you reset it.

disables any Data Breakpoints that are set. You must re-enable them when you start your next debug session.


Fixing program errors

See also

Once you have found the location of the error in your program, you can type the correction directly into the Code editor and the change takes effect immediately. Once you change a line of code in the Code editor, however, the IDE prompts you to rebuild your program before you resume program execution and continue debugging.

Instead of fixing an error while debugging, you might want to test your fix by modifying data values using the debugger. This way, you do not have to recompile your program to see if your fix works.


Using breakpoints

See also

Breakpoints pause program execution during a debugging session at source code or address locations that you specify. You can set breakpoints before potential problem areas, then run your program at full speed. Your program pauses when it encounters a breakpoint, and the Code editor or CPU view Disassembly pane displays the line or address location containing the breakpoint. You can then use the debugger to view the state of your program, or to step over or trace into your code one line or machine instruction at a time.

The IDE keeps track of all your breakpoints during a debugging session and associates them with your current project. You can maintain all your breakpoints from a single Breakpoints List window and not have to search through your source code files to look for them.

Debugging with breakpoints

When you run your program from the IDE, it will stop whenever the debugger reaches the location in your program where the breakpoint is set, but before it executes the line or machine instruction.

If you set a breakpoint on a line in your source code, the line that contains the breakpoint appears in the Code editor highlighted by the execution point.

If you set a breakpoint on an address location, the instruction that contains the breakpoint appears in the CPU window Disassembly pane (or in the Code editor on the line that most closely corresponds to the address location) highlighted by the execution point.

At this point, you can perform any other debugging actions.

Setting breakpoints after program execution begins

While your program is running, you can switch to the debugger (the IDE), just as you would switch to any Windows application, and set a breakpoint. When you return to your application, the new breakpoint is set, and your application will pause or perform a specified action when it reaches the breakpoint.

You must set a breakpoint on an executable line of code or machine instruction. For example, breakpoints set on comment lines, blank lines, declarations, or other non-executable lines of code are displayed as invalid breakpoints in the Code editor, and are disabled when you run your program.


Setting breakpoints

See also

You can set breakpoints before you begin debugging or while your program is running using the Code editor or the CPU window Disassembly pane. Your application halts when it reaches a breakpoint.

For a breakpoint to be valid, it must be set on an executable line of code. Breakpoints set on comment lines, blank lines, declarations, or other non-executable lines of code are invalid and become disabled when you run your program.

Source breakpoints

To set a breakpoint on a line of source code, select the line in the Code editor where you want to set the breakpoint, then use one of the following methods:

Click the left margin of the line.

Right-click anywhere on the line and choose Debug|Toggle Breakpoint.

Place the insertion point anywhere in the line and press F5 (default key mapping).

Right-click the Breakpoint List window and choose Add|Source Breakpoint.

Breakpoints are shown in color with a filled circle in the left gutter of the Code editor (red by default). When you point to the circle in the gutter, a tooltip displays showing the breakpoint’s pass count and condition.

If you know the line of code where you want to set a breakpoint,

1.	Choose Run|Add Breakpoint|Source Breakpoint and type the source-code line number in the Line Number box.

2.	Complete the settings in the Add Source Breakpoint dialog box to create the breakpoint.

When you set a breakpoint, the line on which the breakpoint is set becomes highlighted, and a stop-sign appears in the left margin of the breakpoint line.

Invalid breakpoints

If a breakpoint is not placed on an executable line of code, the debugger considers it invalid. For example, a breakpoint set on a comment, a blank line, or declaration is invalid. If you set an invalid breakpoint, the debugger marks the breakpoint invalid and runs. To correct this situation, delete the invalid breakpoint from the Breakpoint List window. You can then set the breakpoint in the intended location. You can, however, also ignore invalid breakpoints; the IDE disables any invalid breakpoints when you run your program.

During the linking phase of compilation, lines of code that do not get called in your program are marked as dead code by the linker. In turn, the integrated debugger marks any breakpoints set on dead code as invalid.

Address breakpoints

The debugger supports address breakpoints. When set, the debugger breaks if the instruction at the specified address gets executed.

You can set an address breakpoint in the following ways:

When in the Breakpoint List window, choose Add|Address breakpoint. On the dialog, enter an address.

From the Run menu choose Add Breakpoint|Address Breakpoint. On the dialog, enter an address.

From the gutter of the CPU window click the mouse.

From the Disassembly pane of the CPU window right-click and choose Toggle breakpoint.

Press F5.

Address breakpoints are only available when the process is paused in the debugger.

Data breakpoints

The debugger supports data breakpoints. When set, the debugger breaks if the memory at the specified address is written to. You can set a data watch breakpoint three ways:

When in the breakpoint view, choose Add|Data breakpoint. On the dialog, enter an address and specify a length. You can also enter symbol names such as variable names.

When in the watch view, select an item, right-click, and choose Break When Changed. Selecting this menu item sets a Data Watch breakpoint.

From the Run menu choose Add Breakpoint|Data Breakpoint. On the dialog, enter an address and specify a length.

When your current debug session ends, Data Breakpoints are marked disabled. On the start of your next debug session, you need to re-enabled them from either the Breakpoint view (Breakpoint list window) or the Watch view (Watch List). Data breakpoints are only available when the process is paused in the debugger.


Modifying breakpoint properties

See also

You can specify breakpoint properties when you create a breakpoint, or you can edit the properties after creation. Use the Breakpoint Properties dialog boxes to modify breakpoint properties.

Adding breakpoints

Use the Add Breakpoint dialog boxes to add a breakpoint. You can open these Breakpoint dialog boxes in the following ways:

Choose Run|Add Breakpoint and select Source Breakpoint, Address Breakpoint, Data Breakpoint or Module Load Breakpoint.

Choose View|Debug Windows|Breakpoints, then right-click the Breakpoint List window. Choose Add, and then choose Source Breakpoint, Address Breakpoint, or Data Breakpoint.

Editing breakpoints

Use the Breakpoint Properties dialog boxes to modify an existing breakpoint. You can open these Breakpoint Properties dialog boxes in the following ways:

Right-click an existing source, address, or data breakpoint in the Breakpoint List window and choose Properties. Do NOT check Keep existing breakpoint if you want to modify a breakpoint.

Right-click in the gutter on an existing source breakpoint in the Code editor and choose Properties.

Right-click in the gutter on an existing address or source breakpoint in the CPU window and choose Properties.

Use the following options to specify where and when you want a breakpoint to pause your program. These options are available depending upon the type of breakpoint set and the point at which you decide to modify it:

Filename

Sets or changes the program file for the breakpoint. Enter the name of the program file for the breakpoint. (This option appears only for a breakpoint set on a line of source code in the Code editor.)

Line Number

Sets or changes the line number for the breakpoint. Enter or change the line number for the breakpoint. (This option appears only for a breakpoint set in the Code editor on a line of source code.)

Address

Sets a breakpoint on a machine instruction. Enter a specific starting address or any symbol, such as a variable or a class data member or method, that evaluates to an address. (This setting appears only for a breakpoint set on a machine instruction in the Disassembly pane in the CPU window.)

Condition

Specifies a conditional expression that is evaluated each time the breakpoint is encountered. Program execution stops when the expression evaluates to true. You can enter any valid language expression. All symbols in the expression, however, must be accessible (within scope) from the breakpoint's location.

For more information, see Creating Boolean expressions.

Pass Count

Stops program execution at a certain line number or machine instruction after a specified number of passes. The integrated debugger decrements the pass count number each time the line containing the breakpoint is encountered. When the pass count equals 1, program execution pauses.

When you use pass counts with conditions, program execution pauses the nth time that the conditional expression is true. The debugger decrements the pass count only when the conditional expression is true.

For more information, see Using Pass Counts.


Creating conditional breakpoints

See also

When a breakpoint is first set, by default, program execution pauses each time the breakpoint is encountered. The Add Breakpoint dialog boxes lets you customize your breakpoints so that your program pauses only when a specified set of conditions is met.

To create a conditional breakpoint:

1.	Choose Run|Add Breakpoint and select Source Breakpoint, Address Breakpoint, or Data Breakpoint OR right-click the Breakpoint List window, choose Add, and then choose Source Breakpoint, Address Breakpoint, or Data Breakpoint.

2.	Enter the required information on the Condition line of the dialog box.

The integrated debugger provides two types of breakpoint conditions:

Boolean expressions

Pass counts

To modify conditions, use the Breakpoint Properties dialog boxes. For details see Modifying Breakpoint Properties.


Creating Boolean expressions

See also

The Condition edit box in the Breakpoint dialog box lets you enter an expression that is evaluated each time the breakpoint is encountered during the program execution. If the expression evaluates to true (or not zero), the breakpoint pauses the program run. If the condition evaluates to false (or zero), the debugger does not stop at the breakpoint location.

Conditional breakpoints are useful when you want to see how your program behaves when a variable falls into a certain range or what happens when a particular flag is set.

For example, suppose you want a breakpoint to pause on a line of code only when the variable mediumCount is greater than 10. To do so,

1.	Place the insertion point on the line of code you want in the Code editor and press F5 to set the breakpoint.

2.	Choose View|Debug Windows|Breakpoints to open the Breakpoint List window.

3.	In the Breakpoint List window, highlight the breakpoint you just created, then right-click and choose Properties.

4.	On the Breakpoint Properties dialog box, enter the following expression into the Condition edit box:

mediumCount > 10

5.	To modify a breakpoint, do NOT check Keep existing breakpoint.

You can input any valid language expression into the Condition edit box, but all symbols in the expression must be accessible (within scope) from the breakpoint’s location.


Using pass counts

See also

The Pass Count edit box enables you to specify a particular number of times that a breakpoint must be passed for the breakpoint to be activated. A pass count tells the debugger to pause program execution the nth time that the breakpoint is encountered during the program run (you supply the number n which is set to 0 by default).

The current pass count number increments each time the line containing the breakpoint is encountered during the program execution. If the current pass count equals the specified pass count number when the breakpoint line is encountered, program execution pauses on that line of code. For example, if you enter a pass count of 2, your program stops the second time the debugger reaches the line where the breakpoint is set.

When you use a pass count in conjunction with a Boolean condition, the breakpoint pauses program execution the nth time that the condition is true; the condition must be true for the pass count to increment. For example, if you enter the expression x>3 in Conditions and the number 2 in Pass Count, your program stops the second time the debugger reaches the breakpoint when the value of x is greater than 3.


Locating breakpoints

See also

If a breakpoint is not visible in the Code editor or in the CPU view, you can use the Breakpoint List window to quickly locate the breakpoint.

To scroll the Code editor to the location of a breakpoint in your source code,

Right-click on a source breakpoint in the Breakpoint List window and choose View Source.

To scroll the Code editor to the location of a breakpoint in your source code and make the Code editor active,

Right-click on a source breakpoint in the Breakpoint List window and choose Edit Source.

To scroll the CPU window to the location of an address breakpoint and make the CPU window active,

Right-click on an address breakpoint in the Breakpoint List window and choose either Edit Source or View Source.

If you choose View Source, the Breakpoint List window remains active so you can modify the breakpoint or go on to view another. If you choose Edit Source, the Code editor gains focus so you can modify the source code at that location.


Disabling and enabling breakpoints

See also

Disabling a breakpoint hides the breakpoint from the current program run. When you disable a breakpoint, its settings remain defined, but the breakpoint does not cause your program to stop. When you set a breakpoint, it is enabled by default.

Disabling is useful when you temporarily do not need a breakpoint but want to preserve its settings.

To disable a single breakpoint,

Right-click the breakpoint in the Breakpoint List window and choose Enable and toggle it OFF (so that it no longer has a check mark next to it).

To disable all breakpoints,

Right-click the Breakpoint List window, but not on a breakpoint, and choose Disable All.

To enable a single breakpoint,

Right-click the breakpoint in the Breakpoint List window and choose Enabled and toggle it OFF (so that it no longer has a check mark next to it).

To enable all breakpoints,

Right-click the Breakpoint List window, but not on a breakpoint, and choose Enable All.

See Breakpoint List context menu for a complete list of the context menus available from the Breakpoint List window.


Deleting breakpoints

See also

When you no longer need to examine the code at a breakpoint location, you can delete the breakpoint from the debugging session. You can delete breakpoints using either the Code editor, the CPU window, or the Breakpoints window:

To delete a single breakpoint,

Right-click the breakpoint in the Breakpoint List window and choose Delete.

Right-click the breakpoint in the Code editor and choose Debug|Toggle breakpoint.

Right-click the breakpoint in the CPU window and choose Toggle breakpoint.

Place the insertion point anywhere in the line in the Code editor containing the breakpoint or highlight the breakpoint in the CPU window and press F5. (using the default keymapping).

Click the stop-sign glyph in the left gutter of the line containing the breakpoint in the Code editor or CPU window.

Use the Delete key or Ctrl+D in the Breakpoint list window to delete the selected breakpoint.

To delete all breakpoints,

Right-click the Breakpoint List window and choose Delete all.


Examining program data values

See also

After you have paused your application using the integrated debugger, you can examine the different symbols and data structures with regard to the location of the current execution point. You frequently need to examine the values of variables and expressions to uncover bugs in your program. For example, it is helpful to know the value of the index variable as you step though a for loop, or the values of the parameters passed to a function call.

Data evaluation operates at the level of expressions. An expression consists of constants, variables, and values contained in data structures, combined with language operators.

Almost anything you can use as the right side of an assignment operator can be used as a debugging expression, except for variables not accessible from the current execution point.

You can view the state of your program by

Watching program values

Evaluating and modifying expressions

Inspecting data elements

Viewing the low-level state of your program

Viewing functions in the Call Stack window

Viewing Local Variables from the View|Debug Windows menu.


Modifying program data values

See also

Sometimes you will find that a programming error is caused by an incorrect data value. Using the integrated debugger, you can test a "fix" by modifying the data value while your program is running. You can modify program data in the following ways:

Modifying variables

Changing the value of inspector items

Using the CPU window's Memory Dump pane


Watch expressions

See also

If you want to monitor the value of a variable or expression while you debug your code, add a watch to the Watch List. The Watch List window displays the current value of the watch expression based on the scope of the execution point.

Each time your program’s execution pauses, the debugger evaluates all the items listed in the Watch List and updates their displayed values.

You can set a watch expression in the following ways:

The easiest way to set a watch is to place the insertion point on a term in the Code editor, then right-click and choose Debug|Add Watch at Cursor.

You can also set a watch and specify its properties on the Watch Properties dialog box (from the Run|Add Watch menu). For more information, see Setting watch properties.


Setting watch properties

See also

Use the Watch properties dialog box to set the properties of a new watch expression or to change the properties of an existing one.

You can open the Watch Properties dialog box in the following ways:

Choose Run|Add Watch from the main menu.

Right-click the Watch List and choose Add Watch.

Select a watch in the Watch List, then right-click and choose Edit Watch.


Formatting watch expressions

See also

By default, the debugger displays the result of a watch in the format that matches the data type of the expression. For example, by default, integer values are displayed in decimal form. If you select Hexadecimal in the Watch Properties dialog box for an integer type expression, the debugger changes the display format from decimal to hexadecimal.

If you are setting up a watch on an element in a data structure (such as an array), you can display the values of consecutive data elements. For example, suppose you have an array of five integers named xarray. Type the number 5 in Repeat Count on the Watch Properties dialog box to see all five values of the array. To use a repeat count, however, the watch expression must represent a single data element.

To format a floating-point expression, select Decimal at Display format and enter a number for Digits on the Watch Properties dialog to indicate the number of significant digits you want displayed in the Watch List.

The following table describes the watch expression format options and their effects.

Option	Types affected	Description

Hexadecimal	integers/characters	Shows integer values in hexadecimal with the 0x prefix, including those in data structures.

Character	characters/strings	Shows special display characters for ASCII 0 to 31. By default, such characters are shown using the appropriate C escape sequences (\n, \t, and so forth).

Decimal	integers	Shows integer values in decimal form, including those in data structures.

Floating point	floating point	Shows the significant digits specified; from 2-18. The default is 7.

Memory dump	all	Shows the size in bytes starting at the address of the indicated expression. By default, each byte displays two hex digits. Use the memory dump with the character, decimal, hexadecimal, and string options to change the byte formatting. Use the Repeat Count setting to specify the number of bytes you want to display.

Pointer	pointers	Shows the address of the pointer.

Structure/Union	structures /unions	Shows field names and unions as well as values such as X:1;Y:10;Z:5.

String	char, strings	Shows ASCII 0 to 31 as C escape sequences. Use this option only to modify memory dumps.

Default	all	Shows the result in the display format that matches the data type of the expression.


Enabling and disabling watches

See also

Evaluating many watch expressions can slow down the process of debugging. Disable a watch expression when you prefer not to view it in the Watch List window, but want to save it for later use.

When you set a watch, it is enabled by default. Disabling a watch hides the watch from the current program run. When you disable a watch, its settings remain defined, but the debugger does not evaluate it.

To enable or disable a watch,

1.	Choose View|Debug Windows|Watches to open the Watch List.

2.	Select a watch, then right-click and choose Enable or Disable watch.

The flag <disabled> appears next to a watch that is disabled.

To disable or enable all watches,

Right-click the Watch List and choose Enable All Watches or Disable All Watches.


Deleting watches

See also

When you no longer need to examine the value of an expression, you can delete the watch from the debugging session.

To delete a single watch,

1.	Choose View|Debug Windows|Watches to open the Watch List.

2.	Select a watch, then right-click and choose Delete Watch.

OR

Use the del key or the Ctrl+D key combination to delete the selected Watch.

To delete all watches in a source code file,

Right-click the Watch List and choose Delete All Watches.


Evaluating and modifying expressions

See also

Use the Evaluate/Modify dialog box to evaluate or change the value of an existing expression or property. The Evaluate/Modify dialog box has the advantage over watches in that it enables you to change the values of variables and items in data structures during the course of your debugging session.

You can test different error hypotheses and see how a section of code behaves under different circumstances by modifying the value of data items during a debugging session. This technique can be useful if you think you have found the solution to a bug, and you want to try the correction without having to exit the debugger, changing the source code, and recompiling the program.

To evaluate an expression or property

1.	Open the Evaluate/Modify dialog box one of the following ways.

Choose Run|Evaluate/Modify.

Right-click the Code editor and choose Debug|Evaluate/Modify.

2.	Type an expression in the Expression box.

By default, the word at the cursor position in the current Code editor is placed in the Expression input box. You can accept this expression, enter another one, or choose an expression from the history list of expressions you have previously evaluated. If you want to evaluate a function call, enter the function name, parentheses, and arguments just as you would type it into your program, but leave out the statement-ending semicolon (;).

3.	Choose Evaluate. The value of the item appears in the Result edit box.


Evaluating expressions

See also

You can evaluate any valid language expression, except those that contain variables that are not accessible from the current execution point.

Formatting values

To format the result that displays, add a comma and one or more format specifiers to the end of the expression entered in the Expression box. For example:

To display a result in hexadecimal, type ,H after the expression.

To see a floating point number to 3 decimal places, type ,F3 after the expression.

For a complete list of format options, see Evaluate/modify format specifiers.

Evaluate/Modify dialog box

The Evaluate/Modify dialog box provides the following options:

Expression

Lets you specify the variable, array, or object to evaluate or modify.

Result

Displays the value of the item specified in the Expression text box after you choose Evaluate or Modify.

New value

Lets you assign a new value to the item specified in the Expression edit box.

Evaluate

Evaluates the expression in the Expression edit box and displays its value in the Result edit box.

Modify

Changes the value of the expression in the Expression edit box using the value in the New Value edit box.


Modifying variables

After you have evaluated a variable or data structure item, you can modify its value. When you modify a value through the debugger, the modification is effective for that specific program run only. Changes you make through the Evaluate/Modify dialog box do not affect your source code or the compiled program. To make your change permanent, you must modify your source code in the Code editor, then recompile your program.

To change the value of an expression

1.	Open the Evaluate/Modify dialog box one of the following ways.

Choose Run|Evaluate/Modify

Right-click the Code editor and choose Debug|Evaluate/Modify.

2.	Specify the expression in the Expression edit box. To modify a component property, explicitly specify the property name. For example, enter: Form1->Button1->Height

3.	Enter a value in the New Value edit box.

4.	Choose Modify. The new value is displayed in the Result box.

You cannot undo a change to a variable after you choose Modify. To restore a value, however, you can enter the previous value in the Expression box and modify the expression again.

Keep these points in mind when you modify program data values:

You can change individual variables or elements of arrays and data structures, but you cannot change the contents of an entire array or data structure with a single expression.

The expression in the New Value box must evaluate to a result that is assignment-compatible with the variable you want to assign it to. A good rule of thumb is that if the assignment would cause a compile-time or runtime error, it is not a legal modification value.

Use caution when you modify variables or when evaluating functions while debugging an application – any side effects that occur will modify the data values of the program you are debugging. For example, if you evaluate a function that increments a variable, the new value of that variable will be reflected when you continue to step through your application. Modifying values (especially pointer values and array indexes) can have undesirable effects because you might overwrite other variables and data structures. Because these errors might not be immediately apparent, use caution whenever you modify program values from the debugger.


Inspecting data elements

See also

Inspector windows are only available when the process is stopeed in the debugger.

Inspector windows are the best way to view data items because the debugger automatically formats Inspector windows according to the type of data it is displaying. Inspector windows are especially useful when you want to examine compound data objects, such as arrays and linked lists. Because you can inspect individual items displayed in an Inspector window, you can “walk” through compound data objects by opening an Inspector window on a component of the compound object.

To display an Inspector window directly from the Code editor,

1.	Place the insertion point in the Code editor on the data element you want to inspect.

2.	Right-click and choose Debug|Inspect.

To inspect a data element from the menu bar,

1.	Choose Run|Inspect from the menu bar to display the Inspect dialog box.

2.	Type the expression you want to inspect, then choose OK.

Scope

Unlike watch expressions, the scope of a data element in an Inspector window is fixed at the time you evaluate it:

If you use the Inspect command from the Code editor, the debugger uses the location of the insertion point to determine the scope of the expression you are inspecting. This makes it possible to inspect data elements that are not within the current scope of the execution point..

If you use the Run|Inspect command from the menu bar, the data element is evaluated within the scope of the execution point.

If the execution point is in the scope of the expression you are inspecting, the value appears in the Inspector window. If the execution point is outside the scope of the expression, the value is undefined and the Inspector window becomes blank.

Inspecting local variables

While in debug mode, you can show the current function’s local variables. To do so, choose View|Debug Windows|Local variables.

Data types

The number of panes and the appearance of the data in the Inspector window depends on which of the following types of data you inspect:

scalar variables

functions

constants

arrays

pointers

classes

objects

records and interfaces

For example, if you inspect an array, you will see a line for each member of the array with the array index of the member. The value of the member follows in its display format, followed by the value in hexadecimal.


Inspecting scalar variables

See also

When you inspect a scalar variable, such as simple data items including Integer, Real, and so on, the top of the Inspector window shows the name, type, and address of the variable. The middle pane shows the name of the scalar on the left and its current value on the right. Integer values are displayed first in decimal, followed by the hexadecimal value enclosed in parentheses.

If the variable inspected is of type Char, the equivalent character appears to the left of the numeric values. If the present value does not have a printable character equivalent, the debugger displays a backslash (\) followed by the Object Pascal hexadecimal value that represents the character value.


Inspecting pointers and arrays

See also

When you inspect a pointer or an array, Inspector windows show the values of variables that point to other data items. The top of the Inspector window shows the name, type, count, address (or register if applicable), and pointer location of the variable. The middle pane shows the current values of the data pointed to. The bottom of the Inspector window shows the data type to which the pointer points.

If the value pointed to is a compound data object (such as a structure or record, or an array), the values are enclosed in braces ({}) and the Inspector window displays as much of the data as possible.

If the pointer appears to be pointing to a null-terminated character string, the debugger displays the value of each item in the character array. The left of each line displays the array index ([0], [1], [2], and so on), and the values appear on the right. When you inspect character strings, the entire string appears at the top of Inspector window, along with the address of the pointer variable and the address of the string that it points to.


Inspecting records
Inspecting records and interfaces

See also

When you inspect a structure or record, the Inspector window shows the values of members contained in compound data objects.

The top of the window shows the name of the object. The middle pane lists the names and values of the data members of contained in the object, and contains as many lines as needed to show the entire data object.

The bottom of the window shows the data type of the member currently selected.


Inspecting functions

See also

When you inspect a function, the top of the Inspector window shows the function or procedure name, prototype, and its address in memory. The middle pane shows the function's arguments. To inspect a function, enter the function’s name without parentheses or arguments.

If the function is currently on the call stack, its parameters appear at the bottom of the inspector window.


Isolating the view in an Inspector window

See also

You can more closely inspect certain elements (such as classes, records, and arrays) in the Inspector window to isolate the view to the member level:

1.	Select an item in the Inspector window.

2.	Right-click and choose Inspect to open a new Inspector window, or choose Descend to update the display of the current Inspector window.

The scope of the data element remains the same as it was when you opened it on the Inspector window. If you select a data member that is a pointer to a class, the Inspector window displays the class pointed to.


Changing the value of Inspector items

See also

An ellipsis (…) appears next to a data element that can modified.

To change the value of a inspected element,

1.	Select an item in the Inspector window.

2.	Click the ellipsis (…), or right-click the element and choose Change.

3.	Type a new value, then choose OK.


Using Module view in a debugging session

See also

Use the module view to see different modules, such as .EXEs and DLLs, within a single debug session. Module view is a three-paned view which shows information about the different modules loaded by the process you are debugging.

To display module view,

1.	Start a debug session.

2.	Choose View|Debug Windows|Modules to display the Module View.

3.	Select a module from the list in the upper-left pane.

In the lower-left pane, a tree-view list of source files appears.

4.	Expand source files to show the files included in the source file.

5.	Right-click on any source file or entry point to go to the code editor. For more information on the context menu, see Module Window context menu.

If a file cannot be found, add the path to the file to the Debugger Source path on the Project|Options|Directories/Conditionals option page.

The upper-left pane shows each module name and the address at which it is loaded. The lower left pane shows a tree view display of source files used to build the module. The right pane shows a list of entry points into the module.


Locating function calls

See also

While debugging, it is useful to know the order of function calls that brought you to your current location. The Call Stack window lets you view the current sequence of function calls. It also shows the values of the arguments passed to each function call (the arguments with which the call was made).

To open the Call Stack window,

Choose View|Debug Windows|Call Stack from the menu bar.

To scroll the Code editor to the location of a function call,

Right-click the function call in the Call Stack window and choose View Source.

To scroll the Code editor to the location of a function call and make the Code editor active,

Right-click the function call in the Call Stack window and choose Edit Source.

If you choose View Source, the Call Stack window remains active. If you choose Edit Source, the Code editor gains focus, enabling you to modify the source code at that location.

Stepping over function calls

The Call Stack window is useful if you accidentally trace into code you wanted to step over. Using the Call Stack window, you can return to the point from which the current function was called, then resume debugging.

To use the Call Stack window to step over function calls,

1.	In the Call Stack window, right-click the calling function (the second function in the Call Stack window) and choose Edit Source. The Code editor becomes active with the cursor positioned at the location of the function call.

2.	In the Code editor, move the cursor to the statement following the function call.

3.	Choose Run|Run to Cursor.

You can also use Run|Run Until Return to step out of the top-most function in the stack.


Customizing the colors of the execution point and breakpoints

See also

You can customize the colors used to indicate the execution point and the enabled, disabled, and invalid breakpoint lines.

To set execution point and breakpoint colors,

1.	Choose Tools|Environment Options.

2.	On the Environment Options dialog box, select the Colors tab.

3.	From the Element list, select the following options that you want to change:

Execution point

Enabled Break

Disabled Break

Invalid Break

4.	Select the background (BG) and foreground (FG) colors you want.


Handling hardware and software exceptions
Handling exceptions in the Debugger

See also

You can control the way exceptions are handled while you debug your program. In addition, most hardware exceptions are treated as language exceptions. The IDE traps the hardware exceptions generated by your application, and you can gracefully recover rather than having your program execution end with a system crash.

If a hardware or language exception occurs while you are debugging a an application, your program halts and the Exception dialog box displays. If you choose OK, you can continue to run your program if your program handles the exception.

To pause the program run when an exception occurs,

1	Choose Tools|Debugger Options.

2	Choose the Language Exceptions or the OS Exceptions tab.

For OS Exceptions:

1	Find the type of exception in the Exceptions scroll box.

2	In the Handled By box click Debugger.

3	In the On Resume box, specify whether you want the IDE to continue to handle the exception when the program resumes.

To add a new type of exception not listed in the Exceptions scroll box, click Add. Specify the low and high range for the new exception and click OK.

The IDE displays the Exception dialog box when an exception is generated. When you choose OK to close the dialog box, the IDE opens the Code editor with the execution point positioned on the location of the exception (if no corresponding source is available, a checkbox “View CPU” appears on a dialog. If you want the CPU view opened, check the box and click OK.).


Debugging multi-threaded applications

See also

The integrated debugger supports debugging multi-thread programs in both Windows NT and Windows 95. Only a single thread, however, can be “active” at a given time. The active thread is the one that responds to debugger commands such as stepping and expression evaluation.

The Call Stack, the CPU, the Watch, and the Local Variables windows are “thread aware,” meaning that they display information based on a particular thread.

You can specify the active thread in the following ways:

Choose View|Debug Windows|Threads from the menu bar, then select a Thread ID listed in the Thread Status window, right-click and select Make Current.

Right-click the CPU window and choose Change Thread, then select a Thread ID listed in the Select a Thread dialog box


Debugging class member functions

See also

If you use classes in your programs, you can still use the integrated debugger to step through the member functions in your code. The debugger handles member functions the same way it would step through functions in a program that is not object-oriented.


Debugging Dynamic-link Libraries
Debugging dynamic link libraries

See also

The following topics cover issues when debugging DLLs.

Specifying the host EXE

When debugging a DLL, you don’t need to add the host .EXE to a project to in order to debug it. You can specify a pathname to the .EXE by selecting Run|Parameters and entering the path to the .EXE in the Host application edit box. Press the Load button to load the .EXE in the debugger.

Opening a DLL source file

When trying to open DLL main source code module, do not accept the first default filter in the open dialog (C++Builder files *.cpp,*.bpg,*. bpr,*. bpk). If you use this first filter, the project associated with the DLL will open replacing your current open project. Instead, use the pick list to select C++Builder source(*.cpp).

Setting a breakpoint in a DLL

When debugging an application that calls a DLL, if you want to set a breakpoint in the DLL you must use the correct filter for .CPP files in the Open dialog.

Using Module load breakpoints when debugging .DLLs

Use Module load breakpoints to halt an application when it loads a specified .DLL. To set a Module load breakpoint either:

Select either Run|Add Breakpoint|Module Load Breakpoint

Choose View|Debug Windows|Modules to display the Modules window and right-click anywhere in the upper-left pane and select Add Module

Then in the Add Module dialog box, enter the module name of the .DLL or click Browse to find the .DLL. Click OK. When the application loads the specified .DLL, the application will halt.

Setting a debug source path

The debug source path is specified under Project|Options|Directories\Conditionals. Debug source paths for modules in the current project, or project group, are automatically set. If you are debugging modules (EXEs, DLLs) in different projects or projects groups, you need to add the debug source path for each module that is not part of the current project group.

Locating of TDS files

TDS files must be in the same directory as the corresponding DLL or EXE.


Welcome to Borland C++Builder Help

This topic automatically appears temporarily when you get Help (press F1) on a component from the Object Inspector or a term in the Code Editor.


Sorry, topic not found

This topic appears if the topic you are looking for is not found when you press F1 on a component from the Object Inspector, a term in the Code Editor, or a message in the message view. If one of these situations occur, please report it as a documentation bug.

To search for a topic,

Click the Content or Index button and to display the Help Topics dialog box, and then

Click the Contents tab to browse through topics by category.

Click the Index tab to see a list of index entries. Then, either type the word you're looking for or scroll through the list.

Click the Find tab to search for words or phrases


Using Help in Borland C++Builder

Borland C++Builder provides complete online documentation through the Help system. Using Help is a convenient way to get information about extensive language features, compiler options, and any tasks you need to perform while developing applications with Borland C++Builder.

You can customize your C++Builder Help system including or excluding specific help files by using OpenHelp (select Help|Customize). For information on using OpenHelp (OH.exe), see OPENHELP.HLP.

In addition, Borland provides many Microsoft Help files. These Help files are located (by default) in the Program Files\Common Files\Borland Shared Files\MSHelp directory.

In addition, many other Help files are included depending on which level of the C++Builder product you purchase. For example, you may also receive Help files that describe Interbase, Internet Controls, Borland Database Engine, InstallShield, PVCS, and the Image Editor.


Getting Help in Borland C++Builder

In Borland C++Builder, you can get Help in the following ways:

Context-Sensitive Help (F1)

Contents Screens

Index

Keyword Search (F1 or Ctrl+F1 in the Edit window)

Help context menus (in the Help window)


Getting context-sensitive Help

You can get context-sensitive Help for items in the Borland C++Builder Integrated Development Environment (IDE). To access context-sensitive Help:

1.	Select the element you want help on (menu, menu command, item in a dialog box, error message, etc.).

2.	Press F1 or Ctrl+F1.

Many items on the toolbar and on the Component palette also have fly-over help. Point to a tool or component on the palette and a brief description of the item appears.

Help buttons are available on many dialog boxes and for most system messages.

Click Help to view information about:

The entire dialog box

A system message

The current group of topics in an Options settings dialog box


Accessing and using contents screens

Each Help Contents screen offers an entry into a Help system installed with Borland C++Builder. From the Contents, select the information you want, then click on it.

To display the master contents screen, choose Contents on the Help menu in the Borland C++Builder IDE.

To access the Help Contents screen from within a topic in the active Help file, click the Contents button.

To return to a previous topic or Help file, click the Back button.

Using the Contents screen

You can expand books that appear on the master Contents screen, or jump directly to a topic. To view a topic, click on it.

Printing from the Contents screen

You can print several topics at once by clicking a book on the Contents screen and then clicking Print.


Using the index

In Help, click the Index tab to view a list of index entries. Either type the word you're looking for or scroll through the list.


Searching for keywords

Keyword Search gives you direct access to Help about a term in your program. To get help on a term:

1.	In the Edit window, place the insertion point on the term you want help on.

2.	Use one of the following methods:

Press F1 or Ctrl+F1.

Right-click on the Edit window and choose Topic Search.

3.	One of these events occurs:

The topic associated with the term you selected is displayed.

If more than one topic in is available on the term for which you requested Help, the Topics Found dialog box is displayed listing topics associated with the term. Double-click the topic you want to view.

If no Help is available for the term nearest the insertion point, the index is displayed. You can then select a different searching method to locate a topic associated with that term. The term for which you requested Help appears highlighted in the top box. Click the Display button or double-click the term to view the list of topics associated with the term.

To return to a previous topic or Help file, click the Back button.


Printing Help topics

You can print Help topics from the Help Contents screen or from the topic itself.

To print from the help contents:

1.	Display the Help Contents containing the information you want to print.

2.	Select the topic or topics you want to print and click Print. You can also select a book in the Contents to print several related topics at once.

To print from a Help topic:

1.	Display the topic you want to print.

2.	Click Print. (You can also right-click inside the topic and select Print Topic.)


Help context menus

All the Borland C++Builder Help files have context menus that you access by pointing to an area and right-clicking. These menus provide quick access to commands that are relevant to the area you pointed to.


Using Windows Help

More information about using standard Windows Help features is available if you need it. To learn more about the features of Help in Windows 95 and Windows NT, see the following instructions.

If you're already in a Help topic, press F1 to display Windows Help.

Otherwise, for details about using Help in Windows 95 or Windows NT 4.0,

1.	Choose Start in the lower left corner of the Windows Desktop, then choose Help.

Windows Help is displayed.

2.	In the Help Contents, open the How To book, then open Use Help.

To choose a book in the Help Contents, double-click it or move to it with the arrow keys and press Enter.

For details about using Help in Windows NT 3.51 (or earlier),

In the Program Manager, choose Help|How To Use Help.


Redistributable files

When you finish coding your application and are ready to deploy it, you need to determine which files to include to make it run. These files are called redistributable files.

Refer to the file DEPLOY.TXT in the main C++Builder directory for a list of files that you can redistribute in accordance with the Non-Nonsense License Statement. DEPLOY.TXT lists the files associated with each application option and specifies where the files need to be installed. Detailed information about deploying applications is located in Deploying applications.

If you have the Professional or Enterprise edition of C++Builder, you can also use InstallShield to help prepare an install program for your application. InstallShield provides options to help you determine and include appropriate redistributable files.


Borland C++Builder User's Guide
Using C++Builder

You have requested information from the Using C++Builder Help file. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\HELP) for BCB4.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\BCB4.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Borland C++Builder Programmer's Guide
Programmer's Guide

You have requested information from the Programmer's Guide. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\Help) for BCB4Prog.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\bcb4prog.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4Prog.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Borland C++Builder Library Reference
C Runtime Library Reference

You have requested information from the C Runtime Library Reference. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\Help) for BCB4RTL.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\bcb4rtl.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4RTL.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Borland C++Builder Component Writer's Guide
Writing components

You have requested information from the Writing Components Help file. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\Help) for BCB4CWG.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\BCB4CWG.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4CWG.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Borland C++Builder Database Application Developer's Guide
Borland C++Builder Database Application Developer’s Guide

You have requested information from the Borland C++Builder Database Application Developer’s Guide. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\Help) for BCB4DBD.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\BCB4DBD.* C:\CBuilder\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4DBD.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Borland C++Builder Visual Component Library Reference
Visual Component Library Reference

You have requested information from the Visual Component Library Reference. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\Help) for BCB4VCL.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\BCB4VCL.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4VCL.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Borland C++Builder Error Messages and Warnings
Error Messages and Warnings

You have requested information from Borland C++Builder Error Messages and Warnings. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\Help) for BCB4ERRS.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder\Help\BCB4ERRS.* C:\CBuilder\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4ERRS.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Borland C++Builder Tools and Utilities
Tools and Utilities

You have requested information from Borland C++Builder Tools and Utilities. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\CBuilder4\Help) for BCB4TOOL.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\BCB4TOOL.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If BCB4Tool.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Using Online Help
OpenHelp User’s Guide

You have requested information from the OpenHelp User’s Guide. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\Help) for OPENHELP.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\OPENHELP.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If OPENHELP.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


Object Pascal Language Reference

You have requested information from Object Pascal Language Reference. Either the Help file is not installed or it is not included in your current search range.

To solve the problem:

1.	Look in the Help directory (..\CBuilder4\Help) for Del4OP.HLP.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\Del4OP*.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.

3.	If DEL4OP.HLP is in the HELP directory, try using OPENHELP to add it to the search range:

a.	Choose Help|Customize.

b.	Add the missing Help file.

c.	Click OK.


A Help File Could Not Be Found

You have requested information from a help file that could not be located. Either the Help file is not installed or is not located in the correct directory.

To solve the problem:

1.	Look in the Help directory (..\CBuilder4\Help) for the missing help.

2.	If the file is not there, you need to copy it from CD:

copy D:\CBuilder4\Help\helpfile.* C:\CBuilder4\Help

Note:	This command assumes that you have a CD-ROM drive (set to D:) and that C++Builder is installed on your C: drive. Modify as required for your setup. If you're using disks, you'll need to run a Custom Install.


ClassExplorer basics

The ClassExplorer makes it easy to navigate through your unit files and automates the creation of classes. It contains a tree diagram showing all the types, classes, properties, methods, global variables, and global routines defined in your unit. You can expand or collapse the nodes on the tree.

By default, the ClassExplorer window appears docked to the editor. You can drag it to another docking site using the grab bar at the top, or close the window by clicking the button in the upper left corner.

ClassExplorer parses all project files when a project is opened and parses a single project file when it is saved. It uses this to display the classes in alphabetical order. Within a class, the tree view shows fields, properties, and methods. The elements that can appear in the tree view are described more fully in Class view.

Additional details about the class explorer can be found in the following topics:

Browsing using the keyboard presents the keyboard shortcuts for the ClassExplorer.

ClassExplorer context menu describes the commands you can select by right-clicking in the ClassExplorer.

ClassExplorer options describes the options that affect the ClassExplorer, which you can set from the Environment options dialog.

ClassExplorer legend lists all the symbols used in the ClassExplorer.


Class view

The hierarchy of classes that appears in the ClassExplorer is referred to as the Class view. It contains the following elements:

 Classes

Classes consist of fields, properties and methods. The Class view first shows fields and properties before methods (both in alphabetical order). The symbol of each item represents its visibility (except constructors and destructors - see below). To jump to the code where classes are declared just double-click the class name or use the ClassExplorer context menu.

 Interfaces

If you have included an Object Pascal unit in your project, the Class view shows any interfaces that are defined in that unit. These are displayed just like classes.

 Fields

The base color for fields is green, while for all properties the base color is blue. To jump to the code where fields or properties are declared just double-click the field or property name or use the ClassExplorer context menu. ClassExplorer distinguishes these kinds of fields and properties:

 public or published field

 protected field

 private field

 public or published property

 protected property

 private property

 Methods

The base color for methods is purple, except for constructors and destructors, which use red. There are two special symbols for constructors and destructors. To jump to the code where methods are implemented just double-click the method name or use the ClassExplorer context menu. To jump to the declaration of a method open the context menu and choose "Go to declaration". ClassExplorer distinguishes these kinds of methods:

 public or published method

 protected method

 private method

 constructor method*

 destructor method*

 public operator

 protected operator

 private operator

(*) because constructors and destructors are public usually, there is no differentiation between the visibilities.

 Routines

The "Routines" section in the Class view shows all global procedures and functions (not class methods) declared in the header files included in the project or the external files.

Note:	When you add new units to a project, their elements do not appear in the Class view until you save them.

For keyboard usage, see Browsing using the Keyboard.


ClassExplorer context menu

The list below describes all popup menu items that are available if you right-click the class tree.

Item	Description
Go to Declaration	Jump to the declaration of the class, field or method. Enabled when the selected item is a class, field or a method.
Go to Implementation	Jump to the implementation of a method. Enabled when the selected item is a method.
View Modes	When All Files is selected, the Class view shows all classes and global routines included in the project. When Current File is selected, the Class view shows only the classes and global routines defined in the unit that is selected in the Code editor.
New Field	Invoke the add field dialog.
New Property	Invoke the add property dialog.
New Method	Invoke the add method dialog.
Class Hierarchy	Invoke the class hierarchy view. This is not visible when you right click from the class hierarchy view.
Node	Here you can choose to expand or collapse the current or all Class view nodes.
View Editor	Shifts focus to the Code editor window.
Dockable	Toggle whether the ClassExplorer window can be docked to the code editor or other tool windows.


Class hierarchy

The Class Hierarchy window displays the class hierarchy of the project. It can be used in conjunction with the Class view to navigate through your classes. Besides the hierarchical display of classes the Class Hierarchy window shows the fields and methods of the current selected class.

The Class Heirarchy window uses the same symbols as the Class view. These are listed in ClassExplorer legend.

You can right-click in the class hierarchy to see the ClassExplorer context menu.

For keyboard usage, see Browsing using the Keyboard.

Note:	The Class Hierarchy window does not display any nested classes or structs.


Browsing using the keyboard

This is the keyboard reference for the browsing features of ClassExplorer.

Keyboard and Mouse	Action
ENTER (or mouse double click)	Browse to declaration of classes or fields, or implementation of methods and routines.
SHIFT-ENTER	Like ENTER, if the selected symbol is a method of routine, go to the declaration instead of the implementation.


Add dialog boxes

ClassExplorer supports the adding of Fields, Properties, and Methods.

All dialogs consist of a button bar at the bottom and a part where specific parameters can be entered.

The Reset - button resets the dialog

The Apply - button adds the new item to the source without leaving the dialog. This is useful if you want to add multiple items.

The OK - button adds the new item to the source an leaves the dialog.

The Cancel - button leaves the dialog, without adding the new item.

If the check syntax check box is enabled, ClassExplorer checks the syntax of every identifier you typed in. After pressing the Apply or Ok button, ClassExplorer verifies that no members exist with names you have entered.

When you have to choose a type for a member or a function result, or message types, you can choose a type from a combo box. If you wish to extend the list of types or message types you can edit the files types.lst and messages.lst to add types that are not included by default. These files are located in the Bin directory.

ClassExplorer automatically selects the currently selected class for adding the new member. You can, however, change this to any other class using the drop-down menu.

You can undo changes made to your source using the editor’s undo-command.


Add Fields
Add Dialogs – Add Fields

Use the Add Fields dialog to add a field to a class.

Field Name:	Specify the name of the field.

Add to class:	Specify the class to which you are adding the field.

Type:	Specify the type of the field (int, char *, etc)

Visibility:	Specify the visibility of the new field.

For more details on using this dialog, see ClassExplorer add dialogs.


Add Properties
Add Dialogs – Add Properties

Use the Add Property dialog to add a property to a class.

Property Name	Specify the name of the property.

Add to Class	Specify the class to which the property is added. This is initialized to the currently selected class.

Type	Specify the type for the class.

Visibility	Indicate whether the property is public, private, protected, or published.

Reads	Choose an existing method from the drop-down list to be the read implementer, or check the box labeled Create Get Method to tell ClassExplorer to generate a new read implementer.

Writes	Choose an exisiting method from the drop-down list to be the write implementer or check the box labeled Create Set Method to tell ClassExplorer to generate a new write implementer. Leave this blank for a read-only property.

Implement Get using member	Check this box to tell ClassExplorer to implement the Get method using a class member. Choose an existing member from the drop-down list, or click the Create Field check box to add a new field to hold the property value. This control is only enabled if you check Create Get Method.

Implement Set using member	Check this box to tell ClassExplorer to implement the Set method using a class member. Choose an existing member from the drop-down list, or click the Create Field check box to add a new field to hold the property value. This control is only enabled if you check Create Set Method.

If you are creating a property for a C++ class with Get- and/or Set- methods you can specify the file to which the implementation of the method should be added. Click the ellipses button next to the file name to specify a different file name.

Create Field	Check this box to tell ClassExplorer to add a field to the class that should hold the property value. Type a name for the field into the edit control beside the check box. Check boxes as appropriate to indicate that ClassExplorer should automatically add implementation code that uses the field in the Get method or Set method.

Array	Type the array specifier including the array brackets. (Unless you are creating an array property for a Pascal class, in which case you must omit the array brackets).

Index	If the property is indexed, type in the index specifier as it should appear after the = sign.

Stored	If the property is conditionally stored, type in the stored specify as it should appear after the = sign.

Default	Enter a default value for the property.

How ClassExplorer generates properties

•	If "create field" is checked ClassExplorer generates a new field, which can be used as the read and the write specifier by the property.
If create methods check boxes are not checked, you can use this field for the read and/or the write specifier of the property. If the create methods check boxes are checked, you can use this field for the implementation of these methods. Just check the check boxes below the field name edit control to enable this property generation feature.

•	If the "create Get-method" and/or "create Set-method" are checked, ClassExplorer generates a property, which is read through the Get-Method and written through the Set-Method. The names of the Get- and Set-methods are taken from the Reads- and Writes- field.

•	If "Implement Read" and/or "Implement Write" are checked, ClassExplorer generates code which implements the Get- or Set-method like this:
Assume you added a property of type "TPropertyType" which reads and writes FProperty through get and set methods:

void TClassName::SetProperty(TPropertyType value)

0	{

1	  FProperty = value;

2	}

3	TPropertyType TClassName::GetProperty()

4	{

5	  return FProperty;

6	}

•	ClassExplorer only implements the Get- and/or the Set-methods, when the read and/or write specifiers are defined. Therefore you have to choose either implementation fields or check the "use create field for implementation" option.

•	The difference between the "create field" - field and the identifiers given in the "Reads"- field and the "Write"- field is that the "create field" - field will be generated. Note also: The "create field" - field is "stronger". This means that ClassExplorer will choose the identifier typed in the "create field" - field for reading and/or writing even when the "Reads" - field and/or the "Writes" - field is not empty.

For more details on using this dialog, see ClassExplorer add dialogs.


Add Methods
Add Dialogs - Add Methods

Use the Add Method dialog to add a method to a class.

Method Name	Specify the name of the method.

Add to Class	Specify the class to which the method is added. This is initialized to the currently selected class.

Arguments	List the arguments, if any, just as they appear between the parentheses in the function declaration.

Method Type	Indicate the type of method you are creating. If you are creating a function, choose a return type from the drop-down list (or type in a valid type). The second drop-down list allows you to specify that the function returns a pointer or reference.

Visibility	Indicate whether the function is public, private, protected, or published.

Directives	Check any compiler directives you want to add to the function declaration. If the function is a message-handler, choose the message to which it responds from the drop-down list.

Implementation details	Check the options to indicate what implementation details you want added. The "call inherited" option tells ClassExplorer to generate code that calls the parent class’s method. The “Inline” option tells ClassExplorer to use the inline directive. When “Inline” is checked, the “Implicit Inline” option is enabled, where you can enter the implementation in the unit header.

If you are creating a method for a C++ class you can specify the file to which the implementation of the method should be added. Click the ellipses button next to the file name to specify a different file name.

Method insert example

Assume that you want to insert a method named "Test" into a class named "TTestClass". The new method shall have two arguments i and j, both of type integer. Furthermore you want to the method to override a method named "Test" of the base class of "TTestClass" which is "TTestBase" and you want to call the inherited method.

Declaration Code inserted by ClassExplorer:

virtual int Test(int i, int j);

Implementation Code inserted by ClassExplorer:

int TTestClass::Test(int i, int j)

{

return TTestBase::Test(i,j);

}

For more details on using this dialog, see ClassExplorer add dialogs.


ClassExplorer legend

Following are the symbols that ClassExplorer displays (see also: Class view and Class Hierarchy):

 Project

 Class

 C++ Struct

 C++ Template

 Class that is derived from TForm

 Public or published field

 Protected field

 Private field

 Public or published property

 Protected property

 Private property

 Public or published method, routine

 Protected method

 Private method

 Constructor

 Destructor

 Public operator

 Protected operator

 Private operator


CORBA support

See also

C++Builder includes several wizards and dialogs to help you build CORBA clients and servers. This support includes the following:

On the Multitier page of the New Items dialog, there are wizards to create a new IDL file, to create a new CORBA client or server project, and to generate CORBA object implementations from the IDL files in your project.

You can add IDL files to your project either using the CORBA wizards or by choosing Project | Add To Project. Once they are added, IDL files appear in the project manager, where you can right click on them to compile the IDL file into server and client units that contain skeleton and stub classes.

To influence the way the IDL files are compiled or what CORBA libraries are linked to your project, use the CORBA page of the project options dialog.

To bind to a CORBA object in a CORBA client application, choose Edit|Use CORBA Object.

You can update your implementation classes to reflect changes to your IDL files by choosing Edit|CORBA Refresh. This command optionally displays the Project Updates dialog, depending on the settings in the CORBA page of the environment options dialog.

Use the CORBA toolbar to quickly access the most commonly used CORBA wizards and commands.

Start the Visibroker SmartAgent from the IDE by choosing Tools|Visibroker SmartAgent.

Register your IDL files with the Interface Repository using the Update IDL Repository dialog.

You can set cross-process debugging options for your CORBA server on the Distributed Debugging page of the Tools|Debugger Options dialog.


CORBA IDL syntax

See also

CORBA IDL is the interface definition language defined by the Object Management Group (OMG) for all CORBA interface definitions. This topic presents an overview of IDL that allows you to create IDL files that define most of your objects. For a complete and up-to-date definition of IDL, see the OMG Web site (info@omg.org).

You can use IDL to define types, constants, and interfaces. This is analogous to declaring types, constants, and classes in C++. IDL is a language for declaring interfaces and types. It does not include elements that allow you to write implementations. The objects whose interfaces are declared must be implemented in a separate implementation unit.

Identifiers in IDL file can contain letters, digits, and the underscore (_) character, but can’t begin with an underscore. IDL is case-sensitive. It is generally a good idea to avoid the underscore character, however, because it can cause problems with translating to languages that do not support an underscore. Similarly, it is not a good idea to use two identifiers that differ only in case, as these can be a problem for case-insensitive languages.

IDL files can include preprocessor directives such as:

#define

#elif

#else

#endif

#ifdef

#ifndef

#include

For example, the interface names for the CORBA pseudo types NamedValue, Principal, and TypeCode are available only if the IDL file includes the directive:

#include <orb.idl>

For more details on preprocessor directives, see the VisiBroker documentation.


CORBA IDL types

See also

Typedefs

A typedef declaration can be used to assign a name to any type definition. For example:

typedef string MemoVal;

A typedef is not necessary for basic types or constructed types (which are named in their definition), but should be used for arrays and template types.

Basic types

The following table lists the basic types supported in IDL. Note that there is no int type, and char can’t be qualified by unsigned (char is neither signed nor unsigned).

Type	Description

float	IEEE single-precision floating-point numbers

double	IEEE double-precision numbers

long	32-bit signed integer

short	16-bit signed integer

unsigned long	32-bit unsigned integer

unsigned short	16-bit unsigned integer

char	8-bit quantity (the ISO-Latin subset of ASCII)

boolean	true or false

octet	8-bit quantity guaranteed not to undergo conversion during transmission. (char is not guaranteed inviolate).

any	arbitrary IDL type (analogous to a Variant)

NamedValue	a pair consisting of a name (a string) and a value (an any).

Arrays

IDL provides multidimensional fixed-size arrays to hold like-typed elements. The size of each dimension must be specified in the definition. For example:

typedef long CellValues [10][20];

Note that you must use a typedef on an array that is used as a parameter, attribute, or return value.

Template types

IDL provides two template types, sequence and string. As with arrays, you should use a typedef to name sequence and string types.

A sequence is a variable length list of elements of any IDL type. It is like a one-dimensional array, except that the length is not fixed. It may be bounded or unbounded, depending on whether the maximum size is specified when the sequence type is defined. For example, the following line declares a bounded sequence type:

typedef sequence <octet, 10> UpToTenBytes;

An instance of this type is a sequence of bytes whose length is less than or equal to 10.

The following line declares an unbounded sequence type:

typedef sequence <octet> SomeBytes;

An instance of this type is a sequence of bytes of any length.

A string is a sequence of char. Like a sequence it can be bounded:

typedef string<15> Moniker;

or unbounded

typedef string Description;

When declaring a bounded string type, remember that any null terminator is not considered part of the string’s length. Use strings rather than arrays of char. Uninitialized elements in an array of char can cause transmission problems.

Constructed types

IDL files can also declare constructed types, using the keywords struct, union, and enum.

An example of a struct definition is as follows:

struct StructName {

  char charMember;

  unsigned short AnotherMember;

};

Note that there is no typedef. Using typedef with a struct is considered bad style because it introduces two type names.

An example of an enum definition is as follows:

enum Pet {cat, dog, fish, bird, rat, horse, gerbil};

A union in IDL must be discriminated. That is, a tag field specifies which member of the union is currently assigned a value:

union Reference switch (short) {

  case 1 : { Title: string; Author: string; }

  case 2: URL: string;

  case 3: TopicID: long;

};


CORBA IDL constants

See also

IDL files can declare constants that are then used in interface and type declarations. To declare a constant, use the const keyword:

const unsigned long LengthOfNameString = 15;

IDL files can declare constants of type long, unsigned long, unsigned short, char, boolean, float, double, or string. Note that IDL does not support constants of type octet.

Integer constants can be specified using decimal, octal, or hexadecimal notation. Character constants can be declared using the standard C++ escape sequences such as ‘\n’, ‘\t’, ‘\031’ and so on.


CORBA IDL interfaces

See also

An IDL file interface describes the functionality provided by a CORBA object. It encapsulates all the information required by clients that use the interface. Each interface corresponds to a class on the CORBA server, and its declaration is similar to a class declaration:

interface Example1 {

  readonly attribute string Name;

  attribute long Value;

  long AddToValue(in long Summand, out long Result);

};

Interfaces are declared using the keyword interface. Within the interface declaration is a list of attributes and methods. All attributes and methods are public. There is no concept of private or protected, because these have to do with implementation rather than the public interface of an object.

Attributes

An interface does not have member variables. Attributes behave like properties (which do not carry an implication of how the value is stored), not member variables. They are declared using the keyword attribute.

If clients can’t write to an attribute, its declaration is prefixed by the keyword readonly:

readonly attribute float Balance;

Note:	Although attributes behave like properties, they are not implemented using C++Builder properties (which are not portable). Instead, attributes compile to getter (and, optionally, setter) methods with the same name as the attribute.

Methods

Method declarations must include the return type of the method.

In addition, they must provide the direction in which every parameter is passed, using the keywords in, out, and inout. Each parameter must be given a name.

Normally, a caller of a method is blocked while the server object processes the call. However, IDL syntax allows a method to be declared as oneway, if the caller does not need to wait for a response:

oneway void SendInformation(long Value);

Overloading of method names is illegal, because CORBA is a standard that applies to languages that do not support method overloading.

Comments

Interfaces can include comments, using the same // syntax as C++:

// this is a comment

Type definitions

Interfaces can include type definitions:

interface Example2 {

  struct Example2Struct {

    string Name;

    long Value;

  };

  // more definitions here

};

Other definitions from within the same interface can refer to the type by name (Example2Struct), but definitions outside the interface must use the scope operator (Example2::Example2Struct);

Exceptions

In addition to attributes, methods, and types, an interface can include user-defined exceptions:

interface ExceptionExample {

  exception ValueOutOfBounds {

    long value;

  void SetValue(in long Value)

    raises (ValueOutOfBounds);

  };

};

The SetValue method indicates that it can throw the ValueOutOfBounds exception. This example shows an exception with a member, which aids in debugging. However, interfaces can include exceptions that have no members between the curly braces {}.

Contexts

Methods can have a context clause associated with them. A client can maintain one or more CORBA context objects, which provide mapping from identifiers to string values. An IDL method can specify that it must be provided with the client’s mapping for particular identifiers using the keyword context:

interface ContextExample {

  long SomeMethod(in long Value,

                  in char Letter)

     raises ( /*     */ )

     context ("value1", "value2");

  };

};

The caller of ContextExample must pass a context object as a parameter.

Modules

IDL files can group definitions into modules. The concept of a module is the same as that of a namespace: it allows definitions to be grouped into logical units and prevents namespace clashes. A module defines a naming scope. Thus:

module SyntaxExamples {

  interface Example1 {

    // definitions here

  };

  interface Example2 {

    // definitions here

  };

};

Other definitions from outside the module must use the module name with the scope operator to refer to definitions within the module (SyntaxExamples::Example1).

Inheritance

As with ++ classes, IDL interfaces can be created as descendants of other classes Descendant interfaces inherit the attributes and methods of their ancestor interfaces:

interface Ancestor {

  // definitions here

};

interface Descendant: Ancestor {

  // more definitions here

};

Note:	Because there is no implementation associated with interfaces, descendant interfaces whose corresponding classes override a member function do not relist that method.

Interfaces support multiple inheritance, but only if all ancestor interfaces do not include definitions with identical names.

All IDL interfaces implicitly inherit from the CORBA interface “Object”. This means that any parameter defined to be of type Object can take a reference to any CORBA object.

Forward references

If two interfaces refer to each other, the IDL file must include a forward reference to one of the interfaces, as an inteface can’t refer to definitions later in the IDL file. This is done as follows :

interface Example2; // A forward reference

interface Example1 {

  // definitions here

  readonly attribute Example2 TheOtherOne;

};

interface Example2 {

  // definitions here

  Example1 ReturnTheOtherOne( );

};

Forward references also allow an interface to contain references to itself.


Library is already loaded, probably as a result of an incorrect program termination. Your system may be unstable and you should exit and restart Windows now.

An error occurred while attempting to initialize C++Builder's component library. One or more DLLs are already in memory, probably as a result of an incorrect program termination in a previous C++Builder or BDE session.

You should exit and then restart Windows.


Name is not a valid identifier

The identifier name is invalid. Ensure that the first character is a letter or an underscore (_). The characters that follow must be letters, digits, or underscores, and there cannot be any spaces in the identifier.


A field or method named name already exists

The name you have specified is already being used by an existing method or field.

For a complete list of all fields and methods defined, check the form declaration at the top of the unit source file.


A component class named name already exists

The component library already contains a component with the same class name you have specified.


Breakpoint is set on line that may have been removed by the optimizer or contains no debug information. Run anyway?

A breakpoint is set on a line that does not generate code or in a module which is not part of the project. If you choose to run anyway, invalid breakpoints will be disabled (ignored).


Could not stop due to hard mode

The integrated debugger has detected that Windows is in a modal state and will not allow the debugger to stop your application. Windows enters "hard mode" whenever processing an inter-task SendMessage, when there is no task queue, or when the menu system is active. You will not generally encounter hard mode unless you are debugging DDE or OLE processes within C++Builder.

A standalone debugger such as the Turbo Debugger for Windows can be used to debug applications even when Windows is in hard mode.


Another file named filename is already on the search path

A file with the same name as the one you just specified is already in another directory on the search path.


Cannot find filename1 or filename2 on the current search path

The file you just specified cannot be found on the search path.

You can modify the search path, copy the file to a directory along the path, or remove the file from the list of installed units.


Cannot find implementation of method method

The indicated method is declared in the form's class declaration but cannot be located in the implementation section of the unit. It probably has been deleted, commented out, renamed, or incorrectly modified.

Use UNDO to reverse your changes, or correct the procedure declaration manually. Be sure the declaration in the class is identical to the one in the implementation section. (This is done automatically if you use the Object Inspector to create and rename event handlers.)


Debug session in progress. Terminate?

Your application is running and will be terminated if you proceed. When possible, you should cancel this dialog and terminate your application normally (for example, by selecting Close on the System menu).


Declaration of class class is missing or incorrect

C++Builder is unable to locate the form's class declaration in the header file of the unit. This is probably because the type declaration containing the class has been deleted, commented out, or incorrectly modified. This error occurs if C++Builder cannot locate a class declaration equivalent to the following:

...

class TForm1: public TForm

...


Error address not found

The address you have specified cannot be mapped to a source code position. This error usually occurs for one of the following reasons:

The address you entered is invalid or is not an address in your application.

The module containing the specified address was not compiled with debug information.

The address specified does not correspond to a program statement.

Note that the runtime and visual component libraries are compiled without debug information.


Unable to create process

C++Builder was unable to start your application for the reason specified.


Field field does not have a corresponding component. Remove the declaration?

The first section of your form's class declaration defines a field for which there is no corresponding component on the form. Note that this section is reserved for use by the form designer.

To declare your own fields and methods, place them in a separate public, private, or protected section.

This error will also occur if you load the binary form file (.DFM) into the Code Editor and delete or rename one or more components.


Field field should be of type type1 but is declared as type2. Correct the declaration?

The type of specified field does not match its corresponding component on the form. This error will occur if you change the field declaration in the Code Editor or load the binary form file (.DFM) into the Code Editor and modify the type of a component.

If you select No and run your application, an error will occur when the form is loaded.


IMPLEMENTATION part is missing or incorrect

In order to keep your form and source code synchronized, C++Builder must be able to find the unit's implementation section. This reserved word has been deleted, commented out, or misspelled.

Use UNDO to reverse your changes or correct the reserved word manually.


Incorrect field declaration in class class

To keep your form and source code synchronized, C++Builder must be able to find and maintain the declaration of each field in the first section of the form's class definition. Though the compiler allows more complex syntax, the form designer will report an error unless each field that is declared in this section is equivalent to the following:

...

Class TForm1: public TForm {

FieldType Field1;

FieldType Field2;

...

This error occurred because one or more declarations in this section have been deleted, commented out, or incorrectly modified. Use UNDO to reverse your changes or correct the declaration manually.

Note that this first section of the form's class declaration is reserved for use by the form designer. To declare your own fields and methods, place them in a separate public, private, or protected section.


Incorrect method declaration in class class

To keep your form and source code synchronized, C++Builder must be able to find and maintain the declaration of each method in the first section of the form's class definition. The form designer will report an error unless the field and method declarations in this section are equivalent to the following:

...

Class TForm1: public TForm {

FieldType Field1;

FieldType Field2;

...

<Method1 Declaration>;

<Method2 Declaration>;

...

...

This error occurred because one or more method declarations in this section have been deleted, commented out, or incorrectly modified. Use UNDO to reverse your changes or correct the declaration manually.

Note that this first section of the form's class declaration is reserved for use by the form designer. To declare your own fields and methods, place them in a separate public, private, or protected section.


Insufficient memory to run

C++Builder was unable to run your application due to insufficient memory or Windows resources. Close other Windows applications and try again.

This error sometimes occurs because of insufficient low (conventional) memory.


Invalid event profile name

The VBX control you are installing is invalid.


Module header is missing or incorrect

The module header has been deleted, commented out, or otherwise incorrectly modified. Use UNDO to reverse your changes, or correct the declaration manually.

In order to keep your form and source code synchronized, C++Builder must be able to find a valid module header at the beginning of the source file. A valid module header consists of the reserved word unit, program or library, followed by an identifier (for example, Unit1, Project1), followed by a semicolon. The file name must match the identifier.

For example, C++Builder will look for a unit named Unit1 in UNIT1.CPP, a project named Project1 in PROJECT1.CPP, and a library (.DLL) named MyDLL in MYDLL.DLL.

Note that module identifiers cannot exceed eight characters in length.


No code was generated for the current line

You are attempting to run to the cursor position, but you have specified a line that did not generate code, or is in a module which is not part of the project.

Specify another line and try again.

Note that the smart linker will remove procedures that are declared but not called by the program (unless they are virtual method of an object that is linked in).


Property and method method are not compatible

You are assigning a method to an event property even though they have incompatible parameter lists. Parameter lists are incompatible if the number of types of parameters are not identical. For a list of compatible methods in this form, see the dropdown list on the Object Inspector Events page.


Source has been modified. Rebuild?

You have made changes to one or more source or form modules while your application is running. When possible, you should terminate your application normally (select No, switch to your running application, and select Close on the System Menu), and then run or compile again.

If you select Yes, your application will be terminated and then recompiled.

If you choose not to recompile the source, you may have difficulty interpreting the source view of the debugger because line numbers may have changed from when the code was compiled.


Symbol symbol not found.

The browser cannot find the specified symbol. This error will occur if you enter an invalid symbol name or if debug information is not available for the module that contains the specified symbol.


The method method referenced by form does not exist. Remove the reference?

The indicated method is no longer present in the class declaration of the form. This error occurs when you manually delete or rename a method in the form's class declaration that is assigned to an event property.

If you select No and run this application, an error will occur when the form is loaded.


The method method referenced by form. Event has an incompatible parameter list. Remove the reference?

A form has been loaded that contains an event property mapped to a method with an incompatible parameter list. Parameter lists are incompatible if the number or types of parameters are not identical.

For a list of methods declared in this form which are compatible for this event property, use the dropdown list on the Object Inspector's Events page.

This error occurs when you manually modify a method declaration that is referenced by an event property.

Note that it is unsafe to run this program without removing the reference or correcting the error.


The project already contains a form or module named name

Every module name (program or library, form and unit) in a project must be unique.


#INCLUDE directive is missing or incorrect

In order to keep your forms and source code synchronized, C++Builder must be able to find and maintain the #INCLUDE directives.

This error occurs because the #INCLUDE directive was deleted, commented out, or incorrectly modified. Use UNDO to reverse your changes or correct the declaration manually.


Setting project options and compiling

See also

This section shows how to set project options using the Project Options dialog box, and it describes how to compile and run your program.

Setting project options

You can customize the way C++Builder appears and works for a particular project, including customizing the integrated development environment (IDE) itself. The appearance and behavior of the IDE when you start C++Builder or begin a new project are governed by the settings of several groups of options:

Environment settings affect all C++Builder projects.
To set these options, choose Tools|Environment Options.

Project settings affect the current project only.
To set these options, choose Project|Options.

Repository settings determine the default new form, new data module, and new project.
To set these options, choose Tools|Repository.

If you share your installation of C++Builder with other users, it's possible that another user has modified the option settings. In this case, displays or behaviors might differ from those described in the examples and illustrations in this chapter. In a shared-installation situation, it's a good idea to check and modify environment options as described in the following sections, before creating a new project.

If the Default box on the Project Options dialog is cleared, the current settings affect only the current open project. C++Builder creates an options file with a file extension .BPR in the project directory each time you save the project. When you reopen the project in future sessions, the project options saved in the options file will be in effect.

If you check the Default box and click OK, C++Builder also uses the current settings as the default for any new projects you create.

The .BPR file can be used with the Borland MAKE utility.


Changing the defaults for new projects

See also

The Project Options dialog box contains a check box labeled Default. This control enables you to modify some of C++Builder's default project configuration properties. When you check this control, C++Builder saves your current settings in a file called DEFAULT.BPR located in the BIN directory. (If the current project is a package, default settings are saved in DEFAULT.BPK, also in the BIN directory.) C++Builder then uses the project options settings stored in this file as the default for any new projects you create. If the Default checkbox is cleared, your selections affect only the current Project.

Project options you set for an open project override the current C++Builder defaults, whether those defaults are as originally shipped or as modified by you or another user. If you open an existing project or create a project from a template in the Object Repository that has its own options file, those settings will override the default settings in DEFAULT.BPR. DEFAULT.BPR is required for making new projects.


.BPR file

See also

The .BPR file stores the compiler and linker settings that C++Builder uses to build your project. When you save a project for the first time, C++Builder prompts you to save a .BPR file that defines the name of the project.

Because C++Builder maintains the .BPR file, you will not normally need to modify it manually, and it is generally recommended that you not do so. Most changes you could make to the .BPR file can be made using the Project|Options in C++Builder, and doing so ensures that C++Builder keeps all the project's files synchronized. Additional build options, however, are available as command line switches.

If you need to manually edit the .BPR file, choose Project|View Project Makefile from the main menu to open it in the Code editor.

C++Builder treats each section of the .BPR file differently. For example, you can modify some parts only from the IDE and some parts you can modify only by editing the .BPR file manually. Additionally, some .BPR file options are intended only for the command line make utility. The following examples show the sections of the .BPR file generated by C++Builder for a new application and how they are used by the IDE. Changes to the .BPR file are describes in Makefile changes.

You can modify the options in the following section of the .BPR file manually, but you cannot set them in the IDE:

!if !$d(BCB)

BCB = $(MAKEDIR)\..

!endif

VERSION = BCB.04.03

Use the IDE to set the options in the following section of the .BPR file. Do not change them manually because C++Builder will overwrite them to match the current settings in the IDE:

PROJECT = Project1.exe

OBJFILES = Project1.obj Unit1.obj

RESFILES = Project1.res

RESDEPEN = $(RESFILES) Unit1.dfm

LIBFILES =

IDLFILES =

IDLGENFILES =

LIBRARIES =

SPARELIBS =

PACKAGES = Vcl40.bpi Vclx40.bpi vcljpg40.bpi Vclmid40.bpi Vcldb40.bpi vcldbx40.bpi \

  bcbsmp40.bpi Qrpt40.bpi TeeUI40.bpi teedb40.bpi tee40.bpi Dss40.bpi ibsmp40.bpi \

  NMFast40.bpi Inetdb40.bpi Inet40.bpi dclocx40.bpi

DEFFILE =

You can set the following options either in the IDE or by editing the .BPR file manually. C++Builder uses the most recent settings in the IDE if you have changed them since they were last saved.

CFLAG = -I$(BCB)\include;$(BCB)\include\vcl -Od -Hc -H=$(BCB)\lib\vcl40.csm -w -Ve -r- \

  -k -y -v -vi- -c -b- -w-par -w-inl -Vx -tW -tWM -D$(SYSDEFINES);$(USERDEFINES)

IDLCFLAGS = -I$(BCB)\include -I$(BCB)\include\vcl -src_suffixcpp

PFLAGS = -U$(BCB)\lib\obj;$(BCB)\lib;$(RELEASELIBPATH) \

  -I$(BCB)\include;$(BCB)\include\vcl -$W -$O- -v -JPHN -M

RFLAGS = -i$(BCB)\include;$(BCB)\include\vcl

AFLAGS = /i$(BCB)\include /i$(BCB)\include\vcl /mx /w2 /zd

LFLAGS = -L$(BCB)\lib\obj;$(BCB)\lib;$(RELEASELIBPATH) -aa -Tpe -x -Gn -v

You can modify the following options by editing the .BPR file manually, but you cannot set them in the IDE:

ALLOBJ = c0w32.obj $(PACKAGES) sysinit.obj $(OBJFILES)

ALLRES = $(RESFILES)

ALLLIB = $(LIBFILES) $(LIBRARIES) import32.lib cp32mti.lib

The IDE ignores the options in the following section of the .BPR file. They are available, however, for use with the command line Make utility. You cannot set them in the IDE, but you can change them by editing the .BPR file manually:

.autodepend

# ---------------------------------------------------------------------------

!if !$d(BCC32)

BCC32 = bcc32

!endif

!if !$d(CPP32)

CPP32 = cpp32

!endif

!if !$d(DCC32)

DCC32 = dcc32

!endif

!if !$d(TASM32)

TASM32 = tasm32

!endif

!if !$d(LINKER)

LINKER = ilink32

!endif

!if !$d(BRCC32)

BRCC32 = brcc32

!endif

!if !$d(IDL2CPP)

IDL2CPP = idl2cpp

!endif

# ---------------------------------------------------------------------------

!if $d(PATHCPP)

.PATH.CPP = $(PATHCPP)

.PATH.C   = $(PATHCPP)

!endif

!if $d(PATHPAS)

.PATH.PAS = $(PATHPAS)

!endif

!if $d(PATHASM)

.PATH.ASM = $(PATHASM)

!endif

!if $d(PATHRC)

.PATH.RC  = $(PATHRC)

!endif

# ---------------------------------------------------------------------------

$(PROJECT): $(IDLGENFILES) $(OBJFILES) $(RESDEPEN) $(DEFFILE)

    $(BCB)\BIN\$(LINKER) @&&!

    $(LFLAGS) +

    $(ALLOBJ), +

    $(PROJECT),, +

    $(ALLLIB), +

    $(DEFFILE), +

    $(ALLRES)

!

# ---------------------------------------------------------------------------

.pas.hpp:

    $(BCB)\BIN\$(DCC32) $(PFLAGS) {$< }

.pas.obj:

    $(BCB)\BIN\$(DCC32) $(PFLAGS) {$< }

.cpp.obj:

    $(BCB)\BIN\$(BCC32) $(CFLAG1) -n$(@D) {$< }

.c.obj:

    $(BCB)\BIN\$(BCC32) $(CFLAG1) -n$(@D) {$< }

.c.i:

    $(BCB)\BIN\$(CPP32) $(CFLAG1) -n. {$< }

.cpp.i:

    $(BCB)\BIN\$(CPP32) $(CFLAG1) -n. {$< }

.asm.obj:

    $(BCB)\BIN\$(TASM32) $(AFLAGS) $<, $@

.rc.res:

    $(BCB)\BIN\$(BRCC32) $(RFLAGS) -fo$@ $<


Project source file

See also

The project source file is the main program file C++Builder uses to compile and link all other units and files. C++Builder updates this file throughout the development of the project. As with unit source code files, you can open the project file in the Code editor. The main reason to do this is so you can see the units and forms that make up the project, and which form is specified as the application's main form. As you add forms and units to the project, you can see C++Builder's updates of the project source code.

To open the project source file, use either of these methods:

Right-click the Project Manager and choose View Project Source.

Choose View|Project Source from the main menu.

The contents of the project source file appears in a Code editor window. To hide the project file again, close the window in the Code editor.

C++Builder generates the following source code for a default, blank project:

#include <vcl\vcl.h>

#pragma hdrstop

//---------------------------------------------------------------------------

USEFORM("Unit1.cpp", Form1);

USERES("Project1.res");

//---------------------------------------------------------------------------

WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)

{

try

{

Application->Initialize();

Application->CreateForm(__classid(TForm1), &Form1);

Application->Run();

}

catch (Exception &exception)

{

Application->ShowException(&exception);

}

return 0;

}

The default project code performs the following:

The vcl.h header file contains definitions that are needed for the Visual Component Library. This file is included in each C++Builder project.

The #pragma hrdstop statement instructs the compiler to stop adding header files to the collection of precompiled headers. By default, vcl.h is included in the precompiled headers.

The USEFORM and USERES statements are two of several macros used to add items such as files, forms, and resources to your project. These macros are defined in ..\include\vcl\sysclass.h (for GUI projects) or ..\include\sysdefs.h (for console applications). The header that defines these macros also defines USEDATAMODULE, USEDATAMODULENS, USEFORMNS, USEUNIT, USEOBJ, USERC, USELIB, and USEFILE. C++Builder creates these macros automatically and you will not normally need to change them.

The WinMain call is the program entry point.

Application->Initialize(); initializes the VCL Application object for this process.

The Application->CreateForm statement creates the form specified in the function parameters. The statement creates the form object specified in the second parameter using the form class specified in the first parameter.

C++Builder adds an Application->CreateForm statement to the project file for each form you add to the project. The statements are listed in the order the forms are added to the project. This is the order that the forms will be created in memory at runtime. To change this order, edit the project source file.

The Application->Run(); statement causes the process to enter the program's message loop. From there, the process gets Windows messages and dispatches them to the proper window message procedure. This is essentially where your program begins running in the Windows environment.


Compiling:building, and running projects
Compiling, building, and running projects

All C++Builder projects have as a target a single distributable executable file, either an .EXE or a .DLL file. You can view or test your application at various stages of development. For details, see compiling, building and running projects.


Compiling a single file

See also

To compile a single unit in your project,

1.	Make the unit you want to compile the current selected form unit (in the editor) or file (in Project Manager window).

2.	Choose the Project|Compile Unit from the main menu.

The hourglass cursor appears or the "progress" dialog is displayed, if that option has been set, to indicate that a compile is in progress and returns to normal if the compiler finds no errors.

If an error is found when the Code editor is not open, the Message window displays an error message. If you double-click the message, the Code editor displays the source file showing the line where the error occurred.

If an error is found when the Code editor is open,

The Code editor window comes to the front.

The unit source file page containing the error comes to the top of the Code editor.

The line containing the error is highlighted in the Code editor.

The Code editor message pane displays an error message.

Context-sensitive help about the error message is available by pressing F1.

Compile error display


Making a project

See also

To compile and link all the source files that changed since you last compiled them, choose Project|Make from the main menu.

When you choose this command, this is what happens:

The compiler compiles source code for each unit if the source code has changed since the last time the unit was compiled.

If a unit contains an include (.h) file, and the include file is newer than the unit's .OBJ file, the unit is recompiled.

Once all the units that make up the project have been compiled, C++Builder links them into an executable file (or dynamic link library). This file is given an .EXE (or .DLL) file extension and the same file name as the project source code file. This file now contains all the compiled code and forms found in the individual units, and the program is ready to run.

Obtaining compile status information

You can get information about the compile status of your project by displaying the Information dialog box (Choose Information from the Project menu). This dialog box displays information about the number of lines of source code compiled, the byte size of your code and data, the stack size, and the compile status of the project.

To get status information from the compiler as a project compiles,

1.	Choose Tools|Environment Options.

2.	On the Preferences tab, check Show Compiler Progress.

For more information, see Environment Options in online Help.


Working with event handlers

See also

In C++Builder, almost all the code you write is executed, indirectly or directly, in response to events. Such code is called an event handler. Event handlers are actually specialized procedures, a form method attached to an event. The event handler executes when the particular event occurs.

In C++Builder, you usually use the Object Inspector to generate event handlers. The Object Inspector not only generates the event handler name for you, but if you change that name later using the Object Inspector, C++Builder changes it everywhere that it occurs in your source code. This is not the case for event handlers you write without using the Object Inspector. You can write source code in the Code editor without using the Object Inspector. For example, you might write a general-purpose routine that's not associated directly with a component event, but that is called by an event handler.

This section discusses ways to use the Object Inspector and the Code editor to generate event handlers in your source code. The following topics are explained:

Generating the default event handler

Writing an event handler

Locating an existing event handler

Associating an event with an existing event handler

Coding menu events

To read these topics in sequence, press the >> button.


Generating the default event handler

See also

The default event is the one a component most commonly needs to handle at runtime. For example, a button's default event is the OnClick event.

To generate a default event handler, double-click the component in the form.

Note:	Certain components, don't need to handle user events. For these components, double-clicking them in the form doesn't generate an event handler. Double-clicking certain other components, such as the Image component or either of the menu components, opens a dialog box where you perform design time property edits.

To read these topics in sequence, press the >> button.


Writing an event handler

See also

Once you've placed a component on the form, you can easily write an event handler for it.

To write an event handler for a component,

1.	Select the component on the form.

2.	Click the Events tab of the Object Inspector.

3.	Choose from the list of available events for that component and double click the event you want to program.

The Code editor displays the generated code for the event handler with the cursor positioned so you can start typing an event handler.

4.	Type the source code for the event handler.

The example that follows demonstrates an event handler for a button's OnClick event. When the button is clicked, the contents of a Memo component (Memo1) on the form (TViewerForm) is printed on the default printer.

#include <printers.hpp>

void __fastcall TViewerForm::PrintButtonClick(TObject *Sender)

{

   if (MessageBox (NULL, "Are you sure you want to print?", "Print",

MB_YESNO) == IDYES)

   {

int FontHeight, LinesOnPage;

TCanvas *pcanvas;

 Printer()->BeginDoc();

 pcanvas = Printer()->Canvas;

 FontHeight = pcanvas->Font->Height;

 LinesOnPage = Printer()->PageHeight / -FontHeight;

 for (int i = 0, j = 0; i < Memo1->Lines->Count; i++, j++)

 {

 if ((i > 1) && (i % LinesOnPage == 0))

 {

 j = 0;

 	 Printer()->NewPage();

 }

 	 	pcanvas->TextOut (10, ((j * -FontHeight) + 10),
Memo1->Lines->Strings[i]);

 Printer()->EndDoc();

   }

}

To learn more about programming event handlers, search for event handlers in the Help index.

To read these topics in sequence, press the >> button.


Locating an existing event handler

See also

If you want to view the code for an event handler that you have previously written, you can quickly locate it in the Code editor.

To locate an existing event handler in the Code editor,

1.	In the form, select the component whose event handler you want to locate.

2.	In the Object Inspector, display the Events page.

3.	In the Events column, double-click the event whose code you want to view.

C++Builder displays the Code editor, placing the cursor inside the code block of the event handler. You can now add source code to this event handler.

If you generated a default event handler for a component by double-clicking it in the form, you can locate that event handler the same way.

To locate an existing default event handler, double-click the component in the form. The Code editor opens with the cursor at the start of the first line of code for the component's default event handler.

To read these topics in sequence, press the >> button.


Associating an event with an existing event handler

See also

C++Builder emphasizes reuse at all levels of application development, from the project, to the form, to components and code. You can reuse code by writing event handlers that handle more than one component event.

You can do this by creating generic event handlers that, for example, are called by both a menu command and an equivalent button on a toolbar.

Once you write one such event handler, you can easily associate other compatible events with the original handler.

To read these topics in sequence, press the >> button.


Writing an event handler for multiple component events

See also

The Sender parameter in an event handler informs C++Builder which component generated the event, and called the handler. You can write a single event handler that responds to multiple component events by using the Sender parameter in an if..else statement. However, you don't have to use Sender to share event code.

To associate a new component event with an existing event handler,

1.	In the form, select the component whose event you want to code.

2.	Display the Events page of the Object Inspector, and select the event to which you want to attach handler code.

3.	Click the down arrow next to the event to open a list of existing event handlers.

The list shows only the event handlers in this form that can be assigned to the selected event.

4.	Select an event handler name.

The code written for this event handler is now associated with the selected component event.

Note:	C++Builder doesn't duplicate the event handler code for every component event associated with a shared handler. The same code is called whenever any of the associated component events occurs.

To read these topics in sequence, press the >> button.


Displaying and coding shared events

See also

There is another way to share event handlers. When components have events in common, you can select the components to display their shared events, select a shared event, and then create a new event handler for it, or select an existing one. All the selected components will now use this event handler.

To read these topics in sequence, press the >> button.


Displaying shared events

See also

To display shared events,

1.	In the form, select all the components whose common events you want to view.

2.	Display the Events page of the Object Inspector.

The Object Inspector displays only those events that pertain to all the selected components. (Note also that only events in the current form are displayed.)

To associate a shared component event with an existing event handler,

1.	Select the components with which you want to associate a shared event handler.

2.	Display the Events page of the Object Inspector, and select an event.

The Object Inspector displays only those events which the selected components have in common.

3.	From the drop-down list next to the event, select an existing event handler, and press Enter.

Whenever any of the components you selected receives the specified event, the event handler you selected is called.

To read these topics in sequence, press the >> button.


Creating an event handler for a shared event

See also

To create an event handler for a shared event,

1.	Select the components for which you want to create a shared event handler.

2.	Display the Events page of the Object Inspector, and select an event.

3.	Type a name for the new event handler and press Enter, or double-click the Handler column if you want C++Builder to generate a name.

C++Builder creates an event handler in the Code editor, positioning the cursor on the first line of code.

If you choose not to name the event handler, C++Builder names it for you based on the order in which you selected the components. For example, if you create a shared event handler for several buttons, C++Builder names the event handler Button<n>Click, where Button<n> is the first button you selected for sharing an event handler.

4.	Type the code you want executed when the selected event occurs for any of the components.

To read these topics in sequence, press the >> button.


Modifying a shared event handler

See also

Modifying an event handler that is shared by more than one component is virtually the same as modifying any existing event handler. Just remember that whenever you modify a shared event handler, you are modifying it for all the component events that call it.

To modify the shared event handler,

1.	Select any of the components whose event calls the handler you want to modify.

2.	In the Events page of the Object Inspector, double-click the event handler name.

3.	In the Code editor, modify the handler.

Now when any of the components that share this handler receive the shared event, the modified code is called.

To read these topics in sequence, press the >> button.


Deleting event handlers

See also

When you delete a component, C++Builder removes its reference in the form's type declaration. However, deleting a component does not delete any associated methods from the unit, because those methods might be called by other components in the form.

You can still run your application so long as the method declaration and the method itself both remain in the unit. If you delete the method without deleting its declaration, C++Builder generates an "Undefined forward" error message, indicating that you need to either replace the method itself (if you intend to use it), or delete its declaration as well as the method code (if you do not intend to use it).

You can still explicitly delete an event handler, if you choose, or you can have C++Builder do it for you.

To manually delete an event handler, remove all event handler code and the handler's declaration.

You can also have C++Builder delete an event handler, simply remove all the code (including comments) inside the event handler code block. C++Builder removes all empty event handlers when you compile or save your projects.

To read these topics in sequence, press the >> button.


Coding menu events

See also

While you use the C++Builder Menu designer to visually design your application menus, the underlying event code is what makes the menus useful. Each menu command needs to be able to respond to an OnClick event, and there are many times when you want to change menus dynamically in response to program conditions.

The following topics describe how to associate code with menu events. To read these topics in sequence, press the >> button.


Menu component events

See also

The MainMenu component is different from most other components in that it doesn't have any associated events. You access the events for items in a main menu by means of the Menu designer.

In contrast, the PopupMenu component has one event: the OnPopup event. This is necessary because pop-up menus have no menu bar, therefore, no OnClick event is available prior to users opening the menu.

To read these topics in sequence, press the >> button.


Handling menu item events

See also

There is only one event for menu items: the OnClick event. Code that you associate with a menu item's OnClick event is executed whenever the user chooses the menu item in the running application, either by clicking the menu command or by using its accelerator or shortcut keys.

To generate an event handler for any menu item,

1.	From the Menu designer window, double-click the menu item.

2.	Inside the code block, type the code you want to execute when the user clicks this menu command.

You can also easily generate event handlers for menu items displayed in a form. This procedure does not apply to pop-up menu items, as they are not displayed in the form at design time.

To generate an event handler for a menu item displayed in the form, simply click the menu item (not the menu component). For example, if your form contains a File menu with an Open menu item, you can click Open to generate or open the associated event handler.

This procedure applies only to menu items in a list, not those on a menu bar. Clicking a menu item on a menu bar opens that menu, displaying the subordinate menu items.

To read these topics in sequence, press the >> button.


Associating a menu item with an existing event handler

See also

You can associate a menu item with an existing event handler, so that you don't have to rewrite the same code in order to reuse it.

To associate a menu item with an existing OnClick event handler,

1.	In the Menu designer window, select the menu item.

2.	Display the Properties page of the Object Inspector, and ensure that a value is assigned to the menu item's Name property.

3.	Display the Events page of the Object Inspector.

4.	Click the down arrow next to OnClick to open a list of previously written event handlers.

Only those event handlers written for OnClick events in this form appear in the list.

5.	Select from the list by clicking an event handler name.

The code written for this event handler is now associated with the selected menu item.

To read these topics in sequence, press the >> button.


Writing an event handler for the Help|Memory Info menu

See also

The following example illustrates a menu handler for an item on the Help menu called "Memory Info." When the user selects this menu item, this handler sets several edit fields on a second form to show information on the current state of system memory. After setting the edit fields, the handler then calls the second form's ShowModal function to display the form with the current memory state.

void __fastcall TForm1::Memory1Click(TObject *Sender)

{

char buf[16];

MEMORYSTATUS ms;

   	ms.dwLength = sizeof(MEMORYSTATUS);

   	GlobalMemoryStatus(&ms);

  	wsprintf (buf, "%d", ms.dwTotalPhys);

MemoryForm->TotalPhysicalEdit->Text = buf;

  	wsprintf (buf, "%d", ms.dwAvailPhys);

MemoryForm->FreePhysicalEdit->Text = buf;

wsprintf (buf, "%d", ms.dwTotalPageFile);

MemoryForm->TotalPagingEdit->Text = buf;

wsprintf (buf, "%d", ms.dwAvailPageFile);

MemoryForm->FreePagingEdit->Text = buf;

wsprintf (buf, "%d", ms.dwTotalVirtual);

MemoryForm->TotalVirtualEdit->Text = buf;

wsprintf (buf, "%d", ms.dwAvailVirtual);

MemoryForm->FreeVirtualEdit->Text = buf;

MemoryForm->ShowModal();

}

To learn more about programming event handlers, search for event handlers in the Help index.

To read these topics in sequence, press the << button.


Creating forms

See also

Forms are the foundation for all your C++Builder applications. You design the user interface for your applications using forms. Forms can contain menus, buttons, edit boxes, dialog boxes, or any other objects you need to make your application work the way you want. When you finish designing your form, you can add it to the Object Repository so you or others can reuse it in their projects.

This section discusses the following topics:

What are forms?

Building dialog boxes

Using predesigned forms

Creating form templates


Creating a C++Builder application
Creating a VCL-based application

See also

In brief, to create a VCL-based application, you do the following:

1.	Start with a form.

2.	Put components on the form.

3.	Set the properties of the components.

4.	Create event handlers for those components.

5.	Save the project.

A C++Builder application usually contains multiple forms: a main form, which is the primary user interface, and other forms such as dialog boxes, secondary windows, and so on.

You develop your application by customizing the main form and adding and customizing other forms. You customize forms by adding components, setting their properties, and creating menus to provide user control over the application at runtime. You can also add components such as the menu component or pop-up menu component to create a main menu and context (right-click) menus for your application.


What are forms?

See also

Forms are specialized objects on which you place VCL components. Forms generally appear as windows and dialog boxes in a running application.

Even though you design the application user interface using forms, it's important to understand that a form is just another component. So as with other components, you interact with forms by reading and setting their properties, calling their methods, and responding to their events.

Associated with each form is a .CPP and .H file pair, referred to collectively as the form unit.


Creating a form

See also

C++Builder provides several ways to create a new form, reuse existing forms, and customize existing forms.

You can create a new form in many ways. For example:

Start C++Builder.

C++Builder generates a blank form, its associated unit, and a project file.

Note:	If you chose a different form or project as the default from the Object Repository dialog box, the default form opens instead of a blank form.

Create a new application by choosing File|New Application.

C++Builder generates a new form and unit file whenever it generates a new application.

Add a new form to an existing project by choosing File|New Form.

After the form is created, you can add components to the form.

To reuse existing forms, see "Using predesigned forms".


Placing components on a form

See also

To place a component on a form,

1.	Double-click a component on the Component palette.

2.	Click the form to place the component.

The upper left corner of the component is placed where you click on the form.

3.	Click the resizing handles on the component and drag to size the component, if you need to.

See "Understanding components"to learn how to select appropriate components for your application.


Understanding components

See also

Components are the building blocks of C++Builder applications. Each component encapsulates some single application element in a standard, reusable way. Understanding this component model is the most important step to understanding C++Builder.

This section examines two views of C++Builder's components: a hierarchical view and a functional view. The hierarchical view describes components according to what they are, whereas the functional view describes components according to what they do.


Component hierarchy

See also

One way to understand components is to look at the inheritance relationships that different components share. By noting the common properties, methods, and events that various groups of components inherit, you can understand some of their similarities and differences. For details on the Visual Component Library (VCL) hierarchy, see the Component Writer's Guide and the VCL Reference.

The following figure shows a simplified view of the major kinds of components.

A simple component hierarchy

In general, components fall into two broad categories: nonvisual components and controls.

Nonvisual components are components that represent program elements that the user cannot interact with directly, such as system timers and database connections. Nonvisual components appear at design time as small icons on a form or data module, which enables you to select them for setting properties and attaching event handlers.

Some nonvisual components actually represent visual elements when the application runs, such as a main menu bar or a Windows common dialog box. They store a description of items the application will create at the appropriate time when running.

Controls are visible elements the user can interact with at runtime. In general, they look the same at design time as they will at runtime, which facilitates form layout. Whenever possible, C++Builder controls look and act "live" at design time: a list box displays its list of items, a data grid connected to an active data set displays actual data.

There are two subcategories of controls: windowed and graphics controls.

Windowed controls are controls that can get input focus. Most of the standard Windows controls are windowed controls. The term "windowed" comes from the fact that such controls have a window handle (which you can access through a Handle property).

Graphics controls (sometimes called "non-windowed controls") are controls that cannot receive focus, and do not have window handles. Graphic controls consume fewer system resources, so they are useful for complex forms that need to display numerous controls.

The distinction between windowed and graphic controls is important when you design your user interfaces. For example, if you create a toolbar that contains a large number of buttons, you could use standard Windows button components, but each one would consume a window handle. You could instead choose a non-windowed speedbutton component that would greatly reduce the drain on system resources.


What components do

See also

Another way to understand components is to look at what they do. In many cases, several components can all perform the desired action, but you might choose one because it has greater capacity, better performance, or lesser impact on system resources.

The following table lists categories of common user interface tasks and suggests the components you would consider for those tasks. To learn more about a specific component, select it and press F1.

Task category	Components
Text input and manipulation	edit box, memo, mask edit, rich edit, DBText, DBEdit, DBMemo
Specialized input	scroll bar, track bar, up-down, hot key, splitter, date-time picker, month calendar
Button input, choosing options	button, check box, radio button, bitmap button, speedbutton, tool button, DB check box, DB radio button, DB navigator
List display and manipulation	list box, combo box, tree view, list view, DB list box, DB check box, DB lookup list box, DB lookup combo box
Grouping components	group box, radio group, panel, scroll box, tab control, page control, header control, cool bar, control bar, tool bar, DB radio group
Visual feedback	label, progress bar, status bar, static text
Tabular display	string grid, draw grid, DB grid, DB control grid
Graphic and media display	image, shape, bevel, image list, paint box, DB image, animate, media player
Windows common dialog boxes	open dialog, save dialog, font dialog, color dialog, print dialog, printer setup dialog, search dialog, replace dialog


Adding components in a specific location

See also

To add a component to a specific location in the form,

1.	Click the component on the Component palette.

2.	Move the cursor to where you want the upper left corner of the component to appear in the form, then click the form.

The component appears in its default size at the position you clicked on the form.

When you add a component to a form, C++Builder generates an instance variable, for the component and adds it to the form's type declaration. C++Builder is a two-way tool, so adding a component changes the form's type declaration:

class TAboutBox : public TForm

{

__published:

 TButton *Button1:

 TButton *Button2;

 void __fastcall Button1Click(TObject *Sender);

private:     //private user declarations

public:     //public user declarations

   virtual __fastcall TAboutBox(TComponent* Owner);

};

Similarly, when you delete a component, C++Builder deletes the corresponding type declaration.


Adding multiple copies of a component

See also

To add multiple copies of the same component,

1.	Press and hold down the Shift key.

2.	Click the component on the palette, then click the form once for each copy you want of the component. (You don't need to hold down the Shift key after the component is selected.)

Clicking on the form continues to add the component to the form, as long as the component remains selected in the palette.

3.	Click the pointer icon to clear the selected component.


Organizing components

See also

C++Builder provides several components--the group box, panel, page control, and scroll box--that can contain other components. These are called container components. You can use these container components to group other components so that they behave as a unit at design time. You often use container components such as the panel component to create customized toolbars, backdrops, status bars, and so on.

When you place components within container components, you create a new parent-child relationship between the container and the components it contains. Design-time operations you perform on these "container" (or parent) components, such as moving, copying, or deleting, also affect any components grouped within them.

Note:	The form remains the owner for all components, regardless of whether they are parented within another component.

Once a component is on the form, you must add it to a container component by cutting and then pasting it. Simply moving it will not add it to the container.


Grouping components

See also

To group components,

1.	Add a group box or panel component to a form.

2.	Select the container component and add components as you normally would.

As you add components, they appear inside the container component.


Adding multiple copies of a component to a container

See also

To add multiple copies of a component to a container,

1.	Press Shift and then select a component from the palette.

2.	Click anywhere in the container component.

Each subsequent click continues to place the component in whatever eligible receiving component (including the form) is clicked.

3.	Select the pointer icon when you finish adding components.


Aligning using the Alignment palette

See also

To align components using the Alignment palette,

1.	Select the components.

2.	Choose View|Alignment palette.

The Alignment palette appears.

3.	Select an alignment icon from the palette.


Aligning using the Alignment dialog box

See also

To align components using the Alignment dialog box,

1.	Select the components.

2.	Choose Edit|Align.

The Alignment dialog box appears.

3.	Select the alignment options you want in the dialog box.

4.	Choose OK to put your alignment options into effect.

You can continue to choose or modify alignment options as long as the components remain selected.


Aligning components using the grid

See also

The evenly spaced dots that appear in the form at design time are the form grid. The grid makes it easier to align components visually.

Form grid

By default, both the grid and its Snap To Grid option, which causes the left and top sides of each component to always align with the nearest grid markings, are enabled at design time. You can, however, choose to disable the Snap To Grid option or disable the grid altogether.

You can also modify the granularity of the grid--that is, how far apart the grid dots appear.


Setting grid options

See also

To set form grid options,

1.	Choose Tools|Environment Options to display the Environment Options dialog box.

2.	Click the Preferences tab to display the Preferences page.

3.	In the Form designer options, check Display Grid to view the grid, or uncheck it to hide it.


Snapping to grid

See also

To enable the Snap To Grid option,

1.	Choose Tools|Environment Options to display the Environment Options dialog box.

2.	In the Form Designer options, check the Snap To Grid to enable the option, or uncheck it to disable it.


Changing grid size

See also

To modify the granularity of the grid,

1.	Choose Tools|Environment Options to display the Environment Options dialog box.

2.	In the Form designer options, enter new values in the Grid Size boxes.

Grid size X controls the horizontal spacing, and grid size Y controls the vertical spacing. The default values are 8 and 8. To space the dots further apart, choose larger numbers. To create a finer grid, choose smaller numbers.


Locking the position of components

See also

Once you have aligned the components on a form, you can prevent components from being moved accidentally.

To lock the position of the components on a form,

Choose Edit|Lock Controls from the menu bar.

A check mark appears before the Lock Controls menu item.

To unlock a form, choose Edit|Lock Controls from the menu bar.


About the Object Inspector

See also

The Object Inspector enables you to

Set design-time properties for components you placed on a form (or for the form itself)

Create and help you navigate through event handlers

The Object selector at the top of the Object Inspector is a drop-down list containing all the components on the active form and it also displays the object type of the selected component. This lets you quickly select different components on the current form.

You can resize the columns of the Object Inspector by dragging the separator line to a new position.

The Object Inspector has two pages:

Properties page

Events page


Properties page

See also

The Properties page of the Object Inspector enables you to set design-time properties for components on your form, and for the form itself. You can set runtime properties by writing source code inside event handlers.

The first column on the Property page lists the names of the selected component’s published properties:

If a plus symbol (+) appears beside a property name, this can be clicked to display the sub-properties of that property.  These can be a list of possible values when the property represents a set of flags (the value column lists the set enclosed in square brackets []), or subproperties if the property represents an object (the value column gives the name of the object, enclosed in parentheses).

The second column on the Property page lists the property values:

When the property is selected, the value changes to an edit control where you can type a new value.

If the value can be set using a dialog, an ellipses button (...) appears when the property is selected. Click this button to display a dialog where you can set the property. You can also display the dialog by double-clicking.

If the value is an enumerated type, a drop-down button appears when the property is selected. Click this button to display a drop-down list that you can use to set the property.

The Properties page displays only the published properties of the selected component.


Events page

See also

The Events page of the Object Inspector enables you to connect forms and components to program events. When you double-click an event from the Events page, C++Builder creates an event handler and switches focus to the Code editor. In the Code editor, you write the code inside event handlers that specifies how a component or form responds to a particular event.

When you select an event, the value column can display a drop-down list of existing event handlers that can respond to the event. Choose one of these existing event handlers if you write one event handler to respond to multiple events.

The Events page displays only the published events of the selected component.


How the Object Inspector displays properties

See also

The Object Inspector dynamically changes the set of properties it displays, based on the component selected. Only the shared properties are displayed. For example, if you select a Label and a GroupBox, you'll see the property Color along with other properties. If you select a Label and then a Button, the choice for Color goes away because Color is not a property for buttons. The Object Inspector has several other behaviors that make it easier to set component properties at design time.

When you use the Object Inspector to select a property, the property remains selected in the Object Inspector while you add or switch focus to other components in the form, provided that those components also share the same property. This enables you to type a new value for the property without always having to reselect the property.

If a component does not share the selected property, C++Builder selects its Caption property. If the component does not have a Caption property, C++Builder selects its Name property.

When more than one component is selected in the form, the Object Inspector displays all properties that are shared among the selected components. This is true even when the value for the shared property differs among the selected components. In this case, the property values displayed are either the default, or the value of the first component selected. When you change any of the shared properties in the Object Inspector, the property value changes those values in all the selected components.

There is one exception to this: when you select multiple components in a form, the Name property no longer appears in the Object Inspector, even though they all have a Name property. This is because you cannot assign the same name to more than one component in a form.


Tabbing to specific properties

See also

You can jump directly to a property in the Object Inspector by pressing the Tab key followed by any alphabetic character. The cursor jumps to the Property column of the first property beginning with the typed letter. (The Object Inspector lists property names alphabetically.)

To tab to a specific property (in this case, Width),

1.	Select the form.

2.	In the Object Inspector, select the form's AutoScroll property.

3.	Press Tab, W to jump directly to the Width property.

4.	Press Tab again to place the cursor in the Value column, where you can begin entering your edits.

Pressing Tab acts as a toggle between the Value column and the Property column. Whenever you are in the Property column, pressing an alphabetic character jumps you to the first property starting with that character.


Changing component properties

See also

You can change component properties at design time or dynamically when the application runs. You can also view a form as a text file and make changes that will be reflected in the Object Inspector.

To change a component property at design time,

1.	Select the component in the form or with the Object selector.

2.	Select the property that you want to change by selecting it from the Properties page.

3.	Type a new value for that property.

To change a component property at runtime,

1.	Select the component in your source code using the Code editor. (For example, Form1)

2.	Select the property that you want to change (Color) and type a new value (clAqua).

See the following example:

Form1->Color = clAqua;


Displaying and setting shared properties

See also

You can set shared properties to the same value without having to individually set them for each component.

To display and edit shared properties,

1.	In the form, Shift+click to select the components whose shared property you want to set.

The Properties page of the Object Inspector displays only those properties that the selected components have in common. (Notice, however, that the Name property is no longer visible because each component must have a unique name.)

2.	With the components still selected, use the Object Inspector to set the property.


Building dialog boxes

See also

C++Builder provides a number of predesigned dialog boxes as components for your user interface. They appear on the Dialogs page of the Component palette. You can specify different options for these dialog boxes, such as whether a Help button appears in the dialog box, and then add any changes your dialog requires. You can also develop customized dialog boxes.


Developing customized dialog boxes

See also

This section describes the most common considerations when designing customized dialog boxes, including

Making a dialog box modal or modeless

Setting form properties for a dialog box

Specifying a caption for a dialog box

Setting the tab order

Testing the tab order

Removing a component from the tab order

Disabling components


Making a dialog box modal or modeless

See also

At design time, dialog boxes are simply customized forms. At runtime, they can be either modal or modeless. When a form runs modally, the user must explicitly close it before working in another running form. Most dialog boxes are modal.

When a running form is modeless, it can remain onscreen while the user works in another form (for example, the application main form). You might create a modeless form to display status information, such as the number of records searched during a query, or information the user might want to refer to while working.

Note:	If you want a modeless dialog box to remain on top of other open windows at runtime, set its FormStyle property to fsStayOnTop.

Forms have two methods that govern their runtime modality. To display a form in a modeless state, you call its Show method; to display a form modally, you call its ShowModal method.


Setting form properties for a dialog box

See also

By default, C++Builder forms have Maximize and Minimize buttons, a resizable border, and a Control menu that provides additional commands to resize the form. While these features are useful at runtime for modeless forms, modal dialog boxes seldom need them.

C++Builder provides a BorderStyle property for the form that includes several useful values. Setting the form's BorderStyle to bsDialog implements the most common settings for a modal dialog box:

Removing the Minimize and Maximize buttons

Providing a Control menu with only the Move and Close options

Making the form border non-resizable, and giving it a "beveled" appearance

The following table shows other form property settings that can be used, individually or in concert, to create different form styles.

Property	Setting	Effect
BorderIcons
biSystemMenu	False	Removes Control (System) menu
biMinimize	False	Removes Minimize button
biMaximize	False	Removes Maximize button
BorderStyle
	bsSizeable	Lets the user resize the form border
	bsSingle	Provides a single, non-resizable border
	bsNone	No distinguishable border; not resizable
	bsDialog	Window has a border, but not resizable
	bsToolWindow	Makes the title bar small; window is not resizable
	bsSizeToolWindow	Makes the title bar small; window is resizable
Note:	Changing these settings doesn't change the design-time appearance of the form; these property settings become visible at runtime.


Specifying a caption for a dialog box

See also

By default, C++Builder displays the Name property value for each form in the form's title bar. If you change the Name property of the form prior to changing the Caption property, the title bar caption changes to the new name. Once you change the Caption property, the form's title bar always reflects the current value of Caption.


Setting the tab order

See also

Tab order is the order in which focus moves from component to component on a form that is displayed in a running application when the user presses the Tab key. To let the Tab key shift focus to a component on a form, the TabStop property of the component must be set to true.

The tab order is initially set by C++Builder, corresponding to the order in which you add components to the form. You can change this by using the Edit Tab Order dialog box, or by changing the TabOrder property of each component.


Setting tabs with the Edit Tab Order dialog box

See also

To change the tab order using the Edit Tab Order dialog box,

1.	Select the form or a container component in the form, that contains the components whose tab order you want to set.

2.	Choose Edit|Tab Order, or right-click and choose Tab Order.

The Edit Tab Order dialog box appears, displaying a list of components ordered (first to last) in their current Tab order.

3.	In the Controls list, select a component, and press the appropriate arrow button (Up or Down), or move the component to its new location in the tab order list.

4.	When the components are ordered the way you want, choose OK.

Using the Edit Tab Order dialog box changes the value of the component's TabOrder property. You can also do this manually, if you want.

Keep in mind the following points when manually setting your tab order (you needn't be concerned with these points if using the Edit Tab Order dialog box):

Each TabOrder property value must be unique. If you assign two components the same TabOrder value, C++Builder renumbers the TabOrder value for all other components accordingly.

If you attempt to give a component a TabOrder value equal to or greater than the number of components on the form (because numbering starts with 0), C++Builder changes the value, so it is last in the tab order.

Invisible or disabled components are not recognized in the tab order, even if they have a valid TabOrder value. When the user presses Tab, the focus skips over such components and goes to the next one in the tab order.


Setting tabs with the Tab Order property

See also

To change tab order using the component's TabOrder property,

1.	Select the component whose position in the tab order you want to change.

2.	In the Object Inspector, select the TabOrder property.

3.	Change the TabOrder property's integer value to the value you want the component to have in the tab order, starting with the number zero.


Testing the tab order

See also

You can test the tab order you've set by running the application. At design time, focus always moves from component to component in the order that the components were placed on the form. Changes you make to the tab order are reflected only at runtime.

To test the tab order,

1.	Compile and run the application.

2.	Display the form whose tab order you want to test.

3.	Use the Tab key to view the order in which focus moves from component to component.


Removing a component from the tab order

See also

In some cases, you might want to prevent users from being able to tab to a component on a form, and have them skip to the next one instead.

To remove a component from the tab order,

1.	Select the component.

2.	Use the Object Inspector to set the value of the TabStop property to False.

Note:	Removing a component from the tab order does not disable the component.


Disabling components

See also

When a component is disabled, it appears dimmed in the running application, and the user cannot tab to it, even if its TabStop property is set to true.

By disabling a component at design time, that component will be initially unavailable to the user when the dialog box first opens. You can also dynamically change whether a component is enabled at runtime.

To disable a component at design time, use the Object Inspector to set the component's Enabled property to False.

To disable a component at runtime, type the following code in an event handler for the component:

<component>->Enabled = false;

For example, the following event handler specifies that when Button1 receives an OnClick event, Button2 is disabled.

void __fastcall TAboutBox::Button1Click(TObject* Sender)

{

 Button2->Enabled = false;

}


Using predesigned forms

See also

When you start C++Builder for the first time, it opens with an empty project consisting of a single, blank form that contains no controls or other components. You can then place components on the form. You can also choose to add a predesigned form to the project and use it or modify it.

You can easily use any of the predesigned forms in the Object Repository in your applications. You can also save any form you've designed in the Object Repository. To add a predesigned form to your project, choose File|New.

When you choose File|New, C++Builder displays the New Items dialog box, which shows what is in the Object Repository. The Object Repository contains forms, projects, data modules, and wizards you can either use directly, copy into your projects, or derive new items from.


Adding an existing form

See also

You can use any of the forms from the Object Repository in your application.

To add a form from the Object Repository to your project,

1.	With a project open, choose File|New.

The New Items dialog box appears.

2.	Choose the Forms page.

The Forms page opens with the default new form highlighted.

Note:	Depending on which templates have been installed, modified, or deleted in your C++Builder installation, your Object Repository window for forms might look different from the one shown.

Standard C++Builder forms in the Object Repository

3.	Select the form you want to add.

4.	Choose one of the sharing options: Copy, Inherit, or Use.

Copy creates an exact copy of the form and places it in your project. Changes made to the template form in the Object Repository will not affect the form in your project. Note that Copy is the only option available for Form wizards (such as the Database form wizard), because running the wizard generates a new form for you.

Inherit derives a new form object from the one in the Object Repository and adds it to your project. Changes to the template form in the Object Repository will show up in your form, unless you have already modified that part of the new form.

Use means you want to use and modify the template form. Any changes you make to the form in your project are reflected back into the template in the Object Repository.

5.	Choose OK.

C++Builder adds the form and its associated unit to the project you have open. You can now use this form the way you would any form in a project.

Modifications you make might affect the original item in the Object Repository, depending on the sharing option you chose.

Note:	With no project open, it is still possible to choose File|New and select a form from the Object Repository. The form's unit file then opens as a reference file. If you subsequently open a project or create a new project, the open template form is not part of that project. To save it as part of the project, you must explicitly add it to the project.


Creating form templates

See also

You can create form templates for others to use by saving a form or an object in the Object Repository.

To add your current form to the Object Repository,

1.	Right-click the form and choose the Add To Repository command.

The Add To Repository dialog box appears.

2.	In the Title edit box, specify a name for the form.

3.	In the Description edit box, type a brief description of this form.

4.	Choose the Page on which the form should appear in the New Items dialog box.

5.	You can specify an Author of the form, which shows only in the detailed view of the Object Repository.

6.	To specify an icon for the object, choose the Browse button.

The Select Icon dialog box appears.

7.	Locate and select the icon (if any) you want to use, and choose OK to exit the Select Icon dialog box.

8.	Choose OK to accept your specifications, and exit the Add To Repository dialog box.

The next time you choose File|New and click the page tab you selected above, your form appears in the templates list, with the icon and title you chose.


Inheriting from forms in the Object Repository

See also

If you create an application with several similar forms, you can create one version of the form, then create the others by inheriting. This allows you to change the standard form and have those changes reflected in all the inherited forms.

When browsing items in the Object Repository, you have the option to copy, inherit, or use at the bottom of the dialog box.

When you inherit from the template form, you create a reference to the ancestor form, and only have additional code for added components and event handlers. If you inherit several forms in the same project, they share the inherited code. All the ancestors of the chosen form are also added to the project.

Inheriting forms is a good way to reduce the size of projects that use a number of similar forms. It also provides a way to create and maintain a set of standard form templates that work in a number of projects, even when each project requires customization.

Inherit is not enabled when a Form wizard is selected, since these cannot be ancestor forms. Choosing Copy on a non-inherited form works the same as before, it creates a new form that is a copy of the form chosen.


Sharing forms

See also

Before you begin designing and building the forms for your applications, think about whether you want these forms to be available for other developers to use. C++Builder is designed with the principle of reusable components in mind, and this encompasses larger elements such as forms or even entire projects.

The easiest way to share a form is to add an existing form to a project. Place forms that you want to reuse into the Object Repository.


Linking forms

See also

Adding a form or component to a project adds a reference to it in the project file, but not to other parts of the project. You need to add a reference to it in the other files that need access to it. This is called form linking.

The most common kind of component that uses such links are data-access components. For example, you can have a table component on one form in an application and allow several different forms to provide different views into the same data set, such as a grid view and a form view.

C++Builder links forms by linking their associated units. Given two forms, Form1 and Form2, and their associated units, Unit1 and Unit2, respectively, components on Form1 can refer to components on Form2 if Unit1 contains Unit2 in one of its #include directives.

To link one form to another,

1.	Select the form that needs to refer to the other.

2.	Choose File|Include Unit Hdr.

3.	Select the name of the form unit for the form to be referenced.

4.	Choose OK.

Linking a form to another just means that the #include directives of one form unit contains a reference to the other's form unit, meaning that the linked form and its components are now in scope for the linking form.


Programming with VCL objects

See also

Object-oriented programming (OOP) is a natural extension of structured programming. OOP requires that you use good programming practices and makes it very easy for you to do so. The result is clean code that is easy to extend and simple to maintain.

Once you create an object for an application, you and other programmers can then use that same object in other applications. Reusing objects can greatly cut your development time and increase productivity for yourself and others.

This section explains what you need to know about objects to use C++Builder effectively. If you want to create new components and put them on the C++Builder Component palette, see the Component Writer's Guide.

These are the primary topics discussed in this section:

What is an object?

Inheriting data and code from a class

Object scope

Assigning values to object variables

Creating nonvisual objects

Before reading this section, you should know how to design a user interface for your application using the C++Builder tools, how a C++Builder project is structured, and how to handle events.

To read these topics in sequence, press the >> button.


What is an object?

See also

An object is an instance of a class that wraps up data and code all into one bundle. Before OOP, code and data were treated as separate elements.

Think of the work involved to assemble a bicycle if you have all the bicycle parts and a list of instructions for the assembly process. This is analogous to writing a Windows program from scratch without using objects. C++Builder gives you a head start on "building your bicycle" because it already gives you many of the "preassembled bicycle parts"--the C++Builder forms and components.

An object is a specific instance of a class. A class is a collection of related information that includes both data and functions (the instructions for working with that data). The properties of C++Builder objects have default values. You can change these values at design time to modify an object to suit the needs of your project without writing code. If you want a property value to change at runtime, you need to write only a very small amount of code.

To read these topics in sequence, press the >> button.


Examining a C++Builder object and its class

See also

When you choose to create a new project, C++Builder displays a new form for you to customize. In the Code editor, C++Builder declares a new class for the form and produces the code in a .cpp and .h unit file pair that creates the new form object. The section "Inheriting data and code from a class" discusses why a new class is declared for each new form. For now, examine the following example to see what the code in the Code editor looks like:

Unit1.h file

#ifndef Unit1H

#define Unit1H

//---------------------------------------------------------------------------

#include <vcl\Classes.hpp>

#include <vcl\Controls.hpp>

#include <vcl\StdCtrls.hpp>

#include <vcl\Forms.hpp>

//---------------------------------------------------------------------------

class TForm1 : public TForm

{

__published:	// IDE-managed Components

private:	// User declarations

public:	// User declarations

virtual __fastcall TForm1(TComponent* Owner);

};

//---------------------------------------------------------------------------

extern TForm1 *Form1;

//---------------------------------------------------------------------------

#endif

Unit1.cpp file

//---------------------------------------------------------------------------

#include <vcl\vcl.h>

#pragma hdrstop

#include "Unit1.h"

//---------------------------------------------------------------------------

#pragma resource "*.dfm"

TForm1 *Form1;	//The object is here

//---------------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

}

//---------------------------------------------------------------------------

The new class is TForm1, and it is derived from TForm, which is also a class. The section "Inheriting data and code from a class" presents more about TForm and objects derived from other objects.

So far, type TForm1 appears to contain no data members or methods, because you haven't added to the form any components (the data members of the new object), and you haven't created any event handlers (the methods of the new object). As discussed later, TForm1 does contain data members and methods, even though you don't see them in the class declaration.

This code declaration creates a variable named Form1 of the new class TForm1.

TForm1 *Form1;

Form1 is called an instance of the type TForm1. The Form1 variable refers to the form itself to which you add components to design your user interface.

You can declare more than one instance of a class. You might want to do this to manage multiple child windows in a Multiple Document Interface (MDI) application, for example. Each instance carries its own data in its own package, and all the instances of a class use the same code.

Although you haven't added any components to the form or written any code, you already have a complete C++Builder application that you can compile and run. All it does is display a blank form because the form object doesn't yet contain the data members or methods to do more.

Suppose, though, that you add a button component to this form and an OnClick event handler for the button, that changes the color of the form when the user clicks the button. You then have an application that's about as simple as it can be and still actually does something. Here is the form for the application:

A simple form

When the user clicks the button, the form changes color to green. This is the event-handler code for the button OnClick event:

void__fastcall TForm1::Button1Click(TObject *Sender)

{

 Form1->Color = clGreen;

}

If you create this application and then look at the code in the Code editor, you'll see there is both a Unit1.cpp and Unit1.h file. You can right-click and choose Open Source/Header Files to display the header file. You will see files like the following:

Unit1.h file

#ifndef Unit1H

#define Unit1H

//---------------------------------------------------------------------------

#include <vcl\Classes.hpp>

#include <vcl\Controls.hpp>

#include <vcl\StdCtrls.hpp>

#include <vcl\Forms.hpp>

//---------------------------------------------------------------------------

class TForm1 : public TForm

{

__published:	// IDE-managed Components

TButton *Button1;

void__fastcall Button1Click(TObject *Sender);

private:	// User declarations

public:	// User declarations

virtual __fastcall TForm1(TComponent* Owner);

};

//---------------------------------------------------------------------------

extern TForm1 *Form1;

//---------------------------------------------------------------------------

#endif

Unit1.cpp file

//---------------------------------------------------------------------------

#include <vcl\vcl.h>

#pragma hdrstop

#include "Unit1.h"

//---------------------------------------------------------------------------

#pragma resource "*.dfm"

TForm1 *Form1;

//---------------------------------------------------------------------------

__fastcall TForm1::TForm1(TComponent* Owner)

: TForm(Owner)

{

}

//---------------------------------------------------------------------------

void__fastcall TForm1::Button1Click(TObject *Sender)

{

Form1->Color = clGreen;

}

//---------------------------------------------------------------------------

The new TForm1 class now has a Button1 data member--that's the button you added to the form. TButton is a class, so Button1 is also an object. Classes, such as TForm1, can contain other objects, such as Button1, as data members. Each time you put a new component on a form, a new data member with the component's name appears in the form's class declaration in the unit header file (Unit1.h).

All the event handlers you write in C++Builder are methods of the form object. Each time you create an event handler, a method is declared in the form class. The TForm1 type now contains a new method, the Button1Click procedure, declared within the TForm1 class declaration.

The actual code for the Button1Click method appears in the .cpp part of the unit file pair. The method is the same as the empty event handler you created with C++Builder and then filled in to respond when the user clicks the button as the application runs.

To read these topics in sequence, press the >> button.


Changing the name of a component

See also

You should always use the Object Inspector to change the name of a component. The best time to do this is right after you've created the form or component. For example, when you change the default name of a form from Form1 to something else by changing the value of the Name property using the Object Inspector, the name change is reflected throughout the code C++Builder produces. If you wrote the previous application, but named the form ColorBox, this is how your code would appear:

Unit1.h file

#ifndef Unit1H

#define Unit1H

//---------------------------------------------------------------------------

#include <vcl\Classes.hpp>

#include <vcl\Controls.hpp>

#include <vcl\StdCtrls.hpp>

#include <vcl\Forms.hpp>

//---------------------------------------------------------------------------

class TColorBox : public TForm

{

__published:	// IDE-managed Components

TButton *Button1;

void__fastcall Button1Click(TObject *Sender);

private:	// User declarations

public:	// User declarations

virtual __fastcall TColorBox(TComponent* Owner);

};

//---------------------------------------------------------------------------

extern TColorBox *ColorBox;

//---------------------------------------------------------------------------

#endif

Unit1.cpp file

//---------------------------------------------------------------------------

#include <vcl\vcl.h>

#pragma hdrstop

#include "Unit1.h"

//---------------------------------------------------------------------------

#pragma resource "*.dfm"

TColorBox *ColorBox;

//---------------------------------------------------------------------------

__fastcall TColorBox::TColorBox(TComponent* Owner)

: TForm(Owner)

{

}

//---------------------------------------------------------------------------

void__fastcall TColorBox::Button1Click(TObject *Sender)

{

Form1->Color = clGreen;

}

//---------------------------------------------------------------------------

Notice that the name of the form class changed from TForm1 to TColorBox. Also note that the form variable is now ColorBox, the name you gave to the form. References to the ColorBox variable and the TColorBox type also appear in the final block of code, the code that creates the form object and starts the application running. If C++Builder originally generated the code, it updates it automatically when you use the Object Inspector to change the name of the form or any other component.

Note that the code you wrote in the OnClick event handler for the button hasn't changed. Because you wrote the code, you have to update it yourself and correct any references to the form if you change the form's name. If you don't, your code won't be compiled. In this case, change the code to this:

__fastcall TColorBox::Button1Click(TObject *Sender);

{

 ColorBox->Color = clGreen;

}

You should change the name of a component only with the Object Inspector. While nothing prevents you from altering the code C++Builder produced and changing the name of component variables, you won't be able to compile your program until you manually update all instances of the variable name.

To read these topics in sequence, press the >> button.


Inheriting and code from a class
Inheriting data and code from a class

See also

The TForm1 class might seem quite simple. If you create the application, TForm1 appears to contain one data member, Button1, one method, Button1Click, and no properties. Yet you can change the size of the form, add or delete Minimize and Maximize buttons, or set up the form to become part of a Multiple Document Interface (MDI) application. How is it possible to do all these things with a form that contains only one data member and one method?

The answer lies in the notion of inheritance. Recalling the bicycle analogy, once you have put together all the objects that make up a complete "bicycle object," you can ride it because it has all the essentials to make the bicycle useful--it has pedals you push to make the wheels go around, it has a seat for you to sit on, it has handlebars so you can steer, and so on. Similarly, when you add a new form to your project, it has all the capabilities of any form. For example, all forms provide a space to put other components on them, all forms have the methods to open, show, and hide themselves, and so on.

Suppose, though, that you want to customize that bicycle, just as you would customize a form object in C++Builder. You might adjust a few gear settings, add a headlight, and provide a horn with a selection of sounds--just as you might customize a form by adding or rearranging buttons, changing a few property values, and adding a new method that allows the form to appear with a plaid background.

To change the bicycle to make it exactly as you want it, you start with the basic model and then customize it. You do the same thing with C++Builder forms. When you add a new form to your project, you've added the "basic model" form. By adding components to the form, changing property values, and writing event handlers, you are customizing the new form.

To customize any object, whether it be a blank form, a form with multiple controls that is used as a dialog box, or a new version of the C++Builder bitmap button, you start by deriving a new class from an existing class. When you add a new form to your project, C++Builder automatically derives a new form class for you from the TForm class.

At the moment a new form is added to a project, the new form class is identical to the TForm class. Once you add components to it, change properties, and write event handlers, the new form object and the TForm class are no longer the same.

No matter how you customize your bicycle, it can still do all the things you expect a bicycle to do. Likewise, a customized form class still exhibits all the built-in capabilities of a class, and it can still do all the things you expect a form to do, such as change color, resize, close, and so on. That's because the new form object inherits all the data members, properties, methods, and events from the TForm class.

When you add a new form to a C++Builder project, C++Builder creates a new class, TForm1, deriving it from the more generic class, TForm. The first line of the TForm1 class declaration specifies that TForm1 is derived from TForm:

class TForm1: public TForm;

Because TForm1 is derived from TForm, all the elements that belong to a TForm class automatically become part of the TForm1 class. If you look up TForm in online Help (you can click the form itself and press F1), you see lists of all the properties, methods, and events in the TForm class. You can use all the elements inherited from TForm in your application. Only the elements you specifically add to your TForm1 class, such as components you place on the form or event handlers (methods) you write to respond to events, appear in the TForm1 class declaration. These are the things that make TForm1 different from TForm.

The more broad-based or generic class from which another more customized object inherits data and code is called the ancestor of the customized class. The customized class itself is a descendant of its ancestor. A VCL-based class can have only one immediate ancestor, but it can have many descendants. For example, TForm is the ancestor type of TForm1, and TForm1 is a descendant of TForm. All form classes are descendants of TForm, and you can derive many form classes from TForm.

Inheriting from TForm

To read these topics in sequence, press the >> button.


Objects, components, and controls

See also

When you look up TForm in online Help, you'll notice that TForm is called a component. Don't let this confuse you. All components and controls are also classes. The terminology used in the documentation comes from the inheritance hierarchy of the C++Builder Visual Component Library. The following figure is a greatly simplified diagram of the hierarchy, omitting some intermediary objects. To see a more complete diagram, refer to the Component Writer's Guide.

A simplified hierarchy diagram

Everything in this hierarchy is a class. Components, which inherit data and code from a TObject, are classes with additional properties, methods, and events that make them suitable for specialized purposes, such as the ability to save their state to a file. Controls, which inherit data and code from a TComponent type (which in turn inherits elements from TObject) have additional specialized capabilities, such as the ability to display something. So controls are components and classes, and components are classes but not necessarily controls. And an object is an instance of a class. This section refers to all components and controls as classes.

Even though TCheckBox isn't an immediate descendant of TObject, it still has all the attributes of TObject because TCheckBox is ultimately derived from TObject in the VCL hierarchy. TCheckBox is a very specialized kind of class that inherits all the functionality of TObject, TComponent, and TControl, and defines some unique capabilities of its own.

To read these topics in sequence, press the >> button.


Object scope

See also

An object's scope determines the availability and accessibility of the data members, properties, and methods within that object. Using the earlier bicycle analogy, if you were to add a headlight only to your customized "bicycle object," the headlight would belong to that bicycle and to no other. If, however, the "basic model bicycle object" included a headlight, then all bicycle objects would inherit the presence of a headlight. The headlight could lie either within the scope of the ancestor bicycle object--in which case, a headlight would be a part of all descendant bicycle objects--or within the scope only of the customized bicycle object, and available only to that bicycle.

Likewise, all data members, properties, and methods declared within a class declaration are within the scope of the class, and are available to that class and its descendants.

When you write code in an event handler of an object that refers to properties, methods, or data members of the object itself, you don't need to preface these identifiers with the name of the object variable. For example, if you put a button and an edit box on a new form, you could write this event handler for the OnClick event of the button:

__fastcall TForm1::Button1Click(TObject *Sender);

{

 Color = clFuchsia;

 Edit1->Color = clLime;

}

The first statement colors the form. You could have written the statement like this:

Form1->Color = clFuchsia

It's not necessary, however, to put the Form1 qualifier on the Color property because the Button1Click method is within the scope of the TForm1 object. Any time you are within an object's scope, you can omit the qualifier on all properties, methods, and data members that are part of the object.

The second statement refers to the Color property of a TEdit object. Because you want to access the Color property of the TEdit1 object, not of the TForm1 object, you need to specify the scope of the Color property by including the name of the edit box, so the compiler can determine which Color property you are referring to. If you omit it, the second statement is like the first; the form ends up lime green, and the edit box control remains unchanged when the handler runs.

Because it's necessary to specify the name of the edit box whose Color property you are changing, you might wonder why it's not necessary to specify the name of the form as well. This is unnecessary because the control Edit1 is within the scope of TForm1; it's declared to be a data member of TForm1.

To read these topics in sequence, press the >> button.


Accessing components on another form

See also

If Edit1 were on some other form, you would need to preface the name of the edit box with the name of the form class. For example, if Edit1 were on Form2, it would be a data member in the TForm2 class declaration, and would lie with the scope of Form2. You would write the statement to change the color of the edit box in Form2 from the TForm1::ButtonClick method like this:

Form2->Edit1->Color = clLime;

In the same way, you can also access methods of a component on another form. For example,

Form2->Edit1->Clear();

To give the code of Form1 access to properties, methods, and events of Form2, you need to add Unit2 with an #include statement to Unit1 (assuming the units associated with Form1 and Form2 are named Unit1 and Unit2, respectively). Use File|Include Hdr to add the #include statement.

To read these topics in sequence, press the >> button.


Scope and descendants of a class

See also

The scope of a class extends to all the class's descendants. That means all the data members, properties, methods, and events that are part of TForm are within the scope of TForm1 also, because TForm1 is a descendant of TForm.

To read these topics in sequence, press the >> button.


Overriding a method

See also

You can, however, use the name of a method within an ancestor class to declare a method within a descendent class. This is how you override or hide a method. It is important to understand whether you are overriding, hiding, or overloading a method. You would want to override an existing method if you want the method in the descendent class to the same thing as the method in the ancestor class, but the task is accomplished in another way. In other words, the code that implements the two methods differs.

If you declare a data member in a derived class with the same name as a data member in the base class, the base class member is hidden.

If you declare a function in a derived class with the same name and matching parameters as a virtual function in a base class, the new function will override the base class function (and take its place in the vtable).

If you declare a function in a derived class with the same name but different parameters as a function in the base class, the function will be overloaded (both are in the scope of the derived class).

If you declare a function in a derived class with the same name and matching parameters as a (nonvirtual) function in a base class, the base class function is hidden.

It's not often that you would want to override a method unless you are creating new components. You should be aware that you can do so, though, and that you won't receive any warning or error message from the compiler. You can read more about overriding methods in the Component Writer's Guide.

To read these topics in sequence, press the >> button.


Public and private declarations

See also

When you build an application using the C++Builder environment, you are adding data members and methods to a descendant of TForm. You can also add data members and methods to a class without putting components on a form or filling in event handlers, but by modifying the class declaration directly.

There are private, protected, public, published, and automated declarations in a class. You can add new data members and methods to either the public or private part of a class. Public and private are keywords. When you add a new form to the project, C++Builder begins constructing the new form class. Each new class contains the public and private keywords that mark locations for data members and methods you want to add to the code directly. For example, note the private and public parts in this new form class declaration that so far contains no data members or methods:

class TForm1 : public TForm

{

__published:	// IDE-managed Components

private:	// User declarations

public:	// User declarations

virtual __fastcall TForm1(TComponent* Owner);

};

Use the public part to

Declare data members you want methods in other classes to access

Declare methods you want other classes to access

Declarations in the private part are restricted in their access. If you declare data members or methods to be private, they are unknown and inaccessible outside the class. Use the private part to

Declare data members you want only methods in the same class to access

Declare methods you want only methods in the same class to access

To add data members or methods to a public, private, or protected section, put the data members or method declarations after the appropriate access specifier (public, private, and so on). Here is an example:

class TForm1 : public TForm

{

__published:	// reserved for IDE-managed Components

TEdit *Edit1;

TButton *Button1;

void __fastcall Button1Click(TObject *Sender);

private:	// User declarations

int Number;

   	int Calculate (int X, int Y);

public:	// User declarations

virtual __fastcall TForm1(TComponent* Owner);

   	void ChangeColor();

};

Place the code that implements the Calculate and ChangeColor methods in the .cpp part of the unit file pair.

The Number data member and Calculate function are declared to be private. Only members within the class can use Number and Calculate. This restriction means that only the form class can use them.

Because the ChangeColor method is declared to be public, code in other units can use it. Such a method call from another unit must include the object name in the call:

Form1->ChangeColor;

The unit making this method call must #include Form1's Unit1 file.

The other declarations listed at the beginning of this section are discussed in further detail in the Programmer's Guide. In brief, the published declaration is reserved for the IDE -managed components and has the same scope as public. The IDE uses this section to maintain the component and event handlers for the form. Published properties display in the Object Inspector. Automated declarations cause automation type information to be generated for the method property and also have the same scope as public. This automation information makes it possible to create OLE Automation Servers. Protected declarations can only be seen by the current class or its descendants.

To read these topics in sequence, press the >> button.


Accessing object data members and methods

See also

To change the value of an object's property that is a data member in the form object, or call a method of an object that is a data member in the form object, you must include the name of that object in the property name or method call. For example, if your form has an edit box control on it and you want to change the value of its Text property, you should write the assignment statement something like this, making sure to specify the name of the edit box (in this example, Edit1):

Edit1->Text = 'Frank Borland was here';

Likewise, if you want to clear the text selected in the edit box control, you would write the call to the ClearSelection method like this:

Edit1->ClearSelection();

To read these topics in sequence, press the >> button.


Assigning values to object variables

See also

You can assign one object pointer variable to another object pointer variable if the variables are of the same type or assignment compatible, just as you can assign variables of any type other than objects to variables of the same type or assignment-compatible types. For example, if the variables Form1 and Form2 have been declared as pointers to TForm, you could assign Form1 to Form2:

Form2 = Form1;

You can also assign an object pointer variable to another object pointer variable if the type of the variable you are assigning a value to is an ancestor of the type of the variable being assigned. For example, here is a TDataForm class declaration:

class TTDataForm : public TForm

{

__published:	// IDE-managed Components

TButton *Button1;

TEdit *Edit1;

TDBGrid *DBGrid1;

TDatabase *Database1;

private:	// User declarations

public:	// User declarations

virtual __fastcall TTDataForm(TComponent* Owner);

};

Here are the declarations of two objects; one of type TForm, and one of type TDataForm:

TDataForm *DataForm;

TForm *AForm;

AForm is of type pointer to TForm, and DataForm is of type pointer to TDataForm. Because TDataForm is a descendant of TForm, this assignment statement is legal:

AForm = DataForm;

You might wonder why this is important. Taking a look at what happens behind the scenes when your application calls an event handler shows you why.

Suppose you write an event handler for the OnClick event of a button. When the button is clicked, the event handler for the OnClick event is called.

Each event handler has a Sender parameter of type pointer to TObject. For example, note the Sender parameter in this empty Button1Click handler:

void __fastcall TForm1::Button1Click(TObject *Sender)

{

}

If you look back at "A simplified hierarchy diagram", you'll recall that TObject is at the top of the C++Builder Visual Component Library. That means that all C++Builder objects are descendants of TObject. Because Sender is of type TObject, any object can be assigned to Sender. Although you don't see the code that makes the assignment, the component or control to which the event happened is assigned to Sender. This means the value of Sender is always the control or component that responds to the event that occurred.

How is this information useful? You can test Sender to find the type of component or control that called the event handler. For example:

if (typeid(*Sender) == typeid(TEdit))

  DoSomething;

else

  DoSomethingElse;

To read these topics in sequence, press the >> button.


Creating nonvisual objects

See also

Most of the objects you use in C++Builder are components you can see at both design time and runtime, such as edit boxes and string grids. A few, such as common dialog boxes, are components you see only at runtime. Still others, such as timers and data source components, never have any visual representation in your application at runtime, but are there for your application to use.

Occasionally you might want to create your own nonvisual objects for your application. For example, you might want to create a TEmployee object that contains Name, Title, and HourlyPayRate data members. You could then add a CalculatePay method that uses the data in the HourlyPayRate data member to compute a paycheck amount for a given period.

The TEmployee class declaration could look like this:

class TEmployee : public TObject

{

private:

   	char Name[25];

       char Title[25];

       double HourlyRate;

   public:

   	double CalculatePayAmount();

TEmployee();

};

In this case, TEmployee is derived from TObject. TEmployee contains three data members and one method. Because it is derived from TObject, TEmployee also contains all methods of TObject (TObject has no data members).

Place class declarations you create without the help of C++Builder in the class declaration part of your unit (.h header file) along with the form class declaration. In the variable declaration part of the unit (the .cpp file), you usually need to declare a variable of the new type:

 TEmployee *Employee;

To read these topics in sequence, press the >> button.


Creating an instance of an object

See also

TEmployee is just a class. An actual object doesn't exist in memory until the object is instantiated, or created, by operator new (which calls the class constructor). A constructor is a method that allocates memory for the new object and points to the new object, which is called an instance of the class.

If you want to declare an instance of the TEmployee object, your code must call TEmployee::TEmployee before you can access any of the data members of the object:

Employee = new TEmployee;

Now you are ready to access the data members of an Employee object, just as you would any other C++Builder object.

To read these topics in sequence, press the >> button.


Destroying your object

See also

When you are through using an object, you should destroy it, which releases the memory the object used. You destroy an object by calling the delete operator (which calls the class destructor, a method that releases the memory allocated to the object).

To destroy the Employee object when you have finished using it, you would make this call:

delete Employee;

To follow good programming practices, you should place your destructor call in the catch part of a try..catch block, while placing the code that uses the object in the try part. This assures that the memory allocated for your object is released even if an exception occurs while your code is attempting to use the object.

To read these topics in sequence, press the << button.


Text controls

See also

Many applications require the user to enter text or need to present text to the user. The type of control used to hold the information depends on the size and format of the information.

Use this component:	When you want users to do this:
Edit	Edit a single line of text.
Memo	Edit multiple lines of text.
MaskEdit	Adhere to a particular format, such as a nine-digit postal code or a phone number. See the Library Reference or online Help for the special characters to use in constructing a mask.
RichEdit	Edit unlimited lines of text or use rich text format.
Properties common to all text controls

All of the text controls have these properties in common:

Text determines the text that appears within an edit box or memo control.

CharCase forces the case of the text being entered to lowercase, mixed case or uppercase.

ReadOnly specifies whether the user is restricted from making changes. By default all edit controls are editable.

MaxLength limits the number of characters in an edit box.

PasswordChar hides the text the user types by assigning a single character. PasswordChar is most often used to show asterisks instead of a user's password.

HideSelection specifies whether selected text will remain highlighted when the control does not have focus.

Properties shared by memo and rich text controls

In addition to the properties common to all text controls, memos and rich text controls have several other properties in common with each other:

Alignment specifies how text is aligned (left, right, or center) within the component.

Lines contains the text of a memo or rich edit component as a list of strings.

OEMConvert determines whether the text in the control is converted to OEM characters. If true, the text is converted. Otherwise, the characters remain as ANSI characters.

WordWrap determines whether the text will wrap at the right margin.

WantReturns determines whether return characters the user enters in the memo or rich edit components by pressing Enter affect the text in the control or go to the form. If WantReturns is true and the user presses Enter, a return character is entered in the memo or rich edit component. Otherwise, the return goes to the form.

Set WantTabs property to true to enable users to type tabs in a memo control.

Memo controls

A memo control handles text much like an edit-box component, but the memo component can handle multiple text lines.

The text in the memo is the value of the Text property. Your application can tell if the text changes by checking the Modified property.

To have the text in a memo automatically selected whenever it becomes the active control, set the AutoSelect property to true.

At runtime, you can select all the text in the memo with the SelectAll method.

To find out which text in the memo the user has selected, or to replace selected text, use the SelText property.

To select only part of the text or to find out what part of the text is selected, use the SelStart and SelLength properties.

Rich text controls

The rich text component is a memo control that supports rich text formatting. That is, you can change the formatting of individual characters, words, or paragraphs. It includes a Paragraphs property that contains information on paragraph formatting. Rich text controls also have printing and text-searching capabilities.

By default, the rich text editor supports

Font properties, such as typeface, size, color, bold, and italic format

Format properties, such as alignment, tabs, indents, and numbering

Automatic drag-and-drop of selected text

Display in both rich text and plain text formats. Set PlainText to true to remove formatting.


Specialized input controls

The following components provide additional ways of capturing input:

Use this component:	When you want users to do this:
ScrollBar	Select values on a continuous range
TrackBar	Select values on a continuous range (more visually effective than a scroll bar)
UpDown	Select a value from a spinner attached to an edit component
HotKey	Enter Ctrl/Shift/Alt keyboard sequences
Splitter	Resize controls that are aligned
Scroll bars

The scroll bar component is a Windows scroll bar, used to scroll the contents of a window, form, or control. In the OnScroll event handler, you write code that determines how the window, form, or control behaves in response to the user scrolling the scroll bar.

LargeChange determines how far a thumb tab moves when the user clicks the scroll bar on either side of the thumb tab.

SmallChange determines how far the thumb tab moves when the user clicks the arrows at the end of the scroll bar to scroll or uses the arrow keys on the keyboard. The default value is 1.

Min and Max property values together determine how many positions are available on the scroll bar for the thumb tab to move when the user scrolls the scroll bar.

Your application can set the position of the thumb tab with the Position property, or use the property to determine how far the scroll bar has scrolled.

Track bar controls

The track bar can set or adjust integer values on a continuous range, such as volume or brightness. A track bar consists of a bar that defines the extent or range of the adjustment, and an indicator that both shows the current value for the control and provides the means for changing the value.

The user moves the slide indicator by dragging to a particular location or clicking in the hot zone area of the bar, which moves the slide indicator directly to that location.

Use the Max and Min properties to set the upper and lower range of the track bar.

Use SelEnd and SelStart to highlight a selection range. See the following figure.

By default, a track bar has one row of ticks along the bottom. Set the TickMarks property to tmNone to remove them, or tmBoth to put ticks on both the top and bottom. See the following figure.

You can build either a horizontal or vertical track bar with the Orientation property.

TickStyle controls automatic or manual tickstyle.

Position sets a default position for the track bar, it also tracks the value the user has selected at runtime.

By default, users can move one tickmark up or down by pressing the up and down arrow keys. Set LineSize to change that increment.

Set PageSize to determine the number of ticks moved when the user presses Page Up and Page Down.

Up-down controls

Up-down controls are text boxes that accept a limited set of discrete ordered input values that make up a circular loop. An up-down control is a combination of a text box and a special control that incorporates a pair of buttons, it is similar to the spin button.

When the user clicks the text box or the buttons, the input focus is set to the text box of the control. The user can type a value directly into the control or use the buttons to increment or decrement the value.

Use Associate to attach the up-down control to a text control.

Use the AlignButton property to place the up-down component to the left or right of its associated text control.

To switch the orientation from vertical to horizontal, set Orientation to horizontal.

Use Max and Min to set limits on the values the up-down control can have.

By default, you can use the arrow keys to increment and decrement the up-down control. To disable keyboard interaction, set ArrowKeys to false.

The Position property holds the value as the control moves up or down. Use Position to set the default value at design time.

When the value of an up-down control is over 1000, it automatically places a separator between every three digits. To remove the separator, set Thousands to false.

By default, an up-down control stops at its maximum value. If you want the control to move back to the minimum value when it reaches the maximum, set Wrap to true.

Hot key controls

Use the hot key component to assign a hot-key sequence to transfer focus to any component. The HotKey property contains the current key combination of the hot-key control. Alt+A is the default. To modify the value of the HotKey property either edit it directly or set the value of the Modifiers property.

The Modifiers property allows selection of one or more modifier keys such as Ctrl, Alt , Extra, or Shift for the hot key. Modifier keys are used in combination with another non-modifier key such as characters, function keys, or arrow keys.

The InvalidKeys property allows the user to specify that one or more modifier keys should be considered invalid. If this property is set a default modifier should also be specified in the Modifiers property.

Splitter control

Add a splitter to a form between two aligned controls to allow users to resize the controls. The splitter sits between a control aligned to one of the edges of the form and the controls that fill up the rest of the client area. Give the splitter the same alignment as the control that is anchored to the edge of the form.

Use each control on the form as a separate pane. After each pane is placed, place a splitter with the same alignment to allow that pane to be resized. The last pane you place on the form should be client-aligned, so that it resizes automatically to fill up the remaining space after all other panes are resized.

Set MinSize to specify a minimum size the splitter must leave when resizing its neighboring control.

Set Beveled to true to give the splitter's edge a 3D beveled look.


Buttons and similar controls

Aside from menus, buttons provide the most common way to invoke a command in an application.  There are several variations of the standard text-based button:

Use this component:	To do this:
Button	Present command choices
BitBtn	Present command choices on buttons with glyphs
SpeedButton	Create tool bar buttons
CheckBox	Present Boolean options
RadioButton	Present a set of mutually exclusive choices
ToolBar	Arrange tool buttons and other controls in rows and automatically adjust their sizes and positions.
CoolBar	Display a collection of windowed controls within movable, resizable bands
Button controls

A button component is a push button control. Users choose button controls to initiate actions. Double-clicking a button at design time takes you to the button's OnClick event handler in the Code editor.

Set Cancel to true if you want the button to trigger its OnClick event when the user presses Esc.

Set Default to true if you want the Enter key to trigger the button's OnClick event. Enter triggers OnClick even if another control has focus.

Bitmap buttons

A bitmap button component is a push button control that can include a bitmap on its face. You can choose from predefined bitmap button styles or specify your own bitmap.

To choose a custom bitmap for your button, set the Glyph property.

Use Kind to automatically configure a button with a glyph and default behavior. See the Kind property for a table of possibilities.

By default, the glyph is to the left of any text. To move it, use the Layout property.

The glyph and text are automatically centered in the button. To move their position, use the Margin property. Margin determines the number of pixels between the edge of the image and the edge of the button.

By default, the image and the text are separated by 4 pixels. Use Spacing to increase or decrease the distance.

Bitmap buttons can have 3 states: up, down, and held down. Set the NumGlyphs property to 3 to show a different bitmap for each state.

Speed buttons

Speed button components are buttons that usually have graphical images on their faces that execute commands or set modes. They have some unique capabilities that allow them to work as a set. Speed buttons are commonly used with panels to create tool bars.

By default, speed buttons appear in an up (unselected) state.  To initially display a speed button as selected, set the Down property to true.

If AllowAllUp is true, all of the speed buttons in a group can be unselected, or "up" state.  Set AllowAllUp to false if you want a group of buttons to act like a radio group.

To make speedbuttons act as a group, give the GroupIndex property of all the buttons the same non-zero value.

Adding speed buttons to tool bars is discussed in "Designing toolbars and cool bars."

Check boxes

A check box lets the user make a binary decision like yes/no, male/female.

Set Checked to true and a check mark appears in the check box, indicating the option is selected.

The value of the AllowGrayed property determines if a check box can have two or three possible states. If AllowGrayed is false, the default value, clicking a check box alternately checks and unchecks it. If AllowGrayed is true, clicking a check box either checks, grays, or unchecks it.

The State property determines the various states a check box control can have. cbUnchecked: the check box has no check mark indicating the user hasn't selected the option.  cbChecked: the check box has a check mark in it indicating the user has selected the option, cbGrayed: the check box is gray indicating a third state that is neither checked nor unchecked. Your application determines the meaning of a grayed check box.

RadioButton

Radio buttons present a set of mutually exclusive choices. You can use the radio button component to place individual buttons, or use the radio group component to set a rectangular region with a Caption property, and list your radio-button items using the Items property. See "Grouping components"for more information.

Use the Caption property to set a value for the radio button.

When Checked is true, a black circle appears in the radio button, indicating that the option is selected.

Tool bars

Tool bars provide an easy way to arrange and manage visual controls. You can create a tool bar out of a panel component and speed buttons, or you can use the ToolBar component, then choose New Button from its SpeedMenu for each button you want. Using the last way has these advantages:

All tool buttons on a tool bar maintain a uniform width and height.

Other controls you place on the tool bar are held in place by invisible tool buttons and maintain a uniform height.

Controls can automatically wrap around and start a new row when they do not fit horizontally on the tool bar.

Spaces and dividers (which are specially configured tool buttons) can group controls on the tool bar.

You have added display options, such as pop-up borders and transparency.

Adding a tool bar to a form is discussed in "Designing toolbars and cool bars."

Cool bars

A cool bar contains child controls that can be moved and resized independently. Each control resides on an individual band. The user positions the controls by dragging the sizing grip to the left of each band.

The cool bar requires version 4.70 or later of COMCTL32.DLL (usually located in the WINDOWS\SYSTEM or WINDOWS\SYSTEM32 directory) at both design time and runtime.

The Bands property holds a collection of TCoolBand objects. At design time, you can add, remove, or modify bands with the Bands editor. To open the Bands editor, select the Bands property in the Object Inspector, then double-click in the Value column to the right, or click the ellipsis (...) button. You can also create bands simply by adding new windowed controls from the palette.

You can specify if a user can reorder the bands by seting the FixedOrder property to true or false.

Specify if the bands automatically maintain a uniform height or width with the FixedSize property.


Handling lists

Lists present the user with a collection of items to select from.  Several components display lists:

Use this component:	To do this:
ListBox	Display a list of text strings. The user may select one or more.
ComboBox	Display a collapsible list of text strings. This component conserves form space.
TreeView	Display items hierarchically.
ListView	Display items graphically.
ImageList	Manage a list of images.
CheckListBox	Display a list with check boxes in front of each item
DateTimePicker	Display a list box for entering dates or times
Properties common to list controls

The following properties are common to the display of list controls:

Columns specifies the number of columns in a list control.

IntegralHeight specifies whether the list box shows only entries that fit completely in the vertical space.  If IntegralHeight is false, the bottom of the list box is at the location determined by its ItemHeight property, and the bottom item visible in the list might not be complete.

ItemHeight specifies the height of a list item in pixels.  The Style property can cause ItemHeight to be ignored.

The following properties are common to the control of lists:

Items uses a string list to fill the list control with values. See "Working with string lists" for information on how to use string lists.

ItemIndex indicates which item in the list is selected.

MultiSelect specifies whether a user can select more than one item at a time. The user can then use the Ctrl key to select multiple noncontiguous items, or the Shift key to select a range of items.

Sorted determines whether the list will be sorted in alphabetical order.

List boxes

A list box displays a list from which users can select one or more items. The following properties are key to using a list box.

You can add, delete, and insert items in the list box using the Add, Delete, and Insert methods of the Items property, which is a string list.

When MultiSelect is set to true, users can select more than one item. By default, the multiselect process for list boxes is to click on individual items with the Ctrl key pressed. Holding down the Shift key has no effect. To activate Shift to select a range of values, set both MultiSelect and ExtendedSelect to true.

The Style property determines how a list box displays its items. By default, Style is lbStandard, meaning that the list box displays each item as a string. By changing the value of Style, you can create owner-draw list boxes, meaning that items can be graphical and of either fixed or varying height.

For a discussion of implementing owner-draw controls in your application, see Adding graphics to controls

Combo boxes

A combo box component is a control that combines an edit box with a list much like that of a list box. Users can either type text in the edit box or select an item from the list.

When users enter data into the combo box, either by typing text or selecting an item from the list, the value of the Text property changes.

By default, the drop-down list will display eight items. To increase or decrease displayed items, assign DropDownCount a new value.

Combo boxes have five different styles. Use the Style property to select the type of combo box you need:

Use csDropdown if you want a list of values like a list box but don't want to see the list of values until the user pushes the button. By default the text area will be editable.

Use csDropDownList style to make the combo box edit region read-only. The user can't edit an item or type in a new item, but can select items from the list.

csSimple to create a combo box with a fixed size list that does not close up.

Tree views

A tree view control is a special list box control that displays a set of objects as an indented outline based on their logical hierarchical relationship. The control includes buttons that allow the outline to be expanded and collapsed. You can use a tree view to display the relationship between a set of containers or other hierarchical elements.

You can optionally include icons with the text label of each item in the tree. Different icons can be displayed when the user expands or collapses the item in the tree. In addition, you can also include a graphic, such as a check box, that can be used to reflect state information about the item.

The control also supports drawing lines that define the hierarchical relationship of the items in the list and buttons for expanding and collapsing the outline.

Indent sets the number of pixels horizontally separating items from their parents.

Set ShowButtons to false to remove the '+' button that indicates the item can be expanded.

Set ShowLines to false to remove the connecting lines of the tree view.

Set ShowRoot to false to remove the lines connecting the root (top level) items.

DateTimePicker

DateTimePicker displays a list box for entering dates or times. To use DateTimePicker, you must have the latest version of COMCTL32.DLL (usually located in the WINDOWS\SYSTEM or WINDOWS\SYSTEM32 directory).


Grouping components

It is much easier for users to navigate through an application when the information is presented in groups.  C++Builder provides several components that can be used to group information:

Use this component:	When you want this:
GroupBox	A standard group box with a title
RadioGroup	A simple group of radio buttons
Panel	A more visually flexible group of controls
ScrollBox	A scrollable region containing controls
TabControl	A set of mutually-exclusive notebook-style tabs
PageControl	A set of mutually-exclusive notebook-style tabs with corresponding pages, each of which may contain other controls
HeaderControl	To provide titles for columns of data
Group boxes

The group box component is a standard Windows group box. Use a group box component to group related controls on a form. The most commonly grouped controls in a group box are radio buttons.

Place the group box on the form, then select the components you want to appear in the group box from the Component palette, and place them in the group box.

The text that identifies the grouping appears as the value of the Caption property.

Radio groups

The radio group component simplifies the task of grouping radio buttons and getting them to work together. The radio group gives you a rectangular region with a Caption property.

Use the Items property of the radio group component to specify the choices in the box: click the ellipsis (...) button in the Value column on the Properties page of the Object Inspector to open the String List editor. Type the strings you want to appear next to the radio buttons, and press Enter.

You cannot select individual radio buttons in a radio group component. To respace the buttons, reize the radio group component. To edit their names, use the String List editor.

Panels

The panel component is used to place panels on a form on which other controls can be placed. For example, you can create a panel which is a tool bar. Panels are containers. Use a bevels component instead for purely visual effects.

Panels can be aligned with the form so that they maintain the same relative position to the form even when the form is resized.

The BorderWidth property determines the width in pixels of the border around a panel. The default value is 0, which means no border.

The Locked property determines whether a panel is replaced by an in-place active OLE object. If Locked is false, the OLE server can replace the panel. If Locked is true and the panel is aligned to one of the edges of the form, then the panel remains when an OLE object in an OLE container component is activated in place.  Use Locked to prevent status bars and the like from being replaced.

Page controls

The page control component is a page set that is used to make a multiple-page dialog box. To create a new page in a page control at design time, right-click the page control and choose New Page.

The ActivePage property specifies the active tab sheet object.

Set Multiline to true to allow multiple lines.

PageCount specifies the number of pages.

Pages gives you access to the pages of the tab sheet object.

TabHeight property sets the height in pixels of the tabs. TabWidth is the horizontal size in pixels of the individual tabs. If zero, TabWidth tabs will automatically size themselves to fit their text.

Tab controls

The tab control component has the appearance of notebook dividers.  To create a multiple page dialog box, use a page control.

Scroll boxes

Scroll box components make it possible to create scrolling areas on a form that are smaller than the entire form. The are many times when an application needs to display more information than will fit in a particular area. Some controls, such as list boxes and memos can automatically scroll their contents. But other controls, and sometimes even forms full of controls, need to be able to scroll. C++Builder handles these scrolling regions with a control called a scroll box.

A scroll box is much like a panel or a group box, in that it can contain other controls, but a scroll box is normally invisible. However, if the controls contained in the scroll box cannot all fit in the visible area of the scroll box, it automatically displays one or two scroll bars, enabling users to move controls outside the visible region into position where they can be seen and used.

Set the boundaries of the scroll-box to the region you want to scroll.

Use the Kind property to determine whether a scroll box has horizontal or vertical scroll bars.

You can use the Align property of a scroll box to allow the scroll box to adjust its area to a form or a part of a form

Header controls

The header component is a sectioned visual control that displays text and allows each section to be resized with the mouse. At design time, resize a section by clicking the mouse button on a section border and dragging to the new size. At runtime, the user can resize the header by clicking and dragging with the left mouse button. The widths of the other sections that are not resized remain unchanged.

Use the Sections property to specify the separate sections in a header.

The control also supports the user dragging on the divisions that separate header parts to set the width of each column. As an option, you can support double-clicking on a division as a shortcut to a command that applies to formatting the column, such as automatically sizing the column to the largest value in that column.


Visual feedback

Well-designed applications provide users with information pertaining to the current state of the application.  This information is conveyed using the following components:

Use this component or property:	To do this:
Label	Display non-editable text strings
ProgressBar	Display the percentage of work remaining for a particular task
StatusBar	Display a non-editable status region at the bottom of a window
StaticText	Display non-editable text in a component that has a window handle
Hint and ShowHint	Activate fly-by of "tool-tip" help
HelpContext	Link in online help systems
Labels

The label component displays text on a form. Usually labels are placed adjacent to edit boxes or other controls. The label is a nonwindowed control, so it cannot receive focus.

Caption contains the text string for the label.

The FocusControl links the label control with another control on the form. If the caption of a label includes an accelerator key, the control specified in the FocusControl property becomes the focused control when the user uses the accelerator key.

If you want a label to appear on top of a graphic, but you want to be able to see through the label so that part of the graphic/bitmap isn't hidden, set the Transparent property to true.

The ShowAccelChar property determines how an ampersand (&) in the caption of a label appears. If ShowAccelChar is true, an ampersand appears as an underline under the character to its right in the caption indicating the underlined character is an accelerator character. Otherwise, the ampersand character appears as an ampersand.

Progress bars

A progress bar is a control you can use to show the percentage of completion of a lengthy operation. It consists of a rectangular bar that "fills" from left to right. Use the control as feedback for long operations or background processes.

Use Position to set a default position for the progress bar. At runtime, Position tracks the exact location as values increment.

Use Max and Min to set the range of Position.

By default, the progress meter will advance by a value of one. Assign StepBy a higher number to increase the increments. See the StepIt method in online Help for more information.


Status bars

A status bar usually occupies the bottom of a window and usually displays text. Although you can use C++Builder's panel component to make a status bar, it is simpler to use the Windows status-bar component. You will generally subdivide the status bar into multiple text areas.

The status-bar component automatically has its Align property set to alBottom, which takes care of both positioning and size.

To create subpanels in the status bar component, use the Panels property: in the Values column of the Object Inspector, click the ellipsis (..) button to open the Panels editor.

Set each panel's Width property while the Panels editor is open and a panel is selected in the Panels editor. Set Alignment and other properties at this time, as well.

Add code to the individual status panels to reflect the status of the application.

Help or hint properties for a component

The following properties are common to all controls that show help and hints:

Hint is the text string that can appear when the user moves the mouse pointer over a control or menu item. To make the hint appear when the user moves the mouse over the component, set ShowHint to true.

ParentShowHint quickly shows all defined hints for controls in a group. Like the parent properties for font and color, ParentShowHint determines where a control looks to find out if hints should be shown.

HelpContext establishes a Help context number for the control.


Tabular display

Grids consist of a set of rows and columns that define a collection of cells.  What appears in each of the cells depends on the application and the type of grid control used:

Use this component:	To do this:
DrawGrid	Display an existing data structure in a grid
StringGrid	Display a grid of text strings
DBGrid	Display the contents of a dataset
Draw grids

A draw grid component is a grid control that permits the display of an existing data structure in column and row format.

The grid uses the OnDrawCell event to fill in the cells of the grid. If the DefaultDrawing property is false, the code you write in the OnDrawCell event handler draws in the cells. If DefaultDrawing is true, the contents of the cells are automatically drawn using some default values.

You can obtain the drawing area of a cell with the CellRect method. The MouseToCell method returns the column and row coordinates of the cell the mouse cursor is in.

You can determine which cell is selected in the grid by checking the value of the Selection property.

You can change the appearance and behavior of a data grid by changing the value of the Options property. For example, you can choose to allow the user to use the Tab key to move to a new column, you can decide to display grid lines between columns but not between rows, or let the user edit the data displayed in the grid.

Several properties affect the appearance of the grid. The DefaultColWidth and DefaultRowHeight properties determine the default widths and heights of the columns and rows.

You can change the width or height of a specific column or row with the ColWidths and RowHeights properties. You can choose to have fixed or nonscrolling columns and rows with the FixedCols and FixedRows properties, and you can assign the color of the fixed columns and rows with the FixedColor property. Set the width of the grid lines with the GridLineWidth property. Add scroll bars to the grid with the ScrollBars property.

You can determine which row is currently the top row in the grid, or set a specified row to be the top row with the TopRow property. To determine which column is the first visible column in the grid, use the LeftCol property. The values of the VisibleColCount and VisibleRowCount properties are the number of columns and rows visible in the grid.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.

String grids

The string grid component is a grid control designed to simplify the handling of strings and associated objects while maintaining all the features of the draw grid component.

All the strings in a string grid are contained in the Cells property, which you can use to access a particular string within the grid. All the objects associated with the strings in a string grid are contained in the Objects property.

All the strings and their associated objects for a particular column can be accessed using the Cols property. The Rows property gives you access to all the strings and their associated objects for a particular row.

In addition to these properties, methods, and events, this component also has the properties, methods, and events that apply to all windowed controls.


Graphic display

Graphics, when used appropriately, can add that extra bit of flash and style which makes an application stand out.  To incorporate graphics into your C++Builder applications use the following components:

Use this component	To do this:
Image	Display the contents of a graphics file
Shape	Display a geometric shape
Bevel	Display 3D lines and frames
PaintBox	Programmatically display graphics
Animate	Silently display an AVI file
Images

The image component displays a graphical image, like a bitmap, icon, or metafile on a form. C++Builder includes a library of images to choose from in the IMAGES subdirectories. Use the following properties to set up the image component.

Select an image to display by clicking on the Picture property.

By default, any image is centered in the Image component, to align the image to the upper left corner, change Center to false.

To make the image shrink or grow with the border, change Stretch to true.

Shapes

The shape component displays a geometric shape on the form. It is a nonwindowed component and cannot receive user input.

You determine which geometric shape the shape control assumes by setting the Shape property.

To change the color of the border, use BorderColor.

To change the color of the shape or to add a pattern, use the Brush property to fill it. How the shape is painted depends on the two nested properties of the Brush object, Color and Style.

Bevels

The bevel component lets you put beveled lines, boxes, or frames on the forms in your application.

A panel component has two bevels, an outer bevel drawn next to the border of the control, and an inner bevel drawn inside the outer bevel. Use BevelInner and BevelOuter to determine the style of the bevel:  none, raised, or lowered.

The BevelWidth property determines the width in pixels between the inner and the outer bevels of a panel.

Paint boxes

The paint box component provides a way for your application to draw on the form using code in a specified rectangular area. It prevents drawing outside the boundaries of the paint box. Once a paint box is added to your form, your application can use the OnPaint event handler to draw on the paint box's Canvas.

For information on how to draw on a canvas, see "Using Canvas methods to draw graphic objects."

Animation control

The animation component is a window that silently displays an Audio Video Interleaved (AVI) clip. An AVI clip is a series of bitmap frames, like a movie. Although AVI clips can have sound, animation controls work only with silent AVI clips. The files you use must be either uncompressed AVI files or AVI clips compresed using run-length encoding (RLE). These are some of the properties of an animation component:

ResHandle is the Windows handle for the module that contains the AVI clip as a resource. Set ResHandle at runtime to the instance handle or module handle of the module that includes the animation resource. After setting ResHandle, set the ResID or ResName property to specify which resource in the indicated module is the AVI clip that should be displayed by the animation control.

Set AutoSize to true to have the animation control adjust its size to the size of the frames in the AVI clip.

StartFrame and StopFrame specify in which frames to start and stop the clip.

You can set CommonAVI to display one of the common Windows AVI clips provided in Shell32.DLL.

Specify when to start and interrupt the animation by setting the Active property to true and false, respectively, and how many repetitions to play by setting the Repetitions property.

The Timers property lets you display the frames using a timer. This is useful for synchronizing the animation sequence with other actions, such as playing a sound track.


Windows common dialog boxes

The dialog box components on the Dialogs page of the Component palette make the Windows "common"dialog boxes available to your C++Builder applications. These dialog boxes provide all Windows-based applications with a familiar, consistent interface that enables the user to perform common file operations such as opening, saving, and printing files.

Each dialog box opens when its Execute method is called. Execute returns a Boolean value: if the user chooses OK to accept any changes made in the dialog box, execute returns true; if the user chooses Cancel to escape from the dialog box without making or saving changes, Execute returns false.


ImageList Editor

Use the ImageList Editor at design time to add bitmaps and icons to a TImageList component. To display the ImageList editor, double-click a TImageList component or right-click it and choose ImageList Editor

Selected Image

Displays information about the image selected in Images. Controls in this group are grayed if there are no images available or the selected image was added in a previous use of the editor.

Transparent Color

Determines which color is used to create a mask for drawing the image transparently. The default transparent color is the color of the bitmap's left-most pixel in the bottom line. Transparent Color is set to clNone for an icon image (icons are already masked).

Fill Color

Used when an image is smaller than the TImageList component to specify what color the empty area of the image is filled with when it is cropped or centered. Fill Color is set to clNone for an icon image.

Options

Specifies how to adjust a newly added bitmap image whose width or height don't match the imagelist's width or height. (Disabled for icons.)

Setting	Description

Crop	Displays the section of the image beginning at the top-left, extending the imagelist width and height towards the bottom-right (default)

Stretch	Causes the entire image to stretch so that it fits the imagelist width and height

Center	Centers the image within the imagelist width and height. If the image width or height is larger than the imagelist width or height, the image may be clipped.

Images

Contains a preview list view of all the images in the imagelist, and controls for adding or deleting images from the list. Each image is displayed within a 24x24 area for easier viewing of multiple images. Beneath each image is a caption that indicates the zero-based position of the image within the imagelist. You can edit the caption to change an images position in the list or drag the image to its new position.

Add

Displays the Add Images dialog box, which lets you select one or more bitmaps or icons to add to the imagelist. The images then appear highlighted in the preview list view and their captions are assigned sequential values in the imagelist.

If a bitmap is larger than the imagelist width or height by even increments, a prompt appears asking whether the ImageList editor should divide the bitmap into several images. This is useful for toolbar bitmaps, which are usually composed of several small images in a sequence and stored as one larger bitmap.

Delete

Removes the selected images from the imagelist. All images left after clicking Delete will be repositioned to be a contiguous zero-based list.

Clear

Removes all images from the imagelist.


Menu title area

Menu titles display in this area. Click the highlighted block to add new items to the menu.


Menu command area

Menu commands display in this area. Click the highlighted block to add new menu commands.


System (Visual Studio)

See also

These system keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Action or command

Ctrl+R	Records a keyboard macro

Ctrl+P	Plays back a keyboard macro

F1	Displays context-sensitive Help

F4	Run|Go to Cursor

F5	Run|Run

F7	Project|Build project

F9	Toggle breakpoint

F10	Run|Step over

F11	Run|Trace Into

F12	View|Toggle Form/Unit

Alt+0	View|Window list

Alt+3	View|Debug Windows|Watches

Alt+4	View|Debug Windows|Local Variables

Alt+7	View|Debug Windows|Call Stack

Alt+8	View|Debug Windows|CPU

Alt+F2	View|Debug Windows|CPU

Alt+F5	Run|Inspect

Alt+F7	Project|Options

Alt+F10	Displays a context menu

Alt+F11	File|Include Unit Hdr

Alt+F12	View|Toggle Form/Unit

Alt+Enter	View|Object Inspector

Shift+F5	Run|Program Reset

Shift+F7	Run|Trace To Next Source Line

Shift+F9	Run|Add Watch

Shift+ F11	Project|Add To Project

Shift+ F12	View|Forms

Ctrl+F1	Topic search

Ctrl+F2	Evaluate/modify

Ctrl+F3	View|Debug Windows|Call Stack

Ctrl+F6	Open Source/Header file

Ctrl+F7	Project|Make

Ctrl+F10	Run|Go to Cursor

Ctrl+F12	View|Units

Ctrl+a	Edit|Select All

Ctrl+B	View|Breakpoints

Ctrl+E	View|ClassExplorer

Ctrl+n	File|New

Ctrl+N	File|New Application

Ctrl+o	File|Open

Ctrl+O	File|Open Project

Ctrl+s	File|Save

Ctrl+S	File|Save All

Ctrl+<space bar>	Code Completion pop-up window

Ctrl+Shift+<space bar>	Code Completion pop-up window

Ctrl+Tab	Displays the next page

Ctrl+Shift+Tab	Displays the previous page

Ctrl+Q+W	Displays next error in Message view

Ctrl+Alt+E	View|Debug Windows|Event Log

Ctrl+Alt+M	View|Debug Windows|Modules


Clipboard control (Visual Studio)

See also

These Clipboard keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Command

Ctrl+Ins	Edit|Copy

Shift+Del	Edit|Cut

Shift+Ins	Edit|Paste

Ctrl+C	Edit|Copy

Ctrl+V	Edit|Paste

Ctrl+X	Edit|Cut


Editor (Visual Studio)

See also

These editor keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Action or command

F3	Search|Search Again

Ctrl+F	Search|Find

Ctrl+g	Search|Go to line number

Ctrl+G	Open file at cursor

Ctrl+h	Search|Replace

Ctrl+I	Search|Incremental Search

Ctrl+j	Templates pop-up menu

Ctrl+L	Deletes a line

Ctrl+P	Causes next character to be interpreted as an ASCII sequence

Ctrl+s	File|Save

Ctrl+T	Deletes the word to the left of the cursor

Ctrl+y	Deletes a line

Ctrl+Y	Deletes to the end of a line

Ctrl+z	Edit|Undo

Ctrl+Z	Edit|Redo

Ctrl+Tab	Displays the next window in the buffer list

Ctrl+Shift+Tab	Displays the previous window in the buffer list

Ctrl+F4	Closes the current page

Ctrl+K+E	Converts the word under the cursor to lower case

Ctrl+K+F	Converts the word under the cursor to upper case

Ctrl+Q+A	Search|Replace

Ctrl+Q+F	Search|Find

Ctrl+Q+Y	Deletes to the end of a line

Ctrl+Q+[	Finds the matching delimiter (forward)

Ctrl+Q+Ctrl+[	Finds the matching delimiter (forward)

Ctrl+Q+]	Finds the matching delimiter (backward)

Ctrl+Q+Ctrl+]	Finds the matching delimiter (backward)

Alt+F3	Search|Find

Alt+[	Finds the matching delimiter (forward)

Alt+]	Finds the matching delimiter (backward)

Delete	Deletes a character or block at the cursor

Backspace	Deletes the character to the left of the cursor

Shift+Backspace	Deletes the character to the left of the cursor

Ctrl+Backspace	Deletes the word to the left of the cursor

Tab	Inserts a tab character

Enter	Inserts a new line character

Insert	Toggles insert mode

Shift+Left Arrow	Selects the character to the left of the cursor

Shift+Right Arrow	Selects the character to the right of the cursor

Shift+Up Arrow	Moves the cursor up one line and selects from the left of the starting cursor position

Shift+Down Arrow	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+PgUp	Moves the cursor up one screen and selects from the left of the starting cursor position

Shift+PgDn	Moves the cursor down one line and selects from the right of the starting cursor position

Shift+End 	Selects from the cursor position to the end of the current line

Shift+Home	Selects from the cursor position to the start of the current line

Shift+Space	Inserts a blank space

Shift+Enter	Inserts a new line character

Ctrl+Shift+Left Arrow	Selects the word to the left of the cursor

Ctrl+Shift+Right Arrow	Selects the word to the right of the cursor

Ctrl+Shift+Home	Selects from the cursor position to the start of the current file

Ctrl+Shift+End 	Selects from the cursor position to the end of the current file

Ctrl+Shift+PgDn	Selects from the cursor position to the bottom of the screen

Ctrl+Shift+PgUp	Selects from the cursor position to the top of the screen

Alt+Backspace	Edit|Undo

Alt+Shift+Backspace	Edit|Redo

Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Alt+Shift+Right Arrow	Selects the column to the right of the cursor

Alt+Shift+Up Arrow	Moves the cursor up one line and selects the column from the left of the starting cursor position

Alt+Shift+Down Arrow	Moves the cursor down one line and selects the column from the left of the starting cursor position

Alt+Shift+Page Up	Moves the cursor up one screen and selects the column from the left of the starting cursor position

Alt+Shift+Page Down	Moves the cursor down one line and selects the column from the right of the starting cursor position

Alt+Shift+End	Selects the column from the cursor position to the end of the current line

Alt+Shift+Home	Selects the column from the cursor position to the start of the current line

Ctrl+Alt+Shift+Left Arrow	Selects the column to the left of the cursor

Ctrl+Alt+Shift+Right Arrow	Selects the column to the right of the cursor

Ctrl+Alt+Shift+Home	Selects the column from the cursor position to the start of the current file

Ctrl+Alt+Shift+End	Selects the column from the cursor position to the end of the current file

Ctrl+Alt+Shift+Page Up	Selects the column from the cursor position to the bottom of the screen

Ctrl+Alt+Shift+Page Down	Selects the column from the cursor position to the top of the screen


Block commands (Visual Studio)

See also

These block command keyboard shortcuts apply to the Visual Studio keystroke mapping scheme.

Shortcut	Action or command

Ctrl+K+B	Marks the beginning of a block

Ctrl+K+C	Copies a selected block

Ctrl+K+H	Hides/shows a selected block

Ctrl+K+I	Indents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box

Ctrl+K+K	Marks the end of a block

Ctrl+K+L	Marks the current line as a block

Ctrl+K+N	Changes a block to uppercase

Ctrl+K+O	Changes a block to lowercase

Ctrl+K+P	Prints selected block

Ctrl+K+R	Reads a block from a file

Ctrl+K+T	Marks a word as a block

Ctrl+K+U	Outdents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box.

Ctrl+K+V	Moves a selected block

Ctrl+K+W	Writes a selected block to a file

Ctrl+K+Y	Deletes a selected block

Ctrl+I	Indents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box

Ctrl+U	Outdents a block by the amount specified in the Block Indent combo box on the Editor options page of the Environment Options dialog box.

Ctrl+Del	Deletes a selected block

Ctrl+Q+B	Moves to the beginning of a block

Ctrl+Q+K	Moves to the end of a block


Cursor movement (Visual Studio)

See also

These cursor movement shortcuts apply to the Visual Studio keystroke mappings scheme.

Shortcut	Action

UpArrow	Moves up one line in the same column position

DownArrow	Moves down one line in the same column position

Home	Moves to the start of a line

End	Moves to the end of a line

Left Arrow	Moves one character to the left

Right Arrow	Moves one character to the right

PgDn	Moves down one screen in the current window

PgUp	Moves up one screen in the current window

Shift+Tab 	Moves the cursor to the left one tab position

Ctrl+Left Arrow	Moves one word to the left

Ctrl+Right Arrow	Moves one word to the right

Ctrl+PgDn	Moves to the bottom of the screen

Ctrl+PgUp	Moves to the top of the screen

Ctrl+UpArrow	Scrolls the screen up one line.

Ctrl+DownArrow	Scrolls the screen down one line.

Ctrl+Home	Moves to the top of a file

Ctrl+End 	Moves to the end of a file

Ctrl+Q+B	Moves to the beginning of a block

Ctrl+Q+C	Moves to end of a file

Ctrl+Q+D	Moves to the end of a line

Ctrl+Q+E	Moves to the top of the window

Ctrl+Q+K	Moves to the end of a block

Ctrl+Q+P	Moves to previous position

Ctrl+Q+R	Moves to the beginning of a file

Ctrl+Q+S	Moves to the beginning of a line

Ctrl+Q+T	Moves to the top of the window

Ctrl+Q+U	Moves to the bottom of the window

Ctrl+Q+X	Moves to the bottom of the window


Setting advanced options in C++Builder

See also

Set project options through the Project Options dialog box, reached with the Project|Options menu command. The Project Options dialog box lets you set most options for the C++Builder compilers and linkers.

If there is an option you cant find in the Project Options dialog box, you can try setting options in the project .BPR file.

When you open the Project makefile (by choosing Project|View Makefile), you will see a section that contains the following makefile code:

CFLAG1 = ...

IDLCFLAGS = ...

PFLAGS = ...

RFLAGS = ...

AFLAGS = ...

LFLAGS = ...

These sections contain the option settings for the C++ compiler, the Object Pascal compiler, the resource compiler, and the linkers.

To set advanced C++ compiler options, add the command-line switch of the desired option to the CFLAG1 line. Use the PFLAGS line for Object Pascal compiler options. The RFLAGS line contains resource compiler options. The LFLAGS line sets linker options.

Compiler and linker options

The C++Builder compiler and linker options are grouped into the following areas:

Compiler-specific options

C++-specific options

Optimization options

Warning message options

Linker options

Option listings

For a complete listing of the compiler and linker options, refer to the following charts:

Compiler options (alphabetical listing)

Compiler options (functional listing)

Linker options (alphabetical listing)

Linker options (functional listing)


Compiler options (alphabetical listing)

See also

The following table is an alphabetical listing of the C++Builder compiler options:

Option	Description

@<filename>	Read compiler options from the response file filename

+<filename>	Use alternate compiler configuration file filename

-3	Generate 80386 protected-mode compatible instructions (Default)

-4	Generate 80386/80486 protected-mode compatible instructions

-5	Generate Pentium instructions

-6	Generate Pentium Pro instructions

-A	Use ANSI keywords and extensions

-AK	Use Kernighan and Ritchie keywords and extensions

-AT	Use Borland C++ keywords and extensions (also -A-)

-AU	Use UNIX V keywords and extensions

-a	Default (-a4) data alignment; -a- is byte alignment (-a1)

-an	Align data on "n" boundaries, where 1=byte, 2=word (2 bytes), 4=double word (4 bytes), 8=quad word (8 bytes), 16=paragraph (16 bytes) (Default: -a4)

-B	Compile to .ASM (-S), then assemble to .OBJ

-b	Make enums always integer-sized (Default: -b makes enums integer size)

-b-	Makes enums byte-sized when possible

-C	Turn nested comments on (Default: -C- turn nested comments off)

-CP	Enable code paging (for MBCS)

-c	Compile to .OBJ, no link

-D<name>	Define "name" to the null string

-D<name=string>	Define "name" to "string"

-d	Merge duplicate strings

-d-	Does not merge duplicate strings (Default)

-E<filename>	Specify assembler

-e<filename>	Specify executable file name

-f	Emulate floating point

-f-	No floating point

-ff	Fast floating point

-fp	Correct Pentium FDIV flaw

-gb	Stop batch compilation after first file with warnings (Default = OFF)

-gn	Warnings: stop after n messages (Default = 255)

-G, -G-	Optimize for size/speed; use – O1 and –O2 instead

-H	Generate and use precompiled headers

-H-	Does not generate or use precompiled headers (Default)

-H=<filename>	Set the name of the file for precompiled headers

-H"xxx"	Stop precompiling after header file xxx

-Hc	Cache precompiled header (Must be used with -H or -H"xxx"

-He	Enable precompiled headers with external type files (Default)

-Hh=xxx	Stop precompiling after header file xxx

-Hs	Enable smart cached precompiled headers (Default)

-Hu	Use but do not generate precompiled headers

-I<path>	Include file search path

-in	Make significant identifier length to be n (Default = 250)

-Ja	Expand all template members (including unused members)

-jb	Stop batch compilation after first file with errors (Default = OFF)

-Jgd	Generate definitions for all template instances and merge duplicates (Default)

-Jgx	Generate external references for all template instances

-jn	Errors: stop after n messages (Default = 25)

-K	Default character type unsigned (Default: -K- default character type signed)

-k	Turn on standard stack frame (Default)

-L<path>	Library file search path

-lx	Pass option x to linker

-l-x	Disables option x for the linker

-M	Create a Map file

-n<path>	Sets output directory to path

-O	Optimize jumps

-O1	Generate smallest possible code

-O2	Generate fastest possible code

-Oc	Eliminate duplicate expressions within basic blocks and functions

-Od	Disable all optimizations

-Oi	Expand common intrinsic functions

-OS	Pentium instruction scheduling

-O-S	Disables instruction scheduling

-Og	Optimize for speed; use –O2 instead

-Os	Optimize for speed; use –O2 instead

-Ot	Optimize for size; use –O1 instead

-Ov	Enable loop induction variable and strength reduction

-Ox	Optimize for speed; use –O2 instead

-o<filename>	Compile .OBJ to filename

-P	Perform C++ compile regardless of source extension

-P-	Perform C++ compile depending on source file extension

-P<ext>	Perform C++ compile, set output to extension to .ext

-p	Use Pascal calling convention

-p-	Use C calling convention

-pc	Use C calling convention (Default: -pc, -p-)

-pr	Use fastcall calling convention for passing parameters in registers

-ps	Use stdcall calling convention

-q	Suppress compiler identification banner (Default = OFF)

-R	Include browser information in generated .OBJ files

-RT	Enable runtime type information (Default)

-r	Use register variables (Default)

-r-	Disable the use of register variables

-rd	Use register variables only when register keyword is employed

-S	Compile to assembler

-T-	Removes all assembler options

-Tx	Specify assembler option x

-tW	Target is a Windows application (same as -W)

-tWC	Target is a console application (same as -WC)

-tWD	Generate a .DLL executable (same as -WD)

-tWM	Generate a 32-bit multi-threaded target (same as -WM)

-tWR	Target uses the dynamic RTL (same as -WR)

-tWV	Target uses the VCL

-U<name>	Undefine any previous definitions of name

-u	Generate underscores (Default)

-V	Use smart C++ virtual tables (Default)

-V0	External C++ virtual tables

-V1	Public C++ virtual tables

-VC	Calling convention mangling compatibility

-Vd	for loop variable scoping

-Ve	Zero-length empty base classes

-VF	MFC compatibility

-VI-	Use old Borland search algorithm to locate header files (look first in current working directory)

-Vl	Use old-style Borland C++ structure layout (for compatibility with older versions of BCC32.EXE)

-Vmd	Use the smallest possible representation for member pointers

-Vmm	Support multiple inheritance for member pointers

-Vmp	Honor declared precision of member pointers

-Vms	Support single inheritance for member pointers

-Vmv	Place no restrictions on where member pointers can point (Default)

-Vx	Zero-length empty class member functions

-v	Turn on source debugging

-vi	Control expansion of inline functions

-W	Target is a Windows application (same as -tW)

-WC	Target is a console application (same as -tWC)

-WD	Generate a .DLL executable (same as -tWD)

-WM	Generate a 32-bit multi-threaded target (same as -tWM)

-WR	Target uses the dynamic RTL (same as -tWR)

-WU	Generates Unicode application

-w	Display warnings on

-w!	Returns non-zero from compiler on warnings

-wxxx	Enable xxx warning message

-w-xxx	Disable xxx warning message

-wmsg	User-defined warnings

-X	Disable compiler autodependency output (Default: -X- use compiler autodependency output)

-x	Enable exception handling (Default)

-xd	Enable destructor cleanup (Default)

-xdg	Use global destructor count (for compatibility with older versions of BCC32.EXE)

-xf	Enable fast exception prologs

-xp	Enable exception location information

-xs	Enable slow exception epilogues

-y	Debug line numbers on

Message options (alphabetical listing)

-wamb	-w8000	Ambiguous operators need parentheses (Default OFF)

-wamp	-w8001	Superfluous & with function (Default OFF)

-w-asc	-w-8002	Restarting compile using assembly (Default ON)

-wasm	-w8003	Unknown assembler instruction (Default OFF)

-w-aus	-w-8004	'identifier' is assigned a value that is never used (Default ON)

-wbbf	-w8005	Bit fields must be signed or unsigned int (Default OFF)

-w-bei	-w-8006	Initializing 'identifier' with 'identifier' (Default ON)

-w-big	-w-8007	Hexadecimal value contains more than three digits (Default ON)

-w-ccc	-w-8008	Condition is always true OR Condition is always false (Default ON)

-wcln	-w8009	Constant is long (Default OFF)

-w-com	-w-8010	Continuation character \ found in // comment (Default ON)

-w-cpt	-w-8011	Nonportable pointer comparison (Default ON)

-w-csu	-w-8012	Comparing signed and unsigned values (Default ON)

-wdef	-w8013	Possible use of 'identifier' before definition (Default OFF)

-w-dig	-w-8014	Declaration ignored (Default ON)

-w-dpu	-w-8015	Declare 'type' prior to use in prototype (Default ON)

-w-dsz	-w-8016	Array size for 'delete' ignored (Default ON)

-w-dup	-w-8017	Redefinition of 'macro' is not identical (Default ON)

-w-eas	-w-8018	Assigning ‘type’ to ‘enum’  (Default ON)

-w-eff	-w-8019	Code has no effect (Default ON)

-w-ext	-w-8020	'identifier' is declared as both external and static (Default ON)

-w-hch	-w-8021	Handler for 'type1' Hidden by Previous Handler for 'type2' (Default ON)

-w-hid	-w-8022	'function1' hides virtual function 'function2' (Default ON)

-w-ias	-w-8023	Array variable 'identifier' is near (Default ON)

-w-ibc	-w-8024	Base class 'class1' is also a base class of 'class2' (Default ON)

-w-ifr	-w-8085	Function 'function' redefined as non-inline (Default ON)

-w-ill	-w-8025	Ill-formed pragma (Default ON)

-w-inl	-w-8026	Functions containing certain constructs are not expanded inline (Default ON)

-w-inl	-w-8027	Functions containing reserved words are not expanded inline (Default ON)

-w-lin	-w-8028	Temporary used to initialize 'identifier' (Default ON)

-w-lvc	-w-8029	Temporary used for parameter 'parameter' (Default ON)

-w-lvc	-w-8030	Temporary used for parameter 'parameter' in call to 'function' (Default ON)

-w-lvc	-w-8031	Temporary used for parameter number (Default ON)

-w-lvc	-w-8032	Temporary used for parameter number in call to 'function' (Default ON)

-w-mpc	-w-8033	Conversion to ‘type’ fails for members of virtual base ‘base’ (Default ON)

-w-mpd	-w-8034	Maximum precision used for member pointer type ‘type’ (Default ON)

-w-msg	-w-8035	User-defined warnings (Default ON)

-wnak	-w8036	Non-ANSI Keyword Used: 'keyword' (Default OFF)
(Note: Use of this option is required for ANSI conformance)

-w-ncf	-w-8037	Non-const function ‘function’ called for const object (Default ON)

-w-nci	-w-8038	Constant member 'identifier' is not initialized (Default ON)

-w-ncl	-w-8039	Constructor initializer list ignored (Default ON)

-w-nfd	-w-8040	Function body ignored (Default ON)

-w-ngu	-w-8041	Negating unsigned value (Default ON)

-w-nin	-w-8042	Initializer for object 'identifier' ignored (Default ON)

-w-nma	-w-8043	Macro definition ignored (Default ON)

-w-nmu	-w-8044	#undef directive ignored (Default ON)

-wnod	-w8045	No declaration for function 'function' (Default OFF)

-w-nop	-w-8046	Pragma option pop with no matching option push (Default ON)

-w-npp	-w-8083	Pragma pack pop with no matching pack push (Default ON)

-w-nsf	-w-8047	Declaration of static function 'function(...)' ignored (Default ON)

-w-nst	-w-8048	Use qualified name to access nested type 'type' (Default ON)

-w-ntd	-w-8049	Use '> >' for nested templates instead of '>>' (Default ON)

-w-nto	-w-8050	No type OBJ file present. Disabling external types option. (Default ON)

-w-nvf	-w-8051	Non-volatile function ‘function’ called for volatile object (Default ON)

-w-obi	-w-8052	Base initialization without a class name is now obsolete (Default ON)

-w-obs	-w-8053	'identifier' is obsolete (Default ON)

-w-ofp	-w-8054	Style of function definition is now obsolete (Default ON)

-w-osh	-w-8055	Possible overflow in shift operation (Default ON)

-w-ovf	-w-8056	Integer arithmetic overflow (Default ON)

-w-par	-w-8057	Parameter 'parameter' is never used (Default ON)

-w-pch	-w-8058	Cannot create pre-compiled header: ‘header’ (Default ON)

-w-pck	-w-8059	Structure packing size has changed (Default ON)

-w-pia	-w-8060	Possibly incorrect assignment (Default ON)

-wpin	-w8061	Initialization is only partially bracketed (Default OFF)

-w-pow	-w-8062	Previous options and warnings not restored (Default ON)

-wprc	-w8084	Suggest parentheses to clarify precedence (Default OFF)

-w-pre	-w-8063	Overloaded prefix operator 'operator' used as a postfix operator (Default ON)

-w-pro	-w-8064	Call to function with no prototype (Default ON)

-w-pro	-w-8065	Call to function 'function' with no prototype (Default ON)

-w-rch	-w-8066	Unreachable code (Default ON)

-w-ret	-w-8067	Both return and return of a value used (Default ON)

-w-rng	-w-8068	Constant out of range in comparison (Default ON)

-w-rpt	-w-8069	Nonportable pointer conversion (Default ON)

-w-rvl	-w-8070	Function should return a value (Default ON)

-wsig	-w8071	Conversion may lose significant digits (Default OFF)

-w-spa	-w-8072	Suspicious pointer arithmetic (Default ON)

-wstu	-w8073	Undefined structure 'structure' (Default OFF)

-wstv	-w8074	Structure passed by value (Default OFF)

-w-sus	-w-8075	Suspicious pointer conversion (Default ON)

-w-tai	-w-8076	Template instance 'instance' is already instantiated (Default ON)

-w-tes	-w-8077	Explicitly specializing an explicitly specialized class member makes no sense (Default ON)

-w-thr	-w-8078	Throw expression violates exception specification (Default ON)

-wucp	-w8079	Mixing pointers to different 'char' types (Default OFF)

-wuse	-w8080	'identifier' declared but never used (Default OFF)

-w-voi	-w-8081	void functions may not return a value (Default ON)

-w-zdi	-w-8082	Division by zero (Default ON)


Compiler options (functional listing)

See also

Compiler options are grouped into the following functional categories:

Compiler-specific options

Configuration and Response files

Defines

Code generation

Floating point

Compiler output

Source

Debugging

Precompiled headers

Processor

Calling convention

C++-specific options

C++ compatibiltiy

Virtual tables

Templates

Exception handling

Optimization options

Warning message options

Portability

ANSI violations

Obsolete C++

Potential C++ errors

Inefficient C++ coding

Potential errors

Inefficient coding

General

Linker options

Input options

Map file options

Output options

File addressing options

File addressing options

Application target options

Linker messages and warnings

Compiler configuration files

@<filename>	Read compiler options from the response file " filename

Compiler response files

+<filename>	Use alternate configuration file filename

Compiler options | Defines

-D<name>	Define name to the null string

-Dname=string	Define "name" to "string"

-U<name>	Undefine any previous definitions of name

Compiler options | Code generation

-an	Align data on "n" boundaries, where 1=byte, 2=word (2 bytes), 4=Double word (4 bytes), 8=Quad word (8 bytes), 16=Paragraph (16 bytes) (Default: -a4)

-b	Make enums always integer-sized (Default: -b makes enums integer size)

-CP	Enable code paging (for MBCS)

-d	Merge duplicate strings

-K	Default character type unsigned (Default: -K- default character type signed)

-r	Use register variables (Default)

-rd	Use register variables only when register keyword is employed

-WU	Generates Unicode application

Compiler options | Floating point

-f-	No floating point

-f	Emulate floating point

-ff	Fast floating point

-fp	Correct Pentium fdiv flaw

Compiler options | Compiler output

-c	Compile to .OBJ, no link

-e<filename>	Specify executable file name

-lx	Pass option x to linker

-M	Create a Map file

-o<filename>	Compile .OBJ to filename

-P	Perform C++ compile regardless of source extension

-P<ext>	Perform C++ compile, set output to extension to .ext

-tW	Target is a Windows application

-tWC	Target is a console application

-tWD	Generate a .DLL executable

-tWM	Generate a 32-bit multi-threaded target

-tWR	Target uses the dynamic RTL

-tWV	Target uses the VCL

-X	Disable compiler autodependency output (Default: -X- use compiler autodependency output)

-u	Generate underscores (Default)

Compiler options | Source

-C	Turn nested comments on (Default: -C- turn nested comments off)

-in	Make significant identifier length to be "n" (Default = 250)

-AT	Use Borland C++ keywords (also -A-)

-A	Use only ANSI keywords

-AU	Use only UNIX V keywords

-AK	Use only Kernighan and Ritchie keywords

-VF	MFC compatibility

-VI-	Use old Borland search algorithm to locate header files (look first in current working directory)

Compiler options | Debugging

-k	Turn on standard stack frame (Default)

-vi	Control expansion of inline functions

-y	Line numbers on

-v	Turn on source debugging

-R	Include browser information in generated .OBJ files

Compiler options | Precompiled headers

-H	Generate and use precompiled headers (Default)

-Hu	Use but do not generate precompiled headers

-Hc	Cache precompiled header

-He	Enable precompiled headers with external type files (Default)

-Hs	Enable smart cached precompiled headers (Default)

-H=filename	Set the name of the file for precompiled headers

-H\"xxx\"	Stop precompiling after header file xxxx

-Hh=xxx	Stop precompiling after header file xxx

Compiler options | Processor

-3	Generate 80386 instructions. (Default)

-4	Generate 80486 instructions

-5	Generate Pentium instructions

-6	Generate Pentium Pro instructions

Compiler options | Calling convention

-p	Use Pascal calling convention

-pc	Use C calling convention (Default: -pc, -p-)

-pr	Use fastcall calling convention for passing parameters in registers

-ps	Use stdcall calling convention

Compiler options | Assembler-code options

-B	Compile to .ASM (-S), then assemble to .OBJ

-E<filename>	Specify assembler

-S	Compile to assembler

-Tx	Specify assembler option x

C++ options | C++ compatibility

-VC	Calling convention mangling compatibility

-Vd	for loop variable scoping

-Ve	Zero-length empty base classes

-Vl	Use old-style Borland C++ structure layout (for compatibility with older versions of BCC32.EXE)

-Vmd	Use the smallest possible representation for member pointers

-Vmm	Support multiple inheritance for member pointers

-Vmp	Honor declared precision of member pointers

-Vms	Support single inheritance for member pointers

-Vmv	Place no restrictions on where member pointers can point (Default)

-Vx	Zero-length empty class member functions

-xdg	Use global destructor count (for compatibility with older versions of BCC32.EXE)

C++ options | Virtual tables

-V	Use smart C++ virtual tables (Default)

-V0	External C++ virtual tables

-V1	Public C++ virtual tables

C++ options | Templates

-Ja	Expand all template members (including unused members)

-Jgd	Generate definitions for all template instances and merge duplicates (Default)

-Jgx	Generate external references for all template instances

C++ options | Exception handling

-x	Enable exception handling (Default)

-xp	Enable exception location information

-xd	Enable destructor cleanup (Default)

-xf	Enable fast exception prologs

-xs	Enable slow exception epilogues

-RT	Enable runtime type information (Default)

Optimization options

-G, -G-	Optimize for size/speed; use – O1 and –O2 instead

-O	Optimize jumps

-O1	Generate smallest possible code

-O2	Generate fastest possible code

-Oc	Eliminate duplicate expressions within basic blocks and functions

-Od	Disable all optimizations

-Oi	Expand common intrinsic functions

-OS	Pentium instruction scheduling

-Og	Optimize for speed; use –O2 instead

-Os, -Ot	Optimize for speed/size; use –O2 and –O1 instead

-Ov	Enable loop induction variable and strength reduction

-Ox	Optimize for speed; use –O2 instead

Warning message options

-q	Suppress compiler identification banner (Default = OFF)

-w	Display warnings on

-wxxx	Enable xxx warning message

-w-xxx	Disable xxx warning message

-gn	Warnings: stop after n messages (Default = 100)

-gb	Stop batch compilation after first file with warnings (Default = OFF)

-jn	Errors: stop after n messages (Default = 25)

-jb	Stop batch compilation after first file with errors (Default = OFF)

Message options | Portability

-w-rpt	-w-8069	Nonportable pointer conversion (Default ON)

-w-cpt	-w-8011	Nonportable pointer comparison (Default ON)

-w-rng	-w-8068	Constant out of range in comparison (Default ON)

-wcln	-w8009	Constant is long

-wsig	-w8071	Conversion may lose significant digits

-wucp	-w8079	Mixing pointers to different 'char' types

Message options | ANSI violations

-w-voi	-w-8081	Void functions may not return a value (Default ON)

-w-ret	-w-8067	Both return and return of a value used (Default ON)

-w-sus	-w-8075	Suspicious pointer conversion (Default ON)

-wstu	-w8073	Undefined structure 'structure'

-w-dup	-w-8017	Redefinition of 'macro' is not identical (Default ON)

-w-big	-w-8007	Hexadecimal value contains more than three digits (Default ON)

-wbbf	-w8005	Bit fields must be signed or unsigned int

-w-ext	-w-8020	'identifier' is declared as both external and static (Default ON)

-w-dpu	-w-8015	Declare type 'type' prior to use in prototype (Default ON)

-w-zdi	-w-8082	Division by zero (Default ON)

-w-bei	-w-8006	Initializing 'identifier' with 'identifier' (Default ON)

-wpin	-w8061	Initialization is only partially bracketed

-wnak	-w8036	Non-ANSI Keyword Used: '<keyword>' (Note: Use of this option is a requirement for ANSI conformance)

Message options | Obsolete C++

-w-obi	-w-8052	Base initialization without a class name is now obsolete (Default ON)

-w-ofp	-w-8054	Style of function definition is now obsolete (Default ON)

-w-pre	-w-8063	Overloaded prefix operator 'operator' used as a postfix operator (Default ON)

Message options | Potential C++ errors

-w-nci	-w-8038	The constant member 'identifier' is not initialized (Default ON)

-w-ncl	-w-8039	Constructor initializer list ignored (Default ON)

-w-nin	-w-8042	Initializer for object 'identifier' ignored (Default ON)

-w-eas	-w-8018	Assigning ‘type’ to ‘enum’ (Default ON)

-w-hid	-w-8022	'function1' hides virtual function 'function2' (Default ON)

-wncf	-w-8037	Non-constant function ‘ident’ called for const object

-w-ibc	-w-8024	Base class 'class1' is also a base class of 'class2' (Default ON)

-w-dsz	-w-8016	Array size for 'delete' ignored (Default ON)

-w-nst	-w-8048	Use qualified name to access nested type 'type' (Default ON)

-whch	-w-8021	Handler for 'type1' Hidden by Previous Handler for 'type2'

-w-mpc	-w-8033	Conversion to type fails for members of virtual base class base (Default ON)

-w-mpd	-w-8034	Maximum precision used for member pointer type <type> (Default ON)

-w-ntd	-w-8049	Use '> >' for nested templates instead of '>>' (Default ON)

-w-thr	-w-8078	Throw expression violates exception specification (Default ON)

-w-tai	-w-8076	Template instance 'instance' is already instantiated (Default ON)

-w-tes	-w-8077	Explicitly specializing an explicitly specialized class member makes no sense (Default ON)

-w-nvf	-w-8051	Non-volatile function ‘function’ called for volatile object (Default ON)

Message options | Inefficient C++ coding

-w-inl	-w-8026, -w-8027	Functions containing ... are not expanded inline (Default ON)

-w-lin	-w-8028	Temporary used to initialize 'identifier' (Default ON)

-w-lvc	-w-8029, -w-8030, -w-8031, -w-8032	Temporary used for parameter (Default ON)

Message options | Potential errors

-w-pia	-w-8060	Possibly incorrect assignment (Default ON)

-wdef	-w8013	Possible use of 'identifier' before definition

-wnod	-w8045	No declaration for function 'function'

-w-pro	-w-8064, -w-8065	Call to function with no prototype (Default ON)

-w-rvl	-w-8070	Function should return a value (Default ON)

-wamb	-w8000	Ambiguous operators need parentheses

-wprc	-w8084	Suggest parentheses to clarify precedence (Default OFF)

-w-ccc	-w-8008	Condition is always true OR Condition is always false (Default ON)

-w-com	-w-8010	Continuation character \ found in // comment (Default ON)

-w-csu	-w-8012	Comparing signed and unsigned values (Default ON)

-w-nfd	-w-8040	Function body ignored (Default ON)

-w-ngu	-w-8041	Negating unsigned value (Default ON)

-w-nma	-w-8043	Macro definition ignored (Default ON)

-w-nmu	-w-8044	#undef directive ignored (Default ON)

-w-nop	-w-8046	Pragma option pop with no matching option push (Default ON)

-w-npp	-w-8083	Pragma pack pop with no matching pack push (Default ON)

-w-nsf	-w-8047	Declaration of static function 'function(...)' ignored (Default ON)

-w-osh	-w-8055	Possible overflow in shift operation (Default ON)

-w-ovf	-w-8056	Integer arithmetic overflow (Default ON)

-w-dig	-w-8014	Declaration ignored (Default ON)

-w-pck	-w-8059	Structure packing size has changed (Default ON)

-w-spa	-w-8072	Suspicious pointer arithmetic (Default ON)

-w-ifr	-w-8085	Function 'function' redefined as non-inline (Default ON)

Message options | Inefficient coding

-w-aus	-w-8004	'identifier' is assigned a value that is never used (Default ON)

-w-par	-w-8057	Parameter 'parameter' is never used (Default ON)

-wuse	-w8080	'identifier' declared but never used

-wstv	-w8074	Structure passed by value

-w-rch	-w-8066	Unreachable code (Default ON)

-w-eff	-w-8019	Code has no effect (Default ON)

Message options | General

-wasm	-w8003	Unknown assembler instruction

-w-ill	-w-8025	Ill-formed pragma (Default ON)

-w-ias	-w-8023	Array variable 'identifier' is near (Default ON)

-wamp	-w8001	Superfluous & with function

-w-obs	-w-8053	'ident' is obsolete (Default ON)

-w-pch	-w-8058	Cannot create precompiled header: ‘header‘ (Default ON)

-w-msg	-w-8035	User-defined warnings

-w-asc	-w-8002	Restarting compile using assembly (Default ON)

-w-nto	-w-8050	No type OBJ file present. Disabling external types option. (Default ON)

-w-pow	-w-8062	Previous options and warnings not restored (Default ON)


Linker options (alphabetical listing)

The following list shows the ILINK32 linker options in alphabetical order.

Option	Description

@xxxx	Uses the response file xxxx

/A:dd	Specifies file alignment (backward compatibility switch; use /Af)

/Af:nnnn	Specifies file alignment; set nnnn in hex or decimal (0x200 = 512 byte boundaries)

/Ao:nnnn	Specifies object alignment; set nnnn in hex or decimal (0x1000 = 4096 byte boundaries)

/aa	Builds a 32-bit Windows application

/ap	Builds a 32-bit Windows console application

/B:xxxx	Specifies image base address

/b:xxxx	Specifies image base address; preserves DLL relocation table

/C	Erases all linker-state files before each link

/c	Treats case as significant in symbols

/D:xxxx	Save specified description with package

/Gi	Save generated .BPI file

/Gl	Generate .LIB file

/Gpd	Generate design-time–only package

/Gpr	Generate runtime-only package

/Gn	Don’t generate state files (disable incremental linking)

/Gz	Calculate checksum of target and insert result in PE header

/H:xxxx	Specifies application heap reserve size

/Hc:nnnn	Specifies application heap commit size

/j	Specifies object search paths

/Ja	Expand all template members, even those which are not used

/L	Specifies library search paths

/M	Mangled names in map file

/m	Creates map file with public names

/S:xxxx	Specifies application stack reserve size

/Sc:xxxx	Specifies application stack commit size

/s	Detailed map file of segments

/Tpd	Targets a Windows .DLL file

/Tpe	Targets a Windows .EXE file

/Tpp	Generate package

/t	Displays time spent on link

/Vd.d	Specifies expected Windows version

/v	Includes full symbolic debug information

/w	Warning control

/w-	Disables all warnings

/wdef	Enables “No .DEF file” warning

/wdpl	Enables “Duplicate symbol in library” warning

/wimt	Enables “Import does not match previous definition” warning

/wmsk	Enables “Multiple stack segment” warning

/w-bdl	Disables “Using based linking in .DLL” warning

/w-dll	Disables “.EXE module built with a .DLL extension” warning

/w-dup	Disables “Duplicate symbol” warning

/w-ent	Disables “No entry point” warning

/w-inq	Disables “Extern not qualified with __import” warning

/w-srf	Disables “Self-relative fixup overflow” warning

/w-stk	Disables “No stack” warning

/x	Suppresses creation of map file

Default map file of segments (no linker switch, map file created by default)


Compiler-specific options

See also

Compiler-specific options can be used with all C and C++ programs. They directly affect how the compiler generates code.

The sub-topics are

Compiler define options

Compiler code generation options

Floating point options

Compiler output options

Source options

Debugging options

Precompiled header options

Assembler-code options


Compiler define options

See also

The macro definition capability of C++Builder lets you define and undefine macros (also called manifest or symbolic constants). The macros you define override those defined in your source files.

Defining macros

(Command-line switch: -Dname and -Dname=string)

The -Dname option defines the identifier name to the null string. -Dname=string defines name to string. In this assignment, string cannot contain spaces or tabs. You can also define multiple #define options on the command line using either of the following methods:

Include multiple definitions after a single -D option by separating each define with a semicolon (;) and assigning values with an equal sign (=). For example:

BCC32.EXE -Dxxx;yyy=1;zzz=NO MYFILE.C

Include multiple -D options, separating each with a space. For example:

BCC32.EXE -Dxxx -Dyyy=1 -Dzzz=NO MYFILE.C

Undefining macros

(Command-line switch = -Uname)

This command-line option undefines the previous definition of the identifier name.


Compiler code generation options

See also

Compiler Code Generation options affect how code is generated.

The options are

Instruction set

Calling convention

Data alignment

Treat enums as ints

Unsigned characters

Merge duplicate strings

Register variables

Code paging

Unicode application


Instruction set options

See also

The Instruction Set options specify for which CPU instruction set the compiler should generate code.

80386

(Command-line switch: -3)

Choose the 80386 option if you want the compiler to generate 80386 protected-mode compatible instructions running on Windows 95 or Windows NT.

i486

(Command-line switch: -4)

Choose the i486 option if you want the compiler to generate i486 protected-mode compatible instructions running on Windows 95 or Windows NT.

Pentium

(Command-line switch: -5)

Choose the Pentium option if you want the compiler to generate Pentium instructions on Windows 95 or Windows NT.

While this option increases the speed at which the application runs on Pentium machines, expect the program to be a bit larger than when compiled with the 80386 or i486 options. In addition, Pentium-compiled code will sustain a performance hit on non-Pentium systems.

Pentium Pro

(Command-line switch: -6)

Choose the Pentium Pro option if you want the compiler to generate Pentium Pro instructions running on Windows 95 or Windows NT.

Default = 80386  (-3)


Calling convention options

See also

Calling Convention options tell the compiler which calling sequences to generate for function calls. The C, Pascal, and Register calling conventions differ in the way each handles stack cleanup, order of parameters, case, and prefix of global identifiers.

You can use the _ _cdecl, _ _pascal, _ _fastcall, or _ _stdcall keywords to override the default calling convention on specific functions.

In C++Builder code, you will normally use the default C calling convention.

C

(Command-line switch: -pc, -p-)

This option tells the compiler to generate a C calling sequence for function calls (generate underbars, case sensitive, push parameters right to left). This is the same as declaring all subroutines and functions with the _ _cdecl keyword. Functions declared using the C calling convention can take a variable parameter list (the number of parameters does not need to be fixed).

You can use the _ _pascal,  _ _fastcall, or _ _stdcall keywords to specifically declare a function or subroutine using another calling convention.

Pascal

(Command-line switch: -p)

This option tells the compiler to generate a Pascal calling sequence for function calls (do not generate underbars, all uppercase, calling function cleans stack, pushes parameters left to right). This is the same as declaring all subroutines and functions with the _ _pascal keyword. The resulting function calls are usually smaller and faster than those made with the C (-pc) calling convention. Functions must pass the correct number and type of arguments.

You can use the _ _cdecl, _ _fastcall, or _ _stdcall keywords to specifically declare a function or subroutine using another calling convention.

Register

(Command-line switch: -pr)

This option forces the compiler to generate all subroutines and all functions using the Register parameter-passing convention, which is equivalent to declaring all subroutine and functions with the _ _fastcall keyword. With this option enabled, functions or routines expect parameters to be passed in registers.

You can use the _ _pascal, _ _cdecl, or _ _stdcall keywords to specifically declare a function or subroutine using another calling convention.

Standard Call

(Command-line switch: -ps)

This option tells the compiler to generate a Stdcall calling sequence for function calls (does not generate underscores, preserve case, called function pops the stack, and pushes parameters right to left). This is the same as declaring all subroutines and functions with the _ _stdcall keyword. Functions must pass the correct number and type of arguments.

You can use the _ _cdecl, _ _pascal, _ _fastcall keywords to specifically declare a function or subroutine using another calling convention.

Default = C  (-pc)


Data alignment options

See also

The Data Alignment options let you choose how the compiler aligns data in stored memory. Word, double word, and quad word alignment force integer-size and larger items to be aligned on memory addresses that are multiples of the type chosen. Extra bytes are inserted in structures to ensure that members align correctly.

Byte alignment

(Command-line switch: -a1 or -a-)

When byte alignment is on, the compiler does not force alignment of variables or data fields to any specific memory boundaries. The compiler aligns data at even or odd addresses, depending on the next available address.

While byte alignment produces more compact programs, the programs tend to run slower. The other data alignment options increase the speed at which 80x86 processors fetch and store data.

Word alignment (2-byte)

(Command-line switch: -a2)

When word alignment is on, the compiler aligns non-character data at even addresses. Automatic and global variables are aligned properly. char and unsigned char variables and fields can be placed at any address; all others are placed at even-numbered addresses.

Double word (4-byte)

(Command-line switch: -a4 or -a)

Double word alignment aligns non-character data at 32-bit word (4-byte) boundaries. Data with type sizes of less than four bytes are aligned on their type size.

Quad word (8-byte)

(Command-line switch: -a8)

Quad word alignment aligns non-character data at 64-bit word (8-byte) boundaries. Data with type sizes of less than eight bytes are aligned on their type size.

Paragraph (16-byte)

(Command-line switch: -a16)

Paragraph alignment aligns non-character data at 128-bit word (16-byte) boundaries. Data with type sizes of less than 16 bytes are aligned on their type size.

Default = Double word alignment (-a4 or -a)


Treat enums as ints option

See also

(Command-line switch: -b)

When the Treat Enums As Ints option is set, the compiler always allocates a whole word (a four-byte int for 32-bit programs) for enumeration types (variables of type enum).

When this option is off (-b-), the compiler allocates the smallest integer that can hold the enumeration values: the compiler allocates an unsigned or signed char if the values of the enumeration are within the range of 0 to 255 (minimum) or -128 to 127 (maximum), or an unsigned or signed short if the values of the enumeration are within the following ranges:

0 to 4,294,967,295 or -2,147,483,648 to 2,147,483,647

The compiler allocates a four-byte int (32-bit) to represent the enumeration values if any value is out of range.

Default = ON


Unsigned characters option

See also

(Command-line switch: -K)

When Unsigned Characters is set, the compiler treats char declarations as if they were unsigned char type, which provides compatibility with other compilers.

Default = OFF (char declarations default to signed; -K-)


Merge duplicate strings option

See also

(Command-line switch: -d)

When you set this option, the compiler merges two literal strings when one matches another. This produces smaller programs (at the expense of a slightly longer compile time), but can introduce errors if you modify one string.

Default = OFF (-d-)


Register variable option
Register variable options

See also

These options suppress or enable the use of register variables.

None

(Command-line switch: -r-)

None tells the compiler not to use register variables, even if you have used the register keyword.

Register keyword

(Command-line switch: -rd)

Register Keyword tells the compiler to use register variables only if you use the register keyword and a register is available. Use this option or the Automatic option (-r) to optimize the use of registers.

You can use -rd in #pragma options.

Automatic

(Command-line switch: -r)

Automatic tells the compiler to automatically assign register variables if possible, even when you do not specify a register variable by using the register keyword.

Generally, you can use Automatic, unless you are interfacing with preexisting assembly code that does not support register variables.

Default = Automatic (-r)


Code paging (MBCS)
Code paging (for MBCS)

(Command-line switch: -CP)

This option enables support for user-defined code pages. Its primary use is to let BCC32 know how to parse and convert multi-byte character strings (MBCS).

There are two distinct areas where code pages come into effect:

1.	String constants, comments, #error, and #pragma directives

2.	Wide-char string constants (as specified by L'<MBCS string>')

For MBCS strings belonging to the first set, you must specify the correct code page using a call to the Windows API function IsDBCSLeadByteEx. Using this function, specify the code page to correctly parse the MBCS strings for a particular locale (this, for example, enables BCC32 to correctly parse backslashes in MBCS trail bytes).

For MBCS strings belonging to the second set (wide-char string constants), specify the correct code page to convert the MBCS strings to Unicode strings using the Windows API function MultiByteToWideChar.

Syntax

Enable code paging with the following command-line switch:

-CPnnnn

In this syntax, nnnn is the decimal value of the code page you need to use for your specific locale.

The following rules apply:

When setting code paging, numeric settings for nnnn must adhere to the Microsoft NLS Code Page ID values. For example, use 437 for United States MS-DOS applications. Use 932 for Japanese.

The numeric value nnnn must be a valid code page supported by the OS.

The users may need to install the relevant Windows NLS files to make certain Asian locales and code pages accessible. Please refer to the Microsoft NLS Code Page documentation for specifics.

If you do not specify a code page value, BCC32 will call the Windows API function GetACP to retrieve the system's default code page, and will use this value when handling strings as indicated above.

Default = OFF


Unicode application

(Command-line switch: -WU)

This option creates a Unicode application from source code that uses the _txxxx macros in tchar.h. The macros are replaced with Unicode names if _UNICODE is enabled, and with non-Unicode names otherwise.

For example, the following code can be compiled as either a Unicode or a non-Unicode application. To compile it as a Unicode application, put the -WU switch on the command line.

#include <stdio.h>

#include <tchar.h>

int _tmain(char argc, _TCHAR ** _targv)

{

        _TCHAR buff[200];

        int i;

        for (i = 0; i < argc; i++)

        {

                _tcscpy(buff, _targv[i]);

                _tprintf(_T("argument %d:%s\n"), i, buff);

        }

        return 0;

}

In this example, _tcscpy is replaced by wcscpy if -WU is used, and by strcpy otherwise. Similarly, _tprintf is replaced by wprintf or printf, _TCHAR by wchar_t or char, and _targv by _wargv or _argv. The _T(...) macro turns the string in parentheses into a wide-character or standard string.

The tchar.h header file also maps _tWinMain to WinMain or wWinMain, and so forth. See tchar.h for a complete list of translations.

Default = OFF


Compiler floating point options

See also

Floating Point options tell the compiler how to handle floating-point code and floating-point optimization.

No floating point

(Command-line switch: -f-)

Use No Floating Point if you are not using floating point. No floating-point libraries are linked when this option is set (-f-). If you enable this option and use floating-point calculations in your program, you will get link errors. When unchecked (-f), the compiler emulates 80x87 calls at runtime.

Default = OFF  (-f)

Fast floating point

(Command-line switch: -ff)

When Fast Floating Point is on, floating-point operations are optimized without regard to explicit or implicit type conversions. Calculations can be faster than under ANSI operating mode.

The purpose of the fast floating-point option is to allow certain optimizations that are technically contrary to correct C semantics. For example,

double x;

x = (float) (3.5*x);

To execute this correctly, x is multiplied by 3.5 to give a double that is truncated to float precision, then stores as a double in x. Under the fast floating-point operation, the long double product is converted directly to a double. Since very few programs depend on the loss of precision on passing to a narrower floating-point type, fast floating point is the default.

When this option is disabled (-ff-), the compiler follows strict ANSI rules regarding floating-point conversions.

Default = ON

Correct Pentium FDIV flaw

(Command-line switch: -fp)

Some early Pentium chips do not perform specific floating-point division calculations with full precision. Although your chances of encountering this problem are slim, this switch inserts code that emulates floating-point division so that you are assured of the correct result. This option decreases your program's FDIV instruction performance.

Use of this option only corrects FDIV instructions in modules that you compile. The run-time library also contains FDIV instructions which are not modified by the use of this switch. To correct the run-time libraries, you must recompile them using this switch.

The following functions use FDIV instructions in assembly language which are not corrected if you use this option:

acos	cosh	pow10l

acosl	coshl	powl

asin	cosl	sin

asinl	exp	sinh

atan	expl	sinhl

atan2	fmod	sinl

atan2l	fmodl	tan

atanl	pow	tanh

cos	pow10	tanhl

tanl

In addition, this switch does not correct functions that convert a floating-point number to or from a string (such as printf or scanf).

Default = OFF


Compiler output options

See also

The following options control the compiler outputs

General compiler output options

Autodependency information

Generate underscores


General compiler output options

See also

Compile to .OBJ, no link

(Command-line switch = -c)

Compiles and assembles the named .C, .CPP, and .ASM files, but does not execute a link on the resulting .OBJ files.

Specify executable file name

(Command-line switch = -efilename)

Link file using filename as the name of the executable file. If you do not specify an executable name with this option, the linker creates an executable file based on the name of the first source file or object file listed in the command.

Pass option to linker

(Command-line switch = -lx)

Use this command-line option to pass option(s) x to the linker from a compile command. Use the command-line option -l-x to disable a specific linker option.

Create a MAP file

(Command-line switch = -M)

Use this compiler option to instruct the linker to create a map file.

Compile .OBJ to filename

(Command-line switch = -ofilename)

Use this option to compile the specified source file to filename.OBJ.

C++ compile

(Command-line switch = -P)

The -P command-line option causes the compiler to compile all source files as C++ files, regardless of their extension. Use -P- to compile all .CPP files as C++ source files and all other files as C source files.

The command-line option -Pext causes the compiler to compile all source files as C++ files and it changes the default extension to whatever you specify with ext. This option is provided because some programmers use different extensions as their default extension for C++ code.

The option -P-ext compiles files based on their extension (.CPP compiles to C++, all other extensions compile to C) and sets the default extension (other than .CPP).

Generate a multi-threaded target

(Command-line switch = -tWM)

The compiler creates a multi-threaded .EXE or .DLL. (The command-line option -WM is supported for backward compatibility only; it has the same functionality as -tWM.)

This option is not needed if you include a module definition file in your compile and link commands which specifies the type of 32-bit application you intend to build.


Autodependency information option

See also

(Command-line switch: -X-)

When the Autodependency option is set (-X-), the compiler generates autodependency information for all project files with a .C or .CPP extension.

The Borland C++ Project Manager uses autodependency information to speed up compilation times. The Project Manager opens the .OBJ file and looks for information about files included in the source code. This information is always placed in the .OBJ file when the source module is compiled. After that, the time and date of every file that was used to build the .OBJ file is checked against the time and date information in the .OBJ file. The source file is recompiled if the dates are different. This is called an autodependency check.

If the project file contains valid dependency information, the Project Manager does the autodependency check using that information. This is much faster than reading each .OBJ file.

When this option is disables (-X), the compiler does not generate the autodependency information.

Modules compiled with autodependency information can use MAKE's autodependency feature.

Note	The C++Builder Project Manager does not use autodependency information.

Default = OFF  (-X)


Generate underscores option

See also

(Command-line switch: -u)

When Generate Underscores option is set, the compiler automatically adds an underscore character (_) in front of every global identifier (functions and global variables) before saving them in the object module. Pascal identifiers (those modified by the _ _pascal keyword) are converted to uppercase and are not prefixed with an underscore.

Underscores for C and C++ are optional, but you should turn this option on to avoid errors if you are linking with the Borland C++ libraries.

Default = ON


Compiler source options

See also

Compiler source options tell the compiler how to interpret source code.

The options are

Source

Nested comments

Identifier Length

Language compliance

Borland extensions

ANSI

UNIX V

Kernighan and Ritchie

Compatibility

MFC compatibility


Nested comments option

See also

(Command-line switch: -C)

When Nested Comments is on, you can nest comments in your C and C++ source files.

Nested comments are not allowed in standard C implementations, and they are not portable.

Default = OFF


Identifier length option

See also

(Command-line switch: -in, where n = significant characters)

Use Identifier Length to specify the number of significant characters (those which will be recognized by the compiler) in an identifier.

Except in C++, which recognizes identifiers of unlimited length, all identifiers are treated as distinct only if their significant characters are distinct. This includes variables, preprocessor macro names, and structure member names.

Valid numbers for n are 0, and 8 to 250, where 0 means use the maximum identifier length of 250.

By default, C++Builder uses 250 characters per identifier. Other systems (including some UNIX compilers) ignore characters beyond the first eight. If you are porting to other environments, you might want to compile your code with a smaller number of significant characters, which helps you locate name conflicts in long identifiers that have been truncated.

Default = 250


Language compliance options

See also

The Language Compliance options tell the compiler how to recognize keywords in your programs.

Borland extensions

(Command-line switches: -A-, -AT)

Borland Extensions tells the compiler to recognize Borland's extensions to the C language keywords, including near, far, huge, asm, cdecl, pascal, interrupt, _export, _ds, _cs, _ss, _es, and the register pseudovariables (_AX, _BX, and so on). For a complete list of keywords, see the keyword index.

ANSI

(Command-line switch: -A)

The ANSI option compiles C and C++ ANSI-compatible code, allowing for maximum portability. Non-ANSI keywords are ignored as keywords.

UNIX V

(Command-line switch: -AU)

The UNIX V option tells the compiler to recognize only UNIX V keywords and treat any of Borland's C++ extension keywords as normal identifiers.

Kernighan and Ritchie

(Command-line switch: -AK)

The Kernighan and Ritchie option tells the compiler to recognize only the K&R extension keywords and treat any of Borland's C++ extension keywords as normal identifiers.

Hint:	If you get declaration syntax errors from your source code, check that this option is set to Borland Extensions.

Default = Borland Extensions  (-A-)


MFC compatibility option

See also

(Command-line switches: -VF)

Turn this option on to compile code that is compatible with the Microsoft foundation classes (MFC). Among other things, the compiler makes the following adjustments to be compatible with MFC:

Accepts spurious semicolons in a class scope

Allows anonymous structs

Uses the old-style scoping resolution in for loops

Allows methods to be declared with a calling convention, but leaves off the calling convention in the definition

Tries the operator new if it cannot resolve a call to the operator new[ ]

Lets you omit the operator & on member functions

Allows a const class that is passed by value to be treated as a trivial conversion, not as a user conversion

Allows you to use a cast to a member pointer as a selector for overload resolution, even if the qualifying type of the member pointer is not derived from the class in which the member function is declared

Accepts declarations with duplicate storage in a class, as in

extern "C" typedef

Accepts and ignores #pragma comment(linker, "...") directives

Note:	The -VF option is not compatible with – A.

Default = OFF


Compiler debugging options

See also

Compiler Debugging options affect the generation of debug information during compilation. When linking larger .OBJ files, you may need to turn these options off to increase the available system resources.

The options are

Standard stack frame

Out-of-line inline functions

Line numbers

Debug information in OBJs


Standard stack frame option

See also

(Command-line switch: -k)

When the Standard Stack Frame option is on, the compiler generates a standard stack frame (standard function entry and exit code). This is helpful when debugging, since it simplifies the process of stepping through the stack of called subroutines.

When this option is off, any function that does not use local variables and has no parameters is compiled with abbreviated entry and return code. This makes the code smaller and faster.

The Standard Stack Frame option should always be on when you compile a source file for debugging.

Default = ON


Out-of-line inline functions option

See also

(Command-line switch: -vi)

When the Out-of-Line Inline Functions option is on, the compiler expands C++ inline functions inline.

To control the expansion of inline functions, the Debug Information In OBJs option (-v) acts slightly different for C++ code: when inline function expansion is disabled, inline functions are generated and called like any other function.

Because debugging with inline expansion can be difficult, the following command-line options are provided:

-v turns debugging on and inline expansion off

-v- turns debugging off and inline expansion on

-vi turns inline function expansion on

-vi- turns inline expansion off (inline functions are expanded out of line)

For example, if you want to turn both debugging and inline expansion on, use the -v and -vi options.

Default = OFF


Line numbers option

See also

(Command-line switch: -y)

When the Line Numbers option is on, the compiler automatically includes line numbers in the object and object map files. Line numbers are used by both the integrated debugger and Turbo Debugger.

Although the Debug Info in OBJs option (-v) automatically generates line number information, you can turn that option off (-v-) and turn on Line Numbers (-y) to reduce the size of the debug information generated. With this setup, you can still step, but you will not be able to watch or inspect data items.

Including line numbers increases the size of the object and map files but does not affect the speed of the executable program.

When Line Numbers is on, make sure you turn off Pentium scheduling in the Compiler options. When this option is set, the source code will not exactly match the generated machine instructions, which can make stepping through code confusing.

Default = OFF


Debug information in OBJs option

See also

(Command-line switch: -v)

When the Debug Info In OBJs option is on, debugging information is included in your .OBJ files. The compiler passes this option to the linker so it can include the debugging information in the .EXE file. For debugging, this option treats C++ inline functions as normal functions.

You need debugging information to use either the integrated debugger or the standalone Turbo Debugger.

When this option is off (-v-), you can link and create larger object files. While this option does not affect execution speed, it does affect compilation and link time.

When Line Numbers is on, make sure you turn off Pentium scheduling in the Compiler options. When this option is set, the source code will not exactly match the generated machine instructions, which can make stepping through code confusing.

Default = ON


Precompiled header options

See also

Precompiled header files can dramatically increase compilation speed by storing an image of the symbol table on disk in a file, then later reloading that file from disk instead of parsing all the header files again. Directly loading the symbol table from disk is much faster than parsing the text of header files, especially if several source files include the same header file.

The options are

General usage

Cache precompiled header

Smart-cached precompiled header

Generate external type files (precompiled headers)

Precompiled header name

Stop precompiling after header file


General precompiled header options

See also

Precompiled headers can dramatically increase compilation speeds, although they require a considerable amount of disk space.

Generate and use

(Command-line switch: -H)

When you set this option, the IDE generates and uses precompiled headers. The default file name is <projectname>.CSM for IDE projects, and is BC32DEF.CSM for command-line compiles.

Use but do not generate

(Command-line switch: -Hu)

When the Use But Do Not Generate option is set, the compilers use preexisting precompiled header files; new precompiled header files are not generated.

Do not generate or use

(Command-line switch: -H-)

When the Do Not Generate Or Use option is on, the compilers do not generate or use precompiled headers.

Default = Do not generate or use  (-H-)


Cache precompiled header option

See also

(Command-line switch: -Hc)

When you enable this option, the compiler caches the precompiled headers it generates. This is useful when you are precompiling more than one header file.

To use this option, you must also enable the Generate and Use (-H) precompiled header option.

Default = OFF


Smart-cached precompiled header option

See also

(Command-line switch: -Hs)

When you enable this option, the compiler smart-caches the precompiled headers it generates (smart-caching uses less memory than regular caching option -Hc). Caching your header files in memory is useful when you are precompiling more than one header file.

Default = ON


Generate external type files (precompiled headers)

See also

(Command-line switch: -He)

When this option is set, the compiler generates a file or files that contain debug type information for all the symbols contained in the precompiled headers. The files end with the .#xx extension, where xx is 00 for the first file generated and is incremented for each additional type-information file required.

Using this option dramatically decreases the size of your .OBJ files, since debug type information is centralized and is not duplicated in each .OBJ file.

Default = ON


Precompiled header name option

See also

(Command-line switch: -H=filename)

This option lets you specify the name of your precompiled header file. The compilers set the name of the precompiled header to filename.

When this option is set, the compilers generate and use the precompiled header file that you specify.


Stop precompiling after header file option

See also

(Command-line switch: -Hh=xxx or -H\"xxx\")

This option terminates compiling the precompiled header after processing the file specified as xxx. You can use this option to reduce the disk space required for precompiled headers.

The -Hh sytnax is generally easier to use than the -H syntax. Whichever version you choose, you need to quote long file names. Examples:

-Hh=mycsm.csm

-H\"mycsm.csm\"

-Hh="c:\program files\mycsm.csm"

-H\"c:\program files\mycsm.csm\"

When you use this option, the file you specify must be included from a source file for the compiler to generate a .CSM file.

You can also use #pragma hdrstop within your .CPP files to specify when to stop the generation of precompiled headers.

You cannot specify a header file that is included from another header file. For example, you cannot list a header included by windows.h because this would cause the precompiled header file to be closed before the compilation of windows.h was completed.


Assembler_code options
Assembler-code options

See also

Compile to .ASM, then assemble

(Command-line switch = -B)

This command-line option causes the compiler to first generate an .ASM file from your C++ (or C) source code (same as the -S command-line option). The compiler then calls TASM32 (or the assembler specified with the -E option) to create an .OBJ file from the .ASM file. The .ASM file is then deleted. To use this 32-bit compiler option, you must install a 32-bit assembler, such as TASM32.EXE, and then specify this assembler with the -E option.

Your program will fail to compile with the -B option if your C or C++ source code declares static global variables that are keywords in assembly. This is because the compiler does not precede static global variables with an underscore (as it does other variables), and the assembly keywords will generate errors when the code is assembled.

Specify assembler

(Command-line switch = -Efilename)

Assemble instructions using filename as the assembler. The 32-bit compiler uses TASM32 as the default assembler.

Compile to assembler

(Command-line switch = -S)

This option causes the compiler to generate an .ASM file from your C++ (or C) source code. The generated .ASM file includes the original C or C++ source lines as comments in the file.

Specify assembler option

(Command-line switch = -Tx)

Use this command-line option to pass the option(s) x to the assembler you specify with the -E option. To disable all previously enabled assembler options, use the -T- command-line option.


Search directories

See also

The search directory options let you specify the directories that contain your standard include files, library and .OBJ files, and program source files.

Include

(Command-line equivalent: -Ipath, where path = directory path)

Use this option to specify the drive and/or directories that contain program include files. Standard include files are those you specify in angle brackets (<>) in an #include statement (for example, #include <myfile>).

The Borland compilers and linkers use specific file search algorithms to locate the files needed to complete the compilation and link cycles.

Library

(Command-line equivalent: -Lpath, where path = directory path)

Use the Library option to specify the directories that contain the C++Builder startup object files (C0x.OBJ), run-time library files (.LIB files), and all other .LIB files. By default, the linker looks for them in the directory containing the project file (or in the current directory if you’re using the command-line compiler).

You can also use the linker option /Lpath to specify the library search directories when you link files from the command line.

Specifying multiple directories

You can specify multiple directory names from the command line by using a semicolon (;) to separate the specified drives and directories:

You can stack multiple entries with a single -L or -I option by separating directories with a semicolon:

BCC32.EXE -Ldirname1;dirname2;dirname3 -Iinc1;inc2;inc3 myfile.c

You can place more than one of each option on the command line, like this:

BCC32.EXE -Ldirname1 -Ldirname2 -Iinc1 -Iinc2 -Iinc3 myfile.c

You can mix listings:

BCC32.EXE -Ldir1;dir2 -Iinc1 -Ld:dir3 -Iinc2;inc3 myfile.c

If you list multiple -L or -I options on the command line, the result is cumulative; the compiler searches all the directories listed in order from left to right.


Guidelines for entering directory names

See Also

Use the following guidelines when entering directories in the Directories options page.

You must separate multiple directory path names (if allowed) with a semicolon (;).

You can use up to a maximum of 127 characters (including whitespace).

Whitespace before and after the semicolon is allowed but not required.

Relative and absolute path names are allowed, including path names relative to the logged position in drives other than the current one.

For example,

C:\;C:..\CBuilder;D:\myprog\source


File search algorithms

See also

#include-file search algorithms

The Borland C++ compiler searches for files included in your source code with the #include directive in the following ways:

If you specify a path and/or directory with your include statement, the compiler searches only the location specified. For example, if you have the following statement in your code:

   #include "c:\CBuilder\include\vcl\vcl.h"

the header file vcl.h must reside in the directory C:\ CBuilder\INCLUDE. In addition, if you use the statement:

   #include <vcl\vcl.h>

and you set the Include option (-I) to specify the path c:\CBuilder\include, the file vcl.h must reside in C:\CBuilder\INCLUDE\VCL, and not in C:\CBuilder\INCLUDE or C:\VCL.

If you put an #include <somefile> statement in your source code, the compiler searches for "somefile" only in the directories specified with the Include (-I) option.

If you put an #include "somefile" statement in your code, the compiler will search for "somefile" in the following order:

1. the same directory as the file containing the #include statement.

2. the directories of files that include (#include) that file.

3. the current directory

4. the directories specified with the Include (-I) option.

Library file search algorithms

The library file search algorithms are similar to those for include files:

Implicit libraries: The Borland C++ compiler searches for implicit libraries only in the specified library directories; this is similar to the search algorithm for #include <somefile>.

Implicit library files are the ones the compiler automatically links in and the start-up object file (C0x.OBJ).

Explicit libraries: Where the compiler searches for explicit (user-specified) libraries depends in part on how you list the library file name. Explicit library files are ones you list on the command line or in a project file; these are file names with a .LIB extension.

If you list an explicit library file name with no drive or directory (like this: mylib.lib), the compiler first searches for that library in the current directory. If the first search is unsuccessful, the compiler looks in the directories specified with the Library (-L) option. This is similar to the search algorithm for #include "somefile".

If you list a user-specified library with drive and/or directory information (like this: c:\mystuff\mylib1.lib), C++Builder searches only in the location you explicitly listed as part of the library path name and not in any specified library directories.


C++-specific options

See also

The C++ options affect compilation of all C and C++ programs. For most of the C++ options, you'll usually want to use the default settings.

The subtopics are

C++ compatibility options

Virtual table options

Template options

Exception handling/RTTI options


C++ compatibility options

See also

Use the C++ Compatibility options to handle C++ compatibility issues, such as handling char types, specifying options about hidden pointers, passing class arguments, adding hidden members and code to a derived class, passing the this pointer to Pascal member functions, changing the layout of classes, or insuring compatibility when class instances are shared with non-C++ code or code compiled with previous versions of Borland C++.

Don't restrict scope of 'for' loop expression variables

Calling convention mangling compatibility

Zero-length empty base classes

Zero-length empty class member functions

Old-style structure layout

Member pointer representation


Don't restrict scope of 'for' loop expression variables option

See also

(Command-line switch: -Vd)

This option lets you specify the scope of variables declared in for loop expressions. The output of the following code segment changes, depending on the setting of this option.

int main(void)

{

for(int i=0; i<10; i++)

{

      cout << "Inside for loop, i = " << i << endl;

}     //end of for-loop block

cout << "Outside for loop, i = " << i << endl;  //error without -Vd

}      //end of block containing for loop

If this option is disabled (the default), the variable i goes out of scope when processing reaches the end of the for loop. Because of this, you'll get an Undefined Symbol compilation error if you compile this code with this option disabled.

If this option is set (-Vd), the variable i goes out of scope when processing reaches the end of the block containing the for loop. In this case, the code output would be:

Inside for loop, i = 0

...

Outside for loop, i = 10

Default = OFF


Calling convention mangling compatibility option

See also

(Command-line switch: -VC)

When this option is set, the compiler disables the distinction of function names where the only possible difference is incompatible code generation options. For example, with this option set, the linker will not detect if a call is made to a _ _fastcall member function with the cdecl calling convention.

This option is provided for backward compatibility only; it lets you link old library files that you cannot recompile.

Default = OFF


Zero-length empty base classes

See also

(Command-line switch: -Ve)

Usually the size of a class is at least one byte, even if the class does not define any data members. When you set this option, the compiler ignores this unused byte for the memory layout and the total size of any derived classes; empty base classes will not consume space in derived classes.

Default = OFF


Zero-length empty class member functions
Zero-length class member functions

See also

(Command-line switch: -Vx)

Usually the size of a data member in a class definition is at least one byte. When this option is enabled, the compiler allows an empty structure of zero length.

Default = OFF


Old-syle structure layout
Old-style structure layout

See also

(Command-line switch: -Vl)

This is a backward compatibility switch that causes the BCC32 C++ compiler to lay out derived classes the same way it did in older versions of Borland C++. Enable this option if you need to compile source files that you intend to use with older versions of Borland C++ (for example, if you need to work with a .DLL that you cannot recompile, or if you have older data files that contain hardwired class layouts).

Default = OFF


Member pointer representation

See also

Use Member Pointers options to direct member pointers and affect how the compiler treats explicit casts.

Support all cases

(Command-line switch: -Vmv)

When this option is enabled, the compiler places no restrictions on where member pointers can point. Member pointers use the most general (but not always the most efficient) representation.

Default = ON

Support multiple inheritance

(Command-line switch: -Vmm)

When this option is enabled, member pointers can point to members of multiple inheritance classes (with the exception of virtual base classes).

Default = OFF

Support single inheritance

(Command-line switch: -Vms)

When this option is enabled, member pointers can point only to members of base classes that use single inheritance.

Default = OFF

Smallest for class

(Command-line switch: -Vmd)

When this option is enabled, member pointers use the smallest possible representation that allows them to point to all members of their particular class. If the class is not fully defined at the point where the member pointer type is declared, the most general representation is chosen by the compiler and a warning is issued.

Default = OFF

Honor declared precision

(Command-line switch: -Vmp)

When this option is enabled, the compiler uses the declared precision for member pointer types. Use this option when a pointer to a derived class is explicitly cast as a pointer-to-member of a simpler base class (when the pointer is actually pointing to a derived class member).

Default = OFF


Virtual table options

See also

The virtual tables options control C++ virtual tables and the expansion of inline functions when debugging.

Smart

(Command-line switch: -V)

This option generates common C++ virtual tables and out-of-line inline functions across the modules in your application. As a result, only one instance of a given virtual table or out-of-line inline function is included in the program.

The Smart option generates the smallest and most efficient executables, but produces .OBJ and .ASM files compatible only with Borland linkers and assemblers.

Default = ON

External

(Command-line switch: -V0)

You use the External option to generate external references to virtual tables. If you don’t want to use the Smart or Local options, use the External and Public options to produce and reference global virtual tables.

When you use this option, one or more of the modules comprising the program must be compiled with the Public option to supply the definitions for the virtual tables.

Default = OFF

Public

(Command-line switch: -V1)

Public produces public definitions for virtual tables. When using the External option (-V0), at least one of the modules in the program must be compiled with the Public option to supply the definitions for the virtual tables. All other modules should be compiled with the External option to refer to that Public copy of the virtual tables.

Default = OFF


Template options

See also

The Template options specify how the compiler generates template instances in C++.

Smart

(Command-line switch: -Jgd)

When the Smart option is set, the compiler generates public (global) definitions for all template instances. If more than one module generates the same template instance, the linker automatically merges duplicates to produce a single copy of the instance.

To generate the instances, the compiler must have available the function body (in the case of a template function) or the bodies of member functions and definitions for static data members (in the case of a template class), typically in a header file.

This is a convenient way of generating template instances.

Default = ON

External

(Command-line switch: -Jgx)

When the External option is set, the compiler generates external references to all template instances.

If you use this option, all template instances that need to be linked must have an explicit instantiation directive in at least one other module.

Default = OFF


C++ Options|Exception handling/RTTI (Project Options)
Exception handling/RTTI options

See also

Use the Exceptions Handling options to enable or disable exception handling and to tell the compiler how to handle the generation of run-time type information.

If you use exception handling constructs in your code and compile with exceptions disabled, you'll get an error.

The options are

Enable exceptions

Exception handling options

Enable run-time type information


Enable Exceptions (Project Options)
Enable exceptions option

See also

(Command-line switch: -x)

When this option is set, C++ exception handling is set. If this option is disabled (-x-) and you attempt to use exception handling routines in your code, the compiler generates error messages during compilation.

Disabling this option makes it easier for you to remove exception handling information from programs; this might be useful if you are porting your code to other platforms or compilers.

Disabling this option turns off only the compilation of exception handling code; your application can still include exception code if you link .OBJ and library files that were built with exceptions enabled (such as the Borland runtime libraries).

Default = ON


Exception Handling (Project Options)
Exception handling options

See also

Enable exception location information

(Command-line switch: -xp)

When this option is set, run-time identification of exceptions is available because the compiler provides the file name and source-code line number where the exception occurred. This enables the program to query file and line number from where a C++ exception was thrown.

Default = OFF

Enable destructor cleanup

(Command-line switch: -xd)

When this option is setand an exception is thrown, destructors are called for all automatically declared objects between the scope of the catch and throw statements.

In general, when you set this option, you should also set Enable Runtime Type Information (-RT) as well.

Destructors are not automatically called for dynamic objects allocated with new, and dynamic objects are not automatically freed.

Default = ON

Enable fast exception prologs

(Command-line switch: -xf)

When this option is set, inline code is expanded for every exception handling function. This option improves performance at the cost of larger executable file sizes.

Default = OFF

Enable slow exception epilogues

(Command-line switch: -xs)

When this option is set, the exception handling epilogue code is not expanded inline. This option decreases performance slightly.

Default = OFF


Enable Runtime Type Information (Project Options)
Enable run-time type information option

See also

(Command-line switch: -RT)

This option causes the compiler to generate code that allows run-time type identification.

In general, if you set Enable Destructor Cleanup (-xd), you will need to set this option as well.

Default = ON


Linker options

See also

Linker options let you control how the linkers combine intermediate files (.OBJ, .LIB, and .RES) into executable (.EXE) and dynamic-link library (.DLL) files. You will usually want to keep the default settings for most options in this section.

The linker options can be broken into the following subtopics

Input options

Map file options

Output options

File addressing options

Application target options

Package options

Warning options


Linker input options

The following options are available to control the input to your link cycles:

Case-sensitive link

Object search paths

No state files (disable incremental linking)


Case-sensitive link

(Command-line switch = /c)

When the Case-Sensitive Link option is set, the linker differentiates between upper and lower-case characters in public and external symbols. Normally, this option should be set, since C and C++ are both case-sensitive languages.

Default = ON


Object search paths

See also

(Command-line switch = /j)

This option lets you specify the directories the linker will search if there is no explicit path given for an .OBJ module in the compile/link statement.

The Specify Object Search Path uses the following command-line syntax:

/j<PathSpec>[;<PathSpec>][...]

The linker uses the specified object search path(s) if there is no explicit path given for the .OBJ file and the linker cannot find the object file in the current directory. For example, the command

ILINK32 /jc:\myobjs;.\objs splash .\common\logo,,,utils logolib

directs the linker to first search the current directory for SPLASH.OBJ. If it is not found in he current directory, the linker then searches for the file in the C:\MYOBJS directory, and then in the .\OBJs directory. However, notice that the linker does not use the object search paths to find the file LOGO.OBJ because an explicit path was given for this file.


No state files

(Command-line switch = /Gn)

This switch suppresses the generation of linker state files, disabling incremental linking. If you use /Gn, subsequent links will take just as long as the first one.

Default = OFF


Map file options

Linker map file options tell the linker what type of map file to produce. These options control the information generated on segment ordering, segment sizes, and public symbols.

By default, the linker creates a map file that contains general segment information, which includes a list of segments, the program start address, and any warning or error messages produced during the link.

For settings other than Off, the map file is placed in the directory where the project makefile is stored.

The map file options are:

Off      (default Segments map file not created)

Publics map

Detailed segments map

Mangled names


Off option (linker map file)
Off option (map file)

(Command-line switch = /x)

This switch turns off the creation of the default linker map file.

By default, the linker generates a map file with that contains general segment information that includes a list of segments, the program start address, and any warning or error messages produced during the link. There is no switch for this setting. Use the /x option to suppress the creation of the default map file.

Default = OFF (Default map file is created)


Publics map option

(Command-line switch = /m)

This option instructs the linker to produce a map file that contains an overview of the application segments and two listings of the public symbols.

The segments listing has a line for each segment, showing the segment starting address, segment length, segment name, and the segment class.

The public symbols are broken down into two lists, the first showing the symbols in sorted alphabetically, the second showing the symbols in increasing address order. Symbols with absolute addresses are tagged Abs.

A list of public symbols is useful when debugging: many debuggers use public symbols, which lets you refer to symbolic addresses while debugging.


Detailed segments map option

(Command-line switch = /s)

The Detailed Segments option creates the most comprehensive map file by adding a detailed map of segments to the map file created with the Publics option (/m). The detailed list of segments contains the segment class, the segment name, the segment group, the segment module, and the segment ACBP information. If the same segment appears in more than one module, each module appears as a separate line.

The ACBP field encodes the A (alignment), C (combination), and B (big) attributes into a set of four bit fields, as defined by Intel. ILINK32 uses only three of the fields: A, C, and B. The ACBP value in the map is printed in hexadecimal. The following field values must be ORed together to arrive at the ACBP value printed.

Field	Value	Description

A (alignment)	00	An absolute segment

20	A byte-aligned segment

40	A word-aligned segment

60	A paragraph-aligned segment

80	A page-aligned segment

A0	An unnamed absolute portion of storage

C (combination)	00	Cannot be combined

08	A public combining segment

B (big)	00	Segment less than 64K

02	Segment exactly 64K

With the Segments options set, public symbols with no references are flagged idle. An idle symbol is a publicly defined symbol in a module that was not referenced by an EXTDEF record or by any other module included in the link. For example, this fragment from the public symbol section of a map file indicates that symbols Symbol1 and Symbol3 are not referenced by the image being linked:

0002:00000874     Idle     Symbol1

0002:00000CE4              Symbol2

0002:000000E7     Idle     Symbol3


Mangled names option (map file)

(Command-line switch = /M)

Prints the mangled C++ identifiers in the map file, not the full name. This can help you identify how names are mangled (mangled names are needed as input by some utilities).

Default = OFF


Linker output options

The following linker output options are available:

Include debug information

Subsystem version (major.minor)

Calculate checksum


Include debug information

(Command-line switch = /v)

When the Include Debug Information option is on, the linker includes information in the output file needed to debug your application with the C++Builder integrated debugger or Turbo Debugger.

On the command line, this option causes the linker to include debugging information in the executable file for all object modules that contain debugging information. You can use the /v+ and /v- options to selectively enable or disable debugging information on a module-by-module basis (but not on the same command-line where you use /v). For example, the following command includes debugging information for modules mod2 and mod3, but not for mod1 and mod4:

ILINK32 mod1 /v+ mod2 mod3 /v- mod4

Default = ON in IDE; OFF on the command line


Subsystem version
Subsystem version (major.minor)

(Command-line switch = /Vd.d)

This option lets you specify the Windows version ID on which you expect your application will be run. The linker sets the Subsystem version field in the .EXE header to the number you specify in the input box.

You can also set the Windows version ID in the SUBSYSTEM portion of the module definition file (.DEF file) However, any version setting you specify in the IDE or on the command line overrides the setting in the .DEF file.

Command-line usage

When you use the /Vd.d command-line option, the linker sets the Windows version ID to the number specified by d.d. For example, if you specify /V4.0, the linker sets the Subsystem version field in the .EXE header to 4.0, which indicates a Windows 95 application.

Default = 4.0


Calculate checksum

(Command-line switch = /Gz)

The /Gz option calculates the checksum of the target and places the result in the target’s PE header. This is used for NT Kernel mode drivers and system DLLs.

Default = OFF


Linker file addressing options

The following linker output file addressing options are available:

Image base address (in hexadecimal)

File alignment (in hexadecimal)

Object alignment (in hexadecimal)

Reserved stack size (in hexadecimal)

Commit stack size (in hexadecimal)

Reserved heap size (in hexadecimal)

Commit heap size (in hexadecimal)


Image base address (in hexadecimal)
Image base address

The following switches allow you to specify a base address for an executable or library. (The default address is 0x400000 for Win32 systems.) These options improve both load-time and runtime performance, since the operating system no longer has to apply internal fixups.

These switches accept either decimal or hexadecimal numbers as the image base address.

/b is the preferred switch for this purpose.

Specify image base address

(Command-line switch = /b:xxxx)

Use this option to specify an image base address for your executable or DLL. The load address of the first object in the application or library is set to the number you specify, if possible, and all successive objects are aligned on 64K linear address boundaries; internal fixups are ignored. However, if the module cannot be loaded using the specified address, the operating system reverts to its default setting and applies internal fixups.

Default = OFF

Specify image base address; remove relocation table

(Command-line switch = /B:xxxx)

/B does the same thing as /b, except that it discards the module’s relocation table. Internal fixups are removed from the image and the requested load address of the first object in the application is set to the number you specify. Although this option can reduce the size of your final application module, it is not recommended for producing DLLs.

Default = OFF


File alignment
File alignment (in hexadecimal)

(Command-line switch = /Af:xxxx)

The File Alignment option specifies page alignment for code and data within the executable file. The linker uses the file alignment value when it writes the various objects and sections (such as code and data) to the file. For example, if you use the default value of 0x200, the linker stores the section of the image on 512-byte boundaries within the executable file.

When using this option, you must specify a file alignment value that is a power of 2, with the smallest value being 16.

The old style of this option (/A:dd) is still supported for backward compatibility. With this option, the decimal number dd is multiplied by the power of 2 to calculate the file alignment value.

The command-line version of this option (/Af:xxxx) accepts either decimal or hexadecimal numbers as the file alignment value. The value setting is 512 (0x200).

Default = 512 (0x200)


Object alignment
Object alignment (in hexadecimal)

(Command-line switch = /Ao:xxxx)

The linker uses the object alignment value to determine the virtual addresses of the various objects and sections (such as code and data) in your application. For example, if you specify an object alignment value of 8192, the linker aligns the virtual addresses of the sections in the image on 8192-byte (0x2000) boundaries.

When using this option, you must specify an object alignment value that is a power of 2, with the smallest value being 4096 (the default).

The command-line version of this option (/Ao:xxxx) accepts either decimal or hexadecimal numbers as the object alignment value.

Default = 4096 (0x1000)


Reserve stack size
Reserved stack size

(Command-line switch = /S:xxxx)

Use this option to specify the size of the reserved stack in hexadecimal or decimal. The minimum allowable value for this field is 4K (0x1000).

Specifying the reserved stack size here overrides any STACKSIZE setting in a module definition file.

Default = 1Mb (0x1000000)


Commit stack size
Committed stack size

(Command-line switch = /Sc:xxxx)

Use this option to specify the size of the committed stack in hexadecimal or decimal. The minimum allowable value for this field is 4K (0x1000) and any value specified must be equal to or less than the Reserved Stack Size setting (/S).

Specifying the committed stack size here overrides any STACKSIZE setting in a module definition file.

Default = 8K (0x2000)


Reserved heap size

(Command-line switch = /H:xxxx)

Use this option to specify the size of the reserved heap in hexadecimal or decimal. The minimum allowable value for this field is 0.

Specifying the reserved heap size here overrides any HEAPSIZE setting in a module definition file.

Default = 1Mb (0x1000000)


Commited heap size
Committed heap size

(Command-line switch = /Hc:xxxx)

Use this option to specify the size of the committed heap in hexadecimal or decimal. The minimum allowable value for this field is 0 and any value specified must be equal to or less than the Reserved Heap Size setting (/H).

Specifying the committed heap size here overrides any HEAPSIZE setting in a module definition file.

Default = 4K (0x1000)


Application target options

See also

The following options tell the linkers what type of application image to build.

The following options are not needed if you include a module definition file in your compile and link commands that specifies the type of 32-bit application you intend to build.

Link using 32-bit Windows API

(Command-line switch = /aa)

The linker generates a protected-mode executable that runs using the 32-bit Windows API.

Link for 32-bit console application

(Command-line switch = /ap)

The linker generates a 32-bit protected-mode executable file that runs in console mode.

Link 32-bit .DLL file

(Command-line switch = /Tpd)

The linker generates a 32-bit protected-mode Windows .DLL file.

Link 32-bit .EXE file

(Command-line switch = /Tpe)

The linker generates a 32-bit protected-mode Windows .EXE file.

Generate package (/Tpp)


Package linker options
Package options

See also

The following options apply to packages.

Build project as package

(Command-line switch = /Tpp)

The linker generates a package. This switch is included automatically in package makefiles.

Generate runtime-only package

(Command-line switch = /Gpr)

Generates a runtime-only package. (If neither /Gpr nor /Gpd is used, the resulting package works at both design time and runtime.)

Generate design-time–only package

(Command-line switch = /Gpd)

Generates a design-time–only package. (If neither /Gpr nor /Gpd is used, the resulting package works at both design time and runtime.)

Save generated BPI file

(Command-line switch = /Gi)

Saves the generated .BPI file. This switch is included automatically in package makefiles.

Generate LIB file

(Command-line switch = /Gl)

Generates a .LIB file.

Save specified description with package

(Command-line switch = /D:xxxx)

Saves the specified description.


Linker warnings

Warning options enable or disable the display of ILINK32 warnings. The warnings are

Warn duplicate symbol in .LIB

"No Stack" warning

No program entry point

Public symbol 'symbol' defined in both module 'module1' and 'module2' (Duplicate symbols)

No module definition file

Import record does not match previous definition

Using based linking for DLLs may cause the DLL to malfunction

Self-relative fixup overflowed

Image linked as .EXE but with .DLL extension

Multiple stack segments found


Warn duplicate symbol in .LIB

(Command-line switch = /wdpl)

When the Warn Duplicate Symbols option is on, the linker warns you if a symbol appears in more than one object or library files.

If the symbol must be included in the program, the linker uses the symbol definition from the first file it encounters with the symbol definition.

Use the command-line option /w-dpl to turn this warning off.

Default = OFF


"No stack" warning

(Command-line switch = /wstk)

This option lets you control whether or not the linker emits the "No stack" warning. The warning is generated if no stack segment is defined in any of the object files or in any of the libraries included in the link. Except for .DLLs, this indicates an error. If a C++Builder program produces this error, make sure you are using the correct C0x startup object file.

Use the command-line option /w-stk to turn this warning off.

Default = OFF


Warning message options

See also

The Warning Message Options let you control the messages generated by the compiler. Messages are indicators of potential trouble spots in your program. These messages can warn you of many problems that may be waiting to happen, such as variables and parameters that are declared but never used, type mismatches, and many others.

Setting a message option causes the compiler to generate the associated message or warning when the specific condition arises. Note that some of the messages are on by default.

The different compiler messages can be broken in to the following subtopics

Portability

ANSI violations

Obsolete C++

Potential C++ errors

Inefficient C++ coding

Potential errors

Inefficient coding

General

User-defined warnings

Displaing warnings

Selecting warnings

Stop after n warnings

Stop after n errors


Portability message options

See also

Portability options enable or disable individual warning messages about statements that might not operate correctly in all computer environments.

Option	Command-line switch	Default

Non-portable pointer conversion	     -w-rpt	ON

Non-portable pointer comparison	     -w-cpt	ON

Constant out of range in comparison	     -w-rng	ON

Constant is long	     -wcln	OFF

Conversion may lose significant digits	     -wsig	OFF

Mixing pointers to signed and unsigned char	     -wucp	OFF


ANSI violation message options

See also

ANSI violations message options enable or disable individual warning messages about statements that violate the ANSI standard for the C language.

Option	Command-line switch	Default

Void functions may not return a value	     -w-voi	ON

Both return and return of a value used	     -w-ret	ON

Suspicious pointer conversion	     -w-sus	ON

Undefined structure 'ident'	     -wstu	OFF

Redefinition of 'ident' is not identical	     -w-dup	ON

Hexadecimal value more than three digits	     -w-big	ON

Bit fields must be signed or unsigned int	     -wbbf	OFF

'ident' declared as both external and static	     -w-ext	ON

Declare 'ident' prior to use in prototype	     -w-dpu	ON

Division by zero	     -w-zdi	ON

Initializing 'ident' with 'ident'	     -w-bei	ON

Initialization is only partially bracketed	     -wpin	OFF

Non-ANSI keyword used 	     -wnak	OFF


Obsolete C++ message options

See also

Obsolete C++ message options let you choose the obsolete items or incorrect syntax C++ warnings display.

Option	Command-line switch	Default

Base initialization without class name is obsolete	     -w-obi	ON

This style of function definition is obsolete	     -w-ofp	ON

Overloaded prefix operator used as a postfix operator	     -w-pre	ON


Potential C++ error message options

See also

Potential C++ errors message options enable or disable individual warning messages about statements that violate C++ language implementation.

Option	Command-line switch	Default

Constant member 'ident' is not initialized	     -w-nci	ON

Assigning 'type' to 'enumeration'	     -w-eas	ON

'function' hides virtual function 'function2'	     -w-hid	ON

Non-const function <function> called for const object	     -w-ncf	ON

Base class 'ident' inaccessible because also in 'ident'	     -w-ibc	ON

Array size for 'delete' ignored	     -w-dsz	ON

Use qualified name to access nested type 'ident'	     -w-nst	ON

Handler for '<type1>' Hidden by Previous Handler for '<type2>'	     -w-hch	ON

Conversion to 'type' will fail for virtual base members	     -w-mpc	ON

Maximum precision used for member pointer type <type>	     -w-mpd	ON

Use '> >' for nested templates instead of '>>'	     -w-ntd	ON

Non-volatile function <function> called for volatile object	     -w-nvf	ON


Inefficient C++ coding message options

See also

Inefficient C++ coding message options enable or disable individual warning messages about inefficient C++ coding.

Option	Command-line switch	Default

Functions containing 'ident' not expanded inline	     -w-inl	ON

Temporary used to initialize 'ident'	     -w-lin	ON

Temporary used for parameter 'ident'	     -w-lvc	ON


Potential error message options

See also

Potential error message options enable or disable individual warning messages about potential coding errors.

Option	Command-line switch	Default

Possibly incorrect assignment	     -w-pia	ON

Possible use of 'ident' before definition	     -wdef	OFF

No declaration for function 'ident'	     -wnod	OFF

Call to function with no prototype	     -w-pro	ON

Function should return a value	     -w-rvl	ON

Ambiguous operators need parentheses	     -wamb	OFF

Condition is always (true/false)	     -w-ccc	ON

Continuation character \ found in //	     -w-com	ON


Inefficient coding message options

See also

Inefficient coding message options are used to enable or disable individual warning messages about inefficient coding.

Option	Command-line switch	Default

'ident' assigned a value which is never used	     -w-aus	ON

Parameter 'ident' is never used	     -w-par	ON

'ident' declared but never used	     -wuse	OFF

Structure passed by value	     -wstv	OFF

Unreachable code	     -w-rch	ON

Code has no effect	     -w-eff	ON

The warnings Unreachable Code and Code Has No Effect can indicate serious coding problems. If the compiler generates these warnings, be sure to examine the lines of code that cause these warnings.


General message options

See also

General message options enable or disable a few general warning messages.

Option	Command-line switch	Default

Unknown assembler instruction	     -wasm	OFF

Ill-formed pragma	     -w-ill	ON

Array variable 'ident' is near	     -w-ias	ON

Superfluous & with function	     -wamp	OFF

'ident' is obsolete	     -w-obs	ON

Cannot create precompiled header	     -w-pch	ON

User-defined messages	     -w-msg	ON


User-defined warnings
User-defined messages

See also

(Command-line switch: -wmsg)

The user-defined messages option allows user-defined messages to appear in the IDE's Message window. User-defined messages are introduced with the #pragma message compiler syntax.

In addition to messages that you introduce with the #pragma message compiler syntax, User-defined messages displays messages introduced by third-party libraries. If you need Help concerning a message generated by third-party libraries, please contact the vendor of the header file that issued the message.

Default = ON


Display warnings
Display warnings options

See also

Use the Display Warnings options to choose which warnings are displayed by the compiler.

All

(Command-line switch: -w)

Display all warning and error messages.

Default = OFF

Selected

(Command-line switch: -wxxx)

Choose which warnings are displayed. xxx is the three-letter or four-digit message identifier used by the command-line option. Using pragma warn in your source code overrides messages options set either at the command line or in the IDE.

To disable a message from the command line, use the command-line option -w-xxx.

Default = Refer to the individual messages for their default status


Stop after n warnings

See also

(Command-line switch: -gn)

Warnings: Stop After causes compilation to stop after the specified number of warnings has been detected. You can enter any number from 0 to 255.

Entering 0 causes compilation to continue until either the end of the file or the error limit set in Stop after n errors has been reached, whichever comes first.

Default = 100


Stop batch compile after warnings

See also

(Command-line switch: -gb)

This option aborts batch compilations after the first file that causes warnings. For example,

BCC32 –c -gb *.ccp

BCC32 –c –gb file1.cpp file2.cpp

Without the –gb flag, batch compilations continue to the next scheduled file, even after an earlier file has caused a warning.

Default = OFF


Stop after n errors

See also

(Command-line switch: -jn)

Errors: Stop After causes compilation to stop after the specified number of errors has been detected. You can enter any number from 0 to 255.

Entering 0 causes compilation to continue until the end of the file or the warning limit set in Stop after n warnings has been reached, whichever comes first.

Default = 25


Stop batch compile after errors

See also

(Command-line switch: -jb)

This option aborts batch compilations after the first file that causes errors. For example,

BCC32 –c -gb *.ccp

BCC32 –c –gb file1.cpp file2.cpp

Without the –jb flag, batch compilations continue to the next scheduled file, even after an earlier file has caused a error.

Default = OFF


Optimization options

See also

Optimization options are the software equivalent of performance tuning. There are two general types of compiler optimizations:

Those that make your code smaller

Those that make your code faster

Although you can compile with optimizations at any point in your product development cycle, be aware when debugging at the assembly level that some assembly instructions might be "optimized away" by certain compiler optimizations.

C++Builder predefined optimization settings

C++Builder offers predefined optimization settings on the Compiler page of the Project Options dialog box. Because of the complexities involved with setting compiler optimizations, it is recommended that you use one of these predefined optimization settings while compiling C++Builder applications.

If you need to further customize the compiler optimizations, use the following options from the command line or by editing the project file:

Aggregate optimizations

Jump optimization

Eliminate duplicate expressions

Inline intrinsic functions

Induction variables

Pentium instruction scheduling


Aggrigate optimization options
Aggregate optimization options

See also

Disable all optimizations

(Command-line switch: -Od)

Disables all optimization settings, including ones which you may have specifically set and those which would normally be performed as part of the speed/size tradeoff.

Because this disables code compaction (tail merging) and cross-jump optimizations, using this option can keep the debugger from jumping around or returning from a function without warning, which makes stepping through code easier to follow.

Optimize for size

(Command-line switches: -O1)

This switch sets an aggregate of optimization options that tells the compiler to optimize your code for size. For example, the compiler scans the generated code for duplicate sequences. When such sequences warrant, the optimizer replaces one sequence of code with a jump to the other and eliminates the first piece of code. This occurs most often with switch statements. The compiler optimizes for size by choosing the smallest code sequence possible.

Optimize for speed

(Command-line switch: -O2)

This switch sets an aggregate of optimization options that tells the compiler to optimize your code for speed.


Jump optimization option

See also

(Command-line switch: -O)

When Jump Optimization is set, the compiler reduces the code size by eliminating redundant jumps and reorganizing loops and switch statements.

When this option is set, the sequences of stepping in the debugger can be confusing because of the reordering and elimination of instructions. If you are debugging at the assembly level, you might want to disable this option.

Default = ON


Eliminate duplicate expressions option

See also

(Command-line switch: -Oc)

When this option is set, the compiler eliminates common subexpressions within groups of statements unbroken by jumps (basic blocks) and functions. This option globally eliminates duplicate expressions within the target scope and stores the calculated value of those expressions once (instead of recalculating the expression).

Although this optimization could theoretically reduce code size, it optimizes for speed and rarely results in size reductions. Use this option if you prefer to reuse expressions rather than create explicit stack locations for them.

The -Og compiler option is supported for backward compatibility only, and is equivalent to the -Oc compiler option.


Inline intrinsic functions option

See also

(Command-line switch: -Oi)

When Inline Intrinsic Functions is set, the compiler generates the code for common memory functions like strcpy() within your function's scope. This eliminates the need for a function call. The resulting code executes faster, but it is larger.

The following functions are inlined with this option:

alloca	fabs	memchr	memcmp

memcpy	memset	rotl	rotr

stpcpy	strcat	strchr	strcmp

strcpy	strlen	strncat	strncmp

strncpy	strnset	strrchr

You can control the inlining of these functions with the pragma intrinsic. For example, #pragma intrinsic strcpy causes the compiler to generate inline code for all subsequent calls to strcpy in your function, and #pragma intrinsic -strcpy prevents the compiler from inlining strcpy. Using these pragmas in a file overrides any compiler option settings.

When inlining any intrinsic function, you must include a prototype for that function before you use it; the compiler creates a macro that renames the inlined function to a function that the compiler recognizes internally. In the previous example, the compiler would create a macro #define strcpy __strcpy__.

The compiler recognizes calls to functions with two leading and two trailing underscores and tries to match the prototype of that function against its own internally stored prototype. If you don't supply a prototype, or if the prototype you supply doesn't match the compiler's prototype, the compiler rejects the attempt to inline that function and generates an error.


Induction variables option

See also

(Command-line switch: -Ov)

When this option is set, the compiler creates induction variables and it performs strength reduction, which optimizes for loops speed.

Use this option when you're compiling for speed and your code contains loops. The optimizer uses induction to create new variables (induction variables) from expressions used in loops. The optimizer assures that the operations performed on these new variables are computationally less expensive (reduced in strength) than those used by the original variables.

Optimizations are common if you use array indexing inside loops, because a multiplication operation is required to calculate the position in the array that is indicated by the index. For example, the optimizer creates an induction variable out of the operation v[i] in the following code because the v[i] operation requires multiplication. This optimization also eliminates the need to preserve the value of i:

int v[10];

void f(int x, int y, int z)

{

  int i;

  for (i = 0; i < 10; i++)

     v[i] = x * y * z;

}

With Induction variables set, the code changes:

int v[10];

void f(int x, int y, int z)

{

  int i, *p;

  for (p = v; p < &v[9]; p++)

    *p = x * y * z;

}


Pentium instruction scheduling option

See also

(Command-line switch: -OS)

When set, this switch rearranges instructions to minimize delays that can be caused by Address Generation Interlocks (AGI) which occur on the i486 and Pentium processors. This option also optimizes the code so that it takes advantage of the Pentium parallel pipelines. Best results for Pentium systems are obtained when you use this switch in conjunction with the Generate Pentium Instructions option (-5).

Scheduled code is more difficult to debug at the source level because instructions from a particular source line may be mixed with instructions from other source lines. Stepping through the source code is still possible, although the execution point might make unexpected jumps between source lines as you step. Also, setting a breakpoint on a source line may result in several breakpoints being set in the code. This is especially important to note when inspecting variables, since a variable may be undefined even though the execution point is positioned after the variable assignment.

Stepping through the following function when this switch is set demonstrates the stepping behavior:

int v[10];

void f(int i, int j)

{

int a,b;

a = v[i+j];

b = v[i-j];

v[i] = a + b;

v[j] = a - b;

}

Execution starts by computing the index i-j in the assignment to b (note that a is still undefined although the execution point is positioned after the assignment to a). The index i+j is computed, v[i-j] is assigned to b, and v[i+j] is assigned to a. If a breakpoint is set on the assignment to b, execution will stop twice: once when computing the index and again when performing the assignment.

Default = OFF (-O-S)


SQL Explorer
SQL/Database Explorer

The SQL/Database Explorer enables you to maintain a persistent connection to a remote database server during application development and to work with BDE aliases and metadata objects.  With the SQL/Database Explorer, you can create, view, and modify:

BDE aliases.

Metadata objects such as tables, views, triggers, and stored procedures.

Users and server security information.

The All Database Aliases pane of the SQL/Database Explorer displays all valid, defined aliases.  Select an alias to display the its definition.

To connect to the database specified by an alias,

1.	Select the alias in the All Database Aliases pane.

2.	Do one of the following,

Choose Object|Open.

From the context menu, choose Open.

When you are connected to a database, the icon in the left pane will turn green.

To expand a database,

In the All Database Aliases pane, click "+” next to the alias you want to view. The native server object types expand beneath the icon.

Once connected to a database, you can perform SQL operations on the database.

To perform SQL operations,

1.	Select the Enter SQL tab.

2.	Enter SQL statements in the statement area.

3.	Click on the Execute button.

Your SQL statements will execute and the results will be displayed in the table grid.


Using the Database Form wizard

See also

The Database Form wizard enables you to easily generate a form that displays data from an external InterBase, Paradox, dBase, IBM-DB2, Sybase, Informix, or ORACLE database.

The Database Form wizard helps you create two types of database forms,

Simple database forms

Master-detail forms

The tool automates such form building tasks as

Connecting the form to Table and Query components.

Writing SQL statements for Query components.

Placing interactive and non-interactive components on a form.

Defining a tab order.

Connecting DataSource components to interactive components and Table/Query components.


Creating a form using the Database Form wizard

See also

You can use the Database Form wizard to create a simple information form.

To build a form using the Database Form wizard,

1.	Open the Database Form wizard by choosing Database|Form wizard.

2.	Select a Form Option. A simple form uses one table. A master/detail form creates a link from a detail table to a master, or summary, table and displays only those records in the detail table that are linked to the current record in the master table (in C++Builder’s sample files, CUSTOMERS.DB would be a master table and ORDERS.DB would be an associated detail table).

3.	Select a Dataset Option. A table will provide access to all records (rows) and all fields selected later in the Form wizard. A query will allow you to limit the records (rows) retrieved by specifying retrieval criteria.

4.	Click Next.

5.	Select an an alias from the Drive or Alias Name list. Select the BCDEMOS alias to create a sample form with C++Builder’s sample database files. To create an alias, see the online help for the BDE Administration Utility.

If you have not created an alias, select the drive and directory containing the database in the Form wizard dialog box.

6.	Select the fields to use on the generated form:

To use only some of the fields,

1.	Press and hold Ctrl.

2.	Select each field you want from the Available Fields list.

3.	Choose the > button.

To use all of the fields from the Available Fields list, click the button marked >>.

To remove fields from the Selected Fields list, click the buttons marked < or <<.

To reorder the fields in the Selected Fields list,

1.	Select a field to move.

2.	Choose the Up or Down button to change the field's position in the list.

For the purposes of this exercise, use all the fields from the Available Fields list.

3.	Choose Next to proceed.

The next Form wizard screen presents options for displaying the selected fields on the form. The wizard explains and illustrates each of your choices. For the purposes of this exercise, choose the Vertical option.

The Form wizard generates text labels for each of the data entry components in the generated form when you opt for a vertical layout. You can choose the way these labels are displayed in relation to the data entry fields. The screen explains and illustrates your choices. For this exercise, choose the Left option, then choose Next to proceed.

Select a method for generating the form. You may choose to generate only a form when your application will contain only one dataset or choose to generate both a form and a data module if your application will contain several datasets or data sources and you want to centralize their access or re-use standard designs.

4.	Choose the Finish button to generate the form.

The Form wizard generates a database form based on your choices.


Write Block To File dialog box

See also

This dialog box enables you to specify the filename and location of an operating system file in which you want to write a block of text you have selected in the Code Editor Window.

When using default key mapping, access this dialog box with: Ctrl+K+W


Read File As Block dialog box

See also

This dialog box enables you to specify the filename and location of an operating system file containing a block of Object Pascal source code which you want to insert in the Code Editor Window at the current cursor position.

When using default key mapping, access this dialog box with: Ctrl+K+R


Using the Code editor

See also

The C++Builder Code editor provides a convenient and reliable way to view and modify your source code. It is a full-featured, customizable editor that offers many powerful features, such as:

Syntax highlighting

Multiple and Group Undo

Five predefined editor settings: Default, IDE Classic, Brief, Epsilon, and Visual Studio

Context-sensitive Help for language elements

C++Builder generates a page in the Code editor in the following situations:

Whenever you create a new project

Whenever you add a form or unit to a project

Whenever you open a file, even if you do not add it to the project file

You can also use the Code editor to open text files for viewing or modification.

To open a Code editor page,

Add a new form, unit or other file to a project.

To select a Code editor page,

In the Code editor window, click the tab corresponding to the page you want to view or modify.

To modify text in the Code editor,

1. Position the cursor at the position you want new text to begin.

2. Type in the new text, pressing Enter to end each line.

To insert a code template

Press <ctrl>-j to see a pop-up list of templates.

(To configure templates, use the Code Insight page of the Environment Options dialog.)

To close a Code editor page do one of the following:

Right-click the Code editor window, then choose Close Page.

Choose File|Close.

To close all Code editor pages and the project, do one of the following:

Select the Code editor page you wish to close, then choose File|Close.

Click the close button in upper right corner of the code editor window.

If you have modified code in a page and have not saved the changes, C++Builder opens the Save File As dialog box, where you can enter a file name.

If you have modified the project and have not saved the changes, C++Builder opens the Save As dialog box, where you can enter a name for the project.


Searching in the Code editor

See also

You can use the Search menu (located on the Main menu) to locate specific text in the Code editor. Use the Search menu commands to locate text, objects, units, variables, and symbols in the Code editor.

The commands in the Search menu are as follows:

Find searches for specific text.

Replace searches for specific text and replaces it with new text.

Search Again repeats a search.

Incremental Search searches for text as you type.

Find In Files searches for specific text accross entire projects, accross specified directories, and accross all open files.

Go to Line Number moves the cursor to a specific line number.

Go to Address becomes available when the CPU window is active; this command moves the Disassembly pane display to the address you specify.

To learn more about any of the commands on the Search menu, select the command and press F1.


Viewing the associated form

See also

When viewing and editing source code, you can easily switch between the code and the associated form to see how your design changes effect your code, and vice versa. Because C++Builder is a two-way tool, object declarations and definitions that you add to your source code are immediately reflected on the form that you add them to.

Use any of the following methods to view a project form:

Click any part of the form that is visible under the Code editor to view the form associated with the currently displayed source file.

Choose View|Forms to open the View Form dialog box, then choose any form in the project that you want to view.

Use toolbar buttons to toggle between the unit and form, or to open the View Form dialog box.

Note:	If you view a form that is different from the one associated with the currently displayed code in the editor, the editor changes code pages to keep in sync with the selected form. Because of this, when you return to the Code editor, it might not display the code you were previously viewing.


Customizing the editor

See also

You can choose one of the predefined editor settings. If you want, you can then customize the behaviors and appearance of that editor by

Use the Editor SpeedSetting on the Editor page of the Tools|Environment Options dialog box to select the default keymappings of your editor.

Use the Colors page of the Tools|Environment Options dialog box to specify how you want the different elements of your code to appear in the Code editor.

Use the Display page of the Tools|Environment Options dialog box to customize the display and font options for your Code editor.

Use the Code Insight page of the Tools|Environment Options dialog box to enable and configure Code Insight features. See About Code Insight for more information on these features.


Using the Form editor

The C++Builder Form editor provides a convenient and reliable way to create forms that include visual and non-visual components. C++Builder generates a form in the Form editor in the following situations:

Whenever you add a form to a project.

Whenever you create a form using the Object Repository.

To add components to the form,

Select the component and drag it onto the form.

To close a Form editor page,

Select the Form editor page you want to close, then choose File|Close.

Or,

Click the close button in the upper right corner of the Form editor window.

To close all Form editor pages and the project,

Choose File|Close All.

Or,

Choose File|New Application.

If you have modified a form and have not saved the changes, C++Builder opens the Save File As dialog box, where you can enter a file name.

If you have modified the project and have not saved the changes, C++Builder opens the Save As dialog box, where you can enter a name for the project.

To get context-sensitive Help from the Form editor window, place the cursor on the component for which you want Help, then press F1.


Alignment palette context menu

The Alignment palette context menu contains the following commands:

Stay On Top

Show Hints

Hide

Help


Stay On Top (Alignment palette context menu)

Choose Stay On Top from the Alignment palette context menu to keep the Alignment palette in front of all other windows and dialog boxes.


Hide (Toolbar/Component Palette context menu)
Hide

Right click and choose Hide from the following context menus to close that interface element.

Alignment Palette context menu

Component Palette context menu

Object Inspector context menu

If you close an interface element, you can display it again using the View menu.


Show Hints

Right click and choose Show Hints from the following context menus to toggle the display of Help Hints.

Alignment Palette context menu

Component Palette context menu

When this command is checked, Help Hints are enabled.


Help (Toolbar context menu)
Help

Right click and choose Help from any of the following context menus to get Help on using that element.

Alignment Palette context menu

Component Palette context menu

Object Inspector context menu


Find Declaration (Code editor context menu)

See Also

Choose Find Declaration to open the source or header file where a particular class is declared. The appropriate file is opened in the code editor window with the cursor on the class declaration.

Note:	 this command only appears when the caret is on a class name (such as TForm1).


Close Page (Code editor context menu)

Choose Close Page from the Code editor context menu to close the current page in the Code editor window.

If you have modified code, not saved the changes, and this is the last page open in a file, C++Builder opens the Save As dialog box, where you can enter a new file name.

If you are closing the last page in the project and have not saved it yet, C++Builder opens the Save As dialog box, where you can enter a name for the project.


Open File At Cursor (Code editor context menu)

See Also

Choose Open File At Cursor from the Code editor context menu to open the file at the current cursor position.

C++Builder searches for files with the default extension of .CPP, unless another file extension is explicitly specified. Similarly, C++Builder uses the directory settings for unit and include files specified in the Directories/Conditionals page of the Options|Project dialog box.

To change directory settings for unit and include files,

1.	Choose Options|Project from the main C++Builder menu.

2.	Click the Directories/Conditionals page.

3.	Set unit and include directories as you want.

4.	Choose OK to put your choices into effect.


New Edit Window
New Edit Window (Code editor context menu)

See Also

Choose New Edit Window to open a new Code Editor that contains a copy of the active page from the original Code editor.

Any changes you make to either the original or the copy are reflected in both files.

So that you can distinguish between the windows, the caption in the original window is postfixed with a 1, the first copy with a 2, the second copy with a 3, and so on.


Topic Search (Code editor context menu)

Choose Topic Search from the Code editor context menu to display a Help window for the word or token at the cursor in the Code editor.

If no Help topic exists, a dialog box is displayed, with the closest match highlighted.


Run To Cursor (Code editor context menu)

Choose Run To Cursor to run the loaded program up to the location of the cursor in the Module window.

When you run to the cursor, your program is executed at full speed, then pauses and places the execution point on the line of code containing the cursor.

You can use Run To Cursor to run your program and pause before the location of a suspected problem. You can then use Run|Step Over or Run|Trace Into to control the execution of individual lines of code.

An alternative way to perform this command is:

Choose Run|Run To Cursor.


Inspect (Code editor context menu)

See Also

Choose Inspect to to open an Inspector window for the term at the curent insertion point. If the insertion point is on a blank space when you choose this command, an empty Inspector window displays where you can enter an item you want to inspect.

This command is available only while you run your program from the IDE.


Evaluate/Modify (Code editor context menu)

See also

The Evaluate/Modify command opens the Evaluate/Modify dialog box, which lets you evaluate or change the value of an existing expression.

An alternate way to perform this command is:

Choose Run|Evaluate/Modify from the main menu.


Add Watch at Cursor (Code editor context menu)

See also

The Add Watch at Cursor command opens the Watch Properties dialog box, where you can create and modify watches. After you create a watch, use the Watch List to display and manage the current list of watches.

Alternate ways to perform this command are:

Choose Run|Add Watch from the Code editor context menu.

Choose Add Watch from the Watch List context menu.

Right-click an existing watch in the Watch List and choose Edit Watch from the Watch List context menu.


View as Form (Code editor context menu)

Choose View as form (or View from Text command) from the Code editor context menu to toggle viewing a form file as a text file or a form.

Caution	If you make changes to the text file that are not supported by C++Builder, you will not be able to view the file as a form.


Read Only (Code editor context menu)

Choose Read Only from the Code editor context menu to make the current open file read only. When a file is read only, you cannot make any changes to the file.

When you mark a file as read only this command is checked on the Code editor context menu and "Read only" is displayed in the Code editor status line.


Message View (Code editor context menu)

Choose Message View to move focus to the message view window. This dockable window appears by default at the bottom of the Code editor, and shows messages, warnings, and errors generated as you build your program.


View CPU (Code editor context menu)

See also

Choose this command to display the CPU window with the disassembly pane positioned at the machine address that corresponds to the line currently selected in the Code editor. If the line currently selected does not have a corresponding machine instruction, the disassembly pane is positioned at the instruction at the current execution point.

If the CPU view is already open, it becomes the active view.


Properties (Code editor context menu)

Choose Properties from the Code editor context menu to set editor environment options.


View Source

Positions the Code editor at the source location of the highlighted error, but does not make the Code editor the active window. If the source file is not already open in the Code editor, it appears in a new Code editor page.


Edit Source

Positions the Code editor at the source location of the highlighted error and makes the Code editor the active window. If the source file is not already open in the Code editor, it appears in a new Code editor page.


Component palette context menu

The Component palette context menu enables you to edit or rearrange the components on the Component palette. You can also use the Component palette context menu to hide the Component palette.

Properties

Show Hints

Hide

Help

To display the Component palette context menu,

Right-click anywhere on the ToolBar.


Properties (Component palette context menu)

Choose Properties from the Component palette context menu to open the Palette page

Palette page of the Tools|Environment Options dialog box.

Use this dialog box to rearrange the Components on the Component palette.


Data Module context menu

Right click the Data Module to access the following commands:

Align To Grid	Aligns data-access components to the data module's invisible grid.

Align	Aligns data-access components according to criteria you supply in the Alignment dialog box.

Revert to Inherited	Discards changes made to a data module inherited from another data module in the Object Repository, and reverts to the originally inherited data module.

Creation Order	Enables you to change the order in which data-access components are created at start-up.

Add to Repository	Stores a link to the data module in the Object RepositoryReusing data modules in the Object Repository.

View as Text	Displays the text representation of the data module's properties. You can view the properties as text only when the dataset is not active (Active = false).


Fields editor context menu
Fields editor

The Fields editor lets you add new persistent fields to a dataset and create data fields, calculated fields, and lookup fields.

Use the Fields editor at design time to create persistent lists of the field components used by the datasets in your application. Persistent fields component lists are stored in your application, and do not change even if the structure of a database underlying a dataset is changed. All fields in a dataset are either persistent or dynamic.

To start the fields editor,

Double-click the dataset component.

The Fields editor contains a title bar, navigator buttons, and a list box.

Title bar

The title bar displays the both the name of the data module or form containing the dataset, and the name of the dataset itself.

Navigation buttons

Use these buttons to scroll one-by-one through the records in an active dataset at design time. You can also jump to the first or last record. The buttons are dimmed if the data set is not active or empty.

List box

The List box displays the names of persistent fields components for the dataset. The first time you invoke the Fields editor for a new dataset, the list is empty because the fields components for the dataset are dynamic, not persistent. If you invoke the Fields editor for a dataset that already has persistent fields components, you see the fields component names in the list box.

To add fields to the list of persistent fields for a dataset,

Right-click the list box and choose Add Fields.

Fields editor commands

Right click the Fields editor to access the following commands:

Add fields	Displays the Add Fields dialog box which enables you to add persistent field components for a dataset.

New field	Displays the New Field dialog box which enables you to create new persistent fields as additions to or replacements of the other persistent fields in a dataset.  The types of new persistent fields that may be created are data fields, calculated fields, and lookup fields.

Cut	Removes the selected field component(s) from the list of persistent fields and places them on the clipboard.

Copy	Copies the persistent field component to the clipboard.

Paste	Inserts the contents of the clipboard into the list of persistent field components.  You can only paste persistent field components that reside in the current dataset if the dataset is active.

Delete	Removes persistent field components from the dataset.  Use this to access a subset of available columns in a dataset.  Fields you remove are no longer available to the dataset and cannot be displayed by data-aware controls, but are not removed from the underlying database.  Use Add fields to recreate persistent field components that were accidentally deleted.

Select all	Selects all persistent field components in the Fields editor.

Retrieve attributes	Updates the attributes currently associated with the field component.  To be prompted for a different attribute set, select Associate attributes.  Retrieve attributes is useful when you want to update multiple types of components associated with multiple attribute sets simultaneously.

Save attributes	Stores the current field’s property settings as defined in the Object Inspector as an attribute set in the Data Dictionary.  The name for the attribute set defaults to the name of the current field.

Save attributes as	Stores the current field’s property settings as defined in the Object Inspector as an attribute set in the Data Dictionary and allows you to specify a name other than the field name for the attribute set.

Associate attributes	Applies previously defined attribute set to current field.  If changes are made to the attribute set in the Data Dictionary, those changes are automatically applied to every field associated with the attribute set.

Unassociate attributes	Removes the attribute set from a field component.  After you remove an attribute set from a field component, the attributes remain as they were when they were associated.  You can either use the Object Inspector to set its properties or you can associate the component with a different attribute set.


Save attributes dialog box
Save attributes

When several fields in the datasets used by your application share common formatting properties, it is more convenient to set the properties for a single field, then store those properties as an attribute set in the Data Dictionary. Attribute sets stored in the data dictionary can be easily applied to other fields.

To create an attribute set based on a field component in a dataset,

1	Double-click the dataset to invoke the Fields editor.

2	Select the field for which to set properties.

3	Set the desired properties for the field in the Object Inspector.

4	Right-click the Fields editor list box and choose Save Attributes to save the current field’s property settings as an attribute set in the Data Dictionary.

The name for the attribute set defaults to the name of the current field.

You can also create attribute sets directly from the Database Explorer. When you create an attribute set from the data dictionary, the set is not applied to any fields, but you can specify two additional attributes in the set: a field type and a data-aware control that is automatically placed on a form when a field based on the attribute set is dragged onto the form. For more information, see the online help for the Database Explorer.


Retrieve attributes

Choose Retrieve attributes to update the current field component’s attributes to the attribute set currently saved for the corresponding database field.


Save as attributes
Save attributes as

To save an attribute set and assign it a name that differs from the currently selected field component name, choose Save as attributes, and then enter the new attribute set name.


Associate attributes dialog box
Associate attributes

You can apply attribute sets to fields without having to recreate the settings manually if:

If several fields in datasets used by your application share common formatting properties

and

You have saved those property settings as attribute sets in the Data Dictionary.

If you change the attributes in the Data Dictionary, those changes are automatically applied to every field associated with the set the next time field components are added to the dataset.

To apply an attribute set to a field component,

1	Double-click the dataset to invoke the Fields editor.

2	Select the field for which to apply an attribute set.

3	Right-click the Fields editor list box and choose Associate Attributes.

4	Select or enter the attribute set to apply from the Attribute set name dialog box.

If there is an attribute set in the Data Dictionary that has the same name as the current field, that set name appears in the edit box.


Unassociate attributes

To remove an attribute set assignment for a selected field component, choose Unassociate attributes.


Fields Editor edit options

Right-click the Field editor to access the following commands.

Cut

Use this option to remove selected field from the editor and place them on the Windows clipboard.

Copy

Use this option to copy selected fields to the Windows clipboard.

Paste

Use this option to paste the clipboard contents into an application.

Delete

Use this option to delete selected fields without copying them to the clipboard.

Select All

Use this option to select all the fields in the fields.


Add Fields dialog box

Use the Add Fields dialog box to create a persistent field component for a dataset:

To create a persistent field component for a dataset:

1	Right-click the Fields editor list box and choose Add fields.

The Add Fields dialog box appears. The Available fields list box displays all fields in the dataset which do not have persistent field components.

2	Select the fields for which you want to create persistent field components and then click OK.

Each time you open the dataset, C++Builder no longer creates dynamic field components for every column in the underlying database. It only creates persistent components for the fields you specified.

Each time you open the dataset, C++Builder verifies that each non-calculated persistent field exists or can be created from data in the database. If it cannot, C++Builder raises an exception warning you that the field is not valid, and does not open the dataset.

To delete a persistent field component.

1	Select the field(s) to remove in the Fields editor list box.

2	Press the Delete key.

Fields you remove are no longer available to the dataset and cannot be displayed by data aware controls.


New Field dialog
New Field dialog box

Use the New Field dialog box to create new persistent fields as additions to or replacements of the other persistent fields in a dataset. There are three type of persistent fields you can create:

Data fields	Usually to replace existing fields (for example to change the data type of a field) based on columns in the table or query underlying a dataset.

Calculated fields	To display values calculated at run time by a dataset’s OnCalcFields event handler.

Lookup fields	To retrieve values from a specified dataset at run time based on search criteria you specify.

Internal Calc fields	To retrieve calculated values that are stored with the dataset (instead of being dynamically calculated in an OnCalcFields event handler). These include fields calculated by a query or calculated on a server.

Aggregate fields	To retrieve values that summarize the data over the records in a client dataset.

These types of persistent fields are only for display purposes. The data they contain at run time are not retained either because they already exist elsewhere in your database, or because they are temporary. The physical structure of the table and data underlying the dataset is not changed in any way.

To create a new persistent field component,

Right-click the Fields editor list box and choose New field to open et New Field dialog box.

The New Field dialog box contains three group boxes: Field properties, Field type, and Lookup definition.

Field type group

The Field type radio group enables you to specify the type of new field component to create. The default type is Data. If you choose Lookup, the Dataset and Source Fields edit boxes in the Lookup definition group box are enabled.

Field properties group

The Field properties group box enables you to enter general field component information. Enter the component’s field name in the Name edit box. The name you enter here corresponds to the field component’s FieldName property. C++Builder uses this name to build a component name in the Component edit box. The name that appears in the Component edit box corresponds to the field component’s Name property and is only provided for informational purposes (Name contains the identifier by which you refer to the field component in your source code). C++Builder discards anything you enter directly in the Component edit box.

Type combo box

The Type combo box in the Field properties group enables you to specify the field component’s data type. You must supply a data type for any new field component you create. For example, to display floating point currency values in a field, select Currency from the drop-down list. The Size edit box enables you to specify the maximum number of characters that can be displayed or entered in a string-based field or the size of Bytes and VarBytes fields. For all other data types, Size is meaningless.

Lookup definition group

The Lookup definition group box is only used to create lookup fields.


Database editor context menu
Database editor

Double click the database component to access the Database editor. The Database editor contains the following options:

Name	Enables you to specify the name of the database that must be used by dataset and session components to associate themselves with this component.  This dialog corresponds to the DatabaseName property in the Object Inspector.

Alias name	Enables you to identify the existing Borland Database Engine (BDE) alias associated with this database component.  If Driver Name is set, this property is cleared.  This dialog corresponds to the AliasName property in the Object Inspector.

Driver name	Enables you to identify the BDE driver for the component.  If AliasName is set, this property is cleared.  This dialog corresponds to the DriverName property in the Object Inspector.

Parameter overrides	Enables you to view and set BDE connection parameters.  Some typical connection parameters include path statement, server name, schema caching size, language driver, and SQL query mode.  This dialog corresponds to the Params property in the Object Inspector.

Defaults	Removes existing connection parameters from the Params property and Parameter overrides dialog and replaces them with default path and driver parameters.

Clear	Removes existing connection parameters from the Params property and Parameter overrides dialog.

Login prompt	Enables you set the state of the LoginPrompt property.  If true (checked), users are prompted to log in to a database server the first time your application attempts to connect to a database requiring a login.  If false (unchecked), your application must provide the user name and password.

Keep inactive connection	Enables you to set the state of the KeepConnection property.  If true (checked), a connection to a database is maintained even when all datasets associated with that database are closed.  If false (unchecked), a connection is dropped when there are no active datasets using the database.

OK	Saves all current settings and closes the Database editor.

Cancel	Closes the Database editor without saving any changes made since the Database editor was opened.


Form context menu

Use the Form context menu to manipulate components in the form at design time.

To display the Form context menu,

1.	On the form, select the component or components you want to manipulate.

Select a single component by clicking it. Select more than one by dragging across them or by holding down Shift while clicking each one.

2.	Right-click anywhere on the form, or press Alt-F10.

The following commands always appear on the Form context menu:

Align to Grid

Bring to Front

Send to Back

Align

Size

Scale

Tab Order

Creation Order

Add to Repository

View as Text

Other commands appear on the Form context menu when you select certain components on the form. The additional commands are:

SQL Builder

Execute

Edit Report

Next Page

Previous Page

Your installation of C++Builder may have additional commands installed by a third party. To get help on a command not listed above, display the Form context menu and select the command. This activates the module named in the command. Then, press F1 to get help on that module.


SQL Builder (Form context menu)

To open the SQL Builder , put a SQL Builder component on a form and right click. If a database is not already open, this command opens the Database’s dialog box for you to select a database.


Execute (Form context menu)

At design time, to perform the process specified in the Mode property, choose Execute from the Form context menu when you have the BatchMove component selected.

The Mode property enables you to perform any of the following tasks:

Copy a dataset to a table.

Append a dataset to a table.

Update a table with data from a dataset.

Display data using data from a control.

To run this process at run time, you must call the Execute method for BatchMove.


Edit Report (Form context menu)

To load QuickReports and open the report you specified using the ReportName and ReportDir properties, choose Edit Report from the Form context menu while you have the Report component selected.

If you have not previously specified a report, C++Builder allows you to select a report.

You can also perform this command by double-clicking the Report component on the form.


Next Page (Form context menu)

To set the ActivePage property to the next page in the notebook, choose Next Page from the Form context menu when you have either the Notebook component or TabbedNotebook component selected.

The next page is determined by the page order that you specify using the Notebook editor.


Previous Page (Form context menu)

To set the ActivePage property to the previous page of the notebook, choose Previous Page from the Form context menu when you have either the Notebook component or the TabbedNotebook component selected.

The previous page is determined by the page order which you can specify using Notebook editor.


Align To Grid (Form context menu)

Choose Align To Grid to align the selected components to the closest grid point.

To select more than one component, hold down Shift while clicking each one.

To change the size of the grid,

1. Go to Tools|Environment Options|Preferences.

2. Enter new values in Grid Size X, Grid Size Y.

This context menu command works the same as Edit|Align To Grid.


Bring To Front (Form context menu)

Choose Bring To Front to move a selected component in front of all other components on the form.

This is called changing the component's z-order.

Note:	The Bring To Front and Send To Back commands do not work if you are combining windowed and non-windowed components. For example, you cannot change the z-order of a label in relation to a button.

This context menu command works the same as Edit|Bring To Front.


Send To Back (Form context menu)

Choose Send To Back to move a selected component behind all other components on the form.

This is called changing the component's z-order.

Note:	The Send To Back and Bring To Front commands do not work if you are combining windowed and non-windowed components. For example, you cannot change the z-order of a label in relation to a button.

This context menu command works the same as Edit|Send To Back.


Align (Form context menu)

Choose Align to open the Alignment dialog box.

Alignment dialog box

Use this dialog box to line up selected components in relation to each other or to the form.

The Horizontal alignment options align components along their right edges, left edges, or center.

The Vertical alignment options align components along their top edges, bottom edges, or center.

The options for Horizontal or Vertical alignment are

Option	Description

No Change	Does not change the alignment of the component

Left Sides	Lines up the left edges of the selected components (horizontal only)

Centers	Lines up the centers of the selected components

Right Sides	Lines up the right edges of the selected components (horizontal only)

Tops	Lines up the top edges of the selected components (vertical only)

Bottoms	Lines up the bottom edges of the selected components (vertical only)

Space Equally	Lines up the selected components equidistant from each other

Center in Window	Lines up the selected components with the center of the window.

This context menu command works the same as Edit|Align.


Size (Form context menu)

Choose Size from the Form context menu to open the Size dialog box.

Size dialog box

Use this dialog box to resize multiple components to be exactly the same height or width.

The Horizontal options align the width of the selected components.

The Vertical options align the height of the selected components.

The options for Horizontal or Vertical sizing are

Option	Description

No Change	Does not change the size of the components.

Shrink To Smallest	Resizes the group of components to the height or width of the smallest selected component.

Grow To Largest	Resizes the group of components to the height or width of the largest selected component.

Width	Sets a custom width for the selected components. To use this option, you must set Horizontal to Enter Value.

Height	Sets a custom height for the selected components. To use this option, you must set Vertical to Enter Value.

This context menu command works the same as Edit|Size.


Scale (Form context menu)

Choose Scale to open the Scale dialog box.

Scale dialog box

Use this dialog box to proportionally resize the form and all of its components.

Scaling Factor, In Percent

Enter a percentage to which you want to resize the form. The scaling factor must be between 25 and 400.

Percentages over 100 grow the form.

Percentages under 100 shrink the form.

This context menu command works the same as Edit|Scale.


Tab Order (Form context menu)

Choose Tab Order to open the Edit Tab Order dialog box.

Edit Tab Order

Use this dialog box to modify the current tab order of the components on the active form or within the selected component if that component can contain other components.

To change the tab order of a component,

1.	Select the component name.

2.	Click the up button to move the component up in the tab order, or click the down arrow to move the component down in the tab order.

Or, you can drag the selected component to its new position in the tab order.

3.	To save your changes, click OK.

This context menu command works the same as Edit|Tab Order.


Creation Order (Form context menu)

Choose Creation Order from the Form context menu to open the Creation Order dialog box.

Creation Order dialog box

Use this dialog box to specify the order in which your application creates nonvisual components.when you load the form at design time or run time.

The list box displays only those nonvisual components on the active form, their type, and their current creation order. The default creation order is determined by the order in which you placed the nonvisual components on the form.

To change the creation order,

1.	Select a component name.

2.	Click the up button to have the component created before another component, or click the down arrow to have the component created after another component.

You can also drag the selected component to its new position in the creation order.

3.	To save your changes, click OK.

This context menu command works the same as Edit|Creation Order.


Add To Repository (Form context menu)
Add To Repository (Form or Data Module context menu)

Choose Add To Repository to open the Add To Repository dialog box. Use this command to add any form to the Object Repository.

Once you've designed a custom dialog box, you might want to reuse it in other projects. The best way to do this is to add the form to the Object Repository.

Saving a form as an object is similar to saving a copy of the form under a different name. When you save a form as a object, however, it then appears in the Object Repository.


View as Text (Forms context menu)
View as Text (Form context menu)

Use this command to view a text description of the form’s attributes.

This command changes to View as Form when you view the form as text.


View as Form
View as Form (Form context menu)

Use this command to view the form as a visual object.

This command changes to View as Text when you view the form as a visual object.


Select Bitmap Dialog Box
Select Icon dialog box

Use the Select Icon dialog box to choose a bitmap to represent your template in the New Items dialog box.

You can use an icon of any size, but it will be cropped to 60 x 40 pixels.

To open this dialog box, click the Browse button in the Add To Repository dialog box.

Look in	Displays the current directory. Use the icons to change or add directories if needed.

File Name	Enter the name of the file you want to use, or enter wildcards to use as filters in the Files list box.

Files Of Type	Choose the type of file you want to open; the default file type is a bitmap file (.BMP). All files in the current directory of the selected type appear in the Files list box.


Menu designer context menu

See Also

The Menu designer context menu provides quick access to the most common Menu designer commands and to the menu template options.

To display the Menu designer context menu,

Choose one of the following methods:

Right-click anywhere on the Menu designer.

Press Alt+F10 when the cursor is in the Menu designer window.

With the Menu designer context menu, you can perform these commands:

Command	Action

Insert	Inserts a placeholder above or to the left of the cursor

Delete	Deletes the selected menu item (and all its sub-items, if any)

Create SubMenu	Creates a placeholder at a nested level and adds an arrow to the right of the selected menu item

Select Menu	Displays a list of the menus in the current form so you can select which menu to edit

Save as Template	Displays the Save Template dialog box where you can name and save a menu as a template

Insert from Template	Displays a list of predefined menus that can be inserted into the current menu

Delete Templates	Displays a list of predefined menu templates that can be deleted

Insert from Resource	Allows you to insert a .mnu file into the Menu designer

Right click and choose the command and press F1 for more information.


Insert (Menu designer context menu)

Right click and choose Insert to add a menu item placeholder above or to the left of the selected menu item. This option depends on what is selected in the menu designer.

To insert a menu item into a menu,

 	Place the cursor on a menu item, then press the Insert key.

Menu items are inserted to the left of the selected item on the menu bar, and above the selected item in the menu list.


Delete (Menu designer context menu)

Right click and choose Delete to remove the selected menu item.

To delete a menu item from a menu,

1.	Place the cursor on the menu item you want to delete.

2.	Press the Delete key.

You cannot delete the default placeholder that appears below the item last entered in a menu list, or next to the last item on the menu bar. This placeholder does not appear in the menu at runtime.

All sub items, if any, are also deleted.


Create Submenu (Menu designer context menu)

Right click and choose Create Submenu to insert a menu item placeholder to the right of the selected menu item and add an arrow to the selected item to indicate a nested level.

To create nested menus,

1.	Select the menu item under which you want to create a nested menu.

2.	Press Ctrl+Right arrow to create the first placeholder, or choose Create Submenu from the context menu.

3.	Enter a name for the nested menu item.

4.	Press Enter to create the next placeholder.

5.	Repeat steps 3 and 4 for each item you want to add to the nested menu.

6.	Press Esc to return to the previous menu level.

Organizing your menu structure using nested menus can save vertical screen space. However, for optimal design purposes you probably want to use no more than two or three menu levels in your interface design. (For pop-up menus, you might want to use only one such nested level, if any.)

Shortcut:	You can also create a nested menu by inserting a menu item from the menu bar (or a menu template) between menu items in a list. When you move a menu into an existing menu structure, all its associated items move with it, creating a fully intact nested menu. This pertains to nested menus as well; moving a menu item into an existing nested menu just creates one more level of nesting.


Select Menu (Menu designer context menu)

Right click and choose Select Menu to open the Select Menu dialog box.

This allows you to switch between menus if you are designing several menus for your application.

To switch among menus in a form,

1.	Right-click the Menu designer to display the context menu.

2.	From the context menu, choose Select Menu.

The Select Menu dialog box appears. This dialog box lists all the menus associated with the form whose menu is currently open in the Menu designer.

3.	From the list in the Select Menu dialog box, choose the menu you want to view or edit.


Save As Template (Menu designer context menu)

Right click and choose Save As Template from the Menu designer context menu to open the Save Template dialog box, which enables you to save a menu for later reuse.

Any menu you design can be saved as a template so you and others can use it again. You can use menu templates to provide a consistent look to your applications, or use them as a starting point which you then further customize.

Menu templates you save are stored in your BIN directory as .DMT files.

You edit the template file by using the template commands from the Menu designer context menu.

To save a menu as a template,

1.	Choose Save As Template from the Menu designer context menu to open the Save Template dialog box.

2.	In the Template Description edit box, enter a brief description of this menu.

3.	Click OK.

The Save Template dialog box closes, saving your menu design and returning you to the Menu designer window.

Note: The description you enter is displayed only in the Save Template, Insert Template, and Delete Templates dialog boxes. It is not related to the Name or Caption property for the menu.

When you save a menu as a template, C++Builder does not save its Name, since every menu must have a unique name within the scope of its owner (the form). However, when you insert the menu as a template into a new form by using the Menu designer, C++Builder then generates new names for it and all its items.

C++Builder also does not save any event handlers associated with a menu saved as a template, since C++Builder cannot test whether the code would be applicable in a new form. You can associate menu items in the template with existing event handlers in the form.


Insert From Template (Menu designer context menu)

Right click and choose Insert From Template from the Menu designer context menu to open the Insert Template dialog box.

You can also save as a template any menu that you design using the Menu designer. After saving a menu as a template, you can use it as you would any predesigned menu. If you decide you no longer want a particular menu template, you can delete it from the list.

To add a menu template to your application,

1.	Right-click the Menu designer window.

The Menu designer context menu appears.

2.	From the context menu, choose Insert From Template.

(If there are no templates, the Insert From Template option is dimmed.)

The Insert Template dialog box opens, displaying a list of available menu templates.

3.	Select the menu template you want to insert, then press Enter or choose OK.

This inserts the menu into your form at the cursor's location. For example, if your cursor is on a menu item in a list, the menu template is inserted above the selected item. If your cursor is on the menu bar, the menu template is inserted to the left of the cursor.

Menu templates are stored in the file BCB.DMT. The menu templates shipped with C++Builder also reside in this file.


Delete Templates (Menu designer context menu)

Right click and choose Delete Templates from the Menu designer context menu to open the Delete Templates dialog box.

To delete a menu template,

1.	Right-click the Menu designer window.

The Menu designer context menu appears.

2.	From the context menu, choose Delete Templates.

(If there are no templates, the Delete Templates option appears dimmed in the context menu.)

The Delete Templates dialog box opens, displaying a list of available templates.

3.	Select the menu template you want to delete, and press Del.

C++Builder deletes the template from the templates list and from your hard disk.

Note:	After you delete a template, you cannot retrieve it.


Insert from Resource (Menu designer context menu)

Right click and choose Insert From Resource from the Menu designer context menu to open the Insert Menu From Resource dialog box.

Insert Menu From Resource dialog box

Use this dialog box to import a menu from a Windows resource (.RC) file. You first need to save each individual menu as a separate resource file.

Look in	Select the directory whose contents you want to view. In the current directory, the file type in the List Files of Type combo box appear in the Files list box. Use the buttons to change directories, or drives.

Displays the files in the current directory that match the file type in the List Files Of Type combo box.

File Name	Enter the name of the file you want to use, or enter wildcards to use as filters in the Files list box.

Files Of Type	Choose the type of file you want to open; the default file type is a menu file (.MNU). All files in the current directory of the selected type appear in the Files list box.


Insert from Resource (Menu Designer SpeedMenu)

See Also

Choose Insert From Resource from the Menu Designer SpeedMenu to open the Insert Menu From Resource dialog box. This allows you to import menus that you built with other applications, so long as the menus are in the standard Windows resource (.RC) file format.

To load an existing .RC menu file,

1.	In the Menu designer, place the cursor where you want the menu to appear.

The imported menu can be part of a menu you are designing, or an entire menu in itself.

2.	Right click and choose Insert From Resource.

The Insert Menu From Resource dialog box displays.

3.	Select the resource file you want to load, and choose OK.

Note: If your resource file contains more than one menu, you first need to save each menu as a separate resource file before importing it.

Insert Menu From Resource dialog box

Use this dialog box to import a menu from a Windows resource (.RC) file. You first must save each individual menu as a separate resource file.

File Name	Enter the name of the file you want to use, or enter wildcards to use as filters in the Files list box.

Files	Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List Files Of Type	Choose the type of file you want to open; the default file type is a menu file (.MNU). All files in the current directory of the selected type appear in the Files list box.

Directories	Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the File Name input box or the file type in the List Files of Type combo box appear in the Files list box.

Drives	Select the current drive. The directory structure for the current drive appears in the Directories list box.


Object Inspector context menu

The Object Inspector context menu provides you with commands for closing the Object Inspector, displaying Help, and for keeping the Object Inspector the topmost window.

The commands on the Object Inspector context menu are

Revert to Inherited

Expand

Collapse

Stay On Top

Hide

Help


Revert to Inherited (Object Inspector and Form context menu)

Right click and choose Revert to Inherited when you want to change an object that has had its properties overwritten back to the original inherited behavior.

This option is only available when the object has properties.


Stay On Top (Object Inspector context menu)

Right click and choose Stay On Top to keep the Object Inspector in front of all other C++Builder windows and dialog boxes.


Expand (Object Inspector context menu);nested properties
Expand (Object Inspector context menu)

Right click and choose Expand to view the nested properties of the selected property.

Properties with nested properties show a plus (+) sign on their left side in the Object Inspector. You must view these nested properties to set them.


Collapse (Object Inspector context menu)

Right click and choose Collapse to hide the nested properties of the selected property.

Properties with nested properties show a plus (+) sign on their left side in the Object Inspector. You must view these nested properties to set them.


Object Repository context menu
New Items context menu

See Also

The context menu provides the following options for items in the New Items dialog box.

View Large Icons

View Small Icons

View List

View Details

Arrange by Name

Arrange by description

Arrange by Date

Arrange by Author

Properties

Note:	Selecting Properties from the context menu opens the Object Repository dialog box. You can use this dialog box to edit, add pages to, and rename items in the Object Repository. You can also access this dialog from the Tools|Repository menu.


View large icons (Object Repository context menu)

Choose this option to view Object Repository items as large icons.


View small icons (Object Repository context menu)

Choose this option to view Object Repository items as small icons.


View list (Object Repository context menu)

Choose this option to view Object Repository items as a list of names and icons.


View details (Object Repository context menu)

Choose this option to view details about the items in the Object Repository, if specified. The details include the item’s name, description, date last modified, and author.


Arrange by name (Object Repository context menu)

Choose this option to arrange the Object Repository items in alphabetical order by name.


Arrange by description (Object Repository context menu)

Choose this option to arrange the Object Repository items in alphabetical order by description.

If descriptions are blank, the previous sort order is used.


Arrange by date (Object Repository context menu)

Choose this option to arrange the items in the Object Repository by date.


View large icons (Object Repository context menu)
Arrange by author (Object Repository context menu)

Choose this option to arrange items in the Object Repository by author.


Properties (Object Repository context menu)

Choose this option to display the Object Repository dialog box. You can use this dialog box to edit, add pages to, and rename items in the Object Repository. You can also access this dialog from the Tools|Repository menu.


Project Manager context menu

The Project Manager context menu contains commands that enable you to manage your individual projects and project groups, if you have chosen to contain related projects in a project group.

When you right click in the Project Manager, a different context menu appears depending on what is currently selected. Note that all of the context menus include the choices Toolbar, Status Bar, and Dockable. These options apply to the Project Manager.

If you right click with a project group selected, you can perform any of the following commands:

Add New Project

Add Existing Project

Save Project Group

Save Project Group As

View Project Group source

If you right click with a project selected, you can perform any of the following commands:

Add

Remove

Save

Options

Activate

Make

Build

View Source

ViewProjectMakefile

Close

Remove Project

Build Sooner

BuildLater

If you right click with a file within a project selected, you can perform any of the following commands:

Open

Save

Save As

Compile

Remove From Project

To open the Project Manager context menu,

Right-click anywhere in the Project Manager window.

For more information on the Project Manager, see Using the Project Manager


Add New Project
Add New Project (Project Group context menu)

Choose Add New Project from the project group context menu to add a new project to the current project group. This command opens the New Items dialog box to create a new target from the templates provided in the Object Repository.

Typically, a project group consists of at least one project, which contains the source of your application. You can choose to add additional projects to a project group to contain other targets associated with your application. For example, you may have one project for your .EXE, another for your .DLL, and another for your application resources.

This command works the same as Project|Add New Project.

For details on project groups, see creating a project group.


Add Existing Project
Add Existing Project (Project Group context menu)

Choose Add Existing Project from the project group context menu to add an existing project to the current project group. This command opens the Open dialog box for you to specify the path to the project that you want to add to this project group.

Typically, a project group consists of at least one project, which contains the source of your application. You can choose to add additional projects to a project group to contain other targets associated with your application. For example, you may have one project for your .EXE, another for your .DLL, and another for your application resources.

This command works the same as Project|Add Existing Project.

For details on project groups, see creating a project group.


Save Project Group
Save Project Group (Project Group context menu)

Choose Save Project Goup from the project group context menu to save the project file for the project group, which contains the commands to build all the projects contained in the project group. This file has the name of the project group with the .BPG extension.

Use this command after adding or changing the order of projects in a project group. C++Builder prompts you to save this project file when you remove projects from the project group.

For details on project groups, see creating a project group.


Save Project Group As
Save Project Group As (Project Group context menu)

Choose Save Project Group As from the project group context menu to rename the project group. Choose this command when you first set up projects within a project group or any time you want to change the name of a group.

For details on project groups, see creating a project group.


View Project Group Source
View Project Group Source (Project Group context menu)

Choose View Project Group Source from the project group context menu to view the source of the .BPG file. This text file uses a Make syntax specific to Borland projects. You can make changes to this text version of the .BPG file, however, we recommend that you make changes from the IDE to avoid errors.

For details on project groups, see creating a project group.

This command works the same as View|Project Group Source.


Add File (Project Manager context menu)
Add File (Project Manager Project context menu)

See Also

Choose Add from the Project Manager Project context menu to open the Add To Project dialog box.

Add…

Use the Add To Project dialog box to add an existing unit and its associated form to the C++Builder project. When you add a unit to a project, C++Builder automatically adds that unit to the project file.

Dialog box options

File name	Enter the name of the file you want to load, or enter wildcards to use as filters in the Files list box.

Files	Displays the files in the current directory that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box.

List files of type	Choose the type of file you want to open; the default file type is Source file (.PAS). All files in the current directory of the selected type appear in the Files list box.

Directories	Select the directory whose contents you want to view. In the current directory, files that match the wildcards in the File Name edit box or the file type in the List Files Of Type combo box appear in the Files list box.

Drives	Select the current active drive. The directory structure for the current drive appears in the Directories list box.

This context menu command works the same as File|Add File.


Importing a form from a Delphi application

You can use units and forms that you have written with Delphi version 3.0 or later. However, be aware of the following restrictions:

You cannot use a Delphi form or unit if it uses the Object Pascal Real or Comp intrinsic data types; you must change the data type in the form before importing it to C++Builder. For Delphi forms that use the Comp data type, use Currency instead.

The old-style Object Pascal Object type is not supported in C++Builder.

C++Builder does not support Object Pascal virtual class methods.

C++Builder does not support initialized set variables that are greater than 4 bytes in size.

C++Builder does not support the Object Pascal $Z2 compiler directive. Use (in Delphi) the $Z1 or $Z4 directive instead.

You cannot use a Delphi form that uses the Delphi sample controls, unless you:

Install the Delphi version of the sample control on the Component palette (and overwrite the C++Builder version of the control)

Uninstall the C++ version of the sample control


Remove File (Project Manager context menu)
Remove File (Project Manager Project context menu)

Choose Remove File from the Project Manager Project context menu to remove a module from the current project file.

To remove a file from the current project,

1. Select the Project File and right click to get the Project Manager context menu.

2. Choose Remove File, and the Remove From Project dialog appears.

3. Select the file to delete and click OK.

If you have modified the file you are removing during this editing session, C++Builder prompts you to save your changes, just in case you want to use the form or unit in another project. If you have not modified the file, C++Builder removes that file from the project without prompting you.

Removing a file from the Project Manager does not remove the file from disk.

Caution:	Remove the file from your project first before deleting the file from disk so that C++Builder can update project file accordingly.

This context menu command works the same as Project|Remove From Project.


Save Project (Project Manager context menu)
Save Project (Project Manager Project context menu)

Choose Save Project from the Project Manager Project context menu to store changes made to all files in the open project using each file's current name.

If you try to save a project that has an unsaved project file or unit file, C++Builder opens the Save As dialog box, where you enter the new file name.

This context menu command works the same as File|Save Project.


Options (Project Manager context menu)
Options (Project Manager Project context menu)

Choose Options from the Project Manager Project context menu to open the Project|Options dialog box.

You can use this dialog box to set options for an individual project, such as compiler directives, version information, and application settings.

This context menu command works the same as the Project|Options.


Activate Project (Project Manager context menu)
Activate (Project Manager Project context menu)

Choose Activate from the Project Manager Project context menu to activate a project in the project group.

An activated project appears in bold in the Project Manager tree view.

To make another project of the project group active,

1. Select the project.

2. Right click and choose Activate.

Or,

Select the project and click the Activate button.

You must activate a project before you can make changes to the project.

This context menu command works the same as the Project Manager Activate button.


Make
Make (Project Manager Project context menu)

See also

Choose Make from the Project Manager Project context menu to compile all files in the current project that have changed since it was last built into a new executable file (.EXE), dynamic link library (.DLL) or resource (.RES). This command is similar to Build, except that Make builds only those files that have changed whereas Build rebuilds all files regardless of whether they have changed or not.

When you choose this command

The compiler compiles source code for each unit if the source code has changed since the last time the unit was compiled.

If a unit contains an include (.H) file, and the include file is newer than the unit’s .OBJ file, the unit is recompiled.

Once all the units that make up the project have been compiled, C++Builder links them into an executable file (or dynamic link library). This file is given an .EXE (or .DLL) file extension and the same file name as the project source code file. This file now contains all the compiled code and forms found in the individual units, and the program is ready to run.

If you checked Show Compiler Progress from the Preferences page on the Tools|Environment Options dialog box, the Progress dialog box displays information about the compilation progress and results. When your application successfully compiles, choose OK to close the Progress dialog box.

This command works the same as Project|Make.

If you have multiple projects within a project group, you can make all projects within a project group by using the Project|Compile All Projects command.


Build
Build  (Project Manager Project context menu)

See also

Choose Build from the Project Manager Project context menu to rebuild all the components of your project regardless of whether they have changed.

This command is similar to Make except that Build rebuilds everything whereas Make rebuilds only those files that have been changed since the last build. When you choose Build, precompiled headers and files generated by the incremental linker are deleted and regenerated.

This command is useful when you are unsure of exactly which files have or have not been changed, or when you simply want to ensure that all files are current and synchronized. It’s also important to Build All when you’ve changed global compiler directives or compiler options, to ensure that all code compiles in the proper state.

This command works the same as Project|Build.

If you have multiple projects within a project group, you can build all the projects with the Project|Build All Projects command.


View Source (Project Manager context menu)
View Source (Project Manager Project context menu)

Choose View Source from the Project Manager Project context menu to display the project source (.CPP) file in the Code editor.

If the project file is not currently open, C++Builder opens it.

This command works the same as View|Project Source.


View Project Makefile(Project Manager context menu)
View Project Makefile (Project Manager Project context menu)

Choose View Project Makefile from the Project Manager Project context menu to display the project file (with the .BPR extension) in the Code editor. This text file uses a Make syntax specific to Borland projects.

If the project file is not currently open, C++Builder opens it.

This command works the same as View|Project Makefile.


Close
Close (Project Manager Project context menu)

Choose Close from the Project Manager Project context menu to close the all the open files of an active project.

Before closing the file, C++Builder prompts you to save any changes. If you have not previously saved the project, or any file, C++Builder opens the Save As dialog box, where you can enter the new file name.

Note	Closing the project file in the Code editor, closes the entire project. You can also close the entire project by choosing File|Close when the Project Manager is the active window.


Remove Project
Remove Project (Project Manager Project context menu)

Choose Remove Project from the Project Manager Project context menu to remove the active project from the project group.

Removing the target from the current project group affects the project group’s project file (Project.BPG extension); it does not remove any files from disk.

If you have modified any project files that you are removing during this editing session, C++Builder prompts you to save your changes, just in case you want to use the form or unit in another project.

C++Builder prompts you to save changes to the .BPG file upon removing the project.

Caution:	Remove the project from your project group first, before deleting the file from disk so that C++Builder can update project file accordingly.


Build Sooner
Build Sooner (Project Manager Project context menu)

Choose Build Sooner from the Project Manager Project context menu to change the order in which the Project Manager lists projects contained in a project group.

Choose Build Sooner to move a project up in the list of projects within a project group.

By changing the order in which the Project Manager lists projects, you change the order in which the projects are compiled because projects are compiled in the order they appear on the Project Manager.

Note	The Project Manager does not check for interdependencies between projects.

To compile all projects in a project group at once, choose Project|Compile All Projects or Project|Build All Projects.


Build Later
Build Later (Project Manager Project context menu)

Choose Build Later from the Project Manager Project context menu to change the order in which the Project Manager lists projects contained in a project group.

Choose Build Later to move a project down in the list of projects within a project group.

By changing the order in which the Project Manager lists projects, you change the order in which the projects are compiled because projects are compiled in the order in which they appear on the Project Manager.

Note	The Project Manager does not check for interdependencies between projects.

To compile all projects in a project group at once, choose Project|Compile All Projects or Project|Build All Projects.


Open (Project Manager File context menu)

Choose Open from the Project Manager File context menu to open the selected file in the Code editor.


Remove From Project (Project Manager File context menu)

Choose Remove From Project from the Project Manager File context menu to remove the current file from the project.

If you have modified the file you are removing during this editing session, C++Builder prompts you to save your changes, just in case you want to use the form or unit in another project. If you have not modified the file, C++Builder removes that file from the project without prompting you.

Removing a file from the Project Manager does not remove the file from disk.

Caution:	Remove the file from your project first before deleting the file from disk so that C++Builder can update project file accordingly.


Save Project (Project Manager File context menu)
Save (Project Manager File context menu)

See Also

Choose Save from the Project Manager File context menu to store changes made to the current file using its current name.

If you try to save an unsaved project file or unit file, C++Builder opens the Save As dialog box, where you enter the new file name.


Save As (Project Manager File context menu)

Choose Save As from the Project Manager File context menu to rename the current file.


Compile (Project Manager File context menu)

Choose Compile from the Project Manager File context menu to compile the selected file.


Type Library editor

See also

Use the Type Library editor to make changes to your type library. The Type Library editor generates the required IDL syntax automatically. Any changes you make in the editor are reflected in the corresponding control.

To open the Type Library editor,

  Choose View|Type Library.

The Type Library option is available only for projects that contain a type library. An ActiveX control will contain a type library if you create it using the ActiveX control wizard.

The main elements of the Type Library editor are:

Toolbar
These buttons add instances of new information types to the current type library.  When you click a button, its icon is added to the object list pane.

Status Bar pane
Syntax and translation errors and warnings appear here when you edit, save, or load a type library.

Object list pane
Each instance of an information type in the current type library appears in the object list, represented by a unique icon.  Select an icon to see its data pages displayed in the information pane at the right.

Pages of type information. For each object selected in the object list pane, the Type Library editor displays tabbed pages of the object’s attributes, flags, if any, and text. Some objects have additional pages.


Type library attributes page
Type Library attributes

Edit the attributes in the Type Library to change information about the type library itself.

To edit the type library attributes,

In the Type Library Editor object list pane, select the type library, which has the icon:

The attributes page displays type information about the currently selected type library.


Type Info attributes

Type info is a general term for the types of information available in a type library such as interfaces, dispinterfaces, coclasses, enumerations, and so on. You can change information about each type by modifying its attributes page.

To edit type info attributes,

In the Type Library Editor object list pane, select the type you want to edit and its attributes page appears.

   See the following topics for details on modifying the attributes of each type info:

Interface attributes

Dispinterface attributes

CoClass attributes

Enumeration attributes

Alias attributes

Record attributes

Union attributes

Module attributes


Members attributes

You can add or remove members to each type info.

To modify type member attributes,

1.	In the Type Library Editor object list pane, select the type you want create or modify.

The toolbar displays the members available for this type to the left of the vertical bar.

2. Choose the member you want to modify and its attributes page appears.

For interfaces and dispinterfaces, you can add methods or properties.

For enumerations, you can add constants.

Records, are comprised of fields.

A union defines a C-style union.

A module can be comprised of methods and constants.


Text

All type library elements have a text page that displays the IDL syntax for the element. Any changes you make in other pages of the element are reflected here. If add IDL code directly in the text page, changes are reflected in the other pages of the Type Library editor.

The Type Library editor will generate syntax errors if you add IDL identifiers that are currently not supported by the editor; the editor currently supports on those IDL identifiers that relate to type library support (not RPC support).


CoClass implements

You specify  the globally unique identifier (GUID) and supported interfaces on the CoClass implements page.

For each interface, specify the following information.


Type library uses

The uses page lists any other type libraries that this type library references.


Parameters

The parameters page allows you to specify the parameters and return values for the functions contained in your type library.

You can specify the following information.


Type library flags

The type library flags specify how other applications must use the server associated with this type library. You can set the following flags:

Flag	Meaning
Restricted	Prevents the library from being used by a macro programmer.
Control	Indicates that the library represents a control.
Hidden	Indicates that the library exists but should not be displayed in a user-oriented browser.


Type info flags

You can set the following flags for type info. The same flags menu appears for all type info (interfaces, CoClasses, enumerations and so on). Unavailable flags are dimmed.

For details, see:

Interface and dispinterface flags

CoClass flags


Type member flags

The following menu of flags appears when you have a type member (properties, methods, constants and fields). Unavailable flags are dimmed.

For details, see:

Method flags

Property flags


Parameter flags

The parameters flags dialog box allows you to specify parameters and return values for your functions.

To get to this dialog box,

1. In the Type Library Editor, select a method or property.

2. In the Parameters page, click in the flags field.

An ellipse appears.

3. Click on the ellipse to display this Parameter Flags dialog box.

For details on the flags, see Property and method parameters page


Component menu

Use the Component menu to build a component, install a new component, rebuild the component library or configure the Component palette.

The options on the Component menu are:

New Component	Opens the Component wizard

Install Component	Installs new components

Import ActiveX Control	Add type libraries of ActiveX controls to your C++Builder project.

Create Component Template	Customize a component and save it as a template with a new name, palette page, and icon.

Install Packages	Specify packages required by your project.

Configure Palette	Opens the Palette dialog box.


Component|New
Component | New Component

Use the New Component dialog to create the basic unit for a new component.

Ancestor Type 	Use the drop-down list to select a base class, or enter the name of a base class for your new component. Unless you override them in the component declaration, your new component will inherit all the properties, methods, and events from its ancestor class.

After you enter a base class, default entries are written to the Class Name and Unit File Name. You can accept or edit these entries.

Class Name	The name of the new class you are creating. A general rule is that all VCL classes are prefaced with a T. For example, the name of your new button component could be TMYBUTTON.

Palette Page 	Use the drop-down list to select a page, or enter the name of the page on which you want your new component to appear on the Component palette.

Unit File Name 	The name of the unit that will contain the new component. You can include a directory path with the name; otherwise, the unit will be created in the current directory. If the unit directory is not in the Search Path, it will be added at the end.

Search Path 	The path C++Builder uses to search for files. If you change this, you are changing C++Builder’s global library search path.

Install 	Creates component and install it into a new or existing package.

OK	Creates component but does not install it. To install the component later, choose Component|Install Component.


Component|Install
Component | Install Component

See also

Select Component | Install Component to install a component into an existing or new package.

Into existing package

Into new package


Install component into existing package

See also

Use this dialog to install a component into an existing package.

Unit file name 	Enter the name of the unit (.CPP) file. If the unit is in the search path, a full path name is not required.

Search path 	The path C++Builder uses to search for files. If you change this, you are changing C++Builder’s global library search path.

Package file name 	Use the drop-down list to select the name of an installed package, or enter the name of another existing package (.BPK file).


Install component into new package

See also

Use this dialog to create a new package for your component

Unit file name 	Enter a name for the unit (.CPP) file that C++Builder will generate to contain your package source code. If the unit is in the search path, a full directory path is not required.

Search path 	The path C++Builder uses to search for files. If you change this, you are changing C++Builder’s global library search path.

Package file name 	Enter a name for the makefile (.BPK file) that C++Builder will generate for your package.

Package description	Enter a brief description for your package. (Optional.)


Component | Import ActiveX Control

See also

The Import ActiveX Control dialog displays the ActiveX controls registered on your system so you can add them to your C++Builder projects.

The top part of the dialog lists the controls that are currently registered and therefore available to be imported into C++Builder. This list lets you extract the C++ declarations from an existing control.

For convenience, you can also register a new control from this dialog box so that it is available to be imported.

To add and register a new ActiveX control:

1.	Click Add. The Register OLE Control dialog box appears.

2.	In the Register OLE Control dialog box, navigate to the disk or network location of the control file you want to add.

3.	Select the new ActiveX control. It is automatically registered on your system for C++Builder and immediately appears in the list of available controls in the Import ActiveX Control dialog.

Add button 	The Add button lets you locate a new ActiveX control and register it in the Windows Registry, so that it appears in the list of registered objects available to be imported into C++Builder.

Remove button 	To remove a registered ActiveX control, select the control and click the Remove button. The control is removed from the Windows Registry and from this list.

Class names 	Shows only the ActiveX control classes in the selected library.

Palette page 	Shows the Component palette location of objects associated with the selected library. This allows you to group controls by function or vendor, for example.

Unit dir name 	Shows the name of the directory that contains the unit using this control. Only the path root is shown; no file name appears. The unit name is derived from the internal type library name. Click the Browse button to move up the directory tree. If the Unit Directory name is not in the Search Path, it will be added to the end.

Search path 	Shows the path C++Builder uses to search for a file. This is C++Builder’s global library search path.

Install…	Creates a unit and adds it to in the package you specify. When you click Install, a new dialiog appears, asking if you want to install the new unit in an existing C++Builder package (the default) or create a new package to contain it.

Create unit 	Creates a unit and displays the unit code in the Code editor. (It does not include the unit in the current project.)


Install ActiveX control in a new package
Install into a new package

See also

Specify the file name and description of a new package to install in the current project.

File Name

Enter the name of the package to create. You can include a directory path with the name; otherwise, the package will reside in the current directory. To open a file/directory selection dialog box, click Browse. If you type a file name directly in the New Package dialog box, the .BPK extension is added automatically.

Package names must be unique within a project. If you name a package “STATS”, C++Builder generates a source file for it called “STATS.BPK” and the compiler generates an executable called “STATS.BPL”. Use “STATS” to refer to the package in the requires list of another package, or when using the package in an application.

Description

A brief description that appears when the package is installed.

Create new project group

If you check this, C++Builder adds the package to a new project group. If you don’t, it adds the package as a project to the current project group.

When you choose OK, C++Builder builds and installs package.


Install ActiveX control in a new package
Install into an existing package

See also

Specify the file name of the package to install into, then click OK. C++Builder adds the component to the package and rebuilds the package if necessary.

File name 	Use the drop-down list to select the name of an installed package, or enter the name of another existing package.

Create new project group	If you select this, C++Builder adds the package to a new project group. If you don’t, it adds the package as a project to the current project group.

When you choose OK, C++Builder builds and installs the package.


Component | Create Component Template

See also

Component Templates are components that have been configured to have a user-defined set of property values. They can be based on one or several components. Component templates are stored in C++BUILDER.DCT.

To create a custom component template:

1	Choose an existing component as a starting point and place it on a form.

2	With the component selected, in the Object Inspector, set the properties and events you want for your template. For example, if you are creating a StaticText component to be used on forms that require a standard appearance, set the component’s Font and Color properties.

3	With the desired component still selected, choose Component|Create Component Template to give your custom template a new name, palette location, and icon.

Component Name 	This field shows the name of the currently selected component and the appended suffix, “template”.

Palette Page 	Click to select the tabbed C++Builder palette on which you want the new component to appear. If you specify a page that does not exist, a new page is created when you save the template.

Palette Icon 	This field shows the icon of the currently selected component. To change it, click the Change button, navigate the Open dialog to find a directory of images, and choose a new image for the icon. The bitmap you choose must be no larger than 24 pixels by 24 pixels.

To create the new component template, click OK. Your new template appears immediately in the tabbed pallet page you indicated with the new icon.


Component | Configure Palette

Displays the Environment Options dialog box with the Palette tab selected.


Object selector

Displays the active component whose properties and events you are currently editing. You can use the drop-down list to select a component.


Property column

Lists the design-time properties for the component you have selected on your form.


Value column

Displays the current value for a property. Each value uses one of the C++Builder property editors to set values.


Object Inspector tabs

Provide you with a means to switch between the Property page and the Event page of the Object Inspector. To change pages, click a tab.


Minimize button

Shrinks the window down to an icon.


Scroll bars

Provides you with a means to scroll the current window to view objects that cannot fit into the window. To scroll a window, click the up scroll arrow or the down scroll arrow, or you can drag the scroll box.


Control menu

Click the Control-menu box to open the Control menu for the current window.


Handler column

Displays the event-handler link for an event. To generate a default event-handler link for an event, double-click the Handler column.


Event column

Lists the possible events for the component you have selected on your form.


Introducing the Object Repository

See Also

C++Builder provides the Object Repository as a means for sharing and reusing forms and projects. The repository itself is really just a text file that contains references to forms, projects, and wizards.

Sharing across projects

By adding forms, dialog boxes, and data modules to the Object Repository, you make them available to other projects. For example, in a simple case, you could have all your projects use the same About box, copied from the Object Repository. A more advanced use of the Object Repository would be to have a standard empty dialog box with the company or product logo and standard button placement, from which all your projects derive standard-looking dialog boxes.

These sharing options are described in detail in Object Repository usage options.

Sharing within projects

The Object Repository can also help you to share items within a project by allowing you to inherit from forms already in the project. When you open the New Items dialog box (by choosing File|New), you'll see a page tab with the name of your project. If you click that page tab, you'll see all the forms, dialog boxes, and data modules in your project. You can then derive a new item from the existing item, and customize it as needed.

For example, in a database application you might need several forms that display the same data, but which provide different command buttons. Instead of creating and maintaining several nearly-identical forms, you could lay out a generic form that contains all the data-display controls, then create separate forms that inherit the data-display layout, but have different command buttons.

By carefully planning your project forms, you can save tremendous amounts of time and effort by sharing forms within projects.

Sharing entire projects

You can also add an entire project to the Object Repository as a template for future projects. If you have a number of similar applications, for example, you can base them all on a single, standardized model.

Using wizards

The Object Repository also contains references to wizards, which are small applications that lead the user through a series of dialog boxes to create a form or project. C++Builder provides a number of wizards, and you can also add your own.


Object Repository usage options

See Also

When you use an item from the Object Repository in a project, you have as many as three options on how to include that item. Keep in mind that items in the Object Repository are there to be shared, and that you want to use them in ways that help, rather than hinder, reuse.

In general, these are the three options for using Object Repository items,

Copy the item.

Inherit from the item.

Use the item directly.

Copying items from the Object Repository

The simplest sharing option is to copy an item from the Object Repository into your project. Copying makes an exact duplicate of the item as it stands and adds the copy to your project. Future changes to the item in the Object Repository will not be reflected in your copy, and alterations made to your copy will not affect the original Object Repository item.

Note:	Copying is the only option available for using project templates.

Inherit from Object Repository items

The most flexible and powerful sharing option is to inherit from an item in the Object Repository. Inheriting derives a new class from the item and adds the new class to your project. When you recompile your project, any changes made to the item in the Object Repository will be reflected in your derived class, unless you have changed a particular aspect. Changes made to your derived class do not affect the shared item in the Object Repository.

Note:	Inheriting is available as an option for forms, dialog boxes, and data modules, but not for project templates. It is the only option available for reusing items from within the same project.

Using Object Repository items directly

The least flexible sharing option is using an item from the Object Repository directly in your project. Using the item adds the item itself to your project, just as if you had created it as part of that project. Design-time changes made to the item therefore appear in all projects that directly use the item, as well as affecting any projects that inherit from the item.

Note:	Using items directly is an available option for forms, dialog boxes, and data modules.

Items shared this way should generally be modified only at run time, to avoid making changes that affect other projects.

The Use option is the only option available for wizards, whether form wizards or project wizards. Using a wizard doesn't actually add shared code, but rather runs a process that generates its own code.


Using project templates from the Object Repository

See Also

C++Builder provides project templates, pre-designed projects you can use as starting points for your own projects. Project templates are part of the Object Repository (located in the OBJREPOS subdirectory), which also provides form objects and wizards.

When you start a project from a project template (other than the blank project template), C++Builder prompts you for a project directory, a subdirectory in which to store the new project's files. If you specify a directory that doesn't currently exist, C++Builder creates it for you. C++Builder copies the template files to the project directory. You can then modify it, adding new forms and units, or use it unmodified, adding only your event-handler code. In any case, your changes affect only the open project. The original project template is unaffected and can be used again.

To start a new project from a project template,

1	Choose File|New to display the New Items dialog box.

2	Choose the Projects tab.

3	Select the project template you want and choose OK.

4	In the Select Directory dialog box, specify a directory for the new project's files.

A copy of the project template opens in the specified directory.

Adding projects to the Object Repository

You can add your own projects and forms to those already available in the Object Repository. This is helpful in situations where you want to enforce a standard framework for programming projects throughout an organization.

For example, suppose you develop custom billing applications. You might have a generic billing application project that contains the forms and features common to all billing systems. Your business centers around adding and modifying features in this application to meet specific client requirements. In such a case, you might want to save the project containing your Generic Billing application as a project template and perhaps specify it as the default new project on your C++Builder development system. Likewise, you'll probably have a particular form within this project that you want to appear as the default main or new form.

To add a project to the Object Repository,

1	If necessary, open the project you want added to the Object Repository.

2	Choose Project|Add to Repository.

3	In the Title edit box, enter a project title.

The title for the template will appear in the Object Repository window.

4	In the Description field, enter text that describes the template.

 This text will appear in the Object Repository window's status bar.

5	In the Page field, choose the name of the page in the New Items dialog box (probably Projects) you want the template to appear on.

6	In the Author field, enter text identifying the author of the application.

 Author information appears only when the user views the repository items with full details.

7	Choose Browse to select an icon to represent this template in the Object Repository.

9	Choose OK to save the current project as a project template.

Note:	If you later make changes to a project template, those changes automatically appear in new projects created from that template. They will not, however, affect projects already created from that template.

You can also save your own forms as form templates and add them to those already available in the Object Repository. This is helpful in situations where you want to develop standard forms for an organization's software.

To add a form to the Object Repository as a template, right-click the form and choose Add to Repository.


Customizing defaults in the Object Repository

See Also

The settings in the Object Repository Options dialog box affect the behavior of C++Builder when you begin a new project or create a new form in an open project. This is where you specify,

Default project

Default new form

Default main form

You always have to option to override these defaults by choosing File|New and selecting from the New Items dialog box.

By default, opening a new project displays a blank form. You can change this default behavior by changing Object Repository options.

Specifying the default new project

The default new project opens whenever you choose New Application from the File menu on the C++Builder menu bar. If you haven't specified a default project, C++Builder creates a blank project with an empty form. You can specify a project template (including a project you have created and saved as a template) as the default new project.

You can also designate a project wizard to run by default when you start a new project. A project wizard is a program that enables you to build a project based on your responses to a series of dialog boxes.

To specify the default new project,

1	Choose Options|Repository to display the Object Repository dialog box.

2	Choose Projects in the Pages list.

3	Select the project object you want as the default new project from the Objects list.

4	With the object you want selected, check New Project.

5	Choose OK to register the new default setting.

Specifying the default new form

The default new form opens whenever you choose File|New Form or use the Project Manager to add a new form to an open project. If you haven't specified a default form, C++Builder uses a blank form. You can specify any form template, including a form you have created and saved as a template, as the default new form. Or you can designate a form wizard to run by default when a new form is added to a project.

To specify the default new form for new projects,

1	Choose Options|Repository to display the Object Repository dialog box.

2	Choose Forms in the Pages list.

3	Select the form object you want as the default new form.

4	With the object you want selected, check New Form.

5	Choose OK to register the new default setting.

Specifying the default main form

Just as you can specify a form template or wizard to be used whenever a new form is added to a project, you can also specify a form template or wizard that should be used as the default main form whenever you begin a new project.

To specify the default main form for open projects,

1	Choose Options|Repository to display the Object Repository dialog box.

2	Choose Forms in the Pages list.

3	Select the form object you want as the default main form.

4	With the object you want selected, check Main Form.

5	Choose OK to register the new default setting.


Workgroups menu
C++Builder version control interface

See also

After you have created more than one application or source code file with C++Builder, you may want a way to organize and keep track of the programs. You may want to archive old versions of an application before you start to work on the new version. If you work with a team of programmers, you will need a way to coordinate which programmers have access to certain files, so that one programmer does not accidentally lose, change, or overwrite another programmer's code.

A version control system is useful when managing multiple or complex programming projects. Version control is used to archive files, control access to files by locking, and manage multiple versions of your projects. C++Builder includes an interface to Intersolv PVCS Version Manager 5.1 or later.

For more information, see the PVCS Version Control online help (PVCS.HLP) located in the Borland C++Builder Help directory.

Enabling PVCS support

C++Builder's version control system support should be enabled when you run the setup program.

The Workgroups menu group appears in the C++Builder menu bar. Choose commands from the Workgroups menu to use the PVCS Version Manager. Here is a list of the commands on the Workgroups menu:

Browse PVCS Project

Manage Archive Directories

Add Project to Version Control

Set Data Directories


Workgroups|Browse PVCS Project command
Workgroups|Browse PVCS Project

Choose Workgroups| Browse PVCS project to display an explorer type view of the current project.  The project must fist be created using the Add Project to Version Control menu item.


Workgroups|Manage Archive Directories command
Workgroups|Manage Archive Directories

See also

Choose Workgroups|Manage Archive Directories to specify the locations of archive directories.

To use the Manage Archive Directories dialog box,

1.	Specify an archive directory in the Directory and Drives lists.

2.	To designate the specified directory an archive location, choose Add.

3.	To remove an archive location from the Archive directories list, choose Remove.

4.	Choose OK to save the archive directory specification.

For more information, see the PVCS Version Control online help (PVCS.HLP) located in the Borland C++Builder Help directory.


Workgroups|Add Project to Version Control

Choose Workgroups|Add Project to Version Control to create a new PVCS project for the current C++Builder Project.


Workgroups|Set Data Directories

Set Data Directories to specify the location of public and private project root directories. PVCS will use these directories to store subdirectories and files which contain information specific to the projects under PVCS version control.


Custom Expert menu item

You have pressed F1 on a menu item for an Expert that was installed externally. For more information regarding this item, select it to open the Expert. Help is available for externally installed Experts if provided by the developer of the Expert.


Custom Version Control menu item

You have pressed F1 on a menu item for a version control system that was installed externally. For more information regarding this item, select it to gain access to the version control system. Help may be available for your version control system depending on the particular installation.


About the Menu designer

See Also

The Menu designer enables you to easily add menus to your form. You can simply add menu items directly into the Menu designer window. You can add, delete, and rearrange menu items at design time and you do not have to run the program to see the results. Your application menus are always visible on the Form, as they will appear during runtime.

You can build each menu structure entirely from scratch, or you can start from one of the Menu templates (predesigned menus). You can also dynamically change menus, to provide more information or options to the user.


Opening the Menu designer

See Also

To open the Menu designer,

1.	Place a MainMenu or a PopupMenu component on the form.

2.	Leaving the component selected, choose from one of the following methods:

Right click and select Menu designer.

Double-click the MainMenu or PopupMenu component.

Click the ellipses button in the Values column for the Items property.


Naming menus

See Also

When you add a menu component to the form, it has a default name, for example, MainMenu1. You can give the menu a more meaningful name that follows C++ naming conventions.

The menu name is added to the form’s type declaration, and then it appears in the Component list.


Naming menu items

See Also

In contrast to the menu component itself, you need to explicitly name menu items while adding them to the form. You can do this in one of two ways:

Directly type the value for the Name property.

Type the value for the Caption property first, and let C++Builder derive the Name property from the caption.

For example, if you give a menu item a Caption property value of File, C++Builder assigns the menu item a Name property of File1. If you specify the Name property before the Caption property, C++Builder leaves the Caption property blank until you type a value.

Note:	If you enter characters in the Caption property that are not valid for C++ identifiers, C++Builder modifies the Name property accordingly. For example, to start the caption with a number, C++Builder precedes the number with a character to derive the Name property.

The following table demonstrates some examples of this, assuming all menu items shown appear in the same menu bar.

Component name	Derived caption	Explanation
&File	File1	Removes ampersand
&File (second occurrence)	File2	Numerically orders duplicate items
1234	N12341	Adds a preceding letter and numeric order
1234 (second occurrence)	N12342
$@@@#	N1	Removes all non-standard characters, adding preceding letter and numeric order
- (hyphen)	N2	Numerical ordering of second occurrence of caption with no standard characters
As with the menu component, C++Builder adds any menu item names to the form's type declaration, and those names then appear in the Component list.


Adding menu items

See Also

To add menu items,

1.	Open the Menu designer.

2.	Select the position where you want to create the menu item.

3.	Type the Name and press Enter. C++Builder automatically changes the caption of the menu item to reflect the name.

4.	Press Enter.

The next placeholder for a menu item is selected.

5.	Enter values for the Name properties for each new item you want to create, or press Esc to return to the menu bar.

Use the arrow keys to move from the menu bar into the menu, and to then move between items in the list; press Enter to complete an action.

To add a separator bar to a menu, enter a hyphen as the caption of the menu item.


Inserting a menu item

See Also

To insert a menu item into a menu,

 	Place the cursor on a menu item, then press the Insert key.

Menu items are inserted to the left of the selected item on the menu bar, and above the selected item in the menu list.


Deleting a menu item

See Also

To delete a menu item from a menu,

1.	Place the cursor on the menu item you want to delete.

2.	Press the Delete key.

You cannot delete the default placeholder that appears below the item last entered in a menu list, or next to the last item on the menu bar. This placeholder does not appear in the menu at runtime.


Specifying accelerator keys

See Also

Add an ampersand (&) in front of the appropriate letter in the caption. The letter after the ampersand appears underlined in the menu.

Accelerator keys let the user access a menu command from the keyboard by pressing Alt+ the appropriate letter, indicated in your code by the preceding ampersand. The letter after the ampersand appears underlined in the menu.

Caution:	C++Builder does not check for duplicate accelerators.  You must track values you have entered in your application menus.


Specifying keyboard shortcuts

See Also

Enter a value for the ShortCut property, or select a key combination from the drop-down list. However, this list contains a subset of the valid combinations you can use.

Keyboard shortcuts enable the user to perform the action without accessing the menu directly by typing the shortcut key combination.

Caution:	C++Builder does not check for duplicate shortcut keys, you must track values you have entered in your application menus.


Creating nested menus

See Also

To create nested menus,

1.	Select the menu item under which you want to create a nested menu.

2.	Press Ctrl+Right arrow to create the first placeholder, or choose Create Submenu from the context menu.

3.	Enter a name for the nested menu item.

4.	Press Enter to create the next placeholder.

5.	Repeat steps 3 and 4 for each item you want to add to the nested menu.

6.	Press Esc to return to the previous menu level.

Organizing your menu structure using nested menus can save vertical screen space. However, for optimal design purposes you probably want to use no more than two or three menu levels in your interface design. (For pop-up menus, you might want to use only one such nested level, if any.)

Shortcut:	You can also create a nested menu by inserting a menu item from the menu bar (or a menu template) between menu items in a list. When you move a menu into an existing menu structure, all its associated items move with it, creating a fully intact nested menu. This pertains to nested menus as well; moving a menu item into an existing nested menu just creates one more level of nesting.


Moving menu items

See Also

During design time, you can move menu items simply by dragging and dropping. You can move menu items along the menu bar, or to a different place in the menu list, or onto a different menu entirely.

You cannot demote a menu item from the menu bar onto its own menu; nor can you move a menu item into its own nested menu. However, you can move any item onto a different menu.

While you are dragging, the cursor changes shape to indicate whether you can release the menu item at the new location. When you move a menu item, any items beneath it move as well.

To move a menu item along the menu bar,

1.	Drag the menu item along the menu bar until the arrow tip of the drag cursor points to the new location.

2.	Release the mouse button to drop the menu item at the new location.

When you move a menu item to a different place on the menu bar, all the sub-items beneath it move as well.

To move a menu item into a menu list,

1.	Drag the menu item along the menu bar until the arrow tip of the drag cursor points to the new menu.

This causes the menu to open, enabling you to drag the item to its new location.

Note: You cannot move a menu item down a level into its own menu.

2.	Drag the menu item into the list, releasing the mouse button to drop the menu item at the new location.

Moving menu items into submenus

When you move a menu item off the menu bar, its sub-items become a submenu. Similarly, if you move a menu item into an existing submenu, its sub-items then form another nested menu under the submenu.

You can move a menu item into an existing submenu, or you can create a placeholder at a nested level next to an existing item, and then drop the menu item into the placeholder to nest it.


Viewing the menu

See Also

You can view your menu at design time without running the application. (Pop-up menu components are visible in the form at design time, but the pop-up menus themselves are not. Use the Menu designer to view a pop-up menu at design time.)

To view the menu,

1.	If the form is visible, click the form, or from the View menu, choose the form whose menu you want to view.

2.	If the form has more than one menu, select the menu you want to view from the form’s Menu property drop-down list.

The menu appears in the form exactly as it will when you run the program.


Editing menu items without opening the Menu designer

See Also

When you edit a menu item using the Menu designer, its properties are still displayed in the Object Inspector. You can switch focus to the Object Inspector and continue editing the menu item properties there. Or you can select the menu item from the Component list and edit its properties without ever opening the Menu designer.

To edit a menu item without opening the Menu designer,

Select the item from the Component list.

To close the Menu designer window and continue editing menu items,

1.	Switch focus from the Menu designer window to the Object Inspector by clicking the properties page of the Object Inspector.

2.	Close the Menu designer.

The focus remains in the Object Inspector, where you can continue editing properties for the selected menu item.

To edit another menu item, select it from the Component list.


Switching amoung menus at design time
Switching among menus at design time

See Also

If you are designing several menus for your application, you can use the Menu designer context menu or the Object Inspector to easily select and move among them.

To use the context menu to switch among menus in a form,

1.	Right-click the Menu designer to display the context menu.

2.	From the context menu, choose Select Menu.

The Select Menu dialog box appears. This dialog box lists all the menus associated with the form whose menu is currently open in the Menu designer.

3.	From the list in the Select Menu dialog box, choose the menu you want to view or edit.

To use the Object Inspector to switch among menus in a form,

1.	Select the form whose menus you want to choose from.

2.	From the Component list, select the menu you want to edit.

3.	On the Properties page of the Object Inspector, select the Items property for this menu, and then either click the ellipsis button (...), or double-click [Menu].


Using menu templates

See Also

C++Builder provides several predesigned menus, or menu templates, that contain frequently used commands. You can use these menus in your applications without modifying them (except to write code), or you can use them as a starting point, customizing them as you would a menu you originally designed yourself. Menu templates do not contain any event handler code.

Menu templates are stored in the file BCB.DMT. The menu templates shipped with C++Builder also reside in this file.

You can also save as a template any menu that you design using the Menu designer. After saving a menu as a template, you can use it as you would any predesigned menu. If you decide you no longer want a particular menu template, you can delete it from the list.

To add a menu template to your application,

1.	Right-click the Menu designer window.

The Menu designer context menu appears.

2.	From the context menu, choose Insert From Template.

(If there are no templates, the Insert From Template option is dimmed.)

The Insert Template dialog box opens, displaying a list of available menu templates.

3.	Select the menu template you want to insert, then press Enter or choose OK.

This inserts the menu into your form at the cursor's location. For example, if your cursor is on a menu item in a list, the menu template is inserted above the selected item. If your cursor is on the menu bar, the menu template is inserted to the left of the cursor.

To delete a menu template,

1.	Right-click the Menu designer window.

The Menu designer context menu appears.

2.	From the context menu, choose Delete Templates.

(If there are no templates, the Delete Templates option appears dimmed in the context menu.)

The Delete Templates dialog box opens, displaying a list of available templates.

3.	Select the menu template you want to delete, and press Del.

C++Builder deletes the template from the templates list and from your hard disk.


Saving a menu as a template

See Also

Any menu you design can be saved as a template so you and others can use it again. You can use menu templates to provide a consistent look to your applications, or use them as a starting point which you then further customize.

Menu templates you save are stored in your BIN directory as .DMT files.

You edit the template file by using the template commands from the Menu designer context menu.

To save a menu as a template,

1.	Choose Save As Template from the Menu designer context menu to open the Save Template dialog box.

2.	In the Template Description edit box, enter a brief description of this menu.

3.	Click OK.

The Save Template dialog box closes, saving your menu design and returning you to the Menu designer window.

Note: The description you enter is displayed only in the Save Template, Insert Template, and Delete Templates dialog boxes. It is not related to the Name or Caption property for the menu.

When you save a menu as a template, C++Builder does not save its Name, since every menu must have a unique name within the scope of its owner (the form). However, when you insert the menu as a template into a new form by using the Menu designer, C++Builder then generates new names for it and all its items.

C++Builder also does not save any event handlers associated with a menu saved as a template, since C++Builder cannot test whether the code would be applicable in a new form. You can associate menu items in the template with existing event handlers in the form.


Naming conventions for template menu items and event handlers

See Also

When you save a menu as a template, C++Builder does not save its Name property, since every menu must have a unique name within the scope of its owner (the form). However, when you insert the menu as a template into a new form by using the Menu designer, C++Builder then generates new names for it and all its items.

For example, suppose you save a File menu as a template. In the original menu, you name it MyFile. If you insert it as a template into a new menu, C++Builder names it File1. If you insert it into a menu with an existing menu item named File1, C++Builder names it File2.

C++Builder also does not save any OnClick event handlers associated with a menu saved as a template, since there is no way to test whether the code would be applicable in the new form. When you generate a new event handler for the menu template item, C++Builder still generates the event handler name.

You can easily associate items in the menu template with existing OnClick event handlers in the form.


Adding menu items dynamically

See Also

You can add menu items to an existing menu structure while the application is running to provide more information or options to the user.

Insert a menu item by using the menu item's Add or Insert method.

Alternately hide and show the items in a menu by changing their Visible property. The Visible property determines whether the menu item is displayed in the menu.

Dim a menu item without hiding it by using the Enabled property.

In Multiple Document Interface (MDI) and ActiveX applications, you can also merge menu items into an existing menu bar. See Merging Menus.

To insert a menu item into an existing menu,

1.	Create an event handler for the event you want to respond to.

2.	Declare the menu item as a variable of type TMenuItem.

3.	Write a procedure that adds the menu item to an existing menu.


Example

The following example adds a new menu item to the Window menu (WindowMenu) when Button1 is clicked.

void __fastcall TForm1::::Button1Click(TObject *Sender)

{

  TMenuItem *NewItem

  NewItem= new TMenuItem(WindowMenu);     //Creates the new menu item

  NewItem ->Caption = "My Menu Command";  //Caption for the new menu item

  WindowMenu->Insert(1, NewItem);         //Inserts the new menu item

}


Merging menus

See Also

For Multiple Document Interface (MDI) and Single Document Interface (SDI) applications, the application's main menu needs to be able to receive menu items either from another form or from the ActiveX server object. This is called merging menus.

You prepare menus for merging by specifying values for two properties:

Menu, a property of the form

GroupIndex, a property of menu items in the menu

Specifying the active menu: Menu property

The Menu property specifies the active menu for the form. Merge operations apply only to the active menu. If the form contains more than one menu component, you can change the active menu at runtime by setting the Menu property in code. For example,

Form1->Menu = SecondMenu;

Determining the order of merged menu items: GroupIndex property

The GroupIndex property determines the order in which the merging menu items appear in the shared menu bar. Merged menu items can replace those on the main menu bar or can be inserted.

The default value for GroupIndex is 0. Several rules apply when specifying a value for GroupIndex:

Lower numbers appear first (farther left) in the menu.

For instance, set the GroupIndex property to 0 (zero) for a menu that you always want to appear leftmost, such as a File menu. Similarly, specify a high number (it needn't be in sequence) for a menu that you always want to appear rightmost, such as a Help menu.

To replace items in the main menu, give items on the child menu the same GroupIndex value.

This can apply to groups or to single items. For example, if your main form has an Edit menu item with a GroupIndex value of 1, you can replace it with one or more items from the child form's menu by giving them a GroupIndex value of 1 as well.

Giving multiple items in the child menu the same GroupIndex value retains their order intact when they merge into the main menu.

To insert items without replacing items in the main menu, leave room in the numeric range of the main menu's items and "plug in" numbers from the child form.

For example, number the items in the main menu 0 and 5, and insert items from the child menu by numbering them 1, 2, 3, and 4.

Additional rules apply for ActiveX client applications.


Importing menus from resource files

See Also

The Menu designer supports menus built with other applications, so long as they are in the standard Windows resource (.RC) file format. You can import such menus directly into your project, saving you the time and effort of rebuilding menus that were created elsewhere.

To load an existing .RC menu file,

1.	In the Menu designer, place the cursor where you want the menu to appear.

The imported menu can be part of a menu you are designing, or an entire menu in itself.

2.	Right click and choose Insert From Resource.

The Insert Menu From Resource dialog box displays.

3.	Select the resource file you want to load, and choose OK.

Note: If your resource file contains more than one menu, you first need to save each menu as a separate resource file before importing it.


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4112


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4113


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4114


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4116


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4117


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4118


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4119


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4110


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4121


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4122


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4123


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4124


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4126


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4127


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4128


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4129


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4131


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4133


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4134


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4135


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4136


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4137


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4138


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4139


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4130


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4141


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4142


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4143


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4144


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4145


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4146


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4147


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4148


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4149


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4140


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4151


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4152


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4153


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4154


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4155


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4156


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4157


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4158


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4159


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4150


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4161


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4162


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4163


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4164


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4165


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4166


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4167


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4168


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4169


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4160


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4172


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4173


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4174


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4175


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4176


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4177


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4178


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4179


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4170


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4181


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4182


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4183


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4184


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4185


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4186


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4187


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4188


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4189


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4180


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4191


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4192


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4193


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4194


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4195


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4196


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4197


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4198


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4190


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4101


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4102


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4103


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4104


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4105


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4106


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4107


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4108


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4109


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4100


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4011


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4012


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4013


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4014


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4015


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4016


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4017


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4018


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4019


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4010


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4021


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4022


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4023


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4024


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4025


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4026


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4027


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4028


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4029


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4020


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4031


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4032


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4033


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4034


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4035


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4036


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4037


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4038


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4039


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4030


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4041


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4042


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4043


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4044


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4045


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4046


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4047


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4048


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4049


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4040


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4051


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4052


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4053


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4054


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4055


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4056


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4057


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4058


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4059


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4050


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4061


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4062


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4063


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4064


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4065


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4066


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4067


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4068


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4069


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4071


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4072


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4073


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4074


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4075


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4076


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4077


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4078


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4079


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4070


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4081


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4082


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4083


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4084


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4085


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4086


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4087


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4088


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4089


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4080


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4091


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4092


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4093


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4094


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4095


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4096


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4097


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4098


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4099


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4090


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4001


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4002


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4003


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4004


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4005


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4006


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4007


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

4008


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MWClearCompilerMessages


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DAllUnitsUsed


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGMissingDefaultMakeFile


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_FirstRunDlg


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MHelpWhatsNew


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGDuplicateContains


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DFileDateChanged


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGInvalidStackBreakpoint


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_RedirectLinkDlg


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MWClearSearchResults


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_RedirectLinkError


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGMissingMakeSymbol


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGBuildPackage


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MsgDeleteAxRegInfo


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_CompilerErrorFirst


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_ViewModuleDialog


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGNoInMemoryExeProject


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DNewInheritedForm


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DHTMLFileOpen


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MViewsPropInsp


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_mRunMTXInstall


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DOpenAddContains


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGNotAllowedOnPasForm


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGRequiresError


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_CompilerErrorLast


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGWrongProjExtension


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_SearchDialog


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGWrongUnitExtension


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_EditPageNameDialog


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGNoInMemoryExeUnderWin95


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGCantCompileHostPackage


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MFileNewDataModule


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MWSaveMessages


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DResetWarning


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_ChangeDialog


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGContainsError


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DOpenPackage


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_DDebuggeeFaulted


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_EditClassNameDialog


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGDuplicateRequires


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGFormVarsError


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MWindow


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGDirectivesError


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_UseUnitDialog


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_NewInheritedFormDialog


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGWrongFormExtension


No Help topic is associated with the control or object you selected. Click here to search the index for the word or phrase you need.

HC_MSGMissingFormHdr


OnScroll event


Backcolor property


Title property


Monochrome property