]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/infobar.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / infobar.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/infobar.h
3 // Purpose: interface of wxInfoBar
4 // Author: Vadim Zeitlin
5 // Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 An info bar is a transient window shown at top or bottom of its parent
11 window to display non-critical information to the user.
12
13 This class provides another way to show messages to the user, intermediate
14 between message boxes and status bar messages. The message boxes are modal
15 and thus interrupt the users work flow and should be used sparingly for
16 this reason. However status bar messages are often too easy not to notice
17 at all. An info bar provides a way to present the messages which has a much
18 higher chance to be noticed by the user but without being annoying.
19
20 Info bar may show an icon (on the left), text message and, optionally,
21 buttons allowing the user to react to the information presented. It always
22 has a close button at the right allowing the user to dismiss it so it isn't
23 necessary to provide a button just to close it.
24
25 wxInfoBar calls its parent wxWindow::Layout() method and assumes that it
26 will change the parent layout appropriately depending on whether the info
27 bar itself is shown or hidden. Usually this is achieved by simply using a
28 sizer for the parent window layout and adding wxInfoBar to this sizer as
29 one of the items. Considering the usual placement of the info bars,
30 normally this sizer should be a vertical wxBoxSizer and the bar its first
31 or last element so the simplest possible example of using this class would
32 be:
33 @code
34 class MyFrame : public wxFrame
35 {
36 ...
37
38 wxInfoBar *m_infoBar;
39 };
40
41 MyFrame::MyFrame()
42 {
43 ...
44 m_infoBar = new wxInfoBar(this);
45
46 wxSizer *sizer = new wxBoxSizer(wxVERTICAL);
47 sizer->Add(m_infoBar, wxSizerFlags().Expand());
48 ... add other frame controls to the sizer ...
49 SetSizer(sizer);
50 }
51
52 void MyFrame::SomeMethod()
53 {
54 m_infoBar->ShowMessage("Something happened", wxICON_INFORMATION);
55 }
56 @endcode
57
58 See the dialogs sample for more sophisticated examples.
59
60
61 Currently this class is implemented generically (i.e. in the same
62 platform-independent way for all ports) and also natively in wxGTK but the
63 native implementation requires a recent -- as of this writing -- GTK+ 2.18
64 version.
65
66 @library{wxcore}
67 @category{miscwnd}
68
69 @see wxStatusBar, wxMessageDialog
70
71 @since 2.9.1
72 */
73 class wxInfoBar : public wxControl
74 {
75 public:
76 /**
77 Default constructor.
78
79 Use Create() for the objects created using this constructor.
80 */
81 wxInfoBar();
82
83 /**
84 Constructor creating the info bar window.
85
86 @see Create()
87 */
88 wxInfoBar(wxWindow *parent, wxWindowID winid = wxID_ANY);
89
90 /**
91 Create the info bar window.
92
93 Notice that unlike most of the other wxWindow-derived classes,
94 wxInfoBar is created hidden and is only shown when ShowMessage() is
95 called. This is more convenient as usually the info bar is created to
96 be shown at some later time and not immediately and so creating it
97 hidden avoids the need to call Hide() explicitly from the code using
98 it.
99
100 This should be only called if the object was created using its default
101 constructor.
102
103 @param parent
104 A valid parent window pointer.
105 @param winid
106 The id of the info bar window, usually unused as currently no
107 events are generated by this class.
108 */
109 bool Create(wxWindow *parent, wxWindowID winid = wxID_ANY);
110
111 /**
112 Add a button to be shown in the info bar.
113
114 The button added by this method will be shown to the right of the text
115 (in LTR layout), with each successive button being added to the right
116 of the previous one. If any buttons are added to the info bar using
117 this method, the default "Close" button is not shown as it is assumed
118 that the extra buttons already allow the user to close it.
119
120 Clicking the button will generate a normal EVT_COMMAND_BUTTON_CLICKED
121 event which can be handled as usual. The default handler in wxInfoBar
122 itself closes the window whenever a button in it is clicked so if you
123 wish the info bar to be hidden when the button is clicked, simply call
124 @c event.Skip() in the button handler to let the base class handler do
125 it (calling Dismiss() explicitly works too, of course). On the other
126 hand, if you don't skip the event, the info bar will remain opened so
127 make sure to do it for at least some buttons to allow the user to close
128 it.
129
130 Notice that the generic wxInfoBar implementation handles the button
131 events itself and so they are not propagated to the info bar parent and
132 you need to either inherit from wxInfoBar and handle them in your
133 derived class or use wxEvtHandler::Connect(), as is done in the dialogs
134 sample, to handle the button events in the parent frame.
135
136 @param btnid
137 Id of the button. It will be used in the button message clicking
138 this button will generate.
139 @param label
140 The label of the button. It may only be empty if @a btnid is one of
141 the stock ids in which case the corresponding stock label (see
142 wxGetStockLabel()) will be used.
143 */
144 void AddButton(wxWindowID btnid, const wxString& label = wxString());
145
146 /**
147 Hide the info bar window.
148
149 This method hides the window and lays out the parent window to account
150 for its disappearance (unlike a simple Hide()).
151 */
152 virtual void Dismiss();
153
154 /**
155 Remove a button previously added by AddButton().
156
157 @param btnid
158 Id of the button to remove. If more than one button with the same
159 id is used in the info bar (which is in any case not recommended),
160 the last, i.e. most recently added, button with this id is removed.
161 */
162 void RemoveButton(wxWindowID btnid);
163
164 /**
165 Show a message in the bar.
166
167 If the bar is currently hidden, it will be shown. Otherwise its message
168 will be updated in place.
169
170 @param msg
171 The text of the message.
172 @param flags
173 One of wxICON_NONE, wxICON_INFORMATION (default), wxICON_QUESTION,
174 wxICON_WARNING or wxICON_ERROR values. These flags have the same
175 meaning as in wxMessageDialog for the generic version, i.e. show
176 (or not, in case of wxICON_NONE) the corresponding icon in the bar
177 but can be interpreted by the native versions. For example, the
178 GTK+ native implementation doesn't show icons at all but uses this
179 parameter to select the appropriate background colour for the
180 notification.
181 */
182 void ShowMessage(const wxString& msg, int flags = wxICON_NONE);
183
184 /**
185 @name Generic version customization methods.
186
187 All these methods exist in the generic version of the class only.
188
189 The generic version uses wxWindow::ShowWithEffect() function to
190 progressively show it on the platforms which support it (currently only
191 wxMSW). The methods here allow to change the default effect used (or
192 disable it entirely) and change its duration.
193 */
194 //@{
195
196 /**
197 Set the effects to use when showing and hiding the bar.
198
199 Either or both of the parameters can be set to wxSHOW_EFFECT_NONE to
200 disable using effects entirely.
201
202 By default, the info bar uses wxSHOW_EFFECT_SLIDE_TO_BOTTOM effect for
203 showing itself and wxSHOW_EFFECT_SLIDE_TO_TOP for hiding if it is the
204 first element of the containing sizer and reverse effects if it's the
205 last one. If it is neither the first nor the last element, no effect is
206 used to avoid the use of an inappropriate one and this function must be
207 called if an effect is desired.
208
209 @param showEffect
210 The effect to use when showing the bar.
211 @param hideEffect
212 The effect to use when hiding the bar.
213 */
214 void SetShowHideEffects(wxShowEffect showEffect, wxShowEffect hideEffect);
215
216 /// Return the effect currently used for showing the bar.
217 wxShowEffect GetShowEffect() const;
218
219 /// Return the effect currently used for hiding the bar.
220 wxShowEffect GetHideEffect() const;
221
222 /**
223 Set the duration of the animation used when showing or hiding the bar.
224
225 By default, 500ms duration is used.
226
227 @param duration
228 Duration of the animation, in milliseconds.
229 */
230 void SetEffectDuration(int duration);
231
232 /// Return the effect animation duration currently used.
233 int GetEffectDuration() const;
234
235 /**
236 Overridden base class methods changes the font of the text message.
237
238 wxInfoBar overrides this method to use the font passed to it for its
239 text message part. By default a larger and bold version of the standard
240 font is used.
241
242 This method is generic-only.
243 */
244 virtual bool SetFont(const wxFont& font);
245
246 //@}
247 };