/*******************************************************************************
 * Copyright (c) 2006, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 ******************************************************************************/

package org.eclipse.jface.internal.provisional.action;

import org.eclipse.jface.action.IContributionItem;
import org.eclipse.jface.action.IContributionManager;
import org.eclipse.jface.action.IToolBarManager;

/**
 * The intention of this interface is to provide in interface for
 * ToolBarContributionItem so that the implementation can be replaced.
 *
 * <p>
 * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
 * part of a work in progress. There is a guarantee neither that this API will
 * work nor that it will remain the same. Please do not use this API without
 * consulting with the Platform/UI team.
 * </p>
 *
 * @since 3.2
 */
public interface IToolBarContributionItem extends IContributionItem {

	/**
	 * Returns the current height of the corresponding cool item.
	 *
	 * @return the current height
	 */
	public int getCurrentHeight();

	/**
	 * Returns the current width of the corresponding cool item.
	 *
	 * @return the current size
	 */
	public int getCurrentWidth();

	/**
	 * Returns the minimum number of tool items to show in the cool item.
	 *
	 * @return the minimum number of tool items to show, or <code>SHOW_ALL_ITEMS</code>
	 *         if a value was not set
	 * @see #setMinimumItemsToShow(int)
	 */
	public int getMinimumItemsToShow();

	/**
	 * Returns whether chevron support is enabled.
	 *
	 * @return <code>true</code> if chevron support is enabled, <code>false</code>
	 *         otherwise
	 */
	public boolean getUseChevron();

	/**
	 * Sets the current height of the cool item. Update(SIZE) should be called
	 * to adjust the widget.
	 *
	 * @param currentHeight
	 *            the current height to set
	 */
	public void setCurrentHeight(int currentHeight);

	/**
	 * Sets the current width of the cool item. Update(SIZE) should be called
	 * to adjust the widget.
	 *
	 * @param currentWidth
	 *            the current width to set
	 */
	public void setCurrentWidth(int currentWidth);

	/**
	 * Sets the minimum number of tool items to show in the cool item. If this
	 * number is less than the total tool items, a chevron will appear and the
	 * hidden tool items appear in a drop down menu. By default, all the tool
	 * items are shown in the cool item.
	 *
	 * @param minimumItemsToShow
	 *            the minimum number of tool items to show.
	 * @see #getMinimumItemsToShow()
	 * @see #setUseChevron(boolean)
	 */
	public void setMinimumItemsToShow(int minimumItemsToShow);

	/**
	 * Enables or disables chevron support for the cool item. By default,
	 * chevron support is enabled.
	 *
	 * @param value
	 *            <code>true</code> to enable chevron support, <code>false</code>
	 *            otherwise.
	 */
	public void setUseChevron(boolean value);

	/**
	 * Returns the internal tool bar manager of the contribution item.
	 *
	 * @return the tool bar manager, or <code>null</code> if one is not
	 *         defined.
	 * @see IToolBarManager
	 */
	public IToolBarManager getToolBarManager();

	/**
	 * Returns the parent contribution manager, or <code>null</code> if this
	 * contribution item is not currently added to a contribution manager.
	 *
	 * @return the parent contribution manager, or <code>null</code>
	 *
	 * TODO may not need this, getToolBarManager may be enough.
	 */
	public IContributionManager getParent();

}
