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.
Properties
Name |
Type |
Read-Only |
Shared |
|---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
|---|---|---|---|
FileType As String |
|||
Type As String |
|||
button As ToolbarItem |
|||
index As Integer, button As ToolbarItem |
|||
index As Integer |
|||
[EraseBackground As Boolean] |
|||
eraseBackground As Boolean |
|||
index As Integer |
|||
Events
Name |
Parameters |
Returns |
|---|---|---|
item As ToolItem |
||
item As ToolbarItem, hitItem As MenuItem |
||
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.