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.

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.