1/*
2 * Copyright 2008 by Aaron Seigo <aseigo@kde.org>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin St, Fifth Floor,
17 * Boston, MA 02110-1301 USA
18 */
19
20#ifndef PLASMA_TOOLTIPCONTENT_H
21#define PLASMA_TOOLTIPCONTENT_H
22
23#include <QtCore/QString>
24#include <QtCore/QUrl>
25#include <QtCore/QVariant>
26#include <QtCore/QList>
27#include <QtGui/QPixmap>
28#include <QtGui/QIcon>
29
30#include <plasma/plasma_export.h>
31
32class QTextDocument;
33class QGraphicsWidget;
34
35/**
36 * This provides the content for a tooltip.
37 *
38 * Normally you will want to set at least the @p mainText and
39 * @p subText.
40 */
41
42namespace Plasma
43{
44
45class ToolTipContentPrivate;
46
47class PLASMA_EXPORT ToolTipContent
48{
49public:
50 enum ResourceType { ImageResource = 0, HtmlResource, CssResource };
51
52 /**
53 * Creates an empty Content
54 */
55 ToolTipContent();
56
57 ~ToolTipContent();
58
59 /**
60 * Copy constructor
61 */
62 ToolTipContent(const ToolTipContent &other);
63
64 /**
65 * Constructor that sets the common fields
66 */
67 ToolTipContent(const QString &mainText,
68 const QString &subText,
69 const QPixmap &image = QPixmap());
70
71 /**
72 * Constructor that sets the common fields
73 */
74 ToolTipContent(const QString &mainText,
75 const QString &subText,
76 const QIcon &icon);
77
78 ToolTipContent &operator=(const ToolTipContent &other);
79
80 /**
81 * @return true if all the fields are empty
82 */
83 bool isEmpty() const;
84
85 /**
86 * Sets the main text which containts important information, e.g. the title
87 */
88 void setMainText(const QString &text);
89
90 /**
91 * Important information, e.g. the title
92 */
93 QString mainText() const;
94
95 /**
96 * Sets text which elaborates on the @p mainText
97 */
98 void setSubText(const QString &text) ;
99
100 /**
101 * Elaborates on the @p mainText
102 */
103 QString subText() const;
104
105 /**
106 * Sets the icon to show
107 */
108 void setImage(const QPixmap &image);
109
110 /**
111 * Sets the icon to show
112 */
113 void setImage(const QIcon &icon);
114
115 /**
116 * An icon to display
117 */
118 QPixmap image() const;
119
120 /**
121 * Sets the ID of the window to show a preview for.
122 * @deprecated
123 * @see setWindowsToPreview
124 */
125 KDE_DEPRECATED void setWindowToPreview(WId id);
126
127 /**
128 * Id of a window if you want to show a preview
129 * @deprecated
130 * @see windowsToPreview
131 */
132 KDE_DEPRECATED WId windowToPreview() const;
133
134 /**
135 * Sets the IDS of the windows to show a preview for
136 * @since 4.3
137 */
138 void setWindowsToPreview(const QList<WId> &ids);
139
140 /**
141 * Ids of a windows if you want to show a preview
142 * @since 4.3
143 */
144 QList<WId> windowsToPreview() const;
145
146 /**
147 * sets if when the mouse will be over a thumbnail the corresponding window
148 * will be highlighted by reducing opacity of all the other windows
149 * @since 4.4
150 */
151 void setHighlightWindows(bool highlight);
152
153 /**
154 * true if when the mouse will be over a thumbnail the corresponding window
155 * will be highlighted by reducing opacity of all the other windows
156 * @since 4.4
157 */
158 bool highlightWindows() const;
159
160 /** Sets whether or not to autohide the tooltip, defaults to true
161 */
162 void setAutohide(bool autohide);
163
164 /**
165 * Whether or not to autohide the tooltip, defaults to true
166 */
167 bool autohide() const;
168
169 /**
170 * Sets whether or not the tooltip should popup instantly when
171 * the widget is hovered, defaults to false.
172 *
173 * @since 4.7
174 */
175 void setInstantPopup(bool enabled);
176
177 /**
178 * Whether or not the tooltip should popup instantly when
179 * the widget is hovered, defaults to false.
180 *
181 * @since 4.7
182 */
183 bool isInstantPopup() const;
184
185 /**
186 * Adds a resource that can then be referenced from the text elements
187 * using rich text
188 */
189 void addResource(ResourceType type, const QUrl &path, const QVariant &resource);
190
191 /**
192 * Registers all resources with a given document
193 */
194 void registerResources(QTextDocument *document) const;
195
196 /**
197 * Sets whether or not the tooltip contains clickable content, such as
198 * window previews. Defaults to false, or not clickable.
199 *
200 * @since 4.3
201 */
202 void setClickable(bool clickable);
203
204 /**
205 * @return true if the tooltip is clickabel
206 *
207 * @since 4.3
208 */
209 bool isClickable() const;
210
211 /**
212 * Sets an optional graphicsWidget that will be used for positioning the tooltip
213 * @since 4.6
214 */
215 void setGraphicsWidget(QGraphicsWidget *widget);
216
217 /**
218 * the graphicsWidget used for positioning the tooltip, if any
219 * @since 4.6
220 */
221 QGraphicsWidget *graphicsWidget() const;
222
223private:
224 ToolTipContentPrivate * const d;
225};
226
227} // namespace Plasma
228
229#endif
230
231