GCC Code Coverage Report
Directory: src/ Exec Total Coverage
File: src/gui/widgets/widget.h Lines: 28 52 53.8 %
Date: 2017-11-29 Branches: 15 30 50.0 %

Line Branch Exec Source
1
/*
2
 *  The ManaPlus Client
3
 *  Copyright (C) 2011-2017  The ManaPlus Developers
4
 *
5
 *  This file is part of The ManaPlus Client.
6
 *
7
 *  This program is free software; you can redistribute it and/or modify
8
 *  it under the terms of the GNU General Public License as published by
9
 *  the Free Software Foundation; either version 2 of the License, or
10
 *  any later version.
11
 *
12
 *  This program is distributed in the hope that it will be useful,
13
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
14
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15
 *  GNU General Public License for more details.
16
 *
17
 *  You should have received a copy of the GNU General Public License
18
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
19
 */
20
21
/*      _______   __   __   __   ______   __   __   _______   __   __
22
 *     / _____/\ / /\ / /\ / /\ / ____/\ / /\ / /\ / ___  /\ /  |\/ /\
23
 *    / /\____\// / // / // / // /\___\// /_// / // /\_/ / // , |/ / /
24
 *   / / /__   / / // / // / // / /    / ___  / // ___  / // /| ' / /
25
 *  / /_// /\ / /_// / // / // /_/_   / / // / // /\_/ / // / |  / /
26
 * /______/ //______/ //_/ //_____/\ /_/ //_/ //_/ //_/ //_/ /|_/ /
27
 * \______\/ \______\/ \_\/ \_____\/ \_\/ \_\/ \_\/ \_\/ \_\/ \_\/
28
 *
29
 * Copyright (c) 2004 - 2008 Olof Naessén and Per Larsson
30
 *
31
 *
32
 * Per Larsson a.k.a finalman
33
 * Olof Naessén a.k.a jansem/yakslem
34
 *
35
 * Visit: http://guichan.sourceforge.net
36
 *
37
 * License: (BSD)
38
 * Redistribution and use in source and binary forms, with or without
39
 * modification, are permitted provided that the following conditions
40
 * are met:
41
 * 1. Redistributions of source code must retain the above copyright
42
 *    notice, this list of conditions and the following disclaimer.
43
 * 2. Redistributions in binary form must reproduce the above copyright
44
 *    notice, this list of conditions and the following disclaimer in
45
 *    the documentation and/or other materials provided with the
46
 *    distribution.
47
 * 3. Neither the name of Guichan nor the names of its contributors may
48
 *    be used to endorse or promote products derived from this software
49
 *    without specific prior written permission.
50
 *
51
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
52
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
53
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
54
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
55
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
56
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
57
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
58
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
59
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
60
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
61
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
62
 */
63
64
#ifndef GUI_WIDGETS_WIDGET_H
65
#define GUI_WIDGETS_WIDGET_H
66
67
#include "enums/simpletypes/visible.h"
68
69
#include "gui/rect.h"
70
71
#include "gui/widgets/widget2.h"
72
73
#include <list>
74
75
#include "localconsts.h"
76
77
class ActionListener;
78
class WidgetDeathListener;
79
class FocusHandler;
80
class FocusListener;
81
class Font;
82
class Graphics;
83
class KeyListener;
84
class MouseListener;
85
class WidgetListener;
86
87
/**
88
  * Abstract class for widgets of Guichan. It contains basic functions
89
  * every widget should have.
90
  *
91
  * NOTE: Functions begining with underscore "_" should not
92
  *       be overloaded unless you know what you are doing
93
  *
94
  * @author Olof Naessén
95
  * @author Per Larsson.
96
  */
97
class Widget notfinal : public Widget2
98
{
99
    public:
100
        friend class BasicContainer;
101
102
        /**
103
          * Constructor. Resets member variables. Noteable, a widget is not
104
          * focusable as default, therefore, widgets that are supposed to be
105
          * focusable should overide this default in their own constructor.
106
          */
107
        explicit Widget(const Widget2 *const widget);
108
109
        A_DELETE_COPY(Widget)
110
111
        /**
112
          * Default destructor.
113
          */
114
        virtual ~Widget();
115
116
        /**
117
          * Draws the widget. It is called by the parent widget when it is time
118
          * for the widget to draw itself. The graphics object is set up so
119
          * that all drawing is relative to the widget, i.e coordinate (0,0) is
120
          * the top left corner of the widget. It is not possible to draw
121
          * outside of a widget's dimension.
122
          *
123
          * @param graphics aA graphics object to draw with.
124
          */
125
        virtual void draw(Graphics *const graphics) A_NONNULL(2) = 0;
126
127
        virtual void safeDraw(Graphics *const graphics) A_NONNULL(2) = 0;
128
129
        /**
130
          * Called when a widget is given a chance to draw a frame around itself.
131
          * The frame is not considered a part of the widget, it only allows a frame
132
          * to be drawn around the widget, thus a frame will never be included when
133
          * calculating if a widget should receive events from user input. Also
134
          * a widget's frame will never be included when calculating a widget's
135
          * position.
136
          *
137
          * The size of the frame is calculated using the widget's frame size.
138
          * If a widget has a frame size of 10 pixels than the area the drawFrame
139
          * function can draw to will be the size of the widget with an additional
140
          * extension of 10 pixels in each direction.
141
          *
142
          * An example when drawFrame is a useful function is if a widget needs
143
          * a glow around itself.
144
          *
145
          * @param graphics A graphics object to draw with.
146
          * @see setFrameSize, getFrameSize
147
          */
148
        virtual void drawFrame(Graphics* graphics A_UNUSED) A_NONNULL(2)
149
        { }
150
151
        virtual void safeDrawFrame(Graphics* graphics A_UNUSED) A_NONNULL(2)
152
        { }
153
154
        /**
155
          * Sets the size of the widget's frame. The frame is not considered a part of
156
          * the widget, it only allows a frame to be drawn around the widget, thus a frame
157
          * will never be included when calculating if a widget should receive events
158
          * from user input. Also a widget's frame will never be included when calculating
159
          * a widget's position.
160
          *
161
          * A frame size of 0 means that the widget has no frame. The default frame size
162
          * is 0.
163
          *
164
          * @param frameSize The size of the widget's frame.
165
          * @see getFrameSize, drawFrame
166
          */
167
        void setFrameSize(const unsigned int frameSize) noexcept2
168
1578
        { mFrameSize = frameSize; }
169
170
        /**
171
          * Gets the size of the widget's frame. The frame is not considered a part of
172
          * the widget, it only allows a frame to be drawn around the widget, thus a frame
173
          * will never be included when calculating if a widget should receive events
174
          * from user input. Also a widget's frame will never be included when calculating
175
          * a widget's position.
176
          *
177
          * A frame size of 0 means that the widget has no frame. The default frame size
178
          * is 0.
179
          *
180
          * @return The size of the widget's frame.
181
          * @see setFrameSize, drawFrame
182
          */
183
        unsigned int getFrameSize() const noexcept2 A_WARN_UNUSED
184
2064
        { return mFrameSize; }
185
186
        /**
187
          * Called for all widgets in the gui each time Gui::logic is called.
188
          * You can do logic stuff here like playing an animation.
189
          *
190
          * @see Gui::logic
191
          */
192
1
        virtual void logic()
193
1
        { }
194
195
        /**
196
          * Gets the widget's parent container.
197
          *
198
          * @return The widget's parent container. NULL if the widget
199
          *         has no parent.
200
          */
201
        Widget* getParent() const noexcept2 A_WARN_UNUSED
202
80
        { return mParent; }
203
204
        /**
205
          * Sets the width of the widget.
206
          *
207
          * @param width The width of the widget.
208
          * @see getWidth, setHeight, getHeight, setSize,
209
          *      setDimension, getDimensi
210
          */
211
        void setWidth(const int width);
212
213
        /**
214
          * Gets the width of the widget.
215
          *
216
          * @return The width of the widget.
217
          * @see setWidth, setHeight, getHeight, setSize,
218
          *      setDimension, getDimension
219
          */
220
        int getWidth() const noexcept2 A_WARN_UNUSED
221
35304
        { return mDimension.width; }
222
223
        /**
224
          * Sets the height of the widget.
225
          *
226
          * @param height The height of the widget.
227
          * @see getHeight, setWidth, getWidth, setSize,
228
          *      setDimension, getDimension
229
          */
230
        void setHeight(const int height);
231
232
        /**
233
          * Gets the height of the widget.
234
          *
235
          * @return The height of the widget.
236
          * @see setHeight, setWidth, getWidth, setSize,
237
          *      setDimension, getDimension
238
          */
239
        int getHeight() const noexcept2 A_WARN_UNUSED
240
12974
        { return mDimension.height; }
241
242
        /**
243
          * Sets the size of the widget.
244
          *
245
          * @param width The width of the widget.
246
          * @param height The height of the widget.
247
          * @see setWidth, setHeight, getWidth, getHeight,
248
          *      setDimension, getDimension
249
          */
250
        void setSize(const int width, const int height);
251
252
        /**
253
          * Sets the x coordinate of the widget. The coordinate is
254
          * relateive to the widget's parent.
255
          *
256
          * @param x The x coordinate of the widget.
257
          * @see getX, setY, getY, setPosition, setDimension, getDimension
258
          */
259
        void setX(const int x);
260
261
        /**
262
          * Gets the x coordinate of the widget. The coordinate is
263
          * relative to the widget's parent.
264
          *
265
          * @return The x coordinate of the widget.
266
          * @see setX, setY, getY, setPosition, setDimension, getDimension
267
          */
268
        int getX() const noexcept2 A_WARN_UNUSED
269
404
        { return mDimension.x; }
270
271
        /**
272
          * Sets the y coordinate of the widget. The coordinate is
273
          * relative to the widget's parent.
274
          *
275
          * @param y The y coordinate of the widget.
276
          * @see setY, setX, getX, setPosition, setDimension, getDimension
277
          */
278
        void setY(const int y);
279
280
        /**
281
          * Gets the y coordinate of the widget. The coordinate is
282
          * relative to the widget's parent.
283
          *
284
          * @return The y coordinate of the widget.
285
          * @see setY, setX, getX, setPosition, setDimension, getDimension
286
          */
287
        int getY() const noexcept2 A_WARN_UNUSED
288
586
        { return mDimension.y; }
289
290
        /**
291
          * Sets position of the widget. The position is relative
292
          * to the widget's parent.
293
          *
294
          * @param x The x coordinate of the widget.
295
          * @param y The y coordinate of the widget.
296
          * @see setX, getX, setY, getY, setDimension, getDimension
297
          */
298
        void setPosition(const int x, const int y);
299
300
        /**
301
          * Sets the dimension of the widget. The dimension is
302
          * relative to the widget's parent.
303
          *
304
          * @param dimension The dimension of the widget.
305
          * @see getDimension, setX, getX, setY, getY, setPosition
306
          */
307
        void setDimension(const Rect& dimension);
308
309
        /**
310
          * Gets the dimension of the widget. The dimension is
311
          * relative to the widget's parent.
312
          *
313
          * @return The dimension of the widget.
314
          * @see getDimension, setX, getX, setY, getY, setPosition
315
          */
316
        const Rect& getDimension() const noexcept2 A_WARN_UNUSED
317
132
        { return mDimension; }
318
319
        /**
320
          * Sets the widget to be fosusable, or not.
321
          *
322
          * @param focusable True if the widget should be focusable,
323
          *                  false otherwise.
324
          * @see isFocusable
325
          */
326
        void setFocusable(const bool focusable);
327
328
          /**
329
          * Checks if a widget is focsable.
330
          *
331
          * @return True if the widget should be focusable, false otherwise.
332
          * @see setFocusable
333
          */
334
        bool isFocusable() const A_WARN_UNUSED;
335
336
        /**
337
          * Checks if the widget is focused.
338
          *
339
          * @return True if the widget is focused, false otherwise.
340
          */
341
        virtual bool isFocused() const A_WARN_UNUSED;
342
343
        /**
344
          * Sets the widget to enabled, or not. A disabled
345
          * widget will never recieve mouse or key events.
346
          *
347
          * @param enabled True if widget should be enabled,
348
          *                false otherwise.
349
          * @see isEnabled
350
          */
351
        void setEnabled(const bool enabled) noexcept2
352
780
        { mEnabled = enabled; }
353
354
        /**
355
          * Checks if the widget is enabled. A disabled
356
          * widget will never recieve mouse or key events.
357
          *
358
          * @return True if widget is enabled, false otherwise.
359
          * @see setEnabled
360
          */
361
        bool isEnabled() const A_WARN_UNUSED;
362
363
        /**
364
          * Sets the widget to be visible, or not.
365
          *
366
          * @param visible True if widget should be visible, false otherwise.
367
          * @see isVisible
368
          */
369
        void setVisible(Visible visible);
370
371
        /**
372
          * Checks if the widget is visible.
373
          *
374
          * @return True if widget is be visible, false otherwise.
375
          * @see setVisible
376
          */
377
524
        bool isVisible() const A_WARN_UNUSED
378
        {
379





1546
            return mVisible == Visible_true &&
380


1291
                ((mParent == nullptr) || mParent->isVisible());
381
        }
382
383
        /**
384
          * Sets the base color of the widget.
385
          *
386
          * @param color The baseground color.
387
          * @see getBaseColor
388
          */
389
        void setBaseColor(const Color& color) noexcept2
390
        { mBaseColor = color; }
391
392
        /**
393
          * Gets the base color.
394
          *
395
          * @return The base color.
396
          * @see setBaseColor
397
          */
398
        const Color& getBaseColor() const noexcept2 A_WARN_UNUSED
399
        { return mBaseColor; }
400
401
        /**
402
          * Sets the foreground color.
403
          *
404
          * @param color The foreground color.
405
          * @see getForegroundColor
406
          */
407
        void setForegroundColor(const Color& color) noexcept2
408
        { mForegroundColor = color; }
409
410
        /**
411
          * Gets the foreground color.
412
          *
413
          * @see setForegroundColor
414
          */
415
        const Color& getForegroundColor() const noexcept2 A_WARN_UNUSED
416
        { return mForegroundColor; }
417
418
        /**
419
          * Sets the background color.
420
          *
421
          * @param color The background Color.
422
          * @see setBackgroundColor
423
          */
424
        void setBackgroundColor(const Color &color) noexcept2
425
4
        { mBackgroundColor = color; }
426
427
        /**
428
          * Gets the background color.
429
          *
430
          * @see setBackgroundColor
431
          */
432
        const Color &getBackgroundColor() const noexcept2 A_WARN_UNUSED
433
        { return mBackgroundColor; }
434
435
        /**
436
          * Requests focus for the widget. A widget will only recieve focus
437
          * if it is focusable.
438
          */
439
        virtual void requestFocus();
440
441
        /**
442
          * Requests a move to the top in the parent widget.
443
          */
444
        virtual void requestMoveToTop();
445
446
        /**
447
          * Requests a move to the bottom in the parent widget.
448
          */
449
        virtual void requestMoveToBottom();
450
451
        /**
452
          * Sets the focus handler to be used.
453
          *
454
          * WARNING: This function is used internally and should not
455
          *          be called or overloaded unless you know what you
456
          *          are doing.
457
          *
458
          * @param focusHandler The focus handler to use.
459
          * @see getFocusHandler
460
          */
461
        virtual void setFocusHandler(FocusHandler *const focusHandler);
462
463
        /**
464
          * Gets the focus handler used.
465
          *
466
          * WARNING: This function is used internally and should not
467
          *          be called or overloaded unless you know what you
468
          *          are doing.
469
          *
470
          * @return The focus handler used.
471
          * @see setFocusHandler
472
          */
473
        FocusHandler* getFocusHandler() noexcept2 A_WARN_UNUSED
474
4348
        { return mFocusHandler; }
475
476
        /**
477
          * Adds an action listener to the widget. When an action event
478
          * is fired by the widget the action listeners of the widget
479
          * will get notified.
480
          *
481
          * @param actionListener The action listener to add.
482
          * @see removeActionListener
483
          */
484
        void addActionListener(ActionListener *const actionListener);
485
486
        /**
487
          * Removes an added action listener from the widget.
488
          *
489
          * @param actionListener The action listener to remove.
490
          * @see addActionListener
491
          */
492
        void removeActionListener(ActionListener *const actionListener);
493
494
        /**
495
          * Adds a death listener to the widget. When a death event is
496
          * fired by the widget the death listeners of the widget will
497
          * get notified.
498
          *
499
          * @param deathListener The death listener to add.
500
          * @see removeDeathListener
501
          */
502
        void addDeathListener(WidgetDeathListener *const deathListener);
503
504
        /**
505
          * Removes an added death listener from the widget.
506
          *
507
          * @param deathListener The death listener to remove.
508
          * @see addDeathListener
509
          */
510
        void removeDeathListener(WidgetDeathListener *const deathListener);
511
512
        /**
513
          * Adds a mouse listener to the widget. When a mouse event is
514
          * fired by the widget the mouse listeners of the widget will
515
          * get notified.
516
          *
517
          * @param mouseListener The mouse listener to add.
518
          * @see removeMouseListener
519
          */
520
        void addMouseListener(MouseListener *const mouseListener);
521
522
        /**
523
          * Removes an added mouse listener from the widget.
524
          *
525
          * @param mouseListener The mouse listener to remove.
526
          * @see addMouseListener
527
          */
528
        void removeMouseListener(MouseListener *const mouseListener);
529
530
        /**
531
          * Adds a key listener to the widget. When a key event is
532
          * fired by the widget the key listeners of the widget will
533
          * get notified.
534
          *
535
          * @param keyListener The key listener to add.
536
          * @see removeKeyListener
537
          */
538
        void addKeyListener(KeyListener *const keyListener);
539
540
        /**
541
          * Removes an added key listener from the widget.
542
          *
543
          * @param keyListener The key listener to remove.
544
          * @see addKeyListener
545
          */
546
        void removeKeyListener(KeyListener *const keyListener);
547
548
        /**
549
          * Adds a focus listener to the widget. When a focus event is
550
          * fired by the widget the key listeners of the widget will
551
          * get notified.
552
          *
553
          * @param focusListener The focus listener to add.
554
          * @see removeFocusListener
555
          */
556
        void addFocusListener(FocusListener *const focusListener);
557
558
        /**
559
          * Removes an added focus listener from the widget.
560
          *
561
          * @param focusListener The focus listener to remove.
562
          * @see addFocusListener
563
          */
564
        void removeFocusListener(FocusListener *const focusListener);
565
566
        /**
567
          * Adds a widget listener to the widget. When a widget event is
568
          * fired by the widget the key listeners of the widget will
569
          * get notified.
570
          *
571
          * @param widgetListener The widget listener to add.
572
          * @see removeWidgetListener
573
          */
574
        void addWidgetListener(WidgetListener *const widgetListener);
575
576
        /**
577
          * Removes an added widget listener from the widget.
578
          *
579
          * @param widgetListener The widget listener to remove.
580
          * @see addWidgetListener
581
          */
582
        void removeWidgetListener(WidgetListener *const widgetListener);
583
584
        /**
585
          * Sets the action event identifier of the widget. The identifier is
586
          * used to be able to identify which action has occured.
587
          *
588
          * NOTE: An action event identifier should not be used to identify a
589
          *       certain widget but rather a certain event in your application.
590
          *       Several widgets can have the same action event identifer.
591
          *
592
          * @param actionEventId The action event identifier.
593
          * @see getActionEventId
594
          */
595
        void setActionEventId(const std::string &actionEventId) noexcept2
596
3540
        { mActionEventId = actionEventId; }
597
598
        /**
599
          * Gets the action event identifier of the widget.
600
          *
601
          * @return The action event identifier of the widget.
602
          * @see setActionEventId
603
          */
604
        const std::string &getActionEventId() const noexcept2
605
        { return mActionEventId; }
606
607
        /**
608
          * Gets the absolute position on the screen for the widget.
609
          *
610
          * @param x The absolute x coordinate will be stored in this parameter.
611
          * @param y The absolute y coordinate will be stored in this parameter.
612
          */
613
        virtual void getAbsolutePosition(int& x, int& y) const;
614
615
        /**
616
          * Sets the parent of the widget. A parent must be a BasicContainer.
617
          *
618
          * WARNING: This function is used internally and should not
619
          *          be called or overloaded unless you know what you
620
          *          are doing.
621
          *
622
          * @param parent The parent of the widget.
623
          * @see getParent
624
          */
625
1962
        virtual void setParent(Widget* parent)
626
4490
        { mParent = parent; }
627
628
        /**
629
          * Gets the font set for the widget. If no font has been set,
630
          * the global font will be returned. If no global font has been set,
631
          * the default font will be returend.
632
          *
633
          * @return The font set for the widget.
634
          * @see setFont, setGlobalFont
635
          */
636
        Font *getFont() const RETURNS_NONNULL A_WARN_UNUSED;
637
638
        /**
639
          * Sets the global font to be used by default for all widgets.
640
          *
641
          * @param font The global font.
642
          * @see getGlobalFont
643
          */
644
        static void setGlobalFont(Font *const font);
645
646
        static Font *getGloablFont()
647
2
        { return mGlobalFont; }
648
649
        static void cleanGlobalFont()
650
248
        { mGlobalFont = nullptr; }
651
652
        /**
653
          * Sets the font for the widget. If NULL is passed, the global font
654
          * will be used.
655
          *
656
          * @param font The font to set for the widget.
657
          * @see getFont
658
          */
659
        void setFont(Font *const font);
660
661
        /**
662
          * Called when the font has changed. If the change is global,
663
          * this function will only be called if the widget doesn't have a
664
          * font already set.
665
          */
666
290
        virtual void fontChanged()
667
290
        { }
668
669
        /**
670
          * Checks if a widget exists or not, that is if it still exists
671
          * an instance of the object.
672
          *
673
          * @param widget The widget to check.
674
          * @return True if an instance of the widget exists, false otherwise.
675
          */
676
        static bool widgetExists(const Widget *const widget) A_WARN_UNUSED;
677
678
        /**
679
          * Checks if tab in is enabled. Tab in means that you can set focus
680
          * to this widget by pressing the tab button. If tab in is disabled
681
          * then the focus handler will skip this widget and focus the next
682
          * in its focus order.
683
          *
684
          * @return True if tab in is enabled, false otherwise.
685
          * @see setTabInEnabled
686
          */
687
        bool isTabInEnabled() const noexcept2 A_WARN_UNUSED
688
        { return mTabIn; }
689
690
        /**
691
          * Sets tab in enabled, or not. Tab in means that you can set focus
692
          * to this widget by pressing the tab button. If tab in is disabled
693
          * then the FocusHandler will skip this widget and focus the next
694
          * in its focus order.
695
          *
696
          * @param enabled True if tab in should be enabled, false otherwise.
697
          * @see isTabInEnabled
698
          */
699
        void setTabInEnabled(const bool enabled) noexcept2
700
        { mTabIn = enabled; }
701
702
        /**
703
          * Checks if tab out is enabled. Tab out means that you can lose
704
          * focus to this widget by pressing the tab button. If tab out is
705
          * disabled then the FocusHandler ignores tabbing and focus will
706
          * stay with this widget.
707
          *
708
          * @return True if tab out is enabled, false otherwise.
709
          * @see setTabOutEnabled
710
          */
711
        bool isTabOutEnabled() const noexcept2 A_WARN_UNUSED
712
        { return mTabOut; }
713
714
        /**
715
          * Sets tab out enabled. Tab out means that you can lose
716
          * focus to this widget by pressing the tab button. If tab out is
717
          * disabled then the FocusHandler ignores tabbing and focus will
718
          * stay with this widget.
719
          *
720
          * @param enabled True if tab out should be enabled, false otherwise.
721
          * @see isTabOutEnabled
722
          */
723
        void setTabOutEnabled(const bool enabled) noexcept2
724
        { mTabOut = enabled; }
725
726
        /**
727
          * Requests modal focus. When a widget has modal focus, only that
728
          * widget and it's children may recieve input.
729
          *
730
          * @throws Exception if another widget already has modal focus.
731
          * @see releaseModalFocus, isModalFocused
732
          */
733
        void requestModalFocus();
734
735
        /**
736
          * Requests modal mouse input focus. When a widget has modal input focus
737
          * that widget will be the only widget receiving input even if the input
738
          * occurs outside of the widget and no matter what the input is.
739
          *
740
          * @throws Exception if another widget already has modal focus.
741
          * @see releaseModalMouseInputFocus, isModalMouseInputFocused
742
          */
743
        virtual void requestModalMouseInputFocus();
744
745
        /**
746
          * Releases modal focus. Modal focus will only be released if the
747
          * widget has modal focus.
748
          *
749
          * @see requestModalFocus, isModalFocused
750
          */
751
        virtual void releaseModalFocus();
752
753
        /**
754
          * Releases modal mouse input focus. Modal mouse input focus will only
755
          * be released if the widget has modal mouse input focus.
756
          *
757
          * @see requestModalMouseInputFocus, isModalMouseInputFocused
758
          */
759
        virtual void releaseModalMouseInputFocus();
760
761
        /**
762
          * Checks if the widget or it's parent has modal focus.
763
          *
764
          * @return True if the widget has modal focus, false otherwise.
765
          * @see requestModalFocus, releaseModalFocus
766
          */
767
        virtual bool isModalFocused() const A_WARN_UNUSED;
768
769
        /**
770
          * Checks if the widget or it's parent has modal mouse input focus.
771
          *
772
          * @return True if the widget has modal mouse input focus, false
773
          *         otherwise.
774
          * @see requestModalMouseInputFocus, releaseModalMouseInputFocus
775
          */
776
        virtual bool isModalMouseInputFocused() const A_WARN_UNUSED;
777
778
        /**
779
          * Gets a widget from a certain position in the widget.
780
          * This function is used to decide which gets mouse input,
781
          * thus it can be overloaded to change that behaviour.
782
          *
783
          * NOTE: This always returns NULL if the widget is not
784
          *       a container.
785
          *
786
          * @param x The x coordinate of the widget to get.
787
          * @param y The y coordinate of the widget to get.
788
          * @return The widget at the specified coodinate, NULL
789
          *         if no widget is found.
790
          */
791
        virtual Widget *getWidgetAt(int x A_UNUSED,
792
                                    int y A_UNUSED) A_WARN_UNUSED
793
        { return nullptr; }
794
795
        /**
796
          * Gets the mouse listeners of the widget.
797
          *
798
          * @return The mouse listeners of the widget.
799
          */
800
        const std::list<MouseListener*>& getMouseListeners() const
801
                                         A_CONST A_WARN_UNUSED;
802
803
        /**
804
          * Gets the key listeners of the widget.
805
          *
806
          * @return The key listeners of the widget.
807
          */
808
        const std::list<KeyListener*>& getKeyListeners() const
809
                                       A_CONST A_WARN_UNUSED;
810
811
        /**
812
          * Gets the focus listeners of the widget.
813
          *
814
          * @return The focus listeners of the widget.
815
          */
816
        const std::list<FocusListener*>& getFocusListeners() const
817
                                         A_CONST A_WARN_UNUSED;
818
819
        /**
820
          * Gets the area of the widget occupied by the widget's children.
821
          * By default this method returns an empty rectangle as not all
822
          * widgets are containers. If you want to make a container this
823
          * method should return the area where the children resides. This
824
          * method is used when drawing children of a widget when computing
825
          * clip rectangles for the children.
826
          *
827
          * An example of a widget that overloads this method is ScrollArea.
828
          * A ScrollArea has a view of its contant and that view is the
829
          * children area. The size of a ScrollArea's children area might
830
          * vary depending on if the scroll bars of the ScrollArea is shown
831
          * or not.
832
          *
833
          * @return The area of the widget occupied by the widget's children.
834
          * @see BasicContainer
835
          * @see BasicContainer::getChildrenArea
836
          * @see BasicContainer::drawChildren
837
          */
838
        virtual Rect getChildrenArea() A_WARN_UNUSED;
839
840
        /**
841
          * Gets the internal focus handler used.
842
          *
843
          * @return the internalFocusHandler used. If no internal focus handler
844
          *         is used, NULL will be returned.
845
          * @see setInternalFocusHandler
846
          */
847
        virtual FocusHandler* getInternalFocusHandler() A_WARN_UNUSED;
848
849
        /**
850
          * Sets the internal focus handler. An internal focus handler is
851
          * needed if both a widget in the widget and the widget itself
852
          * should be foucsed at the same time.
853
          *
854
          * @param focusHandler The internal focus handler to be used.
855
          * @see getInternalFocusHandler
856
          */
857
        void setInternalFocusHandler(FocusHandler *const internalFocusHandler);
858
859
        /**
860
          * Moves a widget to the top of this widget. The moved widget will be
861
          * drawn above all other widgets in this widget.
862
          *
863
          * @param widget The widget to move to the top.
864
          * @see moveToBottom
865
          */
866
        virtual void moveToTop(Widget* widget A_UNUSED)
867
        { }
868
869
        /**
870
          * Moves a widget in this widget to the bottom of this widget.
871
          * The moved widget will be drawn below all other widgets in this widget.
872
          *
873
          * @param widget The widget to move to the bottom.
874
          * @see moveToTop
875
          */
876
        virtual void moveToBottom(Widget* widget A_UNUSED)
877
        { }
878
879
        /**
880
          * Focuses the next widget in the widget.
881
          *
882
          * @see moveToBottom
883
          */
884
        virtual void focusNext()
885
        { }
886
887
        /**
888
          * Focuses the previous widget in the widget.
889
          *
890
          * @see moveToBottom
891
          */
892
        virtual void focusPrevious()
893
        { }
894
895
        /**
896
          * Tries to show a specific part of a widget by moving it. Used if the
897
          * widget should act as a container.
898
          *
899
          * @param widget The target widget.
900
          * @param area The area to show.
901
          */
902
        virtual void showWidgetPart(Widget *const widget A_UNUSED,
903
                                    const Rect &area A_UNUSED)
904
        { }
905
906
        /**
907
          * Sets an id of a widget. An id can be useful if a widget needs to be
908
          * identified in a container. For example, if widgets are created by an
909
          * XML document, a certain widget can be retrieved given that the widget
910
          * has an id.
911
          *
912
          * @param id The id to set to the widget.
913
          * @see getId
914
          */
915
        void setId(const std::string& id)
916
36
        { mId = id; }
917
918
        const std::string& getId() const noexcept2 A_WARN_UNUSED
919
        { return mId; }
920
921
        /**
922
          * Shows a certain part of a widget in the widget's parent.
923
          * Used when widgets want a specific part to be visible in
924
          * its parent. An example is a TextArea that wants a specific
925
          * part of its text to be visible when a TextArea is a child
926
          * of a ScrollArea.
927
          *
928
          * @param rectangle The rectangle to be shown.
929
          */
930
        virtual void showPart(const Rect &rectangle);
931
932
        bool isAllowLogic() const noexcept2 A_WARN_UNUSED
933
4332
        { return mAllowLogic; }
934
935
        void setMouseConsume(const bool b) noexcept2
936
376
        { mMouseConsume = b; }
937
938
        bool isMouseConsume() const noexcept2 A_WARN_UNUSED
939
        { return mMouseConsume; }
940
941
        void setRedraw(const bool b) noexcept2
942
2
        { mRedraw = b; }
943
944
        virtual bool isSelectable() const noexcept2 A_WARN_UNUSED
945
        { return mSelectable; }
946
947
        void setSelectable(const bool selectable) noexcept2
948
1278
        { mSelectable = selectable; }
949
950
        static void distributeWindowResizeEvent();
951
952
        void windowResized();
953
954
        static Widget *callPostInit(Widget *const widget) RETURNS_NONNULL;
955
956
        virtual void postInit()
957
        { }
958
959
        /**
960
          * True if the widget visible, false otherwise.
961
          */
962
        Visible mVisible;
963
964
    protected:
965
        /**
966
          * Distributes an action event to all action listeners
967
          * of the widget.
968
          */
969
        void distributeActionEvent();
970
971
        /**
972
          * Distributes resized events to all of the widget's listeners.
973
          */
974
        void distributeResizedEvent();
975
976
        /**
977
          * Distributes moved events to all of the widget's listeners.
978
          */
979
        void distributeMovedEvent();
980
981
        /**
982
          * Distributes hidden events to all of the widget's listeners.
983
          *
984
          * @author Olof Naessén
985
          */
986
        void distributeHiddenEvent();
987
988
        /**
989
          * Distributes shown events to all of the widget's listeners.
990
          *
991
          * @author Olof Naessén
992
          */
993
        void distributeShownEvent();
994
995
        /**
996
          * Typdef.
997
          */
998
        typedef std::list<MouseListener*> MouseListenerList;
999
1000
        /**
1001
          * Typdef.
1002
          */
1003
        typedef MouseListenerList::iterator MouseListenerIterator;
1004
1005
        /**
1006
          * Holds the mouse listeners of the widget.
1007
          */
1008
        MouseListenerList mMouseListeners;
1009
1010
        /**
1011
          * Typdef.
1012
          */
1013
        typedef std::list<KeyListener*> KeyListenerList;
1014
1015
        /**
1016
          * Holds the key listeners of the widget.
1017
          */
1018
        KeyListenerList mKeyListeners;
1019
1020
        /**
1021
          * Typdef.
1022
          */
1023
        typedef KeyListenerList::iterator KeyListenerIterator;
1024
1025
        /**
1026
          * Typdef.
1027
          */
1028
        typedef std::list<ActionListener*> ActionListenerList;
1029
1030
        /**
1031
          * Holds the action listeners of the widget.
1032
          */
1033
        ActionListenerList mActionListeners;
1034
1035
        /**
1036
          * Typdef.
1037
          */
1038
        typedef ActionListenerList::iterator ActionListenerIterator;
1039
1040
        /**
1041
          * Typdef.
1042
          */
1043
        typedef std::list<WidgetDeathListener*> WidgetDeathListenerList;
1044
1045
        /**
1046
          * Holds the death listeners of the widget.
1047
          */
1048
        WidgetDeathListenerList mDeathListeners;
1049
1050
        /**
1051
          * Typdef.
1052
          */
1053
        typedef WidgetDeathListenerList::iterator WidgetDeathListenerIterator;
1054
1055
        /**
1056
          * Typdef.
1057
          */
1058
        typedef std::list<FocusListener*> FocusListenerList;
1059
1060
        /**
1061
          * Holds the focus listeners of the widget.
1062
          */
1063
        FocusListenerList mFocusListeners;
1064
1065
        /**
1066
          * Typdef.
1067
          */
1068
        typedef FocusListenerList::iterator FocusListenerIterator;
1069
1070
        typedef std::list<WidgetListener*> WidgetListenerList;
1071
1072
        /**
1073
          * Holds the widget listeners of the widget.
1074
          */
1075
        WidgetListenerList mWidgetListeners;
1076
1077
        /**
1078
          * Typdef.
1079
          */
1080
        typedef WidgetListenerList::iterator WidgetListenerIterator;
1081
1082
        /**
1083
          * Holds the foreground color of the widget.
1084
          */
1085
        Color mForegroundColor;
1086
1087
        /**
1088
          * Holds the background color of the widget.
1089
          */
1090
        Color mBackgroundColor;
1091
1092
        /**
1093
          * Holds the base color of the widget.
1094
          */
1095
        Color mBaseColor;
1096
1097
        /**
1098
          * Holds the dimension of the widget.
1099
          */
1100
        Rect mDimension;
1101
1102
        /**
1103
          * Holds the action event of the widget.
1104
          */
1105
        std::string mActionEventId;
1106
1107
        /**
1108
          * Holds the id of the widget.
1109
          */
1110
        std::string mId;
1111
1112
        /**
1113
          * Holds the focus handler used by the widget.
1114
          */
1115
        FocusHandler* mFocusHandler;
1116
1117
        /**
1118
          * Holds the focus handler used by the widget. NULL
1119
          * if no internal focus handler is used.
1120
          */
1121
        FocusHandler* mInternalFocusHandler;
1122
1123
        /**
1124
          * Holds the parent of the widget. NULL if the widget
1125
          * has no parent.
1126
          */
1127
        Widget* mParent;
1128
1129
        /**
1130
          * Holds the font used by the widget.
1131
          */
1132
        Font* mCurrentFont;
1133
1134
        /**
1135
          * Holds the frame size of the widget.
1136
          */
1137
        unsigned int mFrameSize;
1138
1139
        /**
1140
          * True if the widget focusable, false otherwise.
1141
          */
1142
        bool mFocusable;
1143
1144
        /**
1145
          * True if the widget has tab in enabled, false otherwise.
1146
          */
1147
        bool mTabIn;
1148
1149
        /**
1150
          * True if the widget has tab in enabled, false otherwise.
1151
          */
1152
        bool mTabOut;
1153
1154
        /**
1155
          * True if the widget is enabled, false otherwise.
1156
          */
1157
        bool mEnabled;
1158
1159
        bool mAllowLogic;
1160
1161
        bool mMouseConsume;
1162
1163
        bool mRedraw;
1164
1165
        bool mSelectable;
1166
1167
        /**
1168
          * Holds the global font used by the widget.
1169
          */
1170
        static Font* mGlobalFont;
1171
1172
    private:
1173
        /**
1174
          * Holds a list of all instances of widgets.
1175
          */
1176
        static std::list<Widget*> mAllWidgets;
1177
1178
        static std::set<Widget*> mAllWidgetsSet;
1179
};
1180
1181
#endif  // GUI_WIDGETS_WIDGET_H