CommandButtonW class
A CommandButtonW is a push button with a caption, which the user clicks to start an action. It can show a picture beside its caption, have a second part with an arrow that opens a menu, show the shield of an action that needs elevation, and leave its drawing to the program.
CommandButtonW1.Caption = "&Save " & ChrW$(&H3A9) ' the caption is Unicode: a Greek capital omega
CommandButtonW1.Default = True ' the Enter key clicks it
Debug.Print Len(CommandButtonW1.Caption); CommandButtonW1.Default; CommandButtonW1.Value
' Output:
' 7 TrueFalse
The control stands in place of the CommandButton of VB6, which in twinBASIC is the CommandButton of the VB package. This one adds the split button (SplitButton), a picture from an image list (ImageList), a picture and a caption together (PictureAndCaption), the caption’s alignment and wrapping, SetShield, GetIdealSize, PerformClick, Transparent, and drawing by the program (DrawMode).
Of the common members, the control has those under Name and place, Window handles, Font and visual styles, Mouse but DblClick, Keyboard and focus, Dragging the control, OLE drag and drop and Right-to-left but RightToLeftLayout. Its Click event has a meaning of its own.
- Clicking the button
- Caption and pictures
- The split button
- The graphical style
- Drawing the control in code
- Properties
- Methods
- Events
- CmdImageListAlignmentConstants
- CmdDrawModeConstants
- See Also
Clicking the button
The control raises Click when the user clicks it with the left mouse button, presses the space key while it has the focus, or presses the Alt key with the character that follows an & in the Caption. The button with Default set raises it for the Enter key, and the button with Cancel set for the Esc key, whichever control of the form has the focus.
A program clicks the button with PerformClick, or by setting Value to True. Value is True only while the Click event runs, and False at every other time.
Private Sub CommandButtonW1_Click()
Debug.Print "Saving..."
End Sub
Caption and pictures
In the standard Style Windows draws the button. Alignment, VerticalAlignment and WordWrap place the caption on it.
A picture comes from one of two places:
- Picture is shown in place of the caption. With PictureAndCaption set, in a program with visual styles, the button shows both.
- An ImageList control assigned to the ImageList property is shown together with the caption, at the side that ImageListAlignment names and at the distance of ImageListMargin from the edge. The control shows the image list’s pictures when the program has visual styles. While an image list is assigned, Picture is not shown.
The image list holds one picture, which the control shows in every state, or one picture for each state in this order: normal, under the mouse, pressed, disabled, default or with the focus, under a pen.
GetIdealSize gives the size at which the caption and the picture fit:
Dim W As Single, H As Single
CommandButtonW1.Caption = "Copy to the clipboard"
CommandButtonW1.GetIdealSize W, H
CommandButtonW1.Width = W
CommandButtonW1.Height = H
The split button
With SplitButton set, in a program with visual styles, the button has a narrow second part with an arrow, at the side that SplitButtonAlignment names. A click on the main part raises Click. A click on the arrow raises DropDown and no Click, and the handler shows what the arrow opens, a popup menu as a rule. The arrow part is drawn as held down while the handler runs.
Private Sub CommandButtonW1_DropDown()
' Show a popup menu under the button here. The arrow stays down until this procedure returns.
Debug.Print CommandButtonW1.DroppedDown ' True
End Sub
SplitButtonGlyph puts a picture in place of the arrow. SplitButtonNoSplit removes the line between the two parts.

Setting DroppedDown to True does what a click on the arrow does: the arrow part goes down, DropDown is raised, and the arrow part comes up again when the handler returns. On a button that is not a split button it does nothing.
CommandButtonW1.SplitButton = True
CommandButtonW1.DroppedDown = True ' raises DropDown
Debug.Print CommandButtonW1.DroppedDown
' Output:
' False
The graphical style
With Style set to vbButtonGraphical the control draws the button itself: the picture in the middle and the caption under it, centered. Picture is the picture of the button when it is up, DownPicture when it is held down, and DisabledPicture when it is disabled. With UseMaskColor the color MaskColor of a bitmap is not drawn. The button has the BackColor and the caption the ForeColor.
In this style Alignment, VerticalAlignment, WordWrap, ImageList, PictureAndCaption and SplitButton have no effect.
Drawing the control in code
With DrawMode set to CmdDrawModeOwnerDraw the control draws nothing. It raises OwnerDraw each time it has to be drawn, and the handler draws the whole button on the device context the event gives it. The button is still clicked as any other.
Private Declare PtrSafe Function Rectangle Lib "gdi32" (ByVal hDC As LongPtr, ByVal Left As Long, ByVal Top As Long, ByVal Right As Long, ByVal Bottom As Long) As Long
Private Declare PtrSafe Function TextOutW Lib "gdi32" (ByVal hDC As LongPtr, ByVal X As Long, ByVal Y As Long, ByVal Text As LongPtr, ByVal Length As Long) As Long
Private Sub CommandButtonW1_OwnerDraw(ByVal DisplayAsDefault As Boolean, ByVal Action As Long, ByVal State As Long, ByVal hDC As Long, ByVal Left As Long, ByVal Top As Long, ByVal Right As Long, ByVal Bottom As Long)
Dim Shift As Long
If (State And 1) <> 0 Then Shift = 1 ' held down: move the caption a little
Rectangle hDC, Left, Top, Right, Bottom
TextOutW hDC, Left + 6 + Shift, Top + 4 + Shift, StrPtr(CommandButtonW1.Caption), Len(CommandButtonW1.Caption)
End Sub
The graphical style and this mode exclude each other. Setting Style to vbButtonGraphical in this mode raises run-time error 383, and setting DrawMode to CmdDrawModeOwnerDraw makes a graphical Style standard.
Properties
Alignment
Where the caption is on the button, from left to right. A member of AlignmentConstants. Default: vbCenter.
Another value raises run-time error 380.
Setting RightToLeft to True changes vbLeftJustify to vbRightJustify, and setting it to False changes it back.
Appearance
Whether the button is drawn flat or raised. A member of CCAppearanceConstants. Default: CCAppearance3D. Another value raises run-time error 380. The flat button shows where the control is drawn without visual styles.
BackColor
The color of the button in the graphical Style, where the control is drawn without visual styles. OLE_COLOR. Default: vbButtonFace.
Cancel
Whether the button is the form’s cancel button, which the Esc key clicks. Boolean. Default: False.
Caption
The text on the button. String. A control newly drawn on a form has its own name.
The character after an & is underlined, and the Alt key with that character clicks the button. Two of them, &&, show one &.
Default
Whether the button is the form’s default button, which the Enter key clicks while no other button has the focus. Boolean. Default: False. The form’s default button is drawn with a heavier border.
DisabledPicture
The picture of a disabled control in the graphical Style. A picture object, or Nothing (the default): the control then shows Picture, grayed.
DownPicture
The picture of the control in the graphical Style while it is held down. A picture object, or Nothing (the default): the control then shows Picture.
DrawMode
Whether the control draws itself or leaves the drawing to the OwnerDraw event. A member of CmdDrawModeConstants. Default: CmdDrawModeNormal. Another value raises run-time error 380. A change makes the control’s window again, so hWnd changes. See Drawing the control in code.
DroppedDown
Whether the arrow part of a split button is drawn as held down. Boolean. It is True while the DropDown event runs. Setting it to True raises DropDown; see The split button.
ForeColor
The color of the caption in the graphical Style. OLE_COLOR. A control newly drawn on a form has black. In the standard style Windows draws the caption in the color of the system or of the visual style.
Hot
Whether the mouse is over the control, as Windows reports it for a control with visual styles. Boolean, read-only.
Assigning to it raises run-time error 383.
ImageList
The image list whose pictures the control shows beside its caption. See Caption and pictures.
The property takes one of three things:
- an ImageList control of the package. The property then returns the control.
- a String: the name of an ImageList control on the same form. The property then returns the control.
- a Long or a LongLong: the handle of an image list of Windows. The property then returns the handle.
Nothing, the handle 0, a name that no ImageList control on the form has, and an image list that holds no picture all leave the control without an image list: the property then returns Nothing. An object of another class raises run-time error 35610, and a value of another type, an Integer included, raises run-time error 13.
ImageListAlignment
Where the picture of the image list is, relative to the caption. A member of CmdImageListAlignmentConstants. Default: CmdImageListAlignmentLeft. Another value raises run-time error 380.
Setting RightToLeft to True changes CmdImageListAlignmentLeft to CmdImageListAlignmentRight, and setting it to False changes it back.
ImageListMargin
The distance between the picture of the image list and the edge of the control that ImageListAlignment names, in the scale units of the control’s container. Single. Default: 0. The control keeps it as a whole number of pixels. With CmdImageListAlignmentCenter it has no effect.
A negative value raises run-time error 380.
MaskColor
The color of a bitmap that the control does not draw, in the graphical Style and while UseMaskColor is True. OLE_COLOR. Default: &HC0C0C0, light gray.
Picture
The picture the control shows. A picture object, or Nothing (the default).
In the standard Style an icon or a bitmap is shown in place of the caption, or beside it with PictureAndCaption, unless an ImageList is assigned. In the graphical style the picture is drawn in the middle of the button, above the caption.
PictureAndCaption
Whether a button in the standard Style shows its Picture and its Caption together, in a program with visual styles. Boolean. Default: False, with which the picture takes the caption’s place.
Pushed
Whether the control is drawn as held down. Boolean. It is True while the user holds the mouse button or the space key down on the control. Setting it changes how the control is drawn and raises no event.
SplitButton
Whether the button has a second part with an arrow, in a program with visual styles. Boolean. Default: False. See The split button.
SplitButtonAlignment
The side of the button that the arrow part is at. A member of CCLeftRightAlignmentConstants. Default: CCLeftRightAlignmentRight.
Another value raises run-time error 380.
Setting RightToLeft to True changes CCLeftRightAlignmentRight to CCLeftRightAlignmentLeft, and setting it to False changes it back.
SplitButtonGlyph
The picture shown on the arrow part of a split button, in place of the arrow. A picture object that holds a bitmap or an icon, or Nothing (the default) for the arrow.
SplitButtonNoSplit
Whether a split button is drawn without the line between its two parts. Boolean. Default: False. Without the line the button has no part of its own for the arrow: a click by the user anywhere on it raises Click and no DropDown.
Style
Whether Windows draws the button or the control draws it itself, with a picture. A member of ButtonConstants: vbButtonStandard (the default) or vbButtonGraphical. Another value raises run-time error 380. See The graphical style.
Setting it to vbButtonGraphical while DrawMode is CmdDrawModeOwnerDraw raises run-time error 383. A change makes the control’s window again, so hWnd changes.
Transparent
Whether the control’s background is a copy of what its container draws behind it, so that a picture or a gradient on the form shows through where the button does not cover it. Boolean. Default: False. The control takes the copy when it is first drawn, and again after a change of its size and after Refresh.
UseMaskColor
Whether the color MaskColor of a bitmap is left out when the control draws the bitmap in the graphical Style. Boolean. Default: False.
Value
Whether the button is being clicked. Boolean. It is the control’s default property. It is True while the Click event runs and False at every other time.
Setting it to True raises Click, on a disabled button too. Setting it to False does nothing.
VerticalAlignment
Whether the caption is at the top, the middle or the bottom of the button. A member of CCVerticalAlignmentConstants. Default: CCVerticalAlignmentCenter. Another value raises run-time error 380.
WordWrap
Whether a caption too long for one line continues on the next. Boolean. Default: True.
Methods
GetIdealSize
Gives the size at which the button’s caption and picture fit, as Windows works it out for a control with visual styles.
Syntax: object.GetIdealSize Width, Height
- Width, Height
- required Two Single variables, which the method sets to the size in the scale units of the control’s container.
PerformClick
Clicks the button as the user would: it makes the button’s form the active window, gives the button the focus, and has Windows press and release it, which raises Click.
Syntax: object.PerformClick
SetShield
Shows or removes the shield icon that marks an action for which Windows asks the user for elevation, in a program with visual styles. The icon is beside the caption.
Syntax: object.SetShield( State ) As Long
- State
- required A Boolean: True to show the shield, False to remove it and show the button’s Picture again.
The function returns what Windows returns for the request, which does not tell whether the shield is shown: it is 0 when a button with no picture gets the shield.
Events
Click
Raised when the button is clicked: by the user with the mouse or the keyboard, by PerformClick, or by setting Value to True. See Clicking the button.
Syntax: object_Click( )
DropDown
Raised when the user clicks the arrow part of a split button, and when the program sets DroppedDown to True. See The split button.
Syntax: object_DropDown( )
HotChanged
Raised when the mouse moves onto the control or leaves it, where the control is drawn with visual styles. Hot tells which.
Syntax: object_HotChanged( )
OwnerDraw
Raised when the control has to be drawn, while DrawMode is CmdDrawModeOwnerDraw.
Syntax: object_OwnerDraw( ByVal DisplayAsDefault As Boolean, ByVal Action As Long, ByVal State As Long, ByVal hDC As Long, ByVal Left As Long, ByVal Top As Long, ByVal Right As Long, ByVal Bottom As Long )
- DisplayAsDefault
- True while the button is the one the Enter key would click, which a button shows with a heavier border.
- Action
- Why the control is drawn, as a sum of: 1, the whole control has to be drawn; 2, it was pressed or released; 4, it took or lost the focus.
- State
- The state to draw, as a sum of: 1, held down; 4, disabled;
&H10, with the focus;&H40, under the mouse, which the control reports only while MouseTrack is True;&H100, without the underline of the access key;&H200, without the focus rectangle. - hDC
- The handle of the device context to draw on.
- Left, Top, Right, Bottom
- The rectangle of the control, in pixels.
CmdImageListAlignmentConstants
The values of ImageListAlignment.

| Member | Value | Description |
|---|---|---|
| CmdImageListAlignmentLeft | 0 | The picture is to the left of the caption. |
| CmdImageListAlignmentRight | 1 | The picture is to the right of the caption. |
| CmdImageListAlignmentTop | 2 | The picture is above the caption. |
| CmdImageListAlignmentBottom | 3 | The picture is under the caption. |
| CmdImageListAlignmentCenter | 4 | The picture is in the middle of the control. |
CmdDrawModeConstants
The values of DrawMode.
| Member | Value | Description |
|---|---|---|
| CmdDrawModeNormal | 0 | The control is drawn by Windows, or by itself in the graphical style. |
| CmdDrawModeOwnerDraw | 1 | The program draws the control, in the OwnerDraw event. |
See Also
- Common members – the members this control shares with the package’s other controls
- CommandLink class – a button with a title, a note and an arrow
- CheckBoxW class – a check box, which can also look like a button that stays down
- CommandButton – the push button of the VB package