OPTPARAM

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.