TTBToolbar

Properties | Events | Methods

Description:

This is the toolbar component. To add/edit/delete items on a toolbar, double-click it in the form designer to invoke the Item Editor. (See the Getting Started page for instructions on creating docks and toolbars.)

In addition to Toolbar2000's built-in "items," regular controls may also be placed at the top level of a TTBToolbar. Simply drop them on a toolbar the same way you would any other control. Note, however, that there are several limitations of using controls instead of items on a toolbar. For example, controls will not be displayed in a chevron popup menu.

Remarks:

When the CloseButton property is True (the default), the toolbar can hide itself if the user clicks the close button on a floating toolbar. Because of this, you should always include an item on a menu that toggles the Visible property so the user can get it back if it is closed. See the demo application source code for an example of this.

While toolbars are typically placed on docks, it is not required. When placed outside of a dock, toolbars will not display a drag handle or border. To get an undocked toolbar to wrap or display a chevron, you must do at least one of the following: set AutoResize to False, set Align to one of [alTop, alBottom, alClient], or add [akLeft, akRight] to Anchors.

At run-time, any new items/controls created on a TTBToolbar are initially positioned at the end of the toolbar. To change positions of individual items/controls at run-time, call toolbar.Items.Move.

Key Properties:

• property ActivateParent: Boolean default True; Determines whether the parent form is activated when a floating toolbar is clicked.
• property AutoResize: Boolean default True;
  Determines whether the toolbar will automatically adjust its width and height when items are added/deleted/changed. However, if Anchors includes both akLeft and akRight then it will not change the toolbar's width, and if Anchors includes both akTop and akBottom it will not change the height. This property is not applicable to docked or floating toolbars.
• property BorderStyle: TBorderStyle default bsSingle;
  When set to bsSingle, the toolbar has a 3-D border.
• property Caption;
  What appears in the title bar of a floating toolbar.
• property ChevronHint: string;
  The hint displayed when the mouse is moved over the toolbar's chevron (). This defaults to the value of STBChevronItemMoreButtonsHint in TB2Consts.pas.
• property ChevronMoveItems: Boolean default True;
  Normally, when an item on the toolbar's chevron popup menu () is clicked, the clicked item will move into the visible area of the toolbar in place of the least recently clicked item. This behavior is consistent with Office 2000 and XP. Setting this property to False will disable it.
• property ChevronPriorityForNewItems: TTBChevronPriorityForNewItems default tbcpHighest;
  TTBChevronPriorityForNewItems = (tbcpHighest, tbcpLowest);
  If set to tbcpHighest, items created at run-time are given the "highest priority", meaning items that were created previously are hidden first (as they have lower priority). Setting this to tbcpLowest gives the opposite behavior: items created at run-time will be hidden first.
• property CloseButton: Boolean default True;
  When True, a close button appears in the title bar when the toolbar is floating.
• property CloseButtonWhenDocked: Boolean default False;
  When True, a close button is displayed when the toolbar is docked.
• property CurrentDock: TTBDock;
  The TTBDock control that the toolbar is currently docked to. To move the toolbar to another dock, you can assign to this property any TTBDock control on the form. To make a toolbar floating at run time, assign to the Floating property.
• property DefaultDock: TTBDock;
  (Note: The LastDock property is meant to supersede this property.)
  The default dock location. This is used when the user double-clicks a floating toolbar. If neither this property nor LastDock are set, nothing will happen.
• property DockableTo: TTBDockableTo default [dpTop, dpBottom, dpLeft, dpRight];
  TTBDockableTo = set of (dpTop, dpBottom, dpLeft, dpRight);
  Specifies which positions the toolbar may be docked at.
• property DockMode: TTBDockMode;
  TTBDockMode = (dmCanFloat, dmCannotFloat, dmCannotFloatOrChangeDocks);
  Determines where the user can drag the toolbar. If this is dmCanFloat, the default, the toolbar can float or dock to any dock matching the criteria set by DockableTo. If this is dmCannotFloat, the toolbar can dock to the same docks but it cannot float. If the user moves the mouse outside a dock, the "Unavailable" mouse cursor is displayed. Also, the toolbar does not respond to double-clicks. If this is dmCannotFloatOrChangeDocks, the user cannot drag the toolbar anywhere outside its current dock.
• property DockPos: Integer;
  This is only valid if the toolbar is currently docked (CurrentDock <> nil). This is its current horizontal (or vertical, if docked to a left or right dock) position in pixels.
• property DockRow: Integer;
  This is only valid if the toolbar is currently docked (CurrentDock <> nil). This is the row the toolbar is currently docked at.
• property DragHandleStyle: TTBDragHandleStyle default dhDouble;
  TTBDragHandleStyle = (dhDouble, dhNone, dhSingle);
  Determines the type of drag handle displayed on the left (or top, when docked vertically) of the toolbar.
• property Floating: Boolean;
  Run-time only. This property is True if the toolbar is currently in a floating state. If it is not True, setting it to True will make it floating.
• property FloatingMode: TTBFloatingMode;
  TTBFloatingMode = (fmOnTopOfParentForm, fmOnTopOfAllForms);
  By default, this is set to fmOnTopOfParentForm, meaning when floating the toolbar only stays on top of its parent form. If this is set to fmOnTopOfAllForms, the toolbar will stay above all other forms in the project (except those that are also set to stay on top).
• property FloatingPosition: TPoint;
  Run-time only. The X,Y coordinates the toolbar appears at when it is in a floating state (Floating = True).
• property FloatingWidth: Integer;
  The desired X coordinate at which the toolbar wraps its items when it is in a floating state (Floating = True).
• property FullSize: Boolean default False;
  When True, the toolbar always fills the entire width (or height, if vertically docked) of the dock, much like Office's menu bar.
• property HideWhenInactive: Boolean default True;
  When True, the toolbar is hidden whenever the application is deactivated (a characteristic of Office's toolbars).
• property LastDock: TTBDock;
  The TTBDock control that the toolbar was last docked to, or if the toolbar is currently docked and not being dragged, this is equal to the CurrentDock property. Double-clicking a floating toolbar will restore it back to the dock specified by this property, and at the same position it previously was docked at. This property overrides and is meant to be a replacement for DefaultDock. If you want to disable the use of this property, set UseLastDock to False.
• property MenuBar: Boolean default False;
  When True, the toolbar will act like a menu bar. The MenuBar property itself is used for determining how Alt keypresses are handled, and if accelerator keys may be hidden. Also, for convenience, changing the MenuBar property automatically sets the FullSize and ShrinkMode properties. When MenuBar is set to True, FullSize will be set to True, ShrinkMode will be set to tbsmWrap, CloseButton will be set to False, and ProcessShortCuts will be set to True. This emulates the look and behavior of Office's menu bars.
• property ProcessShortCuts: Boolean default False;
  When True, shortcut keys specified by the items' ShortCut properties will be processed when the owning form is enabled.
• property ShowCaption: Boolean default True;
  When True, the toolbar displays a caption bar and a close button (if CloseButton is True) when floating.
• property ShrinkMode: TTBShrinkMode default tbsmChevron;
  TTBShrinkMode = (tbsmNone, tbsmWrap, tbsmChevron);
  Determines how the toolbar will "shrink" when it is too wide to fit on a horizontal dock, or too tall to fit on a vertical dock. tbsmNone prevents the toolbar from being shrunk. tbsmWrap causes the toolbar's items to wrap into multiple rows when all items cannot fit on a single row. tbsmChevron displays a chevron () at the end of the toolbar when all items cannot fit. Clicking the chevron causes a popup menu to be shown which displays the invisible items.
• property SmoothDrag: Boolean default True;
  When True, the toolbar's position will be constantly updated while the toolbar is being dragged, like Office 2000. When False, a rectangle will be displayed while the toolbar is being dragged, and the actual toolbar will only move once the mouse button released.
• property Stretch: Boolean default False;
  When True, the toolbar, when docked, will stretch to fill any unused space on the row. This creates a TCoolBar-like effect.
  Note: If you wish to use an aligned (Align <> alNone) or anchored control inside a toolbar, you will need to use TTBToolWindow, since TTBToolbar does not support aligned/anchored controls.
• property SystemFont: Boolean default True;
  When True, the toolbar will use the menu font set in Windows' Display Properties for its font, instead of the font specified by the Font property.
• property UpdateActions: Boolean default True;
  When True, Actions associated with the toolbar's top-level items will have their Update methods called every time the application becomes idle. This behavior is consistent with other VCL controls, like TToolBar. However, the calls to Update can waste much CPU time if you have a lot of items with associated Actions, so it may make sense to change this property to False if that is a concern.
• property UseLastDock: Boolean default True;
  When True, the toolbar saves the last dock it was docked to in the property LastDock, and internally preserves the position it was docked at. See the description of LastDock for more information.
• property View: TTBView;
  Run-time only. The TTBView component that the toolbar uses to render items on the screen.

Events:

• property OnClose: TNotifyEvent;
  Occurs after the toolbar is hidden in response to the user clicking the toolbar's Close button, or the application calling the Close method.
• property OnCloseQuery: TCloseQueryEvent;
  TCloseQueryEvent = procedure(Sender: TObject; var CanClose: Boolean) of object;
  Same in function as a form's OnCloseQuery event. Setting CanClose to False will cancel the requested close operation.
• property OnDockChanged: TNotifyEvent;
  Occurs after the toolbar has changed between docks, or from a docked to floating state or vice versa.
• property OnDockChanging: TTBDockChangingEvent;
  TTBDockChangingEvent = procedure(Sender: TObject; Floating: Boolean; DockingTo: TTBDock) of object;
  Occurs immediately before the toolbar changes between docks, or from a docked to floating state or vice versa. Floating specifies whether the toolbar is about to go into a floating state. If Floating is False, DockingTo specifies where the toolbar is about to dock to.
• property OnDockChangingHidden: TTBDockChangingEvent;
  TTBDockChangingEvent = procedure(Sender: TObject; Floating: Boolean; DockingTo: TTBDock) of object;
  Similar to the OnDockChanging event, but this event is called after the toolbar has already been hidden from the screen in preparation to be moved to another dock. This can be useful if, for example, you want to make changes in the ordering of the toolbar's controls whenever it moves between docks, but don't want any visible flickering during this time.
• property OnMove: TNotifyEvent;
  Occurs each time the toolbar moves. Note that when SmoothDrag is True, the event is fired repeatedly as the toolbar is dragged.
• property OnRecreated: TNotifyEvent;
  Occurs immediately after the toolbar recreates itself. This usually happens when it changes between a docked and non-docked state.
• property OnRecreating: TNotifyEvent;
  Occurs immediately before the toolbar recreates itself. This usually happens when it changes between a docked and non-docked state.
• property OnResize: TNotifyEvent;
  Occurs after the toolbar's size changes. Note that this event is fired after any size change, not only when the user resizes a floating toolbar.
• property OnVisibleChanged: TNotifyEvent;
  Occurs after the toolbar's visibility changes. This event will occur if the application manually changes the visibility of the toolbar (e.g., by toggling the Visible property), or if the user closes the toolbar using its Close button.

Key Methods:

• procedure AddDockForm (const Form: TCustomForm);
  Adds a form to the list of forms that the toolbar can be docked to besides the current parent's parent form. Keep in mind that moving a toolbar to another form does not change its Owner property; therefore it will still be destroyed when its owner component is destroyed. To change a toolbar's owner, use TComponent's RemoveComponent and InsertComponent methods.
• procedure BeginMoving (const InitX, InitY: Integer);
  TTBSizeHandle = (twshLeft, twshRight, twshTop, twshTopLeft, twshTopRight, twshBottom, twshBottomLeft, twshBottomRight);
  Forces the toolbar to enter "move" mode. This is called internally whenever the user clicks the drag handle of a docked toolbar or the caption bar of a floating toolbar, and will only work properly if it is called while the left mouse button is still down. The InitX and InitY parameters specify the client coordinates where the mouse button went down at, which determine where the dragging rectangle appears initially. In most cases (0, 0) should be fine.
• procedure BeginSizing (const ASizeHandle: TToolWindowSizeHandle);
  TTBSizeHandle = (twshLeft, twshRight, twshTop, twshTopLeft, twshTopRight, twshBottom, twshBottomLeft, twshBottomRight);
  Forces the toolbar to enter "size" mode. This is called internally whenever the user clicks one of the resizing handles on the border of a floating toolbar, and will only work properly if it is called while the left mouse button is still down. The ASizeHandle parameter specifies which resizing handle was clicked.
• procedure BeginUpdate;
  Disables arrangement of items/controls on the toolbar. You may call this when moving multiple items/controls on the toolbar to reduce flicker. Once the changes are complete, call EndUpdate.
• procedure EndUpdate;
  Re-enables item/control arrangement after a call to BeginUpdate.
• procedure RemoveDockForm (const Form: TCustomForm);
  Removes a form from the list of forms AddDockForm adds to.