%---------------- Functions ------------

\chapter{Text.mui/Text.mui}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf FUNCTION]
Text class allows generating objects that contain
some kind of text. You can control the outfit of
your text with some special control characters,
including italics, bold, underline and color
codes. Format codes align text either left,
centered or right, linefeeds allow multiline
text fields.
\end{deflist}


\subsection{Text.mui/MUIA\_Text\_Contents}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Text\_Contents]  -- (V4 ) [ISG], STRPTR
\end{description}

\item[\bf FUNCTION]
String to be displayed in a text object.

If the string is larger than available display space,
it will be clipped. Setting MUIA\_Text\_Contents to NULL
results in an empty text object.

The string is copied into a private buffer, you can destroy
the original after using this tag.

Whenever MUI prints strings, they may contain some special
character sequences defining format, color and style of the text.

'$\backslash$n'     Start a new line. With this character you can e.g. create
         multi line buttons.

ESC -    Disable text engine, following chars will be printed
         without further parsing.

ESC u    Set the soft style to underline.

ESC b    Set the soft style to bold.

ESC i    Set the soft style to italic.

ESC n    Set the soft style back to normal.

ESC $<$n$>$  Use pen number n (2..9) as front pen. n must be a valid
         DrawInfo pen as specified in "'intuition/screens.h"'.

ESC c    Center current (and following) line(s).
         This sequence is only valid at the beginning of a
         string or after a newline character.

ESC r    Right justify current (and following) line(s).
         This sequence is only valid at the beginning of a
         string or after a newline character.

ESC l    Left justify current (and following) line(s).
         This sequence is only valid at the beginning of a
         string or after a newline character.

ESC I[s] Draw MUI image with specification $<$s$>$. See autodocs
         of image class for image spec definition.

Note:    These rules apply to all MUI strings, not only to
         a text objects contents. You can e.g. format the
         columns of a listview or include images in a cycle
         gadgets entries.

\item[\bf EXAMPLE]
\begin{flushleft}
\begin{verbatim}
...
MUIA_Text_Contents, "\33c\33bMUI\33n\nis magic"
...

would look like     |    MUI   |  <-- bold
                    | is magic |  <-- normal
\end{verbatim}
\end{flushleft}
\item[\bf SEE\_ALSO]
\begin{flushleft}
\begin{verbatim}
MUIA_Text_SetMin, MUIA_Text_SetMax, MUIA_Text_PreParse
\end{verbatim}
\end{flushleft}
\end{deflist}


\subsection{Text.mui/MUIA\_Text\_HiChar}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Text\_HiChar]  -- (V4 ) [I..], char
\end{description}

\item[\bf FUNCTION]
If the character given here exists in the displayed
string (no matter if upper or lower case), it will
be underlined. This makes it easy to create macros
such as KeyButton() that specify the control char
and the underline char at the same time.

\item[\bf SEE ALSO]
MUIA\_Text\_Contents, MUIA\_Control\_Char
\end{deflist}


\subsection{Text.mui/MUIA\_Text\_PreParse}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Text\_PreParse]  -- (V4 ) [ISG], STRPTR
\end{description}

\item[\bf FUNCTION]
String containing format definitions to be parsed before
the text from MUIA\_Text\_Contents is printed.

Using this tag, you can easily define different formats,
colors and styles without modifying the original string.

\item[\bf EXAMPLE]
\begin{flushleft}
\begin{verbatim}
...
MUIA_Text_PreParse, "\33c\33i",   // centered and italics
MUIA_Text_Contents, "foobar",
...
\end{verbatim}
\end{flushleft}
\item[\bf SEE\_ALSO]
\begin{flushleft}
\begin{verbatim}
MUIA_Text_Contents
\end{verbatim}
\end{flushleft}
\end{deflist}


\subsection{Text.mui/MUIA\_Text\_SetMax}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Text\_SetMax]  -- (V4 ) [I..], BOOL
\end{description}

\item[\bf FUNCTION]
Boolean value to indicate wether the objects maximal width
shall be calculated to fit the string given with
MUIA\_Text\_Contents.

When set to FALSE, maximum width is not limited.

For a text object that needs to be updated (e.g. some
information about your programs status) you would probably
set MUIA\_Text\_SetMax to FALSE to allow resizing of this
object.

For a label for one of your gadgets, you might want to
give this tag a value of TRUE to prevent MUI from
inserting additional layout space.

Defaults to FALSE.

\item[\bf EXAMPLE]
\begin{flushleft}
\begin{verbatim}
...
TX_Status = TextObject,
   RecessedFrame,
   MUIA_Background   , MUII_BACKGROUND,
   MUIA_Text_PreParse, "\33c",
   MUIA_Text_Contents, "running...",
   End,
...
set(TX_Status,MUIA_Text_Contents,"reading...");
...
set(TX_Status,MUIA_Text_Contents,"writing...");
...
\end{verbatim}
\end{flushleft}
\item[\bf SEE\_ALSO]
\begin{flushleft}
\begin{verbatim}
MUIA_Text_SetMin, MUIA_Text_Contents
\end{verbatim}
\end{flushleft}
\end{deflist}


\subsection{Text.mui/MUIA\_Text\_SetMin}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Text\_SetMin]  -- (V4 ) [I..], BOOL
\end{description}

\item[\bf FUNCTION]
Boolean value to indicate wether the objects minimal width
shall be calculated to fit the string given with
MUIA\_Text\_Contents.

When set to FALSE, minimum width will be set to 0
and the displayed string may be clipped.

Defaults to TRUE.

\item[\bf SEE\_ALSO]
\begin{flushleft}
\begin{verbatim}
MUIA_Text_SetMax, MUIA_Text_Contents
\end{verbatim}
\end{flushleft}
\end{deflist}


\subsection{Text.mui/MUIA\_Text\_SetVMax}
\rule{\textwidth}{1mm}
\vspace{0.5cm}
\begin{deflist}{MMMMMMMM}
\item[\bf NAME]
\begin{description}
\item[MUIA\_Text\_SetVMax]  -- (V11) [I..], BOOL
\end{description}

\item[\bf FUNCTION]
Settings this to FALSE makes a TextObjects y-size unlimited.
Defaults to TRUE which means the objects height is fixed.
\end{deflist}


%---------------- End of File ----------