/*******************************************************************************
* 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;
/**
* 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 <code>MenuManager</code>}.
* </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);
}