interface/wx/infobar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/infobar.h
   3 // Purpose:     interface of wxInfoBar
   4 // Author:      Vadim Zeitlin
   5 // RCS-ID:      $Id$
   6 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
   7 // Licence:     wxWindows license
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  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.
  13
  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.
  20
  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.
  25
  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
  33     be:
  34     @code
  35     class MyFrame : public wxFrame
  36     {
  37         ...
  38
  39         wxInfoBar *m_infoBar;
  40     };
  41
  42     MyFrame::MyFrame()
  43     {
  44         ...
  45         m_infoBar = new wxInfoBar(this);
  46
  47         wxSizer *sizer = new wxBoxSizer(wxVERTICAL);
  48         sizer->Add(m_infoBar, wxSizerFlags().Expand());
  49         ... add other frame controls to the sizer ...
  50         SetSizer(sizer);
  51     }
  52
  53     void MyFrame::SomeMethod()
  54     {
  55         m_infoBar->ShowMessage("Something happend", wxICON_INFORMATION);
  56     }
  57     @endcode
  58
  59     See the dialogs sample for more sophisticated examples.
  60
  61
  62     Only generic implementation of this class exists currently but it is
  63     planned to provide a native GTK+-based version in future wxWidgets releases
  64     so avoid the use of the methods marked "generic only" for maximal
  65     portability.
  66
  67     @library{wxadv}
  68     @category{miscwnd}
  69
  70     @see wxStatusBar, wxMessageDialog
  71
  72     @since 2.9.1
  73 */
  74 class wxInfoBar : public wxWindow
  75 {
  76 public:
  77     /**
  78         Default constructor.
  79
  80         Use Create() for the objects created using this constructor.
  81      */
  82     wxInfoBar();
  83
  84     /**
  85         Constructor creating the info bar window.
  86
  87         @see Create()
  88      */
  89     wxInfoBar(wxWindow *parent, wxWindowID winid = wxID_ANY);
  90
  91     /**
  92         Create the info bar window.
  93
  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
  99         it.
 100
 101         This should be only called if the object was created using its default
 102         constructor.
 103
 104         @param parent
 105             A valid parent window pointer.
 106         @param winid
 107             The id of the info bar window, usually unused as currently no
 108             events are generated by this class.
 109      */
 110     wxInfoBar(wxWindow *parent, wxWindowID winid = wxID_ANY);
 111
 112     /**
 113         Add a button to be shown in the info bar.
 114
 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
 117         of the previous one.
 118
 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.
 123
 124         @param btnid
 125             Id of the button. It will be used in the button message clicking
 126             this button will generate.
 127         @param label
 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.
 131      */
 132     void AddButton(wxWindowID btnid, const wxString& label = wxString());
 133
 134     /**
 135         Show a message in the bar.
 136
 137         If the bar is currently hidden, it will be shown. Otherwise its message
 138         will be updated in place.
 139
 140         @param msg
 141             The text of the message.
 142         @param flags
 143             One of wxICON_NONE (default), wxICON_INFORMATION, wxICON_QUESTION,
 144             wxICON_WARNING or wxICON_ERROR values. These flags have the same
 145             meaning as in wxMessageDialog, i.e. show the corresponding icon in
 146             the bar.
 147      */
 148     void ShowMessage(const wxString& msg, int flags = wxICON_NONE);
 149
 150     /**
 151         @name Generic version customization methods.
 152
 153         All these methods exist in the generic version of the class only.
 154
 155         The generic version uses wxWindow::ShowWithEffect() function to
 156         progressively show it on the platforms which support it. The methods
 157         here allow to change the default effect used (or disable it entirely)
 158         and change its duration.
 159      */
 160     //@{
 161
 162     /**
 163         Set the effects to use when showing and hiding the bar.
 164
 165         Either or both of the parameters can be set to wxSHOW_EFFECT_NONE to
 166         disable using effects entirely.
 167
 168         Notice that if you place the bar at the bottom of the window you should
 169         reverse the effects used for showing and hiding for better appearance.
 170
 171         @param showEffect
 172             The effect to use when showing the bar. By default,
 173             wxSHOW_EFFECT_SLIDE_TO_BOTTOM which is appropriate for the bars
 174             placed at the top of the window.
 175         @param hideEffect
 176             The effect to use when hiding the bar. By default,
 177             wxSHOW_EFFECT_SLIDE_TO_TOP which is appropriate for the bars placed
 178             at the top of the window.
 179      */
 180     void SetShowHideEffects(wxShowEffect showEffect, wxShowEffect hideEffect);
 181
 182     /// Return the effect currently used for showing the bar.
 183     wxShowEffect GetShowEffect() const;
 184
 185     /// Return the effect currently used for hiding the bar.
 186     wxShowEffect GetHideEffect() const;
 187
 188     /**
 189         Set the duration of the animation used when showing or hiding the bar.
 190
 191         By default, 500ms duration is used.
 192
 193         @param duration
 194             Duration of the animation, in milliseconds.
 195      */
 196     void SetEffectDuration(int duration);
 197
 198     /// Return the effect animation duration currently used.
 199     int GetEffectDuration() const;
 200
 201     /**
 202         Overridden base class methods changes the font of the text message.
 203
 204         wxInfoBar overrides this method to use the font passed to it for its
 205         text message part. By default a larger and bold version of the standard
 206         font is used.
 207
 208         This method is generic-only.
 209      */
 210     virtual bool SetFont(const wxFont& font);
 211
 212     //@}
 213 };