Class JRibbon
- All Implemented Interfaces:
ImageObserver
,MenuContainer
,Serializable
The ribbon has the following major parts:
- Ribbon tasks added with
addTask(RibbonTask)
- Contextual ribbon task groups added with
addContextualTaskGroup(RibbonContextualTaskGroup)
- Application menu content set by
setApplicationMenuCommand(RibbonApplicationMenuCommandButtonProjection)
- Taskbar panel populated by
addTaskbarCommand(BaseCommandButtonProjection)
,addTaskbarGalleryDropdown(RibbonGalleryProjection)
andaddTaskbarComponent(ComponentProjection)
- Anchored content set by
addAnchoredCommand(CommandButtonProjection)
While multiple ribbon tasks can be added to the ribbon, only one is visible at any given time. This task is called the selected task. Tasks can be switched with the task buttons placed along the top part of the ribbon. Once a task has been added to the ribbon, it cannot be removed.
The contextual ribbon task groups allow showing and hiding ribbon tasks based on the current
selection in the application. For example, Word only shows the table tasks when a table is
selected in the document. By default, tasks belonging to the groups added by
addContextualTaskGroup(RibbonContextualTaskGroup)
are not visible. To show the tasks
belonging to the specific group, call setVisible(RibbonContextualTaskGroup, boolean)
API. Note that you can have multiple task groups visible at the same time.
The application menu button is a rectangular button shown in the top left corner of the ribbon.
If the setApplicationMenuCommand(RibbonApplicationMenuCommandButtonProjection)
is not
called,
or called with the null
value, the application menu button is not shown, and ribbon
task buttons are shifted to the left.
The taskbar panel allows showing controls that are visible no matter what ribbon task is
selected. To add content to taskbar, use the addTaskbarCommand(BaseCommandButtonProjection)
,
addTaskbarGalleryDropdown(RibbonGalleryProjection)
and
addTaskbarComponent(ComponentProjection)
APIs. The taskbar panel lives in the top-left
corner of the application frame.
The ribbon can be minimized in one of the following ways:
- Calling
setMinimized(boolean)
withtrue
. - User double-clicking on a task button.
- User pressing
Meta+Alt+R
key combination on a Mac machine orCtrl+F1
key combination on a non-Mac machine.
A minimized ribbon shows the application menu button, taskbar panel, task buttons and anchored contet, but not the ribbon bands of the selected task. Clicking a task button shows the ribbon bands of that task in a popup without shifting the application content down.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
static interface
private class
private class
JRibbon.TaskbarCommandHandler<M extends BaseCommand<MCM>,
MCM extends BaseCommandMenuContentModel, P extends BaseCommandButtonPresentationModel<MPM, P>, MPM extends BaseCommandPopupMenuPresentationModel> private class
JRibbon.TaskbarComponentHandler<C extends JComponent,
CCM extends ComponentContentModel> private static interface
JRibbon.TaskbarContentHandler<T extends ContentModel>
private class
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate ArrayList
<CommandButtonProjection> Commands anchored to the far edge of the task toggle strip (right under LTR and left under RTL).private RibbonApplicationMenuProjection
The application menu.private ArrayList
<AbstractRibbonBand> Bands of the currently shown task.private ArrayList
<RibbonContextualTaskGroup> The contextual task groups.private RibbonTask
Currently selected (shown) task.private Map
<RibbonContextualTaskGroup, Boolean> Visibility status of the contextual task group.private boolean
Indicates whether the ribbon is currently minimized.private JRibbonFrame
The host ribbon frame.The taskbar components (displayed between the application menu button and the frame title).private List
<JRibbon.TaskbarContentHandler<?>> private RibbonTaskbarKeyTipPolicy
private ArrayList
<RibbonTask> The general tasks.static final String
The UI class ID string.Fields inherited from class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
-
Constructor Summary
ConstructorsConstructorDescriptionJRibbon()
Creates a new empty ribbon.JRibbon
(JRibbonFrame ribbonFrame) Creates an empty ribbon for the specified ribbon frame. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addAnchoredCommand
(CommandButtonProjection projection) Adds the specified ribbon command projection to the trailing edge of the task toggle strip of this ribbon.void
Adds the specified change listener to track changes to this ribbon.void
Adds the specified contextual task group to this ribbon.void
void
addTask
(RibbonTask task) Adds the specified task to this ribbon.void
addTaskbarAppMenuLink
(Command appMenuCommand) <M extends BaseCommand<MCM>,
MCM extends BaseCommandMenuContentModel, P extends BaseCommandButtonPresentationModel<MPM, P>, MPM extends BaseCommandPopupMenuPresentationModel>
voidaddTaskbarCommand
(BaseCommandButtonProjection<M, MCM, P, MPM> projection) void
addTaskbarComponent
(ComponentProjection<? extends JComponent, ? extends ComponentContentModel> projection) void
addTaskbarGalleryDropdown
(RibbonGalleryProjection galleryProjection) void
Removes all taskbar content from this ribbon.protected void
Notifies all registered listeners that the state of this ribbon has changed.private void
Returns the anchored commands for this ribbon.Returns the application menu of this ribbon.getContextualTaskGroup
(int index) Retrieves contextual task group at specified index.int
Returns the number of contextual task groups inthis
ribbon.Returns the ribbon frame that hosts this ribbon.Returns the currently selected task.getTask
(int index) Retrieves the regular task at specified index.private JRibbon.TaskbarContentHandler
int
Returns the number of regular tasks inthis
ribbon.getUI()
Returns the UI delegate for this component.boolean
Returns the indication whether this ribbon is minimized.boolean
isShowingInTaskbar
(BaseCommand<?> command) boolean
isShowingInTaskbar
(RibbonGalleryContentModel galleryContentModel) boolean
isShowingInTaskbar
(ComponentContentModel componentContentModel) boolean
Returns the visibility of ribbon tasks in the specified contextual task group.private boolean
void
removeAnchoredCommand
(CommandButtonProjection projection) Removes the specified ribbon command from the trailing edge of the task toggle strip of this ribbon.void
Removes the specified change listener from tracking changes to this ribbon.void
void
removeTaskbarAppMenuLink
(Command appMenuCommand) void
removeTaskbarCommand
(BaseCommand<?> command) void
removeTaskbarComponent
(ComponentContentModel componentContentModel) private void
void
removeTaskbarGallery
(RibbonGalleryContentModel galleryContentModel) void
setApplicationMenuCommand
(RibbonApplicationMenuCommandButtonProjection applicationMenuCommandProjection) Sets the application menu command for this ribbon.void
setMinimized
(boolean isMinimized) Changes the minimized state of this ribbon.void
setOnShowContextualMenuListener
(JRibbon.OnShowContextualMenuListener onShowContextualMenuListener) void
setSelectedTask
(RibbonTask task) Selects the specified task.void
setTaskbarKeyTipPolicy
(RibbonTaskbarKeyTipPolicy taskbarKeyTipPolicy) void
setVisible
(boolean flag) void
setVisible
(RibbonContextualTaskGroup group, boolean isVisible) Sets the visibility of ribbon tasks in the specified contextual task group.private void
void
updateUI()
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
-
Field Details
-
tasks
The general tasks.- See Also:
-
contextualTaskGroups
The contextual task groups.- See Also:
-
taskbarComponents
The taskbar components (displayed between the application menu button and the frame title). -
taskbarContentHandlers
-
bands
Bands of the currently shown task. -
currentlySelectedTask
Currently selected (shown) task. -
anchoredCommands
Commands anchored to the far edge of the task toggle strip (right under LTR and left under RTL).- See Also:
-
groupVisibilityMap
Visibility status of the contextual task group. Must contain a value for each group incontextualTaskGroups
.- See Also:
-
applicationMenuCommandProjection
-
applicationMenuProjection
The application menu.- See Also:
-
isMinimized
private boolean isMinimizedIndicates whether the ribbon is currently minimized.- See Also:
-
ribbonFrame
The host ribbon frame. Isnull
when the ribbon is not hosted in aJRibbonFrame
. -
onShowContextualMenuListener
-
onTaskSelectionChangeListeners
-
taskbarKeyTipPolicy
-
uiClassID
The UI class ID string.- See Also:
-
-
Constructor Details
-
JRibbon
public JRibbon()Creates a new empty ribbon. Applications are highly encouraged to useJRibbonFrame
and access the ribbon withJRibbonFrame.getRibbon()
API. -
JRibbon
JRibbon(JRibbonFrame ribbonFrame) Creates an empty ribbon for the specified ribbon frame.- Parameters:
ribbonFrame
- Host ribbon frame.
-
-
Method Details
-
setTaskbarKeyTipPolicy
-
getTaskbarKeyTipPolicy
-
matchesTaskbarContentHandler
-
getTaskbarContentHandlerFor
-
removeTaskbarContentHandlerFor
-
syncTaskbarContent
private void syncTaskbarContent() -
addTaskbarCommand
public <M extends BaseCommand<MCM>,MCM extends BaseCommandMenuContentModel, void addTaskbarCommandP extends BaseCommandButtonPresentationModel<MPM, P>, MPM extends BaseCommandPopupMenuPresentationModel> (BaseCommandButtonProjection<M, MCM, P, MPM> projection) -
isShowingInTaskbar
-
removeTaskbarCommand
-
addTaskbarAppMenuLink
-
removeTaskbarAppMenuLink
-
addTaskbarComponent
public void addTaskbarComponent(ComponentProjection<? extends JComponent, ? extends ComponentContentModel> projection) -
isShowingInTaskbar
-
removeTaskbarComponent
-
addTaskbarGalleryDropdown
-
isShowingInTaskbar
-
removeTaskbarGallery
-
clearTaskbar
public void clearTaskbar()Removes all taskbar content from this ribbon.- See Also:
-
addTask
Adds the specified task to this ribbon.- Parameters:
task
- The ribbon task to add.- See Also:
-
addAnchoredCommand
Adds the specified ribbon command projection to the trailing edge of the task toggle strip of this ribbon.- Parameters:
projection
- Command projection to add.- See Also:
-
removeAnchoredCommand
Removes the specified ribbon command from the trailing edge of the task toggle strip of this ribbon.- Parameters:
projection
- Command projection to remove.- See Also:
-
getAnchoredCommands
Returns the anchored commands for this ribbon.- Returns:
- This ribbon's anchored commands.
- See Also:
-
addContextualTaskGroup
Adds the specified contextual task group to this ribbon.- Parameters:
group
- Task group to add.- See Also:
-
getTaskCount
public int getTaskCount()Returns the number of regular tasks inthis
ribbon.- Returns:
- Number of regular tasks in
this
ribbon. - See Also:
-
getTask
Retrieves the regular task at specified index.- Parameters:
index
- Task index.- Returns:
- Task that matches the specified index.
- See Also:
-
getContextualTaskGroupCount
public int getContextualTaskGroupCount()Returns the number of contextual task groups inthis
ribbon.- Returns:
- Number of contextual task groups in
this
ribbon. - See Also:
-
getContextualTaskGroup
Retrieves contextual task group at specified index.- Parameters:
index
- Group index.- Returns:
- Group that matches the specified index.
- See Also:
-
setSelectedTask
Selects the specified task. The task can be either regular (added withaddTask(RibbonTask)
) or a task in a visible contextual task group (added withaddContextualTaskGroup(RibbonContextualTaskGroup)
. Fires aselectedTask
property change event.- Parameters:
task
- Task to select.- Throws:
IllegalArgumentException
- If the specified task is not in the ribbon or not visible.- See Also:
-
getSelectedTask
Returns the currently selected task.- Returns:
- The currently selected task.
- See Also:
-
updateUI
public void updateUI()- Overrides:
updateUI
in classJComponent
-
getUI
Returns the UI delegate for this component.- Overrides:
getUI
in classJComponent
- Returns:
- a
RibbonUI
object - See Also:
-
getUIClassID
- Overrides:
getUIClassID
in classJComponent
-
getTaskbarComponents
-
addChangeListener
Adds the specified change listener to track changes to this ribbon.- Parameters:
l
- Change listener to add.- See Also:
-
removeChangeListener
Removes the specified change listener from tracking changes to this ribbon.- Parameters:
l
- Change listener to remove.- See Also:
-
fireStateChanged
protected void fireStateChanged()Notifies all registered listeners that the state of this ribbon has changed. -
setVisible
Sets the visibility of ribbon tasks in the specified contextual task group. Visibility of all ribbon tasks in the specified group is affected. Note that the ribbon can show ribbon tasks of multiple groups at the same time.- Parameters:
group
- Contextual task group.isVisible
- Iftrue
, all ribbon tasks in the specified group will be visible. Iffalse
, all ribbon tasks in the specified group will be hidden.- See Also:
-
isVisible
Returns the visibility of ribbon tasks in the specified contextual task group.- Parameters:
group
- Contextual task group.- Returns:
true
if the ribbon tasks in the specified group are visible,false
otherwise.
-
setApplicationMenuCommand
public void setApplicationMenuCommand(RibbonApplicationMenuCommandButtonProjection applicationMenuCommandProjection) Sets the application menu command for this ribbon. Ifnull
is passed, the application menu button is hidden.- Parameters:
applicationMenuCommandProjection
- The new application menu command. Can benull
.- See Also:
-
getApplicationMenuCommandProjection
-
getApplicationMenuProjection
Returns the application menu of this ribbon.- Returns:
- The application menu of this ribbon.
- See Also:
-
isMinimized
public boolean isMinimized()Returns the indication whether this ribbon is minimized.- Returns:
true
if this ribbon is minimized,false
otherwise.- See Also:
-
setMinimized
public void setMinimized(boolean isMinimized) Changes the minimized state of this ribbon. Fires aminimized
property change event.- Parameters:
isMinimized
- iftrue
, this ribbon becomes minimized, otherwise it is unminimized.
-
getRibbonFrame
Returns the ribbon frame that hosts this ribbon. The result can benull
.- Returns:
- The ribbon frame that hosts this ribbon.
-
setVisible
public void setVisible(boolean flag) - Overrides:
setVisible
in classJComponent
-
setOnShowContextualMenuListener
public void setOnShowContextualMenuListener(JRibbon.OnShowContextualMenuListener onShowContextualMenuListener) -
getOnShowContextualMenuListener
-
addOnTaskSelectionChangedListener
-
removeOnTaskSelectionChangedListener
-
fireTaskSelectionChanged
private void fireTaskSelectionChanged()
-