X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/355ce7adea8043d72e02cd00aa7f475f3b3be92d..0c46625036e3dfb9613aae310f72a00590530689:/interface/wx/control.h diff --git a/interface/wx/control.h b/interface/wx/control.h index 9dcbf8f136..3c77c72a9a 100644 --- a/interface/wx/control.h +++ b/interface/wx/control.h @@ -3,7 +3,7 @@ // Purpose: interface of wxControl // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -47,6 +47,9 @@ enum wxEllipsizeFlags */ 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, @@ -91,50 +94,69 @@ public: 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. + + 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; + /** + 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); /** - 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); /** - 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 @@ -156,27 +178,31 @@ public: 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); };