KTextEditor

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

KDE's Doxygen guidelines are available online.