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 };