Class: QgsMessageBar

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.

Class Hierarchy

Base classes

QFrame
QWidget
QObject
QPaintDevice

Methods

clearWidgets	Removes all items from the bar.
currentItem	Returns the current visible item, or None if no item is shown.
items	Returns a list of all items currently visible or queued for the bar.
popWidget	Remove the specified item from the bar, and display the next most recent one in the stack.
pushCritical	Pushes a critical warning message that must be manually dismissed by the user.
pushInfo	Pushes a information message with default timeout to the message bar.
pushItem	Display a message item on the bar, after hiding the currently visible one and putting it in a stack.
pushMessage	A convenience method for pushing a message with the specified text to the bar.
pushSuccess	Pushes a success message with default timeout to the message bar.
pushWarning	Pushes a warning message that must be manually dismissed by the user.
pushWidget	Display a widget as a message on the bar, after hiding the currently visible one and putting it in a stack.

Static Methods

createMessage	Creates message bar item widget containing a message text to be displayed on the bar.
defaultMessageTimeout	Returns the default timeout in seconds for timed messages of the specified level.

Signals

widgetAdded	Emitted whenever an item is added to the bar.
widgetRemoved	Emitted whenever an item was removed from the bar.

class qgis.gui.QgsMessageBar

Bases: QFrame

__init__(parent: QWidget | None = None)

Constructor for QgsMessageBar

Parameters:

parent (Optional[QWidget] = None)

clearWidgets(self) → bool

Removes all items from the bar.

Return type:

bool

Returns:

True if all items were removed, False otherwise

static createMessage(text: str | None, parent: QWidget | None = None) → QgsMessageBarItem | None

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.

Parameters:

• text (Optional[str])

• parent (Optional[QWidget] = None)

Return type:

Optional[QgsMessageBarItem]

static createMessage(title: str | None, text: str | None, parent: QWidget | None = None) → QgsMessageBarItem | None

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.

Parameters:

• title (Optional[str])

• text (Optional[str])

• parent (Optional[QWidget] = None)

Return type:

Optional[QgsMessageBarItem]

static createMessage(widget: QWidget | None, parent: QWidget | None = None) → QgsMessageBarItem | None

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.

Parameters:

• widget (Optional[QWidget])

• parent (Optional[QWidget] = None)

Return type:

Optional[QgsMessageBarItem]

currentItem(self) → QgsMessageBarItem | None

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

Return type:

Optional[QgsMessageBarItem]

static defaultMessageTimeout(level: Qgis.MessageLevel = Qgis.MessageLevel.NoLevel) → int

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

Added in version 3.18.

Parameters:

level (Qgis.MessageLevel = Qgis.MessageLevel.NoLevel)

Return type:

int

items(self) → List[QgsMessageBarItem]

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

Added in version 3.14.

Return type:

List[QgsMessageBarItem]

popWidget(self, item: QgsMessageBarItem | None) → bool

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 (Optional[QgsMessageBarItem]) – previously added item to remove.

Return type:

bool

Returns:

True if item was removed, False otherwise

popWidget(self) → bool

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.

Return type:

bool

Returns:

True if the widget was removed, False otherwise

pushCritical(self, title: str | None, message: str | None)

Pushes a critical warning message that must be manually dismissed by the user. Before QGIS 3.18 the default timeout was used.

Parameters:

• title (Optional[str]) – title string for message

• message (Optional[str]) – The message to be displayed

pushInfo(self, title: str | None, message: str | None)

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

Parameters:

• title (Optional[str]) – title string for message

• message (Optional[str]) – The message to be displayed

pushItem(self, item: QgsMessageBarItem | None)

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.

Parameters:

item (Optional[QgsMessageBarItem])

pushMessage(self, text: str | None, level: Qgis.MessageLevel = Qgis.MessageLevel.Info, duration: int = -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.

Parameters:

• text (Optional[str])

• level (Qgis.MessageLevel = Qgis.MessageLevel.Info)

• duration (int = -1)

pushMessage(self, title: str | None, text: str | None, level: Qgis.MessageLevel = Qgis.MessageLevel.Info, duration: int = -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.

Parameters:

• title (Optional[str])

• text (Optional[str])

• level (Qgis.MessageLevel = Qgis.MessageLevel.Info)

• duration (int = -1)

pushMessage(self, title: str | None, text: str | None, showMore: str | None, level: Qgis.MessageLevel = Qgis.MessageLevel.Info, duration: int = -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.

Parameters:

• title (Optional[str])

• text (Optional[str])

• showMore (Optional[str])

• level (Qgis.MessageLevel = Qgis.MessageLevel.Info)

• duration (int = -1)

pushSuccess(self, title: str | None, message: str | None)

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

Parameters:

• title (Optional[str]) – title string for message

• message (Optional[str]) – The message to be displayed

pushWarning(self, title: str | None, message: str | None)

Pushes a warning message that must be manually dismissed by the user. Before QGIS 3.18 the default timeout was used.

Parameters:

• title (Optional[str]) – title string for message

• message (Optional[str]) – The message to be displayed

pushWidget(self, widget: QWidget | None, level: Qgis.MessageLevel = Qgis.MessageLevel.Info, duration: int = 0) → QgsMessageBarItem | None

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

Parameters:

• widget (Optional[QWidget]) – message widget to display

• level (Qgis.MessageLevel = Qgis.MessageLevel.Info) – is Qgis.MessageLevel.Info, Warning, Critical or Success

• duration (int = 0) – timeout duration of message in seconds, 0 value indicates no timeout (i.e. the message must be manually cleared by the user).

Return type:

Optional[QgsMessageBarItem]

signal widgetAdded(item: QgsMessageBarItem)

Emitted whenever an item is added to the bar.

Parameters:

item (QgsMessageBarItem)

signal widgetRemoved(item: QgsMessageBarItem)

Emitted whenever an item was removed from the bar.

Parameters:

item (QgsMessageBarItem)