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 added with addCommandButton(AbstractCommandButton, RibbonElementPriority).
Wrapped core / 3rd party components added with addRibbonComponent(JRibbonComponent) or addRibbonComponent(JRibbonComponent, int).
Ribbon galleries added with addRibbonGallery(String, List, Map, int, int, RibbonElementPriority) .

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:

addRibbonGalleryButtons(String, String, JCommandToggleButton...)
removeRibbonGalleryButtons(String, JCommandToggleButton...)
setSelectedRibbonGalleryButton(String, JCommandToggleButton)
setRibbonGalleryExpandKeyTip(String, String)
setRibbonGalleryPopupCallback(String, RibbonGalleryPopupCallback)

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

Nested Classes

Modifier and Type

Class

Description

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

Fields

Modifier and Type

Field

Description

static final CommandButtonDisplayState

BIG_FIXED

Big size with landscape orientation.

static final 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
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

Constructors

Constructor

Description

JRibbonBand(String title, ResizableIcon icon)

Constructs a JRibbonBand specifying the title and the icon when in the collapsed state.

JRibbonBand(String title, ResizableIcon icon, ActionListener expandActionListener)

Constructs a JRibbonBand specifying the title, the icon when in the collapsed state, and the action listener for when the band is expanded.
Method Summary

Modifier and Type

Method

Description

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

addRibbonGallery(JRibbonGallery gallery)

Adds the gallery to the ribbon band with a priority of RibbonElementPriority.TOP.

void

addRibbonGallery(JRibbonGallery gallery, RibbonElementPriority priority)

Adds the gallery to the ribbon band with the specified 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, setIcon, setPopupRibbonBand, setResizePolicies, setTitle, setUI, 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, 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, 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

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details
- 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 Details
- JRibbonBand
  
  public JRibbonBand(String title, ResizableIcon icon)
  
  Constructs a JRibbonBand specifying the title and the icon when in the collapsed state.
  This is equivalent to JRibbonBand(title, icon, null).
  Parameters:
  
  title - band title
  
  icon - the icon displayed when the band collapses
  
  See Also:
  
  JRibbonBand(String, ResizableIcon, ActionListener)
- JRibbonBand
  
  public JRibbonBand(String title, ResizableIcon icon, ActionListener expandActionListener)
  
  Constructs a JRibbonBand specifying the title, the icon when in the collapsed state, and the action listener for when the band is expanded.
  
  Parameters:
  
  title - band title
  
  icon - the icon displayed when the band collapses
  
  expandActionListener - Expand action listener (can be null).
Method Details
- addCommandButton
  
  public void addCommandButton(AbstractCommandButton commandButton, RibbonElementPriority priority)
  
  Adds the specified command button to this band.
  
  Parameters:
  
  commandButton - the 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)
- addRibbonGallery
  
  public void addRibbonGallery(JRibbonGallery gallery)
  
  Adds the gallery to the ribbon band with a priority of RibbonElementPriority.TOP.
  
  Parameters:
  
  gallery - the ribbon gallery
- addRibbonGallery
  
  public void addRibbonGallery(JRibbonGallery gallery, RibbonElementPriority priority)
  
  Adds the gallery to the ribbon band with the specified priority.
  
  Parameters:
  
  gallery - the ribbon gallery
  
  priority - the gallery priority
- 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.

Class JRibbonBand

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JComponent

Nested classes/interfaces inherited from class java.awt.Container

Nested classes/interfaces inherited from class java.awt.Component

Field Summary

Fields inherited from class org.pushingpixels.flamingo.api.ribbon.AbstractRibbonBand

Fields inherited from class javax.swing.JComponent

Fields inherited from class java.awt.Component

Fields inherited from interface java.awt.image.ImageObserver

Constructor Summary

Method Summary

Methods inherited from class org.pushingpixels.flamingo.api.ribbon.AbstractRibbonBand

Methods inherited from class javax.swing.JComponent

Methods inherited from class java.awt.Container

Methods inherited from class java.awt.Component

Methods inherited from class java.lang.Object

Field Details

BIG_FIXED_LANDSCAPE

BIG_FIXED

Constructor Details

JRibbonBand

JRibbonBand

Method Details

addCommandButton

addRibbonGallery

addRibbonGallery

addRibbonGalleryButtons

addRibbonGallery

addRibbonGallery

removeRibbonGalleryButtons

setSelectedRibbonGalleryButton

setRibbonGalleryButtonDisplayState

setRibbonGalleryPopupCallback

setRibbonGalleryExpandKeyTip

addRibbonComponent

addRibbonComponent

startGroup

startGroup

setGroupTitle

getRibbonComponents

cloneBand