Mercurial > fife-parpg

comparison ext/guichan-0.8.2/include/guichan/gui.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_GUI_HPP
45 #define GCN_GUI_HPP
46
47 #include <list>
48 #include <deque>
49
50 #include "guichan/keyevent.hpp"
51 #include "guichan/mouseevent.hpp"
52 #include "guichan/mouseinput.hpp"
53 #include "guichan/platform.hpp"
54
55 namespace gcn
56 {
57 class FocusHandler;
58 class Graphics;
59 class Input;
60 class KeyListener;
61 class Widget;
62
63 // The following comment will appear in the doxygen main page.
64 /**
65 * @mainpage
66 * @section Introduction
67 * This documentation is mostly intended as a reference to the API. If you want to get started with Guichan, we suggest you check out the programs in the examples directory of the Guichan release.
68 * @n
69 * @n
70 * This documentation is, and will always be, work in progress. If you find any errors, typos or inconsistencies, or if you feel something needs to be explained in more detail - don't hesitate to tell us.
71 */
72
73 /**
74 * Contains a Guichan GUI. This is the core class of Guichan to which
75 * implementations of back ends are passed, to make Guichan work with
76 * a specific library, and to where the top widget (root widget of GUI)
77 * is added. If you want to be able to have more then one widget in your
78 * GUI, the top widget should be a container.
79 *
80 * A Gui object cannot work properly without passing back end
81 * implementations to it. A Gui object must have an implementation of a
82 * Graphics and an implementation of Input.
83 *
84 * NOTE: A complete GUI also must have the ability to load images.
85 * Images are loaded with the Image class, so to make Guichan
86 * able to load images an implementation of ImageLoader must be
87 * passed to Image.
88 *
89 * @see Graphics, Input, Image
90 */
91 class GCN_CORE_DECLSPEC Gui
92 {
93 public:
94
95 /**
96 * Constructor.
97 */
98 Gui();
99
100 /**
101 * Destructor.
102 */
103 virtual ~Gui();
104
105 /**
106 * Sets the top widget. The top widget is the root widget
107 * of the GUI. If you want a GUI to be able to contain more
108 * than one widget the top widget should be a container.
109 *
110 * @param top The top widget.
111 * @see Container
112 * @since 0.1.0
113 */
114 virtual void setTop(Widget* top);
115
116 /**
117 * Gets the top widget. The top widget is the root widget
118 * of the GUI.
119 *
120 * @return The top widget. NULL if no top widget has been set.
121 * @since 0.1.0
122 */
123 virtual Widget* getTop() const;
124
125 /**
126 * Sets the graphics object to use for drawing.
127 *
128 * @param graphics The graphics object to use for drawing.
129 * @see getGraphics, AllegroGraphics, HGEGraphics,
130 * OpenLayerGraphics, OpenGLGraphics, SDLGraphics
131 * @since 0.1.0
132 */
133 virtual void setGraphics(Graphics* graphics);
134
135 /**
136 * Gets the graphics object used for drawing.
137 *
138 * @return The graphics object used for drawing. NULL if no
139 * graphics object has been set.
140 * @see setGraphics, AllegroGraphics, HGEGraphics,
141 * OpenLayerGraphics, OpenGLGraphics, SDLGraphics
142 * @since 0.1.0
143 */
144 virtual Graphics* getGraphics() const;
145
146 /**
147 * Sets the input object to use for input handling.
148 *
149 * @param input The input object to use for input handling.
150 * @see getInput, AllegroInput, HGEInput, OpenLayerInput,
151 * SDLInput
152 * @since 0.1.0
153 */
154 virtual void setInput(Input* input);
155
156 /**
157 * Gets the input object being used for input handling.
158 *
159 * @return The input object used for handling input. NULL if no
160 * input object has been set.
161 * @see setInput, AllegroInput, HGEInput, OpenLayerInput,
162 * SDLInput
163 * @since 0.1.0
164 */
165 virtual Input* getInput() const;
166
167 /**
168 * Performs logic of the GUI. By calling this function all logic
169 * functions down in the GUI heirarchy will be called. When logic
170 * is called for Gui, user input will be handled.
171 *
172 * @see Widget::logic
173 * @since 0.1.0
174 */
175 virtual void logic();
176
177 /**
178 * Draws the GUI. By calling this funcion all draw functions
179 * down in the GUI hierarchy will be called. When draw is called
180 * the used Graphics object will be initialised and drawing of
181 * the top widget will commence.
182 *
183 * @see Widget::draw
184 * @since 0.1.0
185 */
186 virtual void draw();
187
188 /**
189 * Focuses none of the widgets in the Gui.
190 *
191 * @since 0.1.0
192 */
193 virtual void focusNone();
194
195 /**
196 * Sets tabbing enabled, or not. Tabbing is the usage of
197 * changing focus by utilising the tab key.
198 *
199 * @param tabbing True if tabbing should be enabled, false
200 * otherwise.
201 * @see isTabbingEnabled
202 * @since 0.1.0
203 */
204 virtual void setTabbingEnabled(bool tabbing);
205
206 /**
207 * Checks if tabbing is enabled.
208 *
209 * @return True if tabbing is enabled, false otherwise.
210 * @see setTabbingEnabled
211 * @since 0.1.0
212 */
213 virtual bool isTabbingEnabled();
214
215 /**
216 * Adds a global key listener to the Gui. A global key listener
217 * will receive all key events generated from the GUI and global
218 * key listeners will receive the events before key listeners
219 * of widgets.
220 *
221 * @param keyListener The key listener to add.
222 * @see removeGlobalKeyListener
223 * @since 0.5.0
224 */
225 virtual void addGlobalKeyListener(KeyListener* keyListener);
226
227 /**
228 * Removes global key listener from the Gui.
229 *
230 * @param keyListener The key listener to remove.
231 * @throws Exception if the key listener hasn't been added.
232 * @see addGlobalKeyListener
233 * @since 0.5.0
234 */
235 virtual void removeGlobalKeyListener(KeyListener* keyListener);
236
237 protected:
238 /**
239 * Handles all mouse input.
240 *
241 * @since 0.6.0
242 */
243 virtual void handleMouseInput();
244
245 /**
246 * Handles key input.
247 *
248 * @since 0.6.0
249 */
250 virtual void handleKeyInput();
251
252 /**
253 * Handles mouse moved input.
254 *
255 * @param mouseInput The mouse input to handle.
256 * @since 0.6.0
257 */
258 virtual void handleMouseMoved(const MouseInput& mouseInput);
259
260 /**
261 * Handles mouse pressed input.
262 *
263 * @param mouseInput The mouse input to handle.
264 * @since 0.6.0
265 */
266 virtual void handleMousePressed(const MouseInput& mouseInput);
267
268 /**
269 *
270 * Handles mouse wheel moved down input.
271 *
272 * @param mouseInput The mouse input to handle.
273 * @since 0.6.0
274 */
275 virtual void handleMouseWheelMovedDown(const MouseInput& mouseInput);
276
277 /**
278 * Handles mouse wheel moved up input.
279 *
280 * @param mouseInput The mouse input to handle.
281 * @since 0.6.0
282 */
283 virtual void handleMouseWheelMovedUp(const MouseInput& mouseInput);
284
285 /**
286 * Handles mouse released input.
287 *
288 * @param mouseInput The mouse input to handle.
289 * @since 0.6.0
290 */
291 virtual void handleMouseReleased(const MouseInput& mouseInput);
292
293 /**
294 * Handles modal focus. Modal focus needs to be checked at
295 * each logic iteration as it might be necessary to distribute
296 * mouse entered or mouse exited events.
297 *
298 * @since 0.8.0
299 */
300 virtual void handleModalFocus();
301
302 /**
303 * Handles modal mouse input focus. Modal mouse input focus needs
304 * to be checked at each logic iteration as it might be necessary to
305 * distribute mouse entered or mouse exited events.
306 *
307 * @since 0.8.0
308 */
309 virtual void handleModalMouseInputFocus();
310
311 /**
312 * Handles modal focus gained. If modal focus has been gained it might
313 * be necessary to distribute mouse entered or mouse exited events.
314 *
315 * @since 0.8.0
316 */
317 virtual void handleModalFocusGained();
318
319 /**
320 * Handles modal mouse input focus gained. If modal focus has been
321 * gained it might be necessary to distribute mouse entered or mouse
322 * exited events.
323 *
324 * @since 0.8.0
325 */
326 virtual void handleModalFocusReleased();
327
328 /**
329 * Distributes a mouse event.
330 *
331 * @param type The type of the event to distribute,
332 * @param button The button of the event (if any used) to distribute.
333 * @param x The x coordinate of the event.
334 * @param y The y coordinate of the event.
335 * @param fource indicates whether the distribution should be forced or not.
336 * A forced distribution distributes the event even if a widget
337 * is not enabled, not visible, another widget has modal
338 * focus or another widget has modal mouse input focus.
339 * Default value is false.
340 * @param toSourceOnly indicates whether the distribution should be to the
341 * source widget only or to it's parent's mouse listeners
342 * as well.
343 *
344 * @since 0.6.0
345 */
346 virtual void distributeMouseEvent(Widget* source,
347 int type,
348 int button,
349 int x,
350 int y,
351 bool force = false,
352 bool toSourceOnly = false);
353
354 /**
355 * Distributes a key event.
356 *
357 * @param keyEvent The key event to distribute.
358
359 * @since 0.6.0
360 */
361 virtual void distributeKeyEvent(KeyEvent& keyEvent);
362
363 /**
364 * Distributes a key event to the global key listeners.
365 *
366 * @param keyEvent The key event to distribute.
367 *
368 * @since 0.6.0
369 */
370 virtual void distributeKeyEventToGlobalKeyListeners(KeyEvent& keyEvent);
371
372 /**
373 * Gets the widget at a certain position.
374 *
375 * @return The widget at a certain position.
376 * @since 0.6.0
377 */
378 virtual Widget* getWidgetAt(int x, int y);
379
380 /**
381 * Gets the source of the mouse event.
382 *
383 * @return The source widget of the mouse event.
384 * @since 0.6.0
385 */
386 virtual Widget* getMouseEventSource(int x, int y);
387
388 /**
389 * Gets the source of the key event.
390 *
391 * @return The source widget of the key event.
392 * @since 0.6.0
393 */
394 virtual Widget* getKeyEventSource();
395
396 /**
397 * Holds the top widget.
398 */
399 Widget* mTop;
400
401 /**
402 * Holds the graphics implementation used.
403 */
404 Graphics* mGraphics;
405
406 /**
407 * Holds the input implementation used.
408 */
409 Input* mInput;
410
411 /**
412 * Holds the focus handler for the Gui.
413 */
414 FocusHandler* mFocusHandler;
415
416 /**
417 * True if tabbing is enabled, false otherwise.
418 */
419 bool mTabbing;
420
421 /**
422 * Typedef.
423 */
424 typedef std::list<KeyListener*> KeyListenerList;
425
426 /**
427 * Typedef.
428 */
429 typedef KeyListenerList::iterator KeyListenerListIterator;
430
431 /**
432 * Holds the global key listeners of the Gui.
433 */
434 KeyListenerList mKeyListeners;
435
436 /**
437 * True if shift is pressed, false otherwise.
438 */
439 bool mShiftPressed;
440
441 /**
442 * True if meta is pressed, false otherwise.
443 */
444 bool mMetaPressed;
445
446 /**
447 * True if control is pressed, false otherwise.
448 */
449 bool mControlPressed;
450
451 /**
452 * True if alt is pressed, false otherwise.
453 */
454 bool mAltPressed;
455
456 /**
457 * Holds the last mouse button pressed.
458 */
459 unsigned int mLastMousePressButton;
460
461 /**
462 * Holds the last mouse press time stamp.
463 */
464 int mLastMousePressTimeStamp;
465
466 /**
467 * Holds the last mouse x coordinate.
468 */
469 int mLastMouseX;
470
471 /**
472 * Holds the last mouse y coordinate.
473 */
474 int mLastMouseY;
475
476 /**
477 * Holds the current click count. Used to keep track
478 * of clicks for a the last pressed button.
479 */
480 int mClickCount;
481
482 /**
483 * Holds the last button used when a drag of a widget
484 * was initiated. Used to be able to release a drag
485 * when the same button is released.
486 */
487 int mLastMouseDragButton;
488
489 /**
490 * Holds a stack with all the widgets with the mouse.
491 * Used to properly distribute mouse events.
492 */
493 std::deque<Widget*> mWidgetWithMouseQueue;
494 };
495 }
496
497 #endif // end GCN_GUI_HPP
498
499 /* yakslem - "Women, it's a constant struggle."
500 * finalman - "Yes, but sometimes they succeed with their guesses."
501 * yaklsem - "...eh...I was talking about love."
502 * finalman - "Oh...ok..."
503 * An awkward silence followed.
504 */