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.window;
17
18 import net.sf.jguiraffe.gui.builder.event.FormMouseListener;
19
20 /**
21 * <p>
22 * Definition of an interface for describing windows in a platform independent
23 * way.
24 * </p>
25 * <p>
26 * This interface is an abstraction of a typical window. It defines methods for
27 * querying and setting window related properties. For each supported GUI
28 * library (or platform) there will be an implementation that hides the
29 * specifics of window objects of that library. So application code can simply
30 * manipulate these objects through the methods provided here.
31 * </p>
32 *
33 * @author Oliver Heger
34 * @version $Id: Window.java 205 2012-01-29 18:29:57Z oheger $
35 */
36 public interface Window
37 {
38 /**
39 * Returns a flag if this window is visible.
40 *
41 * @return the visible flag
42 */
43 boolean isVisible();
44
45 /**
46 * Sets the window's visible flag. This method can be used to hide and later
47 * show the window again.
48 *
49 * @param f the flag's value
50 */
51 void setVisible(boolean f);
52
53 /**
54 * Opens the window. This method must be called to make the window visible
55 * for the first time.
56 */
57 void open();
58
59 /**
60 * Closes this window. This should cause all resources obtained by the
61 * window to be freed. After invocation, the window instance should not be
62 * used any longer. The {@code force} parameter determines whether the
63 * window's {@link WindowClosingStrategy} is to be invoked: if set to
64 * <b>false</b>, the {@link WindowClosingStrategy} is queried, and the
65 * window is only closed if permitted. Otherwise, the window is always
66 * closed. The return value indicates the success of the operation. A value
67 * of <b>false</b> means that the window could not be closed because the
68 * {@link WindowClosingStrategy} prohibited this operation.
69 *
70 * @param force a flag whether the window is to be closed unconditionally
71 * @return a flag whether this operation was successful
72 */
73 boolean close(boolean force);
74
75 /**
76 * Returns the window's x position.
77 *
78 * @return the window's x position
79 */
80 int getXPos();
81
82 /**
83 * Returns the window's y position.
84 *
85 * @return the window's y position
86 */
87 int getYPos();
88
89 /**
90 * Returns the window's width.
91 *
92 * @return the window's width
93 */
94 int getWidth();
95
96 /**
97 * Returns the window's height.
98 *
99 * @return the window's height
100 */
101 int getHeight();
102
103 /**
104 * Allows to set the window's bounds. This method can be called to position
105 * and/or resize the window.
106 *
107 * @param x the new x position
108 * @param y the new y position
109 * @param w the new width
110 * @param h the new height
111 */
112 void setBounds(int x, int y, int w, int h);
113
114 /**
115 * Returns the window's title.
116 *
117 * @return the title (can be <b>null</b>)
118 */
119 String getTitle();
120
121 /**
122 * Sets the window's title.
123 *
124 * @param s the new title
125 */
126 void setTitle(String s);
127
128 /**
129 * Returns the (platform independent abstraction of) window's parent window.
130 * For top level windows this method will return <b>null</b>.
131 *
132 * @return the window's parent window
133 */
134 Window getParentWindow();
135
136 /**
137 * Adds a window listener for this window.
138 *
139 * @param l the listener to add
140 */
141 void addWindowListener(WindowListener l);
142
143 /**
144 * Removes a window listener for this window.
145 *
146 * @param l the listener to remove
147 */
148 void removeWindowListener(WindowListener l);
149
150 /**
151 * Returns the current <code>WindowClosingStrategy</code> of this window.
152 *
153 * @return the <code>WindowClosingStrategy</code>; this can be <b>null</b>
154 */
155 WindowClosingStrategy getWindowClosingStrategy();
156
157 /**
158 * Sets the <code>WindowClosingStrategy</code> for this window. This
159 * object checks if a window can be closed.
160 *
161 * @param windowClosingStrategy the new <code>WindowClosingStrategy</code>
162 */
163 void setWindowClosingStrategy(WindowClosingStrategy windowClosingStrategy);
164
165 /**
166 * Returns the controller object for this window. The window's controller is
167 * a simple POJO provided by the application that can react on window or
168 * component events, thus acting as a typical controller.
169 *
170 * @return the window's controller (can be <b>null</b> if no controller was
171 * specified when the window was created)
172 */
173 Object getWindowController();
174
175 /**
176 * Returns the window's root container. This container must be known if new
177 * components should be added to the window, especially during the builder
178 * process.
179 *
180 * @return the window's root container
181 */
182 Object getRootContainer();
183
184 /**
185 * Adds a listener for mouse events to this window. The listener is then
186 * informed about the standard mouse events supported by the
187 * platform-independent {@code FormMouseListener} interface.
188 *
189 * @param l the mouse listener to be added
190 */
191 void addMouseListener(FormMouseListener l);
192
193 /**
194 * Removes the specified mouse listener from this window. If the listener
195 * was not registered, this method has no effect.
196 *
197 * @param l the listener to remove
198 */
199 void removeMouseListener(FormMouseListener l);
200 }