X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f045c7f52dfcfebcd0ea6a7b689ccb8a25021d1f..f1b08e84a191caaa975569e0cac89658058c7730:/interface/wx/stattext.h diff --git a/interface/wx/stattext.h b/interface/wx/stattext.h index 613d99661a..0004501a88 100644 --- a/interface/wx/stattext.h +++ b/interface/wx/stattext.h @@ -3,7 +3,7 @@ // Purpose: interface of wxStaticText // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -22,11 +22,11 @@ Center the text (horizontally). @style{wxST_NO_AUTORESIZE} By default, the control will adjust its size to exactly fit to the - size of the text when SetLabel is called. If this style flag is + size of the text when SetLabel() is called. If this style flag is given, the control will not change its size (this style is - especially useful with controls which also have wxALIGN_RIGHT or - CENTER style because otherwise they won't make sense any longer - after a call to SetLabel). + especially useful with controls which also have the @c wxALIGN_RIGHT or + the @c wxALIGN_CENTRE style because otherwise they won't make sense any + longer after a call to SetLabel()). @style{wxST_ELLIPSIZE_START} If the labeltext width exceeds the control width, replace the beginning of the label with an ellipsis; uses wxControl::Ellipsize. @@ -89,58 +89,55 @@ public: const wxSize& size = wxDefaultSize, long style = 0, const wxString& name = wxStaticTextNameStr); - /** - Escapes all the symbols of @a str that have a special meaning (<>"'&) for - wxStaticText objects with the @c wxST_MARKUP style. - Those symbols are replaced the corresponding entities (< > " ' &). - */ - static wxString EscapeMarkup(const wxString& str); - /** Returns the contents of the control. - Note that the returned string contains both the mnemonics (@& characters), - if any, and markup tags, if any. - Use GetLabelText() if only the label text is needed. + Note that the returned string may contain both mnemonics (@& characters), + and markup tags, if they were passed to the SetLabel() function. + + Use GetLabelText() if only the label text, without mnemonics and without + markup if the @c wxST_MARKUP style is set, is needed. + + 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 and eventually markup). */ wxString GetLabel() const; /** This method returns the control's label without the mnemonics characters - (if any) and without the markup (if the control has @c wxST_MARKUP style). + (if any) and without the markup (if the control has the @c wxST_MARKUP style). + + Note that because of the stripping of the mnemonics and markup 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; - /** - This overload returns the given @a label string without the - mnemonics characters (if any) and without the markup. - */ - static wxString GetLabelText(const wxString& label); - /** Returns @true if the window styles for this control contains one of the @c wxST_ELLIPSIZE_START, @c wxST_ELLIPSIZE_MIDDLE or @c wxST_ELLIPSIZE_END styles. */ bool IsEllipsized() const; - /** - Removes the markup accepted by wxStaticText when the @c wxST_MARKUP style is used, - and then returns the cleaned string. - - See SetLabel() for more info about the markup. - */ - static wxString RemoveMarkup(const wxString& str); + // NB: when writing docs for the following function remember that Doxygen + // will always expand HTML entities (e.g. ") and thus we need to + // write e.g. "<" to have in the output the "<" string. /** Sets the static text label and updates the controls size to exactly fit the - label unless the control has wxST_NO_AUTORESIZE flag. + label unless the control has @c wxST_NO_AUTORESIZE flag. - This function allows to set decorated static label text on platforms which - support it (currently only GTK+ 2). For the other platforms, the markup is - ignored. + This function allows to set decorated static label text, when the @c wxST_MARKUP + style is used, on those platforms which support it (currently only GTK+ 2). + For the other platforms or when @c wxST_MARKUP is not used, the markup is ignored. The supported tags are:
Tag | +Description | +
<b> | bold text | @@ -226,6 +223,19 @@ public: It may contain newline characters and the markup tags described above. */ virtual 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 and, + if @c wxST_MARKUP is used, without interpreting markup tags. + Notice that it means that the control can't have any mnemonic nor markup defined + for it using this function. + + @see EscapeMarkup() + */ + virtual void SetLabelText(const wxString& text); /** This functions wraps the controls label so that each of its lines becomes at @@ -239,5 +249,34 @@ public: @since 2.6.2 */ void Wrap(int width); + + +public: // static functions + + /** + Returns the given @a label string without the mnemonics characters (if any) + and without the markup. + + Note that since this function is static it will always remove markup + (since it cannot check @c wxST_MARKUP presence/absence!). + */ + static wxString GetLabelText(const wxString& label); + + /** + Escapes all the symbols of @a str that have a special meaning (<>"'&) for + wxStaticText objects with the @c wxST_MARKUP style. + + Those symbols are replaced the corresponding entities + (< > " ' &). + */ + static wxString EscapeMarkup(const wxString& str); + + /** + Removes the markup accepted by wxStaticText when the @c wxST_MARKUP style is used, + and then returns the cleaned string. + + See SetLabel() for more info about the markup. + */ + static wxString RemoveMarkup(const wxString& str); };