Settings dialogs can be displayed by the XCenter to further tune the instance data of a certain widget. An example of a settings dialog is the "Filter" dialog displayed by the standard "Window List" widget that comes with &xwp;.

Using settings dialogs requires a bit more setup. The most important thing to remember is that the XCenter does not invoke a settings dialog on an open XCenter widget, but on a setup string only.

This was done so that settings dialogs could be displayed for a widget even if that widget is not currently visible. With the current implementation, settings dialogs will only be invoked from the "Properties" menu item of an open widget, but this will change in the future so it has been isolated from the beginning.

Basically, to support settings dialogs, your widget class must do the following:

  1. In the widget class definition (XCENTERWIDGETCLASS), set the pShowSettingsDlg field to the function in your DLL which can display the settings dialog.

    This function must have the following prototype:

    typedef VOID EXPENTRY ShowSettingsDialog(PWIDGETSETTINGSDLGDATA pData);

  2. When the XCenter needs to invoke the settings dialog (e.g. because the "Properties" menu item was selected), it will call exactly this function, which should do a standard WinDlgBox and not return until the dialog has been dismissed ("OK" or "Cancel" were pressed).

    That function receives a pointer to a temporary WIDGETSETTINGSDLGDATA structure, which the XCenter has composed for the settings dialog. In there, the settings dialog can find out whether the widget is currently visible.

For details, please look at the "Window list" source code in src\widgets in the &xwp; sources.