Ide/Resource Editor

IDE
Environment Overview Projects Project Settings Project Tree Collaboration Options Creating new Project Items Text Editor Resource Editor Code Experts Debugger Command Line Tools Make Facility External Tools Messages and Errors Window TODO Window IDE Dialogs $(ProDir) Subdirectories Key Bindings

The term resource is applied to the things like dialogs, forms, icons, cursors, pens, brushes, etc. Resources can be created by one of the IDE resource editors, or just added to a project. The correspondent resource files are referenced from a project file.

During project building IDE generates binary ProjectName.res file which is provided to a linker. IDE also generates resourceIdentifiers.i file which specifies numeric constants for resource identifiers. Resource identifierd can be refered from sources codes to provide the proper resource handling. The names and values for resource identifiers can be set or changed with the help of IDE resource editors.

GUI and VPI Style Resources

Historically windowing programs - that is, programs with the graphical user interface - were developed in Visual Prolog using the VPI (Visual Programming Interface) package supplied as one of packages in Prolog Foundation Classes (PFC).

The Visual Programming Interface (VPI) is a high-level Application Programming Interface (API) and it is designed to make it easy for Prolog applications to provide sophisticated user interfaces utilizing the graphical capabilities of today's operating systems and display hardware. The resources and tools needed by such applications - windows, menus, dialogs, controls, pens, brushes, cursors, carets, pictures, etc. all appear as simple Prolog structures.

However, the VPI layer (PFC\vpi) provides an old style of handling the graphical user interface. This was the reason why the PDC has developed the modern GUI package (pfc\gui), which provides really object-oriented implementation of API handling of the main windowing system features. The GUI package presents the object-oriented windows, dialogs, forms, controls, etc., handling. This package is built on top of the VPI package and delivers a new level of abstraction and ease of use while retaining compatibility with VPI programs since both the GUI and VPI programming styles can be applied in the same program.

Currently for new GUI applications the IDE generates the default program code which use the GUI package features (but it still possible to edit old VPI style dialogs, etc.).

Notice that in VPI style programs, except for VPI style dialogs and VPI style windows you can also create GUI style forms, which, of course, are handled by GUI package predicates. From the other side, since each GUI program includes the VPI package, so some VPI features can be embedded into GUI style programs.

To understand difference of GUI and VPI style programs and difference of GUI and VPI style dialogs, windows, forms, controls, etc., we recommend to read carefully VPI and GUI programming tutorials on WEB.

IDE Designer

Editing of dialogs, windows, form, and IDE Controls on the IDE Designer are very closely related. The only real difference is that definitions of the VPI package dialogs are (normally) put into resource files, whereas GUI package dialogs, windows, and forms are always created dynamically by code.

Creating a Dialog

To create and register a new dialog in a project you need to use the File | New menu command. Then the Create Project Item dialog will look like:

Name

In the Name field you should type in the name, which will be associated with this dialog in the automatically generated code. This name should be a correct Visual Prolog name. It should be any sequence of letters, digits, and underscores, beginning with a letter. This name is used to generate names of files handling the dialog. These files appear in the project tree in the Project window. The Code Expert uses this name for names of predicates handling the dialog.

Package

You should check one of the New Package or Existing Package radio buttons to specify whether the generated resource file, interface and class, which handle the dialog, will be included to the new package that will be created or will be included to the existing one.

If you check the New Package button, then you can specify the parent directory name in the Parent Directory field. The package and the dialog handling files will be created and placed into the parent directory.

If you check the Existing Package button, then in the Package list button you should select one of the packages known to the project. The files handling the created dialog will be included into this package. The created files will be placed into the selected package subdirectory

In namespace

If this flag is checked, then it is possible to define a namespace in which the correspondent automatically generated interface, class declaration and class implementation will be placed.

After you fill in all required settings, you should press the Create button, then the Dialog Properties/Attributes dialog appears.

Dialog Properties and Attributes

When you create a dialog it looks like:

Title

At runtime this text appears in the title of the dialog window. This field is ignored if the Titlebar property is set to false or Titlebar check box is not checked.

Dialog Type

It is the Type property. Values Modal and Modeless can be set.

If the Modal property is set to true, then the created dialog will be modal. Modal dialogs prohibit activation of another windows or dialogs in the same application until the modal dialog is closed.

If the Modal property is set to false, then the created dialog will be modeless.

Style Flags

Set of properties that control the look of the dialog. When some option is set to true, then the correspondent property is set to the dialog.

• Titlebar

  When this attribute is set to true or is checked, the dialog will have a title bar.

• CloseBox

  When this attribute is set to true or is checked, the dialog will have a close box.

• MaximizeBox

  Creates the maximize box in the title bar of the dialog window.

• MinimizeBox

  Creates the minimize box in the title bar for the dialog window.

• Invisible

  When the dialog will be opened the first time, it will be invisible. Notice that, even if a modal dialog is created with the Invisible option, it will be initially visible.

  The programmer can make a modal dialog invisible by the call to

  window::setState([vpiDomains::wsf_Invisible,...])

• Disabled

  Determines that the dialog will be displayed as disabled (grayed) when it will be first opened.

• ClipSiblings

  Specifies that two dialogs with the same parent window should use clipping.

• ClipChildren

  Specifies that drawing over any child windows should be clipped.

• HorizScrollbar

  When it is set to true, the dialog includes a horizontal scroll bar.

• VertScrollbar

  When it is set to true, A the dialog includes a vertical scroll bar.

• ChildDialog

  Specifies that the dialog window has behavior similar to child windows. This means that:

  • The dialog window is restricted to stay inside the client rectangle of its parent window.
  • The dialog window can be partially or completely obscured by any overlapping windows.
  • Under MDI mode. When the parent window of the dialog is a task window, then the created dialog is (usually) initially hidden (obscured by other windows).

  It is disabled if the Modal property is set to true.

• SizeBorder

  When it is set to true, the dialog gets double border (such dialogs can be resized).

Position
Size

Two properties that determine the position and the size of the dialog. The coordinates are given in Dialog Base Units. One unit in the X direction is equal to one quarter of the width dialog base unit. One unit in the Y direction is equal to one eighth of the height dialog base unit. The dialog base units are computed from the height and width of the system font.

Font

The property for with which you can select attributes of the font used in controls of the dialog. Note that the selected font is not seen while dialog editing, but using the Resource | Test Mode command it is possible to see how the dialog will look like. The Dialog Base Unit size is scaled by the operating system depending upon the font size - but note that bitmaps and icons are not scaled. Be careful not to specify any fonts that may not exist in the environments where your application might be used.

Default Button

Specifies the default button for a dialog. This button action is called when the user presses the Enter key.

After you fill all the required attributes you may click the OK button. Clicking the OK button you create the new dialog in the current project.

The properties panel is always present in design mode.

After you compile the package in which the created dialog is included, the project tree starts to display files handling the dialog (the interface, the class, and the implementation).

Editing a Dialog

To edit a dialog, in the project tree (in the Project window) double click (or press Enter) the name of a file with a dialog description (the .dlg filename extension). The IDE Designer appears and you can edit whatever form of a dialog you wish.

The IDE Designer After Creation of a New Dialog

When a new dialog is created, it will by default have three push button controls: OK, Cancel and Help. These can freely be rearranged or deleted.

Dialog Controls

Each control in a dialog must have an identifying name (constant in VPI style dialogs), which is unique within that dialog. While two controls within one dialog may not have the same name (or constant value), it is actually a good idea if controls in different dialogs, which perform the same action have the same names (or constants).

Types of Controls

	A Push Button control serves to initiate a specialized action in an application.
	A Check Box control lets you indicate a choice among two alternatives. For example some facility may be switched ON or switched OFF.
	A group of Radio Button controls serves to indicate one choice from among a list of alternatives.
	A Static Text control reserves an area for the text in the dialog. Although called static, in fact the application can change the text during execution. This is often used for prompts or field names relating to other controls.
	An Edit Control reserves an area for text editing (e.g. names, numbers, text constants etc.). Editing text strings with multiple lines is possible.
	A List Box allows you to view a list of elements and to select one - or several - elements from this list.
	A List Button control serves for choosing one from the pop-out set of the alternatives revealed by pressing the button. Pressing the button again pops the list back in again.
	A List Edit control allows single line text editing like an Edit control, or selection from a list of elements.
	The Vertical Scroll Bar and the Horizontal Scroll Bar controls serve to select a value within a scale of values.
	A Group Box control serves for assembling together a number of controls in a functional group with a Group Name. Its only function is a visual one.
	An Icon control reserves an area for an icon image.
	A Custom Control can be either IDE Controls created in the project, it can be VPI user-defined control with a window class defined by vpi::classCreate, or it can be controls imported as COM packages from DLLs, VBXs or OCXs.

Inserting Controls

To insert a new control in a dialog, click the icon of the desired control type in the Controls toolbar. (You can also select the desired control type in the Controls sub-menu of the main IDE menu or in the pop-up menu in the IDE Designer.)

Controls Toolbar

Originally the Controls toolbar is displayed below the IDE Designer window. You see it in the following picture:

The Controls Toolbar

Clicking icons in the Controls toolbar you select a type of a control to be placed into the edited dialog/window/form/IDE control (sometimes we will use the term container instead of dialog/window/form/IDE control). When you click a control type icon, then the current cursor is replaced with the cursor correspondent to the control type to be inserted. Move the cursor to some position in the container client area and click the mouse button. The control with the default size will be inserted at the specified position.

Instead of dropping a control into a container with a click, it is possible to drag out the rectangle (in the container client area) where a control should be placed; so you can specify not only the control position but also the control size.

After a VPI control is placed with the mouse into a VPI style container, the correspondent VPI control Attributes dialog appears. In this dialog you can change some control attributes, when you close the dialog, the control appears at the specified location in the container.

After a GUI control is placed with the mouse into a GUI style container, it immediately appears at the specified location in the container. To change properties of the GUI control, one should select it then the list of GUI control properties appears in the [Properties_of_GUI_Controls\Properties_of_GUI_Controls.htm GUI control Properties table].

There are the following icons in the Controls toolbar:

Icon	Insert a new:	Description
	Push Button	After selection of this control the cursor becomes
	Check Box	After selection of this control the cursor becomes .
	Radio Button	After selection of this control the cursor becomes .
	Static Text Control	After selection of this control the cursor becomes .
	Edit Control	After selection of this control the cursor becomes .
	List Box	After selection of this control the cursor becomes .
	List Button	After selection of this control the cursor becomes File:Ie Cursor ListBtn.png.
	List Edit	After selection of this control the cursor becomes .
	Horizontal Scroll Bar	After selection of this control the cursor becomes .
	Vertical Scroll Bar	After selection of this control the cursor becomes .
File:Id Ctrl GroupBox.png	Group Box	After selection of this control the cursor becomes .
	Icon Control	After selection of this control the cursor becomes .
	Custom Control	After selection of this control the cursor becomes .

Selecting and Deselecting Controls

Click inside a control to select one control. A frame appears around the selected control.

To select a group of controls move the mouse pointer to the point in the dialog you want to be one corner of the selected area and press and hold the left mouse button. While holding the left mouse button move the mouse until all the desired controls in the dialog are inside the selected area. Then release the mouse button. All controls inside the specified rectangle will be selected.

Also after one or more controls are already selected, you can include one extra control in the selection by holding down the Ctrl key and click the control.

To deselect the control or group of controls click outside the selecting frame. Deselected controls lose their frame.

Resizing Controls

Once a control has been inserted in the dialog, it has a default size. To re-size a control, first click inside the control area to select it. Then move the cursor to the sizing handles on the selection frame. A new shape of cursor indicates the direction in which you can re-size the control. Press and hold the mouse button, drag until the selected control has the size you want, then release the mouse button.

You can also change the size of a control by double-clicking it to activate the dialog for control attributes setting. Select the position you want to change and after specifying a new position or size, press enter to return to the dialog.

Remark: You cannot change the size of icons. You can only change their location.

Moving Controls

To move a control or a group of controls first select them. Then move the cursor inside the selection frame, press and hold the mouse button, drag the mouse pointer to a new location and release the mouse. Also, when one or more controls are selected, it is possible to use the cursor keys to move the selection in small steps (corresponding to the Grid settings).

Arranging Controls

To arrange a group of controls first select the group. Then click an appropriate button in the Layout toolbar or a menu item in the Layout menu of the IDE menu (or in the pop-up menu).

The Layout Toolbar

The Layout commands for justifying and resizing controls:

	Align Left	Align the selected controls along their left sides.
	Align Center	Center the selected controls vertically.
	Align Right	Align the selected controls along their right sides.
	Align Top	Align the selected controls along their tops.
	Align Middle	Center the selected controls horizontally.
	Align Bottom	Align the selected controls along their bottoms.
	Even Horizontal Spacing	Spacing the selected controls evenly between the leftmost and the rightmost controls.
File:GridButton.png	Grid	Toggle the Grid (see below).
	Even Vertical Spacing	Spacing the selected controls evenly between the topmost and the bottom-most controls.
	Make Same Size	Make the selected controls the same size as a model control.
	Make Same Horizontal Size	Make the selected controls the same width as a model control.
	Make Same Vertical Size	Make the selected controls the same height as a model control.
	Size To Contents	Resize the selected controls to optimally display its titles (caption texts).

Editing Properties of GUI Controls

When you open a GUI dialog or a Form (GUI window) in the IDE Designer, then near from the opened dialog (form) the [Properties_of_GUI_Controls\Properties_of_GUI_Controls.htm Control Properties] table appears.

To change properties of a GUI package control first select this control (by clicking in it) in the dialog (form). The current set of the control properties appears in the Control Properties table. Now you can edit the displayed GUI control properties.

Click here to view [Properties_of_GUI_Controls\Properties_of_GUI_Controls.htm GUI Control Properties table.]

The displayed set of properties depends on the control type. The [Properties_of_GUI_Controls\Properties_of_GUI_Controls.htm Control Properties] table contains two types of properties. General properties are common to all types of controls and some properties, which are individual to different kinds of controls.

Initially this Control Properties table is empty. However, as soon as one of controls in the edited dialog (form) is selected this table starts to display properties of the selected control.

If the Control Properties table is closed, then double-click a control - the Control Properties table appears. Also the Control Attributes command, from the IDE Designer [Editing_a_Dialog.htm#Speed_Menu speed menu], can be used to open the Control Properties table.

Editing Attributes of VPI Controls

To change attributes of a VPI package control double-click it or select the control and activates the Control Attributes command from the IDE Designer [Editing_a_Dialog.htm#Speed_Menu speed menu]. Then the <ControlType> Attributes dialog appears.

These dialogs contains two levels of attributes. The general group contains attributes, which are common to all types of controls: the Text determines the control title, the Constant (name) is used as the control identifier, and the Control Size group determines position and size of the control.

Notice that the Text property/attribute is not used for some controls, for instance, it is not used for scroll bars.

Notice that in the Text fields the ampersand symbol & is reserved for indicating that the next to it character is to be underlined. For example, if you use the text string E&xit as a control name, then this control will be displayed with the title Exit at runtime. I.e. the char x will be displayed underlined (thus visually indicating that the x is an accelerator key). If you need to display the ampersand & symbol in the Text of a control, then use two of them &&.

Other attributes are individual to different kinds of controls.

Attributes of VPI Controls:

[Properties_of_VPI_Controls\Push_Button_Flags.htm Push Button Attributes]

[Properties_of_VPI_Controls\Check_Box_Flags.htm Check Box Attributes]

[Properties_of_VPI_Controls\Custom_Control_Attributes.htm Custom Control Attributes]

[Properties_of_VPI_Controls\Radio_Button_Flags.htm Radio Button Attributes]

[Properties_of_VPI_Controls\Static_Text_Flags.htm Static Text Attributes]

[Properties_of_VPI_Controls\Edit_Control_Flags.htm Edit Control Attributes]

[Properties_of_VPI_Controls\List_Box_Attributes.htm List Box Attributes]

[Properties_of_VPI_Controls\List_Button_Attributes.htm List Button Attributes]

[Properties_of_VPI_Controls\List_Edit_Attributes.htm List Edit Attributes]

[Properties_of_VPI_Controls\Scroll_Bar_Attributes.htm Scroll Bar Attributes]

[Properties_of_VPI_Controls\Group_Box_Attributes.htm Group Box Attributes]

[Properties_of_VPI_Controls\Icon_Control_Attributes.htm Icon Attributes]

Using Anchors for Positioning GUI Controls while Dialog Resizing

VPI controls remember in their attributes ([#Attributes_of_VPI_Controls Attributes of VPI Controls]) only their absolute positions and sizes. Therefore, when a VPI dialog or a VPI window containing such VPI controls are resized, these VPI controls do not change their positions and sizes!

In difference to them GUI controls have additional Anchor properties, which help to reposition (and may be resize) GUI controls when containing them GUI dialog (or form) is resized.

Each GUI control has four anchor properties: Left Anchor, Top Anchor, Right Anchor, and Bottom Anchor (see [Properties_of_GUI_Controls\Properties_of_GUI_Controls.htm#Anchors Anchor Properties of GUI Controls]).

Each anchor determines that the specified (Left, Top, Right or Bottom) control boundary should be always positioned on the stated distance from the nearest (correspondent) border of the dialog (frame).

Each of anchors can have the True or False values. When the anchor value is True, then this anchor is active (used to position the correspondent control).

For example, when the Left Anchor is active (has the True value), then the left control boundary should be positioned on the stated distance from the nearest (left) border of the dialog (frame).

The simplest way to see which anchors are active for a control, is to select this control. Then some red arrows between control boundaries and correspondent boundaries of the dialog can bee seen. Each arrow specifies, that the correspondent anchor is active. For example, the arrow from the control top to the dialog top identifies, that the Top Anchor is active. In the picture below, you see three arrows, which specify that the Left, Top, and Right anchors are active to the Push Button control.

File:De Anchors.png

Numbers near such arrows show distances (in Dialog Base Units) between the correspondent boundaries of the control and the dialog.

Normally each control has one active horizontal and one active vertical anchors. When the dialog is resized, then such control is always positioned on the specified distances from the specified boundaries of the dialog. The size of the control is not changed!

When a control has both horizontal (or/and both vertical) anchors active, then both horizontal (or/and both vertical) boundaries of the control should be placed on some specified distances from the correspondent horizontal (vertical) boundaries of the dialog. Therefore, when the dialog is resized, then such control is also resized accordingly to keep the specified distances.

When no one of horizontal (or vertical) anchors of a control are active, then no one of horizontal (or vertical) boundaries of the control are bounded to the correspondent horizontal (vertical) boundaries of the dialog. Coordinates of such controls are handles on the "proportional basis". For example, when the dialog width is increased onto Delta dialog base units, then the X coordinate of the control is also increased, but it is increased two times smaller. That is the X coordinate of the control is increased only onto Delta/2 dialog base units.

Cut, Copy and Paste, Undo and Redo

You can Cut or Copy a group of selected controls onto the Windows clipboard, and Paste controls from the clipboard back into a dialog. The Undo and Redo commands serve to delete or restore the last editing operations of your dialog.

Grid

When the menu (or the pop-up menu) entry Resource | Grid is activated, or when the File:GridButton.png button from the Layout toolbar is pressed, the following dialog appears:

File:GridSpecification.png The Dialog to Specify the Grid Properties

With a grid in place, arranging the controls inside a dialog is easier. Also it is possible to tell the [Window_and_Dialog_Editor.htm IDE Designer] by the Snap to Grid that it should place controls at the grid intersections to give a satisfactory result.

File:MyDialog withGrid.png Using a grid in the Dialog/Window/Form Editor

Test Mode

The [Window_and_Dialog_Editor.htm IDE Designer] has the Test Mode, so it is possible to see how the dialog with the created controls behaves. To illustrate the Test Mode we will assign some default values to the controls. The test mode is activated and deactivated from the Resource menu (or from the pop-up menu).

A File:MyDialog TestMode.png Test Mode for a Dialog

Tab Stops

When activating the menu (or the pop-up menu) entry Resource | Tabstops, it is possible to specify to which controls you can Tab to in the dialog. When this command is activated a small button with the or - appears on controls depending upon whether the control has a tab stop or not. By clicking the small buttons, it is possible to toggle the setting.

File:MyDialog TabStops.png Specifying Tab Stops for a Dialog

To exit the tab stop mode, just click in the dialog but outside of any controls.

Visit Order

When the tab stops have been specified for a dialog, then it is possible to specify the order in which controls will receive focus when tabbing.

A File:MyDialog VisitOrder.png Displaying the Visit Order.

To change the visit order, click a small rectangle displaying the visit order number for a control that has an incorrect sequence number and this will bring up another dialog to change this sequence:

A File:MyDialog ChangeVisitOrder.png Changing the Visit Order.

To stop the visit order mode, just click in the dialog outside any controls.

Speed Menu

When you are in the [Window_and_Dialog_Editor.htm IDE Designer] you can click the right mouse button to activate the Speed Menu. From this menu you can easily call any [Window_and_Dialog_Editor.htm IDE Designer] command:

The [Window_and_Dialog_Editor.htm IDE Designer] Speed Menu