org.pushingpixels.flamingo.api.ribbon
Class JRibbonBand

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.AbstractRibbonBand<JBandControlPanel>
                  extended by org.pushingpixels.flamingo.api.ribbon.JRibbonBand
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable

public class JRibbonBand
extends AbstractRibbonBand<JBandControlPanel>

Ribbon band component. Can host three types of content:

Command buttons are added with associated RibbonElementPriority. The higher the priority, the longer the button "stays" in the CommandButtonDisplayState.BIG or CommandButtonDisplayState.MEDIUM state - depending on the available resize policies.

Wrapped components can span one or multiple rows. Use the addRibbonComponent(JRibbonComponent, int) API to add a wrapped component that spans more than one row.

Once a ribbon gallery is added with addRibbonGallery(String, List, Map, int, int, RibbonElementPriority) , you can use the following APIs to configure the content and behavior of that gallery:

A ribbon band can have multiple visual groups separated with vertical separator lines. To start a new unnamed group use the startGroup() API. To start a new named group use the startGroup(String) API. Unnamed groups will have three rows of controls. Named groups will have two rows of controls, with the top row showing the group title.

See Also:
Serialized Form

Nested Class Summary
static interface JRibbonBand.RibbonGalleryPopupCallback
          This callback allows application code to place additional menu entries in the popup menu shown when the ribbon gallery expand button is clicked.
 
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
static CommandButtonDisplayState BIG_FIXED
          Big size with landscape orientation.
static CommandButtonDisplayState BIG_FIXED_LANDSCAPE
          Big size with landscape orientation.
 
Fields inherited from class org.pushingpixels.flamingo.api.ribbon.AbstractRibbonBand
controlPanel, resizePolicies, uiClassID
 
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
JRibbonBand(String title, ResizableIcon icon)
          Creates a new ribbon band.
JRibbonBand(String title, ResizableIcon icon, ActionListener expandActionListener)
          Creates a new ribbon band.
 
Method Summary
 void addCommandButton(AbstractCommandButton commandButton, RibbonElementPriority priority)
          Adds the specified command button to this band.
 void addRibbonComponent(JRibbonComponent comp)
          Adds the specified ribbon component to this ribbon band.
 void addRibbonComponent(JRibbonComponent comp, int rowSpan)
          Adds the specified ribbon component to this ribbon band.
 void addRibbonGallery(String galleryName, List<StringValuePair<List<JCommandToggleButton>>> buttons, Map<RibbonElementPriority,Integer> preferredVisibleButtonCounts, int preferredPopupMaxButtonColumns, int preferredPopupMaxVisibleButtonRows, CommandButtonDisplayState ribbonButtonDisplayState, RibbonElementPriority priority)
          Adds a new ribbon gallery to this band.
 void addRibbonGallery(String galleryName, List<StringValuePair<List<JCommandToggleButton>>> buttons, Map<RibbonElementPriority,Integer> preferredVisibleButtonCounts, int preferredPopupMaxButtonColumns, int preferredPopupMaxVisibleButtonRows, RibbonElementPriority priority)
           
 void addRibbonGalleryButtons(String galleryName, String buttonGroupName, JCommandToggleButton... buttons)
          Adds the specified command toggle buttons to a button group in the specified ribbon gallery.
 AbstractRibbonBand<JBandControlPanel> cloneBand()
          Returns a clone of this ribbon band.
 List<JRibbonComponent> getRibbonComponents(int groupIndex)
           
 void removeRibbonGalleryButtons(String galleryName, JCommandToggleButton... buttons)
          Removes command toggle buttons from the specified ribbon gallery.
 void setGroupTitle(int groupIndex, String groupTitle)
          Changes the title of the specified group.
 void setRibbonGalleryButtonDisplayState(String galleryName, CommandButtonDisplayState displayState)
          Sets the display state for the buttons of the specified ribbon gallery.
 void setRibbonGalleryExpandKeyTip(String galleryName, String expandKeyTip)
          Sets the key tip on the expand button of the specified ribbon gallery.
 void setRibbonGalleryPopupCallback(String galleryName, JRibbonBand.RibbonGalleryPopupCallback popupCallback)
          Sets the application callback to place additional entries in the popup menu shown when the specified ribbon gallery is expanded.
 void setSelectedRibbonGalleryButton(String galleryName, JCommandToggleButton buttonToSelect)
          Selects the specified command toggle button in the specified ribbon gallery.
 int startGroup()
          Starts a new unnamed group.
 int startGroup(String groupTitle)
          Starts a new named group.
 
Methods inherited from class org.pushingpixels.flamingo.api.ribbon.AbstractRibbonBand
getCollapsedStateKeyTip, getControlPanel, getCurrentResizePolicy, getExpandActionListener, getExpandButtonKeyTip, getExpandButtonRichTooltip, getIcon, getPopupRibbonBand, getResizePolicies, getTitle, getUI, getUIClassID, setCollapsedStateKeyTip, setControlPanel, setCurrentResizePolicy, setExpandActionListener, setExpandButtonKeyTip, setExpandButtonRichTooltip, setPopupRibbonBand, setResizePolicies, setTitle, setUI, 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, setVisible, 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, 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, transferFocusBackward, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

BIG_FIXED_LANDSCAPE

public static final CommandButtonDisplayState BIG_FIXED_LANDSCAPE
Big size with landscape orientation. Used for buttons in in-ribbon galleries.


BIG_FIXED

public static final CommandButtonDisplayState BIG_FIXED
Big size with landscape orientation. Used for buttons in in-ribbon galleries.

Constructor Detail

JRibbonBand

public JRibbonBand(String title,
                   ResizableIcon icon)
Creates a new ribbon band.

Parameters:
title - Band title.
icon - Associated icon (for collapsed state).

JRibbonBand

public JRibbonBand(String title,
                   ResizableIcon icon,
                   ActionListener expandActionListener)
Creates a new ribbon band.

Parameters:
title - Band title.
icon - Associated icon (for collapsed state).
expandActionListener - Expand action listener (can be null).
Method Detail

addCommandButton

public void addCommandButton(AbstractCommandButton commandButton,
                             RibbonElementPriority priority)
Adds the specified command button to this band.

Parameters:
commandButton - Command button to add.
priority - Priority of the button.

addRibbonGallery

public void addRibbonGallery(String galleryName,
                             List<StringValuePair<List<JCommandToggleButton>>> buttons,
                             Map<RibbonElementPriority,Integer> preferredVisibleButtonCounts,
                             int preferredPopupMaxButtonColumns,
                             int preferredPopupMaxVisibleButtonRows,
                             RibbonElementPriority priority)

addRibbonGallery

public void addRibbonGallery(String galleryName,
                             List<StringValuePair<List<JCommandToggleButton>>> buttons,
                             Map<RibbonElementPriority,Integer> preferredVisibleButtonCounts,
                             int preferredPopupMaxButtonColumns,
                             int preferredPopupMaxVisibleButtonRows,
                             CommandButtonDisplayState ribbonButtonDisplayState,
                             RibbonElementPriority priority)
Adds a new ribbon gallery to this band.

Parameters:
galleryName - Gallery name.
buttons - Button groups.
preferredVisibleButtonCounts - Preferred count of visible buttons of the ribbon gallery under different states.
preferredPopupMaxButtonColumns - Preferred maximum columns in the popup gallery associated with the ribbon gallery.
preferredPopupMaxVisibleButtonRows - Preferred maximum visible rows in the popup gallery associated with the ribbon gallery.
priority - The initial ribbon gallery priority.
See Also:
addRibbonGalleryButtons(String, String, JCommandToggleButton...), removeRibbonGalleryButtons(String, JCommandToggleButton...), setSelectedRibbonGalleryButton(String, JCommandToggleButton)

addRibbonGalleryButtons

public void addRibbonGalleryButtons(String galleryName,
                                    String buttonGroupName,
                                    JCommandToggleButton... buttons)
Adds the specified command toggle buttons to a button group in the specified ribbon gallery.

Parameters:
galleryName - Ribbon gallery name.
buttonGroupName - Button group name.
buttons - Buttons to add.
See Also:
addRibbonGallery(String, List, Map, int, int, RibbonElementPriority), removeRibbonGalleryButtons(String, JCommandToggleButton...), setSelectedRibbonGalleryButton(String, JCommandToggleButton)

removeRibbonGalleryButtons

public void removeRibbonGalleryButtons(String galleryName,
                                       JCommandToggleButton... buttons)
Removes command toggle buttons from the specified ribbon gallery.

Parameters:
galleryName - Ribbon gallery name.
buttons - Buttons to remove.
See Also:
addRibbonGallery(String, List, Map, int, int, RibbonElementPriority), addRibbonGalleryButtons(String, String, JCommandToggleButton...), setSelectedRibbonGalleryButton(String, JCommandToggleButton)

setSelectedRibbonGalleryButton

public void setSelectedRibbonGalleryButton(String galleryName,
                                           JCommandToggleButton buttonToSelect)
Selects the specified command toggle button in the specified ribbon gallery.

Parameters:
galleryName - Ribbon gallery name.
buttonToSelect - Button to select.
See Also:
addRibbonGallery(String, List, Map, int, int, RibbonElementPriority), addRibbonGalleryButtons(String, String, JCommandToggleButton...), removeRibbonGalleryButtons(String, JCommandToggleButton...)

setRibbonGalleryButtonDisplayState

public void setRibbonGalleryButtonDisplayState(String galleryName,
                                               CommandButtonDisplayState displayState)
Sets the display state for the buttons of the specified ribbon gallery.

Parameters:
galleryName - Ribbon gallery name.
displayState - Display state for the buttons of the matching ribbon gallery.

setRibbonGalleryPopupCallback

public void setRibbonGalleryPopupCallback(String galleryName,
                                          JRibbonBand.RibbonGalleryPopupCallback popupCallback)
Sets the application callback to place additional entries in the popup menu shown when the specified ribbon gallery is expanded.

Parameters:
galleryName - Gallery name.
popupCallback - Application callback.
See Also:
JRibbonBand.RibbonGalleryPopupCallback

setRibbonGalleryExpandKeyTip

public void setRibbonGalleryExpandKeyTip(String galleryName,
                                         String expandKeyTip)
Sets the key tip on the expand button of the specified ribbon gallery.

Parameters:
galleryName - Gallery name.
expandKeyTip - The key tip on the expand button of the specified ribbon gallery.

addRibbonComponent

public void addRibbonComponent(JRibbonComponent comp)
Adds the specified ribbon component to this ribbon band.

Parameters:
comp - The ribbon component to add.

addRibbonComponent

public void addRibbonComponent(JRibbonComponent comp,
                               int rowSpan)
Adds the specified ribbon component to this ribbon band.

Parameters:
comp - The ribbon component to add.
rowSpan - Row span of the ribbon component.
Throws:
IllegalArgumentException - if the row span is not legal. Legal row span is 1..3 for unnamed groups and 1..2 for named groups.
See Also:
startGroup(), startGroup(String)

startGroup

public int startGroup()
Starts a new unnamed group.

Returns:
The index of the new group.

startGroup

public int startGroup(String groupTitle)
Starts a new named group.

Parameters:
groupTitle - The group title.
Returns:
The index of the new group.

setGroupTitle

public void setGroupTitle(int groupIndex,
                          String groupTitle)
Changes the title of the specified group.

Parameters:
groupIndex - Group index.
groupTitle - The new title for this group.

getRibbonComponents

public List<JRibbonComponent> getRibbonComponents(int groupIndex)

cloneBand

public AbstractRibbonBand<JBandControlPanel> cloneBand()
Description copied from class: AbstractRibbonBand
Returns a clone of this ribbon band.

Specified by:
cloneBand in class AbstractRibbonBand<JBandControlPanel>
Returns:
A clone of this ribbon band.