org.pushingpixels.flamingo.api.ribbon
Class JRibbon

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by org.pushingpixels.flamingo.api.ribbon.JRibbon
All Implemented Interfaces:
java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class JRibbon
extends javax.swing.JComponent

The ribbon component.

The ribbon has the following major parts:

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:

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.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
static java.lang.String uiClassID
          The UI class ID string.
 
Fields inherited from class javax.swing.JComponent
accessibleContext, 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
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
JRibbon()
          Creates a new empty ribbon.
 
Method Summary
 void addChangeListener(javax.swing.event.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 addTask(RibbonTask task)
          Adds the specified task to this ribbon.
 void addTaskbarComponent(java.awt.Component comp)
          Adds the specified taskbar component to this ribbon.
 void configureHelp(ResizableIcon helpIcon, java.awt.event.ActionListener helpActionListener)
          Configures the help button of this ribbon.
protected  void fireStateChanged()
          Notifies all registered listeners that the state of this ribbon has changed.
 RibbonApplicationMenu getApplicationMenu()
          Returns the application menu of this ribbon.
 java.lang.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.
 java.awt.event.ActionListener getHelpActionListener()
          Returns the action listener for the help button.
 ResizableIcon getHelpIcon()
          Returns the icon for the help button.
 JRibbonFrame getRibbonFrame()
          Returns the ribbon frame that hosts this ribbon.
 RibbonTask getSelectedTask()
          Returns the currently selected task.
 RibbonTask getTask(int index)
          Retrieves the regular task at specified index.
 java.util.List<java.awt.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.
 java.lang.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 removeAllTaskbarComponents()
          Removes all components added to the taskbar of the ribbon.
 void removeAllTasks()
          Removes all tasks from the ribbon.
 void removeChangeListener(javax.swing.event.ChangeListener l)
          Removes the specified change listener from tracking changes to this ribbon.
 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(java.awt.Component comp)
          Removes the specified taskbar component from this ribbon.
 void setApplicationMenu(RibbonApplicationMenu applicationMenu)
          Sets the application menu for this ribbon.
 void setApplicationMenuKeyTip(java.lang.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 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()
           
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, 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, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, 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, transferFocusBackward, 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, 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, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, 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, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

uiClassID

public static final java.lang.String uiClassID
The UI class ID string.

See Also:
Constant Field Values
Constructor Detail

JRibbon

public JRibbon()
Creates a new empty ribbon. Applications are highly encouraged to use JRibbonFrame and access the ribbon with JRibbonFrame.getRibbon() API.

Method Detail

addTaskbarComponent

public void addTaskbarComponent(java.awt.Component comp)
Adds the specified taskbar component to this ribbon.

Parameters:
comp - The taskbar component to add.
See Also:
removeTaskbarComponent(Component), getTaskbarComponents()

removeTaskbarComponent

public void removeTaskbarComponent(java.awt.Component comp)
Removes the specified taskbar component from this ribbon.

Parameters:
comp - The taskbar component to remove.
See Also:
addTaskbarComponent(Component), getTaskbarComponents()

removeAllTaskbarComponents

public void removeAllTaskbarComponents()
Removes all components added to the taskbar of the ribbon.


addTask

public void addTask(RibbonTask task)
Adds the specified task to this ribbon.

Parameters:
task - The ribbon task to add.
See Also:
addContextualTaskGroup(RibbonContextualTaskGroup), getTaskCount(), getTask(int)

removeTask

public void removeTask(int pos)
Removes the task at the specified position, if it represents a valid task. Throws an IndexOutOfBoundsException if not.

Parameters:
pos - The position of the task to remove.

removeTask

public void removeTask(RibbonTask task)
Removes the given task from the ribbon. If this is the currently visible task, the ribbon will move to the task to its left, unless the removed task is the left-most, in which case it will move to the next task to the right.

Parameters:
task - The ribbon task to be removed from the panel.

removeAllTasks

public void removeAllTasks()
Removes all tasks from the ribbon.


configureHelp

public void configureHelp(ResizableIcon helpIcon,
                          java.awt.event.ActionListener helpActionListener)
Configures the help button of this ribbon.

Parameters:
helpIcon - The icon for the help button.
helpActionListener - The action listener for the help button.
See Also:
getHelpIcon(), getHelpActionListener()

getHelpIcon

public ResizableIcon getHelpIcon()
Returns the icon for the help button. Will return null if the help button has not been configured with the configureHelp(ResizableIcon, ActionListener) API.

Returns:
The icon for the help button.
See Also:
configureHelp(ResizableIcon, ActionListener), getHelpActionListener()

getHelpActionListener

public java.awt.event.ActionListener getHelpActionListener()
Returns the action listener for the help button. Will return null if the help button has not been configured with the configureHelp(ResizableIcon, ActionListener) API.

Returns:
The action listener for the help button.
See Also:
configureHelp(ResizableIcon, ActionListener), getHelpIcon()

addContextualTaskGroup

public void addContextualTaskGroup(RibbonContextualTaskGroup group)
Adds the specified contextual task group to this ribbon.

Parameters:
group - Task group to add.
See Also:
addTask(RibbonTask), setVisible(RibbonContextualTaskGroup, boolean), isVisible(RibbonContextualTaskGroup)

getTaskCount

public int getTaskCount()
Returns the number of regular tasks in this ribbon.

Returns:
Number of regular tasks in this ribbon.
See Also:
getTask(int), addTask(RibbonTask)

getTask

public RibbonTask getTask(int index)
Retrieves the regular task at specified index.

Parameters:
index - Task index.
Returns:
Task that matches the specified index.
See Also:
getTaskCount(), addTask(RibbonTask)

getContextualTaskGroupCount

public int getContextualTaskGroupCount()
Returns the number of contextual task groups in this ribbon.

Returns:
Number of contextual task groups in this ribbon.
See Also:
addContextualTaskGroup(RibbonContextualTaskGroup), getContextualTaskGroup(int)

getContextualTaskGroup

public RibbonContextualTaskGroup getContextualTaskGroup(int index)
Retrieves contextual task group at specified index.

Parameters:
index - Group index.
Returns:
Group that matches the specified index.
See Also:
addContextualTaskGroup(RibbonContextualTaskGroup), getContextualTaskGroupCount()

setSelectedTask

public void setSelectedTask(RibbonTask task)
Selects the specified task. The task can be either regular (added with addTask(RibbonTask)) or a task in a visible contextual task group (added with addContextualTaskGroup(RibbonContextualTaskGroup). Fires a selectedTask property change event.

Parameters:
task - Task to select.
Throws:
java.lang.IllegalArgumentException - If the specified task is not in the ribbon or not visible.
See Also:
getSelectedTask()

getSelectedTask

public RibbonTask getSelectedTask()
Returns the currently selected task.

Returns:
The currently selected task.
See Also:
setSelectedTask(RibbonTask)

updateUI

public void updateUI()
Overrides:
updateUI in class javax.swing.JComponent

getUI

public RibbonUI getUI()
Returns the UI object which implements the L&F for this component.

Returns:
a RibbonUI object
See Also:
JComponent.setUI(javax.swing.plaf.ComponentUI)

getUIClassID

public java.lang.String getUIClassID()
Overrides:
getUIClassID in class javax.swing.JComponent

getTaskbarComponents

public java.util.List<java.awt.Component> getTaskbarComponents()
Gets an unmodifiable list of all taskbar components of this ribbon.

Returns:
All taskbar components of this ribbon.
See Also:
addTaskbarComponent(Component), removeTaskbarComponent(Component)

addChangeListener

public void addChangeListener(javax.swing.event.ChangeListener l)
Adds the specified change listener to track changes to this ribbon.

Parameters:
l - Change listener to add.
See Also:
removeChangeListener(ChangeListener)

removeChangeListener

public void removeChangeListener(javax.swing.event.ChangeListener l)
Removes the specified change listener from tracking changes to this ribbon.

Parameters:
l - Change listener to remove.
See Also:
addChangeListener(ChangeListener)

fireStateChanged

protected void fireStateChanged()
Notifies all registered listeners that the state of this ribbon has changed.


setVisible

public void setVisible(RibbonContextualTaskGroup group,
                       boolean isVisible)
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 - If true, all ribbon tasks in the specified group will be visible. If false, all ribbon tasks in the specified group will be hidden.
See Also:
isVisible(RibbonContextualTaskGroup)

isVisible

public boolean isVisible(RibbonContextualTaskGroup group)
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.

setApplicationMenu

public void setApplicationMenu(RibbonApplicationMenu applicationMenu)
Sets the application menu for this ribbon. If null is passed, the application menu button is hidden. Fires an applicationMenu property change event.

Parameters:
applicationMenu - The new application menu. Can be null.
See Also:
getApplicationMenu()

getApplicationMenu

public RibbonApplicationMenu getApplicationMenu()
Returns the application menu of this ribbon.

Returns:
The application menu of this ribbon.
See Also:
setApplicationMenu(RibbonApplicationMenu)

setApplicationMenuRichTooltip

public void setApplicationMenuRichTooltip(RichTooltip tooltip)
Sets the rich tooltip of the application menu button. Fires an applicationMenuRichTooltip property change event.

Parameters:
tooltip - The rich tooltip of the application menu button.
See Also:
getApplicationMenuRichTooltip(), setApplicationMenu(RibbonApplicationMenu)

getApplicationMenuRichTooltip

public RichTooltip getApplicationMenuRichTooltip()
Returns the rich tooltip of the application menu button.

Returns:
The rich tooltip of the application menu button.
See Also:
setApplicationMenuRichTooltip(RichTooltip), setApplicationMenu(RibbonApplicationMenu)

setApplicationMenuKeyTip

public void setApplicationMenuKeyTip(java.lang.String keyTip)
Sets the key tip of the application menu button. Fires an applicationMenuKeyTip property change event.

Parameters:
keyTip - The new key tip for the application menu button.
See Also:
setApplicationMenu(RibbonApplicationMenu), getApplicationMenuKeyTip()

getApplicationMenuKeyTip

public java.lang.String getApplicationMenuKeyTip()
Returns the key tip of the application menu button.

Returns:
The key tip of the application menu button.
See Also:
setApplicationMenuKeyTip(String), setApplicationMenu(RibbonApplicationMenu)

isMinimized

public boolean isMinimized()
Returns the indication whether this ribbon is minimized.

Returns:
true if this ribbon is minimized, false otherwise.
See Also:
setMinimized(boolean)

setMinimized

public void setMinimized(boolean isMinimized)
Changes the minimized state of this ribbon. Fires a minimized property change event.

Parameters:
isMinimized - if true, this ribbon becomes minimized, otherwise it is unminimized.

getRibbonFrame

public JRibbonFrame getRibbonFrame()
Returns the ribbon frame that hosts this ribbon. The result can be null.

Returns:
The ribbon frame that hosts this ribbon.

setVisible

public void setVisible(boolean flag)
Overrides:
setVisible in class javax.swing.JComponent