LLToolBar
Objectives
The LLToolbar class implements a generic toolbar widget that displays a series of LLToolBarButton widgets in either a horizontal or vertical orientation.
Currently, LLToolBar is tightly coupled to the LLCommandManager system.
Design
Layout
The wrap attribute will enable button wrapping which will stack the buttons if they run out of allotted space. As a result, the width of a horizontal toolbar will be the same as specified in XUI, but the height will be derived from the requested button height as specified in the LLToolBarButton parameter desired_height and whatever degree of wrapping has taken place. For vertical toolbars, the width is set by the widest button in each column, and the height is the value specified in XUI. In code, the term "length" refers to the primary axis of the toolbar itself (width for horizontal toolbars, height for vertical) and "girth" refers to the opposite dimension.
Toolbar buttons appear centered within the toolbar extents. This is currently not controllable via XUI.
Button widths are constrained by the button_width.min and button_width.max attributes of LLToolBarButton. If a button's natural width is greater than button_width.max, the button will show a truncated label with ellipsis and the tooltip for the button will include the full button label.
Layout is performed by the LLToolBar::updateLayoutAsNeeded method, which is triggered during the draw phase if any relevant change has been made to the toolbar contents (e.g. adding a button or switching button display modes) or overall dimensions of the toolbar. Any such change will set the mNeedsLayout flag which will be checked and cleared each frame.
Drag and Drop
A toolbar button can be dragged by clicking and dragging the button more than "DragAndDropDistanceThreshold" pixels. The button can be dropped within the same toolbar to move it, within any other toolbar to transfer it to that toolbar, or within the "Toolbar Buttons" window to remove it.
Toolbar Button Display State
By right clicking on a toolbar, the user can choose from a context menu how toolbar buttons are displayed. The current options are "Image only" and "Image and text". The display of those buttons are managed by the button_icon and button_icon_and_text parameters of LLToolbar, respectively.
Readonly toolbars cannot be used to trigger commands. They simply exist as a storage area for toolbar buttons that can be dragged to other, active, toolbars. For example, the toolbar in the "TOOLBAR BUTTONS" window is set to readonly as it exists simply to show all available toolbar buttons. Readonly toolbars can be set via the XUI read_only attribute and return true from the isReadOnly method.
Command Management
Buttons are added to a toolbar by specifying the relevant Command via a LLCommandID (essentially a command name). LLToolBar::addCommand will add a button tied to the specified command. The button label, tooltip, and behavior will all be derived from the data specified in the command itself.
- NOTE: there is only ever one button associated with a given command in a single toolbar
Similarly, for debugging purposes, the default set of commands that appear in a toolbar can be specified via a command XUI parameter. For example:
<toolbar> <command name="doSomething"/> <command name="doSomethingElse"/> </toolbar>
Buttons can be removed via removeCommand by referencing the appropriate command id, or queried via hasCommand, enabled/disabled with enableCommand, etc. If you have a LLToolBarbutton, you can get the associated command id using getCommandId.
"Disabled" Buttons Hack
A single LLToolBarButton can be enabled or disabled using the standard LLView methods. In particular, if the command that the button is bound to returns false from its "is_enabled_function" then the button will be disabled. In order to allow for drag and drop of disabled buttons, we need to keep processing mouse events, which means we can't actually disable a toolbar button at the LLView level. Instead, we fake the disabled state by swapping the button art between its normal set and its disabled set, while leaving the button itself always enabled.