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

org.pushingpixels.flamingo.api.ribbon.JRibbonBand

public class JRibbonBand
extends AbstractRibbonBand

Ribbon band component. Can host three types of content:

• Ribbon commands added with addRibbonCommand(FlamingoCommand, RibbonElementPriority).
• Wrapped core / 3rd party components added with addRibbonComponent(JRibbonComponent).
• Ribbon galleries added with addRibbonGallery(String, List, Map, int, int, RibbonElementPriority) .

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

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:

• addRibbonGalleryCommands(String, String, FlamingoCommand...)
• removeRibbonGalleryCommands(String, FlamingoCommand...)
• setSelectedRibbonGalleryCommand(String, FlamingoCommand)
• 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 java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BaselineResizeBehavior, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

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

java.awt.Container.AccessibleAWTContainer

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

javax.swing.JComponent.AccessibleJComponent

Field Summary

Fields

Modifier and Type	Field	Description
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

resizePolicies, uiClassID

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

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

Constructor Summary

Constructors

Constructor	Description
JRibbonBand(java.lang.String title, org.pushingpixels.neon.icon.ResizableIcon icon)	Creates a new ribbon band.
JRibbonBand(java.lang.String title, org.pushingpixels.neon.icon.ResizableIcon icon, java.awt.event.ActionListener expandActionListener)	Creates a new ribbon band.

Method Summary

Modifier and Type	Method	Description
AbstractCommandButton	addRibbonCommand(FlamingoCommand ribbonCommand, RibbonElementPriority priority)	Adds the specified command to this band.
void	addRibbonComponent(JRibbonComponent comp)	Adds the specified ribbon component to this ribbon band.
void	addRibbonGallery(java.lang.String galleryName, java.util.List<StringValuePair<java.util.List<FlamingoCommand>>> commands, java.util.Map<RibbonElementPriority,java.lang.Integer> preferredVisibleCommandCounts, int preferredPopupMaxCommandColumns, int preferredPopupMaxVisibleCommandRows, CommandButtonDisplayState commandDisplayState, RibbonElementPriority priority)	Adds a new ribbon gallery to this band.
void	addRibbonGallery(java.lang.String galleryName, java.util.List<StringValuePair<java.util.List<FlamingoCommand>>> commands, java.util.Map<RibbonElementPriority,java.lang.Integer> preferredVisibleCommandCounts, int preferredPopupMaxCommandColumns, int preferredPopupMaxVisibleCommandRows, RibbonElementPriority priority)
void	addRibbonGalleryCommands(java.lang.String galleryName, java.lang.String commandGroupName, FlamingoCommand... commands)	Adds the specified command toggle commands to a command group in the specified ribbon gallery.
AbstractRibbonBand	cloneBand()	Returns a clone of this ribbon band.
java.util.List<JRibbonComponent>	getRibbonComponents(int groupIndex)
void	removeRibbonGalleryCommands(java.lang.String galleryName, FlamingoCommand... commands)	Removes commands from the specified ribbon gallery.
void	setGroupTitle(int groupIndex, java.lang.String groupTitle)	Changes the title of the specified group.
void	setRibbonGalleryCommandDisplayState(java.lang.String galleryName, CommandButtonDisplayState displayState)	Sets the display state for the commands of the specified ribbon gallery.
void	setRibbonGalleryExpandKeyTip(java.lang.String galleryName, java.lang.String expandKeyTip)	Sets the key tip on the expand button of the specified ribbon gallery.
void	setRibbonGalleryPopupCallback(java.lang.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	setSelectedRibbonGalleryCommand(java.lang.String galleryName, FlamingoCommand commandToSelect)	Selects the specified command in the specified ribbon gallery.
int	startGroup()	Starts a new unnamed group.
int	startGroup(java.lang.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 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.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 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.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(java.lang.String title,
                   org.pushingpixels.neon.icon.ResizableIcon icon)

Creates a new ribbon band.

Parameters:

title - Band title.

icon - Associated icon (for collapsed state).

JRibbonBand

public JRibbonBand(java.lang.String title,
                   org.pushingpixels.neon.icon.ResizableIcon icon,
                   java.awt.event.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

addRibbonCommand

public AbstractCommandButton addRibbonCommand(FlamingoCommand ribbonCommand,
                                              RibbonElementPriority priority)

Adds the specified command to this band.

Parameters:

ribbonCommand - Command to add.

priority - Priority of the command.

addRibbonGallery

public void addRibbonGallery(java.lang.String galleryName,
                             java.util.List<StringValuePair<java.util.List<FlamingoCommand>>> commands,
                             java.util.Map<RibbonElementPriority,java.lang.Integer> preferredVisibleCommandCounts,
                             int preferredPopupMaxCommandColumns,
                             int preferredPopupMaxVisibleCommandRows,
                             RibbonElementPriority priority)

addRibbonGallery

public void addRibbonGallery(java.lang.String galleryName,
                             java.util.List<StringValuePair<java.util.List<FlamingoCommand>>> commands,
                             java.util.Map<RibbonElementPriority,java.lang.Integer> preferredVisibleCommandCounts,
                             int preferredPopupMaxCommandColumns,
                             int preferredPopupMaxVisibleCommandRows,
                             CommandButtonDisplayState commandDisplayState,
                             RibbonElementPriority priority)

Adds a new ribbon gallery to this band.

Parameters:

galleryName - Gallery name.

commands - Command groups.

preferredVisibleCommandCounts - Preferred count of visible commands of the ribbon gallery under different states.

preferredPopupMaxCommandColumns - Preferred maximum columns in the popup gallery associated with the ribbon gallery.

preferredPopupMaxVisibleCommandRows - Preferred maximum visible rows in the popup gallery associated with the ribbon gallery.

priority - The initial ribbon gallery priority.

See Also:

addRibbonGalleryCommands(String, String, FlamingoCommand...), removeRibbonGalleryCommands(String, FlamingoCommand...), setSelectedRibbonGalleryCommand(String, FlamingoCommand)

addRibbonGalleryCommands

public void addRibbonGalleryCommands(java.lang.String galleryName,
                                     java.lang.String commandGroupName,
                                     FlamingoCommand... commands)

Adds the specified command toggle commands to a command group in the specified ribbon gallery.

Parameters:

galleryName - Ribbon gallery name.

commandGroupName - Command group name.

commands - Commands to add.

See Also:

addRibbonGallery(String, List, Map, int, int, RibbonElementPriority), addRibbonGallery(String, List, Map, int, int, CommandButtonDisplayState, RibbonElementPriority), removeRibbonGalleryCommands(String, FlamingoCommand...), setSelectedRibbonGalleryCommand(String, FlamingoCommand)

removeRibbonGalleryCommands

public void removeRibbonGalleryCommands(java.lang.String galleryName,
                                        FlamingoCommand... commands)

Removes commands from the specified ribbon gallery.

Parameters:

galleryName - Ribbon gallery name.

commands - Commands to remove.

See Also:

addRibbonGallery(String, List, Map, int, int, CommandButtonDisplayState, RibbonElementPriority), addRibbonGalleryCommands(String, String, FlamingoCommand...), setSelectedRibbonGalleryCommand(String, FlamingoCommand)

setSelectedRibbonGalleryCommand

public void setSelectedRibbonGalleryCommand(java.lang.String galleryName,
                                            FlamingoCommand commandToSelect)

Selects the specified command in the specified ribbon gallery.

Parameters:

galleryName - Ribbon gallery name.

commandToSelect - Command to select.

See Also:

addRibbonGallery(String, List, Map, int, int, RibbonElementPriority), addRibbonGallery(String, List, Map, int, int, CommandButtonDisplayState, RibbonElementPriority), addRibbonGalleryCommands(String, String, FlamingoCommand...), removeRibbonGalleryCommands(String, FlamingoCommand...)

setRibbonGalleryCommandDisplayState

public void setRibbonGalleryCommandDisplayState(java.lang.String galleryName,
                                                CommandButtonDisplayState displayState)

Sets the display state for the commands of the specified ribbon gallery.

Parameters:

galleryName - Ribbon gallery name.

displayState - Display state for the commands of the matching ribbon gallery.

setRibbonGalleryPopupCallback

public void setRibbonGalleryPopupCallback(java.lang.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(java.lang.String galleryName,
                                         java.lang.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.

startGroup

public int startGroup()

Starts a new unnamed group.

Returns:

The index of the new group.

startGroup

public int startGroup(java.lang.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,
                          java.lang.String groupTitle)

Changes the title of the specified group.

Parameters:

groupIndex - Group index.

groupTitle - The new title for this group.

getRibbonComponents

public java.util.List<JRibbonComponent> getRibbonComponents(int groupIndex)

cloneBand

public AbstractRibbonBand cloneBand()

Description copied from class: AbstractRibbonBand

Returns a clone of this ribbon band.

Specified by:

cloneBand in class AbstractRibbonBand

Returns:

A clone of this ribbon band.