org.pushingpixels.flamingo.api.ribbon.JRibbonBand Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of flamengo Show documentation
Flamingo Swing component suite
The newest version!
/*
 * Copyright (c) 2005-2010 Flamingo Kirill Grouchnikov. All Rights Reserved.
 *
 * Redistribution and use in source and binary forms, with or without 
 * modification, are permitted provided that the following conditions are met:
 * 
 *  o Redistributions of source code must retain the above copyright notice, 
 *    this list of conditions and the following disclaimer. 
 *     
 *  o Redistributions in binary form must reproduce the above copyright notice, 
 *    this list of conditions and the following disclaimer in the documentation 
 *    and/or other materials provided with the distribution. 
 *     
 *  o Neither the name of Flamingo Kirill Grouchnikov nor the names of 
 *    its contributors may be used to endorse or promote products derived 
 *    from this software without specific prior written permission. 
 *     
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
 */
package org.pushingpixels.flamingo.api.ribbon;

import java.awt.event.ActionListener;
import java.util.*;

import javax.swing.SwingConstants;

import org.pushingpixels.flamingo.api.common.*;
import org.pushingpixels.flamingo.api.common.icon.ResizableIcon;
import org.pushingpixels.flamingo.api.common.popup.JCommandPopupMenu;
import org.pushingpixels.flamingo.api.ribbon.resize.CoreRibbonResizePolicies;
import org.pushingpixels.flamingo.internal.ui.ribbon.*;

/**
 * Ribbon band component. Can host three types of content:
 * 
 * 
 * Command buttons added with
 * {@link #addCommandButton(AbstractCommandButton, RibbonElementPriority)}.
 * Wrapped core / 3rd party components added with
 * {@link #addRibbonComponent(JRibbonComponent)} or
 * {@link #addRibbonComponent(JRibbonComponent, int)}.
 * Ribbon galleries added with
 * {@link #addRibbonGallery(String, List, Map, int, int, RibbonElementPriority)}
 * .
 * 
 * 
 * 
 * Command buttons are added with associated {@link RibbonElementPriority}. The
 * higher the priority, the longer the button "stays" in the
 * {@link CommandButtonDisplayState#BIG} or
 * {@link CommandButtonDisplayState#MEDIUM} state - depending on the available
 * resize policies.
 * 
 * 
 * 
 * Wrapped components can span one or multiple rows. Use the
 * {@link #addRibbonComponent(JRibbonComponent, int)} API to add a wrapped
 * component that spans more than one row.
 * 
 * 
 * 
 * Once a ribbon gallery is added with
 * {@link #addRibbonGallery(String, List, Map, int, int, RibbonElementPriority)}
 * , you can use the following APIs to configure the content and behavior of
 * that gallery:
 * 
 * 
 * 
 * {@link #addRibbonGalleryButtons(String, String, JCommandToggleButton...)}
 * 
 * {@link #removeRibbonGalleryButtons(String, JCommandToggleButton...)}
 * {@link #setSelectedRibbonGalleryButton(String, JCommandToggleButton)}
 * {@link #setRibbonGalleryExpandKeyTip(String, String)}
 * 
 * {@link #setRibbonGalleryPopupCallback(String, RibbonGalleryPopupCallback)}
 * 
 * 
 * 
 * A ribbon band can have multiple visual groups separated with vertical
 * separator lines. To start a new unnamed group use the {@link #startGroup()}
 * API. To start a new named group use the {@link #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.
 * 
 * 
 * @author Kirill Grouchnikov
 */
public class JRibbonBand extends AbstractRibbonBand {
	/**
	 * This callback allows application code to place additional menu entries in
	 * the popup menu shown when the ribbon gallery expand button is clicked.
	 * Application code should use
	 * {@link JCommandPopupMenu#addMenuButton(JCommandMenuButton)} and
	 * {@link JCommandPopupMenu#addMenuSeparator()} APIs on the passed menu
	 * parameter.
	 * 
	 * @author Kirill Grouchnikov
	 */
	public static interface RibbonGalleryPopupCallback {
		/**
		 * Called just before the popup menu is about to be shown.
		 * 
		 * @param menu
		 *            The popup menu that will be shown.
		 */
		public void popupToBeShown(JCommandPopupMenu menu);
	}

	/**
	 * Big size with landscape orientation. Used for buttons in in-ribbon
	 * galleries.
	 */
	public static final CommandButtonDisplayState BIG_FIXED_LANDSCAPE = new CommandButtonDisplayState(
			"Big Fixed Landscape", 32) {
		@Override
		public CommandButtonLayoutManager createLayoutManager(
				AbstractCommandButton button) {
			return new CommandButtonLayoutManagerBigFixedLandscape();
		}
	};

	/**
	 * Big size with landscape orientation. Used for buttons in in-ribbon
	 * galleries.
	 */
	public static final CommandButtonDisplayState BIG_FIXED = new CommandButtonDisplayState(
			"Big Fixed", 32) {
		@Override
		public CommandButtonLayoutManager createLayoutManager(
				AbstractCommandButton button) {
			return new CommandButtonLayoutManagerBigFixed();
		}
	};

	/**
	 * Creates a new ribbon band.
	 * 
	 * @param title
	 *            Band title.
	 * @param icon
	 *            Associated icon (for collapsed state).
	 */
	public JRibbonBand(String title, ResizableIcon icon) {
		this(title, icon, null);
	}

	/**
	 * Creates a new ribbon band.
	 * 
	 * @param title
	 *            Band title.
	 * @param icon
	 *            Associated icon (for collapsed state).
	 * @param expandActionListener
	 *            Expand action listener (can be null).
	 */
	public JRibbonBand(String title, ResizableIcon icon,
			ActionListener expandActionListener) {
		super(title, icon, expandActionListener, new JBandControlPanel());
		this.resizePolicies = Collections
				.unmodifiableList(CoreRibbonResizePolicies
						.getCorePoliciesPermissive(this));
		updateUI();
	}

	/**
	 * Adds the specified command button to this band.
	 * 
	 * @param commandButton
	 *            Command button to add.
	 * @param priority
	 *            Priority of the button.
	 */
	public void addCommandButton(AbstractCommandButton commandButton,
			RibbonElementPriority priority) {
		commandButton.setHorizontalAlignment(SwingConstants.LEFT);
		this.controlPanel.addCommandButton(commandButton, priority);
	}

	public void addRibbonGallery(String galleryName,
			List>> buttons,
			Map preferredVisibleButtonCounts,
			int preferredPopupMaxButtonColumns,
			int preferredPopupMaxVisibleButtonRows,
			RibbonElementPriority priority) {
		this.addRibbonGallery(galleryName, buttons,
				preferredVisibleButtonCounts, preferredPopupMaxButtonColumns,
				preferredPopupMaxVisibleButtonRows,
				JRibbonBand.BIG_FIXED_LANDSCAPE, priority);
	}

	/**
	 * Adds a new ribbon gallery to this band.
	 * 
	 * @param galleryName
	 *            Gallery name.
	 * @param buttons
	 *            Button groups.
	 * @param preferredVisibleButtonCounts
	 *            Preferred count of visible buttons of the ribbon gallery under
	 *            different states.
	 * @param preferredPopupMaxButtonColumns
	 *            Preferred maximum columns in the popup gallery associated with
	 *            the ribbon gallery.
	 * @param preferredPopupMaxVisibleButtonRows
	 *            Preferred maximum visible rows in the popup gallery associated
	 *            with the ribbon gallery.
	 * @param priority
	 *            The initial ribbon gallery priority.
	 * @see #addRibbonGalleryButtons(String, String, JCommandToggleButton...)
	 * @see #removeRibbonGalleryButtons(String, JCommandToggleButton...)
	 * @see #setSelectedRibbonGalleryButton(String, JCommandToggleButton)
	 */
	public void addRibbonGallery(String galleryName,
			List>> buttons,
			Map preferredVisibleButtonCounts,
			int preferredPopupMaxButtonColumns,
			int preferredPopupMaxVisibleButtonRows,
			CommandButtonDisplayState ribbonButtonDisplayState,
			RibbonElementPriority priority) {
		JRibbonGallery gallery = new JRibbonGallery();
		gallery.setButtonDisplayState(ribbonButtonDisplayState);
		gallery.setName(galleryName);
		for (Map.Entry prefCountEntry : preferredVisibleButtonCounts
				.entrySet()) {
			gallery.setPreferredVisibleButtonCount(prefCountEntry.getKey(),
					prefCountEntry.getValue());
		}
		gallery.setGroupMapping(buttons);
		gallery.setPreferredPopupPanelDimension(preferredPopupMaxButtonColumns,
				preferredPopupMaxVisibleButtonRows);

		this.controlPanel.addRibbonGallery(gallery, priority);
	}

	/**
	 * Adds the specified command toggle buttons to a button group in the
	 * specified ribbon gallery.
	 * 
	 * @param galleryName
	 *            Ribbon gallery name.
	 * @param buttonGroupName
	 *            Button group name.
	 * @param buttons
	 *            Buttons to add.
	 * @see #addRibbonGallery(String, List, Map, int, int,
	 *      RibbonElementPriority)
	 * @see #removeRibbonGalleryButtons(String, JCommandToggleButton...)
	 * @see #setSelectedRibbonGalleryButton(String, JCommandToggleButton)
	 */
	public void addRibbonGalleryButtons(String galleryName,
			String buttonGroupName, JCommandToggleButton... buttons) {
		JRibbonGallery gallery = this.controlPanel
				.getRibbonGallery(galleryName);
		if (gallery == null)
			return;
		gallery.addRibbonGalleryButtons(buttonGroupName, buttons);
	}

	/**
	 * Removes command toggle buttons from the specified ribbon gallery.
	 * 
	 * @param galleryName
	 *            Ribbon gallery name.
	 * @param buttons
	 *            Buttons to remove.
	 * @see #addRibbonGallery(String, List, Map, int, int,
	 *      RibbonElementPriority)
	 * @see #addRibbonGalleryButtons(String, String, JCommandToggleButton...)
	 * @see #setSelectedRibbonGalleryButton(String, JCommandToggleButton)
	 */
	public void removeRibbonGalleryButtons(String galleryName,
			JCommandToggleButton... buttons) {
		JRibbonGallery gallery = this.controlPanel
				.getRibbonGallery(galleryName);
		if (gallery == null)
			return;
		gallery.removeRibbonGalleryButtons(buttons);
	}

	/**
	 * Selects the specified command toggle button in the specified ribbon
	 * gallery.
	 * 
	 * @param galleryName
	 *            Ribbon gallery name.
	 * @param buttonToSelect
	 *            Button to select.
	 * @see #addRibbonGallery(String, List, Map, int, int,
	 *      RibbonElementPriority)
	 * @see #addRibbonGalleryButtons(String, String, JCommandToggleButton...)
	 * @see #removeRibbonGalleryButtons(String, JCommandToggleButton...)
	 */
	public void setSelectedRibbonGalleryButton(String galleryName,
			JCommandToggleButton buttonToSelect) {
		JRibbonGallery gallery = this.controlPanel
				.getRibbonGallery(galleryName);
		if (gallery == null)
			return;
		gallery.setSelectedButton(buttonToSelect);
	}

	/**
	 * Sets the display state for the buttons of the specified ribbon gallery.
	 * 
	 * @param galleryName
	 *            Ribbon gallery name.
	 * @param displayState
	 *            Display state for the buttons of the matching ribbon gallery.
	 */
	public void setRibbonGalleryButtonDisplayState(String galleryName,
			CommandButtonDisplayState displayState) {
		JRibbonGallery gallery = this.controlPanel
				.getRibbonGallery(galleryName);
		if (gallery == null)
			return;
		gallery.setButtonDisplayState(displayState);
	}

	/**
	 * Sets the application callback to place additional entries in the popup
	 * menu shown when the specified ribbon gallery is expanded.
	 * 
	 * @param galleryName
	 *            Gallery name.
	 * @param popupCallback
	 *            Application callback.
	 * @see RibbonGalleryPopupCallback
	 */
	public void setRibbonGalleryPopupCallback(String galleryName,
			RibbonGalleryPopupCallback popupCallback) {
		JRibbonGallery gallery = this.controlPanel
				.getRibbonGallery(galleryName);
		if (gallery == null)
			return;
		gallery.setPopupCallback(popupCallback);
	}

	/**
	 * Sets the key tip on the expand button of the specified ribbon gallery.
	 * 
	 * @param galleryName
	 *            Gallery name.
	 * @param expandKeyTip
	 *            The key tip on the expand button of the specified ribbon
	 *            gallery.
	 */
	public void setRibbonGalleryExpandKeyTip(String galleryName,
			String expandKeyTip) {
		JRibbonGallery gallery = this.controlPanel
				.getRibbonGallery(galleryName);
		if (gallery == null)
			return;
		gallery.setExpandKeyTip(expandKeyTip);
	}

	/**
	 * Adds the specified ribbon component to this ribbon band.
	 * 
	 * @param comp
	 *            The ribbon component to add.
	 */
	public void addRibbonComponent(JRibbonComponent comp) {
		this.controlPanel.addRibbonComponent(comp);
	}

	/**
	 * Adds the specified ribbon component to this ribbon band.
	 * 
	 * @param comp
	 *            The ribbon component to add.
	 * @param 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 #startGroup()
	 * @see #startGroup(String)
	 */
	public void addRibbonComponent(JRibbonComponent comp, int rowSpan) {
		int groupCount = this.controlPanel.getControlPanelGroupCount();
		String groupTitle = (groupCount > 0) ? this.controlPanel
				.getControlPanelGroupTitle(groupCount - 1) : null;
		int availableRows = (groupTitle == null) ? 3 : 2;
		if ((rowSpan <= 0) || (rowSpan > availableRows)) {
			throw new IllegalArgumentException(
					"Row span value not supported. Should be in 1.."
							+ availableRows + " range");
		}
		this.controlPanel.addRibbonComponent(comp, rowSpan);
	}

	/**
	 * Starts a new unnamed group.
	 * 
	 * @return The index of the new group.
	 */
	public int startGroup() {
		return this.controlPanel.startGroup();
	}

	/**
	 * Starts a new named group.
	 * 
	 * @param groupTitle
	 *            The group title.
	 * @return The index of the new group.
	 */
	public int startGroup(String groupTitle) {
		return this.controlPanel.startGroup(groupTitle);
	}

	/**
	 * Changes the title of the specified group.
	 * 
	 * @param groupIndex
	 *            Group index.
	 * @param groupTitle
	 *            The new title for this group.
	 */
	public void setGroupTitle(int groupIndex, String groupTitle) {
		this.controlPanel.setGroupTitle(groupIndex, groupTitle);
	}

	public List getRibbonComponents(int groupIndex) {
		return this.controlPanel.getRibbonComponents(groupIndex);
	}

	/*
	 * (non-Javadoc)
	 * 
	 * @see org.jvnet.flamingo.ribbon.AbstractRibbonBand#cloneBand()
	 */
	@Override
	public AbstractRibbonBand cloneBand() {
		AbstractRibbonBand result = new JRibbonBand(this
				.getTitle(), this.getIcon(), this.getExpandActionListener());
		result.applyComponentOrientation(this.getComponentOrientation());
		return result;
	}
}