KMessageWidget Class
A widget to provide feedback or propose opportunistic interactions. More...
| Header: | #include <KMessageWidget> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS WidgetsAddons)target_link_libraries(mytarget PRIVATE KF6::WidgetsAddons) |
| Since: | 4.7 |
| Inherits: | QFrame |
Public Types
| enum | MessageType { Positive, Information, Warning, Error } |
(since 6.0) enum | Position { Inline, Header, Footer } |
Public Functions
| KMessageWidget(QWidget *parent = nullptr) | |
| KMessageWidget(const QString &text, QWidget *parent = nullptr) | |
| virtual | ~KMessageWidget() override |
| void | addAction(QAction *action) |
(since 5.100) void | clearActions() |
(since 4.11) QIcon | icon() const |
| bool | isCloseButtonVisible() const |
(since 5.0) bool | isHideAnimationRunning() const |
(since 5.0) bool | isShowAnimationRunning() const |
| KMessageWidget::MessageType | messageType() const |
(since 6.0) KMessageWidget::Position | position() const |
| void | removeAction(QAction *action) |
(since 6.0) void | setTextFormat(Qt::TextFormat textFormat) |
| QString | text() const |
(since 6.0) Qt::TextFormat | textFormat() const |
| bool | wordWrap() const |
Public Slots
| void | animatedHide() |
| void | animatedShow() |
| void | setCloseButtonVisible(bool visible) |
(since 4.11) void | setIcon(const QIcon &icon) |
| void | setMessageType(KMessageWidget::MessageType type) |
(since 6.0) void | setPosition(KMessageWidget::Position position) |
| void | setText(const QString &text) |
| void | setWordWrap(bool wordWrap) |
Signals
(since 5.0) void | hideAnimationFinished() |
(since 4.10) void | linkActivated(const QString &contents) |
(since 4.11) void | linkHovered(const QString &contents) |
(since 5.0) void | showAnimationFinished() |
Detailed Description
KMessageWidget can be used to provide inline positive or negative feedback, or to implement opportunistic interactions.
As a feedback widget, KMessageWidget provides a less intrusive alternative to "OK Only" message boxes. If you want to avoid a modal KMessageBox, consider using KMessageWidget instead.
Examples of KMessageWidget look as follows, all of them having an icon set with setIcon(), and the first three show a close button:
Negative feedback
The KMessageWidget can be used as a secondary indicator of failure: the first indicator is usually the fact the action the user expected to happen did not happen.
Example: User fills a form, clicks "Submit".
- Expected feedback: form closes
- First indicator of failure: form stays there
- Second indicator of failure: a KMessageWidget appears on top of the form, explaining the error condition
When used to provide negative feedback, KMessageWidget should be placed close to its context. In the case of a form, it should appear on top of the form entries.
KMessageWidget should get inserted in the existing layout. Space should not be reserved for it, otherwise it becomes "dead space", ignored by the user. KMessageWidget should also not appear as an overlay to prevent blocking access to elements the user needs to interact with to fix the failure.
Positive feedback
KMessageWidget can be used for positive feedback but it shouldn't be overused. It is often enough to provide feedback by simply showing the results of an action.
Examples of acceptable uses:
- Confirm success of "critical" transactions
- Indicate completion of background tasks
Example of unadapted uses:
- Indicate successful saving of a file
- Indicate a file has been successfully removed
Opportunistic interaction
Opportunistic interaction is the situation where the application suggests to the user an action he could be interested in perform, either based on an action the user just triggered or an event which the application noticed.
Example of acceptable uses:
- A browser can propose remembering a recently entered password
- A music collection can propose ripping a CD which just got inserted
- A chat application may notify the user a "special friend" just connected
Member Type Documentation
enum KMessageWidget::MessageType
Available message types. The background colors are chosen depending on the message type.
| Constant | Value | Description |
|---|---|---|
KMessageWidget::Positive | 0 | Positive message type |
KMessageWidget::Information | 1 | Information message type |
KMessageWidget::Warning | 2 | Warning message type |
KMessageWidget::Error | 3 | Error message type |
[since 6.0] enum KMessageWidget::Position
Position of the KMessageWidget
This will update the look of the KMessageWidget to be appropriate to the position.
| Constant | Value | Description |
|---|---|---|
KMessageWidget::Inline | 0 | The message widget is display inside the content. |
KMessageWidget::Header | 1 | The message widget is displayed as header. |
KMessageWidget::Footer | 2 | The message widget is displayed as footer. |
This enum was introduced in 6.0.
Member Function Documentation
[explicit] KMessageWidget::KMessageWidget(QWidget *parent = nullptr)
Constructs a KMessageWidget with the specified parent.
[explicit] KMessageWidget::KMessageWidget(const QString &text, QWidget *parent = nullptr)
Constructs a KMessageWidget with the specified parent and contents text.
[override virtual noexcept] KMessageWidget::~KMessageWidget()
Destructor.
void KMessageWidget::addAction(QAction *action)
Add action to the message widget.
For each action a button is added to the message widget in the order the actions were added.
action the action to add
See also removeAction() and QWidget::actions().
[slot] void KMessageWidget::animatedHide()
Hide the widget using an animation.
[slot] void KMessageWidget::animatedShow()
Show the widget using an animation.
[since 5.100] void KMessageWidget::clearActions()
Clears all actions from the message widget.
This function was introduced in 5.100.
See also KMessageWidget::MessageType, addAction(), and removeAction().
[signal, since 5.0] void KMessageWidget::hideAnimationFinished()
This signal is emitted when the hide animation is finished, started by calling animatedHide(). If animations are disabled, this signal is emitted immediately after the message widget got hidden.
Note: This signal is not emitted if the widget was hidden by calling hide(), so this signal is only useful in conjunction with animatedHide().
This function was introduced in 5.0.
See also animatedHide().
[since 4.11] QIcon KMessageWidget::icon() const
The icon shown on the left of the text. By default, no icon is shown.
Note: Getter function for property icon.
This function was introduced in 4.11.
See also setIcon().
bool KMessageWidget::isCloseButtonVisible() const
Check whether the close button is visible.
Note: Getter function for property closeButtonVisible.
See also setCloseButtonVisible().
[since 5.0] bool KMessageWidget::isHideAnimationRunning() const
Check whether the hide animation started by calling animatedHide() is still running. If animations are disabled, this function always returns false.
This function was introduced in 5.0.
See also animatedHide() and hideAnimationFinished().
[since 5.0] bool KMessageWidget::isShowAnimationRunning() const
Check whether the show animation started by calling animatedShow() is still running. If animations are disabled, this function always returns false.
This function was introduced in 5.0.
See also animatedShow() and showAnimationFinished().
[signal, since 4.10] void KMessageWidget::linkActivated(const QString &contents)
This signal is emitted when the user clicks a link in the text label.
The URL referred to by the href anchor is passed in contents.
contents text of the href anchor
This function was introduced in 4.10.
See also QLabel::linkActivated().
[signal, since 4.11] void KMessageWidget::linkHovered(const QString &contents)
This signal is emitted when the user hovers over a link in the text label.
The URL referred to by the href anchor is passed in contents.
contents text of the href anchor
This function was introduced in 4.11.
See also QLabel::linkHovered().
KMessageWidget::MessageType KMessageWidget::messageType() const
Get the type of this message. By default, the type is set to KMessageWidget::Information.
Note: Getter function for property messageType.
See also KMessageWidget::MessageType and setMessageType().
[since 6.0] KMessageWidget::Position KMessageWidget::position() const
Get the position of this message. By default this is KMessageWidget::Inline.
Note: Getter function for property position.
This function was introduced in 6.0.
See also setPosition().
void KMessageWidget::removeAction(QAction *action)
Remove action from the message widget.
action the action to remove
See also KMessageWidget::MessageType, addAction(), and setMessageType().
[slot] void KMessageWidget::setCloseButtonVisible(bool visible)
Set the visibility of the close button. If visible is true, a close button is shown that calls animatedHide() if clicked.
By default the close button is set to be visible.
Note: Setter function for property closeButtonVisible.
See also isCloseButtonVisible(), closeButtonVisible(), and animatedHide().
[slot, since 4.11] void KMessageWidget::setIcon(const QIcon &icon)
Define an icon to be shown on the left of the text
Note: Setter function for property icon.
This function was introduced in 4.11.
See also icon().
[slot] void KMessageWidget::setMessageType(KMessageWidget::MessageType type)
Set the message type to type. By default, the message type is set to KMessageWidget::Information. Appropriate colors are chosen to mimic the appearance of Kirigami's InlineMessage.
Note: Setter function for property messageType.
See also messageType() and KMessageWidget::MessageType.
[slot, since 6.0] void KMessageWidget::setPosition(KMessageWidget::Position position)
Set the position of this message
Note: Setter function for property position.
This function was introduced in 6.0.
See also position().
[slot] void KMessageWidget::setText(const QString &text)
Set the text of the message widget to text. If the message widget is already visible, the text changes on the fly.
text the text to display, rich text is allowed
Note: Setter function for property text.
See also text().
[since 6.0] void KMessageWidget::setTextFormat(Qt::TextFormat textFormat)
Set the text format of the message widget's label.
Note: Setter function for property textFormat.
This function was introduced in 6.0.
See also textFormat() and QLabel::setTextFormat().
[slot] void KMessageWidget::setWordWrap(bool wordWrap)
Set word wrap to wordWrap. If word wrap is enabled, the text() of the message widget is wrapped to fit the available width. If word wrap is disabled, the message widget's minimum size is such that the entire text fits.
By default word wrap is disabled.
wordWrap disable/enable word wrap
Note: Setter function for property wordWrap.
See also wordWrap().
[signal, since 5.0] void KMessageWidget::showAnimationFinished()
This signal is emitted when the show animation is finished, started by calling animatedShow(). If animations are disabled, this signal is emitted immediately after the message widget got shown.
Note: This signal is not emitted if the widget was shown by calling show(), so this signal is only useful in conjunction with animatedShow().
This function was introduced in 5.0.
See also animatedShow().
QString KMessageWidget::text() const
Get the text of this message widget.
Note: Getter function for property text.
See also setText().
[since 6.0] Qt::TextFormat KMessageWidget::textFormat() const
Get the text format of the message widget's label.
Note: Getter function for property textFormat.
This function was introduced in 6.0.
See also setTextFormat() and QLabel::textFormat().
bool KMessageWidget::wordWrap() const
Check whether word wrap is enabled.
If word wrap is enabled, the message widget wraps the displayed text as required to the available width of the widget. This is useful to avoid breaking widget layouts.
Note: Getter function for property wordWrap.
See also setWordWrap().