Mercurial > fife-parpg

comparison ext/guichan-0.8.1/include/guichan/gui.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_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 gaind 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 gaind
321 * it might be necessary to distribute mouse entered or mouse exited events.
322 *
323 * @since 0.8.0
324 */
325 virtual void handleModalFocusReleased();
326
327 /**
328 * Distributes a mouse event.
329 *
330 * @param type The type of the event to distribute,
331 * @param button The button of the event (if any used) to distribute.
332 * @param x The x coordinate of the event.
333 * @param y The y coordinate of the event.
334 * @param fource indicates whether the distribution should be forced or not.
335 * A forced distribution distributes the event even if a widget
336 * is not enabled, not visible, another widget has modal
337 * focus or another widget has modal mouse input focus.
338 * Default value is false.
339 * @param toSourceOnly indicates whether the distribution should be to the
340 * source widget only or to it's parent's mouse listeners
341 * as well.
342 *
343 * @since 0.6.0
344 */
345 virtual void distributeMouseEvent(Widget* source,
346 int type,
347 int button,
348 int x,
349 int y,
350 bool force = false,
351 bool toSourceOnly = false);
352
353 /**
354 * Distributes a key event.
355 *
356 * @param keyEvent The key event to distribute.
357
358 * @since 0.6.0
359 */
360 virtual void distributeKeyEvent(KeyEvent& keyEvent);
361
362 /**
363 * Distributes a key event to the global key listeners.
364 *
365 * @param keyEvent The key event to distribute.
366 *
367 * @since 0.6.0
368 */
369 virtual void distributeKeyEventToGlobalKeyListeners(KeyEvent& keyEvent);
370
371 /**
372 * Gets the widget at a certain position.
373 *
374 * @return The widget at a certain position.
375 * @since 0.6.0
376 */
377 virtual Widget* getWidgetAt(int x, int y);
378
379 /**
380 * Gets the source of the mouse event.
381 *
382 * @return The source widget of the mouse event.
383 * @since 0.6.0
384 */
385 virtual Widget* getMouseEventSource(int x, int y);
386
387 /**
388 * Gets the source of the key event.
389 *
390 * @return The source widget of the key event.
391 * @since 0.6.0
392 */
393 virtual Widget* getKeyEventSource();
394
395 /**
396 * Holds the top widget.
397 */
398 Widget* mTop;
399
400 /**
401 * Holds the graphics implementation used.
402 */
403 Graphics* mGraphics;
404
405 /**
406 * Holds the input implementation used.
407 */
408 Input* mInput;
409
410 /**
411 * Holds the focus handler for the Gui.
412 */
413 FocusHandler* mFocusHandler;
414
415 /**
416 * True if tabbing is enabled, false otherwise.
417 */
418 bool mTabbing;
419
420 /**
421 * Typedef.
422 */
423 typedef std::list<KeyListener*> KeyListenerList;
424
425 /**
426 * Typedef.
427 */
428 typedef KeyListenerList::iterator KeyListenerListIterator;
429
430 /**
431 * Holds the global key listeners of the Gui.
432 */
433 KeyListenerList mKeyListeners;
434
435 /**
436 * True if shift is pressed, false otherwise.
437 */
438 bool mShiftPressed;
439
440 /**
441 * True if meta is pressed, false otherwise.
442 */
443 bool mMetaPressed;
444
445 /**
446 * True if control is pressed, false otherwise.
447 */
448 bool mControlPressed;
449
450 /**
451 * True if alt is pressed, false otherwise.
452 */
453 bool mAltPressed;
454
455 /**
456 * Holds the last mouse button pressed.
457 */
458 unsigned int mLastMousePressButton;
459
460 /**
461 * Holds the last mouse press time stamp.
462 */
463 int mLastMousePressTimeStamp;
464
465 /**
466 * Holds the last mouse x coordinate.
467 */
468 int mLastMouseX;
469
470 /**
471 * Holds the last mouse y coordinate.
472 */
473 int mLastMouseY;
474
475 /**
476 * Holds the current click count. Used to keep track
477 * of clicks for a the last pressed button.
478 */
479 int mClickCount;
480
481 /**
482 * Holds the last button used when a drag of a widget
483 * was initiated. Used to be able to release a drag
484 * when the same button is released.
485 */
486 int mLastMouseDragButton;
487
488 /**
489 * Holds a stack with all the widgets with the mouse.
490 * Used to properly distribute mouse events.
491 */
492 std::deque<Widget*> mWidgetWithMouseQueue;
493 };
494 }
495
496 #endif // end GCN_GUI_HPP
497
498 /* yakslem - "Women, it's a constant struggle."
499 * finalman - "Yes, but sometimes they succeed with their guesses."
500 * yaklsem - "...eh...I was talking about love."
501 * finalman - "Oh...ok..."
502 * An awkward silence followed.
503 */