]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/statusbr.h
avoid GTK+ prefixes for our tree entry code, it is not part of GTK+, should have...
[wxWidgets.git] / interface / wx / statusbr.h
index bd1eabd32614b52fab6bd80ffe0194758467417b..8070fe0c10402b42f2993763866f4196659afa4c 100644 (file)
@@ -3,16 +3,33 @@
 // Purpose:     interface of wxStatusBar
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+// wxStatusBar styles
+#define wxSTB_SIZEGRIP         0x0010
+#define wxSTB_SHOW_TIPS        0x0020
+
+#define wxSTB_ELLIPSIZE_START   0x0040
+#define wxSTB_ELLIPSIZE_MIDDLE  0x0080
+#define wxSTB_ELLIPSIZE_END     0x0100
+
+#define wxSTB_DEFAULT_STYLE    (wxSTB_SIZEGRIP|wxSTB_ELLIPSIZE_END|wxSTB_SHOW_TIPS|wxFULL_REPAINT_ON_RESIZE)
+
+// style flags for wxStatusBar fields
+#define wxSB_NORMAL    0x0000
+#define wxSB_FLAT      0x0001
+#define wxSB_RAISED    0x0002
+#define wxSB_SUNKEN    0x0003
+
+
 /**
     @class wxStatusBarPane
-    
+
     A status bar pane data container used by wxStatusBar.
 
     @library{wxcore}
-    @category{miscwnd}
+    @category{data}
 
     @see wxStatusBar
 */
@@ -23,28 +40,21 @@ 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 stack of strings pushed on this pane.
-        
-        Note that this stack does include also the string currently displayed in this pane
-        as the version stored in the native status bar control is possibly ellipsized.
-        
-        Also note that GetStack().Last() is the top of the stack (i.e. the string shown 
-        in the status bar).
-    */
-    const wxArrayString& GetStack() const
-        { return m_arrStack; }
+        Returns the text currently shown in this pane.
+     */
+    wxString GetText() const;
 };
 
 /**
@@ -54,21 +64,50 @@ 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
-    @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
     It is possible to create controls and other windows on the status bar.
     Position these windows from an OnSize() event handler.
 
+    @remarks
+    Notice that only the first 127 characters of a string will be shown in
+    status bar fields under pre-XP MSW systems (or even under later systems if
+    a proper manifest indicating that the program uses version 6 of common
+    controls library is not used). This is a limitation of the native control
+    on these platforms.
+
     @library{wxcore}
     @category{miscwnd}
 
     @see wxStatusBarPane, wxFrame, @ref page_samples_statbar
 */
-class wxStatusBar : public wxWindow
+class wxStatusBar : public wxControl
 {
 public:
     /**
@@ -94,7 +133,7 @@ public:
         @see Create()
     */
     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
-                long style = wxST_SIZEGRIP,
+                long style = wxSTB_DEFAULT_STYLE,
                 const wxString& name = wxStatusBarNameStr);
 
     /**
@@ -107,7 +146,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);
 
     /**
@@ -120,21 +159,34 @@ 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;
-    
+
     /**
-        Returns the number of fields in the status bar. 
+        Returns the number of fields in the status bar.
     */
     int GetFieldsCount() const;
-    
+
     /**
         Returns the wxStatusBarPane representing the @a n-th field.
     */
-    const wxStatusBarPane& GetField(int n) const
-        { return m_panes[n]; }
-    
+    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.
 
@@ -148,42 +200,36 @@ public:
     */
     virtual wxString GetStatusText(int i = 0) const;
 
-    /**
-        Returns the stack of strings pushed (see PushStatusText()) on the
-        @a n-th field.
-        
-        See wxStatusBarPane::GetStack() for more info.
-    */
-    const wxArrayString& GetStatusStack(int n) const
-        { return m_panes[n].GetStack(); }
-
     /**
         Returns the width of the @a n-th field.
-        
+
         See wxStatusBarPane::GetWidth() for more info.
     */
-    int GetStatusWidth(int n) const
-        { return m_panes[n].GetWidth(); }
+    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
-        { return m_panes[n].GetStyle(); }
-        
+    int GetStatusStyle(int n) const;
+
     /**
-        Sets the field text to the top of the stack, and pops the stack of saved
-        strings.
+        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()
     */
@@ -198,6 +244,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);
 
@@ -217,16 +268,25 @@ 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 four possible styles:
+            - @c wxSB_NORMAL (default): The field appears with the default native 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.
+            - @c wxSB_SUNKEN: A sunken 3D border is painted around the field
+              (this style is new since wxWidgets 2.9.5).
     */
     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.
@@ -263,6 +323,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);