SysWin Gui ToolBar

Home › All Categories › sys/win › sys/win/gui › ToolBar

ToolBar

Adds, changes and queries the buttons of a toolbar control and the images they show.

A toolbar is a row of buttons, usually under the menu bar, that send WM_COMMAND to the parent with the button's command identifier when they are clicked, just as menu items do. Create one with CWindow.AddControl( "Toolbar", ... ), which also tells the control the size of TBBUTTON (a toolbar made with CreateWindowExW needs ButtonStructSize first). Every function here takes the toolbar's handle first and is written with the namespace: ToolBar.AddButton( hToolBar, ... ).

Buttons have two numbers, and each function says which one it takes:

Number	What it is	Taken by
Command identifier	the id you gave the button; fixed	`CheckButton`, `EnableButton`, `GetState`, `GetRect`, `GetButtonText` …
Index	the button's position from the left, separators counted; changes as buttons are added, moved or deleted	`GetButton`, `GetItemRect`, `DeleteButton`, `MoveButton`, `InsertButton`

CommandToIndex converts one to the other.

The pictures come from image lists: one for the normal state, and optionally one each for hot (under the mouse), disabled and pressed buttons. A button's image number is an index into them. LoadImages fills the normal list with the standard Windows images; your own lists are made with ImageList_Create and are yours to destroy, after the toolbar is gone or when you replace them. Rectangles are client coordinates of the toolbar. Several messages (padding metrics, themes, pressed images, list gap) need version 6 of the common controls: give the program a manifest or call EnableVisualStyles() first.

Importing

#import "sys/win"
#import "sys/win/gui"
using win, gui

Example

A toolbar with the standard New, Open and Save images and a check button. Save is disabled until New or Open is clicked; the check button reports its state in the caption.

#import "sys/win"
#import "sys/win/gui"
using win, gui

const IDC_TOOLBAR = 100
enum
    IDM_NEW = 1001
    IDM_OPEN
    IDM_SAVE
    IDM_LOCK
end enum

declare function WndProc( byval hwnd as HWND, byval uMsg as UINT, byval wParam as WPARAM, byval lParam as LPARAM ) as LRESULT

function main() as long
    SetProcessDpiAwareness( PROCESS_SYSTEM_DPI_AWARE )
    EnableVisualStyles()
    dim pWindow as CWindow = "ToolBarDemo"
    dim hWin as HWND = pWindow.Create( NULL, "ToolBar", @WndProc )
    pWindow.SetClientSize( 420, 200 )
    pWindow.Center()
    dim hToolBar as HWND = pWindow.AddControl( "Toolbar", hWin, IDC_TOOLBAR )
    ToolBar.LoadImages( hToolBar, IDB_STD_SMALL_COLOR )
    ToolBar.AddButton( hToolBar, STD_FILENEW, IDM_NEW, 0, BTNS_AUTOSIZE, 0, "New" )
    ToolBar.AddButton( hToolBar, STD_FILEOPEN, IDM_OPEN, 0, BTNS_AUTOSIZE, 0, "Open" )
    ToolBar.AddButton( hToolBar, STD_FILESAVE, IDM_SAVE, 0, BTNS_AUTOSIZE, 0, "Save" )
    ToolBar.AddSeparator( hToolBar )
    ToolBar.AddButton( hToolBar, STD_PROPERTIES, IDM_LOCK, 0, BTNS_CHECK or BTNS_AUTOSIZE, 0, "Lock" )
    ToolBar.DisableButton( hToolBar, IDM_SAVE )
    ToolBar.AutoSize( hToolBar )
    return pWindow.DoEvents( SW_NORMAL )
end function

function WndProc( byval hwnd as HWND, byval uMsg as UINT, byval wParam as WPARAM, byval lParam as LPARAM ) as LRESULT
    select case uMsg
        case WM_SIZE
            ToolBar.AutoSize( GetDlgItem( hwnd, IDC_TOOLBAR ) )
            return 0
        case WM_COMMAND
            dim hToolBar as HWND = GetDlgItem( hwnd, IDC_TOOLBAR )
            select case CBCTL( wParam, lParam )
                case IDM_NEW, IDM_OPEN
                    ToolBar.EnableButton( hToolBar, IDM_SAVE )
                    SetWindowText( hwnd, "Clicked " & ToolBar.GetButtonText( hToolBar, CBCTL( wParam, lParam ) ) )
                case IDM_SAVE
                    ToolBar.DisableButton( hToolBar, IDM_SAVE )
                    SetWindowText( hwnd, "Saved" )
                case IDM_LOCK
                    SetWindowText( hwnd, iif( ToolBar.IsButtonChecked( hToolBar, IDM_LOCK ), "Locked", "Unlocked" ) )
            end select
            return 0
        case WM_DESTROY
            PostQuitMessage( 0 )
            return 0
    end select
    return DefWindowProcW( hwnd, uMsg, wParam, lParam )
end function

end main()

The toolbar sits at the top of the client area by itself (CCS_TOP); calling AutoSize from WM_SIZE keeps it the width of the window.

Functions

Function	Does
AddButton	Adds one button from its parts.
AddButtons	Adds buttons from an array of `TBBUTTON`.
AddSeparator	Adds a separator.
InsertButton	Inserts a button at an index.
InsertSeparator	Inserts a separator at an index.
DeleteButton	Deletes the button at an index.
MoveButton	Moves a button to another index.
ButtonCount	Returns the number of buttons and separators.
ButtonStructSize	Tells the toolbar the size of `TBBUTTON`.
AutoSize	Resizes the toolbar to fit its buttons and its parent.
CommandToIndex	Returns the index of the button with a command identifier.
SetCmdId	Changes the command identifier of the button at an index.
GetButton	Reads the `TBBUTTON` of the button at an index.
GetButtonInfo	Reads a button's attributes into a `TBBUTTONINFOW`.
SetButtonInfo	Changes a button's attributes from a `TBBUTTONINFOW`.
CheckButton, UncheckButton	Checks or unchecks a button.
EnableButton, DisableButton	Enables or disables a button.
HideButton, UnhideButton	Hides or shows a button.
PressButton, ReleaseButton	Draws a button pressed or released.
MarkButton, HighlightButton, UnhighlightButton	Sets or clears a button's highlight.
Indeterminate	Sets or clears a button's indeterminate (greyed) state.
IsButtonChecked, IsButtonEnabled, IsButtonHidden, IsButtonHighlighted, IsButtonIndeterminate, IsButtonPressed	Test one state of a button.
GetState	Returns all the state flags of a button.
SetState	Sets all the state flags of a button.
GetButtonText	Returns or reads the text of a button.
GetButtonTextLength	Returns the length of a button's text.
AddString	Adds strings to the toolbar's string pool.
GetString	Reads a string from the string pool.
MapAccelerator	Finds the button whose text has a given accelerator letter.
SetMaxTextRows	Sets how many lines of text a button may show.
GetTextRows	Returns how many lines of text a button may show.
SetDrawTextFlags	Sets the `DrawText` flags for button text.
LoadImages	Loads a set of standard Windows images.
AddBitmap	Adds images from a bitmap.
ReplaceBitmap	Replaces images added from a bitmap.
SetBitmapSize	Sets the size of the images to be added.
GetBitmapFlags	Says whether large images should be used.
GetBitmap	Returns a button's image number.
ChangeBitmap	Changes a button's image number.
GetImageList, SetImageList	Read or set the normal image list.
GetHotImageList, SetHotImageList	Read or set the image list for hot buttons.
GetDisabledImageList, SetDisabledImageList	Read or set the image list for disabled buttons.
SetPressedImageList	Sets the image list for pressed buttons.
GetImageListCount	Returns the number of normal image lists.
GetButtonSize, GetButtonWidth, GetButtonHeight	Return the button size.
SetButtonSize	Sets the button size.
SetButtonWidth	Sets the smallest and largest button width.
GetItemRect	Returns the rectangle of the button at an index.
GetRect	Returns the rectangle of the button with a command identifier.
GetMaxSize	Returns the size of all visible buttons together.
GetPadding, GetHorizontalPadding, GetVerticalPadding	Return the padding inside buttons.
SetPadding	Sets the padding inside buttons.
GetMetrics	Reads padding and spacing into a `TBMETRICS`.
SetMetrics	Sets padding and spacing from a `TBMETRICS`.
SetIndent	Sets the space before the first button.
SetListGap	Sets the gap between buttons in list style.
GetRows	Returns the number of rows of a wrapping toolbar.
SetRows	Sets the number of rows of a wrapping toolbar.
HitTest	Finds the button at a point.
GetHotItem	Returns the index of the hot button.
SetHotItem	Makes a button hot.
GetAnchorHighlight	Says whether hot-item highlighting is anchored.
SetAnchorHighlight	Anchors or releases hot-item highlighting.
GetInsertMark	Reads the insertion mark.
SetInsertMark	Places or removes the insertion mark.
GetInsertMarkColor	Returns the colour of the insertion mark.
SetInsertMarkColor	Sets the colour of the insertion mark.
InsertMarkHitTest	Works out where an insertion mark for a point goes.
GetStyle	Returns the toolbar styles.
SetStyle	Sets the toolbar styles.
GetExtendedStyle	Returns the extended toolbar styles.
SetExtendedStyle	Sets the extended toolbar styles.
MakeOpaque	Removes `TBSTYLE_TRANSPARENT`.
GetColorScheme	Reads the highlight and shadow colours.
SetColorScheme	Sets the highlight and shadow colours.
SetWindowTheme	Asks for a visual style by name.
SetDarkMode, RemoveDarkMode	Gives the toolbar the dark theme, or its normal one.
GetTooltips	Returns the toolbar's tooltip control.
SetToolTips	Gives the toolbar a tooltip control.
SetParent	Sets the window that receives the toolbar's notifications.
Customize	Opens the Customize Toolbar dialog.
SaveRestore	Saves the buttons to the registry or restores them.
GetObject	Meant to return the toolbar's `IDropTarget`.

Reference

AddButton

function AddButton( byval hToolbar as HWND, byval idxBitmap as long, byval idCommand as long, byval fsState as ubyte = 0, byval fsStyle as ubyte = 0, byval dwData as DWORD_PTR = 0, byval pwszText as wstring ptr = NULL ) as boolean

Adds one button at the right-hand end, building the TBBUTTON for you. The text, if any, is copied by the toolbar, so the string you pass need not outlive the call.

Parameter	Meaning
`idxBitmap`	The image number in the image lists, or `I_IMAGENONE` for none.
`idCommand`	The command identifier sent with `WM_COMMAND` when the button is clicked.
`fsState`	`TBSTATE_*` flags. 0, the default, is taken as `TBSTATE_ENABLED`; to add a disabled button, call DisableButton afterwards.
`fsStyle`	`BTNS_*` styles: `BTNS_BUTTON` (0), `BTNS_CHECK`, `BTNS_CHECKGROUP`, `BTNS_DROPDOWN`, `BTNS_AUTOSIZE`, `BTNS_SHOWTEXT` …
`dwData`	A value of your own, read back with GetButton.
`pwszText`	The button's text; `NULL` or an empty string for none.

Returns true on success.

Example

ToolBar.AddButton( hCtrl, STD_PRINT, 1005, 0, BTNS_AUTOSIZE, 0, "Print" )

Microsoft Learn: TB_ADDBUTTONS

AddButtons

function AddButtons overload( byval hToolbar as HWND, byval nButtons as DWORD, byval pButtons as TBBUTTON ptr ) as boolean
function AddButtons overload( byval hToolbar as HWND, byval nButtons as DWORD, byref Buttons as TBBUTTON ) as boolean

Adds nButtons buttons at the right-hand end from an array of TBBUTTON; pass a pointer to its first element, or the first element itself. Fill iBitmap, idCommand, fsState (at least TBSTATE_ENABLED), fsStyle and iString (a pool index from AddString, a wstring pointer, or -1 for none).

Returns true on success.

Example

dim tbb(1) as TBBUTTON
tbb(0).iBitmap = STD_CUT : tbb(0).idCommand = 1011 : tbb(0).fsState = TBSTATE_ENABLED : tbb(0).iString = -1
tbb(1).iBitmap = STD_COPY : tbb(1).idCommand = 1012 : tbb(1).fsState = TBSTATE_ENABLED : tbb(1).iString = -1
ToolBar.AddButtons( hCtrl, 2, tbb(0) )

Microsoft Learn: TB_ADDBUTTONS

AddSeparator

function AddSeparator( byval hToolbar as HWND, byval nWidth as long = 0 ) as boolean

Adds a separator at the right-hand end: a gap, drawn as a line in a flat toolbar. A separator counts as a button for indexes and ButtonCount. nWidth is its width in pixels; 0 gives the default width.

Returns true on success.

Example

ToolBar.AddSeparator( hCtrl )

InsertButton

function InsertButton overload( byval hToolbar as HWND, byval idxButton as long, byval pButton as TBBUTTON ptr ) as boolean
function InsertButton overload( byval hToolbar as HWND, byval idxButton as long, byref Button as TBBUTTON ) as boolean
function InsertButton overload( byval hToolbar as HWND, byval idxButton as long, byval idxBitmap as long, byval idCommand as long, byval fsState as ubyte = 0, byval fsStyle as ubyte = 0, byval dwData as DWORD_PTR = 0, byval pwszText as wstring ptr = NULL ) as boolean

Inserts a button to the left of the button at index idxButton; an index equal to the button count, or -1, adds it at the end. The first two forms take a filled-in TBBUTTON; the third builds one from its parts exactly as AddButton does (fsState 0 means enabled).

Returns true on success.

Example

ToolBar.InsertButton( hCtrl, 0, STD_FIND, 1020, 0, BTNS_AUTOSIZE, 0, "Find" )   ' first

Microsoft Learn: TB_INSERTBUTTON

InsertSeparator

function InsertSeparator( byval hToolbar as HWND, byval idxButton as long, byval nWidth as long = 0 ) as boolean

Inserts a separator to the left of the button at index idxButton. nWidth 0 gives the default width.

Returns true on success.

Example

ToolBar.InsertSeparator( hCtrl, 1 )

DeleteButton

function DeleteButton( byval hToolbar as HWND, byval nButton as long ) as boolean

Deletes the button or separator at index nButton. The buttons to its right move down one index.

Returns true on success.

Example

ToolBar.DeleteButton( hCtrl, ToolBar.CommandToIndex( hCtrl, 1005 ) )

Microsoft Learn: TB_DELETEBUTTON

MoveButton

function MoveButton( byval hToolbar as HWND, byval uOldPos as DWORD, byval uNewPos as DWORD ) as boolean

Moves the button at index uOldPos to index uNewPos.

Returns true on success.

Example

ToolBar.MoveButton( hCtrl, 0, ToolBar.ButtonCount( hCtrl ) - 1 )   ' first to last

Microsoft Learn: TB_MOVEBUTTON

ButtonCount

function ButtonCount( byval hToolbar as HWND ) as DWORD

Returns the number of buttons, separators included.

Example

print ToolBar.ButtonCount( hCtrl ); " buttons"

Microsoft Learn: TB_BUTTONCOUNT

ButtonStructSize

sub ButtonStructSize( byval hToolbar as HWND, byval cb as long )

Tells the toolbar the size of the TBBUTTON structures it will be given. A toolbar created with CreateWindowExW needs it once, before the first button is added; CWindow.AddControl sends it already.

Example

ToolBar.ButtonStructSize( hCtrl, sizeof( TBBUTTON ) )

Microsoft Learn: TB_BUTTONSTRUCTSIZE

AutoSize

sub AutoSize( byval hToolbar as HWND )

Resizes the toolbar to the height of its buttons and, unless it has CCS_NORESIZE, to the width of its parent. Call it after adding buttons or changing their size, and from the parent's WM_SIZE.

Example

ToolBar.AutoSize( hCtrl )

Microsoft Learn: TB_AUTOSIZE

CommandToIndex

function CommandToIndex( byval hToolbar as HWND, byval idButton as long ) as long

Returns the index of the button whose command identifier is idButton, or -1 if there is none.

Example

dim i as long = ToolBar.CommandToIndex( hCtrl, 1002 )
if i >= 0 then print "button 1002 is at index"; i

Microsoft Learn: TB_COMMANDTOINDEX

SetCmdId

function SetCmdId( byval hToolbar as HWND, byval index as short, byval cmdid as short ) as boolean

Gives the button at index index the command identifier cmdid. Both are short, so identifiers above 32767 do not fit.

Returns true on success.

Example

ToolBar.SetCmdId( hCtrl, 0, 1030 )

Microsoft Learn: TB_SETCMDID

GetButton

function GetButton overload( byval hToolbar as HWND, byval nButton as long, byval ptbb as TBBUTTON ptr ) as boolean
function GetButton overload( byval hToolbar as HWND, byval nButton as long, byref tbb as TBBUTTON ) as boolean
function GetButton overload( byval hToolbar as HWND, byval nButton as long ) as TBBUTTON

Reads the TBBUTTON of the button at index nButton: image number, command identifier, state, style, your dwData and string. The third form returns the structure, all zero when the index is out of range.

Returns true on success (first two forms).

Example

dim tbb as TBBUTTON = ToolBar.GetButton( hCtrl, 0 )
print "command"; tbb.idCommand; ", image"; tbb.iBitmap

Microsoft Learn: TB_GETBUTTON

GetButtonInfo

function GetButtonInfo overload( byval hToolbar as HWND, byval iID as long, byval ptbbi as TBBUTTONINFOW ptr ) as long
function GetButtonInfo overload( byval hToolbar as HWND, byval iID as long, byref tbbi as TBBUTTONINFOW ) as long
function GetButtonInfo overload( byval hToolbar as HWND, byval iID as long ) as TBBUTTONINFOW

Reads the attributes that dwMask asks for (TBIF_COMMAND, TBIF_IMAGE, TBIF_STATE, TBIF_STYLE, TBIF_TEXT, TBIF_SIZE, TBIF_LPARAM …) of the button with command identifier iID, or of the button at index iID when the mask includes TBIF_BYINDEX. Set cbSize to sizeof( TBBUTTONINFOW ) first. The third form sends a structure whose cbSize and dwMask are 0, so the control fills in nothing and it comes back all zero; use one of the first two.

Returns the index of the button, or -1 on failure.

Example

dim tbbi as TBBUTTONINFOW
tbbi.cbSize = sizeof( tbbi ) : tbbi.dwMask = TBIF_IMAGE or TBIF_STYLE
if ToolBar.GetButtonInfo( hCtrl, 1001, tbbi ) >= 0 then print "image"; tbbi.iImage

Microsoft Learn: TB_GETBUTTONINFO

SetButtonInfo

function SetButtonInfo overload( byval hToolbar as HWND, byval iID as long, byval ptbbi as TBBUTTONINFOW ptr ) as long
function SetButtonInfo overload( byval hToolbar as HWND, byval iID as long, byref tbbi as TBBUTTONINFOW ) as long

Changes the attributes that dwMask names of the button with command identifier iID (or index, with TBIF_BYINDEX); the others stay as they are. Set cbSize first. This is the way to change a button's text or width after it has been added.

Returns nonzero on success, 0 on failure.

Example

dim tbbi as TBBUTTONINFOW
tbbi.cbSize = sizeof( tbbi ) : tbbi.dwMask = TBIF_TEXT : tbbi.pszText = @wstr( "Paste" )
ToolBar.SetButtonInfo( hCtrl, 1001, tbbi )

Microsoft Learn: TB_SETBUTTONINFO

CheckButton, UncheckButton

function CheckButton overload( byval hToolbar as HWND, byval idButton as long, byval fCheck as short ) as boolean
function CheckButton overload( byval hToolbar as HWND, byval idButton as long ) as boolean
function UncheckButton( byval hToolbar as HWND, byval idButton as long ) as boolean

Checks (draws pushed in) or unchecks the button with command identifier idButton. The form with fCheck checks for nonzero and unchecks for 0; the form without it checks. A check button (BTNS_CHECK) also changes state when the user clicks it.

Returns true on success.

Example

ToolBar.CheckButton( hCtrl, 1004 )
ToolBar.UncheckButton( hCtrl, 1004 )

Microsoft Learn: TB_CHECKBUTTON

EnableButton, DisableButton

function EnableButton( byval hToolbar as HWND, byval idButton as long ) as boolean
function DisableButton( byval hToolbar as HWND, byval idButton as long ) as boolean

Enables or disables the button with command identifier idButton. A disabled button is drawn greyed (from the disabled image list, if there is one) and cannot be clicked.

Returns true on success.

Example

ToolBar.DisableButton( hCtrl, 1003 )
ToolBar.EnableButton( hCtrl, 1003 )

Microsoft Learn: TB_ENABLEBUTTON

HideButton, UnhideButton

function HideButton overload( byval hToolbar as HWND, byval idButton as long, byval fShow as short ) as boolean
function HideButton overload( byval hToolbar as HWND, byval idButton as long ) as boolean
function UnhideButton( byval hToolbar as HWND, byval idButton as long ) as boolean

Hides or shows the button with command identifier idButton; the buttons to its right close the gap. Despite its name, fShow hides the button when nonzero and shows it when 0, as the message does; the form without it hides.

Returns true on success.

Example

ToolBar.HideButton( hCtrl, 1003 )
ToolBar.UnhideButton( hCtrl, 1003 )

Microsoft Learn: TB_HIDEBUTTON

PressButton, ReleaseButton

function PressButton overload( byval hToolbar as HWND, byval idButton as long, byval fPress as short ) as boolean
function PressButton overload( byval hToolbar as HWND, byval idButton as long ) as boolean
function ReleaseButton( byval hToolbar as HWND, byval idButton as long ) as boolean

Draws the button with command identifier idButton pressed or released, without sending a command. The form with fPress presses for nonzero and releases for 0.

Returns true on success, false when there is no such button.

Example

ToolBar.PressButton( hCtrl, 1001 )
ToolBar.ReleaseButton( hCtrl, 1001 )

Microsoft Learn: TB_PRESSBUTTON

MarkButton, HighlightButton, UnhighlightButton

function MarkButton( byval hToolbar as HWND, byval idButton as long, byval fHighlight as short ) as boolean
function HighlightButton( byval hToolbar as HWND, byval idButton as long ) as boolean
function UnhighlightButton( byval hToolbar as HWND, byval idButton as long ) as boolean

Sets (fHighlight nonzero) or clears the highlight of the button with command identifier idButton: the TBSTATE_MARKED state, drawn in the highlight colour. HighlightButton and UnhighlightButton are MarkButton with fHighlight set and clear.

Returns true on success.

Example

ToolBar.MarkButton( hCtrl, 1002, CTRUE )
ToolBar.UnhighlightButton( hCtrl, 1002 )
ToolBar.HighlightButton( hCtrl, 1003 )

Microsoft Learn: TB_MARKBUTTON

Indeterminate

function Indeterminate( byval hToolbar as HWND, byval idButton as long, byval fIndeterminate as short ) as boolean

Sets (fIndeterminate nonzero) or clears the indeterminate state of the button with command identifier idButton. An indeterminate button is drawn greyed but can still be clicked.

Returns true on success.

Example

ToolBar.Indeterminate( hCtrl, 1004, CTRUE )

Microsoft Learn: TB_INDETERMINATE

IsButtonChecked, IsButtonEnabled, IsButtonHidden, IsButtonHighlighted, IsButtonIndeterminate, IsButtonPressed

function IsButtonChecked( byval hToolbar as HWND, byval idButton as long ) as long
function IsButtonEnabled( byval hToolbar as HWND, byval idButton as long ) as long
function IsButtonHidden( byval hToolbar as HWND, byval idButton as long ) as long
function IsButtonHighlighted( byval hToolbar as HWND, byval idButton as long ) as long
function IsButtonIndeterminate( byval hToolbar as HWND, byval idButton as long ) as long
function IsButtonPressed( byval hToolbar as HWND, byval idButton as long ) as long

Each tests one state of the button with command identifier idButton.

Returns 0 when the state is off. When it is on, the value is the state's own TBSTATE_* flag, not 1: IsButtonEnabled returns 4 (TBSTATE_ENABLED), IsButtonHidden 8, IsButtonPressed 2, IsButtonIndeterminate 16, IsButtonHighlighted 128 and IsButtonChecked 1. Test them as true or false, not against 1.

Example

if ToolBar.IsButtonEnabled( hCtrl, 1003 ) andalso ToolBar.IsButtonHidden( hCtrl, 1003 ) = 0 then print "1003 can be clicked"
print ToolBar.IsButtonChecked( hCtrl, 1004 ) <> 0; ToolBar.IsButtonPressed( hCtrl, 1004 ) <> 0
print ToolBar.IsButtonHighlighted( hCtrl, 1004 ) <> 0; ToolBar.IsButtonIndeterminate( hCtrl, 1004 ) <> 0

Microsoft Learn: TB_ISBUTTONENABLED

GetState

function GetState( byval hToolbar as HWND, byval idButton as long ) as DWORD

Returns the TBSTATE_* flags of the button with command identifier idButton (TBSTATE_ENABLED, TBSTATE_CHECKED, TBSTATE_PRESSED, TBSTATE_HIDDEN, TBSTATE_INDETERMINATE, TBSTATE_MARKED, TBSTATE_WRAP …): 5 for a checked, enabled button. For a button that does not exist the message returns -1, which arrives here as &hFFFFFFFF.

Example

if ToolBar.GetState( hCtrl, 1004 ) and TBSTATE_CHECKED then print "checked"

Microsoft Learn: TB_GETSTATE

SetState

function SetState( byval hToolbar as HWND, byval idButton as long, byval fState as short ) as boolean

Replaces all the state flags of the button with command identifier idButton with fState. Leave out TBSTATE_ENABLED and the button is disabled.

Returns true on success.

Example

ToolBar.SetState( hCtrl, 1004, TBSTATE_ENABLED or TBSTATE_CHECKED )

Microsoft Learn: TB_SETSTATE

GetButtonText

function GetButtonText overload( byval hToolbar as HWND, byval idButton as long, byval pBuffer as wstring ptr ) as long
function GetButtonText overload( byval hToolbar as HWND, byval idButton as long ) as ustring

Reads the text the button with command identifier idButton shows. The first form copies it into pBuffer, which must be big enough: the control does not know its size, so ask GetButtonTextLength first and allow one more character for the terminating null.

The second form returns a ustring, or "" for a button without text.

Returns the length of the text in characters, or -1 when the button has no text (first form); the text, or an empty string on failure (second form).

Example

dim s as ustring = ToolBar.GetButtonText( hToolbar, 1001 )
print s

Microsoft Learn: TB_GETBUTTONTEXT

GetButtonTextLength

function GetButtonTextLength( byval hToolbar as HWND, byval idButton as long ) as long

Returns the length in characters of the text of the button with command identifier idButton, without the terminating null, or -1 when it has no text.

Example

dim n as long = ToolBar.GetButtonTextLength( hCtrl, 1001 )
dim buf as wstring * 260
if n > 0 andalso n < 260 then ToolBar.GetButtonText( hCtrl, 1001, @buf )

Microsoft Learn: TB_GETBUTTONTEXT

AddString

function AddString( byval hToolbar as HWND, byval hInst as HINSTANCE, byval idString as INT_PTR ) as long

Adds strings to the toolbar's string pool, from which TBBUTTON.iString can take a button's text by number. With hInst NULL, idString is the address of the strings themselves: one or more wide strings one after the other, the last followed by a second null. Otherwise idString is the identifier of a string resource in the module hInst.

Returns the pool index of the first new string, or -1 on failure.

Example

dim pool as wstring * 32 = "Alpha"   ' the rest of the buffer is nulls
dim i as long = ToolBar.AddString( hCtrl, NULL, cast( INT_PTR, @pool ) )

Microsoft Learn: TB_ADDSTRING

GetString

function GetString( byval hToolbar as HWND, byval iString as short, byval pBuffer as wstring ptr, byval cchMax as short ) as long

Copies string number iString of the string pool into pBuffer, which holds cchMax characters.

Returns the length of the string, or -1 on failure.

Example

dim buf as wstring * 64
if ToolBar.GetString( hCtrl, 0, @buf, 64 ) >= 0 then MessageBoxW( hwnd, buf, "String 0", MB_OK )

Microsoft Learn: TB_GETSTRING

MapAccelerator

function MapAccelerator overload( byval hToolbar as HWND, byval chAccel as DWORD, byval pIDBtn as DWORD ptr ) as boolean
function MapAccelerator overload( byval hToolbar as HWND, byval chAccel as DWORD, byref IDBtn as DWORD ) as boolean
function MapAccelerator overload( byval hToolbar as HWND, byval chAccel as DWORD ) as DWORD

Finds the button whose text has chAccel as its accelerator: the letter after &, or the first letter when the text has no &. Upper and lower case match alike. The character is sent with the ANSI form of the message, so letters outside ASCII may not be found.

Returns true when a button matches, with its command identifier stored in pIDBtn / IDBtn (first two forms); the command identifier, or 0 when no button matches (third form).

Example

dim id as DWORD = ToolBar.MapAccelerator( hCtrl, asc( "o" ) )
if id then SendMessageW( hwnd, WM_COMMAND, id, 0 )

Microsoft Learn: TB_MAPACCELERATOR

SetMaxTextRows

function SetMaxTextRows( byval hToolbar as HWND, byval iMaxRows as long ) as boolean

Sets how many lines of text a button may show; longer text is cut. 0 shows no text at all, leaving the text for tooltips.

Returns true on success.

Example

ToolBar.SetMaxTextRows( hCtrl, 2 )

Microsoft Learn: TB_SETMAXTEXTROWS

GetTextRows

function GetTextRows( byval hToolbar as HWND ) as DWORD

Returns the largest number of text lines a button may show, as set by SetMaxTextRows: 1 for a new toolbar, 2 after SetMaxTextRows( h, 2 ). (For the number of rows of buttons, use GetRows.)

Example

print "text lines per button:"; ToolBar.GetTextRows( hCtrl )

Microsoft Learn: TB_GETTEXTROWS

SetDrawTextFlags

function SetDrawTextFlags( byval hToolbar as HWND, byval dwMask as DWORD, byval dwDTFlags as DWORD ) as DWORD

Sets the DT_* flags the toolbar passes to DrawTextW for button text. Only the flags named in dwMask change, to their value in dwDTFlags.

Returns the previous flags.

Example

ToolBar.SetDrawTextFlags( hCtrl, DT_LEFT or DT_CENTER, DT_LEFT )   ' left-aligned text

Microsoft Learn: TB_SETDRAWTEXTFLAGS

LoadImages

function LoadImages overload( byval hToolbar as HWND, byval iBitmapID as DWORD, byval hinst as HINSTANCE ) as long
function LoadImages overload( byval hToolbar as HWND, byval iBitmapID as DWORD ) as long

Adds one of the sets of standard images that come with Windows to the toolbar's normal image list, creating the list when there is none. The second form loads from the common controls (HINST_COMMCTRL), which is what you want. Sets: IDB_STD_SMALL_COLOR / IDB_STD_LARGE_COLOR (file and edit commands: STD_FILENEW, STD_FILEOPEN, STD_FILESAVE, STD_CUT, STD_COPY, STD_PASTE, STD_UNDO, STD_PRINT, STD_FIND …), IDB_VIEW_SMALL_COLOR / IDB_VIEW_LARGE_COLOR (VIEW_*) and IDB_HIST_SMALL_COLOR / IDB_HIST_LARGE_COLOR (HIST_*). The list created belongs to the toolbar.

Returns the number of images the list held before the call, which is the image number of the first image just loaded: 0 for the first set, 15 when a second set follows IDB_STD_SMALL_COLOR.

Example

ToolBar.LoadImages( hCtrl, IDB_STD_SMALL_COLOR )
ToolBar.AddButton( hCtrl, STD_UNDO, 1040 )

Microsoft Learn: TB_LOADIMAGES

AddBitmap

function AddBitmap overload( byval hToolbar as HWND, byval nButtons as DWORD, byval ptabm as TBADDBITMAP ptr ) as long
function AddBitmap overload( byval hToolbar as HWND, byval nButtons as DWORD, byref tabm as TBADDBITMAP ) as long

Adds nButtons images taken from one bitmap, cut into squares of the toolbar's image size (see SetBitmapSize). The TBADDBITMAP names the bitmap: hInst and a resource nID, or hInst NULL and an HBITMAP in nID. It does not mix with image lists set with SetImageList; use one way or the other.

Returns the image number of the first new image, or -1 on failure.

Example

dim tabm as TBADDBITMAP
tabm.hInst = HINST_COMMCTRL : tabm.nID = IDB_VIEW_SMALL_COLOR
dim first as long = ToolBar.AddBitmap( hCtrl, 12, tabm )

Microsoft Learn: TB_ADDBITMAP

ReplaceBitmap

function ReplaceBitmap overload( byval hToolbar as HWND, byval ptbrb as TBREPLACEBITMAP ptr ) as boolean
function ReplaceBitmap overload( byval hToolbar as HWND, byref tbrb as TBREPLACEBITMAP ) as boolean

Replaces the images that were added from one bitmap with AddBitmap by images from another. The TBREPLACEBITMAP names the old bitmap (hInstOld, nIDOld), the new one (hInstNew, nIDNew) and the number of images in the new one (nButtons).

Returns true on success.

Example

dim tbrb as TBREPLACEBITMAP
tbrb.hInstOld = HINST_COMMCTRL : tbrb.nIDOld = IDB_STD_SMALL_COLOR
tbrb.hInstNew = HINST_COMMCTRL : tbrb.nIDNew = IDB_STD_LARGE_COLOR : tbrb.nButtons = 15
ToolBar.ReplaceBitmap( hCtrl, tbrb )

Microsoft Learn: TB_REPLACEBITMAP

SetBitmapSize

function SetBitmapSize( byval hToolbar as HWND, byval dxBitmap as short, byval dyBitmap as short ) as boolean

Sets the width and height, in pixels, of the images the toolbar will be given, before any are added. The default is 16 × 15.

Returns true on success.

Example

ToolBar.SetBitmapSize( hCtrl, 24, 24 )

Microsoft Learn: TB_SETBITMAPSIZE

GetBitmapFlags

function GetBitmapFlags( byval hToolbar as HWND ) as DWORD

Returns TBBF_LARGE when the display calls for large (24 × 24) images, 0 for small (16 × 16) ones. The other bits are reserved.

Example

dim set as DWORD = iif( ToolBar.GetBitmapFlags( hCtrl ) and TBBF_LARGE, IDB_STD_LARGE_COLOR, IDB_STD_SMALL_COLOR )
ToolBar.LoadImages( hCtrl, set )

Microsoft Learn: TB_GETBITMAPFLAGS

GetBitmap

function GetBitmap( byval hToolbar as HWND, byval idButton as long ) as long

Returns the image number of the button with command identifier idButton, or 0 on failure.

Example

print "image"; ToolBar.GetBitmap( hCtrl, 1002 )

Microsoft Learn: TB_GETBITMAP

ChangeBitmap

function ChangeBitmap( byval hToolbar as HWND, byval idButton as long, byval iBitmap as WORD ) as boolean

Shows image iBitmap on the button with command identifier idButton.

Returns true on success.

Example

ToolBar.ChangeBitmap( hCtrl, 1004, STD_DELETE )

Microsoft Learn: TB_CHANGEBITMAP

GetImageList, SetImageList

function GetImageList( byval hToolbar as HWND ) as HIMAGELIST
function SetImageList( byval hToolbar as HWND, byval himlNew as HIMAGELIST ) as HIMAGELIST

Read or replace the image list for buttons in their normal state; it also stands in for the hot, disabled and pressed lists when those are not set. The toolbar does not destroy a list you set: destroy the old one that SetImageList returns, and your own list when the window closes.

Returns the image list, or NULL when there is none (GetImageList); the previous image list, or NULL (SetImageList).

Example

dim himl as HIMAGELIST = ImageList_Create( 24, 24, ILC_COLOR32 or ILC_MASK, 4, 0 )
dim hOld as HIMAGELIST = ToolBar.SetImageList( hCtrl, himl )
if hOld then ImageList_Destroy( hOld )
print ToolBar.GetImageList( hCtrl ) = himl

Microsoft Learn: TB_SETIMAGELIST

GetHotImageList, SetHotImageList

function GetHotImageList( byval hToolbar as HWND ) as HIMAGELIST
function SetHotImageList( byval hToolbar as HWND, byval himlNewHot as HIMAGELIST ) as HIMAGELIST

Read or replace the image list for the hot button, the one under the mouse in a flat toolbar. The same list may be given as the normal and the hot list.

Returns the image list, or NULL (GetHotImageList); the previous one, or NULL (SetHotImageList).

Example

ToolBar.SetHotImageList( hCtrl, ToolBar.GetImageList( hCtrl ) )
print ToolBar.GetHotImageList( hCtrl ) <> NULL

Microsoft Learn: TB_SETHOTIMAGELIST

GetDisabledImageList, SetDisabledImageList

function GetDisabledImageList( byval hToolbar as HWND ) as HIMAGELIST
function SetDisabledImageList( byval hToolbar as HWND, byval himlNewDisabled as HIMAGELIST ) as HIMAGELIST

Read or replace the image list for disabled buttons. Without one, the toolbar greys the normal image itself.

Returns the image list, or NULL (GetDisabledImageList); the previous one, or NULL (SetDisabledImageList).

Example

dim himlGrey as HIMAGELIST = ImageList_Create( 16, 16, ILC_COLOR32 or ILC_MASK, 4, 0 )
ToolBar.SetDisabledImageList( hCtrl, himlGrey )
print ToolBar.GetDisabledImageList( hCtrl ) = himlGrey

Microsoft Learn: TB_SETDISABLEDIMAGELIST

SetPressedImageList

function SetPressedImageList( byval hToolbar as HWND, byval iImageID as DWORD, byval himlNew as HIMAGELIST ) as HIMAGELIST

Sets the image list for buttons while they are pressed. iImageID is the number of the image list (0 unless you use several).

Returns the previous image list, or NULL.

Example

dim himlDown as HIMAGELIST = ImageList_Create( 16, 16, ILC_COLOR32 or ILC_MASK, 4, 0 )
ToolBar.SetPressedImageList( hCtrl, 0, himlDown )

Microsoft Learn: TB_SETPRESSEDIMAGELIST

GetImageListCount

function GetImageListCount( byval hToolbar as HWND ) as long

Returns the number of normal image lists the toolbar has.

Example

print ToolBar.GetImageListCount( hCtrl ); " image lists"

Microsoft Learn: TB_GETIMAGELISTCOUNT

GetButtonSize, GetButtonWidth, GetButtonHeight

function GetButtonSize( byval hToolbar as HWND ) as DWORD
function GetButtonWidth( byval hToolbar as HWND ) as DWORD
function GetButtonHeight( byval hToolbar as HWND ) as DWORD

Return the size of the toolbar's buttons in pixels. GetButtonSize packs both, the width in the low word and the height in the high word; the other two return one each. The height is what a rebar band holding the toolbar needs (see Rebar).

Returns the size.

Example

dim sz as DWORD = ToolBar.GetButtonSize( hCtrl )
print LOWORD( sz ); " x"; HIWORD( sz )
print ToolBar.GetButtonWidth( hCtrl ); " x"; ToolBar.GetButtonHeight( hCtrl )

Microsoft Learn: TB_GETBUTTONSIZE

SetButtonSize

function SetButtonSize( byval hToolbar as HWND, byval dxButton as short, byval dyButton as short ) as boolean

Sets the size of the buttons, in pixels. The toolbar does not make a button smaller than its image and text need. Call AutoSize afterwards.

Returns true on success.

Example

ToolBar.SetButtonSize( hCtrl, 40, 36 )
ToolBar.AutoSize( hCtrl )

Microsoft Learn: TB_SETBUTTONSIZE

SetButtonWidth

function SetButtonWidth( byval hToolbar as HWND, byval cxMin as short, byval cxMax as short ) as boolean

Sets the smallest and largest width, in pixels, of buttons sized to their text.

Returns true on success.

Example

ToolBar.SetButtonWidth( hCtrl, 60, 120 )

Microsoft Learn: TB_SETBUTTONWIDTH

GetItemRect

function GetItemRect overload( byval hToolbar as HWND, byval nButton as long, byval prc as RECT ptr ) as boolean
function GetItemRect overload( byval hToolbar as HWND, byval nButton as long, byref rc as RECT ) as boolean
function GetItemRect overload( byval hToolbar as HWND, byval nButton as long ) as ( long, long, long, long )

Reads the rectangle of the button or separator at index nButton, in client coordinates of the toolbar. A hidden button has no rectangle. The third form returns ( left, top, right, bottom ) and leaves the message's result in GetLastError(): nonzero on success, 0 on failure.

Returns true on success (first two forms); the four edges (third form).

Example

var (l, t, r, b) = ToolBar.GetItemRect( hCtrl, 0 )
if GetLastError() then print "first button:"; r - l; " x"; b - t

Microsoft Learn: TB_GETITEMRECT

GetRect

function GetRect overload( byval hToolbar as HWND, byval iID as long, byval prc as RECT ptr ) as boolean
function GetRect overload( byval hToolbar as HWND, byval iID as long, byref rc as RECT ) as boolean
function GetRect overload( byval hToolbar as HWND, byval iID as long ) as ( long, long, long, long )

Reads the rectangle of the button with command identifier iID, in client coordinates of the toolbar. The third form returns ( left, top, right, bottom ) and leaves the result in GetLastError(): nonzero on success. Map it to the screen to drop a menu below a BTNS_DROPDOWN button.

Returns true on success (first two forms); the four edges (third form).

Example

dim rc as RECT
if ToolBar.GetRect( hCtrl, 1002, rc ) then MapWindowPoints( hCtrl, HWND_DESKTOP, cast( POINT ptr, @rc ), 2 )

Microsoft Learn: TB_GETRECT

GetMaxSize

function GetMaxSize overload( byval hToolbar as HWND, byval psize as SIZE ptr ) as boolean
function GetMaxSize overload( byval hToolbar as HWND, byref sz as SIZE ) as boolean
function GetMaxSize overload( byval hToolbar as HWND ) as ( long, long )

Reads the width and height that all the visible buttons and separators take up together: the size a toolbar needs to show them all, for example as the ideal width of a rebar band. The third form returns ( cx, cy ) and leaves the result in GetLastError(): nonzero on success.

Returns true on success (first two forms); the size (third form).

Example

var (cx, cy) = ToolBar.GetMaxSize( hCtrl )
if GetLastError() then print "all buttons:"; cx; " x"; cy

Microsoft Learn: TB_GETMAXSIZE

GetPadding, GetHorizontalPadding, GetVerticalPadding

function GetPadding( byval hToolbar as HWND ) as DWORD
function GetHorizontalPadding( byval hToolbar as HWND ) as DWORD
function GetVerticalPadding( byval hToolbar as HWND ) as DWORD

Return the padding, in pixels, between a button's edge and its image and text. GetPadding packs both, horizontal in the low word and vertical in the high word.

Returns the padding.

Example

print "padding"; ToolBar.GetHorizontalPadding( hCtrl ); ","; ToolBar.GetVerticalPadding( hCtrl )
print hex( ToolBar.GetPadding( hCtrl ) )

Microsoft Learn: TB_GETPADDING

SetPadding

function SetPadding( byval hToolbar as HWND, byval cx as short, byval cy as short ) as DWORD

Sets the horizontal and vertical padding inside buttons, in pixels.

Returns the previous padding, horizontal in the low word and vertical in the high word.

Example

ToolBar.SetPadding( hCtrl, 10, 6 )
ToolBar.AutoSize( hCtrl )

Microsoft Learn: TB_SETPADDING

GetMetrics

sub GetMetrics overload( byval hToolbar as HWND, byval ptbMetrics as TBMETRICS ptr )
sub GetMetrics overload( byval hToolbar as HWND, byref tbMet as TBMETRICS )
function GetMetrics overload( byval hToolbar as HWND ) as TBMETRICS

Reads the padding and spacing values that dwMask asks for (TBMF_PAD, TBMF_BARPAD, TBMF_BUTTONSPACING) into a TBMETRICS; cbSize is set for you. Needs version 6 of the common controls. The third form sends a structure whose dwMask is 0, so nothing is asked for and only cbSize comes back set; use one of the first two.

Example

dim tbm as TBMETRICS
tbm.dwMask = TBMF_PAD or TBMF_BUTTONSPACING
ToolBar.GetMetrics( hCtrl, tbm )
print "spacing"; tbm.cxButtonSpacing

Microsoft Learn: TB_GETMETRICS

SetMetrics

sub SetMetrics overload( byval hToolbar as HWND, byval ptbMetrics as TBMETRICS ptr )
sub SetMetrics overload( byval hToolbar as HWND, byref tbMet as TBMETRICS )

Sets the padding and spacing values that dwMask names. Unlike GetMetrics it does not fill in cbSize: set it to sizeof( TBMETRICS ) yourself.

Example

dim tbm as TBMETRICS
tbm.cbSize = sizeof( tbm ) : tbm.dwMask = TBMF_BUTTONSPACING : tbm.cxButtonSpacing = 6
ToolBar.SetMetrics( hCtrl, tbm )

Microsoft Learn: TB_SETMETRICS

SetIndent

function SetIndent( byval hToolbar as HWND, byval iIndent as long ) as boolean

Sets the space, in pixels, before the first button.

Returns true on success.

Example

ToolBar.SetIndent( hCtrl, 8 )

Microsoft Learn: TB_SETINDENT

SetListGap

sub SetListGap( byval hToolbar as HWND, byval gap as DWORD )

Sets the distance, in pixels, between buttons of a toolbar with TBSTYLE_LIST (text to the right of the image). Needs version 6 of the common controls.

Example

ToolBar.SetListGap( hCtrl, 12 )

Microsoft Learn: TB_SETLISTGAP

GetRows

function GetRows( byval hToolbar as HWND ) as DWORD

Returns the number of rows of buttons in a toolbar with TBSTYLE_WRAPABLE; 1 for a toolbar on one line.

Example

print ToolBar.GetRows( hCtrl ); " rows"

Microsoft Learn: TB_GETROWS

SetRows

sub SetRows overload( byval hToolbar as HWND, byval cRows as WORD, byval fLarger as boolean, byval prc as RECT ptr )
sub SetRows overload( byval hToolbar as HWND, byval cRows as WORD, byval fLarger as boolean, byref rc as RECT )

Lays the buttons out in cRows rows. When that number cannot be made, fLarger true takes the next larger number of rows and false the next smaller. The toolbar's new rectangle comes back in prc / rc.

Example

dim rc as RECT
ToolBar.SetRows( hCtrl, 2, true, rc )

Microsoft Learn: TB_SETROWS

HitTest

function HitTest overload( byval hToolbar as HWND, byval pptHitTest as POINT ptr ) as long
function HitTest overload( byval hToolbar as HWND, byref ptHitTest as POINT ) as long
function HitTest overload( byval hToolbar as HWND ) as POINT

Finds the button under a point given in client coordinates of the toolbar.

The third form tests the point (0, 0) and returns that point, not the result of the test; it is of no use, so pass a point to one of the first two.

Returns the index of the button (not separator) under the point when it is 0 or more. A negative value means the point is on no button; its absolute value is then the index of the separator it is on or of the nearest button.

Example

dim pt as POINT
GetCursorPos( @pt ) : ScreenToClient( hCtrl, @pt )
dim i as long = ToolBar.HitTest( hCtrl, pt )
if i >= 0 then print "over button"; i

Microsoft Learn: TB_HITTEST

GetHotItem

function GetHotItem( byval hToolbar as HWND ) as DWORD

Returns the index of the hot button: the one under the mouse, or picked with the arrow keys. When no button is hot the message's -1 arrives as a DWORD, &hFFFFFFFF (4294967295): test for that, or convert with cast( long, ... ) and test for -1.

Example

dim i as long = cast( long, ToolBar.GetHotItem( hCtrl ) )
if i <> -1 then print "hot button:"; i

Microsoft Learn: TB_GETHOTITEM

SetHotItem

function SetHotItem( byval hToolbar as HWND, byval iHot as long ) as long

Makes the button at index iHot hot; -1 makes none hot. Has effect only on a flat toolbar.

Returns the index of the previous hot button, or -1 when there was none.

Example

ToolBar.SetHotItem( hCtrl, 0 )

Microsoft Learn: TB_SETHOTITEM

GetAnchorHighlight

function GetAnchorHighlight( byval hToolbar as HWND ) as boolean

Returns true when anchor highlighting is on: the hot button then stays hot when the mouse leaves the toolbar, until another becomes hot. It is off in a new toolbar.

Example

print "anchored:"; ToolBar.GetAnchorHighlight( hCtrl )

Microsoft Learn: TB_GETANCHORHIGHLIGHT

SetAnchorHighlight

function SetAnchorHighlight( byval hToolbar as HWND, byval fAnchor as boolean ) as boolean

Turns anchor highlighting on (true) or off.

Returns the previous setting.

Example

ToolBar.SetAnchorHighlight( hCtrl, true )

Microsoft Learn: TB_SETANCHORHIGHLIGHT

GetInsertMark

function GetInsertMark overload( byval hToolbar as HWND, byval ptbim as TBINSERTMARK ptr ) as long
function GetInsertMark overload( byval hToolbar as HWND, byref tbim as TBINSERTMARK ) as long
function GetInsertMark overload( byval hToolbar as HWND ) as TBINSERTMARK

Reads the insertion mark, the line a toolbar can show between buttons while one is dragged: the index of the button it is next to (iButton, -1 for none) and dwFlags (TBIMHT_AFTER when it is on the button's right).

Returns always true (first two forms); the mark (third form).

Example

dim tbim as TBINSERTMARK = ToolBar.GetInsertMark( hCtrl )
if tbim.iButton >= 0 then print "mark at button"; tbim.iButton

Microsoft Learn: TB_GETINSERTMARK

SetInsertMark

sub SetInsertMark overload( byval hToolbar as HWND, byval ptbim as TBINSERTMARK ptr )
sub SetInsertMark overload( byval hToolbar as HWND, byref tbim as TBINSERTMARK )

Shows the insertion mark next to button iButton (to its right with TBIMHT_AFTER in dwFlags), or removes it when iButton is -1.

Example

dim tbim as TBINSERTMARK
tbim.iButton = 1 : tbim.dwFlags = TBIMHT_AFTER
ToolBar.SetInsertMark( hCtrl, tbim )

Microsoft Learn: TB_SETINSERTMARK

GetInsertMarkColor

function GetInsertMarkColor( byval hToolbar as HWND ) as COLORREF

Returns the colour the insertion mark is drawn in.

Example

print hex( ToolBar.GetInsertMarkColor( hCtrl ) )

Microsoft Learn: TB_GETINSERTMARKCOLOR

SetInsertMarkColor

function SetInsertMarkColor( byval hToolbar as HWND, byval clrInsertMark as COLORREF ) as COLORREF

Returns the previous colour.

Example

SendMessageW( hCtrl, TB_SETINSERTMARKCOLOR, 0, RGB_RED )

Microsoft Learn: TB_SETINSERTMARKCOLOR

InsertMarkHitTest

function InsertMarkHitTest overload( byval hToolbar as HWND, byval ppt as POINT ptr, byval ptbim as TBINSERTMARK ptr ) as boolean
function InsertMarkHitTest overload( byval hToolbar as HWND, byref pt as POINT, byval tbim as TBINSERTMARK ) as boolean

Works out where the insertion mark belongs for a point in client coordinates of the toolbar, as a TBINSERTMARK ready for SetInsertMark. The second form takes the TBINSERTMARK by value: the control fills in a copy, and the structure you pass is not changed. Use the first form, with pointers.

Returns true when the point is on a button, false when it is not (the mark then goes to the nearest one).

Example

dim pt as POINT = ( 30, 10 )
dim tbim as TBINSERTMARK
ToolBar.InsertMarkHitTest( hCtrl, @pt, @tbim )
ToolBar.SetInsertMark( hCtrl, tbim )

Microsoft Learn: TB_INSERTMARKHITTEST

GetStyle

function GetStyle( byval hToolbar as HWND ) as DWORD

Returns the toolbar's styles: window, common-control (CCS_*) and toolbar (TBSTYLE_FLAT, TBSTYLE_LIST, TBSTYLE_TOOLTIPS, TBSTYLE_WRAPABLE, TBSTYLE_TRANSPARENT …) together.

Example

if ToolBar.GetStyle( hCtrl ) and TBSTYLE_FLAT then print "flat"

Microsoft Learn: TB_GETSTYLE

SetStyle

sub SetStyle( byval hToolbar as HWND, byval dwStyle as DWORD )

Replaces the toolbar's styles with dwStyle. Start from GetStyle to change one.

Example

ToolBar.SetStyle( hCtrl, ToolBar.GetStyle( hCtrl ) or TBSTYLE_LIST )
ToolBar.AutoSize( hCtrl )

Microsoft Learn: TB_SETSTYLE

GetExtendedStyle

function GetExtendedStyle( byval hToolbar as HWND ) as DWORD

Returns the extended toolbar styles (TBSTYLE_EX_DRAWDDARROWS, TBSTYLE_EX_MIXEDBUTTONS, TBSTYLE_EX_HIDECLIPPEDBUTTONS, TBSTYLE_EX_DOUBLEBUFFER …); 0 for a new toolbar. These are not the WS_EX_* window styles.

Example

print hex( ToolBar.GetExtendedStyle( hCtrl ) )

Microsoft Learn: TB_GETEXTENDEDSTYLE

SetExtendedStyle

function SetExtendedStyle( byval hToolbar as HWND, byval dwExStyle as DWORD ) as DWORD

Replaces the extended toolbar styles with dwExStyle. TBSTYLE_EX_DRAWDDARROWS gives BTNS_DROPDOWN buttons a separate arrow; TBSTYLE_EX_MIXEDBUTTONS shows text only on buttons with BTNS_SHOWTEXT and uses the rest as tooltips.

Returns the previous extended styles.

Example

ToolBar.SetExtendedStyle( hCtrl, ToolBar.GetExtendedStyle( hCtrl ) or TBSTYLE_EX_DRAWDDARROWS )

Microsoft Learn: TB_SETEXTENDEDSTYLE

MakeOpaque

sub MakeOpaque( byval hToolbar as HWND )

Removes TBSTYLE_TRANSPARENT from the toolbar's window style, so that it paints its own background instead of letting the parent's show through. It changes the style bits only; call InvalidateRect to repaint.

Example

ToolBar.MakeOpaque( hCtrl )
InvalidateRect( hCtrl, NULL, CTRUE )

Microsoft Learn: Toolbar control and button styles

GetColorScheme

function GetColorScheme overload( byval hToolbar as HWND, byval pcs as COLORSCHEME ptr ) as boolean
function GetColorScheme overload( byval hToolbar as HWND, byref cs as COLORSCHEME ) as boolean
function GetColorScheme overload( byval hToolbar as HWND ) as COLORSCHEME

Reads the colours the toolbar draws button highlights and shadows with (clrBtnHighlight, clrBtnShadow); dwSize is set for you. CLR_DEFAULT means the system colour. The first form returns false for a NULL pointer.

Returns true on success (first two forms); the colours (third form).

Example

dim cs as COLORSCHEME = ToolBar.GetColorScheme( hCtrl )
if cs.clrBtnHighlight = CLR_DEFAULT then print "system highlight colour"

Microsoft Learn: TB_GETCOLORSCHEME

SetColorScheme

sub SetColorScheme overload( byval hToolbar as HWND, byval pcs as COLORSCHEME ptr )
sub SetColorScheme overload( byval hToolbar as HWND, byref cs as COLORSCHEME )

Sets the highlight and shadow colours. Unlike GetColorScheme it does not fill in dwSize: set it to sizeof( COLORSCHEME ) yourself.

Example

dim cs as COLORSCHEME
cs.dwSize = sizeof( cs ) : cs.clrBtnHighlight = RGB_WHITE : cs.clrBtnShadow = RGB_GRAY
ToolBar.SetColorScheme( hCtrl, cs )

Microsoft Learn: TB_SETCOLORSCHEME

SetWindowTheme

sub SetWindowTheme( byval hToolbar as HWND, byval pwszTheme as wstring ptr )

Example

SendMessageW( hCtrl, TB_SETWINDOWTHEME, 0, cast( LPARAM, @wstr( "Explorer" ) ) )

Microsoft Learn: TB_SETWINDOWTHEME

SetDarkMode, RemoveDarkMode

function SetDarkMode( byval hToolbar as HWND ) as HRESULT
function RemoveDarkMode( byval hToolbar as HWND ) as HRESULT

SetDarkMode gives the toolbar the dark theme of Explorer's information pane (DarkMode_InfoPaneToolbar); RemoveDarkMode gives it back its normal visual style. Use them with a window in dark mode, see Dark mode.

Returns S_OK on success, or an error code.

Example

if AppsUseDarkMode() then ToolBar.SetDarkMode( hCtrl ) else ToolBar.RemoveDarkMode( hCtrl )

Microsoft Learn: SetWindowTheme

GetTooltips

function GetTooltips( byval hToolbar as HWND ) as HWND

Returns the tooltip control of the toolbar, or NULL when it has none. A toolbar with TBSTYLE_TOOLTIPS (the CWindow.AddControl default) makes its own; its tooltips ask the parent for their text with TTN_GETDISPINFOW, whose hdr.hwndFrom is this handle.

Example

dim hTip as HWND = ToolBar.GetTooltips( hCtrl )
if hTip then SendMessageW( hTip, TTM_SETMAXTIPWIDTH, 0, 300 )

Microsoft Learn: TB_GETTOOLTIPS

SetToolTips

sub SetToolTips( byval hToolbar as HWND, byval hwndToolTip as HWND )

Gives the toolbar the tooltip control hwndToolTip to use instead of its own.

Example

dim hTip as HWND = CreateWindowExW( 0, TOOLTIPS_CLASSW, NULL, TTS_ALWAYSTIP, 0, 0, 0, 0, hwnd, NULL, NULL, NULL )
ToolBar.SetToolTips( hCtrl, hTip )

Microsoft Learn: TB_SETTOOLTIPS

SetParent

function SetParent( byval hToolbar as HWND, byval hwndParent as HWND ) as HWND

Sets the window that receives the toolbar's WM_COMMAND and WM_NOTIFY messages. The toolbar's parent window, and where it is drawn, stay as they are.

Returns the previous notification window, or NULL.

Example

ToolBar.SetParent( hCtrl, hwnd )

Microsoft Learn: TB_SETPARENT

Customize

sub Customize( byval hToolbar as HWND )

Opens the Customize Toolbar dialog, in which the user adds, removes and reorders buttons. The toolbar needs CCS_ADJUSTABLE, and the parent must answer the TBN_QUERYINSERT, TBN_QUERYDELETE and TBN_GETBUTTONINFOW notifications. The call returns when the dialog closes.

Example

ToolBar.Customize( hCtrl )

Microsoft Learn: TB_CUSTOMIZE

SaveRestore

sub SaveRestore overload( byval hToolbar as HWND, byval fSave as long, byval ptbsp as TBSAVEPARAMSW ptr )
sub SaveRestore overload( byval hToolbar as HWND, byval fSave as long, byref tbsp as TBSAVEPARAMSW )

Saves the toolbar's buttons to a registry value (fSave nonzero) or rebuilds them from it (0). The TBSAVEPARAMSW names the key (hkr, pszSubKey) and the value (pszValueName).

Example

dim tbsp as TBSAVEPARAMSW
tbsp.hkr = HKEY_CURRENT_USER : tbsp.pszSubKey = @wstr( "Software\MyApp" ) : tbsp.pszValueName = @wstr( "Toolbar" )
ToolBar.SaveRestore( hCtrl, CTRUE, tbsp )

Microsoft Learn: TB_SAVERESTORE

GetObject

function GetObject( byval hToolbar as HWND ) as IDropTarget ptr

Meant to return the toolbar's IDropTarget, the interface it uses when something is dragged over it. As written it gives the control a null address to store the pointer in, and the program stops with an access violation. Send the message yourself, with the address of your pointer, as in the example; release the interface when done.

Returns nothing usable: the call does not come back.

Example

dim iid as GUID = ( &h00000122, &h0000, &h0000, { &hC0, 0, 0, 0, 0, 0, 0, &h46 } )   ' IID_IDropTarget
dim pDropTarget as IDropTarget ptr
if SendMessageW( hCtrl, TB_GETOBJECT, cast( WPARAM, @iid ), cast( LPARAM, @pDropTarget ) ) = S_OK then pDropTarget->lpVtbl->Release( pDropTarget )

Microsoft Learn: TB_GETOBJECT