Toolbar (deprecated)


This item was deprecated in version 2021r3. Please use DesktopToolbar as a replacement.


Used to create a Toolbar in a window. The Toolbar control is supported on all desktop platforms.







FileType As String



Type As String



button As ToolbarItem


index As Integer, button As ToolbarItem


index As Integer






g As Graphics, x As Integer, y As Integer


[EraseBackground As Boolean]


eraseBackground As Boolean


index As Integer







item As ToolItem



item As ToolbarItem, hitItem As MenuItem


Property descriptions


AllowAutoDeactivate As Boolean

Determines whether the control should be deactivated (on macOS) when the parent window is deactivated. The default is True.


AllowTabStop As Boolean

If True, the RectControl is in the Tab Order and accepts the focus when the user tabs into it. The default is True. If False, the user cannot tab into it to give it the focus. However, the RectControl can gain the focus by other means, such as the user's clicking on it or by setting the focus in code.

This example removes the control from the Tab Order:

Me.AllowTabStop = False


Enabled As Boolean

Determines if the control should be enabled when the owning window is opened.

A disabled control cannot be clicked and cannot receive the focus.

This example disables the control. Its caption is grayed out.

Me.Enabled = False


Handle As Integer

Returns a handle to the control.

This property is read-only.

For interfacing with Mac APIs using Declare</api/language/declare>`s, RectControl.Handle returns NSViews (except for `Toolbar).

On Windows returns the HWND of the control.

On Linux it returns a GtkWidget.

The following gets a handle to the control.

Var i As Integer = Me.Handle


Height As Integer

The height (in points) of the control.

This example sets the height of the control to 100:

Me.Height = 100


Name As String

The name of the control. Set the name of the control in the Inspector.

This property is read-only.


Parent As Control

Used to get and set the control's parent control or window.

Returns Nil if the parent is the window. Assign Nil to make the control's parent the window, even if it is enclosed by another control. The child control's behavior in the IDE will reflect the parent's state. If the parent control is somehow in another window, an InvalidParentException will occur.

The following example sets the parent of the control to the window.

Me.Parent = Nil


Tooltip As String

Text of help message displayed as a Windows or Linux "tooltip" or macOS help tag.

The tip/tag is displayed when the user hovers the mouse cursor over the control.

This example adds a tooltip to a BevelButton that has an icon.

Me.CaptionAlignment = 0 ' left
Me.CaptionDelta = 10
Me.Tooltip = "Click to bark."

Me.Icon = Woof ' added to the project
Me.CaptionPosition = 2


Transparent As Boolean

Determines whether the control is transparent on Windows. The default is False. Has no effect on macOS or Linux.

Transparent controls draw more slowly and use more memory in order to cache the background. Unless you absolutely require transparency, leave this set to False.

For projects that were created prior to 2018r1, this property defaults to True to emulate previous behavior. Consider changing it to False to improve performance if you do not require transparency.


TrueWindow As Window

Returns a reference to the actual enclosing Window.

This property is read-only.

TrueWindow walks up the window hierarchy and finds the actual enclosing window regardless of how deeply nested the RectControl or DesktopContainer hierarchy is.

Window also has a TrueWindow property.

This example accesses the TrueWindow and displays its Title property in a TextField.

TextField1.Text = Me.TrueWindow.Title


Visible As Boolean

Determines whether the control is visible when its owning window is opened. The default is True: the control is visible.

The following code in the DisclosureTriangle Action event handler displays or hides a ListBox on the window:

ListBox1.Value = Me.Visible


Width As Integer

The width (in points) of the control.

The following example resizes the control:

Me.Width = 200


Window As Window

The control's parent window.

This property is read-only.

This code gets the parent window's Title property.

TextField1.Text = Me.Window.Title

Method descriptions


AcceptFileDrop(FileType As String)

Permits documents of type FileType to be dropped on the control. FileType must be a file type that you defined in via the FileType class or the File Type Sets Editor.

This code in the Open event of an ImageWell makes it possible for the user to drop either a picture or a file that is a jpeg image. The File Type Sets editor was used to define the “image/jpeg” file type. It is one of the “Common File Types” that is available in the editor.


To restrict file drops to just folders (and not files), you can put this code in the DragEnter event:

If Not obj.FolderItem.IsFolder Then Return True



Permits pictures to be dropped on the control.

If a control should accept pictures in a drag and drop, then AcceptPictureDrop needs to be called prior to the drop. Typically, it is in the Open event of the control itself. For example, the line:


in the Open event of the control that will receive the dragged pictures is needed. When the picture is dropped, the DropObject event is called and this is where you will put your code to handle the drop.




If obj.PictureAvailable Then
  Me.Backdrop = obj.Picture
End If


AcceptRawDataDrop(Type As String)

Permits data (of the Type specified) to be dropped on the control.

The following specfies a generic file type defined in the File Type Sets editor.




Permits text to be dropped on the control.

This line in the Open event of a control that can accept dragged text.



AddButton(button As ToolbarItem)

Adds the passed ToolbarItem as the last element of the Toolbar.


AddButtonAt(index As Integer, button As ToolbarItem)

Inserts the passed ToolbarItem in the position indicated by Index.


ButtonAt(index As Integer) As ToolbarItem

Returns the ToolbarItem specified by Index.



Closes a control.

Closing a control permanently removes the control from memory, making it impossible to access. You can close both non-indexed controls and indexed controls. When you close an indexed control, the indexes for the remaining controls will shift downward so that the indexes start with zero and are consecutive.

The following code closes the control. When this is executed from a visible control, the control disappears from the window.



Count As Integer

The number of ToolItems in the Toolbar.


DrawInto(g As Graphics, x As Integer, y As Integer)

Draws the contents of the RectControl into the specified Graphics context. The parameters x and y are the coordinates of the top, left corner.

This method does not work with HTMLViewer and OpenGLSurface.

This example draws the current control into the Graphics of a Picture and then displays it as the Backdrop of a Canvas:

Var p As New Picture(Me.Width, Me.Height)
Me.DrawInto(p.Graphics, 0, 0)
Canvas1.Backdrop = p


Invalidate([EraseBackground As Boolean])

Similar to RefreshRect, but causes the specified region of the RectControl to be marked dirty and to be redrawn when the window contents need to be redrawn. The region to be redrawn is specified by the X, Y, Width, and Height parameters. This form of Invalidate was formerly called InvalidateRect.

The following code refreshes the control. EraseBackground defaults to True.



Refresh(eraseBackground As Boolean)

Repaints the portion specified of the contents of the control immediately.

Calling this frequently can cause the code executing to slow down. It is often preferable to call RectControl instead.

Refresh the entire area:


Refresh a portion of the area:

Me.Refresh(100, 150, 200, 300)


RemoveButtonAt(index As Integer)

Removes the passed item from the Toolbar.



If applicable, sets the focus to the RectControl. KeyDown events are directed to the control.

If the control cannot get the focus on the platform on which the application is running, SetFocus does nothing. The SetFocus method of the Window class or the ClearFocus method can be used to remove the focus from the control that currently has the focus, leaving no control with the focus.

On the Mac you need Full Keyboard Access turned on in System Preferences (Keyboard->Shortcuts) in order to manually set focus to non-text controls.

The following example sets the focus to TextField1. If another control has the focus when this line is executed, then the user sees that TextField1 gets the focus.


Event descriptions


Action(item As ToolItem)

The passed item was clicked.



The control is about to close.


DropDownMenuAction(item As ToolbarItem, hitItem As MenuItem)

The passed ToolbarItem was chosen from the passed MenuItem.



The control is about to be displayed. Use this event to initialize a control.

The Open event is called after the Constructor.

Be warned that initializing control property values using the Constructor instead of the Open event may result in those property values being overwritten by what is set in the Inspector. For best results, use the Open event for control initialization rather than the control Constructor.

If the control is supposed to handle drag and drop, you need to tell it which type of item it needs to be able to handle. The following example informs the control that pictures and files can be dropped on it. The type of the file it needs to support is specified via the File Types Editor.

Sub Open()
End Sub


A Toolbar object contains all the buttons in a Toolbar. You create the items in the Toolbar with the ToolbarButton class and add them to the Toolbar with the AddButton or AddButtonAt methods. An item can be either a button or a divider. A button can work as either a pushbutton or a toggle button.


For best results, you should ensure that all your Toolbar icons are the same size. Some platforms will size all icons to that of the icon on the first button in the Toolbar.


You can only have a single Toolbar on a Window.

Mouse events

Although Toolbar inherits from RectControl, it has no mouse-related events. This is due to limitations of the operating system.

Sample code

This example shows how to create a Toolbar via code. It builds a small Toolbar with Open and Save buttons. A Toolbar object was added to a window. The pictures that are displayed by the two buttons were added to the project.

The window has the following properties:

SaveButton As ToolbarButton
OpenButton As ToolbarButton

The following code is in the Open event of the Toolbar instance in the window.

SaveButton = New ToolbarButton
OpenButton = New ToolbarButton

SaveButton.Caption = "Save" ' Caption appears below the Icon
SaveButton.Name = "Save"
SaveButton.icon = SaveButtonImage ' image added to the project

OpenButton.Caption = "Open" ' Caption appears below the Icon
OpenButton.Name = "Open"
OpenButton.Icon = OpenButtonImage ' image added to the project
SaveButton.Style = ToolbarButton.ButtonStyles.PushButton
OpenButton.Style = ToolbarButton.ButtonStyles.PushButton

' add to the Toolbar

The following code is in the Action event of the Toolbar in the window:

Sub Action(item As ToolItem)
  Select Case item.Name
  Case "Open"
    MessageBox("You clicked the Open Button.")
  Case "Save"
    MessageBox("You clicked the Save Button.")
  End Select
End Sub


All project types on all supported operating systems.

See also

RectControl parent class; ToolbarButton, ToolbarItem classes.