SelectionTree Control
This control enables a user to change the selection state of features listed in the Feature table. The control is associated with a string valued property that the user can set by a Browse dialog. You can associate the control with a property by entering the property's name in the Property column of the Control table.
The SelectionTree control automatically publishes the following Control Events on Windows XP or earlier operating systems. The SelectionTree control publishes these events when the selected item is changed from one node to another. If the selection tree has no nodes, the control publishes these events and erases the contents of controls that subscribe to the event. These ControlEvents are not required to be listed in the ControlEvent table.
| Control event | Description |
|---|---|
| SelectionAction | Publishes a string from the UIText table describing the highlighted item. |
| SelectionBrowse | Generates a Browse dialog box used to modify the path of the highlighted item. |
| SelectionDescription | Publishes a string from the Feature table describing the highlighted item. |
| SelectionNoItems | Deletes the descriptive text or disables the buttons of an obsolete item. |
| SelectionPath | Publishes the path for the highlighted item. |
| SelectionPathOn | Publishes whether or not there is a selection path associated with the currently selected feature. |
| SelectionSize | Publishes the size of the highlighted item. |
Beginning with the Windows Server 2003 systems, SelectionTree controls publish all of the events in the above table, and in addition, publish a DoAction ControlEvent or a SetProperty ControlEvent. Records must be added to the ControlEvent table to publish DoAction or SetProperty ControlEvents.
| Control event | Description |
|---|---|
| DoAction | Notifies the installer to execute a custom action. |
| SetProperty | Sets a property to a new value. |
Beginning with Windows Installer version 3.0, SelectionTree controls publish an event that runs custom actions listed in the ControlEvent table. The SelectionTree control publishes this event whenever the feature selection changes in the control or whenever a different selection state is chosen for the current feature. The custom actions run each time the event is published. The SelectionTree control sends information to the custom action by setting the values of the following properties. All these properties are all cleared when the SelectionTree control is closed.
Windows Installer 2.0: Not supported. The SelectionTree control does not publish the event and does not set the following properties.
| Property | Description |
|---|---|
| MsiSelectionTreeSelectedFeature | The selected feature's name in the Feature field of the Feature table. |
| MsiSelectionTreeSelectedAction | The selected feature's installation action state. The value may be INSTALLSTATE_ABSENT, INSTALLSTATE_LOCAL, INSTALLSTATE_SOURCE, or INSTALLSTATE_ADVERTISED. |
| MsiSelectonTreeChildrenCount | Number of direct child nodes. |
| MsiSelectionTreeInstallingChildrenCount | Number of direct child nodes that are INSTALLSTATE_LOCAL, INSTALLSTATE_SOURCE, or INSTALLSTATE_ADVERTISED. |
| MsiSelectionTreeSelectedCost | Cost of installing the selected feature in units of 512 bytes. |
| MsiSelectionTreeChildrenCost | Cost of installing all the children features in units of 512 bytes. |
| MsiSelectionTreeSelectedPath | Path where the selected feature is being installed. Defined only if the feature is being installed as INSTALLSTATE_LOCAL. |
Note
The contents of the Text field of the Control table is never displayed by the SelectionTree control. Instead this field specifies the style of text to be displayed by the control and contains a description of the control used by screen review utilities. To set the font and font style of a text string, prefix the string of displayed characters with {\style} or {&style}. Where style is an identifier listed in the TextStyle column of the TextStyle table. If neither of these are present, but the DefaultUIFont property is defined as a valid text style, that font is used. The information following this is read by screen review utilities as the description of the control. See Accessibility.
Control Attributes
You can use the following attributes with this control. To change the value of an attribute using an event, subscribe the control to a ControlEvent in the EventMapping table and list the attribute's identifier in the Attribute column. Enter the identifier of the ControlEvent in the Event column.
| Attribute identifier | Hexadecimal bit | Description |
|---|---|---|
| IndirectPropertyName | Name of an indirect property associated with the control. If the Indirect attribute bit is set, the control displays or changes the value of the property having this name. If the Indirect attribute bit is set, this name is also the value of the property listed in the Property column of the Control table. | |
| Position | Position of the control in the dialog box. Enter the control's width, height, and coordinates of the control's left corner into the Width, Height, X, and Y columns of the Control table. Use installer units for length and distance. |
|
| PropertyName | Name of the property associated with this control. If the Indirect attribute bit is not set, the control displays or changes the value of the property having this name. This attribute is specified in the Property column of the Control table. | |
| PropertyValue | Current value of the property displayed or changed by this control. If the Indirect attribute bit is not set, this is the value of PropertyName. If the Indirect attribute bit is set, this is the value of IndirectPropertyName. If the attribute changes, the control reflects the new value. | |
| Text | Displays text in screenreaders according to text entered into the Text column of the Control table. See Accessibility. | |
| Visible | 0x00000000 0x00000001 |
Hidden control. Visible control. Include this bit in the bit word of the Attributes column in the Control table to make the control visible or hidden upon its creation. You can also hide or show a control by using the ControlCondition table. |
| Enabled | 0x00000000 0x00000002 |
Control in a disabled state. Control in an enabled state. Include this bit in the bit word in the Attributes column of the Control to enable the control on creation. You can also enable or disable a control by using the ControlCondition table. |
| Sunken | 0x00000000 0x00000004 |
Displays the default visual style. Displays the control with a sunken, 3D, look. Include these bits in the bit word in the Attributes column of the Control table. |
| Indirect | 0x00000000 0x00000008 |
The control displays or changes the value of the property in the Property column of the Control table. The control displays or changes the value of the property that has the Identifier listed in the Property column of the Control table. Determines if the property associated with this control is referenced indirectly. |
| RTLRO | 0x00000000 0x00000020 |
Text in the control is displayed in left-to-right reading order. Text in the control is displayed in right-to-left reading order. |
| RightAligned | 0x00000000 0x00000040 |
Text in the control is aligned to the left. Text in the control is aligned to the right. |
| LeftScroll | 0x00000000 0x00000080 |
The scroll bar is located on the right side of the control. The scroll bar is located on the left side of the control. |
| BiDi | 0x000000E0 | Set this value for a combination of the RTLRO, RightAligned, and LeftScroll attributes. |
Remarks
This control can be created from the WC_TREEVIEW class by using the CreateWindowEx function. It has the WS_BORDER, TVS_HASLINES, TVS_HASBUTTONS, TVS_LINESATROOT, TVS_DISABLEDRAGDROP, TVS_SHOWSELALWAYS, WS_CHILD, WS_TABSTOP, and WS_GROUP styles.
The selection tree is only populated if the CostInitialize action and CostFinalize action have been called.
The following string in the UIText table is related to this control.
| Term | Description |
|---|---|
| AbsentPath |
The path displayed for an item in the absent state. |
The following six strings are used to display the number of children selected and the size associated with the highlighted item:
- SelChildCostPos
- SelChildCostNeg
- SelParentCostPosPos
- SelParentCostPosNeg
- SelParentCostNegPos
- SelParentCostNegNeg
The following strings are used to display the available selection options for an item in a popup menu:
- MenuAbsent
- MenuLocal
- MenuCD
- MenuNetwork
- MenuAllLocal
- MenuAllCD
- MenuAllNetwork
The following strings are used to explain the present selection in the SelectionDescription ControlEvent.
- SelAbsentAbsent
- SelAbsentLocal
- SelAbsentCD
- SelAbsentNetwork
- SelLocalAbsent
- SelLocalLocal
- SelLocalCD
- SelLocalNetwork
- SelCDAbsent
- SelNetworkAbsent
- SelCDLocal
- SelNetworkLocal
- SelCDCD
- SelNetworkNetwork
The following four localized strings are used in formatting the size of a file:
- Bytes
- KB
- MB
- GB