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