Help Center›AfxNova›Windows

CButton Class

Members (45)

CheckChanges the button's state to checked.ClickSimulates the user clicking a button.DeleteBitmapDeletes a bitmap associated with a button.DeleteIconDeletes an icon associated with a button.DeleteImageDeletes an image (icon or bitmap) associated with a button.DisableDisables the button.EnableEnables the button.GetBitmapRetrieves a handle to the bitmap associated with the button.GetCheckGets the check state of a radio button or check box.GetIconRetrieves a handle to the icon associated with the button.GetIdealSizeGets the size of the button that best fits its text and image, if an image list is present.GetImageRetrieves a handle to the image (icon or bitmap) associated with the button.GetImageListGets the BUTTON_IMAGELIST structure that describes the image list assigned to a button control.GetNoteGets the text of the note associated with the Command Link button.GetNoteLengthGets the length of the note text that may be displayed in the description for a command link.GetSplitGlyphSizeGets the size of the glyph in the image list.GetSplitImageListGets the handle of the split button image list.GetSplitInfoGets information for a specified split button control.GetSplitStyleGets the style of the split button.GetStateRetrieves the state of a button or check box.GetStyleRetrieves the style of the button.GetTextRetrieves the text in a button control.GetTextLengthRetrieves the length of the text in a button control.GetTextMarginRetrieves the margins used to draw text in a button control.GraySets the button state to grayed, indicating an indeterminate state.IndeterminateSets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.RemoveDarkModeRemove the dark mode of the button.SetBitmapAssociates a new bitmap with a button. The return value is a handle to the image previously associated with the button, if any; otherwise, it is NULL.SetCheckSets the check state of a radio button or check box.SetDarkModeSets the dark mode of the button.SetDontClickSets a flag on a radio button that controls the generation of BN_CLICKED messages when the button receives focus.SetDropDownStateSets the drop down state for a specified button with style of BS_SPLITBUTTON.SetElevationRequiredStateSets the elevation required state for a specified button or command link to display an elevated icon.SetIconAssociates a new icon with the button.SetImageAssociates a new image (icon or bitmap) with the button.SetImageListAssigns an image list to a button control.SetNoteSets the text of the note associated with a specified Command Link button.SetSplitGlyphSizeSets the split size (glyph area) of a split button (BCSIF_SIZE).SetSplitInfoSets information for a specified split button control.SetSplitStyleSets the split style of a split button.SetStateSets the highlight state of a button.SetStyleSets the style of a button.SetTextSets the text of a button.SetTextMarginSets the margins for drawing text in a button control.UncheckUnchecks the button.

Documentation

CButton Class

Wrapper static class on top of all the Windows Button messages.

A button control is a small, rectangular child window that can be clicked on and off. Buttons can be used alone or in groups and can either be labeled or appear without text. A button typically changes appearance when the user clicks it.

Typical buttons are the check box, radio button, and pushbutton. A CButton object can become any of these, based on the button style specified at its initialization by the AddControl method of the CWindowclass.

See: About Buttons

Include file: CButton.inc.

Name	Description
Check	Changes the button's state to checked.
Click	Simulates the user clicking a button.
DeleteBitmap	Deletes a bitmap associated with a button.
DeleteIcon	Deletes an icon associated with a button.
DeleteImage	Deletes an image (icon or bitmap) associated with a button.
Disable	Disables the button.
Enable	Enables the button.
GetCheck	Gets the check state of a radio button or check box.
GetIdealSize	Gets the size of the button that best fits its text and image, if an image list is present.
GetBitmap	Retrieves a handle to the bitmap associated with the button.
GetIcon	Retrieves a handle to the icon associated with the button.
GetImage	Retrieves a handle to the image (icon or bitmap) associated with the button.
GetImageList	Gets the BUTTON_IMAGELIST structure that describes the image list assigned to a button control.
GetNote	Gets the text of the note associated with the Command Link button.
GetNoteLength	Gets the length of the note text that may be displayed in the description for a command link.
GetSplitImageList	Gets the handle of the split button image list.
GetSplitInfo	Gets information for a specified split button control.
GetSplitGlyphSize	Gets the size of the glyph in the image list.
GetSplitStyle	Gets the style of the split button.
GetState	Retrieves the state of a button or check box.
GetStyle	Retrieves the style of the button.
GetText	Retrieves the text in a button control.
GetTextLength	Retrieves the length of the text in a button control.
GetTextMargin	Retrieves the margins used to draw text in a button control.
Gray	Sets the button state to grayed, indicating an indeterminate state.
Indeterminate	Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.
RemoveDarkMode	Remove the dark mode of the button.
SetCheck	Sets the check state of a radio button or check box.
SetDarkMode	Sets the dark mode of the button.
SetDontClick	Sets a flag on a radio button that controls the generation of BN_CLICKED messages when the button receives focus.
SetDropDownState	Sets the drop down state for a specified button with style of BS_SPLITBUTTON.
SetElevationRequiredState	Sets the elevation required state for a specified button or command link to display an elevated icon.
SetIcon	Associates a new icon with the button.
SetImage	Associates a new image (icon or bitmap) with the button.
SetImageList	Assigns an image list to a button control.
SetNote	Sets the text of the note associated with a specified Command Link button.
SetSplitGlyphSize	Sets the split size (glyph area) of a split button (BCSIF_SIZE).
SetSplitInfo	Sets information for a specified split button control.
SetSplitStyle	Sets the split style of a split button.
SetState	Sets the highlight state of a button.
SetStyle	Sets the style of a button.
SetText	Sets the text of a button.
SetTextMargin	Sets the margins for drawing text in a button control.
Uncheck	Unchecks the button.

Check

Changes the button's state to checked.

SUB CButton.Check (BYVAL hButton AS HWND)

Usage example

CButton.Check(hButton)

Click

Simulates the user clicking a button. This message causes the button to receive the WM_LBUTTONDOWN and WM_LBUTTONUP messages, and the button's parent window to receive a BN_CLICKED notification code.

SUb Click (BYVAL hButton AS HWND)

Remarks

If the button is in a dialog box and the dialog box is not active, the BM_CLICK message might fail. To ensure success in this situation, call the SetActiveWindow function to activate the dialog box before sending the BM_CLICK message to the button.

Usage example

CButton.Click(hButton)

DeleteBitmap

Deletes a bitmap associated with a button. Returns TRUE or FALSE.

FUNCTION DeleteBitmap (BYVAL hButton AS HWND) AS BOOLEAN

Usage example

CButton.DeleteBitmap(hButton)

DeleteIcon

Deletes an icon associated with a button. Returns TRUE or FALSE.

FUNCTION DeleteIcon (BYVAL hButton AS HWND) AS BOOLEAN

Usage example

CButton.DeleteIcon(hButton)

DeleteImage

Deletes an image (icon or bitmap) associated with a button. Returns TRUE or FALSE.

FUNCTION DeleteImage (BYVAL hButton AS HWND, BYVAL ImageType AS DWORD) AS BOOLEAN

Parameter	Description
hButton	The handle of the button control.
ImageType	The type of image to delete. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	A bitmap.
IMAGE_ICON	An icon.

Usage examples

CButton.Deleteimage(hButton, IMAGE_BITMAP)
CButton.Deleteimage(hButton, IMAGE_ICON)

Disable

Disables the button. Returns FALSE if the button was previously disabled; otherwise TRUE.

FUNCTION Disable (BYVAL hButton AS HWND) AS BOOLEAN

Usage example

CButton.Disable(hButton)

Enable

Enables the button. Returns FALSE if the button was previously enabled; otherwise TRUE.

FUNCTION Enable (BYVAL hButton AS HWND) AS BOOLEAN

Usage example

CButton.Enable(hButton)

GetCheck

Gets the check state of a radio button or check box.

FUNCTION GetCheck (BYVAL hButton AS HWND) AS LRESULT

Return value

The return value from a button created with the BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON, or BS_3STATE style can be one of the following.

Return code	Description
BST_CHECKED	Button is checked.
BST_INDETERMINATE	Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).
BST_UNCHECKED	Button is cleared.

Usage example

DIM bst AS LRESULT = CButton.GetCheck(hButton)

GetIdealSize

Gets the size of the button that best fits its text and image, if an image list is present.

FUNCTION GetIdealSize (BYVAL hButton AS HWND, BYVAL pSize AS SIZE PTR) AS BOOLEAN
FUNCTION GetIdealSize (BYVAL hButton AS HWND, BYREF sz AS SIZE) AS BOOLEAN
FUNCTION GetIdealSize (BYVAL hButton AS HWND) AS SIZE

Parameter	Description
tsize	A pointer to a SIZE structure that receives the desired size of the button, including text and image list, if present. The calling application is responsible for allocating this structure. Set the cx and cy members to zero to have the ideal height and width returned in the SIZE structure. To specify a button width, set the cx member to the desired button width. The system will calculate the ideal height for this width and return it in the cy member.

Parameter

Description

tsize

A pointer to a SIZE structure that receives the desired size of the button, including text and image list, if present. The calling application is responsible for allocating this structure. Set the cx and cy members to zero to have the ideal height and width returned in the SIZE structure. To specify a button width, set the cx member to the desired button width. The system will calculate the ideal height for this width and return it in the cy member.

Return value

If the message succeeds, it returns TRUE. Otherwise it returns FALSE.

Remarks

If no special button width is desired, then you must set both members of SIZE to zero to calculate and return the ideal height and width. If the value of the cx member is greater than zero, then this value is considered the desired button width, and the ideal height for this width is calculated and returned in the cy member.

This message is most applicable to PushButtons. When sent to a PushButton, the message retrieves the bounding rectangle required to display the button's text. Additionally, if the PushButton has an image list, the bounding rectangle is also sized to include the button's image.

When sent to a button of any other type, the size of the control's window rectangle is retrieved.

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage examples

DIM sz AS SIZE
DIM res AS BOOLEAN = CButton.GetIdealSize(hButton, @sz)
DIM res AS BOOLEAN = CButton.GetIdealSize(hButton, sz)
sz = CButton.GetIdealSize(hButton)

GetBitmap

Retrieves a handle to the bitmap associated with the button.

FUNCTION GetBitmap (BYVAL hButton AS HWND) AS HANDLE

Return value

The return value is a handle to the bitmap, if any; otherwise, it is NULL.

Usage example

DIM hBmp AS HBIRMAP = CButton.GetBitmap(hButton)

GetIcon

Retrieves a handle to the icon associated with the button.

Return value

The return value is a handle to the icon, if any; otherwise, it is NULL.

Usage example

DIM hicon AS HICON = CButton.GetIcon(hButton)

GetImage

Retrieves a handle to the image (icon or bitmap) associated with the button.

FUNCTION GetImage (BYVAL hButton AS HWND, BYVAL imgType AS LONG) AS HANDLE

Parameter	Description
imgType	The type of image to associate with the button. This parameter can be one of the following values.

Value	Meaning
IMAGE_BITMAP	A bitmap.
IMAGE_ICON	An icon.

Return value

The return value is a handle to the image, if any; otherwise, it is NULL.

Usage examples

DIM hBmp AS HBITMAP = CButton.GetIcon(hButton, IMAGE_BITMAP)
DIM hIcon AS HICON = CButton.GetIcon(hButton, IMAGE_ICON)

GetImageList

Gets the BUTTON_IMAGELIST structure that describes the image list assigned to a button control.

FUNCTION GetImageList (BYVAL hButton AS HWND, BYVAL pbuttonImagelist AS BUTTON_IMAGELIST PTR) AS BOOLEAN
FUNCTION GetImageList (BYVAL hButton AS HWND, BYREF buttonImagelist AS BUTTON_IMAGELIST) AS BOOLEAN
FUNCTION GetImageList (BYVAL hButton AS HWND) AS BUTTON_IMAGELIST

Parameter	Description
pbuttonImagelist	A pointer to a BUTTON_IMAGELIST structure that receives the image list information.
buttonImagelist	A BUTTON_IMAGELIST structure that receives the image list information.

Usage examples

DIM bi AS BUTTON_IMAGELIST
CButton.GetImageList(hButton, @bi)
CButton.GetImageList(hButton, bi)
bi = CButton.GetImageList(hButton)

GetNote

Gets the text of the note associated with the Command Link button.

FUNCTION GetNote (BYVAL hButton AS HWND) AS DWSTRING

Remarks

The BCM_GETNOTE message works only with buttons that have the BS_COMMANDLINK or BS_DEFCOMMANDLINK button style.

Usage example

DIM dwsNote AS DWSTRING = CButton.GetNote(hButton)

GetNoteLength

Gets the length of the note text that may be displayed in the description for a command link.

FUNCTION GetNoteLength (BYVAL hButton AS HWND) AS LONG

Return value

Returns the length of the note text in Unicode characters, not including any terminating NULL, or zero if there is no note text.

Usage example

DIM cbNote AS LONG = CButton.GetNoteLength(hButton)

GetSplitImageList

Gets the handle of the split button image list.

FUNCTION GetSplitImageList (BYVAL hButton AS HWND) AS HIMAGELIST

Return value

The handle of the split button image list.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage example

DIM himl AS HIMAGELIST = CButton.GetSplitImageList

GetSplitInfo

Gets information for a split button control.

FUNCTION GetSplitInfo (BYVAL hButton AS HWND, BYVAL pinfo AS BUTTON_SPLITINFO PTR) AS BOOLEAN
FUNCTION GetSplitInfo (BYVAL hButton AS HWND, BYVAL info AS BUTTON_SPLITINFO) AS BOOLEAN
FUNCTION GetSplitInfo (BYVAL hButton AS HWND) AS BUTTON_SPLITINFO

Parameter	Description
pinfo	A pointer to a BUTTON_SPLITINFO structure to receive information on the button. The caller is responsible for allocating the memory for the structure. Set the mask member of this structure to determine what information to receive.
info	A BUTTON_SPLITINFO structure to receive information on the button. The caller is responsible for allocating the memory for the structure. Set the mask member of this structure to determine what information to receive.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage examples

info AS BUTTON_SPLITINFO
CButton.GetSplitInfo(hButton, @info)
CButton.GetSplitInfo(hButton, info)
info = CButton.GetSplitInfo(hButton)

GetSplitGlyphSize

Gets the size of the glyph in the image list.

FUNCTION GetSplitGlyphSize (BYVAL hButton AS HWND) AS SIZE

Return value

A SIZE structure that specifies the size of the glyph.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage examples

DIM sz AS SIZE = CButton.GetSplitGlyphSize(hButton)

GetSplitStyle

Gets the split button style.

FUNCTION GetSplitStyle (BYVAL hButton AS HWND) AS UINT

Return value

The split button style. Can be be one or more of the following flags.

Value	Description
BCSS_ALIGNLEFT	Align the image or glyph horizontally with the left margin.
BCSS_IMAGE	Draw an icon image as the glyph.
BCSS_NOSPLIT	No split.
BCSS_STRETCH	Stretch glyph, but try to retain aspect ratio.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage examples

DIM dwStyle AS UINT  = CButton.GetSplitStyle(hButton)

GetState

Retrieves the state of a button or check box.

FUNCTION GetState (BYVAL hButton AS HWND) AS LRESULT

Return value

The return value specifies the current state of the button. It is a combination of the following values.

Return code	Description
BST_CHECKED	The button is checked.
BST_DROPDOWNPUSHED	The button is in the drop-down state. Applies only if the button has the TBSTYLE_DROPDOWN style.
BST_FOCUS	The button has the keyboard focus.
BST_HOT	The button is hot; that is, the mouse is hovering over it.
BST_INDETERMINATE	The state of the button is indeterminate. Applies only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_PUSHED	The button is being shown in the pushed state.
BST_UNCHECKED	No special state. Equivalent to zero.

Usage example

DIM bst AS LRESULT = CButton.GetState(hButton)

GetStyle

Retrieves the style of the button.

FUNCTION GetStyle (BYVAL hButton AS HWND) AS DWORD

Return value

The style of the button.

Usage example

DIM dwStyle AS DWORD = CButton.GetStyle(hButton)

GetText

Retrieves the text in a button control.

FUNCTION GetText (BYVAL hButton AS HWND) AS DWSTRING

Usage example

DIM dwsText AS DWSTRING = CButton.GetText(hButton)

GetTextLength

Determines the length, in characters, of the text associated with a button.

FUNCTION GetTextLength (BYVAL hButton AS HWND) AS LONG

Usage example

DIM cbLen AS LONG = CButton.GetTextLength(hButton)

Return value

The return value is the length of the text in characters, not including the terminating null character.

GetTextMargin

Retrieves the margins used to draw text in a button control.

FUNCTION GetTextMargin (BYVAL hButton AS HWND, BYVAL pMargin AS RECT PTR) AS BOOLEAN
FUNCTION GetTextMargin (BYVAL hButton AS HWND, BYREF pMargin AS RECT) AS BOOLEAN
FUNCTION GetTextMargin (BYVAL hButton AS HWND) AS RECT

Parameter	Description
pMargin	A pointer to a RECT structure that contains the margins to use for drawing text.
margin	A RECT structure that contains the margins to use for drawing text.

Return value

If the message succeeds, it returns TRUE. Otherwise it returns FALSE.

Remarks

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage example

DIM rc AS RECT
CButton.GetTextMargin(hButton, @rc)
CButton.GetTextMargin(hButton, rc)
rc = CButton.GetTextMargin(hButton)

Gray

Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.

SUB Gray (BYVAL hButton AS HWND)

Usage example

CButton.Gray(hButton)

Indeterminate

Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.

SUB Indeterminate (BYVAL hButton AS HWND)

Usage example

CButton.Indeterminate(hButton)

SetBitmap

Associates a new bitmap with the button.

FUNCTION SetBitmap (BYVAL hButton AS HWND, BYVAL hbmp AS HBITMAP) AS HBITMAP

Parameter	Description
hButton	The handle of the button control.
hBmp	Handle of bitmap.

Return value

The return value is a handle to the bitmap previously associated with the button, if any; otherwise, it is NULL.

Usage example

CButton.SetBitmap(hButton, hBmp)

SetCheck

Sets the check state of a radio button or check box.

SUB SetCheck (BYVAL hButton AS HWND, BYVAL checkState AS LONG)

Value	Meaning
checkState	The check state. This parameter can be one of the following values.

Parameter	Description
BST_CHECKED	Sets the button state to checked.
BST_INDETERMINATE	Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_UNCHECKED	Sets the button state to cleared.

Return value

This message always returns zero.

Remarks

The BM_SETCHECK message has no effect on push buttons.

Usage example

CButton.SetCheck(hButton, BST_CHECKED)

SetDontClick

Sets a flag on a radio button that controls the generation of BN_CLICKED messages when the button receives focus.

SUB SetDontClick (BYVAL hButton AS HWND, BYVAL fState AS BOOLEAN)

Parameter	Description
fState	A BOOLEAN that specifies the state. TRUE to set the flag, otherwise FALSE.

Usage example

CButton.SetDontClick(hButton, TRUE)

Remarks

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

SetDropdownState

Sets the drop down state for a specified button with style of BS_SPLITBUTTON.

FUNCTION SetDropDownState (BYVAL hButton AS HWND, BYVAL fDropDown AS BOOLEAN) AS BOOLEAN

Parameter	Description
fDropDown	A BOOLEAN that is TRUE for state of BST_DROPDOWNPUSHED, or FALSE otherwise.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage example

CButton.SetDropDownState(hButton, TRUE)

SetElevationRequiredState

Sets the elevation required state for a specified button or command link to display an elevated icon.

FUNCTION SetElevationRequiredState (BYVAL fRequired AS BOOLEAN) AS LONG

Parameter	Description
fRequired	A BOOL that is TRUE to draw an elevated icon, or FALSE otherwise.

Return value

Returns 1 if successful, or an error code otherwise.

Remarks

An application must be manifested to use comctl32.dll version 6 to gain this functionality.

Usage example

CButton.SetElevationRequiredState(hButton, TRUE)

SetIcon

Associates a new icon with the button.

FUNCTION SetIcon (BYVAL hButton AS HWND, BYVAL hIcon AS HICON) AS HICON

Parameter	Description
hButton	The handle of the button control.
hIcon	Handle of icon.

Return value

The return value is a handle to the icon previously associated with the button, if any; otherwise, it is NULL.

Usage example

CButton.SetIcon(hButton, hIcon)

SetImage

Associates a new image (icon or bitmap) with the button. The return value is a handle to the image previously associated with the button, if any; otherwise, it is NULL.

FUNCTION SetImage (BYVAL hButton AS HWND, BYVAL ImageType AS DWORD, BYVAL hImage AS HANDLE) AS HANDLE

Parameter	Description
hButton	The handle of the button control.
ImageType	The type of image to delete. This parameter can be one of the following values (se below):
hImage	Handle of the icon or bitmap.

Value	Meaning
IMAGE_BITMAP	A bitmap.
IMAGE_ICON	An icon.

Return value

The return value is a handle to the image (icon or bitmap) previously associated with the button, if any; otherwise, it is NULL.

Usage examples

CButton.SetImage(hButton, IMAGE_BITMAP, hBmp)
CButton.SetImage(hButton, IMAGE_ICON, hIcon)

SetImageList

Assigns an image list to a button control.

FUNCTION SetImageList (BYVAL hButton AS HWND, BYVAL pbuttonImagelist AS BUTTON_IMAGELIST PTR) AS BOOLEAN
FUNCTION SetImageList (BYVAL hButton AS HWND, BYVAL himl AS HIMAGELIST, BYVAL nLeft AS LONG, _
   BYVAL nTop AS LONG, BYVAL nRight AS LONG, BYVAL nBottom AS LONG, BYVAL uALign AS UINT = 0) AS BOOLEAN

Parameter	Description
hButton	The handle to the button control.
pbuttonImagelist	A pointer to a BUTTON_IMAGELIST structure that contains image list information.

Parameter	Description
hButton	The handle to the button control.
hImageList	The handle to the image list.
nLeft	The x-coordinate of the upper-left corner of the rectangle for the image.
nTop	The y-coordinate of the upper-left corner of the rectangle for the image.
nRight	The x-coordinate of the lower-right corner of the rectangle for the image.
nBottom	The y-coordinate of the lower-right corner of the rectangle for the image.
uAlign	The alignment to use. This parameter can be one of the following values:

Value	Meaning
BUTTON_IMAGELIST_ALIGN_LEFT	Align the image with the left margin.
BUTTON_IMAGELIST_ALIGN_RIGHT	Align the image with the right margin.
BUTTON_IMAGELIST_ALIGN_TOP	Align the image with the top margin.
BUTTON_IMAGELIST_ALIGN_BOTTOM	Align the image with the bottom margin.
BUTTON_IMAGELIST_ALIGN_CENTER	Center the image.

The default value is BUTTON_IMAGELIST_ALIGN_LEFT.

Return value

If the message succeeds, it returns TRUE. Otherwise it returns FALSE.

Remarks

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

The image list referred to in the himl member of the BUTTON_IMAGELIST structure should contain either a single image to be used for all states or individual images for each state. The following states are defined in vssym32.h.

enum PUSHBUTTONSTATES {
    PBS_NORMAL = 1,
    PBS_HOT = 2,
    PBS_PRESSED = 3,
    PBS_DISABLED = 4,
    PBS_DEFAULTED = 5,
    PBS_STYLUSHOT = 6,
};

Note that PBS_STYLUSHOT is used only on tablet computers.

Each value is an index to the appropriate image in the image list. If only one image is present, it is used for all states. If the image list contains more than one image, each index corresponds to one state of the button. If an image is not provided for each state, nothing is drawn for those states without images.

SetNote

Sets the text of the note associated with a specified command link button.

FUNCTION SetNote (BYREF pwsz AS WSTRING) AS BOOLEAN

Parameter	Description
pwsz	A pointer to a null-terminated unicode string that contains the note.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Beginning with comctl32 DLL version 6.01, command link buttons may have a note.

The BCM_SETNOTE message works only with the BS_COMMANDLINK and BS_DEFCOMMANDLINK button styles.

The note text is displayed underneath the main caption. Command Link buttons require extra vertical space; if the control is too short, Windows will hide the note and render a single-line layout. ake the button taller to ensure the note becomes visible.

Usage examples

CButton.SetNote(hButton, "My note")

SetSplitImageList

Sets the image list used as split glyph (BCSIF_IMAGE / BCSIF_GLYPH).

FUNCTON SetSplitImageList (BYVAL hButton AS HWND, BYVAL himlGlyph AS HIMAGELIST) AS BOOLEAN

Parameter	Description
hButton	The handle to the button control.
himlGlyph	The handle of the image list.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0.

Usage examples

CButton.SetNote(hButton, himlGlyph)

SetSplitInfo

Sets information for a specified split button control.

FUNCTION SetSplitInfo (BYVAL hButton AS HWND, BYVAL pinfo AS BUTTON_SPLITINFO PTR) AS BOOLEAN
FUNCTION SetSplitInfo (BYVAL hButton AS HWND, BYREF info AS BUTTON_SPLITINFO) AS BOOLEAN

Parameter	Description
hButton	Handle of the button control.
pinfo	A pointer to a BUTTON_SPLITINFO structure containing information about the split button.
info	A BUTTON_SPLITINFO structure containing information about the split button.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

SetSplitGlyphSize

Sets the split size (glyph area) of a split button.

SetSplitGlyphSize (BYVAL hButton AS HWND, BYVAL cx AS LONG, BYVAL cy AS LONG) AS BOOLEAN

Parameter	Description
hButton	Handle of the button control.
cx	The width of the glyph area.
cy	The height of the glyph area.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

Usage examples

CButton.SetSplitGlyphSize(hButton, 30, 30)

SetSplitStyle

Sets the split style of a split button

FUNCTION SetSplitStyle (BYVAL hButton AS HWND, BYVAL uStyle AS UINT) AS BOOLEAN

Parameter	Description
hButton	Handle of the button control.
uStyle	The split button style. Value must be one or more of the following flags:

Value	Meaning
BCSS_ALIGNLEFT	Align the image or glyph horizontally with the left margin.
BCSS_IMAGE	Draw an icon image as the glyph.
BCSS_NOSPLIT	No split.
BCSS_STRETCH	Stretch glyph, but try to retain aspect ratio.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Use this message only with the BS_SPLITBUTTON and BS_DEFSPLITBUTTON button styles.

Usage examples

CButton.SetSplitStyle(hButton, BCSS_ALIGNLEFT)

SetState

Sets the highlight state of a button. The highlight state indicates whether the button is highlighted as if the user had pushed it.

SUB SetState (BYVAL hButton AS HWND, BYVAL bstate AS BOOLEAN)

Parameter	Description
bstate	A BOOLEAN that specifies whether the button is highlighted. A value of TRUE highlights the button. A value of FALSE removes any highlighting.

Remarks

Highlighting affects only the appearance of a button. It has no effect on the check state of a radio button or check box.

A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

Usage example

CButton.SetState(hButton, TRUE)

SetStyle

Sets the style of a button.

SUB SetStyle (BYVAL hButton AS HWND, BYVAL dwStyle AS DWORD, BYVAL fRedraw AS BOOLEAN)

Parameter	Description
dwStyle	The button style. This parameter can be a combination of button styles.
fRedraw	A BOOLEAN that specifies whether the button is to be redrawn. A value of TRUE redraws the button; a value of FALSE does not redraw the button.

For a table of button styles, see Button Styles.

SetText

Sets the text of a button.

FUNCTION SetText (BYVAL hButton AS HWND, BYVAL pwszText AS WSTRING PTR) AS BOOLEAN

Parameter	Description
hButton	The handle of te button control.
pwszText	The new text.

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Usage example

CButton.SetText(hButton, "Ok")

SetTextMargin

Sets the margins used to draw text in a button control.

FUNCTION SetTextMargin (BYVAL hButton AS HWND, BYVAL pMargin AS RECT PTR) AS BOOLEAN
FUNCTION SetTextMargin (BYVAL hButton AS HWND, BYREF margin AS RECT) AS BOOLEAN
FUNCTION SetTextMargin (BYVAL hButton AS HWND, BYVAL nLeft AS LONG, BYVAL nTop AS LONG, _
   BYVAL nRight AS LONG, BYVAL nBottom AS LONG) AS BOOLEAN

Parameter	Description
hButton	The handle of the button control.
pMargin	A pointer to a RECT structure that specifies the margins to use for drawing text.
margin	A RECT structure that specifies the margins to use for drawing text.
nLeft	The left margin.
nTop	The top margin.
nRight	The right margin.
nBottom	The bottom margin.

Return value

If the message succeeds, it returns TRUE. Otherwise it returns FALSE.

Remarks

To use this message, you must provide a manifest specifying Comclt32.dll version 6.0. For more information on manifests, see Enabling Visual Styles.

Uncheck

Unchecks the button.

SUB CButton.Uncheck ()

Example usage

CButton.Uncheck(hButton)

SetDarkMode

Sets the dark mode of the button.

FUNCTION SetDarkMode(BYVAL hButton AS HWND) AS HRESULT

Example usage

CButton.SetDarkMode(hButton)

RemoveDarkMode

Removes dark mode from the button.

FUNCTION RemoveDarkMode (BYVAL hButton AS HWND) AS HRESULT

Example usage

CButton.RemoveDarkMode(hButton)