org.eclipse.jface.action.IMenuManager.java Source code

Introduction

Here is the source code for org.eclipse.jface.action.IMenuManager.java

Source

/*******************************************************************************
 * Copyright (c) 2000, 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.action;

/**
 * The <code>IMenuManager</code> interface provides protocol for managing
 * contributions to a menu bar and its sub menus. An <code>IMenuManager</code>
 * is also an <code>IContributionItem</code>, allowing sub-menus to be nested in
 * parent menus.
 * <p>
 * This interface is internal to the framework; it should not be implemented
 * outside the framework.
 * </p>
 * <p>
 * This package provides a concrete menu manager implementation,
 * {@link MenuManager MenuManager}.
 * </p>
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IMenuManager extends IContributionManager, IContributionItem {
    /**
     * Adds a menu listener to this menu.
     * Has no effect if an identical listener is already registered.
     *
     * @param listener a menu listener
     */
    public void addMenuListener(IMenuListener listener);

    /**
     * Finds the manager for the menu at the given path. A path
     * consists of contribution item ids separated by the separator
     * character.  The path separator character is <code>'/'</code>.
     * <p>
     * Convenience for <code>findUsingPath(path)</code> which
     * extracts an <code>IMenuManager</code> if possible.
     * </p>
     *
     * @param path the path string
     * @return the menu contribution item, or <code>null</code>
     *   if there is no such contribution item or if the item does
     *   not have an associated menu manager
     */
    public IMenuManager findMenuUsingPath(String path);

    /**
     * Finds the contribution item at the given path. A path
     * consists of contribution item ids separated by the separator
     * character. The path separator character is <code>'/'</code>.
     *
     * @param path the path string
     * @return the contribution item, or <code>null</code> if there is no
     *   such contribution item
     */
    public IContributionItem findUsingPath(String path);

    /**
     * Returns whether all items should be removed when the menu is about to
     * show, but before notifying menu listeners. The default is
     * <code>false</code>.
     *
     * @return <code>true</code> if all items should be removed when shown,
     *         <code>false</code> if not
     */
    public boolean getRemoveAllWhenShown();

    /**
     * Returns whether this menu should be enabled or not.
     *
     * @return <code>true</code> if enabled, and
     *   <code>false</code> if disabled
     */
    @Override
    public boolean isEnabled();

    /**
     * Removes the given menu listener from this menu.
     * Has no effect if an identical listener is not registered.
     *
     * @param listener the menu listener
     */
    public void removeMenuListener(IMenuListener listener);

    /**
     * Sets whether all items should be removed when the menu is about to show,
     * but before notifying menu listeners.
     *
     * @param removeAll
     *            <code>true</code> if all items should be removed when shown,
     *            <code>false</code> if not
     */
    public void setRemoveAllWhenShown(boolean removeAll);

    /**
     * Incrementally builds the menu from the contribution items, and
     * does so recursively for all submenus.
     *
     * @param force <code>true</code> means update even if not dirty,
     *   and <code>false</code> for normal incremental updating
     */
    public void updateAll(boolean force);
}