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
31namespace Plasma
32{
33
34class ToolTipManagerPrivate;
35class Applet;
36class 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
69class PLASMA_EXPORT ToolTipManager : public QObject
70{
71 Q_OBJECT
72public:
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
168Q_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
189private:
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