1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxStaticText
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 The different ellipsization modes supported by wxStaticText and by
11 wxStaticText::Ellipsize function.
14 The members of this enum are used both as window styles for wxStaticText
15 and both as enumeration values for wxStaticText::Ellipsize static function.
19 wxST_ELLIPSIZE_START
= 0x0004,
20 wxST_ELLIPSIZE_MIDDLE
= 0x0008,
21 wxST_ELLIPSIZE_END
= 0x0010
27 A static text control displays one or more lines of read-only text.
28 wxStaticText supports the three classic text alignments, label ellipsization
29 and formatting markup.
33 Align the text to the left
35 Align the text to the right
36 @style{wxALIGN_CENTRE}
37 Center the text (horizontally)
38 @style{wxST_NO_AUTORESIZE}
39 By default, the control will adjust its size to exactly fit to the
40 size of the text when SetLabel is called. If this style flag is
41 given, the control will not change its size (this style is
42 especially useful with controls which also have wxALIGN_RIGHT or
43 CENTER style because otherwise they won't make sense any longer
44 after a call to SetLabel)
45 @style{wxST_ELLIPSIZE_START}
46 If the labeltext width exceeds the control width, replace the beginning
47 of the label with an ellipsis
48 @style{wxST_ELLIPSIZE_MIDDLE}
49 If the label text width exceeds the control width, replace the middle
50 of the label with an ellipsis
51 @style{wxST_ELLIPSIZE_END}
52 If the label text width exceeds the control width, replace the end
53 of the label with an ellipsis
55 Support markup in the label; see SetLabel() for more information
60 @appearance{statictext.png}
62 @see wxStaticBitmap, wxStaticBox
64 class wxStaticText
: public wxControl
73 Constructor, creating and showing a text control.
76 Parent window. Should not be @NULL.
78 Control identifier. A value of -1 denotes a default value.
86 Window style. See wxStaticText.
92 wxStaticText(wxWindow
* parent
, wxWindowID id
,
93 const wxString
& label
,
94 const wxPoint
& pos
= wxDefaultPosition
,
95 const wxSize
& size
= wxDefaultSize
,
97 const wxString
& name
= wxStaticTextNameStr
);
100 Creation function, for two-step construction. For details see wxStaticText().
102 bool Create(wxWindow
* parent
, wxWindowID id
, const wxString
& label
,
103 const wxPoint
& pos
= wxDefaultPosition
,
104 const wxSize
& size
= wxDefaultSize
, long style
= 0,
105 const wxString
& name
= wxStaticTextNameStr
);
108 Escapes all the symbols of @a str that have a special meaning (<tt><>"'&</tt>) for
109 wxStaticText objects with the @c wxST_MARKUP style.
110 Those symbols are replaced the corresponding entities (< > " ' &).
112 static wxString
EscapeMarkup(const wxString
& str
);
115 Replaces parts of the @a label string with ellipsis, if needed, so
116 that it doesn't exceed @a maxWidth.
119 The string to ellipsize
121 The DC used to retrieve the character widths through the
122 wxDC::GetPartialTextExtents() function.
124 The ellipsization modes. See ::wxEllipsizeMode.
126 The maximum width of the returned string in pixels.
128 static wxString
Ellipsize(const wxString
& label
, const wxDC
& dc
,
129 wxEllipsizeMode mode
, int maxWidth
);
132 Returns the contents of the control.
134 Note that the returned string contains both the mnemonics (@& characters),
135 if any, and markup tags, if any.
136 Use GetLabelText() if only the label text is needed.
138 wxString
GetLabel() const;
141 This method returns the control's label without the mnemonics characters
142 (if any) and without the markup (if the control has @c wxST_MARKUP style).
144 wxString
GetLabelText() const;
147 This overload returns the given @a label string without the
148 mnemonics characters (if any) and without the markup.
150 static wxString
GetLabelText(const wxString
& label
);
153 Returns @true if the window styles for this control contains one of the
154 @c wxST_ELLIPSIZE_START, @c wxST_ELLIPSIZE_MIDDLE or @c wxST_ELLIPSIZE_END styles.
156 bool IsEllipsized() const;
159 Removes the markup accepted by wxStaticText when the @c wxST_MARKUP style is used,
160 and then returns the cleaned string.
162 See SetLabel() for more info about the markup.
164 static wxString
RemoveMarkup(const wxString
& str
);
167 Sets the static text label and updates the controls size to exactly fit the
168 label unless the control has wxST_NO_AUTORESIZE flag.
170 This function allows to set decorated static label text on platforms which
171 support it (currently only GTK+ 2). For the other platforms, the markup is
174 The supported tags are:
190 <TD>strike-through text</TD>
194 <TD>subscript text</TD>
198 <TD>superscript text</TD>
201 <TD><small></TD>
202 <TD>smaller text</TD>
206 <TD>monospaced text</TD>
210 <TD>underlined text</TD>
213 <TD><span></TD>
214 <TD>generic formatter tag; see Pango Markup
215 (http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
216 for more information.</TD>
220 Note that the string must be well-formed (e.g. all tags must be correctly
221 closed) otherwise it can be not shown correctly or at all.
222 Also note that you need to escape the following special characters:
226 <TD>@b Special character</TD>
227 <TD>@b Escape as</TD>
231 <TD>@c &amp; or as &&</TD>
235 <TD>@c &apos;</TD>
239 <TD>@c &quot;</TD>
251 The non-escaped ampersand @c & characters are interpreted as
252 mnemonics; see wxControl::SetLabel.
257 The new label to set.
258 It may contain newline characters and the markup tags described above.
260 virtual void SetLabel(const wxString
& label
);
263 This functions wraps the controls label so that each of its lines becomes at
264 most @a width pixels wide if possible (the lines are broken at words
265 boundaries so it might not be the case if words are too long).
267 If @a width is negative, no wrapping is done. Note that this width is not
268 necessarily the total width of the control, since a few pixels for the
269 border (depending on the controls border style) may be added.
273 void Wrap(int width
);