ImageObserver
, MenuContainer
, Serializable
public class JRibbon extends JComponent
The ribbon has the following major parts:
addTask(RibbonTask)
addContextualTaskGroup(RibbonContextualTaskGroup)
setApplicationMenu(RibbonApplicationMenu)
addTaskbarComponent(Component)
configureHelp(ResizableIcon, ActionListener)
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 adde 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 big round button shown in the top left
corner of the ribbon. If the
setApplicationMenu(RibbonApplicationMenu)
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 a taskbar component use the
addTaskbarComponent(Component)
API. The taskbar panel lives to the
right of the application menu button. Taskbar components can be removed with
the removeTaskbarComponent(Component)
API.
The ribbon can be minimized in one of the following ways:
setMinimized(boolean)
with true
.Ctrl+F1
key combination.A minimized ribbon shows the application menu button, taskbar panel, task buttons and help button, 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.
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Container.AccessibleAWTContainer
JComponent.AccessibleJComponent
Modifier and Type | Field | Description |
---|---|---|
ResizableIcon |
applicationIcon |
The application icon.
|
static String |
PROPERTY_APPLICATION_ICON |
The property string used when the
applicationIcon changes. |
static String |
PROPERTY_APPLICATION_MENU |
The property string used when the
applicationMenu changes. |
static String |
PROPERTY_APPLICATION_MENU_KEY_TIP |
The property string used when the
applicationMenuKeyTip changes. |
static String |
PROPERTY_APPLICATION_MENU_RICH_TOOLTIP |
The property string used when the
applicationMenuRichTooltip
changes. |
static String |
PROPERTY_MINIMIZED |
The property string used when the
isMinimized changes. |
static String |
PROPERTY_SELECTED_TASK |
The property string used when the
currentlySelectedTask changes. |
static String |
uiClassID |
The UI class ID string.
|
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Constructor | Description |
---|---|
JRibbon() |
Constructs an empty default
JRibbon . |
JRibbon(ResizableIcon appIcon) |
Constructs a
JRibbon specifying the application icon. |
Modifier and Type | Method | Description |
---|---|---|
void |
addChangeListener(ChangeListener l) |
Adds the specified change listener to track changes to this ribbon.
|
void |
addContextualTaskGroup(RibbonContextualTaskGroup group) |
Adds the specified contextual task group to this ribbon.
|
void |
addHelpPanelComponent(Component comp) |
Adds a component to the 'Help Panel.' This is the area where the
help button lives.
|
void |
addTask(RibbonTask task) |
Adds the specified task to this ribbon.
|
void |
addTaskbarComponent(Component comp) |
Adds the specified taskbar component to this ribbon.
|
void |
configureHelp(ResizableIcon helpIcon,
ActionListener helpActionListener) |
Configures the help button of this ribbon.
|
protected void |
fireStateChanged() |
Notifies all registered listeners that the state of this ribbon has
changed.
|
ResizableIcon |
getApplicationIcon() |
Returns the application icon.
|
RibbonApplicationMenu |
getApplicationMenu() |
Returns the application menu of this ribbon.
|
String |
getApplicationMenuKeyTip() |
Returns the key tip of the application menu button.
|
RichTooltip |
getApplicationMenuRichTooltip() |
Returns the rich tooltip of the application menu button.
|
RibbonContextualTaskGroup |
getContextualTaskGroup(int index) |
Retrieves contextual task group at specified index.
|
int |
getContextualTaskGroupCount() |
Returns the number of contextual task groups in
this ribbon. |
ActionListener |
getHelpActionListener() |
Returns the action listener for the help button.
|
ResizableIcon |
getHelpIcon() |
Returns the icon for the help button.
|
RichTooltip |
getHelpRichTooltip() |
Returns the rich tooltip of the help button.
|
JRibbonFrame |
getRibbonFrame() |
Deprecated.
Dropped support in order to decouple the
JRibbon
from the JRibbonFrame |
RibbonTask |
getSelectedTask() |
Returns the currently selected task.
|
RibbonTask |
getTask(int index) |
Retrieves the regular task at specified index.
|
List<Component> |
getTaskbarComponents() |
Gets an unmodifiable list of all taskbar components of
this
ribbon. |
int |
getTaskCount() |
Returns the number of regular tasks in
this ribbon. |
RibbonUI |
getUI() |
Returns the UI object which implements the L&F for this component.
|
String |
getUIClassID() |
|
boolean |
isMinimized() |
Returns the indication whether this ribbon is minimized.
|
boolean |
isVisible(RibbonContextualTaskGroup group) |
Returns the visibility of ribbon tasks in the specified contextual task
group.
|
void |
removeAllHelpPanelComponents() |
Removes al the components from the 'Help Panel'.
|
void |
removeAllTaskbarComponents() |
Removes all components added to the taskbar of the ribbon.
|
void |
removeAllTasks() |
Removes all tasks from the ribbon.
|
void |
removeChangeListener(ChangeListener l) |
Removes the specified change listener from tracking changes to this
ribbon.
|
void |
removeHelpPanelComponent(Component comp) |
Removes a component from the 'Help Panel'.
|
void |
removeTask(int pos) |
Removes the task at the specified position, if it represents a valid
task.
|
void |
removeTask(RibbonTask task) |
Removes the given task from the ribbon.
|
void |
removeTaskbarComponent(Component comp) |
Removes the specified taskbar component from this ribbon.
|
void |
setApplicationIcon(ResizableIcon applicationIcon) |
Sets the application icon.
|
void |
setApplicationMenu(RibbonApplicationMenu applicationMenu) |
Sets the application menu for this ribbon.
|
void |
setApplicationMenuKeyTip(String keyTip) |
Sets the key tip of the application menu button.
|
void |
setApplicationMenuRichTooltip(RichTooltip tooltip) |
Sets the rich tooltip of the application menu button.
|
void |
setHelpRichTooltip(RichTooltip tooltip) |
Sets the rich tooltip of the help button.
|
void |
setMinimized(boolean isMinimized) |
Changes the minimized state of this ribbon.
|
void |
setSelectedTask(RibbonTask task) |
Selects the specified task.
|
void |
setVisible(boolean flag) |
|
void |
setVisible(RibbonContextualTaskGroup group,
boolean isVisible) |
Sets the visibility of ribbon tasks in the specified contextual task
group.
|
void |
updateUI() |
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
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
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
public static final String PROPERTY_APPLICATION_ICON
applicationIcon
changes. The
value is "ribbon.icon".public static final String PROPERTY_APPLICATION_MENU_RICH_TOOLTIP
applicationMenuRichTooltip
changes. The value is "applicationMenuRichTooltip".public static final String PROPERTY_APPLICATION_MENU
applicationMenu
changes. The
value is "applicationMenu".public static final String PROPERTY_APPLICATION_MENU_KEY_TIP
applicationMenuKeyTip
changes.
The value is "applicationMenuKeyTip".public static final String PROPERTY_SELECTED_TASK
currentlySelectedTask
changes.
The value is "selectedTask".public static final String PROPERTY_MINIMIZED
isMinimized
changes. The value
is "minimized".public static final String uiClassID
public ResizableIcon applicationIcon
public JRibbon()
JRibbon
. Applications are highly
encouraged to use JRibbonFrame
and access the ribbon with
JRibbonFrame.getRibbon()
API.public JRibbon(ResizableIcon appIcon)
JRibbon
specifying the application icon. The
application icon is displayed in the application menu button.
Applications are highly encouraged to use JRibbonFrame
and access
the ribbon with JRibbonFrame.getRibbon()
API.appIcon
- the application iconpublic void addTaskbarComponent(Component comp)
Taskbar components are small components placed to the right of the application menu. These components usually perform an action common among the entire application.
comp
- the taskbar component to addremoveTaskbarComponent(Component)
,
removeAllTaskbarComponents()
,
getTaskbarComponents()
public void removeTaskbarComponent(Component comp)
comp
- The taskbar component to remove.addTaskbarComponent(Component)
,
getTaskbarComponents()
,
removeAllTaskbarComponents()
public void removeAllTaskbarComponents()
public void addTask(RibbonTask task)
task
- The ribbon task to add.addContextualTaskGroup(RibbonContextualTaskGroup)
,
getTaskCount()
,
getTask(int)
public void removeTask(int pos)
IndexOutOfBoundsException
if not.pos
- The position of the task to remove.public void removeTask(RibbonTask task)
task
- The ribbon task to be removed from the panel.IllegalArgumentException
- if task
is null
public void removeAllTasks()
public void configureHelp(ResizableIcon helpIcon, ActionListener helpActionListener)
helpIcon
- The icon for the help button.helpActionListener
- The action listener for the help button.getHelpIcon()
,
getHelpActionListener()
public ResizableIcon getHelpIcon()
null
if
the help button has not been configured with the
configureHelp(ResizableIcon, ActionListener)
API.configureHelp(ResizableIcon, ActionListener)
,
getHelpActionListener()
public ActionListener getHelpActionListener()
null
if the help button has not been configured with the
configureHelp(ResizableIcon, ActionListener)
API.configureHelp(ResizableIcon, ActionListener)
,
getHelpIcon()
public void setHelpRichTooltip(RichTooltip tooltip)
tooltip
- The rich tooltip of the help button.getHelpRichTooltip()
,
configureHelp(org.pushingpixels.flamingo.api.common.icon.ResizableIcon, java.awt.event.ActionListener)
public RichTooltip getHelpRichTooltip()
setHelpRichTooltip(org.pushingpixels.flamingo.api.common.RichTooltip)
,
configureHelp(org.pushingpixels.flamingo.api.common.icon.ResizableIcon, java.awt.event.ActionListener)
public void addHelpPanelComponent(Component comp)
comp
- the component to be addedpublic void removeHelpPanelComponent(Component comp)
comp
- The component to remove. If the component is not currently
on the help panel this call will be a no-op.public void removeAllHelpPanelComponents()
public void addContextualTaskGroup(RibbonContextualTaskGroup group)
group
- Task group to add.addTask(RibbonTask)
,
setVisible(RibbonContextualTaskGroup, boolean)
,
isVisible(RibbonContextualTaskGroup)
public int getTaskCount()
this
ribbon. This
does not include the contextual ribbon tasks.
To find the total number of ribbon tasks (including contextual ribbon tasks) you will have to iterate through the contextual task groups.
this
ribbon.getTask(int)
,
addTask(RibbonTask)
public RibbonTask getTask(int index)
index
- task indexgetTaskCount()
,
addTask(RibbonTask)
public int getContextualTaskGroupCount()
this
ribbon.this
ribbonaddContextualTaskGroup(RibbonContextualTaskGroup)
,
getContextualTaskGroup(int)
public RibbonContextualTaskGroup getContextualTaskGroup(int index)
index
- group indexaddContextualTaskGroup(RibbonContextualTaskGroup)
,
getContextualTaskGroupCount()
public void setSelectedTask(RibbonTask task)
addTask(RibbonTask)
) or a task in a visible contextual task
group (added with
addContextualTaskGroup(RibbonContextualTaskGroup)
. Fires a
selectedTask
property change event.task
- task to selectIllegalArgumentException
- if task
is not in the ribbon, is
null
, or not visible.getSelectedTask()
public RibbonTask getSelectedTask()
setSelectedTask(RibbonTask)
public void updateUI()
updateUI
in class JComponent
public RibbonUI getUI()
getUI
in class JComponent
RibbonUI
objectJComponent.setUI(javax.swing.plaf.ComponentUI)
public String getUIClassID()
getUIClassID
in class JComponent
public List<Component> getTaskbarComponents()
this
ribbon.this
ribbon.addTaskbarComponent(Component)
,
removeTaskbarComponent(Component)
public void addChangeListener(ChangeListener l)
l
- Change listener to add.removeChangeListener(ChangeListener)
public void removeChangeListener(ChangeListener l)
l
- Change listener to remove.addChangeListener(ChangeListener)
protected void fireStateChanged()
public void setVisible(RibbonContextualTaskGroup group, boolean isVisible)
group
- Contextual task group.isVisible
- If true
, all ribbon tasks in the specified group
will be visible. If false
, all ribbon tasks in
the specified group will be hidden.isVisible(RibbonContextualTaskGroup)
public boolean isVisible(RibbonContextualTaskGroup group)
group
- Contextual task group.true
if the ribbon tasks in the specified group are
visible, false
otherwise.public void setApplicationMenu(RibbonApplicationMenu applicationMenu)
null
is
passed, the application menu button is hidden. Fires an
applicationMenu
property change event.applicationMenu
- The new application menu. Can be null
.getApplicationMenu()
public RibbonApplicationMenu getApplicationMenu()
setApplicationMenu(RibbonApplicationMenu)
public void setApplicationMenuRichTooltip(RichTooltip tooltip)
applicationMenuRichTooltip
property change event.tooltip
- The rich tooltip of the application menu button.getApplicationMenuRichTooltip()
,
setApplicationMenu(RibbonApplicationMenu)
public RichTooltip getApplicationMenuRichTooltip()
setApplicationMenuRichTooltip(RichTooltip)
,
setApplicationMenu(RibbonApplicationMenu)
public void setApplicationMenuKeyTip(String keyTip)
applicationMenuKeyTip
property change event.keyTip
- The new key tip for the application menu button.setApplicationMenu(RibbonApplicationMenu)
,
getApplicationMenuKeyTip()
public String getApplicationMenuKeyTip()
setApplicationMenuKeyTip(String)
,
setApplicationMenu(RibbonApplicationMenu)
public boolean isMinimized()
true
if this ribbon is minimized, false
otherwise.setMinimized(boolean)
public void setMinimized(boolean isMinimized)
minimized
property change event.isMinimized
- if true
, this ribbon becomes minimized, otherwise
it is unminimized.@Deprecated public JRibbonFrame getRibbonFrame()
JRibbon
from the JRibbonFrame
null
.public void setVisible(boolean flag)
setVisible
in class JComponent
public ResizableIcon getApplicationIcon()
This is a convenience method and is equivalent to
getUI().getApplicationIcon()
.
getUI()
,
RibbonUI.getApplicationIcon()
,
setApplicationIcon(ResizableIcon)
public void setApplicationIcon(ResizableIcon applicationIcon)
There is no check performed to see if applicationIcon
is
null
.
A PropertyChangeEvent
is fired for the
PROPERTY_APPLICATION_ICON
property.
applicationIcon
- the application icon to setgetUI()
,
RibbonUI.setApplicationIcon(ResizableIcon)
,
getApplicationIcon()