1 /** @file textwidget.h Generic widget with a text-based visual. 2 * 3 * @authors Copyright © 2013-2017 Jaakko Keränen <jaakko.keranen@iki.fi> 4 * 5 * @par License 6 * LGPL: http://www.gnu.org/licenses/lgpl.html 7 * 8 * <small>This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU Lesser General Public License as published by 10 * the Free Software Foundation; either version 3 of the License, or (at your 11 * option) any later version. This program is distributed in the hope that it 12 * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty 13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser 14 * General Public License for more details. You should have received a copy of 15 * the GNU Lesser General Public License along with this program; if not, see: 16 * http://www.gnu.org/licenses</small> 17 */ 18 19 #ifndef LIBSHELL_TEXTWIDGET_H 20 #define LIBSHELL_TEXTWIDGET_H 21 22 #include "libshell.h" 23 #include <de/Widget> 24 #include <de/RuleRectangle> 25 #include <QObject> 26 #include <QFlags> 27 #include "TextCanvas" 28 29 namespace de { namespace shell { 30 31 class TextRootWidget; 32 class Action; 33 34 /** 35 * Generic widget with a text-based visual. 36 * 37 * TextWidget is the base class for all widgets in libshell, because they are 38 * intended to be device-independent and compatible with all character-based 39 * UIs, regardless of whether the underlying device is text-only or graphical. 40 * 41 * It is assumed that the root widget under which text widgets are used is 42 * derived from TextRootWidget. 43 * 44 * QObject is a base class for the signals and slots capabilities. 45 * 46 * @ingroup textUi 47 */ 48 class LIBSHELL_PUBLIC TextWidget 49 : public QObject 50 , public Widget 51 { 52 Q_OBJECT 53 54 public: 55 TextWidget(String const &name = String()); 56 57 TextRootWidget &root() const; 58 59 /** 60 * Sets the text canvas on which this widget is to be drawn. Calling this 61 * is optional; by default all widgets use the root widget's canvas. 62 * 63 * @param canvas Canvas for drawing. Ownership not taken. 64 */ 65 void setTargetCanvas(TextCanvas *canvas); 66 67 /** 68 * Returns the text canvas on which this widget is to be drawn. Derived 69 * classes can use this method to find out where to draw themselves. 70 * 71 * @return Destination canvas for drawing. 72 */ 73 TextCanvas &targetCanvas() const; 74 75 /** 76 * Requests the root widget to redraw all the user interface. 77 */ 78 void redraw(); 79 80 /** 81 * Draw this widget and all its children, and show the target canvas 82 * afterwards. Use this in special cases for faster redrawing of portions 83 * of the screen when only one widget's contents have changed and need 84 * updating. 85 */ 86 void drawAndShow(); 87 88 /** 89 * Returns the rule rectangle that defines the placement of the widget on 90 * the target canvas. 91 */ 92 RuleRectangle &rule(); 93 94 /** 95 * Returns the rule rectangle that defines the placement of the widget on 96 * the target canvas. 97 */ 98 RuleRectangle const &rule() const; 99 100 /** 101 * Returns the position of the cursor for the widget. If the widget 102 * has focus, this is where the cursor will be positioned. 103 * 104 * @return Cursor position. 105 */ 106 virtual Vector2i cursorPosition() const; 107 108 /** 109 * Adds a new action for the widget. During event processing actions are 110 * checked in the order they have been added to the widget. 111 * 112 * @param action Action instance. Ownership taken. 113 */ 114 void addAction(RefArg<Action> action); 115 116 /** 117 * Removes an action from the widget. 118 * 119 * @param action Action instance. 120 */ 121 void removeAction(Action &action); 122 123 /** 124 * Checks actions and triggers them when suitable event is received. 125 */ 126 bool handleEvent(Event const &event); 127 128 private: 129 DENG2_PRIVATE(d) 130 }; 131 132 }} // namespace de::shell 133 134 #endif // LIBSHELL_TEXTWIDGET_H 135