XUITabBar
Inherits DesktopCanvas
Description
XUITabBar is a beautiful, flexible and powerful UI control. It provides an easy-to-use
implementation of a source list. Source lists are a familiar UI control typically used as a
navigation sidebar in applications. Examples are the sidebar in the Finder on macOS and the
navigator in the Xojo IDE.
XUITabBar abstracts away a lot of the complexity of managing a navigation sidebar so you don't
have to worry about it.
The control supports drag reordering, unlimited item depths, badge counts, custom widgets and more.
Properties
Methods
| Name | Parameters | Returns |
|---|---|---|
| AddTabAt | index As Integer, caption As String, icon As Picture, tag As Variant, closable As Boolean, enabled As Boolean |
|
| AppendTab | caption As String, icon As Picture, tag As Variant, closable As Boolean, enabled As Boolean |
|
| Constructor | ||
| OverCloseIconAtIndex | index As Integer |
Boolean |
| OverLeftMenuButton | x As Integer, y As Integer |
Boolean |
| OverRightMenuButton | x As Integer, y As Integer |
Boolean |
| PageLeft | ||
| PageRight | ||
| PopTab | XUITabBarItem |
|
| RemoveAll | ||
| RemoveTabAt | index As Integer |
|
| ReplaceTabAt | index As Integer, newTab As XUITabBarItem |
|
| SelectTabAtIndex | index As Integer |
|
| SwapTabs | index1 As Integer, index2 As Integer, shouldRedraw As Boolean |
|
| TabIndexAtXY | x As Integer, y As Integer, excludeSelected As Boolean |
Integer |
| Tabs | XUITabBarItem() |
|
| ValidTabIndex | index As Integer |
Boolean |
Events
| Name | Parameters | Returns |
|---|---|---|
| DidAddTab | tab As XUITabBarItem, index As Integer |
|
| DidContextualClickLeftMenuButton | x As Integer, y As Integer |
|
| DidContextualClickRightMenuButton | x As Integer, y As Integer |
|
| DidContextualClickTab | tab As XUITabBarItem, x As Integer, y As Integer |
|
| DidFinishDragging | tab As XUITabBarItem, index As Integer |
|
| DidRemoveTab | tab As XUITabBarItem |
|
| DidSelectTab | tab As XUITabBarItem, index As Integer |
|
| DidStartDragging | tab As XUITabBarItem, index As Integer |
|
| MouseExit | ||
| MouseMove | x As Integer, y As Integer |
|
| MouseWheel | x As Integer, y As Integer, deltaX As Integer, deltaY As Integer |
|
| PressedLeftMenuButton | ||
| PressedRightMenuButton |
Constants
| Name | Type |
|---|---|
| DRAG_SCROLL_THRESHOLD | Double |
| DRAG_THRESHOLD_DISTANCE | Double |
| DRAG_THRESHOLD_TICKS | Double |
DRAG_SCROLL_THRESHOLD As Double The number of pixels from the edge when dragging that the mouse needs to be within to scroll the tab bar.
DRAG_THRESHOLD_DISTANCE As Double The number of pixels difference between the current mouse position and the last to trigger a drag operation.
DRAG_THRESHOLD_TICKS As Double The number of ticks that must have elapsed between the last drag operation to trigger another drag.
Property Descriptions
AllowDragReordering As Boolean
True if tabs can be reordered by dragging with the mouse.
AvailableTabSpace As Double
The width available to render tabs, factoring in the presence or absence of the optional menu buttons.
DraggingTabLeftEdgeXOffset As Integer
The offset from the left edge of the tab that's being dragged.
HasLeftBorder As Boolean
True if the tab bar should draw a left border on the left-most tab.
HasLeftMenuButton As Boolean
If True and the (renderer suports it) then a menu button will be drawn to the left of the tab bar.
HasRightBorder As Boolean
True if the tab bar should draw a right border on the right-most tab.
HasRightMenuButton As Boolean
If True and the (renderer suports it) then a menu button will be drawn to the right of the tab bar.
IsDraggingTab As Boolean
True if a tab is currently being dragged.
LeftMenuButtonBounds As Rect
The bounds of the left menu button (if enabled). Set by the renderer. May be Nil.
LeftMenuButtonIcon As Picture
If the left menu button is enabled, this is the icon to use.
mDraggingTabLeftEdgeXOffset As Integer
The offset from the left edge of the tab that's being dragged.
mDragIndex As Integer
When dragging a tab, this is the index being dragged to.
mHasLeftMenuButton As Boolean
If True and the (renderer suports it) then a menu button will be drawn to the left of the tab bar.
mHasRightMenuButton As Boolean
If True and the (renderer suports it) then a menu button will be drawn to the right of the tab bar.
mIsDraggingTab As Boolean
True if a tab is currently being dragged.
mLastClickWasContextual As Boolean
True if the mouse click that just occurred in the MouseDown event was a contextual click.
mLeftMenuButtonIcon As Picture
If the left menu button is enabled, this is the icon to use.
mMouseDownIndex As Integer
The index of the tab under the mouse during the last MouseDown event. -1 if there wasn't one.
mMouseDownTicks As Double
The ticks when the last MouseDown event occurred.
mMouseDownX As Integer
The X coordinate of the last MouseDown event.
mMouseDownY As Integer
The Y coordinate of the last MouseDown event.
mMouseDragX As Integer
The X coordinate in the last MouseDrag event.
mMouseDragY As Integer
The Y coordinate in the last MouseDrag event.
mMouseMoveX As Integer
The X value during the last MouseMove event. Set to -1 if the mouse leaves the tab bar.
mMouseMoveY As Integer
The Y value during the last MouseMove event. Set to -1 if the mouse leaves the tab bar.
mMouseOverIndex As Integer
The index of the tab that the mouse is currently over or -1 if not over one.
mMouseOverLeftMenuButton As Boolean
Cached computation ofOverLeftMenuButton computed in MouseMove().
mMouseOverRightMenuButton As Boolean
Cached computation ofOverRightMenuButton computed in MouseMove().
mNeedsFullRedraw As Boolean
True if the tab bar needs a full redraw during its next Paint() event.
MouseDragX As Integer
The X coordinate in the last MouseDrag event. Read only.
MouseDragY As Integer
The Y coordinate in the last MouseDrag event. Read only.
MouseMoveX As Integer
The X value during the last MouseMove event. Set to -1 if the mouse leaves the tab bar.
MouseMoveY As Integer
The Y value during the last MouseMove event. Set to -1 if the mouse leaves the tab bar.
mPaintLeft As Integer
The left of the control during the last Paint event.
mPaintTop As Integer
The top of the control during the last Paint event.
mPaintWidth As Integer
The width of the control during the last Paint event.
mRenderer As XUITabBarRenderer
The renderer to use for the tab bar.
mRightMenuButtonIcon As Picture
If the right menu button is enabled, this is the icon to use.
mScaleX As Double
Cached value of g.ScaleX from the last Paint event.
mScrollPosX As Integer
The horizontal scroll offset. 0 is baseline. Positive indicates scrolling to the right. Backs the ScrollPosX computed property.
mSelectedTabIndex As Integer
The index of the currently selected tab.
mStyle As XUITabBarStyle
The colour style to use for the tab bar.
mTabs() As XUITabBarItem
This tab bar's items.
Renderer As XUITabBarRenderer
The renderer to use for the tab bar.
RightMenuButtonBounds As Rect
The bounds of the right menu button (if enabled). Set by the renderer. May be Nil.
RightMenuButtonIcon As Picture
If the right menu button is enabled, this is the icon to use.
ScrollPosX As Integer
The horizontal scroll offset. 0 is baseline. Positive indicates scrolling to the right.
SelectedTab As XUITabBarItem
The currently selected tab. May be Nil.
SelectedTabIndex As Integer
The index of the currently selected tab. Read only. Use SelectTabAtIndex to select a tab.
Style As XUITabBarStyle
The colour style to use for the tab bar.
TabCount As Integer
The number of tabs in the tab bar.
Method Descriptions
AddTabAt(index As Integer, caption As String, icon As Picture, tag As Variant, closable As Boolean, enabled As Boolean)
Adds a new tab at the 0-based index.
Will raise an OutOfBoundsException if index is invalid.
AppendTab(caption As String, icon As Picture, tag As Variant, closable As Boolean, enabled As Boolean)
Appends a new tab to this tab bar.
Constructor()
Default constructor.
OverCloseIconAtIndex(index As Integer) As Boolean
True if the mouse is over the close icon of the tab at index.
OverLeftMenuButton(x As Integer, y As Integer) As Boolean
True if x, y is over the left menu button.
x is the absolute coordinate from the left edge of the tab bar. It does not account for any
scrolling of the tab bar.
y is the absolute coordinate from the top left edge of the tab bar.
OverRightMenuButton(x As Integer, y As Integer) As Boolean
True if x, y is over the right menu button.
x is the absolute coordinate from the left edge of the tab bar. It does not account for any
scrolling of the tab bar.
y is the absolute coordinate from the top left edge of the tab bar.
PageLeft()
Moves the selected tab to the tab to the left of the currently selected tab, wrapping round to the right-most tab if paging from the left-most tab.
PageRight()
Moves the selected tab to the tab to the right of the currently selected tab, wrapping around to the first tab if on the right-most tab presently.
PopTab() As XUITabBarItem
Pops the right-most tab off of the tab bar and returns it. May return Nil if there are no tabs.
RemoveAll()
Removes all tabs, starting from the right-most tab.
RemoveTabAt(index As Integer)
Removes the tab at index.
Will raise an OutOfBoundsException if index is invalid
ReplaceTabAt(index As Integer, newTab As XUITabBarItem)
Replaces the tab at index with newTab and selects it.
Will raise an OutOfBoundsException if index is invalid.
SelectTabAtIndex(index As Integer)
Selects the tab at index.
Will raise an OutOfBoundsException if index is invalid.
SwapTabs(index1 As Integer, index2 As Integer, shouldRedraw As Boolean)
Swaps the tabs at the passed indices and redraws the tab bar.
TabIndexAtXY(x As Integer, y As Integer, excludeSelected As Boolean) As Integer
Returns the index of the tab at mouse position x, y or -1 if there isn't one.
xis the absolute coordinate from the left edge of the tab bar. It does not account for any scrolling of the tab bar.yis the absolute coordinate from the top left edge of the tab bar.- If
excludeSelectedthen we don't check the currently selected tab's bounds.
Tabs() As XUITabBarItem()
Returns the tab bar's tabs. This array should be considered read only. Do not modify it!
ValidTabIndex(index As Integer) As Boolean
Returns True if index is a valid tab index.
Event Descriptions
DidAddTab(tab As XUITabBarItem, index As Integer)
A tab was just added to the tab bar at index.
DidContextualClickLeftMenuButton(x As Integer, y As Integer) The user contexutal clicked (right clicked) over the left menu button at the passed coordinates. The coordinates are local to the top left corner of the tab bar.
DidContextualClickRightMenuButton(x As Integer, y As Integer) The user contexutal clicked (left clicked) over the left menu button at the passed coordinates. The coordinates are local to the top left corner of the tab bar.
DidContextualClickTab(tab As XUITabBarItem, x As Integer, y As Integer) The user contexutal clicked (right clicked) over a tab at the passed coordinates. The coordinates are local to the top left corner of the tab bar.
DidFinishDragging(tab As XUITabBarItem, index As Integer)
The user just finished dragging tab (which has a current index of index).
DidRemoveTab(tab As XUITabBarItem) A tab has just been removed from the tab bar.
DidSelectTab(tab As XUITabBarItem, index As Integer) The tab at the specified index was just selected.
DidStartDragging(tab As XUITabBarItem, index As Integer)
The user just began dragging tab (which has a current index of index).
MouseExit() The mouse has just exited the control.
MouseMove(x As Integer, y As Integer) The mouse has just moved within the control.
MouseWheel(x As Integer, y As Integer, deltaX As Integer, deltaY As Integer) The mouse scroll wheel has triggered over the control.
PressedLeftMenuButton() The user has just just pressed the left menu button.
PressedRightMenuButton() The user has just just pressed the right menu button.