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

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |----------------------------------------------------|------------------------------------|-----------|--------| | `AllowAutoDeactivate` | `Boolean` | | | | `AllowTabStop` | `Boolean` | | | | `Enabled` | `Boolean` | | | | `Handle` | `Integer` | ✓ | | | `Height` | `Integer` | | | | `Name` | `String` | ✓ | | | `Parent` | `Control` | | | | `Tooltip` | `String` | | | | `Transparent` | `Boolean` | | | | `TrueWindow` | `Window` | ✓ | | | `Visible` | `Boolean` | | | | `Width` | `Integer` | | | | `Window` | `Window` | ✓ | | ## Methods

table-centered_column_4

| 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

table-centered_column_4

| Name | Parameters | Returns | |--------------------------------------------------|-----------------------------------------------------------------------------------------------------|---------| | `Action` | item As `ToolItem` | | | `Close` | | | | `DropDownMenuAction` | item As `ToolbarItem`, hitItem As `MenuItem` | | | `Open` | | | ## Property descriptions

forsearch

Toolbar.AllowAutoDeactivate **AllowAutoDeactivate** As `Boolean` Determines whether the control should be deactivated (on macOS) when the parent window is deactivated. The default is `True`.

forsearch

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: ``` xojo Me.AllowTabStop = False ```

forsearch

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. ``` xojo Me.Enabled = False ```

forsearch

Toolbar.Handle **Handle** As `Integer` Returns a handle to the control. This property is read-only. For interfacing with Mac APIs using `` 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. ``` xojo Var i As Integer = Me.Handle ```

forsearch

Toolbar.Height **Height** As `Integer` The height (in points) of the control. This example sets the height of the control to 100: ``` xojo Me.Height = 100 ```

forsearch

Toolbar.Name **Name** As `String` The name of the control. Set the name of the control in the Inspector. This property is read-only.

forsearch

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. ``` xojo Me.Parent = Nil ```

forsearch

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. ``` xojo Me.CaptionAlignment = 0 ' left Me.CaptionDelta = 10 Me.Tooltip = "Click to bark." Me.Icon = Woof ' added to the project Me.CaptionPosition = 2 ```

forsearch

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.

forsearch

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`. ``` xojo TextField1.Text = Me.TrueWindow.Title ```

forsearch

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: ``` xojo ListBox1.Value = Me.Visible ```

forsearch

Toolbar.Width **Width** As `Integer` The width (in points) of the control. The following example resizes the control: ``` xojo Me.Width = 200 ```

forsearch

Toolbar.Window **Window** As `Window` The control's parent window. This property is read-only. This code gets the parent window's Title property. ``` xojo TextField1.Text = Me.Window.Title ``` ## Method descriptions

forsearch

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. ``` xojo 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: ``` xojo If Not obj.FolderItem.IsFolder Then Return True ```

forsearch

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: ``` xojo 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: ``` xojo Me.AcceptPictureDrop ``` Canvas.DropObject: ``` xojo If obj.PictureAvailable Then Me.Backdrop = obj.Picture End If ```

forsearch

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. ``` xojo Me.AcceptRawDataDrop("????") ```

forsearch

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. ``` xojo Me.AcceptTextDrop ```

forsearch

Toolbar.AddButton **AddButton**(button As `ToolbarItem`) Adds the passed `ToolbarItem` as the last element of the Toolbar.

forsearch

Toolbar.AddButtonAt **AddButtonAt**(index As `Integer`, button As `ToolbarItem`) Inserts the passed `ToolbarItem` in the position indicated by *Index*.

forsearch

Toolbar.ButtonAt **ButtonAt**(index As `Integer`) As `ToolbarItem` Returns the `ToolbarItem` specified by *Index*.

forsearch

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. ``` xojo Me.Close ```

forsearch

Toolbar.Count **Count** As `Integer` The number of ToolItems in the Toolbar.

forsearch

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: ``` xojo Var p As New Picture(Me.Width, Me.Height) Me.DrawInto(p.Graphics, 0, 0) Canvas1.Backdrop = p ```

forsearch

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`. ``` xojo Me.Invalidate(False) ```

forsearch

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: ``` xojo Me.Refresh(False) ``` Refresh a portion of the area: ``` xojo Me.Refresh(100, 150, 200, 300) ```

forsearch

Toolbar.RemoveButtonAt **RemoveButtonAt**(index As `Integer`) Removes the passed item from the Toolbar.

forsearch

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. ``` xojo TextField1.SetFocus ``` ## Event descriptions

forsearch

Toolbar.Action **Action**(item As `ToolItem`) The passed item was clicked.

forsearch

Toolbar.Close **Close** The control is about to close.

forsearch

Toolbar.DropDownMenuAction **DropDownMenuAction**(item As `ToolbarItem`, hitItem As `MenuItem`) The passed `ToolbarItem` was chosen from the passed `MenuItem`.

forsearch

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. ``` xojo 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: ``` xojo SaveButton As ToolbarButton OpenButton As ToolbarButton ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following code is in the `Open` event of the Toolbar instance in the window. ``` xojo 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: ``` xojo 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.