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{const wxString\&}{GetLabelText}{\void}
 110
 111 Returns the control's label or the given \arg{label} string for the static
 112 version without the mnemonics characters (if any) and without the markup
 113 (if the control has \texttt{wxST\_MARKUP} style).
 114
 115
 116
 117 \membersection{wxStaticText::SetLabel}\label{wxstatictextsetlabel}
 118
 119 \func{virtual void}{SetLabel}{\param{const wxString\& }{ label}}
 120
 121 Sets the static text label and updates the controls size to exactly fit the
 122 label unless the control has wxST\_NO\_AUTORESIZE flag.
 123
 124 This function allows to set decorated static label text on platforms which
 125 support it (currently only GTK+ 2). For the other platforms, the markup is
 126 ignored.
 127
 128 The supported tags are:
 129
 130 \twocolwidtha{5cm}
 131 \begin{twocollist}\itemsep=0pt
 132 \twocolitem{<b>}{bold text}
 133 \twocolitem{<big>}{bigger text}
 134 \twocolitem{<i>}{italic text}
 135 \twocolitem{<s>}{strike-through text}
 136 \twocolitem{<sub>}{subscript text}
 137 \twocolitem{<sup>}{superscript text}
 138 \twocolitem{<small>}{smaller text}
 139 \twocolitem{<tt>}{monospaced text}
 140 \twocolitem{<u>}{underlined text}
 141 \twocolitem{<span>}{generic formatter tag; see \urlref{Pango Markup}{http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html} for more information.}
 142 \end{twocollist}
 143
 144 Note that the string must be well-formed (e.g. all tags must be correctly closed)
 145 otherwise it can be not shown correctly or at all.
 146
 147 Also note that you need to escape the following special characters:
 148
 149 \twocolwidtha{5cm}
 150 \begin{twocollist}\itemsep=0pt
 151 \twocolitem{\textbf{Special character}}{\textbf{Escape as}}
 152 \twocolitem{\texttt{&}}{\texttt{&amp;} or as \texttt{&&}}
 153 \twocolitem{\texttt{'}}{\texttt{&apos;}}
 154 \twocolitem{\texttt{"}}{\texttt{&quot;}}
 155 \twocolitem{\texttt{<}}{\texttt{&lt;}}
 156 \twocolitem{\texttt{>}}{\texttt{&gt;}}
 157 \end{twocollist}
 158
 159 The non-escaped ampersand \texttt{&} characters are interpreted as
 160 mnemonics; see \helpref{wxControl::SetLabel}{wxcontrolsetlabel}.
 161
 162
 163 Example:
 164
 165 %% TEX NOTE: in the following block we need to write the (ugly) &&amp;amp;
 166 %%           string in order to force Tex2rtf to show the &&amp; string
 167 \begin{verbatim}
 168     // this will set the wxStaticText to show the "Hello world!" string
 169     // with the "Hello" world in bold on platforms which support markup
 170     pStaticText->SetLabelWithMarkup(wxT("<b>Hello</b> world!"));
 171
 172     // this will make wxStaticText show the string:
 173     //
 174     //              Specials: & ' " < >"
 175     //
 176     // with "Specials" in smaller size font if markup is supported
 177     pStaticText->SetLabelWithMarkup(
 178         wxT("<small>Specials</small>: &amp;amp; &amp;apos; &amp;quot;; &amp;lt; &amp;gt;"));
 179 \end{verbatim}
 180
 181 \wxheading{Parameters}
 182
 183 \docparam{label}{The new label to set. It may contain newline characters and the markup tags described above.}
 184
 185
 186
 187 \membersection{wxStaticText::Wrap}\label{wxstatictextwrap}
 188
 189 \func{void}{Wrap}{\param{int }{width}}
 190
 191 This functions wraps the controls label so that each of its lines becomes at
 192 most \arg{width} pixels wide if possible (the lines are broken at words
 193 boundaries so it might not be the case if words are too long). If \arg{width}
 194 is negative, no wrapping is done.
 195
 196 \newsince{2.6.2}
 197