Fix header formatting problem in wxMessageBox() documentation.

[wxWidgets.git] / interface / wx / infobar.h

diff --git a/interface/wx/infobar.h b/interface/wx/infobar.h
index 0eb6e6f0febd318666ee0311a5c2c7b96c6e3c2a..322548f14b3988b403f5b37ae2e03dcc3ff987b9 100644 (file)
--- a/interface/wx/infobar.h
+++ b/interface/wx/infobar.h
@@ -4,7 +4,7 @@
 // Author:      Vadim Zeitlin
 // RCS-ID:      $Id$
 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -64,14 +64,14 @@
     native implementation requires a recent -- as of this writing -- GTK+ 2.18
     version.
 
-    @library{wxadv}
+    @library{wxcore}
     @category{miscwnd}
 
     @see wxStatusBar, wxMessageDialog
 
     @since 2.9.1
 */
-class wxInfoBar : public wxWindow
+class wxInfoBar : public wxControl
 {
 public:
     /**
@@ -107,19 +107,32 @@ public:
             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);
+    bool Create(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.
+        of the previous one. If any buttons are added to the info bar using
+        this method, the default "Close" button is not shown as it is assumed
+        that the extra buttons already allow the user to close it.
+
+        Clicking the button will generate a normal EVT_COMMAND_BUTTON_CLICKED
+        event which can be handled as usual. The default handler in wxInfoBar
+        itself closes the window whenever a button in it is clicked so 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 (calling Dismiss() explicitly works too, of course). On the other
+        hand, if you don't skip the event, the info bar will remain opened so
+        make sure to do it for at least some buttons to allow the user to close
+        it.
 
-        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.
+        Notice that the generic wxInfoBar implementation handles the button
+        events itself and so they are not propagated to the info bar parent and
+        you need to either inherit from wxInfoBar and handle them in your
+        derived class or use wxEvtHandler::Connect(), as is done in the dialogs
+        sample, to handle the button events in the parent frame.
 
         @param btnid
             Id of the button. It will be used in the button message clicking
@@ -131,6 +144,24 @@ public:
      */
     void AddButton(wxWindowID btnid, const wxString& label = wxString());
 
+    /**
+        Hide the info bar window.
+
+        This method hides the window and lays out the parent window to account
+        for its disappearance (unlike a simple Hide()).
+     */
+    void Dismiss();
+
+    /**
+        Remove a button previously added by AddButton().
+
+        @param btnid
+            Id of the button to remove. If more than one button with the same
+            id is used in the info bar (which is in any case not recommended),
+            the last, i.e. most recently added, button with this id is removed.
+     */
+    void RemoveButton(wxWindowID btnid);
+
     /**
         Show a message in the bar.
 
@@ -169,17 +200,17 @@ public:
         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.
+        By default, the info bar uses wxSHOW_EFFECT_SLIDE_TO_BOTTOM effect for
+        showing itself and wxSHOW_EFFECT_SLIDE_TO_TOP for hiding if it is the
+        first element of the containing sizer and reverse effects if it's the
+        last one. If it is neither the first nor the last element, no effect is
+        used to avoid the use of an inappropriate one and this function must be
+        called if an effect is desired.
 
         @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.
+            The effect to use when showing the bar.
         @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.
+            The effect to use when hiding the bar.
      */
     void SetShowHideEffects(wxShowEffect showEffect, wxShowEffect hideEffect);