Object / Element / Area / Border / Widget / Group

A container element which can contain any number of child elements. If the Orientation attribute of the box is set to horizontal, the child elements are laid out from left to right in the order that they appear in the group. Otherwise, the child elements are laid out from top to bottom. Child elements do not overlap. The default orientation is horizontal. Child elements can also be laid on a grid defined by the Rows or Columns attributes.

More sophisticated layout is possible by assigning different weights to child elements or by providing your own layout function using the LayoutHook attribute.

A Family object is used to manage child elements. You can use the AddMember and RemMember methods to add and remove child elements. The UI is automatically updated while adding/removing objects.

Types

Attributes

Style properties

Overrides

FWidgetNode -- (12.00)

typedef struct FeelinWidgetNode
{
    FFamilyNode                     Node;
FAreaPublic *AreaPublic; FWidgetPublic *WidgetPublic;
bits32 Flags; FBox PreviousBox; } FWidgetNode;

The Group class uses the CreateNodeHook attribute of its Family object to create extended family nodes.

MEMBERS

Node (FFamilyNode)

The FFamilyNode required by the Family class.

AreaData (FAreaPublic *)

Direct access to the FAreaPublic of the child.

WidgetData (FWidgetPublic *)

Direct access to the FWidgetPublic of the child.

Columns -- (04.00) [I..], uint32

Indicate the 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 the Group class 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:

- the minimum width of a column/row is the maximum minimum width of all objects in this column/row.
- the maximum width of a column/row is the minimum maximum width of all objects in this column/row.
- the weight of a column/row is the sum of all objects in this column/row.

Forward -- (01.00) [.S.], bool32

When this attribute is found TRUE in a Set or Get methods' taglist, the method is forwarded to the children.

HSpacing -- (01.00) [ISG], uint32

The number of pixels to be inserted between horizontal widgets of a group.

Please use this tag wisely, you will override the spacing-horizontal style property.

LayoutHook -- (01.00) [I..], struct Hook *

This attribute gives you the ability to customize the way widgets are placed in a group. Altough the Group class features a very powerful builtin layout algorithm which serves well for almost all UI related purposes, it might sometimes become handy to override this with custom code.

Imagine you want to build a multimedia document viewer which contains text objects, bitmap objects and buttons. An easy way for doing this is to simply create a sub class of the Group class which contains all the documents elements as Feelin objects and which specifies a custom layout hook for the parent group. This hook is then responsible for placing the objects within the bounds of the parent group.

As soon as you specify a layout hook, the builtin layout calculation is skipped and your hook is called whenever the Group class needs some information.

When your hook is called, the Group class has already placed the group object somewhere in a window and now wants you to place the children of this group. You have to traverse through the child family and calculate positions and sizes for each child. Use the Layout method to tell the child where it should appear. You have to make sure that you don't place children outside of the group and you should generally avoid overlapping objects. Return TRUE if all children are placed, return FALSE if you were for some reasons unable to place your children.

If your previous min/max calculations were correct, your algorithms should not have problems to place all the children in the rectangle defined by the parent group. Its size will never be smaller as your specified minimum dimensions and never be larger as your specified maximum dimensions.

MinMaxHook -- (01.00) [I..], struct Hook *

This attribute is similar to the LayoutHook attribute.

As soon as you specify a minmax hook, the builtin minmax calculation is skipped and your hook is called whenever the Group class needs some information.

Your hook is called when the Group class you to calculate your groups minimum, maximum and default sizes. At this time, the children of your group have already been asked for their dimensions. This allows you to traverse through the list of children and do some calculations depending on their min/max sizes. Place the result of your calculations directly in the FMinMax of your object with the _area_minw, _area_minh, _area_maxw and _area_maxh macros.

Name -- (08.00) [ISG], STRPTR

The Name attribute is used as the tab's title of the group in a Page object.

Example

group-name
<Page>
    <Group Name="Page 1"><Button>You are on page 1</Button></Group>
    <Group Name="Page 2"><Button>You are on page 2</Button></Group>
    <Group Name="Page 3"><Button>You are on page 3</Button></Group>
</Page>

Quiet -- (12.00) [.S.], bool32

Turns on/off automated updating of the UI while adding/removing objects.

You can dynamically add and remove children from groups, even when the window that contains these children is currently opened. Usualy, the UI is re-computed for each child added or removed. By setting the Quiet attribute to TRUE you disable this automation. You can then add or remove several widgets silently. Setting the Quiet attribute back to FALSE produce a single re-computing and update (if needed) of the UI.

The Quiet attribute is thus really usefull when you have a lot of widgets to add or remove and you don't want to bother the user with a costing process.

Example

F_Set(group, FA_Group_Quiet, TRUE);
F_Do(group, FM_RemMember, somechild); F_Do(group, FM_RemMember, somechild2); F_Do(group, FM_AddMember, somenewchild, FV_AddMember_Tail);
F_Set(group, FA_Group_Quiet, FALSE);

RelSizing -- (01.00) [I..], bool32

Usualy children's space is allocated according to their Weight attribute, taking care of respecting minimal and maximal dimensions. Setting this attribute to TRUE activate and alternative space allocation algorithm: their minimal dimensions become their weight. The smaller an object can be, the less space it gets.

Rows -- (04.00) [I..], uint32

Indicate the 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 the Group class 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:

- the minimum width of a column/row is the maximum minimum width of all objects in this column/row.
- the maximum width of a column/row is the minimum maximum width of all objects in this column/row.
- the weight of a column/row is the sum of all objects in this column/row.

SameHeight -- (01.00) [I..], bool32

A boolean value to indicate that all children of this group shall have the same height.

SameSize -- (01.00) [I..], bool32

This is a shorthand for the SameWidth and SameHeight attributes, it sets both of these attributes at once.

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.

SameWidth -- (01.00) [I..], bool32

A boolean value to indicate that all children of a group shall have the same width.

VSpacing -- (01.00) [ISG], uint32

The number of pixels to be inserted between vertical widgets of a group.

Please use this tag wisely, you will override the spacing-vertical style property.

spacing-horizontal -- (12.00)

The number of pixels to be inserted between horizontal elements of a group.

spacing-vertical -- (12.00)

The number of pixels to be inserted between horizontal elements of a group.

AddMember

[method override]

The AddMember method can be used to dynamicaly add child elements.

If the group element has already received the GlobalConnect method, the child element is invoked with the method too.

If the group element has already received the Setup method, the child element is invoked with the method too.

If the group element has already received the Show method, the child element is invoked with the method too.

Unless the Quiet attribute is set to TRUE, the UI is automaticaly updated.

The child element must be of the Widget class, or any of its subclasses, otherwise the connection is refused.

Cleanup

[method override]

The method is forwarded to all child elements.

GlobalConnect

[method override]

The method is forwarded to all child elements.

GlobalDisconnect

[method override]

The method is forwarded to all child elements.

Hide

[method override]

The method is forwarded to all showned child elements.

RemMember

[method override]

The RemMember method can be used to dynamicaly remove child elements.

The child element is hidden with the Hide method. Its graphical resources are freed with the Cleanup method. And finaly, it's global informations are cleared with the GlobalDisconnect method.

Unless the Quiet attribute is set to TRUE, the UI is automaticaly updated.

Setup

[method override]

The method is forwarded to all child elements.

Show

[method override]

The method is forwarded to all showable child elements.

Development