1 /*
2 * Copyright 2002-2004 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5 * use this file except in compliance with the License. You may obtain a copy of
6 * 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, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations under
14 * the License.
15 */
16 package org.springframework.richclient.factory;
17
18 import java.awt.Component;
19 import java.awt.LayoutManager;
20
21 import javax.swing.JButton;
22 import javax.swing.JCheckBox;
23 import javax.swing.JComboBox;
24 import javax.swing.JComponent;
25 import javax.swing.JFormattedTextField;
26 import javax.swing.JLabel;
27 import javax.swing.JList;
28 import javax.swing.JMenuItem;
29 import javax.swing.JPanel;
30 import javax.swing.JPasswordField;
31 import javax.swing.JRadioButton;
32 import javax.swing.JTabbedPane;
33 import javax.swing.JTable;
34 import javax.swing.JTextArea;
35 import javax.swing.JTextField;
36 import javax.swing.JScrollPane;
37 import javax.swing.JToggleButton;
38 import javax.swing.JFormattedTextField.AbstractFormatterFactory;
39 import javax.swing.table.TableModel;
40
41 import org.springframework.binding.value.ValueModel;
42 import org.springframework.richclient.util.Alignment;
43
44 /**
45 * A factory interface for encapsulating logic to create well-formed, configured
46 * GUI controls.
47 *
48 * @author Keith Donald
49 */
50 public interface ComponentFactory {
51
52 /**
53 * Create and configure a label with the specified label key. For example:
54 * "&My Control Label:", where the '&' marks a positional mnemonic.
55 *
56 * @param labelKey The label message code; may also be the label text if no
57 * message source is configured.
58 * @return The configured label.
59 */
60 public JLabel createLabel(String labelKey);
61
62 /**
63 * Create and configure a label with the specified label key. For example:
64 * "&My Control Label:", where the '&' marks a positional mnemonic.
65 *
66 * @param labelKey The label message code; may also be the label text if no
67 * message source is configured.
68 * @return The configured label.
69 */
70 public JLabel createLabel(String[] labelKeys);
71
72 /**
73 * Creates and configure a label with the specified label key and
74 * parameterized arguments. Argument values are resolved to {digit
75 * placeholder} characters in the resolved message string.
76 *
77 * @param labelKey
78 * @param arguments
79 * @return The configured label.
80 */
81 public JLabel createLabel(String labelKey, Object[] arguments);
82
83 /**
84 * Creates and configure a label with the specified label key and
85 * parameterized arguments. Argument values are resolved to {digit
86 * placeholder} characters in the resolved message string. Argument values
87 * are pulled from the provided value model, and this component factory will
88 * auto-subscribe for changes, dynamically updating the label when
89 * underlying arguments change.
90 *
91 * @param labelKey
92 * @param argumentValueHolders The value model of the arguments;
93 * @return The configured label.
94 */
95 public JLabel createLabel(String labelKey, ValueModel[] argumentValueHolders);
96
97 /**
98 * Create and configure a title label with the specified label key. A title
99 * label's text matches that of a titled border title (bold, highlighted.)
100 *
101 * @param labelKey The label message code; may also be the label text if no
102 * message source is configured.
103 *
104 * @return The configured label.
105 */
106 public JLabel createTitleLabel(String labelKey);
107
108 /**
109 * Creates a titled border for the specified component.
110 *
111 * @param labelKey the title label message code.
112 * @param comp the component to attach a titled border to.
113 * @return the configured component.
114 */
115 public JComponent createTitledBorderFor(String labelKey, JComponent comp);
116
117 /**
118 * Create and configure a label for the provided component. Associating a
119 * label with a component ensures when the mnemonic is selected the
120 * component is given focus.
121 *
122 * @param labelKey The label message code; may also be the label text if no
123 * message source is configured.
124 * @param comp the labeled component
125 * @return The configured label.
126 */
127 public JLabel createLabelFor(String labelKey, JComponent comp);
128
129 /**
130 * Create and configure a label for the provided component. Associating a
131 * label with a component ensures when the mnemonic is selected the
132 * component is given focus.
133 *
134 * @param labelKey The label message code; may also be the label text if no
135 * message source is configured.
136 * @param comp the labeled component
137 * @return The configured label.
138 */
139 public JLabel createLabelFor(String[] labelKeys, JComponent comp);
140
141 /**
142 * Create and configure a button with the specified label key. The button
143 * will be configured with the appropriate mnemonic and accelerator. Note:
144 * if you find yourself duplicating the same handler logic accross different
145 * buttons, maybe its time to use a Command.
146 *
147 * @param labelKey The label message code; may also be the label text if no
148 * message source is configured.
149 * @return The configured button.
150 */
151 public JButton createButton(String labelKey);
152
153 /**
154 * Create and configure an left-aligned label acting as a form dividing
155 * separator; that is, a control that displays a label and a separator
156 * immediately underneath it.
157 *
158 * @param labelKey The label message code; may also be the label text if no
159 * message source is configured.
160 * @return The configured labeled separator.
161 */
162 public JComponent createLabeledSeparator(String labelKey);
163
164 /**
165 * Create and configure an aligned label acting as a form dividing
166 * separator; that is, a control that displays a label and a separator
167 * immediately underneath it.
168 *
169 * @param labelKey The label message code; may also be the label text if no
170 * message source is configured.
171 * @param alignment The label's alignment.
172 * @return The configured labeled separator.
173 */
174 public JComponent createLabeledSeparator(String labelKey, Alignment alignment);
175
176 /**
177 * Create a list using this component factory.
178 *
179 * @return The new list.
180 */
181 public JList createList();
182
183 /**
184 * Create a combo box using this component factory.
185 *
186 * @return The new combo box.
187 */
188 public JComboBox createComboBox();
189
190 /**
191 * Create a combo box using this component factory. The list of selectable
192 * items is populated from the provided value model, which provides access
193 * to a list. When an item is selected in the list, the
194 * selectedItemValueModel is set.
195 *
196 * @return The new combo box.
197 * @param the value model for the list of selectable items
198 * @param the property to render each item in the list.
199 */
200 public JComboBox createListValueModelComboBox(ValueModel selectedItemValueModel,
201 ValueModel selectableItemsListHolder, String renderedPropertyPath);
202
203 /**
204 * Create a combo box using this component factory, to be populated by the
205 * list of all enums of the specified type, resolved using this factory's
206 * enum resolver.
207 *
208 * @return The new combo box.
209 */
210 public JComboBox createComboBox(Class enumType);
211
212 /**
213 * Configure a combo box to be populated with all enums of the specified
214 * enumeration type. The type must be resolvable by this factory's enum
215 * resolver.
216 *
217 * @param enumType The enumeration type.
218 */
219 public void configureForEnum(JComboBox comboBox, Class enumType);
220
221 /**
222 * Create a configured menu item.
223 *
224 * @param labelKey The label message code; may also be the label text if no
225 * message source is configured.
226 * @return The menu item.
227 */
228 public JMenuItem createMenuItem(String labelKey);
229
230 /**
231 * Create a configured checkbox.
232 *
233 * @param labelKey The label message code; may also be the label text if no
234 * message source is configured.
235 * @return The checkbox.
236 */
237 public JCheckBox createCheckBox(String labelKey);
238
239 /**
240 * Create a configured checkbox.
241 *
242 * @param labelKeys The label message codes; may also be the label text if
243 * no message source is configured.
244 * @return The checkbox.
245 */
246 public JCheckBox createCheckBox(String[] labelKeys);
247
248 /**
249 * Create a configured toggle button.
250 *
251 * @param labelKey The label message code; may also be the label text if no
252 * message source is configured.
253 * @return The toggle button.
254 */
255 public JToggleButton createToggleButton(String labelKey);
256
257 /**
258 * Create a configured toggle button.
259 *
260 * @param labelKeys The label message codes; may also be the label text if
261 * no message source is configured.
262 * @return The toggle button.
263 */
264 public JToggleButton createToggleButton(String[] labelKeys);
265
266 /**
267 * Create a configured radio button.
268 *
269 * @param labelKey The label message code; may also be the label text if no
270 * message source is configured.
271 * @return The radio button.
272 */
273 public JRadioButton createRadioButton(String labelKey);
274
275 /**
276 * Create a configured radio button.
277 *
278 * @param labelKeys The label message codes; may also be the label text if
279 * no message source is configured.
280 * @return The radio button.
281 */
282 public JRadioButton createRadioButton(String[] labelKeys);
283
284 /**
285 * Create a formatted text field using this component factory.
286 *
287 * @param formatterFactory AbstractFormatterFactory used for formatting.
288 * @return The new formatted text field
289 */
290 public JFormattedTextField createFormattedTextField(AbstractFormatterFactory formatterFactory);
291
292 /**
293 * Create a standard text field using this component factory.
294 *
295 * @return the new text field.
296 */
297 public JTextField createTextField();
298
299 /**
300 * Create a standard password field using this component factory.
301 *
302 * @return the new password field.
303 */
304 public JPasswordField createPasswordField();
305
306 /**
307 * Create a text area using this component factory.
308 *
309 * @return The new text area.
310 */
311 public JTextArea createTextArea();
312
313 /**
314 * Create a text area using this component factory.
315 *
316 * @return The new text area.
317 */
318 public JTextArea createTextArea(int row, int columns);
319
320 /**
321 * Create a text area that looks like a label (but with cut/copy/paste
322 * enabled!) using this component factory.
323 *
324 * @return The new text area.
325 */
326 public JTextArea createTextAreaAsLabel();
327
328 /**
329 * Create and return a new tabbed pane.
330 *
331 * @return a new tabbed pane.
332 */
333 public JTabbedPane createTabbedPane();
334
335 /**
336 * Adds a tab to the provided tabbed pane, configuring the tab's appearance
337 * from information retrieved using the <code>labelKey</code> property.
338 * The tab title text, icon, mnemonic, and mnemonic index are all
339 * configurable.
340 *
341 * @param tabbedPane
342 * @param labelKey
343 * @param tabComponent
344 */
345 public void addConfiguredTab(JTabbedPane tabbedPane, String labelKey, JComponent tabComponent);
346
347 /**
348 * Create a scroll pane using this component factory.
349 *
350 * @return empty scroll pane.
351 * @see javax.swing.JScrollPane#JScrollPane()
352 */
353 public JScrollPane createScrollPane();
354
355 /**
356 * Create a scroll pane using this component factory, with the specified
357 * component as the viewport view.
358 *
359 * @param view the component to display in the scrollpane's viewport
360 * @return scroll pane with specified view
361 * @see JScrollPane#JScrollPane(java.awt.Component)
362 */
363 public JScrollPane createScrollPane(Component view);
364
365 /**
366 * Create a scroll pane using this component factory, with the specified
367 * component as the viewport view and with the specified vertical and
368 * horizontal scrollbar policies.
369 *
370 * @param view the component to display in the scrollpane's viewport
371 * @param vsbPolicy set the vertical scrollbar policy.
372 * @param hsbPolicy set the horizontal scrollbar policy.
373 * @return scroll pane with specified view and scrolling policies
374 * @see JScrollPane#JScrollPane(java.awt.Component, int, int)
375 */
376 public JScrollPane createScrollPane(Component view, int vsbPolicy, int hsbPolicy);
377
378 /**
379 * Creates a panel using this component factory.
380 *
381 * @return the panel
382 * @see JPanel
383 */
384 public JPanel createPanel();
385
386 /**
387 * Creates a panel with the supplied LayoutManager using this component
388 * factory.
389 *
390 * @param layoutManager the LayoutManager that will be used by the returned
391 * panel
392 * @return a panel
393 * @see JPanel#JPanel(java.awt.LayoutManager)
394 */
395 public JPanel createPanel(LayoutManager layoutManager);
396
397 /**
398 * Construct a JTable with a default model.
399 * @return new table instance
400 */
401 public JTable createTable();
402
403 /**
404 * Construct a JTable with the specified table model.
405 * @param model TableModel to install into the new table
406 * @return new table instance
407 */
408 public JTable createTable(TableModel model);
409
410 /**
411 * Construct a JToolBar.
412 * @return new toolbar instance
413 */
414 public JComponent createToolBar();
415
416 }