X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0cd159592e4d9c979aa5a626627cdd9158fcc34f..85b1997c095b18cd5e9e54e9d39feaa71c5ffa06:/interface/wx/statusbr.h

diff --git a/interface/wx/statusbr.h b/interface/wx/statusbr.h
index 1f95231b01..0b7c1b1dc7 100644
--- a/interface/wx/statusbr.h
+++ b/interface/wx/statusbr.h
@@ -6,6 +6,40 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    @class wxStatusBarPane
+
+    A status bar pane data container used by wxStatusBar.
+
+    @library{wxcore}
+    @category{data}
+
+    @see wxStatusBar
+*/
+class wxStatusBarPane
+{
+public:
+    /**
+        Constructs the pane with the given @a style and @a width.
+    */
+    wxStatusBarPane(int style = wxSB_NORMAL, size_t width = 0);
+
+    /**
+        Returns the pane width; it maybe negative, indicating a variable-width field.
+    */
+    int GetWidth() const;
+
+    /**
+        Returns the pane style.
+    */
+    int GetStyle() const;
+
+    /**
+        Returns the text currently shown in this pane.
+     */
+    wxString GetText() const;
+};
+
 /**
     @class wxStatusBar
 
@@ -13,9 +47,31 @@
     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
-    @style{wxST_SIZEGRIP}
-        Displays a gripper at the right-hand side of the status bar.
+    @style{wxSTB_SIZEGRIP}
+        Displays a gripper at the right-hand side of the status bar which can be used
+        to resize the parent window.
+    @style{wxSTB_SHOW_TIPS}
+        Displays tooltips for those panes whose status text has been ellipsized/truncated
+        because the status text doesn't fit the pane width.
+        Note that this style has effect only on wxGTK (with GTK+ >= 2.12) currently.
+    @style{wxSTB_ELLIPSIZE_START}
+        Replace the beginning of the status texts with an ellipsis when the status text
+        widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
+    @style{wxSTB_ELLIPSIZE_MIDDLE}
+        Replace the middle of the status texts with an ellipsis when the status text
+        widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
+    @style{wxSTB_ELLIPSIZE_END}
+        Replace the end of the status texts with an ellipsis when the status text
+        widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
+    @style{wxSTB_DEFAULT_STYLE}
+        The default style: includes
+        @c wxSTB_SIZEGRIP|wxSTB_SHOW_TIPS|wxSTB_ELLIPSIZE_END|wxFULL_REPAINT_ON_RESIZE.
     @endStyleTable
 
     @remarks
@@ -25,7 +81,7 @@
     @library{wxcore}
     @category{miscwnd}
 
-    @see wxFrame, @ref page_samples_statbar
+    @see wxStatusBarPane, wxFrame, @ref page_samples_statbar
 */
 class wxStatusBar : public wxWindow
 {
@@ -53,7 +109,7 @@ public:
         @see Create()
     */
     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
-                long style = wxST_SIZEGRIP,
+                long style = wxSTB_DEFAULT_STYLE,
                 const wxString& name = wxStatusBarNameStr);
 
     /**
@@ -66,7 +122,7 @@ public:
         See wxStatusBar() for details.
     */
     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
-                long style = wxST_SIZEGRIP,
+                long style = wxSTB_DEFAULT_STYLE,
                 const wxString& name = wxStatusBarNameStr);
 
     /**
@@ -79,6 +135,11 @@ public:
 
         @return @true if the field index is valid, @false otherwise.
 
+        @beginWxPerlOnly
+        In wxPerl this function returns a @c Wx::Rect if the field
+        index is valid, @c undef otherwise.
+        @endWxPerlOnly
+
         @see wxRect
     */
     virtual bool GetFieldRect(int i, wxRect& rect) const;
@@ -88,6 +149,20 @@ public:
     */
     int GetFieldsCount() const;
 
+    /**
+        Returns the wxStatusBarPane representing the @a n-th field.
+    */
+    const wxStatusBarPane& GetField(int n) const;
+
+    /**
+        Returns the horizontal and vertical borders used when rendering the field
+        text inside the field area.
+
+        Note that the rect returned by GetFieldRect() already accounts for the
+        presence of horizontal and vertical border returned by this function.
+    */
+    wxSize GetBorders() const;
+
     /**
         Returns the string associated with a status bar field.
 
@@ -102,16 +177,35 @@ public:
     virtual wxString GetStatusText(int i = 0) const;
 
     /**
-        Sets the field text to the top of the stack, and pops the stack of saved
-        strings.
+        Returns the width of the @a n-th field.
+
+        See wxStatusBarPane::GetWidth() for more info.
+    */
+    int GetStatusWidth(int n) const;
+
+    /**
+        Returns the style of the @a n-th field.
+
+        See wxStatusBarPane::GetStyle() for more info.
+    */
+    int GetStatusStyle(int n) const;
+
+    /**
+        Restores the text to the value it had before the last call to
+        PushStatusText().
+
+        Notice that if SetStatusText() had been called in the meanwhile,
+        PopStatusText() will not change the text, i.e. it does not override
+        explicit changes to status text but only restores the saved text if it
+        hadn't been changed since.
 
         @see PushStatusText()
     */
     void PopStatusText(int field = 0);
 
     /**
-        Saves the current field text in a per field stack, and sets the field text
-        to the string passed as argument.
+        Saves the current field text in a per-field stack, and sets the field
+        text to the string passed as argument.
 
         @see PopStatusText()
     */
@@ -126,6 +220,11 @@ public:
         @param widths
             An array of n integers interpreted in the same way as
             in SetStatusWidths().
+
+        @beginWxPerlOnly
+        In wxPerl this function accepts only the @a number parameter.
+        Use SetStatusWidths to set the field widths.
+        @endWxPerlOnly
     */
     virtual void SetFieldsCount(int number = 1, const int* widths = NULL);
 
@@ -145,16 +244,23 @@ public:
             The number of fields in the status bar. Must be equal to the
             number passed to SetFieldsCount() the last time it was called.
         @param styles
-            Contains an array of n integers with the styles for each field. There
-            are three possible styles:
-            - wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
-            - wxSB_FLAT: No border is painted around the field so that it appears flat.
-            - wxSB_RAISED: A raised 3D border is painted around the field.
+            Contains an array of @a n integers with the styles for each field.
+            There are three possible styles:
+            - @c wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
+            - @c wxSB_FLAT: No border is painted around the field so that it appears flat.
+            - @c wxSB_RAISED: A raised 3D border is painted around the field.
     */
     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 if PushStatusText() had been called before the new text will
+        also replace the last saved value to make sure that the next call to
+        PopStatusText() doesn't restore the old value, which was overwritten by
+        the call to this function.
 
         @param text
             The text to be set. Use an empty string ("") to clear the field.
@@ -191,6 +297,10 @@ public:
                  width of all fields, minus the sum of widths of the
                  non-variable fields, divided by the number of variable fields.
 
+        @beginWxPerlOnly
+        In wxPerl this method takes as parameters the field widths.
+        @endWxPerlOnly
+
         @see SetFieldsCount(), wxFrame::SetStatusWidths()
     */
     virtual void SetStatusWidths(int n, const int* widths_field);