Skip to content

Commit

Permalink
Cleanup headers, dox++
Browse files Browse the repository at this point in the history
  • Loading branch information
@nyalldawson
nyalldawson committed May 26, 2020
1 parent 15412b0 commit 32274ed
Show file tree
Hide file tree
Showing 5 changed files with 396 additions and 71 deletions.
110 changes: 86 additions & 24 deletions python/gui/auto_generated/qgsmessagebar.sip.in
View file
Expand Up @@ -15,6 +15,21 @@ class QgsMessageBar: QFrame
{
%Docstring
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.
%End

%TypeHeaderCode
Expand All @@ -29,93 +44,140 @@ Constructor for QgsMessageBar

void pushItem( QgsMessageBarItem *item /Transfer/ );
%Docstring
Display a message item on the bar after hiding the currently visible one
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 the item.

:param item: Item to display
The message bar will take ownership of ``item``.
%End

QgsMessageBarItem *pushWidget( QWidget *widget /Transfer/, Qgis::MessageLevel level = Qgis::Info, int duration = 0 );
%Docstring
Display a widget as a message on the bar after hiding the currently visible one
Display a ``widget`` as a message on the bar, after hiding the currently visible one
and putting it in a stack.

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

bool popWidget( QgsMessageBarItem *item );
%Docstring
Remove the passed widget from the bar (if previously added),
then display the next one in the stack if any or hide the bar
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.

:param item: item to remove
:param item: previously added item to remove.

:return: ``True`` if the widget was removed, ``False`` otherwise
:return: ``True`` if ``item`` was removed, ``False`` otherwise
%End

static QgsMessageBarItem *createMessage( const QString &text, QWidget *parent = 0 ) /Factory/;
%Docstring
make out a widget containing a message to be displayed on the bar
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.
%End

static QgsMessageBarItem *createMessage( const QString &title, const QString &text, QWidget *parent = 0 ) /Factory/;
%Docstring
make out a widget containing title and message to be displayed on the bar
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.
%End

static QgsMessageBarItem *createMessage( QWidget *widget, QWidget *parent = 0 ) /Factory/;
%Docstring
make out a widget containing title and message to be displayed on the bar
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.
%End

void pushMessage( const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
%Docstring
convenience method for pushing a message to the bar
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.
%End

void pushMessage( const QString &title, const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
%Docstring
convenience method for pushing a message with title to the bar
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.
%End

void pushMessage( const QString &title, const QString &text, const QString &showMore, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
%Docstring
convenience method for pushing a message to the bar with a detail text which be shown when pressing a "more" button
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.
%End

QgsMessageBarItem *currentItem();
%Docstring
Returns the current visible item, or ``None`` if no item is shown.
%End

signals:

void widgetAdded( QgsMessageBarItem *item );
%Docstring
emitted when a message widget is added to the bar
Emitted whenever an ``item`` is added to the bar.
%End

void widgetRemoved( QgsMessageBarItem *item );
%Docstring
emitted when a message widget was removed from the bar
Emitted whenever an ``item`` was removed from the bar.
%End

public slots:

bool popWidget();
%Docstring
Remove the currently displayed widget from the bar and
display the next in the stack if any or hide the bar.
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: ``True`` if the widget was removed, ``False`` otherwise
%End

bool clearWidgets();
%Docstring
Remove all items from the bar's widget list
Removes all items from the bar.

:return: ``True`` if all items were removed, ``False`` otherwise
%End

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

:param title: title string for message
:param message: The message to be displayed
Expand All @@ -125,7 +187,7 @@ Pushes a success message with default timeout to the message bar

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

:param title: title string for message
:param message: The message to be displayed
Expand All @@ -135,7 +197,7 @@ Pushes a information message with default timeout to the message bar

void pushWarning( const QString &title, const QString &message );
%Docstring
Pushes a warning with default timeout to the message bar
Pushes a warning ``message`` with default timeout to the message bar.

:param title: title string for message
:param message: The message to be displayed
Expand All @@ -145,7 +207,7 @@ Pushes a warning with default timeout to the message bar

void pushCritical( const QString &title, const QString &message );
%Docstring
Pushes a critical warning with default timeout to the message bar
Pushes a critical warning ``message`` with default timeout to the message bar.

:param title: title string for message
:param message: The message to be displayed
Expand Down
94 changes: 87 additions & 7 deletions python/gui/auto_generated/qgsmessagebaritem.sip.in
View file
Expand Up @@ -12,76 +12,155 @@

class QgsMessageBarItem : QWidget
{
%Docstring
Represents an item shown within a QgsMessageBar widget.

QgsMessageBarItem represents a single item (or message) which can be shown in a QgsMessageBar widget.
%End

%TypeHeaderCode
#include "qgsmessagebaritem.h"
%End
public:

QgsMessageBarItem( const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
%Docstring
make out a widget containing a message to be displayed on the bar
Constructor for QgsMessageBarItem, containing a message with the specified ``text`` to be displayed on the bar.

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

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.
%End

QgsMessageBarItem( const QString &title, const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
%Docstring
make out a widget containing title and message to be displayed on the bar
Constructor for QgsMessageBarItem, containing a ``title`` and message with the specified ``text`` to be displayed on the bar.

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

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.
%End

QgsMessageBarItem( const QString &title, const QString &text, QWidget *widget, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
%Docstring
make out a widget containing title, message and widget to be displayed on the bar
Constructor for QgsMessageBarItem, containing a \title, message with the specified ``text``, and a custom ``widget`` to be displayed on the bar.

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

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.
%End

QgsMessageBarItem( QWidget *widget, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
%Docstring
make out a widget containing a widget to be displayed on the bar
Constructor for QgsMessageBarItem, containing a custom ``widget`` to be displayed on the bar.

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

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.
%End

QgsMessageBarItem *setText( const QString &text );
%Docstring
Sets the message ``text`` to show in the item.

.. seealso:: :py:func:`text`
%End

QString text() const;
%Docstring
Returns the text for the message.

.. seealso:: :py:func:`setText`
%End

QgsMessageBarItem *setTitle( const QString &title );
%Docstring
Sets the ``title`` for in the item.

.. seealso:: :py:func:`title`
%End

QString title() const;
%Docstring
Returns the title for the message.

.. seealso:: :py:func:`setTitle`
%End

QgsMessageBarItem *setLevel( Qgis::MessageLevel level );
%Docstring
Sets the message ``level`` for the item, which controls how the message bar is styled
when the item is displayed.

.. seealso:: :py:func:`level`
%End

Qgis::MessageLevel level() const;
%Docstring
Returns the message level for the message.

.. seealso:: :py:func:`setLevel`
%End

QgsMessageBarItem *setWidget( QWidget *widget );
%Docstring
Sets a custom ``widget`` to show in the item.

.. seealso:: :py:func:`widget`
%End

QWidget *widget() const;
%Docstring
Returns the widget for the message.

.. seealso:: :py:func:`setWidget`
%End

QgsMessageBarItem *setIcon( const QIcon &icon );
%Docstring
Sets the ``icon`` associated with the message.

.. seealso:: :py:func:`icon`
%End

QIcon icon() const;
%Docstring
Returns the icon for the message.

.. seealso:: :py:func:`setIcon`
%End

QgsMessageBarItem *setDuration( int duration );
%Docstring
Sets the ``duration`` (in seconds) to show the message for. If ``duration``
is 0 then the message will not automatically timeout and instead must be
manually dismissed by the user.

.. seealso:: :py:func:`duration`
%End

int duration() const;
%Docstring
returns the duration in second of the message
Returns the duration (in seconds) of the message.

If the duration is 0 then the message will not automatically timeout and instead must be
manually dismissed by the user.

.. seealso:: :py:func:`setDuration`
%End

QString getStyleSheet();
%Docstring
returns the styleSheet
Returns the styleSheet which should be used to style a QgsMessageBar object when
this item is displayed.
%End

public slots:
Expand All @@ -99,7 +178,8 @@ has no effect.

void styleChanged( const QString &styleSheet );
%Docstring
emitted when the message level has changed
Emitted when the item's message level has changed and the message bar style
will need to be updated as a result.
%End

};
Expand Down

0 comments on commit 32274ed

Please sign in to comment.