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.components;
17
18 /**
19 * <p>
20 * Definition of an interface for dealing with widgets.
21 * </p>
22 * <p>
23 * A <em>widget</em> is an arbitrary GUI element. It can be an input element
24 * like a text field, or a checkbox, but also a simple graphical element like a
25 * label, or a panel. Through the methods provided by this interface such
26 * widgets can be manipulated; for instance they can be made invisible, or their
27 * colors can be changed. This way it is possible to change the GUI dynamically.
28 * </p>
29 * <p>
30 * {@link ComponentBuilderData} provides methods for obtaining
31 * the widgets created during the latest builder operation by name. After a
32 * <code>WidgetHandler</code> has been obtained this way, it can be used for
33 * doing something with the corresponding widget.
34 * </p>
35 * <p>
36 * <strong>Note:</strong> This interface is not intended to be directly
37 * implemented by client code. It is subject to change even in minor releases as
38 * new features are made available.
39 * </p>
40 *
41 * @author Oliver Heger
42 * @version $Id: WidgetHandler.java 205 2012-01-29 18:29:57Z oheger $
43 */
44 public interface WidgetHandler
45 {
46 /**
47 * Returns a reference to the underlying widget. This is the
48 * platform-specific GUI control. For instance, if Swing was used as GUI
49 * platform, a <code>Component</code> object would be returned.
50 *
51 * @return the underlying GUI control
52 */
53 Object getWidget();
54
55 /**
56 * Returns a flag whether the wrapped widget is currently visible.
57 *
58 * @return the visible flag of the wrapped widget
59 */
60 boolean isVisible();
61
62 /**
63 * Sets the visible flag of the wrapped widget. Using this method a widget
64 * can be hidden and made visible again.
65 *
66 * @param f the visible flag of the wrapped widget
67 */
68 void setVisible(boolean f);
69
70 /**
71 * Returns the background color of the underlying widget.
72 *
73 * @return the background color of this widget
74 */
75 Color getBackgroundColor();
76
77 /**
78 * Sets the background color of the underlying widget.
79 *
80 * @param c the new background color (as a platform-independent
81 * <code>Color</code> object); if the passed in color object is <b>null</b>,
82 * this operation has no effect
83 */
84 void setBackgroundColor(Color c);
85
86 /**
87 * Returns the foreground color of the underlying widget.
88 *
89 * @return the foreground color of this widget
90 */
91 Color getForegroundColor();
92
93 /**
94 * Sets the foreground color of the underlying widget.
95 *
96 * @param c the new background color (as a platform-independent
97 * <code>Color</code> object); if the passed in color object is <b>null</b>,
98 * this operation has no effect
99 */
100 void setForegroundColor(Color c);
101
102 /**
103 * Returns the tool tip text of the underlying widget. This can be
104 * <b>null</b> if no tool tip was set. Note: It is possible that an
105 * implementation returns a different tool tip text than the one passed to
106 * {@link #setToolTip(String)}. This is due to the fact that certain control
107 * characters like line feeds may have to be converted by a concrete
108 * implementation. To avoid confusion related to changed tool tips client
109 * code should only interact with the {@link ToolTipManager} to manipulate
110 * tool tips.
111 *
112 * @return the tool tip of this widget
113 */
114 String getToolTip();
115
116 /**
117 * Sets the tool tip text of the underlying widget. Note: Client code should
118 * not call this method directly. Rather, the {@link ToolTipManager} should
119 * be used for setting tool tips for widgets.
120 *
121 * @param tip the new tool tip text
122 */
123 void setToolTip(String tip);
124
125 /**
126 * Returns the font of this widget. This is a platform-specific object.
127 *
128 * @return the font of this widget
129 */
130 Object getFont();
131
132 /**
133 * Sets the font of this widget. The font is a platform-specific object. It
134 * can be created in builder scripts using the {@code <f:font>} tag or
135 * directly using the {@code createFont()} method of
136 * {@link ComponentManager}. Concrete implementations may throw a runtime
137 * exception if the font object passed to this method is invalid.
138 *
139 * @param font the font to be set
140 */
141 void setFont(Object font);
142 }