KTextEditor

message.h
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 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 <dhaumann@kde.org>
91 * @since 4.11
92 */
93class KTEXTEDITOR_EXPORT Message : public QObject
94{
95 Q_OBJECT
96
97 //
98 // public data types
99 //
100public:
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 */
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
140public:
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
310public 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
335Q_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 */
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
361private:
362 class MessagePrivate *const d;
363};
364
365}
366
367#endif
A KParts derived class representing a text document.
Definition document.h:284
This class holds a Message to display in Views.
Definition message.h:94
MessagePosition
Message position used to place the message either above or below of the KTextEditor::View.
Definition message.h:117
@ BelowView
show message below view.
Definition message.h:121
@ TopInView
show message as view overlay in the top right corner.
Definition message.h:123
@ BottomInView
show message as view overlay in the bottom right corner.
Definition message.h:125
void closed(KTextEditor::Message *message)
This signal is emitted before the message is deleted.
void textChanged(const QString &text)
This signal is emitted whenever setText() was called.
MessageType
Message types used as visual indicator.
Definition message.h:106
@ Information
information message type
Definition message.h:108
@ Warning
warning message type
Definition message.h:109
AutoHideMode
The AutoHideMode determines when to trigger the autoHide timer.
Definition message.h:135
void iconChanged(const QIcon &icon)
This signal is emitted whenever setIcon() was called.
A text widget with KXMLGUIClient that represents a Document.
Definition view.h:244
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:53:31 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.