typedef struct _OPTPARAM {
WORD cbSize;
BYTE Flags;
BYTE Style;
LPTSTR pData;
DWORD IconID;
LONG lParam;
DWORD dwReserved[2];
} OPTPARAM, *POPTPARAM;
The OPTPARAM structure is used to describe each selectable entry in an option item's list of selections.
Members
cbSize
Size in bytes of this structure.
Flags
Bitmask in which the caller can return a bitwise OR of any of the following flags.
Flag | Description |
OPTPF_HIDE | This selection is hidden from the user. |
OPTPF_DISABLED | This selection is not available for a user to select. |
OPTPF_ICONID_AS_HICON | The CPSUI interprets the IconID member as a handle to an icon rather than as a resource ID. |
OPTPF_OVERLAY_WARNING_ICON | The CPSUI overlays its IDI_CPSUI_WARNING icon on the icon associated with this selection. |
OPTPF_OVERLAY_STOP_ICON | The CPSUI overlays its IDI_CPSUI_STOP icon on the icon associated with this selection. |
OPTPF_OVERLAY_NO_ICON | The CPSUI overlays its IDI_CPSUI_NO icon on the icon associated with this selection. |
OPTPF_USE_HDLGTEMPLATE | The lParam member is a handle to a DLGTEMPLATE structure supplied by the original caller. |
Style
Specifies the action to be performed on this item if it is selected. The pData and lParam fields depend on the value of Style. This member is valid only when the treeview option type is TVOT_PUSH BUTTON, and can be one of the following values.
Value | Description |
PUSH BUTTON_TYPE_DLGPROC | This push button causes the CPSUI to display a caller-specified dialog box. |
PUSH BUTTON_TYPE_CALLBACK | This push button requires that the caller process the option item. |
PUSH BUTTON_TYPE_HTCLRADJ | This push button causes the CPSUI to display a halftone color adjustment dialog box. |
PUSH BUTTON_TYPE_HTSETUP | This push button causes the CPSUI to display a device halftone setup dialog box. |
pData
Pointer to data whose interpretation depends on the Type field of the associated OPTTYPE structure. For each OPTPARAM in the array to which the pOptParam member of OPTYPE points, pData has the following value:
Type | Description |
TVOT_2STATES | pOptParam[0]->pData points to the text string that describes State 1. pOptParam[1]->pData points to the string that describes State 2. |
TVOT_3STATES | pOptParam[0]->pData points to the text string that describes State 1. pOptParam[1]->pData points to the text string that describes State 2. pOptParam[2]->pData points to the text string that describes State 3. |
TVOT_UDARROW | pOptParam[0]->pData points to the text string for the selection postfix and icons. pOptParam[1]->pData points to the help line text above the control. |
TVOT_TRACKBAR TVOT_SCROLLBAR |
pOptParam[0]->pData points to the text string for the selection postfix and icons. pOptParam[1]->pData points to the low range of the trackbar/scrollbar control. This value must be in the range of a 16-bit signed integer. |
TVOT_LISTBOX TVOT_COMBOBOX |
pOptParam[0]->pData points to the text string for the first OPTPARAM. pOptParam[1]->pData points to the text string for the second OPTPARAM. … pOptParam[n-1]->pData points to the text string for the nth OPTPARAM. |
TVOT_EDITBOX | pOptParam[0]->pData points to the text string for the selection postfix and icons. pOptParam[1]->pData points to the help line text above the control. |
TVOT_PUSH BUTTON | Depends on the value of Style. See the Comments section for details. |
TVOT_CHKBOX | pOptParam[0]->pData points to the text string for the OPTPARAM. |
IconID
Identifies the icon to be associated with this selectable option item entry. This field can be a standard IDI_CPSUI_Xxx icon ID, a caller's icon resource ID, or, if the OPTPF_ICONID_AS_HICON bit is set in Flags, a handle to a caller-defined icon. If IconID is zero, the selectable entry does not have an icon associated with it.
lParam
The value of this field depends on the TVOT_Xxx type specified in the Type field of the OPTTYPE structure of which this OPTPARAM structure is a member, and is described in the following table.
Type | Description |
TVOT_2STATES | The CPSUI ignores lParam. |
TVOT_3STATES | The CPSUI ignores lParam. |
TVOT_UDARROW | Specifies the high range of the up-down control. This value must be in the range of a 16-bit signed integer. |
TVOT_TRACKBAR TVOT_SCROLLBAR |
Specifies the high range of the trackbar/scrollbar control. This value must be in the range of a 16-bit signed integer. |
TVOT_LISTBOX TVOT_COMBOBOX |
The CPSUI ignored lParam. |
TVOT_EDITBOX | The CPSUI ignored lParam. |
TVOT_PUSH BUTTON | Depends on the value of Style. See the Comments section for details. |
TVOT_CHKBOX | The CPSUI ignored lParam. |
dwReserved[2]
Reserved; these fields must be set to zero.
Comments
The OPTPARAM structure is used to describe each selectable entry in an option item's list of selections.
When the caller has set the OPTPF_HIDE flag, the CPSUI does not display this selection in the selection list on the property sheet. If all of the selectable items associated with an option item are marked as hidden, then the CPSUI automatically hides the entire option item.
The OPTPF_HIDE flag is valid only when the treeview option type is one of TVOT_3STATES, TVOT_LISTBOX, or TVOT_COMBOBOX. If the Type field of an option item's OPTTYPE structure is TVOT_3STATES and only two of the three states are specified as hidden, the CPSUI does not add the page and returns an error condition.
When the caller has set the OPTPF_DISABLED flag, the CPSUI displays this selection, but does not allow a user to select it. This flag is valid only when the treeview option type is one of TVOT_2STATES, TVOT_3STATES, TVOT_LISTBOX, or TVOT_COMBOBOX.
When the Type field of the associated OPTTYPE structure is TVOT_PUSH BUTTON, the pData and lParam fields depend on the value of Style, and are interpreted as shown in the following table.
Style | pData and lParam |
PUSH BUTTON_ TYPE_DLGPROC |
The pData field is a pointer to the caller's dialog box function; the lParam field specifies the caller's DIALOG resource template ID or DLGTEMPLATE handle, depending on the OPTPF_USE_HDLGTEMPLATE flag. |
PUSH BUTTON_ TYPE_CALLBACK |
The pData field is a pointer to a callback of type _CPSUICALLBACK; the lParam field is not used. |
PUSH BUTTON_ TYPE_HTCLRADJ |
The pData field is a pointer to a COLORADJUSTMENT structure; the lParam field is not used. |
PUSH BUTTON_ TYPE_HTSETUP |
The pData field is a pointer to a DEVHTADJDATA structure; the lParam field is not used. |
The pData field must be supplied when Type is TVOT_CHKBOX and Style is one of CHKBOXS_FALSE_PDATA, CHKBOXS_NO_PDATA, CHKBOXS_OFF_PDATA, or CHKBOXS_NONE_PDATA.
If the treeview option type is not TVOT_PUSH BUTTON, the pData field is either a pointer to a null-terminated string that describes the selectable option item entry, or an integer value that specifies a string resource identifier. If pData specifies a resource identifier, its high-order word must be zero and its low-order word must contain the identifier.
When using resource IDs, the caller should use the standard IDS_CPSUI_Xxx values as often as possible for user interface consistency.