X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5c87527c5a81eda63e7ccbda2f226ca02716e7da..323d36e452c48f1e48ffe48312004d5e224634ca:/interface/wx/stattext.h
diff --git a/interface/wx/stattext.h b/interface/wx/stattext.h
index c5ebe78294..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 |
@@ -191,12 +188,12 @@ public:
- | @b Special character |
- @b Escape as |
+ Special character |
+ Escape as |
| @c & |
- @c & or as && |
+ @c & or as @c && |
| @c ' |
@@ -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);
};