docs/latex/wx/stattext.tex

   1 \section{\class{wxStaticText}}\label{wxstatictext}
   2
   3 A static text control displays one or more lines of read-only text.
   4
   5 \wxheading{Derived from}
   6
   7 \helpref{wxControl}{wxcontrol}\\
   8 \helpref{wxWindow}{wxwindow}\\
   9 \helpref{wxEvtHandler}{wxevthandler}\\
  10 \helpref{wxObject}{wxobject}
  11
  12 \wxheading{Include files}
  13
  14 <wx/stattext.h>
  15
  16 \wxheading{Library}
  17
  18 \helpref{wxCore}{librarieslist}
  19
  20 \wxheading{Window styles}
  21
  22 \twocolwidtha{5cm}
  23 \begin{twocollist}\itemsep=0pt
  24 \twocolitem{\windowstyle{wxALIGN\_LEFT}}{Align the text to the left}
  25 \twocolitem{\windowstyle{wxALIGN\_RIGHT}}{Align the text to the right}
  26 \twocolitem{\windowstyle{wxALIGN\_CENTRE}}{Center the text (horizontally)}
  27 \twocolitem{\windowstyle{wxST\_NO\_AUTORESIZE}}{By default, the control will
  28 adjust its size to exactly fit to the size of the text when
  29 \helpref{SetLabel}{wxstatictextsetlabel} is called. If this style flag is
  30 given, the control will not change its size (this style is especially useful
  31 with controls which also have wxALIGN\_RIGHT or CENTER style because otherwise
  32 they won't make sense any longer after a call to SetLabel)}
  33 \twocolitem{\windowstyle{wxST\_ELLIPSIZE\_START}}{If the text width exceeds the
  34 control width, replace the beginning of the text with an ellipsis}
  35 \twocolitem{\windowstyle{wxST\_ELLIPSIZE\_MIDDLE}}{Same as above, but replace
  36 the text in the middle of the control with an ellipsis}
  37 \twocolitem{\windowstyle{wxST\_ELLIPSIZE\_END}}{Same as above, but replace the
  38 end of the text with an ellipsis}
  39 \twocolitem{\windowstyle{wxST\_MARKUP}}{Support markup in the label; see
  40 \helpref{SetLabel}{wxstatictextsetlabel} for more information}
  41 \end{twocollist}
  42
  43 See also \helpref{window styles overview}{windowstyles}.
  44
  45 \wxheading{See also}
  46
  47 \helpref{wxStaticBitmap}{wxstaticbitmap}, \helpref{wxStaticBox}{wxstaticbox}
  48
  49 \latexignore{\rtfignore{\wxheading{Members}}}
  50
  51
  52 \membersection{wxStaticText::wxStaticText}\label{wxstatictextconstr}
  53
  54 \func{}{wxStaticText}{\void}
  55
  56 Default constructor.
  57
  58 \func{}{wxStaticText}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
  59 \param{const wxString\& }{label}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  60 \param{long}{ style = 0}, \param{const wxString\& }{name = ``staticText"}}
  61
  62 Constructor, creating and showing a text control.
  63
  64 \wxheading{Parameters}
  65
  66 \docparam{parent}{Parent window. Should not be NULL.}
  67
  68 \docparam{id}{Control identifier. A value of -1 denotes a default value.}
  69
  70 \docparam{label}{Text label.}
  71
  72 \docparam{pos}{Window position.}
  73
  74 \docparam{size}{Window size.}
  75
  76 \docparam{style}{Window style. See \helpref{wxStaticText}{wxstatictext}.}
  77
  78 \docparam{name}{Window name.}
  79
  80 \wxheading{See also}
  81
  82 \helpref{wxStaticText::Create}{wxstatictextcreate}
  83
  84
  85 \membersection{wxStaticText::Create}\label{wxstatictextcreate}
  86
  87 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
  88 \param{const wxString\& }{label}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  89 \param{long}{ style = 0}, \param{const wxString\& }{name = ``staticText"}}
  90
  91 Creation function, for two-step construction. For details see \helpref{wxStaticText::wxStaticText}{wxstatictextconstr}.
  92
  93
  94 \membersection{wxStaticText::GetLabel}\label{wxstatictextgetlabel}
  95
  96 \constfunc{wxString}{GetLabel}{\void}
  97
  98 Returns the contents of the control.
  99
 100 Note that the returned string contains both the mnemonics (\texttt{\&} characters),
 101 if any, and markup tags, if any.
 102
 103 Use \helpref{wxStaticText::GetLabelText}{wxstatictextgetlabeltext} if only the
 104 label text is needed.
 105
 106
 107 \membersection{wxStaticText::GetLabelText}\label{wxstatictextgetlabeltext}
 108
 109 \constfunc{wxString}{GetLabelText}{\void}
 110
 111 \func{static wxString}{GetLabelText}{\param{const wxString\& }{label}}
 112
 113 The first form returns the control's label without the mnemonics characters (if any)
 114 and without the markup (if the control has \texttt{wxST\_MARKUP} style).
 115
 116 The second (static) version returns the given \arg{label} string without the mnemonics
 117 characters (if any) and without the markup.
 118
 119
 120 \membersection{wxStaticText::SetLabel}\label{wxstatictextsetlabel}
 121
 122 \func{virtual void}{SetLabel}{\param{const wxString\& }{ label}}
 123
 124 Sets the static text label and updates the controls size to exactly fit the
 125 label unless the control has wxST\_NO\_AUTORESIZE flag.
 126
 127 This function allows to set decorated static label text on platforms which
 128 support it (currently only GTK+ 2). For the other platforms, the markup is
 129 ignored.
 130
 131 The supported tags are:
 132
 133 \twocolwidtha{5cm}
 134 \begin{twocollist}\itemsep=0pt
 135 \twocolitem{<b>}{bold text}
 136 \twocolitem{<big>}{bigger text}
 137 \twocolitem{<i>}{italic text}
 138 \twocolitem{<s>}{strike-through text}
 139 \twocolitem{<sub>}{subscript text}
 140 \twocolitem{<sup>}{superscript text}
 141 \twocolitem{<small>}{smaller text}
 142 \twocolitem{<tt>}{monospaced text}
 143 \twocolitem{<u>}{underlined text}
 144 \twocolitem{<span>}{generic formatter tag; see \urlref{Pango Markup}{http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html} for more information.}
 145 \end{twocollist}
 146
 147 Note that the string must be well-formed (e.g. all tags must be correctly closed)
 148 otherwise it can be not shown correctly or at all.
 149
 150 Also note that you need to escape the following special characters:
 151
 152 \twocolwidtha{5cm}
 153 \begin{twocollist}\itemsep=0pt
 154 \twocolitem{\textbf{Special character}}{\textbf{Escape as}}
 155 \twocolitem{\texttt{&}}{\texttt{&amp;} or as \texttt{&&}}
 156 \twocolitem{\texttt{'}}{\texttt{&apos;}}
 157 \twocolitem{\texttt{"}}{\texttt{&quot;}}
 158 \twocolitem{\texttt{<}}{\texttt{&lt;}}
 159 \twocolitem{\texttt{>}}{\texttt{&gt;}}
 160 \end{twocollist}
 161
 162 The non-escaped ampersand \texttt{&} characters are interpreted as
 163 mnemonics; see \helpref{wxControl::SetLabel}{wxcontrolsetlabel}.
 164
 165
 166 Example:
 167
 168 %% TEX NOTE: in the following block we need to write the (ugly) &&amp;amp;
 169 %%           string in order to force Tex2rtf to show the &&amp; string
 170 \begin{verbatim}
 171     // this will set the wxStaticText to show the "Hello world!" string
 172     // with the "Hello" world in bold on platforms which support markup
 173     pStaticText->SetLabelWithMarkup(wxT("<b>Hello</b> world!"));
 174
 175     // this will make wxStaticText show the string:
 176     //
 177     //              Specials: & ' " < >"
 178     //
 179     // with "Specials" in smaller size font if markup is supported
 180     pStaticText->SetLabelWithMarkup(
 181         wxT("<small>Specials</small>: &amp;amp; &amp;apos; &amp;quot;; &amp;lt; &amp;gt;"));
 182 \end{verbatim}
 183
 184 \wxheading{Parameters}
 185
 186 \docparam{label}{The new label to set. It may contain newline characters and the markup tags described above.}
 187
 188
 189
 190 \membersection{wxStaticText::Wrap}\label{wxstatictextwrap}
 191
 192 \func{void}{Wrap}{\param{int }{width}}
 193
 194 This functions wraps the controls label so that each of its lines becomes at
 195 most \arg{width} pixels wide if possible (the lines are broken at words
 196 boundaries so it might not be the case if words are too long). If \arg{width}
 197 is negative, no wrapping is done.
 198
 199 \newsince{2.6.2}
 200