Documented new menu label functions

[wxWidgets.git] / docs / latex / wx / stattext.tex

diff --git a/docs/latex/wx/stattext.tex b/docs/latex/wx/stattext.tex
index 81d1505b586d032388fc531f571da85a2adbb1d1..00be03aa2c5842b6b04fe4d38ff0236bc985e831 100644 (file)
--- a/docs/latex/wx/stattext.tex
+++ b/docs/latex/wx/stattext.tex
@@ -13,9 +13,32 @@ A static text control displays one or more lines of read-only text.
 
 <wx/stattext.h>
 
 
 <wx/stattext.h>
 

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{Window styles}
 
 \wxheading{Window styles}
 

-There are no special styles for this control.
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\windowstyle{wxALIGN\_LEFT}}{Align the text to the left}
+\twocolitem{\windowstyle{wxALIGN\_RIGHT}}{Align the text to the right}
+\twocolitem{\windowstyle{wxALIGN\_CENTRE}}{Center the text (horizontally)}
+\twocolitem{\windowstyle{wxST\_NO\_AUTORESIZE}}{By default, the control will
+adjust its size to exactly fit to the size of the text when 
+\helpref{SetLabel}{wxstatictextsetlabel} is called. If this style flag is
+given, the control will not change its size (this style is especially useful
+with controls which also have wxALIGN\_RIGHT or CENTER style because otherwise
+they won't make sense any longer after a call to SetLabel)}
+\twocolitem{\windowstyle{wxST\_ELLIPSIZE\_START}}{If the text width exceeds the
+control width, replace the beginning of the text with an ellipsis}
+\twocolitem{\windowstyle{wxST\_ELLIPSIZE\_MIDDLE}}{Same as above, but replace
+the text in the middle of the control with an ellipsis}
+\twocolitem{\windowstyle{wxST\_ELLIPSIZE\_END}}{Same as above, but replace the
+end of the text with an ellipsis}
+\twocolitem{\windowstyle{wxST\_MARKUP}}{Support markup in the label; see
+\helpref{SetLabel}{wxstatictextsetlabel} for more information}
+\end{twocollist}

 
 See also \helpref{window styles overview}{windowstyles}.
 
 
 See also \helpref{window styles overview}{windowstyles}.
 


@@ -25,6 +48,7 @@ See also \helpref{window styles overview}{windowstyles}.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

+

 \membersection{wxStaticText::wxStaticText}\label{wxstatictextconstr}
 
 \func{}{wxStaticText}{\void}
 \membersection{wxStaticText::wxStaticText}\label{wxstatictextconstr}
 
 \func{}{wxStaticText}{\void}


@@ -32,7 +56,7 @@ See also \helpref{window styles overview}{windowstyles}.
 Default constructor.
 
 \func{}{wxStaticText}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 Default constructor.
 
 \func{}{wxStaticText}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp

-\param{const wxString\& }{label = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\param{const wxString\& }{label}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp

 \param{long}{ style = 0}, \param{const wxString\& }{name = ``staticText"}}
 
 Constructor, creating and showing a text control.
 \param{long}{ style = 0}, \param{const wxString\& }{name = ``staticText"}}
 
 Constructor, creating and showing a text control.


@@ -57,28 +81,120 @@ Constructor, creating and showing a text control.
 
 \helpref{wxStaticText::Create}{wxstatictextcreate}
 
 
 \helpref{wxStaticText::Create}{wxstatictextcreate}
 

+

 \membersection{wxStaticText::Create}\label{wxstatictextcreate}
 
 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 \membersection{wxStaticText::Create}\label{wxstatictextcreate}
 
 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp

-\param{const wxString\& }{label = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
+\param{const wxString\& }{label}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp

 \param{long}{ style = 0}, \param{const wxString\& }{name = ``staticText"}}
 
 Creation function, for two-step construction. For details see \helpref{wxStaticText::wxStaticText}{wxstatictextconstr}.
 
 \param{long}{ style = 0}, \param{const wxString\& }{name = ``staticText"}}
 
 Creation function, for two-step construction. For details see \helpref{wxStaticText::wxStaticText}{wxstatictextconstr}.
 

+

 \membersection{wxStaticText::GetLabel}\label{wxstatictextgetlabel}
 
 \constfunc{wxString}{GetLabel}{\void}
 
 Returns the contents of the control.
 
 \membersection{wxStaticText::GetLabel}\label{wxstatictextgetlabel}
 
 \constfunc{wxString}{GetLabel}{\void}
 
 Returns the contents of the control.
 

+Note that the returned string contains both the mnemonics (\texttt{\&} characters),
+if any, and markup tags, if any.
+
+Use \helpref{wxStaticText::GetLabelText}{wxstatictextgetlabeltext} if only the
+label text is needed.
+
+
+\membersection{wxStaticText::GetLabelText}\label{wxstatictextgetlabeltext}
+
+\constfunc{wxString}{GetLabelText}{\void}
+
+\func{static wxString}{GetLabelText}{\param{const wxString\& }{label}}
+
+The first form returns the control's label without the mnemonics characters (if any) 
+and without the markup (if the control has \texttt{wxST\_MARKUP} style).
+
+The second (static) version returns the given \arg{label} string without the mnemonics 
+characters (if any) and without the markup.
+
+

 \membersection{wxStaticText::SetLabel}\label{wxstatictextsetlabel}
 
 \func{virtual void}{SetLabel}{\param{const wxString\& }{ label}}
 
 \membersection{wxStaticText::SetLabel}\label{wxstatictextsetlabel}
 
 \func{virtual void}{SetLabel}{\param{const wxString\& }{ label}}
 

-Sets the static text label.
+Sets the static text label and updates the controls size to exactly fit the
+label unless the control has wxST\_NO\_AUTORESIZE flag.
+
+This function allows to set decorated static label text on platforms which
+support it (currently only GTK+ 2). For the other platforms, the markup is
+ignored.
+
+The supported tags are:
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{<b>}{bold text}
+\twocolitem{<big>}{bigger text}
+\twocolitem{<i>}{italic text}
+\twocolitem{<s>}{strike-through text}
+\twocolitem{<sub>}{subscript text}
+\twocolitem{<sup>}{superscript text}
+\twocolitem{<small>}{smaller text}
+\twocolitem{<tt>}{monospaced text}
+\twocolitem{<u>}{underlined text}
+\twocolitem{<span>}{generic formatter tag; see \urlref{Pango Markup}{http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html} for more information.}
+\end{twocollist}
+
+Note that the string must be well-formed (e.g. all tags must be correctly closed)
+otherwise it can be not shown correctly or at all.
+
+Also note that you need to escape the following special characters:
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\textbf{Special character}}{\textbf{Escape as}}
+\twocolitem{\texttt{&}}{\texttt{&amp;} or as \texttt{&&}}
+\twocolitem{\texttt{'}}{\texttt{&apos;}}
+\twocolitem{\texttt{"}}{\texttt{&quot;}}
+\twocolitem{\texttt{<}}{\texttt{&lt;}}
+\twocolitem{\texttt{>}}{\texttt{&gt;}}
+\end{twocollist}
+
+The non-escaped ampersand \texttt{&} characters are interpreted as
+mnemonics; see \helpref{wxControl::SetLabel}{wxcontrolsetlabel}.
+
+
+Example:
+
+%% TEX NOTE: in the following block we need to write the (ugly) &&amp;amp;
+%%           string in order to force Tex2rtf to show the &&amp; string
+\begin{verbatim}
+    // this will set the wxStaticText to show the "Hello world!" string
+    // with the "Hello" world in bold on platforms which support markup
+    pStaticText->SetLabelWithMarkup(wxT("<b>Hello</b> world!"));
+
+    // this will make wxStaticText show the string:
+    //
+    //              Specials: & ' " < >"
+    //
+    // with "Specials" in smaller size font if markup is supported
+    pStaticText->SetLabelWithMarkup(
+        wxT("<small>Specials</small>: &amp;amp; &amp;apos; &amp;quot;; &amp;lt; &amp;gt;"));
+\end{verbatim}

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 

-\docparam{label}{The new label to set. It may contain newline characters.}
+\docparam{label}{The new label to set. It may contain newline characters and the markup tags described above.}
+
+
+
+\membersection{wxStaticText::Wrap}\label{wxstatictextwrap}
+
+\func{void}{Wrap}{\param{int }{width}}
+
+This functions wraps the controls label so that each of its lines becomes at
+most \arg{width} pixels wide if possible (the lines are broken at words
+boundaries so it might not be the case if words are too long). If \arg{width}
+is negative, no wrapping is done.

 
 

+\newsince{2.6.2}