TbrButtons class
The collection of the buttons of a ToolBar, which its Buttons property returns. Its items are TbrButton objects, numbered from 1, and an item can have a key as well.
Dim Button As TbrButton
ToolBar1.Buttons.Add , "new", "New"
ToolBar1.Buttons.Add , "open", "Open"
ToolBar1.Buttons.Add 1, "save", "Save" ' before the first
For Each Button In ToolBar1.Buttons
Debug.Print Button.Index; Button.Key
Next
' Output:
' 1 save
' 2 new
' 3 open
A program goes through the buttons with For Each, or by number from 1 to Count. It cannot make a TbrButtons object with New.
Numbers and keys
The number of a button in the collection is its Index. It changes when a button is added before it or removed before it, so that a program that keeps a number over such a change keeps the wrong button. A key stays with its button.
A key is any string, and capital and small letters in it are the same: "Open" and "OPEN" are one key. No two buttons of a toolbar have the same key. A button needs no key: an empty string is no key, and any number of buttons can be without one.
The order of the collection is not the order on the toolbar. The user, or the program through Position, moves a button on the toolbar, and its Index does not change.
Properties
Count
The number of buttons in the collection. Long, read-only.
Item
Returns one button. It is the default member, so ToolBar1.Buttons("open") is ToolBar1.Buttons.Item("open").
Syntax: object.Item( Index ) As TbrButton
- Index
- required The number of the button, from 1 to Count, or its key as a String.
A number outside that range raises run-time error 9, and a key that no button has raises run-time error 5. Exists asks without an error.
Methods
Add
Puts a button on the toolbar and returns its TbrButton.
Syntax: object.Add( [ Index ] [, Key ] [, Caption ] [, Style ] [, Image ] ) As TbrButton
- Index
- optional A Long: the number the new button gets. The buttons from that number on move up by one, on the toolbar as well. Without it, or with 0, the button goes after the last one.
- Key
- optional A String by which the program can name the button. See Numbers and keys.
- Caption
- optional A String: the text of the button. An ampersand before a letter makes the letter the button’s mnemonic.
- Style
- optional A member of TbrButtonStyleConstants. Default: TbrButtonStyleDefault.
- Image
- optional A Variant: the number of a picture in the toolbar’s ImageList, or its key as a String.
A button added at an Index stands at that place on the toolbar as well as in the collection, and the later buttons move up in both.
An Index below 0, and one above Count + 1, raises run-time error 35600, Index out of bounds. A Key that another button has raises run-time error 457. A Style that is not a member raises error 380.
A key as Image needs an image list on the toolbar that has a picture of that key: where it has not, the call raises run-time error 35601, Element not found, and a negative number raises error 35600.
Warning 1.8.141.0
A call that raises error 457 for its key has already put its button on the toolbar. The collection is as it was, and the toolbar shows one button more than Count says, which no TbrButton reaches. A program asks Exists before it adds a button with a key that the toolbar may have.
Clear
Removes every button.
Syntax: object.Clear
Exists
Returns whether the collection has a button of a number or a key, so that a program can ask before Item raises an error.
Syntax: object.Exists( Index ) As Boolean
- Index
- required The number or the key to look for.
Remove
Removes one button. The buttons after it move down by one.
Syntax: object.Remove Index
- Index
- required The number or the key of the button. One that the collection does not have raises the error that Item raises for it.
A button object that the program kept, and that was removed, no longer belongs to the toolbar: reading its Position gives 0.
See Also
- ToolBar class
- TbrButton class – one button
- TbrButtonStyleConstants – the values of the Style argument of Add