FeatureTree control is probably the most sophisticated control provided by SharpSetup. As promised, here is the article that describes how the control can be configured. In particular it discusses how to hide/show, enable/disable and collapse/expand feature nodes.
The FeatureTree control is configured mainly using the Feature XML tag in WiX source file. Top level features correspond to Feature tags which are children of Product tag. Feature tags can be nested in each other to create a tree. This tree will be reflected in FeatureTree control - each node in the control corresponds to single Feature tag. Additionally each node's appearance may be modified by attributes of the Feature tag. Here is the list of attributes that may be specified for each Feature tag:
- Id - each feature must have a unique identifier. This value is not displayed anywhere, it is used as feature handle.
- Title - title is the text used for each node in feature tree. Typically you will want to localize it so you will use something like !(loc.FEATURE.MAINFEATURE.TITLE) as value for this attribute.
- Description - this value is not displayed inside FeatureTree control but it is used in FeatureSelectionStep to display feature description on the right side of the dialog. Like for Title attribute you will want to make Description attribute localizable, for example !(loc.FEATURE.MAINFEATURE.DESCRIPTION).
- Display - this attribute can be specified in two forms: either in text form with 3 available values (expand, collapse, hidden) or numeric value. In msi file resulting from compilation of Package project numeric value is written without changes and text value is converted to numeric value in the following way:
- hidden is converted to 0. Either 0 or 'hidden' means that feature is not displayed to the user. Each SharpSetup generated installer has hidden Uninstaller feature that is hidden from user's eyes;
- expand is converted to an odd number. Either odd number or 'expand' means that the node will be expanded (ie. child nodes will be visible);
- collapse is converted to even number. Either even number or 'collapse' means that the node will be collapsed (ie. child nodes will not be visible).
- Level -this attribute controls whether feature will be installed or not. This value should be read in context of three other values: minimum installation level (by default 1), current installtion level (by default set to 100) and maximum installation level (by default 10000). There are 5 possibilities:
- Level is 0 - feature is hidden from feature tree control and is not installed;
- Level is less or equal minimum installation level (which means 1 with default settings) - feature will be installed and user is not able to change that;
- Level is above minimum installation level but less or equal to current installation level (which menas from 2 to 100 with default settings) - feature is installed by default but the user may turn it off;
- Level is above current installation level but less or equal to maximum installation level (which means from 101 to 10000 with default settings) - feature is not istalled by default but user may turn it on;
- Level is above maximum installation level (which means 10001 to 32535 with default settings) - feature is not installed and user cannot change it.
In addition to these attributes the feature may be controlled by Condition tag nested inside Feature tag. Let's have a look at a short example:
<Feature Id="TestFeature" Title="Test Title" Description="Test Description" Level="5">
<!-- component references, component group references -->
<Condition Level="105">TEST = "YES"</Condition>
Depending on the value of TEST property the feature will behave as if it had level of 5 (when TEST is not equal to YES - installed by default) or as if it had a value of 105 (when TEST is equal to YES - not installed by default). The value of the property may be set using Property tag. You may also use DirectorySearch or RegistrySearch tag to set value depending on user environment.
Previous in series: Controls overview
Next in series: Assembler project