Mercurial > fife-parpg

comparison ext/guichan-0.8.1/include/guichan/focushandler.hpp @ 0:4a0efb7baf70

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Datasets becomes the new trunk and retires after that :-)
author mvbarracuda@33b003aa-7bff-0310-803a-e67f0ece8222
date Sun, 29 Jun 2008 18:44:17 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4a0efb7baf70
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