org.eclipse.jface.action.IContributionItem Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2015 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/

package org.eclipse.jface.action;

import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.CoolBar;
import org.eclipse.swt.widgets.Menu;
import org.eclipse.swt.widgets.ToolBar;

/**
 * A contribution item represents a contribution to a shared UI resource such as a
 * menu or tool bar. More generally, contribution items are managed by a contribution
 * manager.
 * For instance, in a tool bar a contribution item is a tool bar button or a separator.
 * In a menu bar a contribution item is a menu, and in a menu a contribution item
 * is a menu item or separator.
 * 
 * A contribution item can realize itself in different SWT widgets, using the different
 * fill methods.  The same type of contribution item can be used with a
 * MenuBarManager, ToolBarManager, CoolBarManager,
 * or a StatusLineManager.
 * 
 * 
 * This interface is internal to the framework; it should not be implemented outside
 * the framework.
 * 
 *
 * @see IContributionManager
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IContributionItem {

    /**
     * Disposes of this contribution item. Called by the parent
     * contribution manager when the manager is being disposed.
     * Clients should not call this method directly, unless they
     * have removed this contribution item from the containing
     * IContributionManager before the contribution lifecycle
     * has ended.
     *
     * @since 2.1
     */
    public void dispose();

    /**
     * Fills the given composite control with controls representing this
     * contribution item.  Used by StatusLineManager.
     *
     * @param parent the parent control
     */
    public void fill(Composite parent);

    /**
     * Fills the given menu with controls representing this contribution item.
     * Used by MenuManager.
     *
     * @param parent the parent menu
     * @param index the index where the controls are inserted,
     *   or -1 to insert at the end
     */
    public void fill(Menu parent, int index);

    /**
     * Fills the given tool bar with controls representing this contribution item.
     * Used by ToolBarManager.
     *
     * @param parent the parent tool bar
     * @param index the index where the controls are inserted,
     *   or -1 to insert at the end
     */
    public void fill(ToolBar parent, int index);

    /**
     * Fills the given cool bar with controls representing this contribution item.
     * Used by CoolBarManager.
     *
     * @param parent the parent cool bar
     * @param index the index where the controls are inserted,
     *   or -1 to insert at the end
     * @since 3.0
     */
    public void fill(CoolBar parent, int index);

    /**
     * Returns the identifier of this contribution item.
     * The id is used for retrieving an item from its manager.
     *
     * @return the contribution item identifier, or null
     *   if none
     */
    public String getId();

    /**
     * Returns whether this contribution item is enabled.
     *
     * @return true if this item is enabled
     */
    public boolean isEnabled();

    /**
     * Returns whether this contribution item is dirty. A dirty item will be
     * recreated when the action bar is updated.
     *
     * @return true if this item is dirty
     */
    public boolean isDirty();

    /**
     * Returns whether this contribution item is dynamic. A dynamic contribution
     * item contributes items conditionally, dependent on some internal state.
     *
     * @return true if this item is dynamic, and
     *  false for normal items
     */
    public boolean isDynamic();

    /**
     * Returns whether this contribution item is a group marker.
     * This information is used when adding items to a group.
     *
     * @return true if this item is a group marker, and
     *  false for normal items
     *
     * @see GroupMarker
     * @see IContributionManager#appendToGroup(String, IContributionItem)
     * @see IContributionManager#prependToGroup(String, IContributionItem)
     */
    public boolean isGroupMarker();

    /**
     * Returns whether this contribution item is a separator.
     * This information is used to enable hiding of unnecessary separators.
     *
     * @return true if this item is a separator, and
     *  false for normal items
     * @see Separator
     */
    public boolean isSeparator();

    /**
     * Returns whether this contribution item is visibile within its manager.
     *
     * @return true if this item is visible, and
     *  false otherwise
     */
    public boolean isVisible();

    /**
     * Saves any state information of the control(s) owned by this contribution item.
     * The contribution manager calls this method before disposing of the controls.
     *
     * @since 3.0
     */
    public void saveWidgetState();

    /**
     * Sets the parent manager of this item
     *
     * @param parent the parent contribution manager
     * @since 2.0
     */
    public void setParent(IContributionManager parent);

    /**
     * Sets whether this contribution item is visibile within its manager.
     *
     * @param visible true if this item should be visible, and
     *  false otherwise
     */
    public void setVisible(boolean visible);

    /**
     * Updates any SWT controls cached by this contribution item with any
     * changes which have been made to this contribution item since the last update.
     * Called by contribution manager update methods.
     */
    public void update();

    /**
     * Updates any SWT controls cached by this contribution item with changes
     * for the the given property.
     *
     * @param id the id of the changed property
     * @since 2.0
     */
    public void update(String id);
}