Class

Toolbar (deprecated)


Warning

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

Description

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

Methods

Name

Parameters

Returns

Shared

AcceptFileDrop

FileType As String

AcceptPictureDrop

AcceptRawDataDrop

Type As String

AcceptTextDrop

AddButton

button As ToolbarItem

AddButtonAt

index As Integer, button As ToolbarItem

ButtonAt

index As Integer

ToolbarItem

Close

Count

Integer

DrawInto

g As Graphics, x As Integer, y As Integer

Invalidate

[EraseBackground As Boolean]

Refresh

eraseBackground As Boolean

RemoveButtonAt

index As Integer

SetFocus

Events

Name

Parameters

Returns

Action

item As ToolItem

Close

DropDownMenuAction

item As ToolbarItem, hitItem As MenuItem

Open

Property descriptions


Toolbar.AllowAutoDeactivate

AllowAutoDeactivate As Boolean

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


Toolbar.AllowTabStop

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

Toolbar.Enabled

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

Toolbar.Handle

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

Toolbar.Height

Height As Integer

The height (in points) of the control.

This example sets the height of the control to 100:

Me.Height = 100

Toolbar.Name

Name As String

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

This property is read-only.


Toolbar.Parent

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

Toolbar.Tooltip

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

Toolbar.Transparent

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.


Toolbar.TrueWindow

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

Toolbar.Visible

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

Toolbar.Width

Width As Integer

The width (in points) of the control.

The following example resizes the control:

Me.Width = 200

Toolbar.Window

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


Toolbar.AcceptFileDrop

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.

Me.AcceptPictureDrop
Me.AcceptFileDrop("image/jpeg")

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

Toolbar.AcceptPictureDrop

AcceptPictureDrop

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:

Me.AcceptPictureDrop

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.

Canvas.Open:

Me.AcceptPictureDrop

Canvas.DropObject:

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

Toolbar.AcceptRawDataDrop

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.

Me.AcceptRawDataDrop("????")

Toolbar.AcceptTextDrop

AcceptTextDrop

Permits text to be dropped on the control.

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

Me.AcceptTextDrop

Toolbar.AddButton

AddButton(button As ToolbarItem)

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


Toolbar.AddButtonAt

AddButtonAt(index As Integer, button As ToolbarItem)

Inserts the passed ToolbarItem in the position indicated by Index.


Toolbar.ButtonAt

ButtonAt(index As Integer) As ToolbarItem

Returns the ToolbarItem specified by Index.


Toolbar.Close

Close

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.

Me.Close

Toolbar.Count

Count As Integer

The number of ToolItems in the Toolbar.


Toolbar.DrawInto

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

Toolbar.Invalidate

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.

Me.Invalidate(False)

Toolbar.Refresh

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:

Me.Refresh(False)

Refresh a portion of the area:

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

Toolbar.RemoveButtonAt

RemoveButtonAt(index As Integer)

Removes the passed item from the Toolbar.


Toolbar.SetFocus

SetFocus

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.

TextField1.SetFocus

Event descriptions


Toolbar.Action

Action(item As ToolItem)

The passed item was clicked.


Toolbar.Close

Close

The control is about to close.


Toolbar.DropDownMenuAction

DropDownMenuAction(item As ToolbarItem, hitItem As MenuItem)

The passed ToolbarItem was chosen from the passed MenuItem.


Toolbar.Open

Open

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()
  Me.AcceptPictureDrop
  Me.AcceptFileDrop("JPEG")
End Sub

Notes

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.

Note

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.

Warning

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
Me.AddButton(OpenButton)
Me.AddButton(SaveButton)

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

Compatibility

All project types on all supported operating systems.

See also

RectControl parent class; ToolbarButton, ToolbarItem classes.