1 | /* |
2 | * Copyright 2007 by Dan Meltzer <hydrogen@notyetimplemented.com> |
3 | * Copyright 2008 by Aaron Seigo <aseigo@kde.org> |
4 | * Copyright 2008 by Alexis Ménard <darktears31@gmail.com> |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Lesser General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2.1 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Lesser General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Lesser General Public |
17 | * License along with this library; if not, write to the Free Software |
18 | * Foundation, Inc., 51 Franklin St, Fifth Floor, |
19 | * Boston, MA 02110-1301 USA |
20 | */ |
21 | |
22 | #ifndef PLASMA_TOOLTIP_MANAGER_H |
23 | #define PLASMA_TOOLTIP_MANAGER_H |
24 | |
25 | #include <kurl.h> |
26 | |
27 | #include <plasma/plasma.h> |
28 | #include <plasma/plasma_export.h> |
29 | #include <plasma/tooltipcontent.h> |
30 | |
31 | namespace Plasma |
32 | { |
33 | |
34 | class ToolTipManagerPrivate; |
35 | class Applet; |
36 | class Corona; |
37 | |
38 | /** |
39 | * @class ToolTipManager plasma/tooltipmanager.h <Plasma/ToolTipManager> |
40 | * |
41 | * @short Manages tooltips for QGraphicsWidgets in Plasma |
42 | * |
43 | * If you want a widget to have a tooltip displayed when the mouse is hovered over |
44 | * it, you should do something like: |
45 | * |
46 | * @code |
47 | * // widget is a QGraphicsWidget* |
48 | * Plasma::ToolTipContent data; |
49 | * data.mainText = i18n("My Title"); |
50 | * data.subText = i18n("This is a little tooltip"); |
51 | * data.image = KIcon("some-icon").pixmap(IconSize(KIconLoader::Desktop)); |
52 | * Plasma::ToolTipManager::self()->setContent(widget, data); |
53 | * @endcode |
54 | * |
55 | * Note that, since a Plasma::Applet is a QGraphicsWidget, you can use |
56 | * Plasma::ToolTipManager::self()->setContent(this, data); in the |
57 | * applet's init() method to set a tooltip for the whole applet. |
58 | * |
59 | * The tooltip will be registered automatically by setContent(). It will be |
60 | * automatically unregistered when the associated widget is deleted, freeing the |
61 | * memory used by the tooltip, but you can manually unregister it at any time by |
62 | * calling unregisterWidget(). |
63 | * |
64 | * When a tooltip for a widget is about to be shown, the widget's toolTipAboutToShow() slot will be |
65 | * invoked if it exists. Similarly, when a tooltip is hidden, the widget's toolTipHidden() slot |
66 | * will be invoked if it exists. This allows widgets to provide on-demand tooltip data. |
67 | */ |
68 | |
69 | class PLASMA_EXPORT ToolTipManager : public QObject |
70 | { |
71 | Q_OBJECT |
72 | public: |
73 | |
74 | enum State { |
75 | Activated = 0 /**<< Will accept tooltip data and show tooltips */, |
76 | Inhibited /**<< Will accept tooltip data, but not show tooltips */, |
77 | Deactivated /**<< Will discard tooltip data, and not attempt to show them */ |
78 | }; |
79 | |
80 | /** |
81 | * @return The singleton instance of the manager. |
82 | */ |
83 | static ToolTipManager *self(); |
84 | |
85 | /** |
86 | * Show the tooltip for a widget registered in the tooltip manager |
87 | * |
88 | * @param widget the widget for which the tooltip will be displayed |
89 | */ |
90 | void show(QGraphicsWidget *widget); |
91 | |
92 | /** |
93 | * Find out whether the tooltip for a given widget is currently being displayed. |
94 | * |
95 | * @param widget the widget to check the tooltip for |
96 | * @return true if the tooltip of the widget is currently displayed, |
97 | * false if not |
98 | */ |
99 | bool isVisible(QGraphicsWidget *widget) const; |
100 | |
101 | /** |
102 | * Hides the tooltip for a widget immediately. |
103 | * |
104 | * @param widget the widget to hide the tooltip for |
105 | */ |
106 | void hide(QGraphicsWidget *widget); |
107 | |
108 | /** |
109 | * Registers a widget with the tooltip manager. |
110 | * |
111 | * Note that setContent() will register the widget if it |
112 | * has not already been registered, and so you do not normally |
113 | * need to use the method. |
114 | * |
115 | * This is useful for creating tooltip content on demand. You can |
116 | * register your widget with registerWidget(), then implement |
117 | * a slot named toolTipAboutToShow for the widget. This will be |
118 | * called before the tooltip is shown, allowing you to set the |
119 | * data with setContent(). |
120 | * |
121 | * If the widget also has a toolTipHidden slot, this will be called |
122 | * after the tooltip is hidden. |
123 | * |
124 | * @param widget the desired widget |
125 | */ |
126 | void registerWidget(QGraphicsWidget *widget); |
127 | |
128 | /** |
129 | * Unregisters a widget from the tooltip manager. |
130 | * |
131 | * This will free the memory used by the tooltip associated with the widget. |
132 | * |
133 | * @param widget the desired widget to delete |
134 | */ |
135 | void unregisterWidget(QGraphicsWidget *widget); |
136 | |
137 | /** |
138 | * Sets the content for the tooltip associated with a widget. |
139 | * |
140 | * Note that this will register the widget with the ToolTipManager if |
141 | * necessary, so there is usually no need to call registerWidget(). |
142 | * |
143 | * @param widget the widget the tooltip should be associated with |
144 | * @param data the content of the tooltip. If an empty Content |
145 | * is passed in, the tooltip content will be reset. |
146 | */ |
147 | void setContent(QGraphicsWidget *widget, |
148 | const ToolTipContent &data); |
149 | |
150 | /** |
151 | * Clears the tooltip data associated with this widget, but keeps |
152 | * the widget registered. |
153 | */ |
154 | void clearContent(QGraphicsWidget *widget); |
155 | |
156 | /** |
157 | * Sets the current state of the manager. |
158 | * @see State |
159 | * @param state the state to put the manager in |
160 | */ |
161 | void setState(ToolTipManager::State state); |
162 | |
163 | /** |
164 | * @return the current state of the manager; @see State |
165 | */ |
166 | ToolTipManager::State state() const; |
167 | |
168 | Q_SIGNALS: |
169 | /** |
170 | * This signal is emitted when a window preview in the tooltip is clicked. |
171 | * @param window the id of the window that was clicked |
172 | * @param buttons the mouse buttons involved in the activation |
173 | * @param modifiers the keyboard modifiers involved in the activation, if any |
174 | * @since 4.4 |
175 | */ |
176 | void windowPreviewActivated(WId window, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, |
177 | const QPoint &screenPos); |
178 | |
179 | /** |
180 | * This signal is emitted when a link in the tooltip is clicked. |
181 | * @param anchor the achor text (e.g. url) that was clicked on |
182 | * @param buttons the mouse buttons involved in the activation |
183 | * @param modifiers the keyboard modifiers involved in the activation, if any |
184 | * @since 4.4 |
185 | */ |
186 | void linkActivated(const QString &anchor, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, |
187 | const QPoint &screenPos); |
188 | |
189 | private: |
190 | /** |
191 | * Default constructor. |
192 | * |
193 | * You should normall use self() instead. |
194 | */ |
195 | explicit ToolTipManager(QObject *parent = 0); |
196 | |
197 | /** |
198 | * Default destructor. |
199 | */ |
200 | ~ToolTipManager(); |
201 | |
202 | friend class ToolTipManagerSingleton; |
203 | friend class Corona; // The corona needs to register itself |
204 | friend class ToolTipManagerPrivate; |
205 | bool eventFilter(QObject *watched, QEvent *event); |
206 | |
207 | ToolTipManagerPrivate *const d; |
208 | Corona* m_corona; |
209 | |
210 | Q_PRIVATE_SLOT(d, void showToolTip()) |
211 | Q_PRIVATE_SLOT(d, void toolTipHovered(bool)) |
212 | Q_PRIVATE_SLOT(d, void resetShownState()) |
213 | Q_PRIVATE_SLOT(d, void onWidgetDestroyed(QObject*)) |
214 | }; |
215 | |
216 | } // namespace Plasma |
217 | |
218 | #endif // PLASMA_TOOL_TIP_MANAGER_H |
219 | |