Qt in Parameter Maps and Parameter Blocks

Qt dialogs are the preferred way of managing automatic parameter mapping between parameter blocks and their UIs.

To map a Qt dialog to a parameter block, use the P_AUTO_UI_QT flag in the parameter block descriptor. Individual parameters should not specify UI properties (through the p_ui flag) when using Qt dialogs; instead, the UI is entirely defined as part of the Qt widget - this includes behavior, naming, localization, and mapping the parameter values.

When specifying the P_AUTO_UI_QT flag on a parameter block descriptor, the usual (Win32) UI specification (dialog resource ID, etc.) are not provided; no UI-definition parameters are to be provided in the parameter block descriptor. When using the P_MULTIMAP flag, the number of parameter maps and their individual IDs are provided as usual, but the IDs are not followed by the usual (Win32) UI specifications. Instead, Qt parameter maps go through ClassDesc2::CreateQtWidget() to retrieve a new Qt widget and associated properties which, in the Win32 world, would have been provided in the parameter block descriptor.

Mapping Qt controls to parameters in the parameter block

Whereas Win32 controls are mapped to parameters using the p_ui tag, Qt controls are matched by object name (QObject::setObjectName()) with the parameter's internal (non-localized) name. For each parameter in the parameter block, a search is performed to find all child Qt objects with a matching name: qtDialog.findChildren<QObjet*>(param_def.int_name) Every QObject found will be managed by the parameter map if it is deemed compatible (see below). Multiple Qt controls may be mapped to a single parameter by giving them the same object name; for example, a parameter could be mapped to both a slider and a spinner control.

Compatible Parameter Types and Qt Control Types

• All integer and floating-point parameter types are supported via generic handling through QVariant:
  • QComboBox
    • The itemData (QComboBox::setItemData()) is the value to set in the parameter block when a selection is made.
  • QButtonGroup
    • The QButtonGroup groups a set of radio buttons that control an integer parameter value.
    • The ID of the button (QButtonGroup::setId()) is the value used in the parameter block.
  • All Others
    • Any QObject that defines a property "value" is supported.
    • Any QObject that does not define a property "value", but has property "text". The value will be reported as read-only through the "text" property.
• TYPE_BOOL
  • Any widget which has a property called "checked".
  • If the widget has a property called "checkable", then this property's value must be 'true'.
• TYPE_INODE
  • QPushButton
    • Will behave as a node picker. The p_classID and p_sclassID options may be used for filtering nodes. The text on the button is automatically set, by the system, to the node's name, if and only if the P_NO_AUTO_LABELS flag is absent from the parameter definition.
• TYPE_TEXMAP, TYPE_MTL
  • QPushButton
    • Will behave as a texture map or material picker. The text on the button is automatically set by the system to the texture map or material name, if and only if the P_NO_AUTO_LABELS flag is absent from the parameter definition.
• TYPE_TAB_*
  • Any of the compatible types mentioned above (float, int, bool, INode, TexMap, Material) can be used in table-type parameters. In this case, the widget name should have the pattern [param_name]_tab_[index], using a 1-based index. For example, to connect to the last element of a 7 member TAB param called "tex", name the widget "tex_tab_7".
• TYPE_POINT2/3/4, TYPE_MATRIX3
  • These parameters have corresponding custom widgets QmaxPoint2Spinner, QmaxPoint3Spinner, QmaxPoint4Spinner and QmaxMatrix3spinner, that are rendered with the correct number of sub-spinners.
• All other types are currently unsupported.