KMessageWidget
#include <KMessageWidget>
Public Types | |
enum | MessageType { Positive , Information , Warning , Error } |
enum | Position { Inline , Header , Footer } |
Public Types inherited from QFrame | |
enum | Shadow |
enum | Shape |
enum | StyleMask |
Public Types inherited from QWidget | |
enum | RenderFlag |
Public Types inherited from QPaintDevice | |
enum | PaintDeviceMetric |
Signals | |
void | hideAnimationFinished () |
void | linkActivated (const QString &contents) |
void | linkHovered (const QString &contents) |
void | showAnimationFinished () |
Public Slots | |
void | animatedHide () |
void | animatedShow () |
void | setCloseButtonVisible (bool visible) |
void | setIcon (const QIcon &icon) |
void | setMessageType (KMessageWidget::MessageType type) |
void | setPosition (Position position) |
void | setText (const QString &text) |
void | setWordWrap (bool wordWrap) |
Detailed Description
A widget to provide feedback or propose opportunistic interactions.
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
- Since
- 4.7
Definition at line 87 of file kmessagewidget.h.
Member Enumeration Documentation
◆ MessageType
Available message types.
The background colors are chosen depending on the message type.
Enumerator | |
---|---|
Positive | Positive message type. |
Information | Information message type. |
Warning | Warning message type. |
Error | Error message type. |
Definition at line 103 of file kmessagewidget.h.
◆ Position
Position of the KMessageWidget.
This will update the look of the KMessageWidget to be appropriate to the position.
- Since
- 6.0
Enumerator | |
---|---|
Inline | The message widget is display inside the content. |
Header | The message widget is displayed as header. |
Footer | The message widget is displayed as footer. |
Definition at line 117 of file kmessagewidget.h.
Property Documentation
◆ closeButtonVisible
|
readwrite |
Definition at line 94 of file kmessagewidget.h.
◆ icon
|
readwrite |
Definition at line 96 of file kmessagewidget.h.
◆ messageType
|
readwrite |
Definition at line 95 of file kmessagewidget.h.
◆ position
|
readwrite |
Definition at line 97 of file kmessagewidget.h.
◆ text
|
readwrite |
Definition at line 91 of file kmessagewidget.h.
◆ textFormat
|
readwrite |
Definition at line 92 of file kmessagewidget.h.
◆ wordWrap
|
readwrite |
Definition at line 93 of file kmessagewidget.h.
Constructor & Destructor Documentation
◆ KMessageWidget() [1/2]
Constructs a KMessageWidget with the specified parent
.
Definition at line 231 of file kmessagewidget.cpp.
◆ KMessageWidget() [2/2]
Constructs a KMessageWidget with the specified parent
and contents text
.
Definition at line 238 of file kmessagewidget.cpp.
◆ ~KMessageWidget()
|
overridedefault |
Destructor.
Member Function Documentation
◆ addAction()
Add action
to the message widget.
For each action a button is added to the message widget in the order the actions were added.
- Parameters
-
action the action to add
- See also
- removeAction(), QWidget::actions()
Definition at line 413 of file kmessagewidget.cpp.
◆ animatedHide
|
slot |
Hide the widget using an animation.
Definition at line 464 of file kmessagewidget.cpp.
◆ animatedShow
|
slot |
Show the widget using an animation.
Definition at line 434 of file kmessagewidget.cpp.
◆ clearActions()
void KMessageWidget::clearActions | ( | ) |
Clears all actions from the message widget.
- Since
- 5.100
Definition at line 425 of file kmessagewidget.cpp.
◆ event()
|
overrideprotectedvirtual |
Reimplemented from QFrame.
Definition at line 292 of file kmessagewidget.cpp.
◆ heightForWidth()
|
overridevirtual |
Returns the required height for width
.
- Parameters
-
width the width in pixels
Reimplemented from QWidget.
Definition at line 328 of file kmessagewidget.cpp.
◆ hideAnimationFinished
|
signal |
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().
- See also
- animatedHide()
- Since
- 5.0
◆ icon()
QIcon KMessageWidget::icon | ( | ) | const |
The icon shown on the left of the text.
By default, no icon is shown.
- Since
- 4.11
Definition at line 503 of file kmessagewidget.cpp.
◆ isCloseButtonVisible()
bool KMessageWidget::isCloseButtonVisible | ( | ) | const |
Check whether the close button is visible.
- See also
- setCloseButtonVisible()
Definition at line 402 of file kmessagewidget.cpp.
◆ isHideAnimationRunning()
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.
- See also
- animatedHide(), hideAnimationFinished()
- Since
- 5.0
Definition at line 493 of file kmessagewidget.cpp.
◆ isShowAnimationRunning()
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.
- See also
- animatedShow(), showAnimationFinished()
- Since
- 5.0
Definition at line 498 of file kmessagewidget.cpp.
◆ linkActivated
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.
- Parameters
-
contents text of the href anchor
- See also
- QLabel::linkActivated()
- Since
- 4.10
◆ linkHovered
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.
- Parameters
-
contents text of the href anchor
- See also
- QLabel::linkHovered()
- Since
- 4.11
◆ messageType()
KMessageWidget::MessageType KMessageWidget::messageType | ( | ) | const |
Get the type of this message.
By default, the type is set to KMessageWidget::Information.
Definition at line 269 of file kmessagewidget.cpp.
◆ minimumSizeHint()
|
overridevirtual |
Returns the minimum size of the message widget.
Reimplemented from QWidget.
Definition at line 286 of file kmessagewidget.cpp.
◆ paintEvent()
|
overrideprotectedvirtual |
Reimplemented from QFrame.
Definition at line 334 of file kmessagewidget.cpp.
◆ position()
KMessageWidget::Position KMessageWidget::position | ( | ) | const |
Get the position of this message.
By default this is KMessageWidget::Inline.
- See also
- setPosition()
- Since
- 6.0
Definition at line 391 of file kmessagewidget.cpp.
◆ removeAction()
Remove action
from the message widget.
- Parameters
-
action the action to remove
Definition at line 419 of file kmessagewidget.cpp.
◆ resizeEvent()
|
overrideprotectedvirtual |
Reimplemented from QWidget.
Definition at line 320 of file kmessagewidget.cpp.
◆ setCloseButtonVisible
|
slot |
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.
- See also
- closeButtonVisible(), animatedHide()
Definition at line 407 of file kmessagewidget.cpp.
◆ setIcon
Define an icon to be shown on the left of the text.
- Since
- 4.11
Definition at line 508 of file kmessagewidget.cpp.
◆ setMessageType
|
slot |
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.
- See also
- messageType(), KMessageWidget::MessageType
Definition at line 274 of file kmessagewidget.cpp.
◆ setPosition
|
slot |
Set the position of this message.
- See also
- position()
- Since
- 6.0
Definition at line 396 of file kmessagewidget.cpp.
◆ setText
Set the text of the message widget to text
.
If the message widget is already visible, the text changes on the fly.
- Parameters
-
text the text to display, rich text is allowed
- See also
- text()
Definition at line 253 of file kmessagewidget.cpp.
◆ setTextFormat()
void KMessageWidget::setTextFormat | ( | Qt::TextFormat | textFormat | ) |
Set the text format of the message widget's label.
- See also
- QLabel::setTextFormat()
- Since
- 6.0
Definition at line 264 of file kmessagewidget.cpp.
◆ setWordWrap
|
slot |
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.
- Parameters
-
wordWrap disable/enable word wrap
- See also
- wordWrap()
Definition at line 375 of file kmessagewidget.cpp.
◆ showAnimationFinished
|
signal |
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().
- See also
- animatedShow()
- Since
- 5.0
◆ sizeHint()
Returns the preferred size of the message widget.
Reimplemented from QFrame.
Definition at line 280 of file kmessagewidget.cpp.
◆ text()
QString KMessageWidget::text | ( | ) | const |
Get the text of this message widget.
- See also
- setText()
Definition at line 248 of file kmessagewidget.cpp.
◆ textFormat()
Qt::TextFormat KMessageWidget::textFormat | ( | ) | const |
Get the text format of the message widget's label.
- See also
- QLabel::textFormat()
- Since
- 6.0
Definition at line 259 of file kmessagewidget.cpp.
◆ wordWrap()
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.
- See also
- setWordWrap()
Definition at line 370 of file kmessagewidget.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.