/*
 * @(#)MenuBuilder.java
 * 
 * Copyright (c) 2010 by the original authors of JHotDraw and all its
 * contributors. All rights reserved.
 * 
 * You may not use, copy or modify this file, except in compliance with the 
 * license agreement you entered into with the copyright holders. For details
 * see accompanying license terms.
 */
package org.jhotdraw.app;

import edu.umd.cs.findbugs.annotations.Nullable;
import java.util.List;
import javax.swing.JMenu;

/**
 * {@code MenuBuilder} is used by {@link Application} to build to build its menu
 * bar(s) and popup menu(s).
 * 

* Each method adds a logical group of menu items to a menu provided by the * {@code Application}. *

* Implementors of this interface typically use actions retrieved from the * application to build the menu items. See {@link DefaultMenuBuilder} for a * typical implementation. *

* Menus may be associated to a specific view or to all views (global) of the * application. In the former case the corresponding view is provided, in the * latter case null is passed. Note that some applications, specifically * {@link OSXApplication}, need to create both kinds of menus. *

* During the lifetime of an application many menus may be created and destroyed. * Implementors must take care that menu items can be garbage collected. * *


* Design Patterns * *

Abstract Factory
* {@code MenuBuilder} is used by {@code Application} for creating menu items. * The {@code MenuBuilder} is provided by {@code ApplicationModel}. * Abstract Factory: {@link MenuBuilder}
* Client: {@link Application}. *


* * @author Werner Randelshofer * @version $Id: MenuBuilder.java 719 2010-11-22 16:53:51Z rawcoder $ */ public interface MenuBuilder { /** Optionally adds one or more "Preferences" items to a menu. *

* Most applications use this method for adding items to the last section * of the "Edit" menu. *

* Note that {@link OSXApplication} does not invoke this method and * instead retrieves an action with ID {@code AbstractPreferencesAction.ID} * from the action map of the {@code ApplicationModel} and adds it to the * "Application" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addPreferencesItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Exit" items to a menu. *

* Most applications use this method for adding items to the last section * of the "File" menu. *

* Note that {@link OSXApplication} does not invoke this method and * instead retrieves an action with ID {@code ExitAction.ID} * from the action map of the {@code ApplicationModel} and adds it to the * "Application" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addExitItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Clear File" items to a menu. *

* Most applications use this method for adding items to the first section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addClearFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "New Window" items to a menu. *

* Most applications use this method for adding items to the first section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addNewWindowItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "New File" items to a menu. *

* Most applications use this method for adding items to the first section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addNewFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Load file" items to a menu. *

* Most applications use this method for adding items to the first section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addLoadFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Open File" items to a menu. *

* Most applications use this method for adding items to the first section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addOpenFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Close File" items to a menu. *

* Most applications use this method for adding items to the second section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addCloseFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Save File" items to a menu. *

* Most applications use this method for adding items to the second section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addSaveFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Export File" items to a menu. *

* Most applications use this method for adding items to the second section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addExportFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Print File" items to a menu. *

* Most applications use this method for adding items to the third section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addPrintFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more file related items to a menu. *

* Most applications use this method for adding items to the third section * of the "File" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addOtherFileItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Undo" items to a menu. *

* Most applications use this method for adding items to the first section * of the "Edit" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addUndoItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Clipboard" items to a menu. *

* Most applications use this method for adding items to the second section * of the "Edit" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addClipboardItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Selection" items to a menu. *

* Most applications use this method for adding items to the third section * of the "Edit" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addSelectionItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Find" items to a menu. *

* Most applications use this method for adding items to the fourth section * of the "Edit" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addFindItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more editing related items to a menu. *

* Most applications use this method for adding items to the fifth section * of the "Edit" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addOtherEditItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more view related items to a menu. *

* Most applications use this method for adding items to the first section * of the "View" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addOtherViewItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more additional menus to a menu bar or a pop up * menu. *

* Most applications add additional menus between the "View" menu and the * "Window" menu to the menu bar. * * @param m A (potentially non-empty) list of menus. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addOtherMenus(List m, Application app, @Nullable View v); /** Optionally adds one or more window related items to a menu. *

* Most applications use this method for adding items to the second section * of the "Window" menu. (The first section usually contains application * specific items). Some applications, such as {@link SDIApplication} add * these items to the "View" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addOtherWindowItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "Help" items to a menu. *

* Most applications use this method for adding items to the first section * of the "Help" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addHelpItems(JMenu m, Application app, @Nullable View v); /** Optionally adds one or more "About" items to a menu. *

* Most applications use this method for adding items to the last section * of the "Help" menu. *

* Note that {@link OSXApplication} does not invoke this method and * instead retrieves an action with ID {@code AboutAction.ID} * from the action map of the {@code ApplicationModel} and adds it to the * "Application" menu. * * @param m A (potentially non-empty) menu. * @param app The Application for which the menu is built. * @param v A view the menu is used exclusively for a specific view, null * if the menu is shared by all views. */ void addAboutItems(JMenu m, Application app, @Nullable View v); }

Ads help maintain this website.