ConfigurationWidget::BuildConfiguration

Defined in: C4Configuration.h

Builds the configuration interface for the settings belonging to a configurable object.

Prototype

void BuildConfiguration(const Configurable *configurable);

Parameters

configurable A pointer to the configurable object.

Description

The BuildConfiguration function builds the table of widgets for the settings belonging to the configurable object specified by the configurable parameter. During this process, the Configurable::GetSettingCount and Configurable::GetSetting functions are called for the configurable object, and the appropriate widgets are created for each setting.

The BuildConfiguration function can be called multiple times for the same configuration widget with different values for the configurable parameter. In this case, settings with unique identifiers returned from later configurable objects cause new widgets to be added to the bottom of the table. However, if a setting having an identifier matching one of the existing entries of the table is returned, then the existing widgets are reused, and the separate settings are combined into a single interface. Settings using the same identifier must have the same type. If the values of the separate settings are the same, then that value is displayed in the combined setting, but if the values are different, then an indeterminate state is displayed until the user makes a change to the setting.

In the particular case that the BuildConfiguration function is called multiple times for configurable objects having the same dynamic type, the settings returned by later objects will always match the identifiers of the existing settings, and the values shown in the configuration widget will reflect the common values shared by all of the configurable objects.

In order to rebuild the contents of a configuration widget from scratch (without combining the new settings with the existing settings), the ConfigurationWidget::ReleaseConfiguration function must first be called to release the widgets for the existing settings. A subsequent call to the BuildConfiguration function will then build new widgets for the configurable object passed to it.