\section{Group.mui}

Group class is responsible for the complete layout
of a MUI window. A group may contain any number of
child objects, maybe buttons, cycle gadgets or
even other groups.

Some attributes of group class define how the children
of a group are layouted. You can e.g. tell your group
to place its children horizontally (in a row) or
vertically (in a column). Since every MUI object knows
about its minimum and maximum dimensions, group class
has everything it needs to do that job.

More sophisticated layout is possible by assigning
different weights to objects in a group or by
making a group two-dimensional.

Beneath the layout issues, a group object passes
attributes and methods through to all of its
children. Thus, you can talk and listen to any
child of a group by talking and listening to the
group itself.

\subsection[MUIA\_Group\_ActivePage]{MUIA\_Group\_ActivePage -- (V5) [ISG], LONG}

\subsubsection*{SPECIAL INPUTS}
MUIV\_Group\_ActivePage\_First\\
MUIV\_Group\_ActivePage\_Last\\
MUIV\_Group\_ActivePage\_Prev\\
MUIV\_Group\_ActivePage\_Next

\subsubsection*{VERSION}
Available since version 5 of ''group.mui''.

\subsubsection*{FUNCTION}
Set (or get) the active page of a page group.
Only this active page is displayed, all others
are hidden.

The value may range from 0 (for the first child)
to numchildren-1 (for the last child). Children are
adressed in the order of creation:

\subsubsection*{EXAMPLE}
\small \begin{verbatim}
PageGroup,
   Child, Page_0_Object,
   Child, Page_1_Object,
   Child, Page_2_Object,
   Child, Page_3_Object,
   End;
\end{verbatim} \normalsize

\subsubsection*{NOTE}
You may {\bf never} supply an incorrect page value!

\subsubsection*{SEE ALSO}
MUIA\_Group\_PageMode

\subsection[MUIA\_Group\_Child]{MUIA\_Group\_Child -- (V4) [I..], Object $\ast$}

\subsubsection*{FUNCTION}
You supply a pointer to a previously created MUI object
here. This object will be treated as child of the group,
the group is responsible for positioning the object.

Of course you can specify any number of child objects,
limited only by available memory.

Normally, the value for a MUIA\_Group\_Child tag is
a direct call to another MUI\_NewObject(), children
are generated ''on the fly''.

When a group is disposed, all of its children will also
get deleted. If you supply a NULL pointer as child,
the group object will fail and previously dispose all
valid children found in the taglist.

This behaviour makes it possible to generate a complete
application within one single (but long) MUI\_NewObject()
call. Error checking is not necessary since every error,
even if it occurs in a very deep nesting level, will
cause the complete call to fail without leaving back
any previously created object.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
Please have a look at some of the supplied example
programs.

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Group\_Horiz

\subsection[MUIA\_Group\_Columns]{MUIA\_Group\_Columns -- (V4) [IS.], LONG}

\subsubsection*{FUNCTION}
Indicate number of columns in a two dimensional group.
If you use this tag, the total number of children must
be dividable by the number of columns.

The children will be positioned in a two dimensional
array, e.g. allowing easy creation of button fields
(maybe for calculator).

The children in your taglist are always read line
by line.

When MUI layouts two-dimensional groups, it does
actually two layout calculations, one for the rows
and one the columns. Parameters like weights and
dimensions are handled this way:

\begin{itemize}
\item the minimum width of a column/row is the maximum
minimum width of all objects in this column/row.

\item the maximum width of a column/row is the minimum
maximum width of all objects in this column/row.

\item the weight of a column/row is the sum of all
objects in this column/row.
\end{itemize}
   
Actually, there is no difference if you use
MUIA\_Group\_Columns or MUIA\_Group\_Rows.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

/* group of labeled string gadgets */

GroupObject,
   MUIA_Group_Columns, 2,
   MUIA_Group_Child  , label1,
   MUIA_Group_Child  , string1,
   MUIA_Group_Child  , label2,
   MUIA_Group_Child  , string2,
   MUIA_Group_Child  , label3,
   MUIA_Group_Child  , string3,
           ...
   End;

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Group\_Rows, MUIA\_Group\_Horiz

\subsection[MUIA\_Group\_Horiz]{MUIA\_Group\_Horiz -- (V4) [I..], BOOL}

\subsubsection*{FUNCTION}
Boolean value to indicate whether the objects in
this group shall be layouted horizontally or
vertically. Defaults to FALSE.

This is the easy way of telling your group how
it has to look like. If you want two-dimensional
groups, you have to use MUIA\_Group\_Columns
or MUIA\_Group\_Rows.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
GroupObject,
   MUIA_Group_Horiz, TRUE,
   MUIA_Group_Child, obj1,
   MUIA_Group_Child, obj2,
   MUIA_Group_Child, obj3,
   End;

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Group\_Columns, MUIA\_Group\_Rows, MUIA\_Group\_Child

\subsection[MUIA\_Group\_HorizSpacing]{MUIA\_Group\_HorizSpacing -- (V4) [IS.], LONG}

\subsubsection*{FUNCTION}
Number of pixels to be inserted between horizontal
elements of a group.

Please use this tag wisely, you will override the
user's prefered default setting!

\subsubsection*{SEE ALSO}
MUIA\_Group\_Spacing, MUIA\_Group\_VertSpacing

\subsection[MUIA\_Group\_PageMode]{MUIA\_Group\_PageMode -- (V5) [IS.], BOOL}

\subsubsection*{VERSION}
Available since version 5 of ''group.mui''.

\subsubsection*{FUNCTION}
Settings this attribute to TRUE makes the current group a page
group. Page groups always display only one their children, which
one can be adjusted with the MUIA\_Group\_ActivePage attribute.

Imagine you have a preferences window with several different
pages, e.g. the MUI preferences with object, frame, image,
font, screen, keyboard and system prefs. Instead of one
separate window for each group, you could put all pages into
one page group and have a cycle gadget for page switching.
This will make your program easier to use since the user
won't have to handle a lot of windows. However, he will not
be able to work with more than one page at the same time.

Sizes are calculated as follows:

\begin{itemize}
\item The minimum width/height of a page group is the maximum
minimum width/height of all its children.

\item The maximum width/height of a page group is the minimum
maximum width/height of all its children.

\item When the maximum width/height of a child in a page group is
smaller than the minimum width/height of the page group
(since it contains another child with big minimum width/height),
the child be centered.
\end{itemize}

Page groups are not limited in depth, children of a page
group may of course be other page groups.

If you want to have a gadget only visible under certain
conditions, you could make a page group containing this
gadget and an empty rectangle object.

If you want TAB cycling for the objects in a page group,
simply include all objects in the cycle chain (as if
they all were visible at the same time).

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}
demo program "Pages.c"

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Group\_ActivePage

\subsection[MUIA\_Group\_Rows]{MUIA\_Group\_Rows -- (V4) [IS.], LONG}

\subsubsection*{FUNCTION}
Indicate number of rows in a two dimensional group.
If you use this tag, the total number of children must
be dividable by the number of rows.

The children will be positioned in a two dimensional
array, e.g. allowing easy creation of button fields
(maybe for calculator).

The children in your taglist are always read line
by line.

When MUI layouts two-dimensional groups, it does
actually two layout calculations, one for the rows
and one the columns. Parameters like weights and
dimensions are handled this way:

\begin{itemize}
\item the minimum width of a column/row is the maximum
minimum width of all objects in this column/row.

\item the maximum width of a column/row is the minimum
maximum width of all objects in this column/row.

\item the weight of a column/row is the sum of all
objects in this column/row.
\end{itemize}

Actually, there is no difference if you use
MUIA\_Group\_Columns or MUIA\_Group\_Rows.

\subsubsection*{SEE ALSO}
MUIA\_Group\_Columns, MUIA\_Group\_Horiz

\subsection[MUIA\_Group\_SameHeight]{MUIA\_Group\_SameHeight -- (V4) [I..], BOOL}

\subsubsection*{FUNCTION}
Boolean value to indicate that all children of this
group shall have the same height.

\subsubsection*{BUGS}
Up to version 5 of groupclass, using MUIA\_Group\_SameHeight
could make objects larger than their maximum height. This
has been fixed for version 6.

\subsubsection*{SEE ALSO}
MUIA\_Group\_SameSize, MUIA\_Group\_SameWidth

\subsection[MUIA\_Group\_SameSize]{MUIA\_Group\_SameSize -- (V4) [I..], BOOL}

\subsubsection*{FUNCTION}
This is a shorthand for MUIA\_Group\_SameWidth and
MUIA\_Group\_SameHeight, it sets both of these
attributes at once.

Using MUIA\_Group\_SameSize, you won't need to think
if your group is horizontal or vertical, both
cases are handled automatically.

Forcing all objects of a group to be the same size
is e.g. useful for a row of buttons. It's visually
more attractive when these buttons have equal sizes
instead of being just as big as the text within.

\subsubsection*{BUGS}
Up to version 5 of groupclass, using MUIA\_Group\_SameSize
could make objects larger than their maximum size. This
has been fixed for version 6.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

/* three buttons, same size */

GroupObject,
   MUIA_Group_Horiz   , TRUE,
   MUIA_Group_SameSize, TRUE,
   MUIA_Group_Child   , but1,
   MUIA_Group_Child   , but2,
   MUIA_Group_Child   , but3,
   End;

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Group\_SameWidth, MUIA\_Group\_SameHeight

\subsection[MUIA\_Group\_SameWidth]{MUIA\_Group\_SameWidth -- (V4) [I..], BOOL}

\subsubsection*{FUNCTION}
Boolean value to indicate that all children of this
group shall have the same width.

\subsubsection*{BUGS}
Up to version 5 of groupclass, using MUIA\_Group\_SameWidth
could make objects larger than their maximum width. This
has been fixed for version 6.

\subsubsection*{SEE ALSO}
MUIA\_Group\_SameSize, MUIA\_Group\_SameHeight

\subsection[MUIA\_Group\_Spacing]{MUIA\_Group\_Spacing -- (V4) [IS.], LONG}

\subsubsection*{FUNCTION}
This is a shorthand for MUIA\_Group\_HorizSpacing and
MUIA\_Group\_VertSpacing, it sets both of these
attributes at once.

Using MUIA\_Group\_Spacing, you won't need to think
if your group is horizontal or vertical, both
cases are handled automatically.

Note that setting a spacing value for a group
overrides the user's default settings. Please
use it only if you have a good reason.

\subsubsection*{EXAMPLE}
\small
\begin{verbatim}

/* no space between obj1 and obj2: */

GroupObject,
   MUIA_Group_Horiz  , TRUE,
   MUIA_Group_Spacing, 0,
   MUIA_Group_Child  , obj1,
   MUIA_Group_Child  , obj2,
   End;

\end{verbatim}
\normalsize
\subsubsection*{SEE ALSO}
MUIA\_Group\_HorizSpacing, MUIA\_Group\_VertSpacing

\subsection[MUIA\_Group\_VertSpacing]{MUIA\_Group\_VertSpacing -- (V4) [IS.], LONG}

\subsubsection*{FUNCTION}
Number of pixels to be inserted between vertical
elements of a group.

Please use this tag wisely, you will override the
user's prefered default setting!

\subsubsection*{SEE ALSO}
MUIA\_Group\_Spacing, MUIA\_Group\_HorizSpacing