1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxInfoBar
4 // Author: Vadim Zeitlin
6 // Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
7 // Licence: wxWindows license
8 /////////////////////////////////////////////////////////////////////////////
11 An info bar is a transient window shown at top or bottom of its parent
12 window to display non-critical information to the user.
14 This class provides another way to show messages to the user, intermediate
15 between message boxes and status bar messages. The message boxes are modal
16 and thus interrupt the users work flow and should be used sparingly for
17 this reason. However status bar messages are often too easy not to notice
18 at all. An info bar provides a way to present the messages which has a much
19 higher chance to be noticed by the user but without being annoying.
21 Info bar may show an icon (on the left), text message and, optionally,
22 buttons allowing the user to react to the information presented. It always
23 has a close button at the right allowing the user to dismiss it so it isn't
24 necessary to provide a button just to close it.
26 wxInfoBar calls its parent wxWindow::Layout() method and assumes that it
27 will change the parent layout appropriately depending on whether the info
28 bar itself is shown or hidden. Usually this is achieved by simply using a
29 sizer for the parent window layout and adding wxInfoBar to this sizer as
30 one of the items. Considering the usual placement of the info bars,
31 normally this sizer should be a vertical wxBoxSizer and the bar its first
32 or last element so the simplest possible example of using this class would
35 class MyFrame : public wxFrame
45 m_infoBar = new wxInfoBar(this);
47 wxSizer *sizer = new wxBoxSizer(wxVERTICAL);
48 sizer->Add(m_infoBar, wxSizerFlags().Expand());
49 ... add other frame controls to the sizer ...
53 void MyFrame::SomeMethod()
55 m_infoBar->ShowMessage("Something happend", wxICON_INFORMATION);
59 See the dialogs sample for more sophisticated examples.
62 Currently this class is implemented generically (i.e. in the same
63 platform-independent way for all ports) and also natively in wxGTK but the
64 native implementation requires a recent -- as of this writing -- GTK+ 2.18
70 @see wxStatusBar, wxMessageDialog
74 class wxInfoBar
: public wxWindow
80 Use Create() for the objects created using this constructor.
85 Constructor creating the info bar window.
89 wxInfoBar(wxWindow
*parent
, wxWindowID winid
= wxID_ANY
);
92 Create the info bar window.
94 Notice that unlike most of the other wxWindow-derived classes,
95 wxInfoBar is created hidden and is only shown when ShowMessage() is
96 called. This is more convenient as usually the info bar is created to
97 be shown at some later time and not immediately and so creating it
98 hidden avoids the need to call Hide() explicitly from the code using
101 This should be only called if the object was created using its default
105 A valid parent window pointer.
107 The id of the info bar window, usually unused as currently no
108 events are generated by this class.
110 wxInfoBar(wxWindow
*parent
, wxWindowID winid
= wxID_ANY
);
113 Add a button to be shown in the info bar.
115 The button added by this method will be shown to the right of the text
116 (in LTR layout), with each successive button being added to the right
119 Clicking the button will generate a normal event which can be handled
120 as usual. Notice that if you wish the info bar to be hidden when the
121 button is clicked, simply call @c event.Skip() in the button handler to
122 let the base class handler do it.
125 Id of the button. It will be used in the button message clicking
126 this button will generate.
128 The label of the button. It may only be empty if @a btnid is one of
129 the stock ids in which case the corresponding stock label (see
130 wxGetStockLabel()) will be used.
132 void AddButton(wxWindowID btnid
, const wxString
& label
= wxString());
135 Remove a button previously added by AddButton().
138 Id of the button to remove. If more than one button with the same
139 id is used in the info bar (which is in any case not recommended),
140 the last, i.e. most recently added, button with this id is removed.
142 void RemoveButton(wxWindowID btnid
);
145 Show a message in the bar.
147 If the bar is currently hidden, it will be shown. Otherwise its message
148 will be updated in place.
151 The text of the message.
153 One of wxICON_NONE, wxICON_INFORMATION (default), wxICON_QUESTION,
154 wxICON_WARNING or wxICON_ERROR values. These flags have the same
155 meaning as in wxMessageDialog for the generic version, i.e. show
156 (or not, in case of wxICON_NONE) the corresponding icon in the bar
157 but can be interpreted by the native versions. For example, the
158 GTK+ native implementation doesn't show icons at all but uses this
159 parameter to select the appropriate background colour for the
162 void ShowMessage(const wxString
& msg
, int flags
= wxICON_NONE
);
165 @name Generic version customization methods.
167 All these methods exist in the generic version of the class only.
169 The generic version uses wxWindow::ShowWithEffect() function to
170 progressively show it on the platforms which support it (currently only
171 wxMSW). The methods here allow to change the default effect used (or
172 disable it entirely) and change its duration.
177 Set the effects to use when showing and hiding the bar.
179 Either or both of the parameters can be set to wxSHOW_EFFECT_NONE to
180 disable using effects entirely.
182 Notice that if you place the bar at the bottom of the window you should
183 reverse the effects used for showing and hiding for better appearance.
186 The effect to use when showing the bar. By default,
187 wxSHOW_EFFECT_SLIDE_TO_BOTTOM which is appropriate for the bars
188 placed at the top of the window.
190 The effect to use when hiding the bar. By default,
191 wxSHOW_EFFECT_SLIDE_TO_TOP which is appropriate for the bars placed
192 at the top of the window.
194 void SetShowHideEffects(wxShowEffect showEffect
, wxShowEffect hideEffect
);
196 /// Return the effect currently used for showing the bar.
197 wxShowEffect
GetShowEffect() const;
199 /// Return the effect currently used for hiding the bar.
200 wxShowEffect
GetHideEffect() const;
203 Set the duration of the animation used when showing or hiding the bar.
205 By default, 500ms duration is used.
208 Duration of the animation, in milliseconds.
210 void SetEffectDuration(int duration
);
212 /// Return the effect animation duration currently used.
213 int GetEffectDuration() const;
216 Overridden base class methods changes the font of the text message.
218 wxInfoBar overrides this method to use the font passed to it for its
219 text message part. By default a larger and bold version of the standard
222 This method is generic-only.
224 virtual bool SetFont(const wxFont
& font
);