Warning, file /frameworks/ktexteditor/src/include/ktexteditor/message.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 /* 0002 SPDX-FileCopyrightText: 2012-2013 Dominik Haumann <dhaumann@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KTEXTEDITOR_MESSAGE_H 0008 #define KTEXTEDITOR_MESSAGE_H 0009 0010 #include <QAction> 0011 #include <QIcon> 0012 #include <QList> 0013 #include <QObject> 0014 0015 #include <ktexteditor_export.h> 0016 0017 namespace KTextEditor 0018 { 0019 class View; 0020 class Document; 0021 0022 /** 0023 * @class Message message.h <KTextEditor/Message> 0024 * 0025 * @brief This class holds a Message to display in View%s. 0026 * 0027 * @section message_intro Introduction 0028 * 0029 * The Message class holds the data used to display interactive message widgets 0030 * in the editor. Use the Document::postMessage() to post a message as follows: 0031 * 0032 * @code 0033 * // always use a QPointer to guard your Message, if you keep a pointer 0034 * // after calling postMessage() 0035 * QPointer<KTextEditor::Message> message = 0036 * new KTextEditor::Message("text", KTextEditor::Message::Information); 0037 * message->setWordWrap(true); 0038 * message->addAction(...); // add your actions... 0039 * document->postMessage(message); 0040 * @endcode 0041 * 0042 * A Message is deleted automatically if the Message gets closed, meaning that 0043 * you usually can forget the pointer. If you really need to delete a message 0044 * before the user processed it, always guard it with a QPointer! 0045 * 0046 * @section message_creation Message Creation and Deletion 0047 * 0048 * To create a new Message, use code like this: 0049 * @code 0050 * QPointer<KTextEditor::Message> message = 0051 * new KTextEditor::Message("My information text", KTextEditor::Message::Information); 0052 * message->setWordWrap(true); 0053 * // ... 0054 * @endcode 0055 * 0056 * Although discouraged in general, the text of the Message can be changed 0057 * on the fly when it is already visible with setText(). 0058 * 0059 * Once you posted the Message through Document::postMessage(), the 0060 * lifetime depends on the user interaction. The Message gets automatically 0061 * deleted either if the user clicks a closing action in the message, or for 0062 * instance if the document is reloaded. 0063 * 0064 * If you posted a message but want to remove it yourself again, just delete 0065 * the message. But beware of the following warning! 0066 * 0067 * @warning Always use QPointer\<Message\> to guard the message pointer from 0068 * getting invalid, if you need to access the Message after you posted 0069 * it. 0070 * 0071 * @section message_positioning Positioning 0072 * 0073 * By default, the Message appears right above of the View. However, if desired, 0074 * the position can be changed through setPosition(). For instance, the 0075 * search-and-replace code in Kate Part shows the number of performed replacements 0076 * in a message floating in the view. For further information, have a look at 0077 * the enum MessagePosition. 0078 * 0079 * @section message_hiding Autohiding Messages 0080 * 0081 * Message%s can be shown for only a short amount of time by using the autohide 0082 * feature. With setAutoHide() a timeout in milliseconds can be set after which 0083 * the Message is automatically hidden. Further, use setAutoHideMode() to either 0084 * trigger the autohide timer as soon as the widget is shown (AutoHideMode::Immediate), 0085 * or only after user interaction with the view (AutoHideMode::AfterUserInteraction). 0086 * 0087 * The default autohide mode is set to AutoHideMode::AfterUserInteraction. 0088 * This way, it is unlikely the user misses a notification. 0089 * 0090 * @author Dominik Haumann \<dhaumann@kde.org\> 0091 * @since 4.11 0092 */ 0093 class KTEXTEDITOR_EXPORT Message : public QObject 0094 { 0095 Q_OBJECT 0096 0097 // 0098 // public data types 0099 // 0100 public: 0101 /** 0102 * Message types used as visual indicator. 0103 * The message types match exactly the behavior of KMessageWidget::MessageType. 0104 * For simple notifications either use Positive or Information. 0105 */ 0106 enum MessageType { 0107 Positive = 0, ///< positive information message 0108 Information, ///< information message type 0109 Warning, ///< warning message type 0110 Error ///< error message type 0111 }; 0112 0113 /** 0114 * Message position used to place the message either above or below of the 0115 * KTextEditor::View. 0116 */ 0117 enum MessagePosition { 0118 /// show message above view. 0119 AboveView = 0, 0120 /// show message below view. 0121 BelowView, 0122 /// show message as view overlay in the top right corner. 0123 TopInView, 0124 /// show message as view overlay in the bottom right corner. 0125 BottomInView, 0126 /// show message as view overlay in the center of the view. 0127 /// @since 5.42 0128 CenterInView 0129 }; 0130 0131 /** 0132 * The AutoHideMode determines when to trigger the autoHide timer. 0133 * @see setAutoHide(), autoHide() 0134 */ 0135 enum AutoHideMode { 0136 Immediate = 0, ///< auto-hide is triggered as soon as the message is shown 0137 AfterUserInteraction ///< auto-hide is triggered only after the user interacted with the view 0138 }; 0139 0140 public: 0141 /** 0142 * Constructor for new messages. 0143 * @param type the message type, e.g. MessageType::Information 0144 * @param richtext text to be displayed 0145 */ 0146 Message(const QString &richtext, MessageType type = Message::Information); 0147 0148 /** 0149 * Destructor. 0150 */ 0151 ~Message() override; 0152 0153 /** 0154 * Returns the text set in the constructor. 0155 */ 0156 QString text() const; 0157 0158 /** 0159 * Returns the icon of this message. 0160 * If the message has no icon set, a null icon is returned. 0161 * @see setIcon() 0162 */ 0163 QIcon icon() const; 0164 0165 /** 0166 * Returns the message type set in the constructor. 0167 */ 0168 MessageType messageType() const; 0169 0170 /** 0171 * Adds an action to the message. 0172 * 0173 * By default (@p closeOnTrigger = true), the action closes the message 0174 * displayed in all View%s. If @p closeOnTrigger is @e false, the message 0175 * is stays open. 0176 * 0177 * The actions will be displayed in the order you added the actions. 0178 * 0179 * To connect to an action, use the following code: 0180 * @code 0181 * connect(action, &QAction::triggered, receiver, &ReceiverType::slotActionTriggered); 0182 * @endcode 0183 * 0184 * @param action action to be added 0185 * @param closeOnTrigger when triggered, the message widget is closed 0186 * 0187 * @warning The added actions are deleted automatically. 0188 * So do @em not delete the added actions yourself. 0189 */ 0190 void addAction(QAction *action, bool closeOnTrigger = true); 0191 0192 /** 0193 * Accessor to all actions, mainly used in the internal implementation 0194 * to add the actions into the gui. 0195 * @see addAction() 0196 */ 0197 QList<QAction *> actions() const; 0198 0199 /** 0200 * Set the auto hide time to @p delay milliseconds. 0201 * If @p delay < 0, auto hide is disabled. 0202 * If @p delay = 0, auto hide is enabled and set to a sane default 0203 * value of several seconds. 0204 * 0205 * By default, auto hide is disabled. 0206 * 0207 * @see autoHide(), setAutoHideMode() 0208 */ 0209 void setAutoHide(int delay = 0); 0210 0211 /** 0212 * Returns the auto hide time in milliseconds. 0213 * Please refer to setAutoHide() for an explanation of the return value. 0214 * 0215 * @see setAutoHide(), autoHideMode() 0216 */ 0217 int autoHide() const; 0218 0219 /** 0220 * Sets the auto hide mode to @p mode. 0221 * The default mode is set to AutoHideMode::AfterUserInteraction. 0222 * @param mode auto hide mode 0223 * @see autoHideMode(), setAutoHide() 0224 */ 0225 void setAutoHideMode(KTextEditor::Message::AutoHideMode mode); 0226 0227 /** 0228 * Get the Message's auto hide mode. 0229 * The default mode is set to AutoHideMode::AfterUserInteraction. 0230 * @see setAutoHideMode(), autoHide() 0231 */ 0232 KTextEditor::Message::AutoHideMode autoHideMode() const; 0233 0234 /** 0235 * Enabled word wrap according to @p wordWrap. 0236 * By default, auto wrap is disabled. 0237 * 0238 * Word wrap is enabled automatically, if the Message's width is larger than 0239 * the parent widget's width to avoid breaking the gui layout. 0240 * 0241 * @see wordWrap() 0242 */ 0243 void setWordWrap(bool wordWrap); 0244 0245 /** 0246 * Check, whether word wrap is enabled or not. 0247 * 0248 * @see setWordWrap() 0249 */ 0250 bool wordWrap() const; 0251 0252 /** 0253 * Set the priority of this message to @p priority. 0254 * Messages with higher priority are shown first. 0255 * The default priority is 0. 0256 * 0257 * @see priority() 0258 */ 0259 void setPriority(int priority); 0260 0261 /** 0262 * Returns the priority of the message. 0263 * 0264 * @see setPriority() 0265 */ 0266 int priority() const; 0267 0268 /** 0269 * Set the associated view of the message. 0270 * If @p view is 0, the message is shown in all View%s of the Document. 0271 * If @p view is given, i.e. non-zero, the message is shown only in this view. 0272 * @param view the associated view the message should be displayed in 0273 */ 0274 void setView(KTextEditor::View *view); 0275 0276 /** 0277 * This function returns the view you set by setView(). If setView() was 0278 * not called, the return value is 0. 0279 */ 0280 KTextEditor::View *view() const; 0281 0282 /** 0283 * Set the document pointer to @p document. 0284 * This is called by the implementation, as soon as you post a message 0285 * through Document::postMessage(), so that you do not have to 0286 * call this yourself. 0287 * @see document() 0288 */ 0289 void setDocument(KTextEditor::Document *document); 0290 0291 /** 0292 * Returns the document pointer this message was posted in. 0293 * This pointer is 0 as long as the message was not posted. 0294 */ 0295 KTextEditor::Document *document() const; 0296 0297 /** 0298 * Sets the position of the message to @p position. 0299 * By default, the position is set to MessagePosition::AboveView. 0300 * @see MessagePosition 0301 */ 0302 void setPosition(MessagePosition position); 0303 0304 /** 0305 * Returns the message position of this message. 0306 * @see setPosition(), MessagePosition 0307 */ 0308 MessagePosition position() const; 0309 0310 public Q_SLOTS: 0311 /** 0312 * Sets the notification contents to @p richtext. 0313 * If the message was already sent through Document::postMessage(), 0314 * the displayed text changes on the fly. 0315 * @note Change text on the fly with care, since changing the text may 0316 * resize the notification widget, which may result in a distracting 0317 * user experience. 0318 * @param richtext new notification text (rich text supported) 0319 * @see textChanged() 0320 */ 0321 void setText(const QString &richtext); 0322 0323 /** 0324 * Add an optional @p icon for this notification which will be shown next to 0325 * the message text. If the message was already sent through Document::postMessage(), 0326 * the displayed icon changes on the fly. 0327 * @note Change the icon on the fly with care, since changing the text may 0328 * resize the notification widget, which may result in a distracting 0329 * user experience. 0330 * @param icon the icon to be displayed 0331 * @see iconChanged() 0332 */ 0333 void setIcon(const QIcon &icon); 0334 0335 Q_SIGNALS: 0336 /** 0337 * This signal is emitted before the @p message is deleted. Afterwards, this 0338 * pointer is invalid. 0339 * 0340 * Use the function document() to access the associated Document. 0341 * 0342 * @param message the closed/processed message 0343 */ 0344 void closed(KTextEditor::Message *message); 0345 0346 /** 0347 * This signal is emitted whenever setText() was called. 0348 * 0349 * @param text the new notification text (rich text supported) 0350 * @see setText() 0351 */ 0352 void textChanged(const QString &text); 0353 0354 /** 0355 * This signal is emitted whenever setIcon() was called. 0356 * @param icon the new notification icon 0357 * @see setIcon() 0358 */ 0359 void iconChanged(const QIcon &icon); 0360 0361 private: 0362 class MessagePrivate *const d; 0363 }; 0364 0365 } 0366 0367 #endif