Add new sample project files.

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

diff --git a/interface/wx/infobar.h b/interface/wx/infobar.h
index 70f662b95ec2f179bf7d485cc59f7ff6bc2a1194..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>
 // Author:      Vadim Zeitlin
 // RCS-ID:      $Id$
 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -59,19 +59,19 @@
     See the dialogs sample for more sophisticated examples.
 
 
     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.
+    Currently this class is implemented generically (i.e. in the same
+    platform-independent way for all ports) and also natively in wxGTK but the
+    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
 */
     @category{miscwnd}
 
     @see wxStatusBar, wxMessageDialog
 
     @since 2.9.1
 */

-class wxInfoBar : public wxWindow
+class wxInfoBar : public wxControl

 {
 public:
     /**
 {
 public:
     /**


@@ -107,19 +107,32 @@ public:
             The id of the info bar window, usually unused as currently no
             events are generated by this class.
      */
             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
 
     /**
         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
 
         @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());
 
      */
     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.
 
     /**
         Show a message in the bar.
 


@@ -140,10 +171,14 @@ public:
         @param msg
             The text of the message.
         @param flags
         @param msg
             The text of the message.
         @param flags

-            One of wxICON_NONE (default), wxICON_INFORMATION, wxICON_QUESTION,
+            One of wxICON_NONE, wxICON_INFORMATION (default), wxICON_QUESTION,

             wxICON_WARNING or wxICON_ERROR values. These flags have the same
             wxICON_WARNING or wxICON_ERROR values. These flags have the same

-            meaning as in wxMessageDialog, i.e. show the corresponding icon in
-            the bar.
+            meaning as in wxMessageDialog for the generic version, i.e. show
+            (or not, in case of wxICON_NONE) the corresponding icon in the bar
+            but can be interpreted by the native versions. For example, the
+            GTK+ native implementation doesn't show icons at all but uses this
+            parameter to select the appropriate background colour for the
+            notification.

      */
     void ShowMessage(const wxString& msg, int flags = wxICON_NONE);
 
      */
     void ShowMessage(const wxString& msg, int flags = wxICON_NONE);
 


@@ -153,9 +188,9 @@ public:
         All these methods exist in the generic version of the class only.
 
         The generic version uses wxWindow::ShowWithEffect() function to
         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.
+        progressively show it on the platforms which support it (currently only
+        wxMSW). The methods here allow to change the default effect used (or
+        disable it entirely) and change its duration.

      */
     //@{
 
      */
     //@{
 


@@ -165,17 +200,17 @@ public:
         Either or both of the parameters can be set to wxSHOW_EFFECT_NONE to
         disable using effects entirely.
 
         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
 
         @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
         @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);
 
      */
     void SetShowHideEffects(wxShowEffect showEffect, wxShowEffect hideEffect);