01: /*
02: * Engine.java
03: *
04: * Created on January 24, 2004, 1:31 AM
05: */
06:
07: package org.netbeans.actions.api;
08:
09: import javax.swing.ActionMap;
10: import javax.swing.InputMap;
11: import javax.swing.JComponent;
12: import javax.swing.JMenuBar;
13: import javax.swing.JPopupMenu;
14: import javax.swing.JToolBar;
15: import javax.swing.text.Keymap;
16:
17: /** The Engine is responsible for the relationship between the user context
18: * (selected object, window, whatever can influence action presence or
19: * enablement). By design it does not use a "push" model, but
20: * rather a "pull" model. That is, it, and only it, manages the
21: * state of the action presenters in the system. It is responsible for
22: * deciding when something needs to be displayed/painted/updated. The
23: * system can provide hints that now would be a good time to update something,
24: * but it will decide what to do.
25: * <p>
26: * For toolbar enablement, the intention is to implement handling enablement
27: * issues using a polling model - rather than trying to push updates for
28: * every change in context (lots of work and most of the time nothing changes),
29: * it will perform such updates in a timely way, but based on its analysis of
30: * the current circumstances. This may be influenced by such things as requests
31: * for visibility on its presenters, idle time in the AWT thread, a timer or
32: * the phase of the moon. In practice the visual result should be no different
33: * than that of a push model, except that it does far less work.
34: * <p>
35: * Note the complete absence of use of the listener pattern - this is by design.
36: *
37: * @author Tim Boudreau
38: */
39: public abstract class Engine {
40: /** Sets the ContextProvider that the engine will ask for the current
41: * user context (selected object, etc.) when it deems it necessary to
42: * update or instantiate presenter components */
43: public abstract void setContextProvider(ContextProvider ctx);
44:
45: /** Method by which the infrastructure can suggest that now is a good time
46: * to update the state of toolbars, etc. Calling this method amounts to
47: * making a suggestion - like calling System.gc(), there is no guarantee
48: * that an implementation will immediately update its presenters.
49: */
50: public abstract void recommendUpdate();
51:
52: public abstract JMenuBar createMenuBar();
53:
54: public abstract JToolBar[] createToolbars();
55:
56: /** Create an input map. Will return an instance of ComponentInputMap
57: * (needed so the resulting input map can be used
58: * as a master input map for an application, i.e. set against
59: * WHEN_IN_FOCUSED_WINDOW). */
60: public abstract InputMap createInputMap(JComponent jc);
61:
62: public abstract ActionMap createActionMap();
63:
64: public abstract JPopupMenu createPopupMenu();
65:
66: }
|