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

#include <qgsmessagebar.h>

Inheritance diagram for QgsMessageBar:

Public Slots
bool	clearWidgets ()
	Removes all items from the bar.

bool	popWidget ()
	Remove the currently displayed item from the bar and display the next item in the stack.

void	pushCritical (const QString &title, const QString &message)
	Pushes a critical warning message that must be manually dismissed by the user.

void	pushInfo (const QString &title, const QString &message)
	Pushes a information message with default timeout to the message bar.

void	pushSuccess (const QString &title, const QString &message)
	Pushes a success message with default timeout to the message bar.

void	pushWarning (const QString &title, const QString &message)
	Pushes a warning message that must be manually dismissed by the user.

Signals
void	widgetAdded (QgsMessageBarItem *item)
	Emitted whenever an item is added to the bar.

void	widgetRemoved (QgsMessageBarItem *item)
	Emitted whenever an item was removed from the bar.

Public Member Functions
	QgsMessageBar (QWidget *parent=nullptr)
	Constructor for QgsMessageBar.

QgsMessageBarItem *	currentItem ()
	Returns the current visible item, or `nullptr` if no item is shown.

QList< QgsMessageBarItem * >	items ()
	Returns a list of all items currently visible or queued for the bar.

bool	popWidget (QgsMessageBarItem *item)
	Remove the specified item from the bar, and display the next most recent one in the stack.

void	pushItem (QgsMessageBarItem *item)
	Display a message item on the bar, after hiding the currently visible one and putting it in a stack.

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.

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.

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.

QgsMessageBarItem *	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.

Static Public Member Functions
static QgsMessageBarItem *	createMessage (const QString &text, QWidget *parent=nullptr)
	Creates message bar item widget containing a message text to be displayed on the bar.

static QgsMessageBarItem *	createMessage (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.

static QgsMessageBarItem *	createMessage (QWidget widget, QWidget parent=nullptr)
	Creates message bar item widget containing a custom widget to be displayed on the bar.

static int	defaultMessageTimeout (Qgis::MessageLevel level=Qgis::MessageLevel::NoLevel)
	Returns the default timeout in seconds for timed messages of the specified level.

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 37 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 183 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 390 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 396 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 401 of file qgsmessagebar.cpp.

◆ currentItem()

QgsMessageBarItem * QgsMessageBar::currentItem ( )

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

Definition at line 380 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 216 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 385 of file qgsmessagebar.cpp.

◆ mousePressEvent()

void QgsMessageBar::mousePressEvent ( QMouseEvent * e )

overrideprotected

Definition at line 112 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 171 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

item	previously added item to remove.

Returns: true if item was removed, false otherwise

Definition at line 162 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

title	title string for message
message	The message to be displayed

Definition at line 211 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

title	title string for message
message	The message to be displayed

Definition at line 201 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 296 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 406 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 349 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 336 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

title	title string for message
message	The message to be displayed

Definition at line 196 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

title	title string for message
message	The message to be displayed

Definition at line 206 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

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

Definition at line 320 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 Symbol Documentation

◆ TestQgsMessageBar

friend class TestQgsMessageBar

friend

Definition at line 277 of file qgsmessagebar.h.

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

/build/qgis-3.41.0+git20241110+fda2aa46e9a+99sid/src/gui/qgsmessagebar.h
/build/qgis-3.41.0+git20241110+fda2aa46e9a+99sid/src/gui/qgsmessagebar.cpp

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ QgsMessageBar()

Member Function Documentation

◆ clearWidgets

◆ createMessage() [1/3]

◆ createMessage() [2/3]

◆ createMessage() [3/3]

◆ currentItem()

◆ defaultMessageTimeout()

◆ items()

◆ mousePressEvent()

◆ popWidget [1/2]

◆ popWidget() [2/2]

◆ pushCritical

◆ pushInfo

◆ pushItem()

◆ pushMessage() [1/3]

◆ pushMessage() [2/3]

◆ pushMessage() [3/3]

◆ pushSuccess

◆ pushWarning

◆ pushWidget()

◆ widgetAdded

◆ widgetRemoved

Friends And Related Symbol Documentation

◆ TestQgsMessageBar