fix push/pop mechanism after r58786; add a few notes about the stack mechanism both in the docs and in the public header (see #10733)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@60321 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/statusbr.h

@@ -105,6 +105,8 @@ public:
     // field text
     // ----------
 
+    // NOTE: even if it is not pure virtual, SetStatusText() must be overloaded by 
+    //       the derived classes to update the given text in the native control
     virtual void SetStatusText(const wxString& text, int number = 0)
         { m_panes[number].GetStack().Last() = text; }
     virtual wxString GetStatusText(int number = 0) const

interface/wx/statusbr.h

@@ -53,6 +53,9 @@ public:
     to give small amounts of status information. It can contain one or more fields,
     one or more of which can be variable length according to the size of the window.
     
+    wxStatusBar also maintains an independent stack of status texts for each field
+    (see PushStatusText() and PopStatusText()).
+
     Note that in wxStatusBar context, the terms @e pane and @e field are synonyms.
 
     @beginStyleTable
@@ -195,7 +198,7 @@ public:
     void PopStatusText(int field = 0);
 
     /**
-        Saves the current field text in a per field stack, and sets the field text
+        Saves the current field text in a per-field stack, and sets the field text
         to the string passed as argument.
 
         @see PopStatusText()
@@ -239,7 +242,11 @@ public:
     virtual void SetStatusStyles(int n, const int* styles);
 
     /**
-        Sets the text for one field.
+        Sets the status text for the @a i-th field.
+        
+        The given text will replace the current text. Note that unlike PushStatusText()
+        this function won't save the current text (and calling PopStatusText() won't
+        restore it!).
 
         @param text
             The text to be set. Use an empty string ("") to clear the field.

src/common/statbar.cpp

@@ -191,22 +191,25 @@ wxArrayInt wxStatusBarBase::CalculateAbsWidths(wxCoord widthTotal) const
 
 void wxStatusBarBase::PushStatusText(const wxString& text, int number)
 {
-    // save current status text in the stack
+    // save the new text (in non-ellipsized form) in the stack
-    m_panes[number].m_arrStack.push_back(GetStatusText(number));
+    m_panes[number].m_arrStack.push_back(text);
 
     SetStatusText(text, number);
-        // update current status text (eventually also in the native control)
+        // update current status text (which will possibly be ellipsized) 
+        // also in the native control
 }
 
 void wxStatusBarBase::PopStatusText(int number)
 {
-    wxASSERT_MSG(m_panes[number].m_arrStack.GetCount() == 1,
+    wxASSERT_MSG(m_panes[number].m_arrStack.GetCount() >= 1,
                  "can't pop any further string");
 
-    wxString text = m_panes[number].m_arrStack.back();
+    // the top of the stack is the status text currently shown in the native control;
-    m_panes[number].m_arrStack.pop_back();  // also remove it from the stack
+    // remove it
+    m_panes[number].m_arrStack.pop_back();
 
-    // restore the popped status text in the pane
+    // restore the previous status text in the native control
+    const wxString& text = m_panes[number].m_arrStack.back();
     SetStatusText(text, number);
 }