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