Package org.pushingpixels.flamingo.api.ribbon

# Class JRibbonBand

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
org.pushingpixels.flamingo.api.ribbon.AbstractRibbonBand<JBandControlPanel>
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.