Plasma

tooltip.h
1 /*
2  SPDX-FileCopyrightText: 2011 Marco Martin <[email protected]>
3  SPDX-FileCopyrightText: 2011 Artur Duque de Souza <[email protected]>
4  SPDX-FileCopyrightText: 2013 Sebastian K├╝gler <[email protected]>
5 
6  SPDX-License-Identifier: GPL-2.0-or-later
7 */
8 
9 #ifndef TOOLTIPOBJECT_H
10 #define TOOLTIPOBJECT_H
11 
12 #include <Plasma/Plasma>
13 #include <QPointer>
14 #include <QQuickItem>
15 #include <QVariant>
16 
17 class QQuickItem;
18 class ToolTipDialog;
19 
20 /**
21  * @class ToolTip
22  *
23  * An Item managing a Plasma-themed tooltip. It is rendered in its own window.
24  * You can either specify icon, mainText and subText, or a custom Component
25  * that will be put inside the tooltip. By default the tooltip will be
26  * rendered when hovering over the parent item.
27  *
28  * The item inside the ToolTipArea is loaded on demand and will be destroyed when the
29  * tooltip is being hidden.
30  *
31  * Example usage:
32  * @code
33  * import org.kde.plasma.core 2.0 as PlasmaCore
34  *
35  * PlasmaCore.IconItem {
36  * PlasmaCore.ToolTipArea {
37  * mainText: i18n("Tooltip Title")
38  * subText: i18n("Some explanation.")
39  * icon: "plasma"
40  * // alternatively, you can specify your own component
41  * // to be loaded when the tooltip shows
42  * mainItem: YourCustomItem { }
43  * }
44  * }
45  * @endcode
46  *
47  */
48 class ToolTip : public QQuickItem
49 {
50  Q_OBJECT
51 
52  /**
53  * The item shown inside the tooltip.
54  */
55  Q_PROPERTY(QQuickItem *mainItem READ mainItem WRITE setMainItem NOTIFY mainItemChanged)
56 
57  /**
58  * The main text of this tooltip
59  */
60  Q_PROPERTY(QString mainText READ mainText WRITE setMainText NOTIFY mainTextChanged)
61 
62  /**
63  * The description of this tooltip
64  */
65  Q_PROPERTY(QString subText READ subText WRITE setSubText NOTIFY subTextChanged)
66 
67  /**
68  * how to handle the text format of the tooltip subtext:
69  * * Text.AutoText (default)
70  * * Text.PlainText
71  * * Text.StyledText
72  * * Text.RichText
73  * Note: in the default implementation the main text is always plain text
74  */
75  Q_PROPERTY(int textFormat READ textFormat WRITE setTextFormat NOTIFY textFormatChanged)
76 
77  /**
78  * An icon for this tooltip, accepted values are an icon name, a QIcon, QImage or QPixmap
79  */
80  Q_PROPERTY(QVariant icon READ icon WRITE setIcon NOTIFY iconChanged)
81 
82  /**
83  * Returns whether the mouse is inside the item
84  */
85  Q_PROPERTY(bool containsMouse READ containsMouse NOTIFY containsMouseChanged)
86 
87  /**
88  * Plasma Location of the dialog window. Useful if this dialog is a popup for a panel
89  */
90  Q_PROPERTY(Plasma::Types::Location location READ location WRITE setLocation NOTIFY locationChanged)
91 
92  /**
93  * TODO: single property for images?
94  * An image for this tooltip, accepted values are an icon name, a QIcon, QImage or QPixmap
95  */
96  Q_PROPERTY(QVariant image READ image WRITE setImage NOTIFY imageChanged)
97 
98  /**
99  * Property that controls if a tooltips will show on mouse over.
100  * The default is true.
101  */
102  Q_PROPERTY(bool active MEMBER m_active WRITE setActive NOTIFY activeChanged)
103 
104  /**
105  * If interactive is false (default), the tooltip will automatically hide
106  * itself as soon as the mouse leaves the tooltiparea, if is true, if the
107  * mouse leaves tooltiparea and goes over the tooltip itself, the tooltip
108  * won't hide, so it will be possible to interact with tooltip contents.
109  */
110  Q_PROPERTY(bool interactive MEMBER m_interactive WRITE setInteractive NOTIFY interactiveChanged)
111 
112  /**
113  * Timeout in milliseconds after which the tooltip will hide itself.
114  * Set this value to -1 to never hide the tooltip automatically.
115  */
116  Q_PROPERTY(int timeout MEMBER m_timeout WRITE setTimeout)
117 
118 public:
119  /// @cond INTERNAL_DOCS
120  explicit ToolTip(QQuickItem *parent = nullptr);
121  ~ToolTip() override;
122 
123  QQuickItem *mainItem() const;
124  void setMainItem(QQuickItem *mainItem);
125 
126  QString mainText() const;
127  void setMainText(const QString &mainText);
128 
129  QString subText() const;
130  void setSubText(const QString &subText);
131 
132  int textFormat() const;
133  void setTextFormat(int format);
134 
135  QVariant icon() const;
136  void setIcon(const QVariant &icon);
137 
138  QVariant image() const;
139  void setImage(const QVariant &image);
140 
141  Plasma::Types::Location location() const;
142  void setLocation(Plasma::Types::Location location);
143 
144  bool containsMouse() const;
145  void setContainsMouse(bool contains);
146 
147  void setActive(bool active);
148 
149  void setInteractive(bool interactive);
150 
151  void setTimeout(int timeout);
152  /// @endcond
153 
154 public Q_SLOTS:
155 
156  /**
157  * Shows the tooltip.
158  * @since 5.73
159  */
160  void showToolTip();
161 
162  /**
163  * Hides the tooltip after a grace period if shown. Does not affect whether the tooltip area is active.
164  */
165  void hideToolTip();
166 
167  /**
168  * Hides the tooltip immediately, in comparison to hideToolTip.
169  * @since 5.84
170  */
171  void hideImmediately();
172 
173 protected:
174  /// @cond INTERNAL_DOCS
175  bool childMouseEventFilter(QQuickItem *item, QEvent *event) override;
176  void hoverEnterEvent(QHoverEvent *event) override;
177  void hoverLeaveEvent(QHoverEvent *event) override;
178 
179  ToolTipDialog *tooltipDialogInstance();
180  /// @endcond
181 
182 Q_SIGNALS:
183  void mainItemChanged();
184  void mainTextChanged();
185  void subTextChanged();
186  void textFormatChanged();
187  void iconChanged();
188  void imageChanged();
189  void containsMouseChanged();
190  void locationChanged();
191  void activeChanged();
192  void interactiveChanged();
193  /**
194  * Emitted just before the tooltip dialog is shown.
195  *
196  * @since 5.45
197  */
198  void aboutToShow();
199  /**
200  * Emitted when the tooltip's visibility changes.
201  *
202  * @since 5.88
203  */
204  void toolTipVisibleChanged(bool toolTipVisible);
205 
206 private Q_SLOTS:
207  void settingsChanged(const QString &file);
208 
209 private:
210  bool isValid() const;
211 
212  void loadSettings();
213  bool m_tooltipsEnabledGlobally;
214  bool m_containsMouse;
215  Plasma::Types::Location m_location;
216  QPointer<QQuickItem> m_mainItem;
217  QTimer *m_showTimer;
218  QString m_mainText;
219  QString m_subText;
220  int m_textFormat;
221  QVariant m_image;
222  QVariant m_icon;
223  bool m_active;
224  bool m_interactive;
225  int m_interval;
226  int m_timeout;
227 
228  // ToolTipDialog is not a Q_GLOBAL_STATIC because QQuickwindows as global static
229  // are deleted too later after some stuff in the qml runtime has already been deleted,
230  // causing a crash on exit
231  bool m_usingDialog : 1;
232  static ToolTipDialog *s_dialog;
233  static int s_dialogUsers;
234 };
235 
236 #endif
Q_OBJECTQ_OBJECT
Q_PROPERTY(...)
virtual bool event(QEvent *ev) override
QString mainText
The main text of this tooltip.
Definition: tooltip.h:60
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
bool active
Property that controls if a tooltips will show on mouse over.
Definition: tooltip.h:102
Q_SLOTSQ_SLOTS
virtual bool contains(const QPointF &point) const const
void showToolTip()
Shows the tooltip.
Definition: tooltip.cpp:113
virtual void hoverLeaveEvent(QHoverEvent *event)
bool interactive
If interactive is false (default), the tooltip will automatically hide itself as soon as the mouse le...
Definition: tooltip.h:110
bool containsMouse
Returns whether the mouse is inside the item.
Definition: tooltip.h:85
void hideToolTip()
Hides the tooltip after a grace period if shown.
Definition: tooltip.cpp:258
Plasma::Types::Location location
Plasma Location of the dialog window.
Definition: tooltip.h:90
void toolTipVisibleChanged(bool toolTipVisible)
Emitted when the tooltip's visibility changes.
Q_SIGNALSQ_SIGNALS
int textFormat
how to handle the text format of the tooltip subtext:
Definition: tooltip.h:75
QQuickItem mainItem
The item shown inside the tooltip.
Definition: tooltip.h:55
QVariant icon
An icon for this tooltip, accepted values are an icon name, a QIcon, QImage or QPixmap.
Definition: tooltip.h:80
int timeout
Timeout in milliseconds after which the tooltip will hide itself.
Definition: tooltip.h:116
void hideImmediately()
Hides the tooltip immediately, in comparison to hideToolTip.
Definition: tooltip.cpp:264
virtual void hoverEnterEvent(QHoverEvent *event)
void aboutToShow()
Emitted just before the tooltip dialog is shown.
QVariant image
TODO: single property for images? An image for this tooltip, accepted values are an icon name,...
Definition: tooltip.h:96
QString subText
The description of this tooltip.
Definition: tooltip.h:65
virtual bool childMouseEventFilter(QQuickItem *item, QEvent *event)
Internally used by Tooltip.
Definition: tooltipdialog.h:26
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 04:05:57 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.