+/////////////////////////////////////////////////////////////////////////////
+// Name: wx/infobar.h
+// Purpose: interface of wxInfoBar
+// Author: Vadim Zeitlin
+// RCS-ID: $Id$
+// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
+// Licence: wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+ An info bar is a transient window shown at top or bottom of its parent
+ window to display non-critical information to the user.
+
+ This class provides another way to show messages to the user, intermediate
+ between message boxes and status bar messages. The message boxes are modal
+ and thus interrupt the users work flow and should be used sparingly for
+ this reason. However status bar messages are often too easy not to notice
+ at all. An info bar provides a way to present the messages which has a much
+ higher chance to be noticed by the user but without being annoying.
+
+ Info bar may show an icon (on the left), text message and, optionally,
+ buttons allowing the user to react to the information presented. It always
+ has a close button at the right allowing the user to dismiss it so it isn't
+ necessary to provide a button just to close it.
+
+ wxInfoBar calls its parent wxWindow::Layout() method and assumes that it
+ will change the parent layout appropriately depending on whether the info
+ bar itself is shown or hidden. Usually this is achieved by simply using a
+ sizer for the parent window layout and adding wxInfoBar to this sizer as
+ one of the items. Considering the usual placement of the info bars,
+ normally this sizer should be a vertical wxBoxSizer and the bar its first
+ or last element so the simplest possible example of using this class would
+ be:
+ @code
+ class MyFrame : public wxFrame
+ {
+ ...
+
+ wxInfoBar *m_infoBar;
+ };
+
+ MyFrame::MyFrame()
+ {
+ ...
+ m_infoBar = new wxInfoBar(this);
+
+ wxSizer *sizer = new wxBoxSizer(wxVERTICAL);
+ sizer->Add(m_infoBar, wxSizerFlags().Expand());
+ ... add other frame controls to the sizer ...
+ SetSizer(sizer);
+ }
+
+ void MyFrame::SomeMethod()
+ {
+ m_infoBar->ShowMessage("Something happend", wxICON_INFORMATION);
+ }
+ @endcode
+
+ See the dialogs sample for more sophisticated examples.
+
+
+ Only generic implementation of this class exists currently but it is
+ planned to provide a native GTK+-based version in future wxWidgets releases
+ so avoid the use of the methods marked "generic only" for maximal
+ portability.
+
+ @library{wxadv}
+ @category{miscwnd}
+
+ @see wxStatusBar, wxMessageDialog
+
+ @since 2.9.1
+*/
+class wxInfoBar : public wxWindow
+{
+public:
+ /**
+ Default constructor.
+
+ Use Create() for the objects created using this constructor.
+ */
+ wxInfoBar();
+
+ /**
+ Constructor creating the info bar window.
+
+ @see Create()
+ */
+ wxInfoBar(wxWindow *parent, wxWindowID winid = wxID_ANY);
+
+ /**
+ Create the info bar window.
+
+ Notice that unlike most of the other wxWindow-derived classes,
+ wxInfoBar is created hidden and is only shown when ShowMessage() is
+ called. This is more convenient as usually the info bar is created to
+ be shown at some later time and not immediately and so creating it
+ hidden avoids the need to call Hide() explicitly from the code using
+ it.
+
+ This should be only called if the object was created using its default
+ constructor.
+
+ @param parent
+ A valid parent window pointer.
+ @param winid
+ The id of the info bar window, usually unused as currently no
+ events are generated by this class.
+ */
+ wxInfoBar(wxWindow *parent, wxWindowID winid = wxID_ANY);
+
+ /**
+ Add a button to be shown in the info bar.
+
+ The button added by this method will be shown to the right of the text
+ (in LTR layout), with each successive button being added to the right
+ of the previous one.
+
+ Clicking the button will generate a normal event which can be handled
+ as usual. Notice that if you wish the info bar to be hidden when the
+ button is clicked, simply call @c event.Skip() in the button handler to
+ let the base class handler do it.
+
+ @param btnid
+ Id of the button. It will be used in the button message clicking
+ this button will generate.
+ @param label
+ The label of the button. It may only be empty if @a btnid is one of
+ the stock ids in which case the corresponding stock label (see
+ wxGetStockLabel()) will be used.
+ */
+ void AddButton(wxWindowID btnid, const wxString& label = wxString());
+
+ /**
+ Show a message in the bar.
+
+ If the bar is currently hidden, it will be shown. Otherwise its message
+ will be updated in place.
+
+ @param msg
+ The text of the message.
+ @param flags
+ One of wxICON_NONE (default), wxICON_INFORMATION, wxICON_QUESTION,
+ wxICON_WARNING or wxICON_ERROR values. These flags have the same
+ meaning as in wxMessageDialog, i.e. show the corresponding icon in
+ the bar.
+ */
+ void ShowMessage(const wxString& msg, int flags = wxICON_NONE);
+
+ /**
+ @name Generic version customization methods.
+
+ All these methods exist in the generic version of the class only.
+
+ The generic version uses wxWindow::ShowWithEffect() function to
+ progressively show it on the platforms which support it. The methods
+ here allow to change the default effect used (or disable it entirely)
+ and change its duration.
+ */
+ //@{
+
+ /**
+ Set the effects to use when showing and hiding the bar.
+
+ Either or both of the parameters can be set to wxSHOW_EFFECT_NONE to
+ disable using effects entirely.
+
+ Notice that if you place the bar at the bottom of the window you should
+ reverse the effects used for showing and hiding for better appearance.
+
+ @param showEffect
+ The effect to use when showing the bar. By default,
+ wxSHOW_EFFECT_SLIDE_TO_BOTTOM which is appropriate for the bars
+ placed at the top of the window.
+ @param hideEffect
+ The effect to use when hiding the bar. By default,
+ wxSHOW_EFFECT_SLIDE_TO_TOP which is appropriate for the bars placed
+ at the top of the window.
+ */
+ void SetShowHideEffects(wxShowEffect showEffect, wxShowEffect hideEffect);
+
+ /// Return the effect currently used for showing the bar.
+ wxShowEffect GetShowEffect() const;
+
+ /// Return the effect currently used for hiding the bar.
+ wxShowEffect GetHideEffect() const;
+
+ /**
+ Set the duration of the animation used when showing or hiding the bar.
+
+ By default, 500ms duration is used.
+
+ @param duration
+ Duration of the animation, in milliseconds.
+ */
+ void SetEffectDuration(int duration);
+
+ /// Return the effect animation duration currently used.
+ int GetEffectDuration() const;
+
+ /**
+ Overridden base class methods changes the font of the text message.
+
+ wxInfoBar overrides this method to use the font passed to it for its
+ text message part. By default a larger and bold version of the standard
+ font is used.
+
+ This method is generic-only.
+ */
+ virtual bool SetFont(const wxFont& font);
+
+ //@}
+};
projects / wxWidgets.git / commitdiff
