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.forms;
17
18 /**
19 * <p>
20 * Definition of an interface for accessing GUI components independently from
21 * their type.
22 * </p>
23 * <p>
24 * This interface represents a Java GUI widget like a text field or a checkbox.
25 * There will be concrete implementations for real components, which implement
26 * data exchange.
27 * </p>
28 * <p>
29 * The form framework uses implementations of this interface to transfer data
30 * from and to GUI components. The details of this data transfer are hidden by
31 * concrete implementations. This makes it possible for instance to read a
32 * complete form and store the entered data in a bean.
33 * </p>
34 *
35 * @author Oliver Heger
36 * @version $Id: ComponentHandler.java 205 2012-01-29 18:29:57Z oheger $
37 * @param <T> the data type used by this component handler
38 */
39 public interface ComponentHandler<T>
40 {
41 /**
42 * Returns a reference to the real component that is wrapped by this
43 * component handler.
44 *
45 * @return the underlying component
46 */
47 Object getComponent();
48
49 /**
50 * Returns the outer most component, which is the component to be added to
51 * the enclosing container. It may sometimes be necessary that for one GUI
52 * widget not a single component can be created, but multiple ones are
53 * necessary. An example would be a text area in Swing, which is comprised
54 * of the Swing text area itself plus a scroll pane object. In this example
55 * the outer component would be the scroll pane, the component (returned by
56 * <code>{@link #getComponent()}</code> would be the text area. The
57 * mechanism with the outer component allows a GUI library specific
58 * implementation to construct composite components for certain complex
59 * widgets, but from the client's view they behave like a single one.
60 *
61 * @return the outer component
62 */
63 Object getOuterComponent();
64
65 /**
66 * Returns the data of the wrapped component. This is the data the user has
67 * entered, e.g. text.
68 *
69 * @return the component's data
70 */
71 T getData();
72
73 /**
74 * Sets the data of the wrapped component. This method can be used to
75 * initialize GUI widgets, e.g. to set default text at start up.
76 *
77 * @param data the data to set
78 */
79 void setData(T data);
80
81 /**
82 * Returns the data type used by this component. The <code>Class</code>
83 * object returned here determines, which type is allowed for the
84 * <code>getData()</code> and <code>setData()</code> methods. It depends
85 * on the concrete GUI component. For text fields it will be a string, for
86 * checkboxes probably a boolean etc.
87 *
88 * @return the data type used by this component
89 */
90 Class<?> getType();
91
92 /**
93 * Returns a flag whether this component is enabled.
94 *
95 * @return the enabled flag
96 */
97 boolean isEnabled();
98
99 /**
100 * Allows to set the enabled flag. A disabled component cannot be focused
101 * and does not accept user input.
102 *
103 * @param f the value of the enabled flag
104 */
105 void setEnabled(boolean f);
106 }