Correct wxID_SEPARATOR description in menu documentation.

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

diff --git a/interface/wx/control.h b/interface/wx/control.h
index 9dcbf8f1361eacdd9d1976c43ffb895a3e6e2b06..3c77c72a9ad19a0cf878c038e3110d6dc6add328 100644 (file)
--- a/interface/wx/control.h
+++ b/interface/wx/control.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxControl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxControl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

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


@@ -47,6 +47,9 @@ enum wxEllipsizeFlags
 */
 enum wxEllipsizeMode
 {
 */
 enum wxEllipsizeMode
 {

+    /// Don't ellipsize the text at all. @since 2.9.1
+    wxELLIPSIZE_NONE,
+

     /// Put the ellipsis at the start of the string, if the string needs ellipsization.
     wxELLIPSIZE_START,
 
     /// Put the ellipsis at the start of the string, if the string needs ellipsization.
     wxELLIPSIZE_START,
 


@@ -91,50 +94,69 @@ public:
     virtual void Command(wxCommandEvent& event);
 
     /**
     virtual void Command(wxCommandEvent& event);
 
     /**

-        Replaces parts of the @a label string with ellipsis, if needed, so
-        that it doesn't exceed @a maxWidth.
-
-        @param label
-            The string to ellipsize
-        @param dc
-            The DC used to retrieve the character widths through the
-            wxDC::GetPartialTextExtents() function.
-        @param mode
-            The ellipsization modes. See ::wxEllipsizeMode.
-        @param maxWidth
-            The maximum width of the returned string in pixels.
-        @param flags
-            One or more of the ::wxEllipsize
-    */
-    static wxString Ellipsize(const wxString& label, const wxDC& dc,
-                              wxEllipsizeMode mode, int maxWidth,
-                              int flags = wxELLIPSIZE_FLAGS_DEFAULT);
+        Returns the control's label, as it was passed to SetLabel().

 
 

-    /**
-        Returns the control's text.
+        Note that the returned string may contains mnemonics ("&" characters) if they were
+        passed to the SetLabel() function; use GetLabelText() if they are undesired.

 
 

-        @note The returned string contains mnemonics ("&" characters) if it has
-              any, use GetLabelText() if they are undesired.
+        Also note that the returned string is always the string which was passed to
+        SetLabel() but may be different from the string passed to SetLabelText()
+        (since this last one escapes mnemonic characters).

     */
     wxString GetLabel() const;
 
     /**
         Returns the control's label without mnemonics.
     */
     wxString GetLabel() const;
 
     /**
         Returns the control's label without mnemonics.

+
+        Note that because of the stripping of the mnemonics the returned string may differ
+        from the string which was passed to SetLabel() but should always be the same which
+        was passed to SetLabelText().

     */
     wxString GetLabelText() const;
 
     */
     wxString GetLabelText() const;
 

+    /**
+        Sets the control's label.
+
+        All "&" characters in the @a label are special and indicate that the
+        following character is a @e mnemonic for this control and can be used to
+        activate it from the keyboard (typically by using @e Alt key in
+        combination with it). To insert a literal ampersand character, you need
+        to double it, i.e. use use "&&". If this behaviour is undesirable, use
+        SetLabelText() instead.
+    */
+    void SetLabel(const wxString& label);
+
+    /**
+        Sets the control's label to exactly the given string.
+
+        Unlike SetLabel(), this function shows exactly the @a text passed to it
+        in the control, without interpreting ampersands in it in any way.
+        Notice that it means that the control can't have any mnemonic defined
+        for it using this function.
+
+        @see EscapeMnemonics()
+     */
+    void SetLabelText(const wxString& text);
+
+
+public:     // static functions
+    

     /**
         Returns the given @a label string without mnemonics ("&" characters).
     */
     static wxString GetLabelText(const wxString& label);
 
     /**
     /**
         Returns the given @a label string without mnemonics ("&" characters).
     */
     static wxString GetLabelText(const wxString& label);
 
     /**

-        Removes the mnemonics ("&" characters) from the given string.
+        Returns the given @a str string without mnemonics ("&" characters).
+        
+        @note This function is identic to GetLabelText() and is provided both for symmetry
+              with the wxStaticText::RemoveMarkup() function and to allow to write more
+              readable code (since this function has a more descriptive name respect GetLabelText()).

     */
     static wxString RemoveMnemonics(const wxString& str);
 
     /**
     */
     static wxString RemoveMnemonics(const wxString& str);
 
     /**

-        Escape the special mnemonics characters ("&") in the given string.
+        Escapes the special mnemonics characters ("&") in the given string.

 
         This function can be helpful if you need to set the controls label to a
         user-provided string. If the string contains ampersands, they wouldn't
 
         This function can be helpful if you need to set the controls label to a
         user-provided string. If the string contains ampersands, they wouldn't


@@ -156,27 +178,31 @@ public:
     static wxString EscapeMnemonics(const wxString& text);
 
     /**
     static wxString EscapeMnemonics(const wxString& text);
 
     /**

-        Sets the item's text.
+        Replaces parts of the @a label string with ellipsis, if needed, so
+        that it doesn't exceed @a maxWidth.
+        
+        Note that this functions is guaranteed to always returns a string
+        whose rendering on the given DC takes less than @a maxWidth pixels
+        in horizontal.

 
 

-        Any "&" characters in the @a label are special and indicate that the
-        following character is a @e mnemonic for this control and can be used to
-        activate it from the keyboard (typically by using @e Alt key in
-        combination with it). To insert a literal ampersand character, you need
-        to double it, i.e. use use "&&". If this behaviour is undesirable, use
-        SetLabelText() instead.
+        @param label
+            The string to ellipsize
+        @param dc
+            The DC used to retrieve the character widths through the
+            wxDC::GetPartialTextExtents() function.
+        @param mode
+            The ellipsization mode. This is the setting which determines
+            which part of the string should be replaced by the ellipsis.
+            See ::wxEllipsizeMode enumeration values for more info.
+        @param maxWidth
+            The maximum width of the returned string in pixels.
+            This argument determines how much characters of the string need to
+            be removed (and replaced by ellipsis).
+        @param flags
+            One or more of the ::wxEllipsizeFlags enumeration values combined.

     */
     */

-    void SetLabel(const wxString& label);
-
-    /**
-        Sets the item's text to exactly the given string.
-
-        Unlike SetLabel(), this function shows exactly the @a text passed to it
-        in the control, without interpreting ampersands in it in any way.
-        Notice that it means that the control can't have any mnemonic defined
-        for it using this function.
-
-        @see EscapeMnemonics()
-     */
-    void SetLabelText(const wxString& text);
+    static wxString Ellipsize(const wxString& label, const wxDC& dc,
+                              wxEllipsizeMode mode, int maxWidth,
+                              int flags = wxELLIPSIZE_FLAGS_DEFAULT);

 };
 
 };