]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/stattext.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / stattext.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: stattext.h
e54c96f1 3// Purpose: interface of wxStaticText
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxStaticText
7c913512 11
23324ae1 12 A static text control displays one or more lines of read-only text.
4520d583
FM
13 wxStaticText supports the three classic text alignments, label ellipsization
14 and formatting markup.
7c913512 15
23324ae1 16 @beginStyleTable
8c6791e4 17 @style{wxALIGN_LEFT}
5c87527c 18 Align the text to the left.
8c6791e4 19 @style{wxALIGN_RIGHT}
5c87527c 20 Align the text to the right.
8c6791e4 21 @style{wxALIGN_CENTRE}
5c87527c 22 Center the text (horizontally).
8c6791e4 23 @style{wxST_NO_AUTORESIZE}
23324ae1
FM
24 By default, the control will adjust its size to exactly fit to the
25 size of the text when SetLabel is called. If this style flag is
26 given, the control will not change its size (this style is
27 especially useful with controls which also have wxALIGN_RIGHT or
28 CENTER style because otherwise they won't make sense any longer
5c87527c 29 after a call to SetLabel).
8c6791e4 30 @style{wxST_ELLIPSIZE_START}
4520d583 31 If the labeltext width exceeds the control width, replace the beginning
5c87527c 32 of the label with an ellipsis; uses wxControl::Ellipsize.
8c6791e4 33 @style{wxST_ELLIPSIZE_MIDDLE}
4520d583 34 If the label text width exceeds the control width, replace the middle
5c87527c 35 of the label with an ellipsis; uses wxControl::Ellipsize.
8c6791e4 36 @style{wxST_ELLIPSIZE_END}
4520d583 37 If the label text width exceeds the control width, replace the end
5c87527c 38 of the label with an ellipsis; uses wxControl::Ellipsize.
8c6791e4 39 @style{wxST_MARKUP}
5c87527c 40 Support markup in the label; see SetLabel() for more information.
23324ae1 41 @endStyleTable
7c913512 42
23324ae1
FM
43 @library{wxcore}
44 @category{ctrl}
7e59b885 45 @appearance{statictext.png}
7c913512 46
e54c96f1 47 @see wxStaticBitmap, wxStaticBox
23324ae1
FM
48*/
49class wxStaticText : public wxControl
50{
51public:
671600d8
RR
52 /**
53 Default constructor.
54 */
55 wxStaticText();
4701dc09 56
23324ae1
FM
57 /**
58 Constructor, creating and showing a text control.
3c4f71cc 59
7c913512 60 @param parent
4cc4bfaf 61 Parent window. Should not be @NULL.
7c913512 62 @param id
4cc4bfaf 63 Control identifier. A value of -1 denotes a default value.
7c913512 64 @param label
4cc4bfaf 65 Text label.
7c913512 66 @param pos
4cc4bfaf 67 Window position.
7c913512 68 @param size
4cc4bfaf 69 Window size.
7c913512 70 @param style
4cc4bfaf 71 Window style. See wxStaticText.
7c913512 72 @param name
4cc4bfaf 73 Window name.
3c4f71cc 74
4cc4bfaf 75 @see Create()
23324ae1 76 */
7c913512
FM
77 wxStaticText(wxWindow* parent, wxWindowID id,
78 const wxString& label,
79 const wxPoint& pos = wxDefaultPosition,
80 const wxSize& size = wxDefaultSize,
81 long style = 0,
11e3af6e 82 const wxString& name = wxStaticTextNameStr);
23324ae1
FM
83
84 /**
85 Creation function, for two-step construction. For details see wxStaticText().
86 */
43c48e1e 87 bool Create(wxWindow* parent, wxWindowID id, const wxString& label,
23324ae1 88 const wxPoint& pos = wxDefaultPosition,
43c48e1e
FM
89 const wxSize& size = wxDefaultSize, long style = 0,
90 const wxString& name = wxStaticTextNameStr);
23324ae1 91
4520d583
FM
92 /**
93 Escapes all the symbols of @a str that have a special meaning (<tt><>"'&</tt>) for
94 wxStaticText objects with the @c wxST_MARKUP style.
95 Those symbols are replaced the corresponding entities (&lt; &gt; &quot; &apos; &amp;).
96 */
97 static wxString EscapeMarkup(const wxString& str);
98
23324ae1
FM
99 /**
100 Returns the contents of the control.
4701dc09
FM
101
102 Note that the returned string contains both the mnemonics (@& characters),
23324ae1 103 if any, and markup tags, if any.
4701dc09 104 Use GetLabelText() if only the label text is needed.
23324ae1 105 */
328f5751 106 wxString GetLabel() const;
23324ae1 107
23324ae1 108 /**
4701dc09
FM
109 This method returns the control's label without the mnemonics characters
110 (if any) and without the markup (if the control has @c wxST_MARKUP style).
111 */
112 wxString GetLabelText() const;
113
114 /**
115 This overload returns the given @a label string without the
116 mnemonics characters (if any) and without the markup.
23324ae1 117 */
4701dc09 118 static wxString GetLabelText(const wxString& label);
23324ae1 119
4520d583
FM
120 /**
121 Returns @true if the window styles for this control contains one of the
122 @c wxST_ELLIPSIZE_START, @c wxST_ELLIPSIZE_MIDDLE or @c wxST_ELLIPSIZE_END styles.
123 */
124 bool IsEllipsized() const;
125
126 /**
127 Removes the markup accepted by wxStaticText when the @c wxST_MARKUP style is used,
128 and then returns the cleaned string.
129
130 See SetLabel() for more info about the markup.
131 */
132 static wxString RemoveMarkup(const wxString& str);
133
23324ae1
FM
134 /**
135 Sets the static text label and updates the controls size to exactly fit the
136 label unless the control has wxST_NO_AUTORESIZE flag.
4701dc09 137
23324ae1
FM
138 This function allows to set decorated static label text on platforms which
139 support it (currently only GTK+ 2). For the other platforms, the markup is
140 ignored.
4701dc09 141
23324ae1 142 The supported tags are:
3f5506cf
RR
143 <TABLE>
144 <TR>
145 <TD>&lt;b&gt;</TD>
146 <TD>bold text</TD>
147 </TR>
148 <TR>
149 <TD>&lt;big&gt;</TD>
150 <TD>bigger text</TD>
151 </TR>
152 <TR>
153 <TD>&lt;i&gt;</TD>
154 <TD>italic text</TD>
155 </TR>
156 <TR>
157 <TD>&lt;s&gt;</TD>
158 <TD>strike-through text</TD>
159 </TR>
160 <TR>
161 <TD>&lt;sub&gt;</TD>
162 <TD>subscript text</TD>
163 </TR>
164 <TR>
165 <TD>&lt;sup&gt;</TD>
166 <TD>superscript text</TD>
167 </TR>
168 <TR>
169 <TD>&lt;small&gt;</TD>
170 <TD>smaller text</TD>
171 </TR>
172 <TR>
173 <TD>&lt;tt&gt;</TD>
174 <TD>monospaced text</TD>
175 </TR>
176 <TR>
177 <TD>&lt;u&gt;</TD>
178 <TD>underlined text</TD>
179 </TR>
180 <TR>
181 <TD>&lt;span&gt;</TD>
4701dc09
FM
182 <TD>generic formatter tag; see Pango Markup
183 (http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html)
184 for more information.</TD>
3f5506cf
RR
185 </TR>
186 </TABLE>
3c4f71cc 187
23324ae1 188 Note that the string must be well-formed (e.g. all tags must be correctly
4701dc09 189 closed) otherwise it can be not shown correctly or at all.
23324ae1 190 Also note that you need to escape the following special characters:
4701dc09 191
3f5506cf
RR
192 <TABLE>
193 <TR>
f045c7f5
FM
194 <TD><b>Special character</b></TD>
195 <TD><b>Escape as</b></TD>
3f5506cf
RR
196 </TR>
197 <TR>
198 <TD>@c &amp;</TD>
f045c7f5 199 <TD>@c &amp;amp; or as @c &amp;&amp;</TD>
3f5506cf
RR
200 </TR>
201 <TR>
202 <TD>@c &apos;</TD>
203 <TD>@c &amp;apos;</TD>
204 </TR>
205 <TR>
206 <TD>@c &quot;</TD>
207 <TD>@c &amp;quot;</TD>
208 </TR>
209 <TR>
210 <TD>@c &lt;</TD>
211 <TD>@c &amp;lt;</TD>
212 </TR>
213 <TR>
214 <TD>@c &gt;</TD>
215 <TD>@c &amp;gt;</TD>
216 </TR>
217 </TABLE>
4701dc09 218
3f5506cf 219 The non-escaped ampersand @c &amp; characters are interpreted as
23324ae1 220 mnemonics; see wxControl::SetLabel.
3c4f71cc 221
23324ae1 222 Example:
3c4f71cc 223
7c913512 224 @param label
4701dc09
FM
225 The new label to set.
226 It may contain newline characters and the markup tags described above.
23324ae1
FM
227 */
228 virtual void SetLabel(const wxString& label);
229
230 /**
231 This functions wraps the controls label so that each of its lines becomes at
4cc4bfaf 232 most @a width pixels wide if possible (the lines are broken at words
4701dc09
FM
233 boundaries so it might not be the case if words are too long).
234
235 If @a width is negative, no wrapping is done. Note that this width is not
cd3eb0f7
SN
236 necessarily the total width of the control, since a few pixels for the
237 border (depending on the controls border style) may be added.
3c4f71cc 238
1e24c2af 239 @since 2.6.2
23324ae1
FM
240 */
241 void Wrap(int width);
242};
e54c96f1 243