4.2. Dialog XML

A dialog is a window displayed inside the PyDADL application's workspace. Dialog XML files are located in the ui_xml directory, you can arrange you XML files in multiple sub directories.

The root element of a dialog XML file is the dialog tag. This tag can hold the following attributes :

The application's name. This attribute is mandatory.
The dialog's name. This attribute is mandatory.
The dialog's title.
The path to the dialog's icon file. The format can be BMP, GIF, JPEG, PNG or XPM.
This attribute holds an XML-RPC function's name that will be executed when retrieving the dialog's definition. If the return value is a dict with keys that correspond to widgets names, the setValues function will be called with the return value as argument. The syntax is function_name or function_name(arg1, arg2, ..., argN). The return value is accessible via the global variable DialogValues.
Width of the dialog. The default value is 640 pixels.
Height of the dialog. The default value is 480 pixels.
If this attribute is set to 1, the dialog is shown in modal mode. the dialog keeps the focus until it is closed.
This attribute controls which button will be displayed. It is a numeric value derived by adding up those values : 1=Ok, 2=Cancel, 4=Apply.

The sub tag widget is the base element of a dialog. Widgets are laid out in a grid. Container widgets can have child widgets. This tag can hold the following attributes :

The widget's type. Can be one of :
Widget's typeWidget's classWidget's description
buttonSimple widgetsPush button.
checkSimple widgetsCheck box.
dateSimple widgetsDate selector.
fileSimple widgetsFile or folder selector.
labelSimple widgetsLabel display.
lineSimple widgetsSingle line edit.
pixmapSimple widgetsImage display.
progressSimple widgetsProgress bar.
radioSimple widgetsRadio button.
ruleSimple widgetsSimple rule.
sliderSimple widgetsSlider widget.
spinSimple widgetsSpin box.
textSimple widgetsMulti line text edit.
timeSimple widgetsTime selector.
comboComplex widgetsCombo box.
listComplex widgetsList display.
tableComplex widgetsTable display.
treeComplex widgetsTree display.
gridContainer widgetsInvisible grid.
groupContainer widgetsGroup box.
scrollContainer widgetsScroll area.
splitContainer widgetsSplit area.
stackContainer widgetsWidgets stack
tabsContainer widgetsTabs display.
dummyother widgetsDummy widget.
customother widgetsCustom class widget.
spacerother widgetsBlank space.

Table 4.1. PyDADL widgets

The widget's name.
The widget's row and column position. Possible values are :
  • A number indicating the row/column.
  • A range in the form start-end or start+nbre_span that indicates a range of row/column to spread into.
  • A "=" character that means using the previous row/column.
  • A "+" character that means using the next row/column.
*any other attribute
If other attributes are specified, they will be passed directly to the corresponding widget class. See each widget documentation for a list of available attributes.

The sub tag page can only be declared inside a widget tag with type of stack or tabs. Pages hold widgets inside as dialog does. The attributes of page tag are :

Name of the page.
Label of the page. Used only by tabs widget.
Page's icon file. Used only by tabs widget.
Page's tooltip. Used only by tabs widget.
Page's What's this text. Used only by tabs widget.
If this attribute is set to 0, the page is disabled. Used only by tabs widget.

The sub tag style is used to specify a style sheet for the dialog. See Qt documentation for more details about style sheet syntaxes.

The sub tag connection is used to connect widget's signals to Python code that you write inside this tag. there are Qt signals and PyDADL signals. Let's assume you have a widget named line_edit_1 of type line, which correspond to a QLineEdit Qt class, to connect the Qt signal cursorPositionChanged ( int old, int new ) you could write :

<connection widget='line_edit_1' signal='cursorPositionChanged(int, int)'>

The two int arguments will be available via the Args list, the first int is Args[0] and the second is Args[1].

You could also write the connection tag like this :

<connection widget='line_edit_1' signal='cursorPositionChanged(old=int, new=int)'>

In this case, the two int variables will also be available via the variables named old and new.

To connect the PyDADL signal cellChanged(row_id, col_id, data) of a tree widget you could write :

<connection widget='tree_1' signal='cellChanged'>


<connection widget='tree_1' signal='cellChanged(row=, col=, data=)'>

In both cases the three signal's arguments will be available via the Args list. In the second case, the variables row, col and data will also be defined.

It is possible to connect more than one signal to the same Python code using widgetN and signalN attributes :

<connection widget='tree_1' signal='cellChanged' widget0='tree_2' signal0='cellChanged' widget1='line_1' signal1='changed'>

The sub tag callback is used to write code that will be executed when applying the dialog, either by clicking on "Ok" button or "Apply" button. Widgets values are accessible via a variable named Values which is a dict, the dict's keys are formed by widgets names. There are also global variables defined that correspond to the widgets names.

The sub tag init can be used to write Python code that will be executed on dialog loading.

The sub tag post_show is similar to init tag, the difference is that the code writing here will be executed after showing the dialog, it can be usefull for actions that must be done on visible widgets.

The sub tag cleanup can be used to write Python code that will be executed when closing the dialog.

The sub tag code can be used to declare Python functions or objects, those objects will be available as global objects in other code tags.

The sub tags thread and event can be used for threading. They are used like in Application XML.

In all Python code blocks there is a variable named d which is a reference to the dialog object. See Section 4.4, “Dialog/Wizard classes” for more details.

Since Python uses indentation for delimiting blocks, you must start all you code blocks from the beginning of the line.