ICommandButton Interface Reference

The main interface (command button) More...

Public Member Functions
HRESULT	About (void)
	Displays the control's credits
HRESULT	Click (void)
	Clicks the button by code
HRESULT	GetControlState ([out, retval] ControlStateConstants *pControlState)
	Retrieves a bit field describing the control's state
HRESULT	GetIdealSize ([in, out, defaultvalue(0)] OLE_XSIZE_PIXELS idealWidth,[in, out, defaultvalue(0)] OLE_YSIZE_PIXELS idealHeight)
	Retrieves the control's optimal size
HRESULT	LoadSettingsFromFile ([in] BSTR file,[out, retval] VARIANT_BOOL *pSucceeded)
	Loads the control's settings from the specified file
HRESULT	Refresh (void)
	Advises the control to redraw itself
HRESULT	SaveSettingsToFile ([in] BSTR file,[out, retval] VARIANT_BOOL *pSucceeded)
	Saves the control's settings to the specified file
Properties
AppearanceConstants	Appearance `[get, set]`
	Controls the style of the control's outer border
OLE_COLOR	BackColor `[get, set]`
	Specifies the control's background color
BorderStyleConstants	BorderStyle `[get, set]`
	Controls the style of the control's inner border
ButtonTypeConstants	ButtonType `[get, set]`
	Specifies the button's sub-type
BSTR	CommandLinkNote `[get, set]`
	Specifies the additional text displayed in a command link button
ContentTypeConstants	ContentType `[get, set]`
	Controls the type of the control's caption
DisabledEventsConstants	DisabledEvents `[get, set]`
	Controls which events are fired
VARIANT_BOOL	DontRedraw `[get, set]`
	Controls redrawing of the control
OLE_YSIZE_PIXELS	DropDownArrowHeight `[get, set]`
	Specifies the height of the control's drop-down arrow
OLE_XSIZE_PIXELS	DropDownArrowWidth `[get, set]`
	Specifies the width of the control's drop-down arrow
SHORT	DropDownGlyph `[get, set]`
	Controls the appearance of the control's drop-down arrow
VARIANT_BOOL	DropDownOnRight `[get, set]`
	Controls the location of the control's drop-down arrow
VARIANT_BOOL	DropDownPushed `[get, set]`
	Specifies whether the split button's drop-down part is drawn like being pushed
DropDownStyleConstants	DropDownStyle `[get, set]`
	Controls the appearance of the control's drop-down arrow
VARIANT_BOOL	Enabled `[get, set]`
	Controls whether the control accepts user input
IFontDisp	Font `[get, set]`
	Specifies the control's font
OLE_COLOR	ForeColor `[get, set]`
	Specifies the control's text color
HAlignmentConstants	HAlignment `[get, set]`
	Controls the horizontal alignment of the control's caption
OLE_HANDLE	hDropDownImageList `[get, set]`
	Specifies the control's associated imagelist containing the drop-down arrows
OLE_HANDLE	hImageList `[get, set]`
	Specifies the control's associated imagelist
LONG	HoverTime `[get, set]`
	Controls when the `MouseHover` event is fired
OLE_HANDLE	hWnd `[get]`
	Retrieves the control's window handle
IconAlignmentConstants	IconAlignment `[get, set]`
	Controls the location of the control's icon
OLE_YSIZE_PIXELS	IconMarginBottom `[get, set]`
	Controls the location of the control's icon
OLE_XSIZE_PIXELS	IconMarginLeft `[get, set]`
	Controls the location of the control's icon
OLE_XSIZE_PIXELS	IconMarginRight `[get, set]`
	Controls the location of the control's icon
OLE_YSIZE_PIXELS	IconMarginTop `[get, set]`
	Controls the location of the control's icon
OLE_HANDLE	Image `[get, set]`
	Specifies the bitmap or icon displayed as caption
VARIANT_BOOL	KeepDropDownArrowAspectRatio `[get, set]`
	Controls the appearance of the control's drop-down arrow
IPictureDisp	MouseIcon `[get, set]`
	Controls the control's mouse cursor
MousePointerConstants	MousePointer `[get, set]`
	Controls the control's mouse cursor
VARIANT_BOOL	MultiLine `[get, set]`
	Specifies whether the control displays text in multiple lines
VARIANT_BOOL	ProcessContextMenuKeys `[get, set]`
	Specifies whether the `ContextMenu` event can be invoked using the keyboard
VARIANT_BOOL	Pushed `[get, set]`
	Specifies whether the control is drawn like being pushed
VARIANT_BOOL	RegisterForOLEDragDrop `[get, set]`
	Controls the control's behavior in drag'n'drop operations
RightToLeftConstants	RightToLeft `[get, set]`
	Controls the control's right-to-left features
VARIANT_BOOL	ShowRightsElevationIcon `[get, set]`
	Specifies whether the control displays the Vista LUA icon
VARIANT_BOOL	ShowSplitLine `[get, set]`
	Controls the appearance of a drop-down button
StyleConstants	Style `[get, set]`
	Controls the control's appearance
VARIANT_BOOL	SupportOLEDragImages `[get, set]`
	Controls the control's behavior in drag'n'drop operations
BSTR	Text `[get, set]`
	Specifies the control's caption
OLE_YSIZE_PIXELS	TextMarginBottom `[get, set]`
	Controls the location of the control's caption
OLE_XSIZE_PIXELS	TextMarginLeft `[get, set]`
	Controls the location of the control's caption
OLE_XSIZE_PIXELS	TextMarginRight `[get, set]`
	Controls the location of the control's caption
OLE_YSIZE_PIXELS	TextMarginTop `[get, set]`
	Controls the location of the control's caption
VARIANT_BOOL	UseSystemFont `[get, set]`
	Specifies whether the control uses the system font
VAlignmentConstants	VAlignment `[get, set]`
	Controls the vertical alignment of the control's caption
BSTR	Version `[get]`
	Retrieves the control's version

Detailed Description

The main interface (command button)

This is the command button control's main interface. It wraps the control window.

See also:: _ICommandButtonEvents

Member Function Documentation

HRESULT About ( void )

Displays the control's credits

Displays some information about this control and its author.

HRESULT Click ( void )

Clicks the button by code

See also:: _ICommandButtonEvents::Click

HRESULT GetControlState ( [out, retval] ControlStateConstants * pControlState )

Retrieves a bit field describing the control's state

Returns:: A bit field of constants defined by the ControlStateConstants enumeration, that describe the control's state.

See also:: Pushed, ControlStateConstants

HRESULT GetIdealSize	(	[in, out, defaultvalue(0)] OLE_XSIZE_PIXELS *	idealWidth,
		[in, out, defaultvalue(0)] OLE_YSIZE_PIXELS *	idealHeight
	)

Retrieves the control's optimal size

Calculates the rectangle that best fits the control's text and image, if an imagelist is present.

Parameters:

`[out]`	idealWidth	The control's optimal width in pixels.
`[out]`	idealHeight	The control's optimal height in pixels.

Remarks:: Requires comctl32.dll version 6.0 or higher.

See also:: Text, hImageList, TextMarginBottom, TextMarginLeft, TextMarginRight, TextMarginTop

HRESULT LoadSettingsFromFile	(	[in] BSTR	file,
		[out, retval] VARIANT_BOOL *	pSucceeded
	)

Loads the control's settings from the specified file

Parameters:

[in] file The file to read from.

Returns:: True if the settings could be loaded; otherwise False.

See also:: SaveSettingsToFile

HRESULT SaveSettingsToFile	(	[in] BSTR	file,
		[out, retval] VARIANT_BOOL *	pSucceeded
	)

Saves the control's settings to the specified file

Parameters:

[in] file The file to write to.

Returns:: True if the settings could be saved; otherwise False.

See also:: LoadSettingsFromFile

Property Documentation

AppearanceConstants Appearance [get, set]

Controls the style of the control's outer border

Retrieves or sets the kind of border that is drawn around the control. Any of the values defined by the AppearanceConstants enumeration is valid.

See also:: BorderStyle, Style, ButtonType, AppearanceConstants

OLE_COLOR BackColor [get, set]

Specifies the control's background color

Retrieves or sets the control's background color.

Remarks:: This property affects owner-drawn buttons only.

See also:: ForeColor, Style

BorderStyleConstants BorderStyle [get, set]

Controls the style of the control's inner border

Retrieves or sets the kind of inner border that is drawn around the control. Any of the values defined by the BorderStyleConstants enumeration is valid.

See also:: Appearance, Style, ButtonType, BorderStyleConstants

ButtonTypeConstants ButtonType [get, set]

Specifies the button's sub-type

Retrieves or sets the control's command button sub-type. Any of the values defined by the ButtonTypeConstants enumeration is valid.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: Appearance, BorderStyle, Style, ButtonTypeConstants

BSTR CommandLinkNote [get, set]

Specifies the additional text displayed in a command link button

Retrieves or sets the text that is displayed below the button's caption if the ButtonType property is set to btCommandLink.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: ButtonType, Text

ContentTypeConstants ContentType [get, set]

Controls the type of the control's caption

Retrieves or sets what the control's caption consists of. Any of the values defined by the ContentTypeConstants enumeration is valid.

See also:: Image, Text, ContentTypeConstants

DisabledEventsConstants DisabledEvents [get, set]

Controls which events are fired

Retrieves or sets the events that won't be fired. Disabling events increases performance. Any combination of the values defined by the DisabledEventsConstants enumeration is valid.

See also:: DisabledEventsConstants

VARIANT_BOOL DontRedraw [get, set]

Controls redrawing of the control

Enables or disables automatic redrawing of the control. Disabling redraw while doing large changes on the control may increase performance. If set to False, the control will redraw itself automatically; otherwise not.

OLE_YSIZE_PIXELS DropDownArrowHeight [get, set]

Specifies the height of the control's drop-down arrow

Retrieves or sets the height (in pixels) of the drop-down part of a split button. If set to 0, the default height is used.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: DropDownArrowWidth, ButtonType, KeepDropDownArrowAspectRatio, _ICommandButtonEvents::CustomDropDownAreaSize

OLE_XSIZE_PIXELS DropDownArrowWidth [get, set]

Specifies the width of the control's drop-down arrow

Retrieves or sets the width (in pixels) of the drop-down part of a split button.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: DropDownArrowHeight, ButtonType, KeepDropDownArrowAspectRatio, _ICommandButtonEvents::CustomDropDownAreaSize

SHORT DropDownGlyph [get, set]

Controls the appearance of the control's drop-down arrow

Retrieves or sets the code of the character, that is displayed as drop-down arrow in a split button, if the DropDownStyle property is set to ddsGlyph.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: ButtonType, DropDownStyle, hDropDownImageList

VARIANT_BOOL DropDownOnRight [get, set]

Controls the location of the control's drop-down arrow

Retrieves or sets whether the drop-down part of a split button is drawn to the right of its caption. If set to True, the separator is displayed to the right; otherwise to the left of the caption.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: ButtonType

VARIANT_BOOL DropDownPushed [get, set]

Specifies whether the split button's drop-down part is drawn like being pushed

Retrieves or sets whether the drop-down part of a split button is drawn like being pushed. If set to True, it is drawn like being pushed; otherwise not.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: ButtonType, Pushed

DropDownStyleConstants DropDownStyle [get, set]

Controls the appearance of the control's drop-down arrow

Retrieves or sets which type of drop-down arrow to use in a split button. Any of the values defined by the DropDownStyleConstants enumeration is valid.

Remarks:: Requires comctl32.dll version 6.10 or higher.

See also:: ButtonType, DropDownGlyph, hDropDownImageList, DropDownStyleConstants

VARIANT_BOOL Enabled [get, set]

Controls whether the control accepts user input

Enables or disables the control for user input. If set to True, it reacts to user input; otherwise not.

IFontDisp Font [get, set]

Specifies the control's font

Retrieves or sets the control's font. It's used to draw the caption.

See also:: UseSystemFont, Text, ForeColor

OLE_COLOR ForeColor [get, set]

Specifies the control's text color

Retrieves or sets the control's text color.

Remarks:: This property affects owner-drawn buttons only.

See also:: BackColor, Text, Font

HAlignmentConstants HAlignment [get, set]

Controls the horizontal alignment of the control's caption

Retrieves or sets the horizontal alignment of the control's caption. Any of the values defined by the HAlignmentConstants enumeration is valid.

See also:: Text, VAlignment, IconAlignment, HAlignmentConstants

OLE_HANDLE hDropDownImageList [get, set]

Specifies the control's associated imagelist containing the drop-down arrows

Retrieves or sets the handle to the imagelist containing the icons, that are displayed as drop-down arrow in a split button, if the DropDownStyle property is set to ddsImage. If set to 0, no icon is drawn.
The icon's index in the imagelist specifies the control state it is used for:

0 - Used if the button is in no special state.
1 - Used if the button is in 'hot' state, i. e. it's below the mouse cursor.
2 - Used if the button is pressed.
3 - Used if the button is disabled.
4 - Used if the button is the dialog's default button.
5 - Used on Tablet PCs (I don't know when).

If the imagelist contains only one icon, it is used for all control states. If it contains more than one, but less than five (six on Tablet PCs), no icon will be drawn if the control is in a state that no icon is specified for.

Remarks:: Requires comctl32.dll version 6.10 or higher.
The previous imagelist does NOT get auto-destroyed.

See also:: hImageList, ButtonType, DropDownStyle, DropDownGlyph

OLE_HANDLE hImageList [get, set]

Specifies the control's associated imagelist

Retrieves or sets the handle to the imagelist containing the control's icons. If set to 0, no icon is drawn.
The icon's index in the imagelist specifies the control state it is used for:

0 - Used if the button is in no special state.
1 - Used if the button is in 'hot' state, i. e. it's below the mouse cursor.
2 - Used if the button is pressed.
3 - Used if the button is disabled.
4 - Used if the button is the dialog's default button.
5 - Used on Tablet PCs (I don't know when).

If the imagelist contains only one icon, it is used for all control states. If it contains more than one, but less than five (six on Tablet PCs), no icon will be drawn if the control is in a state that no icon is specified for.

Remarks:: Requires comctl32.dll version 6.0 or higher.
The previous imagelist does NOT get auto-destroyed.

See also:: hDropDownImageList, Image, Text, IconAlignment, ShowRightsElevationIcon, GetIdealSize

LONG HoverTime [get, set]

Controls when the MouseHover event is fired

Retrieves or sets the number of milliseconds the mouse cursor must be located over the control's client area before the MouseHover event is fired. If set to -1, the system hover time is used.

See also:: _ICommandButtonEvents::MouseHover

OLE_HANDLE hWnd [get]

Retrieves the control's window handle

Retrieves the control's window handle.

Remarks:: This property is read-only.

See also:: _ICommandButtonEvents::RecreatedControlWindow, _ICommandButtonEvents::DestroyedControlWindow

IconAlignmentConstants IconAlignment [get, set]