01: /*
02: * ActionProvider.java
03: *
04: * Created on January 24, 2004, 12:26 AM
05: */
06:
07: package org.netbeans.actions.spi;
08:
09: import java.util.Map;
10: import javax.swing.Icon;
11:
12: /** The heart of the actions framework from the application author's perspective -
13: * the implementation of this class supplies the available actions in a given
14: * context. Note that this class neither constructs Action objects, nor menu
15: * items or other visual components - these are only needed when something
16: * needs to be shown or updated, and the engine will provide
17: * items to display them as needed.
18: * <p>
19: * This works as follows: When menus or toolbars need to be displayed/created/
20: * updated, the Engine will ask its master ActionProvider for the actionNames
21: * for each container context. A container context is simply a programmatic
22: * name for a menu, toolbar, etc. It will then iterate those names, calling
23: * the other methods like getDisplayName, to get the relevant data that is
24: * needed by the presenter to display them, and use that information to
25: * correctly configure the presenters.
26: * <p>
27: * The programmatic names that will be passed in are a private contract between
28: * an implementation and its method of registering actions in the system. For
29: * example, an implementation may allow components to register menus and
30: * toolbars in an XML file; so the names for, e.g., menus will be provided
31: * there. An application's documentation will specify how to register
32: * actions, contexts, etc. and its implementation of ActionProvider will
33: * use this registry to look up information about actions.
34: * <p>
35: * The only method that is passed any state information about the application
36: * is getState(). This call is used to determine if a presenter is visible
37: * and enabled or disabled, which is all the information that is needed to
38: * display a presenter correctly. It is passed a Map which contains all
39: * the available information about the current user context (what object
40: * is selected, what window is focused, etc.) The implementation can query
41: * the map, to decide what to display and its state. The actual contents of this map are
42: * a private contract with a given implementation. For example, in NetBeans,
43: * the Map will probably be a wrapper for the selected node and its Lookup.
44: *
45: * @author Tim Boudreau
46: */
47: public abstract class ActionProvider {
48: public static final int STATE_ENABLED = 1;
49: public static final int STATE_VISIBLE = 2;
50: public static final int STATE_SELECTED = 4;
51:
52: public static final int ACTION_TYPE_ITEM = 0;
53: public static final int ACTION_TYPE_SUBCONTEXT = 1;
54: public static final int ACTION_TYPE_TOGGLE = 2;
55:
56: /** Get the programmatic names (not display names) for all of the actions
57: * in a given context. The result should include <strong>all</strong>
58: * actions registered for that context whether or not they're enabled/displayed/etc.
59: * getState() will be called later for each to decide if they should be
60: * presented currently, or hidden. */
61: public abstract String[] getActionNames(String containerCtx);
62:
63: /** Get the display name for a given action name returned from getActionNames,
64: * in a given logical action container (toolbar, menu, etc) */
65: public abstract String getDisplayName(String actionName,
66: String containerCtx);
67:
68: /** Get the action type. This will not be called for toolbars, but will be
69: * called for menus to determine if a submenu presenter or a menu item
70: * presenter is needed */
71: public abstract int getActionType(String actionName,
72: String containerCtx);
73:
74: /** Get a description for an action appropriate for use in a tooltip. Used
75: * for toolbar presenters. */
76: public abstract String getDescription(String actionName,
77: String containerCtx);
78:
79: /** Get the icon, if any, for a given action. The type argument is as defined
80: * in BeanInfo */
81: public abstract Icon getIcon(String actionName,
82: String containerCtx, int type);
83:
84: /** Get the mnemonic to be used for action text */
85: public abstract int getMnemonic(String actionName,
86: String containerCtx);
87:
88: /** Get the displayed mnemonic index for action text */
89: public abstract int getMnemonicIndex(String actionName,
90: String containerCtx);
91:
92: /** Get the enablement/visibility state of the named action, given the
93: * passed user context map. */
94: public abstract int getState(String actionName,
95: String containerCtx, Map context);
96:
97: }
|