Mercurial > fife-parpg

comparison ext/guichan-0.8.2/include/guichan/widget.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_WIDGET_HPP
45 #define GCN_WIDGET_HPP
46
47 #include <list>
48 #include <string>
49
50 #include "guichan/color.hpp"
51 #include "guichan/rectangle.hpp"
52
53 namespace gcn
54 {
55 class ActionListener;
56 class BasicContainer;
57 class DeathListener;
58 class DefaultFont;
59 class FocusHandler;
60 class FocusListener;
61 class Font;
62 class Graphics;
63 class KeyInput;
64 class KeyListener;
65 class MouseInput;
66 class MouseListener;
67 class WidgetListener;
68
69 /**
70 * Abstract class for widgets of Guichan. It contains basic functions
71 * every widget should have.
72 *
73 * NOTE: Functions begining with underscore "_" should not
74 * be overloaded unless you know what you are doing
75 *
76 * @author Olof Naessén
77 * @author Per Larsson.
78 * @since 0.1.0
79 */
80 class GCN_CORE_DECLSPEC Widget
81 {
82 public:
83 /**
84 * Constructor. Resets member variables. Noteable, a widget is not
85 * focusable as default, therefore, widgets that are supposed to be
86 * focusable should overide this default in their own constructor.
87 */
88 Widget();
89
90 /**
91 * Default destructor.
92 */
93 virtual ~Widget();
94
95 /**
96 * Draws the widget. It is called by the parent widget when it is time
97 * for the widget to draw itself. The graphics object is set up so
98 * that all drawing is relative to the widget, i.e coordinate (0,0) is
99 * the top left corner of the widget. It is not possible to draw
100 * outside of a widget's dimension.
101 *
102 * @param graphics aA graphics object to draw with.
103 * @since 0.1.0
104 */
105 virtual void draw(Graphics* graphics) = 0;
106
107 /**
108 * Called when a widget is given a chance to draw a frame around itself.
109 * The frame is not considered a part of the widget, it only allows a frame
110 * to be drawn around the widget, thus a frame will never be included when
111 * calculating if a widget should receive events from user input. Also
112 * a widget's frame will never be included when calculating a widget's
113 * position.
114 *
115 * The size of the frame is calculated using the widget's frame size.
116 * If a widget has a frame size of 10 pixels than the area the drawFrame
117 * function can draw to will be the size of the widget with an additional
118 * extension of 10 pixels in each direction.
119 *
120 * An example when drawFrame is a useful function is if a widget needs
121 * a glow around itself.
122 *
123 * @param graphics A graphics object to draw with.
124 * @see setFrameSize, getFrameSize
125 * @since 0.8.0
126 */
127 virtual void drawFrame(Graphics* graphics);
128
129 /**
130 * Sets the size of the widget's frame. The frame is not considered a part of
131 * the widget, it only allows a frame to be drawn around the widget, thus a frame
132 * will never be included when calculating if a widget should receive events
133 * from user input. Also a widget's frame will never be included when calculating
134 * a widget's position.
135 *
136 * A frame size of 0 means that the widget has no frame. The default frame size
137 * is 0.
138 *
139 * @param frameSize The size of the widget's frame.
140 * @see getFrameSize, drawFrame
141 * @since 0.8.0
142 */
143 void setFrameSize(unsigned int frameSize);
144
145 /**
146 * Gets the size of the widget's frame. The frame is not considered a part of
147 * the widget, it only allows a frame to be drawn around the widget, thus a frame
148 * will never be included when calculating if a widget should receive events
149 * from user input. Also a widget's frame will never be included when calculating
150 * a widget's position.
151 *
152 * A frame size of 0 means that the widget has no frame. The default frame size
153 * is 0.
154 *
155 * @return The size of the widget's frame.
156 * @see setFrameSize, drawFrame
157 * @since 0.8.0
158 */
159 unsigned int getFrameSize() const;
160
161 /**
162 * Called for all widgets in the gui each time Gui::logic is called.
163 * You can do logic stuff here like playing an animation.
164 *
165 * @see Gui::logic
166 * @since 0.1.0
167 */
168 virtual void logic() { }
169
170 /**
171 * Gets the widget's parent container.
172 *
173 * @return The widget's parent container. NULL if the widget
174 * has no parent.
175 * @since 0.1.0
176 */
177 virtual Widget* getParent() const;
178
179 /**
180 * Sets the width of the widget.
181 *
182 * @param width The width of the widget.
183 * @see getWidth, setHeight, getHeight, setSize,
184 * setDimension, getDimensi
185 * @since 0.1.0
186 */
187 void setWidth(int width);
188
189 /**
190 * Gets the width of the widget.
191 *
192 * @return The width of the widget.
193 * @see setWidth, setHeight, getHeight, setSize,
194 * setDimension, getDimension
195 * @since 0.1.0
196 */
197 int getWidth() const;
198
199 /**
200 * Sets the height of the widget.
201 *
202 * @param height The height of the widget.
203 * @see getHeight, setWidth, getWidth, setSize,
204 * setDimension, getDimension
205 * @since 0.1.0
206 */
207 void setHeight(int height);
208
209 /**
210 * Gets the height of the widget.
211 *
212 * @return The height of the widget.
213 * @see setHeight, setWidth, getWidth, setSize,
214 * setDimension, getDimension
215 * @since 0.1.0
216 */
217 int getHeight() const;
218
219 /**
220 * Sets the size of the widget.
221 *
222 * @param width The width of the widget.
223 * @param height The height of the widget.
224 * @see setWidth, setHeight, getWidth, getHeight,
225 * setDimension, getDimension
226 * @since 0.1.0
227 */
228 void setSize(int width, int height);
229
230 /**
231 * Sets the x coordinate of the widget. The coordinate is
232 * relateive to the widget's parent.
233 *
234 * @param x The x coordinate of the widget.
235 * @see getX, setY, getY, setPosition, setDimension, getDimension
236 * @since 0.1.0
237 */
238 void setX(int x);
239
240 /**
241 * Gets the x coordinate of the widget. The coordinate is
242 * relative to the widget's parent.
243 *
244 * @return The x coordinate of the widget.
245 * @see setX, setY, getY, setPosition, setDimension, getDimension
246 * @since 0.1.0
247 */
248 int getX() const;
249
250 /**
251 * Sets the y coordinate of the widget. The coordinate is
252 * relative to the widget's parent.
253 *
254 * @param y The y coordinate of the widget.
255 * @see setY, setX, getX, setPosition, setDimension, getDimension
256 * @since 0.1.0
257 */
258 void setY(int y);
259
260 /**
261 * Gets the y coordinate of the widget. The coordinate is
262 * relative to the widget's parent.
263 *
264 * @return The y coordinate of the widget.
265 * @see setY, setX, getX, setPosition, setDimension, getDimension
266 * @since 0.1.0
267 */
268 int getY() const;
269
270 /**
271 * Sets position of the widget. The position is relative
272 * to the widget's parent.
273 *
274 * @param x The x coordinate of the widget.
275 * @param y The y coordinate of the widget.
276 * @see setX, getX, setY, getY, setDimension, getDimension
277 * @since 0.1.0
278 */
279 void setPosition(int x, int y);
280
281 /**
282 * Sets the dimension of the widget. The dimension is
283 * relative to the widget's parent.
284 *
285 * @param dimension The dimension of the widget.
286 * @see getDimension, setX, getX, setY, getY, setPosition
287 * @since 0.1.0
288 */
289 void setDimension(const Rectangle& dimension);
290
291 /**
292 * Gets the dimension of the widget. The dimension is
293 * relative to the widget's parent.
294 *
295 * @return The dimension of the widget.
296 * @see getDimension, setX, getX, setY, getY, setPosition
297 * @since 0.1.0
298 */
299 const Rectangle& getDimension() const;
300
301 /**
302 * Sets the widget to be fosusable, or not.
303 *
304 * @param focusable True if the widget should be focusable,
305 * false otherwise.
306 * @see isFocusable
307 * @since 0.1.0
308 */
309 void setFocusable(bool focusable);
310
311 /**
312 * Checks if a widget is focsable.
313 *
314 * @return True if the widget should be focusable, false otherwise.
315 * @see setFocusable
316 * @since 0.1.0
317 */
318 bool isFocusable() const;
319
320 /**
321 * Checks if the widget is focused.
322 *
323 * @return True if the widget is focused, false otherwise.
324 * @since 0.1.0
325 */
326 virtual bool isFocused() const;
327
328 /**
329 * Sets the widget to enabled, or not. A disabled
330 * widget will never recieve mouse or key events.
331 *
332 * @param enabled True if widget should be enabled,
333 * false otherwise.
334 * @see isEnabled
335 * @since 0.1.0
336 */
337 void setEnabled(bool enabled);
338
339 /**
340 * Checks if the widget is enabled. A disabled
341 * widget will never recieve mouse or key events.
342 *
343 * @return True if widget is enabled, false otherwise.
344 * @see setEnabled
345 * @since 0.1.0
346 */
347 bool isEnabled() const;
348
349 /**
350 * Sets the widget to be visible, or not.
351 *
352 * @param visible True if widget should be visible, false otherwise.
353 * @see isVisible
354 * @since 0.1.0
355 */
356 void setVisible(bool visible);
357
358 /**
359 * Checks if the widget is visible.
360 *
361 * @return True if widget is be visible, false otherwise.
362 * @see setVisible
363 * @since 0.1.0
364 */
365 bool isVisible() const;
366
367 /**
368 * Sets the base color of the widget.
369 *
370 * @param color The baseground color.
371 * @see getBaseColor
372 * @since 0.1.0
373 */
374 void setBaseColor(const Color& color);
375
376 /**
377 * Gets the base color.
378 *
379 * @return The base color.
380 * @see setBaseColor
381 * @since 0.1.0
382 */
383 const Color& getBaseColor() const;
384
385 /**
386 * Sets the foreground color.
387 *
388 * @param color The foreground color.
389 * @see getForegroundColor
390 * @since 0.1.0
391 */
392 void setForegroundColor(const Color& color);
393
394 /**
395 * Gets the foreground color.
396 *
397 * @see setForegroundColor
398 * @since 0.1.0
399 */
400 const Color& getForegroundColor() const;
401
402 /**
403 * Sets the background color.
404 *
405 * @param color The background Color.
406 * @see setBackgroundColor
407 * @since 0.1.0
408 */
409 void setBackgroundColor(const Color& color);
410
411 /**
412 * Gets the background color.
413 *
414 * @see setBackgroundColor
415 * @since 0.1.0
416 */
417 const Color& getBackgroundColor() const;
418
419 /**
420 * Sets the selection color.
421 *
422 * @param color The selection color.
423 * @see getSelectionColor
424 * @since 0.6.0
425 */
426 void setSelectionColor(const Color& color);
427
428 /**
429 * Gets the selection color.
430 *
431 * @return The selection color.
432 * @see setSelectionColor
433 * @since 0.6.0
434 */
435 const Color& getSelectionColor() const;
436
437 /**
438 * Requests focus for the widget. A widget will only recieve focus
439 * if it is focusable.
440 */
441 virtual void requestFocus();
442
443 /**
444 * Requests a move to the top in the parent widget.
445 */
446 virtual void requestMoveToTop();
447
448 /**
449 * Requests a move to the bottom in the parent widget.
450 */
451 virtual void requestMoveToBottom();
452
453 /**
454 * Sets the focus handler to be used.
455 *
456 * WARNING: This function is used internally and should not
457 * be called or overloaded unless you know what you
458 * are doing.
459 *
460 * @param focusHandler The focus handler to use.
461 * @see _getFocusHandler
462 * @since 0.1.0
463 */
464 virtual void _setFocusHandler(FocusHandler* focusHandler);
465
466 /**
467 * Gets the focus handler used.
468 *
469 * WARNING: This function is used internally and should not
470 * be called or overloaded unless you know what you
471 * are doing.
472 *
473 * @return The focus handler used.
474 * @see _setFocusHandler
475 * @since 0.1.0
476 */
477 virtual FocusHandler* _getFocusHandler();
478
479 /**
480 * Adds an action listener to the widget. When an action event
481 * is fired by the widget the action listeners of the widget
482 * will get notified.
483 *
484 * @param actionListener The action listener to add.
485 * @see removeActionListener
486 * @since 0.1.0
487 */
488 void addActionListener(ActionListener* actionListener);
489
490 /**
491 * Removes an added action listener from the widget.
492 *
493 * @param actionListener The action listener to remove.
494 * @see addActionListener
495 * @since 0.1.0
496 */
497 void removeActionListener(ActionListener* actionListener);
498
499 /**
500 * Adds a death listener to the widget. When a death event is
501 * fired by the widget the death listeners of the widget will
502 * get notified.
503 *
504 * @param deathListener The death listener to add.
505 * @see removeDeathListener
506 * @since 0.1.0
507 */
508 void addDeathListener(DeathListener* deathListener);
509
510 /**
511 * Removes an added death listener from the widget.
512 *
513 * @param deathListener The death listener to remove.
514 * @see addDeathListener
515 * @since 0.1.0
516 */
517 void removeDeathListener(DeathListener* deathListener);
518
519 /**
520 * Adds a mouse listener to the widget. When a mouse event is
521 * fired by the widget the mouse listeners of the widget will
522 * get notified.
523 *
524 * @param mouseListener The mouse listener to add.
525 * @see removeMouseListener
526 * @since 0.1.0
527 */
528 void addMouseListener(MouseListener* mouseListener);
529
530 /**
531 * Removes an added mouse listener from the widget.
532 *
533 * @param mouseListener The mouse listener to remove.
534 * @see addMouseListener
535 * @since 0.1.0
536 */
537 void removeMouseListener(MouseListener* mouseListener);
538
539 /**
540 * Adds a key listener to the widget. When a key event is
541 * fired by the widget the key listeners of the widget will
542 * get notified.
543 *
544 * @param keyListener The key listener to add.
545 * @see removeKeyListener
546 * @since 0.1.0
547 */
548 void addKeyListener(KeyListener* keyListener);
549
550 /**
551 * Removes an added key listener from the widget.
552 *
553 * @param keyListener The key listener to remove.
554 * @see addKeyListener
555 * @since 0.1.0
556 */
557 void removeKeyListener(KeyListener* keyListener);
558
559 /**
560 * Adds a focus listener to the widget. When a focus event is
561 * fired by the widget the key listeners of the widget will
562 * get notified.
563 *
564 * @param focusListener The focus listener to add.
565 * @see removeFocusListener
566 * @since 0.7.0
567 */
568 void addFocusListener(FocusListener* focusListener);
569
570 /**
571 * Removes an added focus listener from the widget.
572 *
573 * @param focusListener The focus listener to remove.
574 * @see addFocusListener
575 * @since 0.7.0
576 */
577 void removeFocusListener(FocusListener* focusListener);
578
579 /**
580 * Adds a widget listener to the widget. When a widget event is
581 * fired by the widget the key listeners of the widget will
582 * get notified.
583 *
584 * @param widgetListener The widget listener to add.
585 * @see removeWidgetListener
586 * @since 0.8.0
587 */
588 void addWidgetListener(WidgetListener* widgetListener);
589
590 /**
591 * Removes an added widget listener from the widget.
592 *
593 * @param widgetListener The widget listener to remove.
594 * @see addWidgetListener
595 * @since 0.8.0
596 */
597 void removeWidgetListener(WidgetListener* widgetListener);
598
599 /**
600 * Sets the action event identifier of the widget. The identifier is
601 * used to be able to identify which action has occured.
602 *
603 * NOTE: An action event identifier should not be used to identify a
604 * certain widget but rather a certain event in your application.
605 * Several widgets can have the same action event identifer.
606 *
607 * @param actionEventId The action event identifier.
608 * @see getActionEventId
609 * @since 0.6.0
610 */
611 void setActionEventId(const std::string& actionEventId);
612
613 /**
614 * Gets the action event identifier of the widget.
615 *
616 * @return The action event identifier of the widget.
617 * @see setActionEventId
618 * @since 0.6.0
619 */
620 const std::string& getActionEventId() const;
621
622 /**
623 * Gets the absolute position on the screen for the widget.
624 *
625 * @param x The absolute x coordinate will be stored in this parameter.
626 * @param y The absolute y coordinate will be stored in this parameter.
627 * @since 0.1.0
628 */
629 virtual void getAbsolutePosition(int& x, int& y) const;
630
631 /**
632 * Sets the parent of the widget. A parent must be a BasicContainer.
633 *
634 * WARNING: This function is used internally and should not
635 * be called or overloaded unless you know what you
636 * are doing.
637 *
638 * @param parent The parent of the widget.
639 * @see getParent
640 * @since 0.1.0
641 */
642 virtual void _setParent(Widget* parent);
643
644 /**
645 * Gets the font set for the widget. If no font has been set,
646 * the global font will be returned. If no global font has been set,
647 * the default font will be returend.
648 *
649 * @return The font set for the widget.
650 * @see setFont, setGlobalFont
651 * @since 0.1.0
652 */
653 Font *getFont() const;
654
655 /**
656 * Sets the global font to be used by default for all widgets.
657 *
658 * @param font The global font.
659 * @see getGlobalFont
660 * @since 0.1.0
661 */
662 static void setGlobalFont(Font* font);
663
664 /**
665 * Sets the font for the widget. If NULL is passed, the global font
666 * will be used.
667 *
668 * @param font The font to set for the widget.
669 * @see getFont
670 * @since 0.1.0
671 */
672 void setFont(Font* font);
673
674 /**
675 * Called when the font has changed. If the change is global,
676 * this function will only be called if the widget doesn't have a
677 * font already set.
678 *
679 * @since 0.1.0
680 */
681 virtual void fontChanged() { }
682
683 /**
684 * Checks if a widget exists or not, that is if it still exists
685 * an instance of the object.
686 *
687 * @param widget The widget to check.
688 * @return True if an instance of the widget exists, false otherwise.
689 * @since 0.1.0
690 */
691 static bool widgetExists(const Widget* widget);
692
693 /**
694 * Checks if tab in is enabled. Tab in means that you can set focus
695 * to this widget by pressing the tab button. If tab in is disabled
696 * then the focus handler will skip this widget and focus the next
697 * in its focus order.
698 *
699 * @return True if tab in is enabled, false otherwise.
700 * @see setTabInEnabled
701 * @since 0.1.0
702 */
703 bool isTabInEnabled() const;
704
705 /**
706 * Sets tab in enabled, or not. Tab in means that you can set focus
707 * to this widget by pressing the tab button. If tab in is disabled
708 * then the FocusHandler will skip this widget and focus the next
709 * in its focus order.
710 *
711 * @param enabled True if tab in should be enabled, false otherwise.
712 * @see isTabInEnabled
713 * @since 0.1.0
714 */
715 void setTabInEnabled(bool enabled);
716
717 /**
718 * Checks if tab out is enabled. Tab out means that you can lose
719 * focus to this widget by pressing the tab button. If tab out is
720 * disabled then the FocusHandler ignores tabbing and focus will
721 * stay with this widget.
722 *
723 * @return True if tab out is enabled, false otherwise.
724 * @see setTabOutEnabled
725 * @since 0.1.0
726 */
727 bool isTabOutEnabled() const;
728
729 /**
730 * Sets tab out enabled. Tab out means that you can lose
731 * focus to this widget by pressing the tab button. If tab out is
732 * disabled then the FocusHandler ignores tabbing and focus will
733 * stay with this widget.
734 *
735 * @param enabled True if tab out should be enabled, false otherwise.
736 * @see isTabOutEnabled
737 * @since 0.1.0
738 */
739 void setTabOutEnabled(bool enabled);
740
741 /**
742 * Requests modal focus. When a widget has modal focus, only that
743 * widget and it's children may recieve input.
744 *
745 * @throws Exception if another widget already has modal focus.
746 * @see releaseModalFocus, isModalFocused
747 * @since 0.4.0
748 */
749 virtual void requestModalFocus();
750
751 /**
752 * Requests modal mouse input focus. When a widget has modal input focus
753 * that widget will be the only widget receiving input even if the input
754 * occurs outside of the widget and no matter what the input is.
755 *
756 * @throws Exception if another widget already has modal focus.
757 * @see releaseModalMouseInputFocus, isModalMouseInputFocused
758 * @since 0.6.0
759 */
760 virtual void requestModalMouseInputFocus();
761
762 /**
763 * Releases modal focus. Modal focus will only be released if the
764 * widget has modal focus.
765 *
766 * @see requestModalFocus, isModalFocused
767 * @since 0.4.0
768 */
769 virtual void releaseModalFocus();
770
771 /**
772 * Releases modal mouse input focus. Modal mouse input focus will only
773 * be released if the widget has modal mouse input focus.
774 *
775 * @see requestModalMouseInputFocus, isModalMouseInputFocused
776 * @since 0.6.0
777 */
778 virtual void releaseModalMouseInputFocus();
779
780 /**
781 * Checks if the widget or it's parent has modal focus.
782 *
783 * @return True if the widget has modal focus, false otherwise.
784 * @see requestModalFocus, releaseModalFocus
785 * @since 0.8.0
786 */
787 virtual bool isModalFocused() const;
788
789 /**
790 * Checks if the widget or it's parent has modal mouse input focus.
791 *
792 * @return True if the widget has modal mouse input focus, false
793 * otherwise.
794 * @see requestModalMouseInputFocus, releaseModalMouseInputFocus
795 * @since 0.8.0
796 */
797 virtual bool isModalMouseInputFocused() const;
798
799 /**
800 * Gets a widget from a certain position in the widget.
801 * This function is used to decide which gets mouse input,
802 * thus it can be overloaded to change that behaviour.
803 *
804 * NOTE: This always returns NULL if the widget is not
805 * a container.
806 *
807 * @param x The x coordinate of the widget to get.
808 * @param y The y coordinate of the widget to get.
809 * @return The widget at the specified coodinate, NULL
810 * if no widget is found.
811 * @since 0.6.0
812 */
813 virtual Widget *getWidgetAt(int x, int y);
814
815 /**
816 * Gets the mouse listeners of the widget.
817 *
818 * @return The mouse listeners of the widget.
819 * @since 0.6.0
820 */
821 virtual const std::list<MouseListener*>& _getMouseListeners();
822
823 /**
824 * Gets the key listeners of the widget.
825 *
826 * @return The key listeners of the widget.
827 * @since 0.6.0
828 */
829 virtual const std::list<KeyListener*>& _getKeyListeners();
830
831 /**
832 * Gets the focus listeners of the widget.
833 *
834 * @return The focus listeners of the widget.
835 * @since 0.7.0
836 */
837 virtual const std::list<FocusListener*>& _getFocusListeners();
838
839 /**
840 * Gets the area of the widget occupied by the widget's children.
841 * By default this method returns an empty rectangle as not all
842 * widgets are containers. If you want to make a container this
843 * method should return the area where the children resides. This
844 * method is used when drawing children of a widget when computing
845 * clip rectangles for the children.
846 *
847 * An example of a widget that overloads this method is ScrollArea.
848 * A ScrollArea has a view of its contant and that view is the
849 * children area. The size of a ScrollArea's children area might
850 * vary depending on if the scroll bars of the ScrollArea is shown
851 * or not.
852 *
853 * @return The area of the widget occupied by the widget's children.
854 * @see BasicContainer
855 * @see BasicContainer::getChildrenArea
856 * @see BasicContainer::drawChildren
857 * @since 0.1.0
858 */
859 virtual Rectangle getChildrenArea();
860
861 /**
862 * Gets the internal focus handler used.
863 *
864 * @return the internalFocusHandler used. If no internal focus handler
865 * is used, NULL will be returned.
866 * @see setInternalFocusHandler
867 * @since 0.1.0
868 */
869 virtual FocusHandler* _getInternalFocusHandler();
870
871 /**
872 * Sets the internal focus handler. An internal focus handler is
873 * needed if both a widget in the widget and the widget itself
874 * should be foucsed at the same time.
875 *
876 * @param focusHandler The internal focus handler to be used.
877 * @see getInternalFocusHandler
878 * @since 0.1.0
879 */
880 void setInternalFocusHandler(FocusHandler* internalFocusHandler);
881
882 /**
883 * Moves a widget to the top of this widget. The moved widget will be
884 * drawn above all other widgets in this widget.
885 *
886 * @param widget The widget to move to the top.
887 * @see moveToBottom
888 * @since 0.1.0
889 */
890 virtual void moveToTop(Widget* widget) { };
891
892 /**
893 * Moves a widget in this widget to the bottom of this widget.
894 * The moved widget will be drawn below all other widgets in this widget.
895 *
896 * @param widget The widget to move to the bottom.
897 * @see moveToTop
898 * @since 0.1.0
899 */
900 virtual void moveToBottom(Widget* widget) { };
901
902 /**
903 * Focuses the next widget in the widget.
904 *
905 * @see moveToBottom
906 * @since 0.1.0
907 */
908 virtual void focusNext() { };
909
910 /**
911 * Focuses the previous widget in the widget.
912 *
913 * @see moveToBottom
914 * @since 0.1.0
915 */
916 virtual void focusPrevious() { };
917
918 /**
919 * Tries to show a specific part of a widget by moving it. Used if the
920 * widget should act as a container.
921 *
922 * @param widget The target widget.
923 * @param area The area to show.
924 * @since 0.1.0
925 */
926 virtual void showWidgetPart(Widget* widget, Rectangle area) { };
927
928 /**
929 * Sets an id of a widget. An id can be useful if a widget needs to be
930 * identified in a container. For example, if widgets are created by an
931 * XML document, a certain widget can be retrieved given that the widget
932 * has an id.
933 *
934 * @param id The id to set to the widget.
935 * @see getId, BasicContainer::findWidgetById
936 * @since 0.8.0
937 */
938 void setId(const std::string& id);
939
940 /**
941 * Gets the id of a widget. An id can be useful if a widget needs to be
942 * identified in a container. For example, if widgets are created by an
943 * XML document, a certain widget can be retrieved given that the widget
944 * has an id.
945 *
946 * @param id The id to set to the widget.
947 * @see setId, BasicContainer::findWidgetById
948 * @since 0.8.0
949 */
950 const std::string& getId();
951
952 /**
953 * Shows a certain part of a widget in the widget's parent.
954 * Used when widgets want a specific part to be visible in
955 * its parent. An example is a TextArea that wants a specific
956 * part of its text to be visible when a TextArea is a child
957 * of a ScrollArea.
958 *
959 * @param rectangle The rectangle to be shown.
960 * @since 0.8.0
961 */
962 virtual void showPart(Rectangle rectangle);
963
964 protected:
965 /**
966 * Distributes an action event to all action listeners
967 * of the widget.
968 *
969 * @since 0.8.0
970 */
971 void distributeActionEvent();
972
973 /**
974 * Distributes resized events to all of the widget's listeners.
975 *
976 * @since 0.8.0
977 */
978 void distributeResizedEvent();
979
980 /**
981 * Distributes moved events to all of the widget's listeners.
982 *
983 * @since 0.8.0
984 */
985 void distributeMovedEvent();
986
987 /**
988 * Distributes hidden events to all of the widget's listeners.
989 *
990 * @since 0.8.0
991 * @author Olof Naessén
992 */
993 void distributeHiddenEvent();
994
995 /**
996 * Distributes shown events to all of the widget's listeners.
997 *
998 * @since 0.8.0
999 * @author Olof Naessén
1000 */
1001 void distributeShownEvent();
1002
1003 /**
1004 * Typdef.
1005 */
1006 typedef std::list<MouseListener*> MouseListenerList;
1007
1008 /**
1009 * Typdef.
1010 */
1011 typedef MouseListenerList::iterator MouseListenerIterator;
1012
1013 /**
1014 * Holds the mouse listeners of the widget.
1015 */
1016 MouseListenerList mMouseListeners;
1017
1018 /**
1019 * Typdef.
1020 */
1021 typedef std::list<KeyListener*> KeyListenerList;
1022
1023 /**
1024 * Holds the key listeners of the widget.
1025 */
1026 KeyListenerList mKeyListeners;
1027
1028 /**
1029 * Typdef.
1030 */
1031 typedef KeyListenerList::iterator KeyListenerIterator;
1032
1033 /**
1034 * Typdef.
1035 */
1036 typedef std::list<ActionListener*> ActionListenerList;
1037
1038 /**
1039 * Holds the action listeners of the widget.
1040 */
1041 ActionListenerList mActionListeners;
1042
1043 /**
1044 * Typdef.
1045 */
1046 typedef ActionListenerList::iterator ActionListenerIterator;
1047
1048 /**
1049 * Typdef.
1050 */
1051 typedef std::list<DeathListener*> DeathListenerList;
1052
1053 /**
1054 * Holds the death listeners of the widget.
1055 */
1056 DeathListenerList mDeathListeners;
1057
1058 /**
1059 * Typdef.
1060 */
1061 typedef DeathListenerList::iterator DeathListenerIterator;
1062
1063 /**
1064 * Typdef.
1065 */
1066 typedef std::list<FocusListener*> FocusListenerList;
1067
1068 /**
1069 * Holds the focus listeners of the widget.
1070 */
1071 FocusListenerList mFocusListeners;
1072
1073 /**
1074 * Typdef.
1075 */
1076 typedef FocusListenerList::iterator FocusListenerIterator;
1077
1078 typedef std::list<WidgetListener*> WidgetListenerList;
1079
1080 /**
1081 * Holds the widget listeners of the widget.
1082 */
1083 WidgetListenerList mWidgetListeners;
1084
1085 /**
1086 * Typdef.
1087 */
1088 typedef WidgetListenerList::iterator WidgetListenerIterator;
1089
1090 /**
1091 * Holds the foreground color of the widget.
1092 */
1093 Color mForegroundColor;
1094
1095 /**
1096 * Holds the background color of the widget.
1097 */
1098 Color mBackgroundColor;
1099
1100 /**
1101 * Holds the base color of the widget.
1102 */
1103 Color mBaseColor;
1104
1105 /**
1106 * Holds the selection color of the widget.
1107 */
1108 Color mSelectionColor;
1109
1110 /**
1111 * Holds the focus handler used by the widget.
1112 */
1113 FocusHandler* mFocusHandler;
1114
1115 /**
1116 * Holds the focus handler used by the widget. NULL
1117 * if no internal focus handler is used.
1118 */
1119 FocusHandler* mInternalFocusHandler;
1120
1121 /**
1122 * Holds the parent of the widget. NULL if the widget
1123 * has no parent.
1124 */
1125 Widget* mParent;
1126
1127 /**
1128 * Holds the dimension of the widget.
1129 */
1130 Rectangle mDimension;
1131
1132 /**
1133 * Holds the frame size of the widget.
1134 */
1135 unsigned int mFrameSize;
1136
1137 /**
1138 * Holds the action event of the widget.
1139 */
1140 std::string mActionEventId;
1141
1142 /**
1143 * True if the widget focusable, false otherwise.
1144 */
1145 bool mFocusable;
1146
1147 /**
1148 * True if the widget visible, false otherwise.
1149 */
1150 bool mVisible;
1151
1152 /**
1153 * True if the widget has tab in enabled, false otherwise.
1154 */
1155 bool mTabIn;
1156
1157 /**
1158 * True if the widget has tab in enabled, false otherwise.
1159 */
1160 bool mTabOut;
1161
1162 /**
1163 * True if the widget is enabled, false otherwise.
1164 */
1165 bool mEnabled;
1166
1167 /**
1168 * Holds the id of the widget.
1169 */
1170 std::string mId;
1171
1172 /**
1173 * Holds the font used by the widget.
1174 */
1175 Font* mCurrentFont;
1176
1177 /**
1178 * Holds the default font used by the widget.
1179 */
1180 static DefaultFont mDefaultFont;
1181
1182 /**
1183 * Holds the global font used by the widget.
1184 */
1185 static Font* mGlobalFont;
1186
1187 /**
1188 * Holds a list of all instances of widgets.
1189 */
1190 static std::list<Widget*> mWidgets;
1191 };
1192 }
1193
1194 #endif // end GCN_WIDGET_HPP