QGIS API Documentation  3.21.0-Master (5b68dc587e)
Public Slots | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
QgsMessageBar Class Reference

A bar for displaying non-blocking messages to the user. More...

#include <qgsmessagebar.h>

Inheritance diagram for QgsMessageBar:
Inheritance graph
[legend]

Public Slots

bool clearWidgets ()
 Removes all items from the bar. More...
 
bool popWidget ()
 Remove the currently displayed item from the bar and display the next item in the stack. More...
 
void pushCritical (const QString &title, const QString &message)
 Pushes a critical warning message that must be manually dismissed by the user. More...
 
void pushInfo (const QString &title, const QString &message)
 Pushes a information message with default timeout to the message bar. More...
 
void pushSuccess (const QString &title, const QString &message)
 Pushes a success message with default timeout to the message bar. More...
 
void pushWarning (const QString &title, const QString &message)
 Pushes a warning message that must be manually dismissed by the user. More...
 

Signals

void widgetAdded (QgsMessageBarItem *item)
 Emitted whenever an item is added to the bar. More...
 
void widgetRemoved (QgsMessageBarItem *item)
 Emitted whenever an item was removed from the bar. More...
 

Public Member Functions

 QgsMessageBar (QWidget *parent=nullptr)
 Constructor for QgsMessageBar. More...
 
QgsMessageBarItemcurrentItem ()
 Returns the current visible item, or nullptr if no item is shown. More...
 
QList< QgsMessageBarItem * > items ()
 Returns a list of all items currently visible or queued for the bar. More...
 
bool popWidget (QgsMessageBarItem *item)
 Remove the specified item from the bar, and display the next most recent one in the stack. More...
 
void pushItem (QgsMessageBarItem *item)
 Display a message item on the bar, after hiding the currently visible one and putting it in a stack. More...
 
void pushMessage (const QString &text, Qgis::MessageLevel level=Qgis::MessageLevel::Info, int duration=-1)
 A convenience method for pushing a message with the specified text to the bar. More...
 
void pushMessage (const QString &title, const QString &text, const QString &showMore, Qgis::MessageLevel level=Qgis::MessageLevel::Info, int duration=-1)
 A convenience method for pushing a message with the specified title and text to the bar. More...
 
void pushMessage (const QString &title, const QString &text, Qgis::MessageLevel level=Qgis::MessageLevel::Info, int duration=-1)
 A convenience method for pushing a message with the specified title and text to the bar. More...
 
QgsMessageBarItempushWidget (QWidget *widget, Qgis::MessageLevel level=Qgis::MessageLevel::Info, int duration=0)
 Display a widget as a message on the bar, after hiding the currently visible one and putting it in a stack. More...
 

Static Public Member Functions

static QgsMessageBarItemcreateMessage (const QString &text, QWidget *parent=nullptr)
 Creates message bar item widget containing a message text to be displayed on the bar. More...
 
static QgsMessageBarItemcreateMessage (const QString &title, const QString &text, QWidget *parent=nullptr)
 Creates message bar item widget containing a title and message text to be displayed on the bar. More...
 
static QgsMessageBarItemcreateMessage (QWidget *widget, QWidget *parent=nullptr)
 Creates message bar item widget containing a custom widget to be displayed on the bar. More...
 
static int defaultMessageTimeout (Qgis::MessageLevel level=Qgis::MessageLevel::NoLevel)
 Returns the default timeout in seconds for timed messages of the specified level. More...
 

Protected Member Functions

void mousePressEvent (QMouseEvent *e) override
 

Friends

class TestQgsMessageBar
 

Detailed Description

A bar for displaying non-blocking messages to the user.

QgsMessageBar is a reusable widget which allows for providing feedback to users in a non-intrusive way. Messages are shown in a horizontal bar widget, which is styled automatically to reflect the severity ("message level") of the displayed message (e.g. warning messages are styled in an orange color scheme, critical errors are shown in red, etc).

The message bar supports automatic stacking of multiple messages, so that only the most recent message is shown to users. Users can then manually dismiss individual messages to remove them from the stack, causing the next-most-recent message to be shown. If no messages are available to show then the message bar automatically hides.

The class also supports pushing custom widgets to the notification stack via the pushWidget() method.

Definition at line 60 of file qgsmessagebar.h.

Constructor & Destructor Documentation

◆ QgsMessageBar()

QgsMessageBar::QgsMessageBar ( QWidget *  parent = nullptr)

Constructor for QgsMessageBar.

Definition at line 36 of file qgsmessagebar.cpp.

Member Function Documentation

◆ clearWidgets

bool QgsMessageBar::clearWidgets ( )
slot

Removes all items from the bar.

Returns
true if all items were removed, false otherwise

Definition at line 182 of file qgsmessagebar.cpp.

◆ createMessage() [1/3]

QgsMessageBarItem * QgsMessageBar::createMessage ( const QString &  text,
QWidget *  parent = nullptr 
)
static

Creates message bar item widget containing a message text to be displayed on the bar.

The caller takes ownership of the returned item.

Note
This is a low-level API call. Users are recommended to use the high-level pushMessage() API call instead.

Definition at line 389 of file qgsmessagebar.cpp.

◆ createMessage() [2/3]

QgsMessageBarItem * QgsMessageBar::createMessage ( const QString &  title,
const QString &  text,
QWidget *  parent = nullptr 
)
static

Creates message bar item widget containing a title and message text to be displayed on the bar.

The caller takes ownership of the returned item.

Note
This is a low-level API call. Users are recommended to use the high-level pushMessage() API call instead.

Definition at line 395 of file qgsmessagebar.cpp.

◆ createMessage() [3/3]

QgsMessageBarItem * QgsMessageBar::createMessage ( QWidget *  widget,
QWidget *  parent = nullptr 
)
static

Creates message bar item widget containing a custom widget to be displayed on the bar.

The caller takes ownership of the returned item.

Note
This is a low-level API call. Users are recommended to use the high-level pushWidget() API call instead.

Definition at line 400 of file qgsmessagebar.cpp.

◆ currentItem()

QgsMessageBarItem * QgsMessageBar::currentItem ( )

Returns the current visible item, or nullptr if no item is shown.

Definition at line 379 of file qgsmessagebar.cpp.

◆ defaultMessageTimeout()

int QgsMessageBar::defaultMessageTimeout ( Qgis::MessageLevel  level = Qgis::MessageLevel::NoLevel)
static

Returns the default timeout in seconds for timed messages of the specified level.

Since
QGIS 3.18

Definition at line 215 of file qgsmessagebar.cpp.

◆ items()

QList< QgsMessageBarItem * > QgsMessageBar::items ( )

Returns a list of all items currently visible or queued for the bar.

Since
QGIS 3.14

Definition at line 384 of file qgsmessagebar.cpp.

◆ mousePressEvent()

void QgsMessageBar::mousePressEvent ( QMouseEvent *  e)
overrideprotected

Definition at line 111 of file qgsmessagebar.cpp.

◆ popWidget [1/2]

bool QgsMessageBar::popWidget ( )
slot

Remove the currently displayed item from the bar and display the next item in the stack.

If no remaining items are present, the bar will be hidden.

Returns
true if the widget was removed, false otherwise

Definition at line 170 of file qgsmessagebar.cpp.

◆ popWidget() [2/2]

bool QgsMessageBar::popWidget ( QgsMessageBarItem item)

Remove the specified item from the bar, and display the next most recent one in the stack.

If no messages remain in the stack, then the bar will be hidden.

Parameters
itempreviously added item to remove.
Returns
true if item was removed, false otherwise

Definition at line 161 of file qgsmessagebar.cpp.

◆ pushCritical

void QgsMessageBar::pushCritical ( const QString &  title,
const QString &  message 
)
slot

Pushes a critical warning message that must be manually dismissed by the user.

Before QGIS 3.18 the default timeout was used.

Parameters
titletitle string for message
messageThe message to be displayed
Since
QGIS 2.8

Definition at line 210 of file qgsmessagebar.cpp.

◆ pushInfo

void QgsMessageBar::pushInfo ( const QString &  title,
const QString &  message 
)
slot

Pushes a information message with default timeout to the message bar.

Parameters
titletitle string for message
messageThe message to be displayed
Since
QGIS 2.8

Definition at line 200 of file qgsmessagebar.cpp.

◆ pushItem()

void QgsMessageBar::pushItem ( QgsMessageBarItem item)

Display a message item on the bar, after hiding the currently visible one and putting it in a stack.

The message bar will take ownership of item.

Definition at line 295 of file qgsmessagebar.cpp.

◆ pushMessage() [1/3]

void QgsMessageBar::pushMessage ( const QString &  text,
Qgis::MessageLevel  level = Qgis::MessageLevel::Info,
int  duration = -1 
)

A convenience method for pushing a message with the specified text to the bar.

The level argument specifies the desired message level (severity) of the message, which controls how the message bar is styled.

The optional duration argument can be used to specify the message timeout in seconds. If duration is set to 0, then the message must be manually dismissed by the user. Since QGIS 3.18, a duration of -1 indicates that the default timeout for the message level should be used.

Definition at line 405 of file qgsmessagebar.cpp.

◆ pushMessage() [2/3]

void QgsMessageBar::pushMessage ( const QString &  title,
const QString &  text,
const QString &  showMore,
Qgis::MessageLevel  level = Qgis::MessageLevel::Info,
int  duration = -1 
)

A convenience method for pushing a message with the specified title and text to the bar.

Additional message content specified via showMore will be shown when the user presses a "more" button.

The level argument specifies the desired message level (severity) of the message, which controls how the message bar is styled.

The optional duration argument can be used to specify the message timeout in seconds. If duration is set to 0, then the message must be manually dismissed by the user. Since QGIS 3.18, a duration of -1 indicates that the default timeout for the message level should be used.

Definition at line 348 of file qgsmessagebar.cpp.

◆ pushMessage() [3/3]

void QgsMessageBar::pushMessage ( const QString &  title,
const QString &  text,
Qgis::MessageLevel  level = Qgis::MessageLevel::Info,
int  duration = -1 
)

A convenience method for pushing a message with the specified title and text to the bar.

The level argument specifies the desired message level (severity) of the message, which controls how the message bar is styled.

The optional duration argument can be used to specify the message timeout in seconds. If duration is set to 0, then the message must be manually dismissed by the user. Since QGIS 3.18, a duration of -1 indicates that the default timeout for the message level should be used.

Definition at line 335 of file qgsmessagebar.cpp.

◆ pushSuccess

void QgsMessageBar::pushSuccess ( const QString &  title,
const QString &  message 
)
slot

Pushes a success message with default timeout to the message bar.

Parameters
titletitle string for message
messageThe message to be displayed
Since
QGIS 2.8

Definition at line 195 of file qgsmessagebar.cpp.

◆ pushWarning

void QgsMessageBar::pushWarning ( const QString &  title,
const QString &  message 
)
slot

Pushes a warning message that must be manually dismissed by the user.

Before QGIS 3.18 the default timeout was used.

Parameters
titletitle string for message
messageThe message to be displayed
Since
QGIS 2.8

Definition at line 205 of file qgsmessagebar.cpp.

◆ pushWidget()

QgsMessageBarItem * QgsMessageBar::pushWidget ( QWidget *  widget,
Qgis::MessageLevel  level = Qgis::MessageLevel::Info,
int  duration = 0 
)

Display a widget as a message on the bar, after hiding the currently visible one and putting it in a stack.

Parameters
widgetmessage widget to display
levelis Qgis::MessageLevel::Info, Warning, Critical or Success
durationtimeout duration of message in seconds, 0 value indicates no timeout (i.e. the message must be manually cleared by the user).

Definition at line 319 of file qgsmessagebar.cpp.

◆ widgetAdded

void QgsMessageBar::widgetAdded ( QgsMessageBarItem item)
signal

Emitted whenever an item is added to the bar.

◆ widgetRemoved

void QgsMessageBar::widgetRemoved ( QgsMessageBarItem item)
signal

Emitted whenever an item was removed from the bar.

Friends And Related Function Documentation

◆ TestQgsMessageBar

friend class TestQgsMessageBar
friend

Definition at line 281 of file qgsmessagebar.h.


The documentation for this class was generated from the following files: