Interaction Techniques

Technical Article

Abstract

The purpose of this article is to explain how to interact with Rich Application Presentation Designer in your development environment.

The Design Environment

When a Rich Application Presentation Designer file is created or opened, the designer will show its appearance in a design document. Here is the general view of Visual Studio when we are editing this file:

Rich Application Presentation Designer Global View

We can find:

Creating Widgets

The widget creation process depends on the created widget parent container. Basically, once the widget type to create is selected in the toolbox, you can clicks on the container to select the first corner of the component, and drags to select the second corner to define the size of the component. If the container doesn’t have a grid layout, it can’t be resized, and it’s created on the first click. You can abort the widget creation process at any time by a right click or with the escape key. We describe this process for each type of container.

Containers with Layout

This behavior is only applied when the parent container is a CATDlgDialog, a CATDlgFrame or a CATDlgTabPage.

  1. Select the desired widget in the toolbox.

    Rich Application Presentation Designer Toolbox

  2. Move the widget to one of its borders.

    The designer tries to place the created widget in the deepest container located on the mouse cursor. This container is surrounded with a black frame to show the user the container that will be used. Then, the row and column corresponding to the mouse position on the container is computed.

    If the mouse cursor is located on a row/column border, the designer automatically creates a new row/column at this position.

    If a widget is already located on the mouse position, the created widget is hatch in red to signal the user that the widget creation will be impossible at this position.

  3. Click down to confirm the first border.
    If the current mouse position is occupied by another widget, the process goes back to step 2
  4. Drag the mouse to the widget second border.

    The designer calculates the row and column closest to the cursor location on the container where the first point was placed. The widget occupies the position between the first selected point and the current calculated point. If a widget intersects the created widget, this widget is hatch in red to signal the user that the widget creation will be impossible at this position.

  5. Release the mouse click to confirm the widget size.
    If the current mouse position is occupied by another widget, the process goes back to step 4.

If the process succeeds, the new widget is integrated in the dialog box, and is selected.

Containers without Layout

This behavior is only applied when the parent container is either a CATDlgContainer or a CATDlgSplitter.

There is no size of a widget inserted in a container without layout. The process stops after 3 steps, on the first mouse click.

  1. Select the desired widget in the toolbox
  2. Move the widget to its location.
  3. Click down to confirm the position.

Tab Containers

A tab container is created with one tab page.

This tab page is a container with a grid layout and can be filled with other widgets. It can be selected and edited by clicking on the inner part of the tab container. This is useful in particular to change the tab page title or to delete it.

It also shows a grayed page that can be used to generate a new tab page. A simple click on this virtual page indicates the designer that a new page should be created. When a new page is created, it is automatically displayed as the active tab.

Once several tab pages are created, the user can select the displayed page by simply clicking the corresponding tab item. The page order can be modified simply by clicking the page to be moved, and dragging it to its new location. The command can be cancel with a mouse right click, and the moved tab will be placed to its original location.

Manipulate Existing Widgets

Moving Widgets

A widget can be dragged to define a new position, or change its container. When a widget is dragged, its size is preserved unless it’s dragged to a container without layout. The dragged widget is placed in the deepest container located under the mouse cursor.

For this operation, no row/column is automatically created, and if the moved widget is covering an existing one, it’s hatched in red, and the operation is impossible. If the user releases the mouse click when there is a widget intersection, the operation is cancelled, and the moved widget returns to its original location.

You can abort the widget creation process at any time by a right click.

CATDlgDialog and CATDlgTabPage cannot be dragged.

Resizing Widgets

When a widget is selected, a sizing handle appears. You can resize the widget by selecting and then dragging the sizing handle.

You can abort the widget creation process at any time by a right click. The widget returns to its original size.

CATDlgDialog and CATDlgTabPage cannot be resized.

Deleting Widgets

Any selected widget (except the dialog box) can be deleted either by pressing the "Del" key, or by using the widget contextual menu. Deleting a container also deletes its child widgets.

Copy/Paste

Any selected widget can be copied using the Ctrl+C key or the context menu item 'Copy'. The widget is then placed on the clipboard, and can be pasted on any Rich Application Presentation Designer document with the Ctrl+V key or with the context menu item 'Paste'. When a widget is pasted, the widget is not placed right away on the designed dialog box. You must still validate its position using the same interaction techniques that are used to create a new widget from the Visual Studio Toolbox. In particular, the paste command can be cancelled with the Esc key or a mouse right click. If a container is copied, the designer will also copy all its children.

Some containers can't be copied and placed inside a dialog box as they are (like the CATDlgDialog or CATDlgTabPage widgets). Those widgets are transformed into a CATDlgFrame before being pasted. However, their content is preserved in the operation.

Quick copy

You can perform a quick copy of a widget by moving it while maintaining the Ctrl key down. If the Ctrl key is still pressed when the mouse left button is release, the designer will copy the selected widget in the location that you specified.

Multi Selection

You can select several widget by keeping the Ctrl key down while clicking on widgets. If a widget is already selected, then a click on it will deselect it.

Multi-selection can be used to delete several widgets at the same time or to edit properties common to all selected widget. However, the move, resize and copy commands can't be used in a multi-selection context.

 

Editing Widget Properties

Once a widget is selected, its properties can be edited in the VS properties window. Some properties have a direct visual impact on the design view, like the widget title, or its direction if it has one. This visual feedback helps the user to author its dialog box, without using constantly the simulation application.

The properties window can be opened by using the widget contextual menu.

Icon Properties

Icons in the Rich Application Presentation Designer application are handled using the standard process: the icons are searched in the concatenation of the runtime view, in the resources\graphic\icons or in the resources\graphic\icons\normal directories. You can enter directly the name of your icon (without path and extension). The icon will be searched in every icon resource path of the current concatenation path. We also provide a specific tool to be able to find an icon easily, and to force the user to define an icon that exists in its current runtime view concatenation.

In the properties window, every icon property has a browse button that will launch an icon research dialog:

This opened the following dialog box:

This dialog box lists every available path in the current concatenation, and contains an additional item ‘All’ that will list any available icon in the current concatenation.

The icons can be filtered to look faster for a specific icon. This search feature uses a wildcard-like syntax:

Wildcards Meanings
xxx Look for any icon that contains xxx
xxx*yyy Look for any icon that contains xxx, then any character sequence, then yyy
xxx?yyy Look for any icon that contains xxx, then any character (but exactly one), then yyy
^xxx Look for any icon that begins with xxx
yyy$ Look for any icon that ends with yyy

The filter is case insensitive.

Anchoring Widgets

If a widget is placed in a container with a grid layout, its anchor can be accessed by using the anchor contextual menu:

The selected widget is then surrounded with an anchor editor:

Attached sides are marked with a dark line, and the attached aspect can be toggled with a left mouse click on the button right next to the widget border.

The editor also allows the edition of the constant size aspect of a widget. A green line indicates that the widget size can varies, an orange line that its size is fixed. This aspect can be toggle with a left mouse click on the line.

When a widget is selected (but not while editing the anchor), there is a direct visual feedback of the anchor state for that widget. Attached sides appear with a blue line on the corresponding borders. If a widget size is fixed on a direction, a red line is drawn on the corresponding direction.

You can also edit the widgets anchor in the properties window. Each anchor parameter is editable as a separate property. In particular, those properties can be edited with multiple widget selected. You can for instance select several widgets that must be attached to their left side, and set this property for all the selected widgets at the same time.

Controlling Layout

Although the widget creation process can modify the layout to include the created components on new rows/columns, it might be necessary to redefine the layout aspect. If a column has become useless after some constraint modifications, we must be able to destroy it. Besides, we must be able to define which rows/columns are resizable, and the one whose size is fixed.

If a container with layout is selected, we draw the layout form in the design window margin, and the user can interact with it using a context menu to define every aspects specified in the previous paragraph.

Controlling a row:

Controlling a row border:

The "Insert Line" command can be realized anytime.

The "Split Line" command automatically resizes the components contained in the line so that they occupy both rows after the split.

If a ‘Merge Line’ and ‘Delete Line’ commands result in a widget destruction, they are disabled. A row/column destruction is only possible if the row/column is entirely free. For the merge operation, there can’t be two different widgets on the same line, touching the row/column that will be merged.

Finally, the resizable rows/columns are highlighted in the margin, so that the user can see them. The resizable aspect can be toggled using the context menu, or directly right clicking on the margin line, that show whether the row/column is resizable. A line next to the dialog border indicates its resizable status: green if it’s resizable, orange otherwise.

Editing Callbacks

Widget callbacks are located in a special property tab in the Visual Studio properties window.

This tab displays the list of callbacks defined for the selected widget. The callback name can be specified using the 3 methods here below:

Simulating the Application

The designer shows a rendering of the dialog box that is close from its real look. However, some differences are left intentionally to help the designer to create its dialog box faster (some spaces between the widgets for instance). More over, we want to be able to see the behavior when the dialog box is resized. To test the designed application quickly and accurately, we created an application that will create the dialog box on the fly (without compilation), using the real C++ code of the Dialog framework.

To simulate a dialog box, use the context menu on the design surface:

Remark:

Sometimes, the simulator doesn't appear on top of Visual Studio. If the simulator window isn't visible after a few seconds, it means that it is most likely lying under the current Visual Studio window.

Accessing the Generated Code

The designer creates two code files that are generated from the designer file (.DSGen):

Each file is accessible from context menu on the design surface:

Once created, they are added to the C++ project, and can be opened directly from the Visual Studio solution explorer:

Those files show the code that will be generated by mkmk to implement the dialog box that was graphically designed. This generated code is grayed and read only. Those view also include some writable parts that have a white background, where the user can customize the generated code.

In the header, the user can specify:

And in the implementation file:

Compiling the Designed Dialog Box

The generation of the final C++ code implementing the dialog box is fully integrated in mkmk. Just launch mkmk on the module containing your dialog file (.DSGen file), the compiler will automatically translate it into C++ code, and then compile and link it to the other files located in this module.

Remark:

The designer will not update the Identity card and the Imakefile that defines the prerequisites of the module containing the dialog box. You have to edit them manually, to add the frameworks (in the Identity card) or modules (in the Imakefile) that contain the implementation of the widgets used in your Dialog box. The required frameworks and modules for each widget are described in the documentation, on top of each widget description.

Using the Dialog Box as a Command

It is extremely simple to use your Dialog Box as a simple, dialog-based, interactive command.

The only thing you have to do is to set to true the "IsCommand" property of your Dialog Box, like shown in the following figure.

This will trigger the generation of 3 overridden methods, inherited from CATCommand (through CATDlgDialog): Activate, Desactivate and Cancel. The call of CATCreateClass macro and a default constructor are also generated.

History

Version: 2 [Jun 2009] Document update by OJA
Version: 1 [Jul 2007] Document created