Skip to content

Commit 32274ed

Browse files
nyalldawsonnyalldawson
committedMay 26, 2020
Cleanup headers, dox++
·
ltr-3_40final-3_14_0
1 parent 15412b0 commit 32274ed

File tree

5 files changed

+396
-71
lines changed

5 files changed

+396
-71
lines changed
 

‎python/gui/auto_generated/qgsmessagebar.sip.in

Lines changed: 86 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,21 @@ class QgsMessageBar: QFrame
1515
{
1616
%Docstring
1717
A bar for displaying non-blocking messages to the user.
18+
19+
QgsMessageBar is a reusable widget which allows for providing feedback to users in
20+
a non-intrusive way. Messages are shown in a horizontal bar widget, which is styled
21+
automatically to reflect the severity ("message level") of the displayed message (e.g.
22+
warning messages are styled in an orange color scheme, critical errors are shown in
23+
red, etc).
24+
25+
The message bar supports automatic stacking of multiple messages, so that
26+
only the most recent message is shown to users. Users can then manually dismiss
27+
individual messages to remove them from the stack, causing the next-most-recent
28+
message to be shown. If no messages are available to show then the message bar
29+
automatically hides.
30+
31+
The class also supports pushing custom widgets to the notification stack via
32+
the pushWidget() method.
1833
%End
1934

2035
%TypeHeaderCode
@@ -29,93 +44,140 @@ Constructor for QgsMessageBar
2944

3045
void pushItem( QgsMessageBarItem *item /Transfer/ );
3146
%Docstring
32-
Display a message item on the bar after hiding the currently visible one
47+
Display a message ``item`` on the bar, after hiding the currently visible one
3348
and putting it in a stack.
34-
The message bar will take ownership of the item.
3549

36-
:param item: Item to display
50+
The message bar will take ownership of ``item``.
3751
%End
3852

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

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

4964
bool popWidget( QgsMessageBarItem *item );
5065
%Docstring
51-
Remove the passed widget from the bar (if previously added),
52-
then display the next one in the stack if any or hide the bar
66+
Remove the specified ``item`` from the bar, and display the next most recent one in the stack.
67+
If no messages remain in the stack, then the bar will be hidden.
5368

54-
:param item: item to remove
69+
:param item: previously added item to remove.
5570

56-
:return: ``True`` if the widget was removed, ``False`` otherwise
71+
:return: ``True`` if ``item`` was removed, ``False`` otherwise
5772
%End
5873

5974
static QgsMessageBarItem *createMessage( const QString &text, QWidget *parent = 0 ) /Factory/;
6075
%Docstring
61-
make out a widget containing a message to be displayed on the bar
76+
Creates message bar item widget containing a message ``text`` to be displayed on the bar.
77+
78+
The caller takes ownership of the returned item.
79+
80+
.. note::
81+
82+
This is a low-level API call. Users are recommended to use the high-level pushMessage() API call
83+
instead.
6284
%End
85+
6386
static QgsMessageBarItem *createMessage( const QString &title, const QString &text, QWidget *parent = 0 ) /Factory/;
6487
%Docstring
65-
make out a widget containing title and message to be displayed on the bar
88+
Creates message bar item widget containing a ``title`` and message ``text`` to be displayed on the bar.
89+
90+
The caller takes ownership of the returned item.
91+
92+
.. note::
93+
94+
This is a low-level API call. Users are recommended to use the high-level pushMessage() API call
95+
instead.
6696
%End
97+
6798
static QgsMessageBarItem *createMessage( QWidget *widget, QWidget *parent = 0 ) /Factory/;
6899
%Docstring
69-
make out a widget containing title and message to be displayed on the bar
100+
Creates message bar item widget containing a custom ``widget`` to be displayed on the bar.
101+
102+
The caller takes ownership of the returned item.
103+
104+
.. note::
105+
106+
This is a low-level API call. Users are recommended to use the high-level pushWidget() API call
107+
instead.
70108
%End
71109

72110
void pushMessage( const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
73111
%Docstring
74-
convenience method for pushing a message to the bar
112+
A convenience method for pushing a message with the specified ``text`` to the bar.
113+
114+
The ``level`` argument specifies the desired message level (severity) of the message, which controls
115+
how the message bar is styled.
116+
117+
The optional ``duration`` argument can be used to specify the message timeout in seconds. If ``duration``
118+
is set to 0, then the message must be manually dismissed by the user.
75119
%End
120+
76121
void pushMessage( const QString &title, const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
77122
%Docstring
78-
convenience method for pushing a message with title to the bar
123+
A convenience method for pushing a message with the specified ``title`` and ``text`` to the bar.
124+
125+
The ``level`` argument specifies the desired message level (severity) of the message, which controls
126+
how the message bar is styled.
127+
128+
The optional ``duration`` argument can be used to specify the message timeout in seconds. If ``duration``
129+
is set to 0, then the message must be manually dismissed by the user.
79130
%End
80131

81132
void pushMessage( const QString &title, const QString &text, const QString &showMore, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
82133
%Docstring
83-
convenience method for pushing a message to the bar with a detail text which be shown when pressing a "more" button
134+
A convenience method for pushing a message with the specified ``title`` and ``text`` to the bar. Additional
135+
message content specified via ``showMore`` will be shown when the user presses a "more" button.
136+
137+
The ``level`` argument specifies the desired message level (severity) of the message, which controls
138+
how the message bar is styled.
139+
140+
The optional ``duration`` argument can be used to specify the message timeout in seconds. If ``duration``
141+
is set to 0, then the message must be manually dismissed by the user.
84142
%End
85143

86144
QgsMessageBarItem *currentItem();
145+
%Docstring
146+
Returns the current visible item, or ``None`` if no item is shown.
147+
%End
87148

88149
signals:
150+
89151
void widgetAdded( QgsMessageBarItem *item );
90152
%Docstring
91-
emitted when a message widget is added to the bar
153+
Emitted whenever an ``item`` is added to the bar.
92154
%End
93155

94156
void widgetRemoved( QgsMessageBarItem *item );
95157
%Docstring
96-
emitted when a message widget was removed from the bar
158+
Emitted whenever an ``item`` was removed from the bar.
97159
%End
98160

99161
public slots:
100162

101163
bool popWidget();
102164
%Docstring
103-
Remove the currently displayed widget from the bar and
104-
display the next in the stack if any or hide the bar.
165+
Remove the currently displayed item from the bar and display the next item
166+
in the stack. If no remaining items are present, the bar will be hidden.
105167

106168
:return: ``True`` if the widget was removed, ``False`` otherwise
107169
%End
108170

109171
bool clearWidgets();
110172
%Docstring
111-
Remove all items from the bar's widget list
173+
Removes all items from the bar.
112174

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

116178
void pushSuccess( const QString &title, const QString &message );
117179
%Docstring
118-
Pushes a success message with default timeout to the message bar
180+
Pushes a success ``message`` with default timeout to the message bar.
119181

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

126188
void pushInfo( const QString &title, const QString &message );
127189
%Docstring
128-
Pushes a information message with default timeout to the message bar
190+
Pushes a information ``message`` with default timeout to the message bar.
129191

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

136198
void pushWarning( const QString &title, const QString &message );
137199
%Docstring
138-
Pushes a warning with default timeout to the message bar
200+
Pushes a warning ``message`` with default timeout to the message bar.
139201

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

146208
void pushCritical( const QString &title, const QString &message );
147209
%Docstring
148-
Pushes a critical warning with default timeout to the message bar
210+
Pushes a critical warning ``message`` with default timeout to the message bar.
149211

150212
:param title: title string for message
151213
:param message: The message to be displayed

‎python/gui/auto_generated/qgsmessagebaritem.sip.in

Lines changed: 87 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,76 +12,155 @@
1212

1313
class QgsMessageBarItem : QWidget
1414
{
15+
%Docstring
16+
Represents an item shown within a QgsMessageBar widget.
17+
18+
QgsMessageBarItem represents a single item (or message) which can be shown in a QgsMessageBar widget.
19+
%End
1520

1621
%TypeHeaderCode
1722
#include "qgsmessagebaritem.h"
1823
%End
1924
public:
25+
2026
QgsMessageBarItem( const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
2127
%Docstring
22-
make out a widget containing a message to be displayed on the bar
28+
Constructor for QgsMessageBarItem, containing a message with the specified ``text`` to be displayed on the bar.
29+
30+
The ``level`` argument specifies the desired message level (severity) of the message, which controls
31+
how the message bar is styled when the item is displayed.
32+
33+
The optional ``duration`` argument can be used to specify the message timeout in seconds. If ``duration``
34+
is set to 0, then the message must be manually dismissed by the user.
2335
%End
2436

2537
QgsMessageBarItem( const QString &title, const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
2638
%Docstring
27-
make out a widget containing title and message to be displayed on the bar
39+
Constructor for QgsMessageBarItem, containing a ``title`` and message with the specified ``text`` to be displayed on the bar.
40+
41+
The ``level`` argument specifies the desired message level (severity) of the message, which controls
42+
how the message bar is styled when the item is displayed.
43+
44+
The optional ``duration`` argument can be used to specify the message timeout in seconds. If ``duration``
45+
is set to 0, then the message must be manually dismissed by the user.
2846
%End
2947

3048
QgsMessageBarItem( const QString &title, const QString &text, QWidget *widget, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
3149
%Docstring
32-
make out a widget containing title, message and widget to be displayed on the bar
50+
Constructor for QgsMessageBarItem, containing a \title, message with the specified ``text``, and a custom ``widget`` to be displayed on the bar.
51+
52+
The ``level`` argument specifies the desired message level (severity) of the message, which controls
53+
how the message bar is styled when the item is displayed.
54+
55+
The optional ``duration`` argument can be used to specify the message timeout in seconds. If ``duration``
56+
is set to 0, then the message must be manually dismissed by the user.
3357
%End
3458

3559
QgsMessageBarItem( QWidget *widget, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent /TransferThis/ = 0 );
3660
%Docstring
37-
make out a widget containing a widget to be displayed on the bar
61+
Constructor for QgsMessageBarItem, containing a custom ``widget`` to be displayed on the bar.
62+
63+
The ``level`` argument specifies the desired message level (severity) of the message, which controls
64+
how the message bar is styled when the item is displayed.
65+
66+
The optional ``duration`` argument can be used to specify the message timeout in seconds. If ``duration``
67+
is set to 0, then the message must be manually dismissed by the user.
3868
%End
3969

4070
QgsMessageBarItem *setText( const QString &text );
71+
%Docstring
72+
Sets the message ``text`` to show in the item.
73+
74+
.. seealso:: :py:func:`text`
75+
%End
4176

4277
QString text() const;
4378
%Docstring
4479
Returns the text for the message.
80+
81+
.. seealso:: :py:func:`setText`
4582
%End
4683

4784
QgsMessageBarItem *setTitle( const QString &title );
85+
%Docstring
86+
Sets the ``title`` for in the item.
87+
88+
.. seealso:: :py:func:`title`
89+
%End
4890

4991
QString title() const;
5092
%Docstring
5193
Returns the title for the message.
94+
95+
.. seealso:: :py:func:`setTitle`
5296
%End
5397

5498
QgsMessageBarItem *setLevel( Qgis::MessageLevel level );
99+
%Docstring
100+
Sets the message ``level`` for the item, which controls how the message bar is styled
101+
when the item is displayed.
102+
103+
.. seealso:: :py:func:`level`
104+
%End
55105

56106
Qgis::MessageLevel level() const;
57107
%Docstring
58108
Returns the message level for the message.
109+
110+
.. seealso:: :py:func:`setLevel`
59111
%End
60112

61113
QgsMessageBarItem *setWidget( QWidget *widget );
114+
%Docstring
115+
Sets a custom ``widget`` to show in the item.
116+
117+
.. seealso:: :py:func:`widget`
118+
%End
62119

63120
QWidget *widget() const;
64121
%Docstring
65122
Returns the widget for the message.
123+
124+
.. seealso:: :py:func:`setWidget`
66125
%End
67126

68127
QgsMessageBarItem *setIcon( const QIcon &icon );
128+
%Docstring
129+
Sets the ``icon`` associated with the message.
130+
131+
.. seealso:: :py:func:`icon`
132+
%End
69133

70134
QIcon icon() const;
71135
%Docstring
72136
Returns the icon for the message.
137+
138+
.. seealso:: :py:func:`setIcon`
73139
%End
74140

75141
QgsMessageBarItem *setDuration( int duration );
142+
%Docstring
143+
Sets the ``duration`` (in seconds) to show the message for. If ``duration``
144+
is 0 then the message will not automatically timeout and instead must be
145+
manually dismissed by the user.
146+
147+
.. seealso:: :py:func:`duration`
148+
%End
76149

77150
int duration() const;
78151
%Docstring
79-
returns the duration in second of the message
152+
Returns the duration (in seconds) of the message.
153+
154+
If the duration is 0 then the message will not automatically timeout and instead must be
155+
manually dismissed by the user.
156+
157+
.. seealso:: :py:func:`setDuration`
80158
%End
81159

82160
QString getStyleSheet();
83161
%Docstring
84-
returns the styleSheet
162+
Returns the styleSheet which should be used to style a QgsMessageBar object when
163+
this item is displayed.
85164
%End
86165

87166
public slots:
@@ -99,7 +178,8 @@ has no effect.
99178

100179
void styleChanged( const QString &styleSheet );
101180
%Docstring
102-
emitted when the message level has changed
181+
Emitted when the item's message level has changed and the message bar style
182+
will need to be updated as a result.
103183
%End
104184

105185
};

‎src/gui/qgsmessagebar.cpp

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,11 @@ void QgsMessageBar::pushMessage( const QString &title, const QString &text, cons
350350
pushItem( item );
351351
}
352352

353+
QgsMessageBarItem *QgsMessageBar::currentItem()
354+
{
355+
return mItems.value( 0 );
356+
}
357+
353358
QgsMessageBarItem *QgsMessageBar::createMessage( const QString &text, QWidget *parent )
354359
{
355360
QgsMessageBarItem *item = new QgsMessageBarItem( text, Qgis::Info, 0, parent );
@@ -366,6 +371,11 @@ QgsMessageBarItem *QgsMessageBar::createMessage( QWidget *widget, QWidget *paren
366371
return new QgsMessageBarItem( widget, Qgis::Info, 0, parent );
367372
}
368373

374+
void QgsMessageBar::pushMessage( const QString &text, Qgis::MessageLevel level, int duration )
375+
{
376+
pushMessage( QString(), text, level, duration );
377+
}
378+
369379
void QgsMessageBar::updateCountdown()
370380
{
371381
if ( !mCountdownTimer->isActive() )

‎src/gui/qgsmessagebar.h

Lines changed: 113 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,21 @@ class QgsMessageBarItem;
4141
/**
4242
* \ingroup gui
4343
* A bar for displaying non-blocking messages to the user.
44+
*
45+
* QgsMessageBar is a reusable widget which allows for providing feedback to users in
46+
* a non-intrusive way. Messages are shown in a horizontal bar widget, which is styled
47+
* automatically to reflect the severity ("message level") of the displayed message (e.g.
48+
* warning messages are styled in an orange color scheme, critical errors are shown in
49+
* red, etc).
50+
*
51+
* The message bar supports automatic stacking of multiple messages, so that
52+
* only the most recent message is shown to users. Users can then manually dismiss
53+
* individual messages to remove them from the stack, causing the next-most-recent
54+
* message to be shown. If no messages are available to show then the message bar
55+
* automatically hides.
56+
*
57+
* The class also supports pushing custom widgets to the notification stack via
58+
* the pushWidget() method.
4459
*/
4560
class GUI_EXPORT QgsMessageBar: public QFrame
4661
{
@@ -52,98 +67,167 @@ class GUI_EXPORT QgsMessageBar: public QFrame
5267
QgsMessageBar( QWidget *parent SIP_TRANSFERTHIS = nullptr );
5368

5469
/**
55-
* Display a message item on the bar after hiding the currently visible one
70+
* Display a message \a item on the bar, after hiding the currently visible one
5671
* and putting it in a stack.
57-
* The message bar will take ownership of the item.
5872
*
59-
* \param item Item to display
73+
* The message bar will take ownership of \a item.
6074
*/
6175
void pushItem( QgsMessageBarItem *item SIP_TRANSFER );
6276

6377
/**
64-
* Display a widget as a message on the bar after hiding the currently visible one
65-
* and putting it in a stack.
78+
* Display a \a widget as a message on the bar, after hiding the currently visible one
79+
* and putting it in a stack.
80+
*
6681
* \param widget message widget to display
6782
* \param level is Qgis::Info, Warning, Critical or Success
68-
* \param duration timeout duration of message in seconds, 0 value indicates no timeout
83+
* \param duration timeout duration of message in seconds, 0 value indicates no timeout (i.e.
84+
* the message must be manually cleared by the user).
6985
*/
7086
QgsMessageBarItem *pushWidget( QWidget *widget SIP_TRANSFER, Qgis::MessageLevel level = Qgis::Info, int duration = 0 );
7187

7288
/**
73-
* Remove the passed widget from the bar (if previously added),
74-
* then display the next one in the stack if any or hide the bar
75-
* \param item item to remove
76-
* \returns TRUE if the widget was removed, FALSE otherwise
89+
* Remove the specified \a item from the bar, and display the next most recent one in the stack.
90+
* If no messages remain in the stack, then the bar will be hidden.
91+
*
92+
* \param item previously added item to remove.
93+
* \returns TRUE if \a item was removed, FALSE otherwise
7794
*/
7895
bool popWidget( QgsMessageBarItem *item );
7996

80-
//! make out a widget containing a message to be displayed on the bar
97+
/**
98+
* Creates message bar item widget containing a message \a text to be displayed on the bar.
99+
*
100+
* The caller takes ownership of the returned item.
101+
*
102+
* \note This is a low-level API call. Users are recommended to use the high-level pushMessage() API call
103+
* instead.
104+
*/
81105
static QgsMessageBarItem *createMessage( const QString &text, QWidget *parent = nullptr ) SIP_FACTORY;
82-
//! make out a widget containing title and message to be displayed on the bar
106+
107+
/**
108+
* Creates message bar item widget containing a \a title and message \a text to be displayed on the bar.
109+
*
110+
* The caller takes ownership of the returned item.
111+
*
112+
* \note This is a low-level API call. Users are recommended to use the high-level pushMessage() API call
113+
* instead.
114+
*/
83115
static QgsMessageBarItem *createMessage( const QString &title, const QString &text, QWidget *parent = nullptr ) SIP_FACTORY;
84-
//! make out a widget containing title and message to be displayed on the bar
116+
117+
/**
118+
* Creates message bar item widget containing a custom \a widget to be displayed on the bar.
119+
*
120+
* The caller takes ownership of the returned item.
121+
*
122+
* \note This is a low-level API call. Users are recommended to use the high-level pushWidget() API call
123+
* instead.
124+
*/
85125
static QgsMessageBarItem *createMessage( QWidget *widget, QWidget *parent = nullptr ) SIP_FACTORY;
86126

87-
//! convenience method for pushing a message to the bar
88-
void pushMessage( const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 5 ) { pushMessage( QString(), text, level, duration ); }
89-
//! convenience method for pushing a message with title to the bar
127+
/**
128+
* A convenience method for pushing a message with the specified \a text to the bar.
129+
*
130+
* The \a level argument specifies the desired message level (severity) of the message, which controls
131+
* how the message bar is styled.
132+
*
133+
* The optional \a duration argument can be used to specify the message timeout in seconds. If \a duration
134+
* is set to 0, then the message must be manually dismissed by the user.
135+
*/
136+
void pushMessage( const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
137+
138+
/**
139+
* A convenience method for pushing a message with the specified \a title and \a text to the bar.
140+
*
141+
* The \a level argument specifies the desired message level (severity) of the message, which controls
142+
* how the message bar is styled.
143+
*
144+
* The optional \a duration argument can be used to specify the message timeout in seconds. If \a duration
145+
* is set to 0, then the message must be manually dismissed by the user.
146+
*/
90147
void pushMessage( const QString &title, const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
91148

92-
//! convenience method for pushing a message to the bar with a detail text which be shown when pressing a "more" button
149+
/**
150+
* A convenience method for pushing a message with the specified \a title and \a text to the bar. Additional
151+
* message content specified via \a showMore will be shown when the user presses a "more" button.
152+
*
153+
* The \a level argument specifies the desired message level (severity) of the message, which controls
154+
* how the message bar is styled.
155+
*
156+
* The optional \a duration argument can be used to specify the message timeout in seconds. If \a duration
157+
* is set to 0, then the message must be manually dismissed by the user.
158+
*/
93159
void pushMessage( const QString &title, const QString &text, const QString &showMore, Qgis::MessageLevel level = Qgis::Info, int duration = 5 );
94160

95-
QgsMessageBarItem *currentItem() { return mItems.value( 0 ); }
161+
/**
162+
* Returns the current visible item, or NULLPTR if no item is shown.
163+
*/
164+
QgsMessageBarItem *currentItem();
96165

97166
signals:
98-
//! emitted when a message widget is added to the bar
167+
168+
/**
169+
* Emitted whenever an \a item is added to the bar.
170+
*/
99171
void widgetAdded( QgsMessageBarItem *item );
100172

101-
//! emitted when a message widget was removed from the bar
173+
/**
174+
* Emitted whenever an \a item was removed from the bar.
175+
*/
102176
void widgetRemoved( QgsMessageBarItem *item );
103177

104178
public slots:
105179

106180
/**
107-
* Remove the currently displayed widget from the bar and
108-
* display the next in the stack if any or hide the bar.
109-
* \returns TRUE if the widget was removed, FALSE otherwise
181+
* Remove the currently displayed item from the bar and display the next item
182+
* in the stack. If no remaining items are present, the bar will be hidden.
183+
*
184+
* \returns TRUE if the widget was removed, FALSE otherwise
110185
*/
111186
bool popWidget();
112187

113188
/**
114-
* Remove all items from the bar's widget list
115-
* \returns TRUE if all items were removed, FALSE otherwise
189+
* Removes all items from the bar.
190+
*
191+
* \returns TRUE if all items were removed, FALSE otherwise
116192
*/
117193
bool clearWidgets();
118194

119195
/**
120-
* Pushes a success message with default timeout to the message bar
196+
* Pushes a success \a message with default timeout to the message bar.
197+
*
121198
* \param title title string for message
122199
* \param message The message to be displayed
200+
*
123201
* \since QGIS 2.8
124202
*/
125203
void pushSuccess( const QString &title, const QString &message );
126204

127205
/**
128-
* Pushes a information message with default timeout to the message bar
206+
* Pushes a information \a message with default timeout to the message bar.
207+
*
129208
* \param title title string for message
130209
* \param message The message to be displayed
210+
*
131211
* \since QGIS 2.8
132212
*/
133213
void pushInfo( const QString &title, const QString &message );
134214

135215
/**
136-
* Pushes a warning with default timeout to the message bar
216+
* Pushes a warning \a message with default timeout to the message bar.
217+
*
137218
* \param title title string for message
138219
* \param message The message to be displayed
220+
*
139221
* \since QGIS 2.8
140222
*/
141223
void pushWarning( const QString &title, const QString &message );
142224

143225
/**
144-
* Pushes a critical warning with default timeout to the message bar
226+
* Pushes a critical warning \a message with default timeout to the message bar.
227+
*
145228
* \param title title string for message
146229
* \param message The message to be displayed
230+
*
147231
* \since QGIS 2.8
148232
*/
149233
void pushCritical( const QString &title, const QString &message );

‎src/gui/qgsmessagebaritem.h

Lines changed: 100 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,9 @@
1414
* (at your option) any later version. *
1515
* *
1616
***************************************************************************/
17-
#ifndef qgsmessagebaritem_H
18-
#define qgsmessagebaritem_H
17+
#ifndef QGSMESSAGEBARITEM_H
18+
#define QGSMESSAGEBARITEM_H
1919

20-
#include "qgsmessagebaritem.h"
2120
#include "qgis.h"
2221

2322
#include <QWidget>
@@ -32,64 +31,153 @@ class QgsMessageBar;
3231
/**
3332
* \ingroup gui
3433
* \class QgsMessageBarItem
34+
* Represents an item shown within a QgsMessageBar widget.
35+
*
36+
* QgsMessageBarItem represents a single item (or message) which can be shown in a QgsMessageBar widget.
3537
*/
3638
class GUI_EXPORT QgsMessageBarItem : public QWidget
3739
{
3840
Q_OBJECT
3941
public:
40-
//! make out a widget containing a message to be displayed on the bar
42+
43+
/**
44+
* Constructor for QgsMessageBarItem, containing a message with the specified \a text to be displayed on the bar.
45+
*
46+
* The \a level argument specifies the desired message level (severity) of the message, which controls
47+
* how the message bar is styled when the item is displayed.
48+
*
49+
* The optional \a duration argument can be used to specify the message timeout in seconds. If \a duration
50+
* is set to 0, then the message must be manually dismissed by the user.
51+
*/
4152
QgsMessageBarItem( const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent SIP_TRANSFERTHIS = nullptr );
4253

43-
//! make out a widget containing title and message to be displayed on the bar
54+
/**
55+
* Constructor for QgsMessageBarItem, containing a \a title and message with the specified \a text to be displayed on the bar.
56+
*
57+
* The \a level argument specifies the desired message level (severity) of the message, which controls
58+
* how the message bar is styled when the item is displayed.
59+
*
60+
* The optional \a duration argument can be used to specify the message timeout in seconds. If \a duration
61+
* is set to 0, then the message must be manually dismissed by the user.
62+
*/
4463
QgsMessageBarItem( const QString &title, const QString &text, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent SIP_TRANSFERTHIS = nullptr );
4564

46-
//! make out a widget containing title, message and widget to be displayed on the bar
65+
/**
66+
* Constructor for QgsMessageBarItem, containing a \title, message with the specified \a text, and a custom \a widget to be displayed on the bar.
67+
*
68+
* The \a level argument specifies the desired message level (severity) of the message, which controls
69+
* how the message bar is styled when the item is displayed.
70+
*
71+
* The optional \a duration argument can be used to specify the message timeout in seconds. If \a duration
72+
* is set to 0, then the message must be manually dismissed by the user.
73+
*/
4774
QgsMessageBarItem( const QString &title, const QString &text, QWidget *widget, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent SIP_TRANSFERTHIS = nullptr );
4875

49-
//! make out a widget containing a widget to be displayed on the bar
76+
/**
77+
* Constructor for QgsMessageBarItem, containing a custom \a widget to be displayed on the bar.
78+
*
79+
* The \a level argument specifies the desired message level (severity) of the message, which controls
80+
* how the message bar is styled when the item is displayed.
81+
*
82+
* The optional \a duration argument can be used to specify the message timeout in seconds. If \a duration
83+
* is set to 0, then the message must be manually dismissed by the user.
84+
*/
5085
QgsMessageBarItem( QWidget *widget, Qgis::MessageLevel level = Qgis::Info, int duration = 0, QWidget *parent SIP_TRANSFERTHIS = nullptr );
5186

87+
/**
88+
* Sets the message \a text to show in the item.
89+
*
90+
* \see text()
91+
*/
5292
QgsMessageBarItem *setText( const QString &text );
5393

5494
/**
5595
* Returns the text for the message.
96+
*
97+
* \see setText()
5698
*/
5799
QString text() const;
58100

101+
/**
102+
* Sets the \a title for in the item.
103+
*
104+
* \see title()
105+
*/
59106
QgsMessageBarItem *setTitle( const QString &title );
60107

61108
/**
62109
* Returns the title for the message.
110+
*
111+
* \see setTitle()
63112
*/
64113
QString title() const;
65114

115+
/**
116+
* Sets the message \a level for the item, which controls how the message bar is styled
117+
* when the item is displayed.
118+
*
119+
* \see level()
120+
*/
66121
QgsMessageBarItem *setLevel( Qgis::MessageLevel level );
67122

68123
/**
69124
* Returns the message level for the message.
125+
*
126+
* \see setLevel()
70127
*/
71128
Qgis::MessageLevel level() const;
72129

130+
/**
131+
* Sets a custom \a widget to show in the item.
132+
*
133+
* \see widget()
134+
*/
73135
QgsMessageBarItem *setWidget( QWidget *widget );
74136

75137
/**
76138
* Returns the widget for the message.
139+
*
140+
* \see setWidget()
77141
*/
78142
QWidget *widget() const;
79143

144+
/**
145+
* Sets the \a icon associated with the message.
146+
*
147+
* \see icon()
148+
*/
80149
QgsMessageBarItem *setIcon( const QIcon &icon );
81150

82151
/**
83152
* Returns the icon for the message.
153+
*
154+
* \see setIcon()
84155
*/
85156
QIcon icon() const;
86157

158+
/**
159+
* Sets the \a duration (in seconds) to show the message for. If \a duration
160+
* is 0 then the message will not automatically timeout and instead must be
161+
* manually dismissed by the user.
162+
*
163+
* \see duration()
164+
*/
87165
QgsMessageBarItem *setDuration( int duration );
88166

89-
//! returns the duration in second of the message
167+
/**
168+
* Returns the duration (in seconds) of the message.
169+
*
170+
* If the duration is 0 then the message will not automatically timeout and instead must be
171+
* manually dismissed by the user.
172+
*
173+
* \see setDuration()
174+
*/
90175
int duration() const { return mDuration; }
91176

92-
//! returns the styleSheet
177+
/**
178+
* Returns the styleSheet which should be used to style a QgsMessageBar object when
179+
* this item is displayed.
180+
*/
93181
QString getStyleSheet() { return mStyleSheet; }
94182

95183
public slots:
@@ -106,7 +194,8 @@ class GUI_EXPORT QgsMessageBarItem : public QWidget
106194
signals:
107195

108196
/**
109-
* emitted when the message level has changed
197+
* Emitted when the item's message level has changed and the message bar style
198+
* will need to be updated as a result.
110199
*/
111200
void styleChanged( const QString &styleSheet );
112201

@@ -132,4 +221,4 @@ class GUI_EXPORT QgsMessageBarItem : public QWidget
132221
friend class QgsMessageBar;
133222
};
134223

135-
#endif // qgsmessagebaritem_H
224+
#endif // QGSMESSAGEBARITEM_H

0 commit comments

Comments
 (0)
Please sign in to comment.