1/*
2 SPDX-FileCopyrightText: 2012-2013 Dominik Haumann <dhaumann@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KTEXTEDITOR_MESSAGE_H
8#define KTEXTEDITOR_MESSAGE_H
9
10#include <QObject>
11
12#include <ktexteditor_export.h>
13
14class QIcon;
15class QAction;
16
17namespace KTextEditor
18{
19class View;
20class Document;
21
22/*!
23 * \class KTextEditor::Message
24 * \inmodule KTextEditor
25 * \inheaderfile KTextEditor/Message
26 *
27 * \brief This class holds a Message to display in Views.
28 *
29 * \target message_intro
30 * \section1 Introduction
31 *
32 * The Message class holds the data used to display interactive message widgets
33 * in the editor. Use the Document::postMessage() to post a message as follows:
34 *
35 * \code
36 * // always use a QPointer to guard your Message, if you keep a pointer
37 * // after calling postMessage()
38 * QPointer<KTextEditor::Message> message =
39 * new KTextEditor::Message("text", KTextEditor::Message::Information);
40 * message->setWordWrap(true);
41 * message->addAction(...); // add your actions...
42 * document->postMessage(message);
43 * \endcode
44 *
45 * A Message is deleted automatically if the Message gets closed, meaning that
46 * you usually can forget the pointer. If you really need to delete a message
47 * before the user processed it, always guard it with a QPointer!
48 *
49 * \target message_creation
50 * \section1 Message Creation and Deletion
51 *
52 * To create a new Message, use code like this:
53 * \code
54 * QPointer<KTextEditor::Message> message =
55 * new KTextEditor::Message("My information text", KTextEditor::Message::Information);
56 * message->setWordWrap(true);
57 * // ...
58 * \endcode
59 *
60 * Although discouraged in general, the text of the Message can be changed
61 * on the fly when it is already visible with setText().
62 *
63 * Once you posted the Message through Document::postMessage(), the
64 * lifetime depends on the user interaction. The Message gets automatically
65 * deleted either if the user clicks a closing action in the message, or for
66 * instance if the document is reloaded.
67 *
68 * If you posted a message but want to remove it yourself again, just delete
69 * the message. But beware of the following warning!
70 *
71 * \warning Always use QPointer\<Message\> to guard the message pointer from
72 * getting invalid, if you need to access the Message after you posted
73 * it.
74 *
75 * \target message_positioning
76 * \section1 Positioning
77 *
78 * By default, the Message appears right above of the View. However, if desired,
79 * the position can be changed through setPosition(). For instance, the
80 * search-and-replace code in Kate Part shows the number of performed replacements
81 * in a message floating in the view. For further information, have a look at
82 * the enum MessagePosition.
83 *
84 * \target message_hiding
85 * \section1 Autohiding Messages
86 *
87 * Message%s can be shown for only a short amount of time by using the autohide
88 * feature. With setAutoHide() a timeout in milliseconds can be set after which
89 * the Message is automatically hidden. Further, use setAutoHideMode() to either
90 * trigger the autohide timer as soon as the widget is shown (AutoHideMode::Immediate),
91 * or only after user interaction with the view (AutoHideMode::AfterUserInteraction).
92 *
93 * The default autohide mode is set to AutoHideMode::AfterUserInteraction.
94 * This way, it is unlikely the user misses a notification.
95 *
96 * \since 4.11
97 */
98class KTEXTEDITOR_EXPORT Message : public QObject
99{
100 Q_OBJECT
101
102 //
103 // public data types
104 //
105public:
106 /*!
107 \enum KTextEditor::Message::MessageType
108
109 Message types used as visual indicator.
110
111 The message types match exactly the behavior of KMessageWidget::MessageType.
112 For simple notifications either use Positive or Information.
113
114 \value Positive
115 Positive information message
116 \value Information
117 Information message type
118 \value Warning
119 Warning message type
120 \value Error
121 Error message type
122 */
123 enum MessageType {
124 Positive = 0,
125 Information,
126 Warning,
127 Error
128 };
129
130 /*!
131 \enum KTextEditor::Message::MessagePosition
132
133 Message position used to place the message either above or below of the
134 KTextEditor::View.
135
136 \value AboveView
137 Show message above view.
138 \value BelowView
139 Show message below view.
140 \value TopInView
141 Show message as view overlay in the top right corner.
142 \value BottomInView
143 Show message as view overlay in the bottom right corner.
144 \value CenterInView
145 Show message as view overlay in the center of the view. \since 5.42
146 */
147 enum MessagePosition {
148 AboveView = 0,
149 BelowView,
150 TopInView,
151 BottomInView,
152 CenterInView
153 };
154
155 /*!
156 \enum KTextEditor::Message::AutoHideMode
157
158 \brief The AutoHideMode determines when to trigger the autoHide timer.
159
160 \sa setAutoHide(), autoHide()
161
162 \value Immediate
163 Auto-hide is triggered as soon as the message is shown
164 \value AfterUserInteraction
165 Auto-hide is triggered only after the user interacted with the view
166 */
167 enum AutoHideMode {
168 Immediate = 0,
169 AfterUserInteraction
170 };
171
172public:
173 /*!
174 * Constructor for new messages.
175 *
176 * \a type is the message type, e.g. MessageType::Information
177 *
178 * \a richtext is the text to be displayed
179 *
180 */
181 Message(const QString &richtext, MessageType type = Message::Information);
182
183 /*!
184 * Destructor.
185 */
186 ~Message() override;
187
188 /*!
189 * Returns the text set in the constructor.
190 */
191 QString text() const;
192
193 /*!
194 * Returns the icon of this message.
195 * If the message has no icon set, a null icon is returned.
196 * \sa setIcon()
197 */
198 QIcon icon() const;
199
200 /*!
201 * Returns the message type set in the constructor.
202 */
203 MessageType messageType() const;
204
205 /*!
206 * Adds an action to the message.
207 *
208 * By default (\a closeOnTrigger = true), the action closes the message
209 * displayed in all Views. If \a closeOnTrigger is false, the message
210 * is stays open.
211 *
212 * The actions will be displayed in the order you added the actions.
213 *
214 * To connect to an action, use the following code:
215 * \code
216 * connect(action, &QAction::triggered, receiver, &ReceiverType::slotActionTriggered);
217 * \endcode
218 *
219 * \a action is the action to be added
220 *
221 * \a closeOnTrigger when triggered, the message widget is closed
222 *
223 * \warning The added actions are deleted automatically.
224 * So do \b not delete the added actions yourself.
225 */
226 void addAction(QAction *action, bool closeOnTrigger = true);
227
228 /*!
229 * Accessor to all actions, mainly used in the internal implementation
230 * to add the actions into the gui.
231 * \sa addAction()
232 */
233 QList<QAction *> actions() const;
234
235 /*!
236 * Set the auto hide time to \a delay milliseconds.
237 * If \a delay < 0, auto hide is disabled.
238 * If \a delay = 0, auto hide is enabled and set to a sane default
239 * value of several seconds.
240 *
241 * By default, auto hide is disabled.
242 *
243 * \sa autoHide(), setAutoHideMode()
244 */
245 void setAutoHide(int delay = 0);
246
247 /*!
248 * Returns the auto hide time in milliseconds.
249 * Please refer to setAutoHide() for an explanation of the return value.
250 *
251 * \sa setAutoHide(), autoHideMode()
252 */
253 int autoHide() const;
254
255 /*!
256 * Sets the auto hide mode to \a mode.
257 * The default mode is set to AutoHideMode::AfterUserInteraction.
258 *
259 * \a mode is the auto hide mode
260 *
261 * \sa autoHideMode(), setAutoHide()
262 */
263 void setAutoHideMode(KTextEditor::Message::AutoHideMode mode);
264
265 /*!
266 * Get the Message's auto hide mode.
267 * The default mode is set to AutoHideMode::AfterUserInteraction.
268 * \sa setAutoHideMode(), autoHide()
269 */
270 KTextEditor::Message::AutoHideMode autoHideMode() const;
271
272 /*!
273 * Enabled word wrap according to \a wordWrap.
274 * By default, auto wrap is disabled.
275 *
276 * Word wrap is enabled automatically, if the Message's width is larger than
277 * the parent widget's width to avoid breaking the gui layout.
278 *
279 * \sa wordWrap()
280 */
281 void setWordWrap(bool wordWrap);
282
283 /*!
284 * Returns true if word wrap is enabled.
285 *
286 * \sa setWordWrap()
287 */
288 bool wordWrap() const;
289
290 /*!
291 * Set the priority of this message to \a priority.
292 * Messages with higher priority are shown first.
293 * The default priority is 0.
294 *
295 * \sa priority()
296 */
297 void setPriority(int priority);
298
299 /*!
300 * Returns the priority of the message.
301 *
302 * \sa setPriority()
303 */
304 int priority() const;
305
306 /*!
307 * Set the associated view of the message.
308 * If \a view is 0, the message is shown in all View%s of the Document.
309 * If \a view is given, i.e. non-zero, the message is shown only in this view.
310 * \a view the associated view the message should be displayed in
311 */
312 void setView(KTextEditor::View *view);
313
314 /*!
315 * This function returns the view you set by setView(). If setView() was
316 * not called, the return value is 0.
317 */
318 KTextEditor::View *view() const;
319
320 /*!
321 * Set the document pointer to \a document.
322 * This is called by the implementation, as soon as you post a message
323 * through Document::postMessage(), so that you do not have to
324 * call this yourself.
325 * \sa document()
326 */
327 void setDocument(KTextEditor::Document *document);
328
329 /*!
330 * Returns the document pointer this message was posted in.
331 * This pointer is 0 as long as the message was not posted.
332 */
333 KTextEditor::Document *document() const;
334
335 /*!
336 * Sets the position of the message to \a position.
337 * By default, the position is set to MessagePosition::AboveView.
338 * \sa MessagePosition
339 */
340 void setPosition(MessagePosition position);
341
342 /*!
343 * Returns the message position of this message.
344 * \sa setPosition(), MessagePosition
345 */
346 MessagePosition position() const;
347
348public Q_SLOTS:
349 /*!
350 * Sets the notification contents to \a richtext.
351 * If the message was already sent through Document::postMessage(),
352 * the displayed text changes on the fly.
353 * \note Change text on the fly with care, since changing the text may
354 * resize the notification widget, which may result in a distracting
355 * user experience.
356 *
357 * \a richtext is the new notification text (rich text supported)
358 *
359 * \sa textChanged()
360 */
361 void setText(const QString &richtext);
362
363 /*!
364 * Add an optional \a icon for this notification which will be shown next to
365 * the message text. If the message was already sent through Document::postMessage(),
366 * the displayed icon changes on the fly.
367 *
368 * \note Change the icon on the fly with care, since changing the text may
369 * resize the notification widget, which may result in a distracting
370 * user experience.
371 *
372 * \a icon is the icon to be displayed
373 *
374 * \sa iconChanged()
375 */
376 void setIcon(const QIcon &icon);
377
378Q_SIGNALS:
379 /*!
380 * This signal is emitted before the \a message is deleted. Afterwards, this
381 * pointer is invalid.
382 *
383 * Use the function document() to access the associated Document.
384 *
385 * \a message the closed/processed message
386 */
387 void closed(KTextEditor::Message *message);
388
389 /*!
390 * This signal is emitted whenever setText() was called.
391 *
392 * \a text the new notification text (rich text supported)
393 *
394 * \sa setText()
395 */
396 void textChanged(const QString &text);
397
398 /*!
399 * This signal is emitted whenever setIcon() was called.
400 *
401 * \a icon is the new notification icon
402 *
403 * \sa setIcon()
404 */
405 void iconChanged(const QIcon &icon);
406
407private:
408 class MessagePrivate *const d;
409};
410
411}
412
413#endif
414

source code of ktexteditor/src/include/ktexteditor/message.h