1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.action;
17
18 import net.sf.jguiraffe.gui.builder.components.ComponentBuilderData;
19 import net.sf.jguiraffe.gui.builder.components.tags.TextIconData;
20 import net.sf.jguiraffe.gui.forms.ComponentHandler;
21
22 /**
23 * <p>
24 * Definition of an interface for a component that creates GUI library specific
25 * action objects and related classes.
26 * </p>
27 * <p>
28 * This interface plays a similar role for the action builder as the
29 * {@link net.sf.jguiraffe.gui.forms.components.ComponentManager ComponentManager}
30 * interface for the form builder: It hides the details of creating GUI library
31 * specific objects. Instead of form elements this interface deals with objects
32 * like actions, menus, and toolbar buttons.
33 * </p>
34 * <p>
35 * There will be concrete implementations of this interface for all supported
36 * GUI libraries. When the action builder is invoked, an implementation must be
37 * provided. This object is then accessed by Jelly tag handler classes to create
38 * the objects they represent. With the objects created by this implementation
39 * the action related components of an application can be constructed.
40 * </p>
41 * <p>
42 * <strong>Note:</strong> This interface is not intended to be directly
43 * implemented by client code. It is subject to change even in minor releases as
44 * new features are made available. Therefore if an application needs to provide
45 * a custom implementation of this interface, it should extend an existing
46 * implementation. For instance, the {@link ActionManagerWrapper} class is a
47 * good candidate if only a subset of methods is to be modified.
48 * </p>
49 *
50 * @author Oliver Heger
51 * @version $Id: ActionManager.java 205 2012-01-29 18:29:57Z oheger $
52 */
53 public interface ActionManager
54 {
55 /**
56 * Creates an action object based on the provided information.
57 *
58 * @param actionBuilder the central builder data object
59 * @param actionData an object with all information about the action to
60 * create
61 * @return the new action object
62 * @throws FormActionException if an error occurs
63 */
64 FormAction createAction(ActionBuilder actionBuilder, ActionData actionData)
65 throws FormActionException;
66
67 /**
68 * Creates a menu item based on the specified action object. The menu item
69 * will be associated with the given action. Its properties (e.g. text and
70 * icon) will be obtained from the action, too.
71 *
72 * @param actionBuilder the action builder
73 * @param action the action
74 * @param checked a flag if a checked menu item should be created
75 * @param parent the parent menu to which the new item should be added
76 * @return the new menu item
77 * @throws FormActionException if an error occurs
78 */
79 Object createMenuItem(ActionBuilder actionBuilder, FormAction action,
80 boolean checked, Object parent) throws FormActionException;
81
82 /**
83 * Creates a menu item based on the specified action data object and returns
84 * a component handler for it. The data of this component handler will be a
85 * boolean value representing the checked state for checked menu items. For
86 * other menu items it is undefined.
87 *
88 * @param actionBuilder the action builder
89 * @param actionData an object with all information about the menu item
90 * @param checked a flag if a checked menu item should be created
91 * @return a component handler for the new menu item
92 * @param parent the parent menu to which the new item should be added
93 * @throws FormActionException if an error occurs
94 */
95 ComponentHandler<?> createMenuItem(ActionBuilder actionBuilder,
96 ActionData actionData, boolean checked, Object parent)
97 throws FormActionException;
98
99 /**
100 * Creates a menu bar. Later defined (sub) menus will be added to this bar.
101 *
102 * @param actionBuilder the action builder
103 * @return the new menu bar
104 * @throws FormActionException if an error occurs
105 */
106 Object createMenuBar(ActionBuilder actionBuilder)
107 throws FormActionException;
108
109 /**
110 * Creates a (sub) menu. The new menu will be added to the specified parent
111 * menu, which can be either a menu bar or another menu. This method will be
112 * called twice for each menu to be created. In the first call not all
113 * initialization properties might be available (e.g. the icon), but the
114 * menu must be created nevertheless (to allow for the menu items being
115 * added). In the second call missing initialization can be performed. An
116 * implementation should only create an uninitialized menu on the first
117 * call. On the second call it should initialize the menu's properties.
118 *
119 * @param actionBuilder the action builder
120 * @param menu the menu object; this will be <b>null</b> on the first call;
121 * on the second call the object returned by the first call will be passed
122 * @param data data defining the new menu
123 * @param parent the parent menu
124 * @return the new menu
125 * @throws FormActionException if an error occurs
126 */
127 Object createMenu(ActionBuilder actionBuilder, Object menu,
128 TextIconData data, Object parent) throws FormActionException;
129
130 /**
131 * Creates a toolbar object. Later defined toolbar buttons will be added to
132 * this bar.
133 *
134 * @param actionBuilder the action builder
135 * @return the new toolbar object
136 * @throws FormActionException if an error occurs
137 */
138 Object createToolbar(ActionBuilder actionBuilder)
139 throws FormActionException;
140
141 /**
142 * Creates a toolbar button based on the specified action object. The button
143 * will be associated with this action and obtain its properties from there.
144 *
145 * @param actionBuilder the action builder
146 * @param action the action
147 * @param checked a flag if a checked (toggle) button should be created
148 * @param parent the parent component (a toolbar) to which the new button
149 * should be added
150 * @return the new button
151 * @throws FormActionException if an error occurs
152 */
153 Object createToolbarButton(ActionBuilder actionBuilder, FormAction action,
154 boolean checked, Object parent) throws FormActionException;
155
156 /**
157 * Creates a toolbar button based on the given action data object and
158 * returns a component handler for it. The data of this component handler
159 * will be a boolean value representing the checked state for checked
160 * toolbar buttons. For other toolbar buttons it is undefined.
161 *
162 * @param actionBuilder the action builder
163 * @param data a data object defining all properties of the button
164 * @param checked a flag if a checked (toggle) button should be created
165 * @param parent the parent component (a toolbar) to which the new button
166 * should be added
167 * @return a component handler for the new button
168 * @throws FormActionException if an error occurs
169 */
170 ComponentHandler<?> createToolbarButton(ActionBuilder actionBuilder,
171 ActionData data, boolean checked, Object parent)
172 throws FormActionException;
173
174 /**
175 * Adds a separator to the specified menu. The passed in menu object must
176 * have been created using the <code>createMenu()</code> method.
177 *
178 * @param actionBuilder the action builder
179 * @param menu the menu to which the separator should be added
180 * @throws FormActionException if an error occurs
181 */
182 void addMenuSeparator(ActionBuilder actionBuilder, Object menu)
183 throws FormActionException;
184
185 /**
186 * Adds a separator to the specified tool bar. The passed in tool bar object
187 * must have been created using the <code>createToolBar()</code> method.
188 *
189 * @param actionBuilder the action builder
190 * @param toolBar the tool bar to which the separator should be added
191 * @throws FormActionException if an error occurs
192 */
193 void addToolBarSeparator(ActionBuilder actionBuilder, Object toolBar)
194 throws FormActionException;
195
196 /**
197 * Registers the specified <code>PopupMenuHandler</code> at the given UI
198 * component. This will cause the handler to be invoked whenever the user
199 * triggers the context menu for this component (e.g. by right clicking it
200 * with the mouse). A concrete implementation has to install a proper event
201 * listener at the component that takes care of calling the handler when it
202 * detects a gesture that should bring up the context menu.
203 *
204 * @param component the component
205 * @param handler the handler for creating the menu
206 * @param compData the <code>ComponentBuilderData</code> object
207 * @throws FormActionException if an error occurs
208 */
209 void registerPopupMenuHandler(Object component, PopupMenuHandler handler,
210 ComponentBuilderData compData) throws FormActionException;
211 }