Mercurial > fife-parpg

comparison ext/guichan-0.8.2/include/guichan/focushandler.hpp @ 378:64738befdf3b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bringing in the changes from the build_system_rework branch in preparation for the 0.3.0 release. This commit will require the Jan2010 devkit. Clients will also need to be modified to the new way to import fife.
author vtchill@33b003aa-7bff-0310-803a-e67f0ece8222
date Mon, 11 Jan 2010 23:34:52 +0000
parents
children
comparison
equal deleted inserted replaced
377:fe6fb0e0ed23 378:64738befdf3b
1 /* _______ __ __ __ ______ __ __ _______ __ __
2 * / _____/\ / /\ / /\ / /\ / ____/\ / /\ / /\ / ___ /\ / |\/ /\
3 * / /\____\// / // / // / // /\___\// /_// / // /\_/ / // , |/ / /
4 * / / /__ / / // / // / // / / / ___ / // ___ / // /| ' / /
5 * / /_// /\ / /_// / // / // /_/_ / / // / // /\_/ / // / | / /
6 * /______/ //______/ //_/ //_____/\ /_/ //_/ //_/ //_/ //_/ /|_/ /
7 * \______\/ \______\/ \_\/ \_____\/ \_\/ \_\/ \_\/ \_\/ \_\/ \_\/
8 *
9 * Copyright (c) 2004 - 2008 Olof Naessén and Per Larsson
10 *
11 *
12 * Per Larsson a.k.a finalman
13 * Olof Naessén a.k.a jansem/yakslem
14 *
15 * Visit: http://guichan.sourceforge.net
16 *
17 * License: (BSD)
18 * Redistribution and use in source and binary forms, with or without
19 * modification, are permitted provided that the following conditions
20 * are met:
21 * 1. Redistributions of source code must retain the above copyright
22 * notice, this list of conditions and the following disclaimer.
23 * 2. Redistributions in binary form must reproduce the above copyright
24 * notice, this list of conditions and the following disclaimer in
25 * the documentation and/or other materials provided with the
26 * distribution.
27 * 3. Neither the name of Guichan nor the names of its contributors may
28 * be used to endorse or promote products derived from this software
29 * without specific prior written permission.
30 *
31 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
32 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
33 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
34 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
35 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
36 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
37 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
38 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
39 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
40 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
41 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 */
43
44 #ifndef GCN_FOCUSHANDLER_HPP
45 #define GCN_FOCUSHANDLER_HPP
46
47 #include <vector>
48
49 #include "guichan/event.hpp"
50 #include "guichan/platform.hpp"
51
52 namespace gcn
53 {
54 class Widget;
55
56 /**
57 * Handles focus for widgets in a Gui. Each Gui has at least one
58 * focus handler.
59
60 * You will probably not use the focus handler directly as Widget
61 * has functions that automatically uses the active focus handler.
62 *
63 * @see Widget::isFocus, Widget::isModalFocused,
64 * Widget::isModalMouseInputFocused, Widget::requestFocus,
65 * Widget::requestModalFocus, Widget::requestModalMouseInputFocus,
66 * Widget::releaseModalFocus, Widget::relaseModalMouseInputFocus,
67 * Widget::setFocusable, Widget::isFocusable, FocusListener
68 *
69 * @since 0.1.0
70 */
71 class GCN_CORE_DECLSPEC FocusHandler
72 {
73 public:
74
75 /**
76 * Constructor.
77 */
78 FocusHandler();
79
80 /**
81 * Destructor.
82 */
83 virtual ~FocusHandler() { };
84
85 /**
86 * Requests focus for a widget. Focus will only be granted to a widget
87 * if it's focusable and if no other widget has modal focus.
88 * If a widget receives focus a focus event will be sent to the
89 * focus listeners of the widget.
90 *
91 * @param widget The widget to request focus for.
92 * @see isFocused, Widget::requestFocus
93 */
94 virtual void requestFocus(Widget* widget);
95
96 /**
97 * Requests modal focus for a widget. Focus will only be granted
98 * to a widget if it's focusable and if no other widget has modal
99 * focus.
100 *
101 * @param widget The widget to request modal focus for.
102 * @throws Exception when another widget already has modal focus.
103 * @see releaseModalFocus, Widget::requestModalFocus
104 */
105 virtual void requestModalFocus(Widget* widget);
106
107 /**
108 * Requests modal mouse input focus for a widget. Focus will only
109 * be granted to a widget if it's focusable and if no other widget
110 * has modal mouse input focus.
111 *
112 * Modal mouse input focus means no other widget then the widget with
113 * modal mouse input focus will receive mouse input. The widget with
114 * modal mouse input focus will also receive mouse input no matter what
115 * the mouse input is or where the mouse input occurs.
116 *
117 * @param widget The widget to focus for modal mouse input focus.
118 * @throws Exception when another widget already has modal mouse input
119 * focus.
120 * @see releaseModalMouseInputFocus, Widget::requestModalMouseInputFocus
121 */
122 virtual void requestModalMouseInputFocus(Widget* widget);
123
124 /**
125 * Releases modal focus if the widget has modal focus.
126 * If the widget doesn't have modal focus no relase will occur.
127 *
128 * @param widget The widget to release modal focus for.
129 * @see reuqestModalFocus, Widget::releaseModalFocus
130 */
131 virtual void releaseModalFocus(Widget* widget);
132
133 /**
134 * Releases modal mouse input focus if the widget has modal mouse input
135 * focus. If the widget doesn't have modal mouse input focus no relase
136 * will occur.
137 *
138 * @param widget the widget to release modal mouse input focus for.
139 * @see requestModalMouseInputFocus, Widget::releaseModalMouseInputFocus
140 */
141 virtual void releaseModalMouseInputFocus(Widget* widget);
142
143 /**
144 * Checks if a widget is focused.
145 *
146 * @param widget The widget to check.
147 * @return True if the widget is focused, false otherwise.
148 * @see Widget::isFocused
149 */
150 virtual bool isFocused(const Widget* widget) const;
151
152 /**
153 * Gets the widget with focus.
154 *
155 * @return The widget with focus. NULL if no widget has focus.
156 */
157 virtual Widget* getFocused() const;
158
159 /**
160 * Gets the widget with modal focus.
161 *
162 * @return The widget with modal focus. NULL if no widget has
163 * modal focus.
164 */
165 virtual Widget* getModalFocused() const;
166
167 /**
168 * Gets the widget with modal mouse input focus.
169 *
170 * @return The widget with modal mouse input focus. NULL if
171 * no widget has modal mouse input focus.
172 */
173 virtual Widget* getModalMouseInputFocused() const;
174
175 /**
176 * Focuses the next widget added to a conainer.
177 * If no widget has focus the first widget gets focus. The order
178 * in which the widgets are focused is determined by the order
179 * they were added to a container.
180 *
181 * @see focusPrevious
182 */
183 virtual void focusNext();
184
185 /**
186 * Focuses the previous widget added to a contaienr.
187 * If no widget has focus the first widget gets focus. The order
188 * in which the widgets are focused is determined by the order
189 * they were added to a container.
190 *
191 * @see focusNext
192 */
193 virtual void focusPrevious();
194
195 /**
196 * Adds a widget to by handles by the focus handler.
197 *
198 * @param widget The widget to add.
199 * @see remove
200 */
201 virtual void add(Widget* widget);
202
203 /**
204 * Removes a widget from the focus handler.
205 *
206 * @param widget The widget to remove.
207 * @see add
208 */
209 virtual void remove(Widget* widget);
210
211 /**
212 * Focuses nothing. A focus event will also be sent to the
213 * focused widget's focus listeners if a widget has focus.
214 */
215 virtual void focusNone();
216
217 /**
218 * Focuses the next widget which allows tabbing in unless
219 * the current focused Widget disallows tabbing out.
220 *
221 * @see tabPrevious
222 */
223 virtual void tabNext();
224
225 /**
226 * Focuses the previous widget which allows tabbing in unless
227 * current focused widget disallows tabbing out.
228 *
229 * @see tabNext
230 */
231 virtual void tabPrevious();
232
233 /**
234 * Gets the widget being dragged. Used by the Gui class to
235 * keep track of the dragged widget.
236 *
237 * @return the widget being dragged.
238 * @see setDraggedWidget
239 */
240 virtual Widget* getDraggedWidget();
241
242 /**
243 * Sets the widget being dragged. Used by the Gui class to
244 * keep track of the dragged widget.
245 *
246 * @param draggedWidget The widget being dragged.
247 * @see getDraggedWidget
248 */
249 virtual void setDraggedWidget(Widget* draggedWidget);
250
251 /**
252 * Gets the last widget with the mouse. Used by the Gui class
253 * to keep track the last widget with the mouse.
254 *
255 * @return The last widget with the mouse.
256 * @see setLastWidgetWithMouse
257 */
258 virtual Widget* getLastWidgetWithMouse();
259
260 /**
261 * Sets the last widget with the mouse. Used by the Gui class
262 * to keep track the last widget with the mouse.
263 *
264 * @param lastWidgetWithMouse The last widget with the mouse.
265 * @see getLastWidgetWithMouse
266 */
267 virtual void setLastWidgetWithMouse(Widget* lastWidgetWithMouse);
268
269 /**
270 * Gets the last widget with modal focus.
271 *
272 * @return The last widget with modal focus.
273 * @see setLastWidgetWithModalFocus
274 */
275 virtual Widget* getLastWidgetWithModalFocus();
276
277 /**
278 * Sets the last widget with modal focus.
279 *
280 * @param lastWidgetWithModalFocus The last widget with modal focus.
281 * @see getLastWidgetWithModalFocus
282 */
283 virtual void setLastWidgetWithModalFocus(Widget* lastWidgetWithModalFocus);
284
285 /**
286 * Gets the last widget with modal mouse input focus.
287 *
288 * @return The last widget with modal mouse input focus.
289 * @see setLastWidgetWithModalMouseInputFocus
290 */
291 virtual Widget* getLastWidgetWithModalMouseInputFocus();
292
293 /**
294 * Sets the last widget with modal mouse input focus.
295 *
296 * @param lastMouseWithModalMouseInputFocus The last widget with
297 * modal mouse input focus.
298 * @see getLastWidgetWithModalMouseInputFocus
299 */
300 virtual void setLastWidgetWithModalMouseInputFocus(Widget* lastWidgetWithModalMouseInputFocus);
301
302 /**
303 * Gets the last widget pressed. Used by the Gui class to keep track
304 * of pressed widgets.
305 *
306 * @return The last widget pressed.
307 * @see setLastWidgetPressed
308 */
309 virtual Widget* getLastWidgetPressed();
310
311 /**
312 * Sets the last widget pressed. Used by the Gui class to keep track
313 * of pressed widgets.
314 *
315 * @param lastWidgetPressed The last widget pressed.
316 * @see getLastWidgetPressed
317 */
318 virtual void setLastWidgetPressed(Widget* lastWidgetPressed);
319
320 protected:
321 /**
322 * Distributes a focus lost event.
323 *
324 * @param focusEvent the event to distribute.
325 * @since 0.7.0
326 */
327 virtual void distributeFocusLostEvent(const Event& focusEvent);
328
329 /**
330 * Distributes a focus gained event.
331 *
332 * @param focusEvent the event to distribute.
333 * @since 0.7.0
334 */
335 virtual void distributeFocusGainedEvent(const Event& focusEvent);
336
337 /**
338 * Typedef.
339 */
340 typedef std::vector<Widget*> WidgetVector;
341
342 /**
343 * Typedef.
344 */
345 typedef WidgetVector::iterator WidgetIterator;
346
347 /**
348 * Holds the widgets currently being handled by the
349 * focus handler.
350 */
351 WidgetVector mWidgets;
352
353 /**
354 * Holds the focused widget. NULL if no widget has focus.
355 */
356 Widget* mFocusedWidget;
357
358 /**
359 * Holds the modal focused widget. NULL if no widget has
360 * modal focused.
361 */
362 Widget* mModalFocusedWidget;
363
364 /**
365 * Holds the modal mouse input focused widget. NULL if no widget
366 * is being dragged.
367 */
368 Widget* mModalMouseInputFocusedWidget;
369
370 /**
371 * Holds the dragged widget. NULL if no widget is
372 * being dragged.
373 */
374 Widget* mDraggedWidget;
375
376 /**
377 * Holds the last widget with the mouse.
378 */
379 Widget* mLastWidgetWithMouse;
380
381 /**
382 * Holds the last widget with modal focus.
383 */
384 Widget* mLastWidgetWithModalFocus;
385
386 /**
387 * Holds the last widget with modal mouse input focus.
388 */
389 Widget* mLastWidgetWithModalMouseInputFocus;
390
391 /**
392 * Holds the last widget pressed.
393 */
394 Widget* mLastWidgetPressed;
395 };
396 }
397
398 #endif // end GCN_FOCUSHANDLER_HPP