added SetLabelText() and EscapeMnemonics()

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

docs/changes.txt

@@ -433,6 +433,7 @@ All (GUI):
 - Added wxArtProvider::GetNativeSizeHint(); GetSizeHint() as well as
   GetNativeSizeHint() now return more sensible values in wxMSW and wxMac and
   no longer return bogus values.
+- Added wxControl::SetLabelText() and EscapeMnemonics().
 
 wxGTK:
 

include/wx/control.h

@@ -53,9 +53,6 @@ public:
     // get the control alignment (left/right/centre, top/bottom/centre)
     int GetAlignment() const { return m_windowStyle & wxALIGN_MASK; }
 
-    // get just the text of the label, without mnemonic characters ('&')
-    wxString GetLabelText() const { return GetLabelText(GetLabel()); }
-
     virtual void SetLabel(const wxString& label)
     {
         m_labelOrig = label;
@@ -72,6 +69,14 @@ public:
         return m_labelOrig;
     }
 
+    // get just the text of the label, without mnemonic characters ('&')
+    wxString GetLabelText() const { return GetLabelText(GetLabel()); }
+
+    void SetLabelText(const wxString& text)
+    {
+        return SetLabel(EscapeMnemonics(text));
+    }
+
     // static utilities:
 
     // replaces parts of the string with ellipsis if needed
@@ -84,6 +89,9 @@ public:
     // removes the mnemonics characters
     static wxString RemoveMnemonics(const wxString& str);
 
+    // escapes (by doubling them) the mnemonics
+    static wxString EscapeMnemonics(const wxString& str);
+
     // return the accel index in the string or -1 if none and puts the modified
     // string into second parameter if non NULL
     static int FindAccelIndex(const wxString& label,

interface/wx/control.h

@@ -80,15 +80,50 @@ public:
     */
     static wxString RemoveMnemonics(const wxString& str);
 
+    /**
+        Escape 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
+        appear on the display but be used instead to indicate that the
+        character following the first of them can be used as a control mnemonic.
+        While this can sometimes be desirable (e.g. to allow the user to
+        configure mnemonics of the controls), more often you will want to use
+        this function before passing a user-defined string to SetLabel().
+        Alternatively, if the label is entirely user-defined, you can just call
+        SetLabelText() directly -- but this function must be used if the label
+        is a combination of a part defined by program containing the control
+        mnemonics and a user-defined part.
+
+        @param text
+            The string such as it should appear on the display.
+        @return
+            The same string with the ampersands in it doubled.
+     */
+    static wxString EscapeMnemonics(const wxString& text);
+
     /**
         Sets the item's text.
 
         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 "&&".
+        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 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);
 };
 

src/common/ctrlcmn.cpp

@@ -159,6 +159,14 @@ wxString wxControlBase::RemoveMnemonics(const wxString& str)
     return wxStripMenuCodes(str, wxStrip_Mnemonics);
 }
 
+/* static */
+wxString wxControlBase::EscapeMnemonics(const wxString& text)
+{
+    wxString label(text);
+    label.Replace("&", "&&");
+    return label;
+}
+
 /* static */
 int wxControlBase::FindAccelIndex(const wxString& label, wxString *labelOnly)
 {