KTextEditor::Message Class
class KTextEditor::MessageThis class holds a Message to display in Views. More...
| Header: | #include <KTextEditor/Message> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS TextEditor)target_link_libraries(mytarget PRIVATE KF6::TextEditor) |
| Since: | 4.11 |
| Inherits: | QObject |
Public Types
| enum | AutoHideMode { Immediate, AfterUserInteraction } |
(since 5.42) enum | MessagePosition { AboveView, BelowView, TopInView, BottomInView, CenterInView } |
| enum | MessageType { Positive, Information, Warning, Error } |
Public Functions
| Message(const QString &richtext, KTextEditor::Message::MessageType type = Message::Information) | |
| virtual | ~Message() override |
| QList<QAction *> | actions() const |
| void | addAction(QAction *action, bool closeOnTrigger = true) |
| int | autoHide() const |
| KTextEditor::Message::AutoHideMode | autoHideMode() const |
| KTextEditor::Document * | document() const |
| QIcon | icon() const |
| KTextEditor::Message::MessageType | messageType() const |
| KTextEditor::Message::MessagePosition | position() const |
| int | priority() const |
| void | setAutoHide(int delay = 0) |
| void | setAutoHideMode(KTextEditor::Message::AutoHideMode mode) |
| void | setDocument(KTextEditor::Document *document) |
| void | setPosition(KTextEditor::Message::MessagePosition position) |
| void | setPriority(int priority) |
| void | setView(KTextEditor::View *view) |
| void | setWordWrap(bool wordWrap) |
| QString | text() const |
| KTextEditor::View * | view() const |
| bool | wordWrap() const |
Public Slots
Signals
| void | closed(KTextEditor::Message *message) |
| void | iconChanged(const QIcon &icon) |
| void | textChanged(const QString &text) |
Detailed Description
Introduction
The Message class holds the data used to display interactive message widgets in the editor. Use the Document::postMessage() to post a message as follows:
// always use a QPointer to guard your Message, if you keep a pointer // after calling postMessage() QPointer<KTextEditor::Message> message = new KTextEditor::Message("text", KTextEditor::Message::Information); message->setWordWrap(true); message->addAction(...); // add your actions... document->postMessage(message);
A Message is deleted automatically if the Message gets closed, meaning that you usually can forget the pointer. If you really need to delete a message before the user processed it, always guard it with a QPointer!
Message Creation and Deletion
To create a new Message, use code like this:
QPointer<KTextEditor::Message> message = new KTextEditor::Message("My information text", KTextEditor::Message::Information); message->setWordWrap(true); // ...
Although discouraged in general, the text of the Message can be changed on the fly when it is already visible with setText().
Once you posted the Message through Document::postMessage(), the lifetime depends on the user interaction. The Message gets automatically deleted either if the user clicks a closing action in the message, or for instance if the document is reloaded.
If you posted a message but want to remove it yourself again, just delete the message. But beware of the following warning!
Warning: Always use QPointer<Message> to guard the message pointer from getting invalid, if you need to access the Message after you posted it.
Positioning
By default, the Message appears right above of the View. However, if desired, the position can be changed through setPosition(). For instance, the search-and-replace code in Kate Part shows the number of performed replacements in a message floating in the view. For further information, have a look at the enum MessagePosition.
Autohiding Messages
Message%s can be shown for only a short amount of time by using the autohide feature. With setAutoHide() a timeout in milliseconds can be set after which the Message is automatically hidden. Further, use setAutoHideMode() to either trigger the autohide timer as soon as the widget is shown (AutoHideMode::Immediate), or only after user interaction with the view (AutoHideMode::AfterUserInteraction).
The default autohide mode is set to AutoHideMode::AfterUserInteraction. This way, it is unlikely the user misses a notification.
Member Type Documentation
enum Message::AutoHideMode
The AutoHideMode determines when to trigger the autoHide timer.
| Constant | Value | Description |
|---|---|---|
KTextEditor::Message::Immediate | 0 | Auto-hide is triggered as soon as the message is shown |
KTextEditor::Message::AfterUserInteraction | 1 | Auto-hide is triggered only after the user interacted with the view |
See also setAutoHide() and autoHide().
[since 5.42] enum Message::MessagePosition
Message position used to place the message either above or below of the KTextEditor::View.
| Constant | Value | Description |
|---|---|---|
KTextEditor::Message::AboveView | 0 | Show message above view. |
KTextEditor::Message::BelowView | 1 | Show message below view. |
KTextEditor::Message::TopInView | 2 | Show message as view overlay in the top right corner. |
KTextEditor::Message::BottomInView | 3 | Show message as view overlay in the bottom right corner. |
KTextEditor::Message::CenterInView | 4 | Show message as view overlay in the center of the view. |
This enum was introduced in 5.42.
enum Message::MessageType
Message types used as visual indicator.
The message types match exactly the behavior of KMessageWidget::MessageType. For simple notifications either use Positive or Information.
| Constant | Value | Description |
|---|---|---|
KTextEditor::Message::Positive | 0 | Positive information message |
KTextEditor::Message::Information | 1 | Information message type |
KTextEditor::Message::Warning | 2 | Warning message type |
KTextEditor::Message::Error | 3 | Error message type |
Member Function Documentation
Message::Message(const QString &richtext, KTextEditor::Message::MessageType type = Message::Information)
Constructor for new messages.
type is the message type, e.g. MessageType::Information
richtext is the text to be displayed
[override virtual noexcept] Message::~Message()
Destructor.
QList<QAction *> Message::actions() const
Accessor to all actions, mainly used in the internal implementation to add the actions into the gui.
See also addAction().
void Message::addAction(QAction *action, bool closeOnTrigger = true)
Adds an action to the message.
By default (closeOnTrigger = true), the action closes the message displayed in all Views. If closeOnTrigger is false, the message is stays open.
The actions will be displayed in the order you added the actions.
To connect to an action, use the following code:
connect(action, &QAction::triggered, receiver, &ReceiverType::slotActionTriggered);
action is the action to be added
closeOnTrigger when triggered, the message widget is closed
Warning: The added actions are deleted automatically. So do not delete the added actions yourself.
int Message::autoHide() const
Returns the auto hide time in milliseconds. Please refer to setAutoHide() for an explanation of the return value.
See also setAutoHide() and autoHideMode().
KTextEditor::Message::AutoHideMode Message::autoHideMode() const
Get the Message's auto hide mode. The default mode is set to AutoHideMode::AfterUserInteraction.
See also setAutoHideMode() and autoHide().
[signal] void Message::closed(KTextEditor::Message *message)
This signal is emitted before the message is deleted. Afterwards, this pointer is invalid.
Use the function document() to access the associated Document.
message the closed/processed message
KTextEditor::Document *Message::document() const
Returns the document pointer this message was posted in. This pointer is 0 as long as the message was not posted.
See also setDocument().
QIcon Message::icon() const
Returns the icon of this message. If the message has no icon set, a null icon is returned.
See also setIcon().
[signal] void Message::iconChanged(const QIcon &icon)
This signal is emitted whenever setIcon() was called.
icon is the new notification icon
See also setIcon().
KTextEditor::Message::MessageType Message::messageType() const
Returns the message type set in the constructor.
KTextEditor::Message::MessagePosition Message::position() const
Returns the message position of this message.
See also setPosition() and MessagePosition.
int Message::priority() const
Returns the priority of the message.
See also setPriority().
void Message::setAutoHide(int delay = 0)
Set the auto hide time to delay milliseconds. If delay < 0, auto hide is disabled. If delay = 0, auto hide is enabled and set to a sane default value of several seconds.
By default, auto hide is disabled.
See also autoHide() and setAutoHideMode().
void Message::setAutoHideMode(KTextEditor::Message::AutoHideMode mode)
Sets the auto hide mode to mode. The default mode is set to AutoHideMode::AfterUserInteraction.
mode is the auto hide mode
See also autoHideMode() and setAutoHide().
void Message::setDocument(KTextEditor::Document *document)
Set the document pointer to document. This is called by the implementation, as soon as you post a message through Document::postMessage(), so that you do not have to call this yourself.
See also document().
[slot] void Message::setIcon(const QIcon &icon)
Add an optional icon for this notification which will be shown next to the message text. If the message was already sent through Document::postMessage(), the displayed icon changes on the fly.
Note: Change the icon on the fly with care, since changing the text may resize the notification widget, which may result in a distracting user experience.
icon is the icon to be displayed
See also iconChanged().
void Message::setPosition(KTextEditor::Message::MessagePosition position)
Sets the position of the message to position. By default, the position is set to MessagePosition::AboveView.
See also position() and MessagePosition.
void Message::setPriority(int priority)
Set the priority of this message to priority. Messages with higher priority are shown first. The default priority is 0.
See also priority().
[slot] void Message::setText(const QString &richtext)
Sets the notification contents to richtext. If the message was already sent through Document::postMessage(), the displayed text changes on the fly.
Note: Change text on the fly with care, since changing the text may resize the notification widget, which may result in a distracting user experience.
richtext is the new notification text (rich text supported)
See also textChanged().
void Message::setView(KTextEditor::View *view)
Set the associated view of the message. If view is 0, the message is shown in all View%s of the Document. If view is given, i.e. non-zero, the message is shown only in this view. view the associated view the message should be displayed in
See also view().
void Message::setWordWrap(bool wordWrap)
Enabled word wrap according to wordWrap. By default, auto wrap is disabled.
Word wrap is enabled automatically, if the Message's width is larger than the parent widget's width to avoid breaking the gui layout.
See also wordWrap().
QString Message::text() const
Returns the text set in the constructor.
See also setText().
[signal] void Message::textChanged(const QString &text)
This signal is emitted whenever setText() was called.
text the new notification text (rich text supported)
See also setText().
KTextEditor::View *Message::view() const
This function returns the view you set by setView(). If setView() was not called, the return value is 0.
See also setView().
bool Message::wordWrap() const
Returns true if word wrap is enabled.
See also setWordWrap().