Detailed Description

The Dialog widget shows to the user as a separate top-level window.

The Dialog widget supports features like opening and closing animations, rendered pixmap to make any movement as smooth as possible, themes, and other useful features.

The dialogs are opened in GUI using Popup Dialog Buttons. How to configure and create dialog form files is discussed in the Design Mode Manual.

How to Configure External Dialog Windows

The dialog is configured to only show inside the GUI application by default. Trying to drag the dialog outside the GUI, to place it on a separate screen, is not possible. To open the dialog as a separate application window, we can configure the preferParent property on the button to false.

The SVG file that styles the dialog often includes transparency to create shadow effects. This might look weird in the external application window as it doesn't enable transparency by default. We can turn this on by setting translucentBg in the dialog to true. This will make the window look exactly like it does when being internal.

Most themes also have a version of the SVG styling file without shadows. The path is identical to the default except for the shadow part, :/themes/< theme >/dialogs/dialogWindow.svg. Use this if you want to keep the draggable window borders and the default system header.

How to Create a Settings Dialog with Save and Cancel

A settings dialog will often allow the user to configure different settings and then decide whether to reset or save the changes. To achieve this, we will have to configure all input widgets, like spin boxes, line edits, and combo boxes to not immediately send their values to the control system when changed. In most input widgets, this is done by setting the property named updateOnSlotOnly to true. This setting makes the widget send new values to the control system only when its sendToCdp slot is triggered. The input widgets have a similar slot for resetting their value to be identical to the remote value, resetToCdp.

Instead of connecting the save and reset buttons to all input widgets in the settings dialog, we can place the widgets in a Container widget. The Container has slots similar to reset and save in the input widgets and will execute on all children when triggered.

How to Reuse Dialogs to Show Different Remote Values

Some applications might require multiple identical dialogs showing values from different remote sources. A good example of such is pipe diagram applications with pumps and valves. Clicking the various elements usually pops up a dialog showing further status/control details. When the dialogs are identical and more than just a few, it would be much simpler to create one dialog and have it show different sources when clicked, than to create hundreds of dialogs. This is where routing replacement comes in handy.

Routing replacement is done using simple string replacement. The dialog property replaceableRouting, must first be configured with a string that does not occur in any remote objects that are to be routed, for instance $(REPLACE). This string can now be used as a placeholder in the different cdp routing properties of our dialog items. When the dialog is opened, by for instance a button of type CDPBaseButtonPopDlg, the placeholder string will get replaced by a string configured in the button. In CDPBaseButtonPopDlg, this property is named routingReplacement.

To illustrate the above with a full example, we'll add two labels to a dialog to show the state and location of a valve. In the control application, the valve is a component having the two as signals. This would make our dialog.ui look something like the following (when wanting valve component name to be replaceable):

Next, we need to configure the buttons that are to open the dialog. The properties will be identical in each button instance, except for CDPBaseButtonPopDlg::routingReplacement, which represents the valve component name.

Clicking the button will bring up the dialog, replace routings and show the labels with their new routed values. They should now be showing the values of PipeApp.Valve1.state and PipeApp.Valve1.location.

Note: The property named useCache was added to make the dialog global and thus save memory.

Styling by SVG

Use the svgFile property to style the widget using a svg file. Styling by svg enables switching between different themes in runtime (as long as the files are placed at identical locations within theme directories).

Main element structure

In the svg structure for the CDPBaseDialog, all graphics are located in the cdpBackground element. The widget draws the background as a border pixmap based on the border margin rects. Thus, the title and the exit cross gets painted correctly when the widget is scaled. The shadow rects are used to place the content of the dialog correctly when we got shadows and the exit rect for knowing the position of the close box.

svg
└─── Layer1
      ├─── cdpTitleText               (text)
      ├─── cdpShadowTopLeft           (transparent rect/path)
      ├─── cdpShadowBottomRight       (transparent rect/path)
      ├─── cdpBorderMarginBottomRight (transparent rect/path)
      ├─── cdpBorderMarginTopLeft     (transparent rect/path)
      ├─── cdpExitRect                (transparent rect/path)
      └─── cdpBackground              (element group or rect/path)
            ├─── < Path >             (transparent rect/path)
            └─── < Group >            (graphics)

The following tree view shows the svg structure that can be used on the CDPBaseDialog.

Style element structure

The dialog supports the following structure for styles.

svg
├─── Layer1
│     └─── ...                  (see previous section)
└─── Styles
      ├─── cdpTitleTextStyleX   (text)
      └─── cdpBackgroundStyleX  (element group or rect/path)
            ├─── < Path >       (transparent rect/path)
            └─── < Group >      (background graphics)

Note: The X in the above list is just a placeholder for the style number that the element represents.