NAME

UI::Various::container - abstract container class for UI elements

SYNOPSIS

    # This module should never be used directly!
    # It is used indirectly via the following:
    use UI::Various::...;

ABSTRACT

This module is the common abstract container class for all kinds UI elements that may contain other UI elements (e.g. UI::Various::Window, UI::Various::Dialog or UI::Various::Box).

DESCRIPTION

The documentation of this module is mainly intended for developers of the package itself.

All container classes share the following common attributes (inherited from UI::Various::container):

Attributes

children [private]

a list with the children of the container UI element, which must not be directly accessed (use child for access and iteration, use children to get their quantity and use add and remove for manipulation)

METHODS

Besides the common methods inherited from UI::Various::widget the following additional ones are available in all UI::Various::[A-Z]* container classes (UI elements containing other UI elements):

new - constructor

see UI::Various::core::construct

add - add new children

    $ui_container->add($other_ui_element, ...);

example:

    $self->add($that);
    $self->add($foo, $bar);

parameters:

    $other_ui_element   one ore more UI elements to be added to container

description:

This method adds new children to a container element. Note that children already having a parent are removed from their old parent first.

returns:

number of elements added

remove - remove children

    $ui_container->remove($other_ui_element, ...);

example:

    $self->remove($that);
    $self->remove($foo, $bar);

parameters:

    $other_ui_element   one ore more UI elements to be removed from container

description:

This method removes children from a container element.

returns:

the last node that has been removed or undef if nothing could be removed

children - return number of children

    $_ = $ui_container->children;

description:

This method returns the number of children a container element has.

returns:

number of children

child - access children or iterate through them

    $ui_element = $ui_container->child($index);
    $ui_element = $ui_container->child();
    $ui_container->child(undef);

example:

    $ui_element = $self->child(0);
    while ($_ = $self->child())
    {
        ...
        if ($abort)
        {
            $self->child(undef);
            last;
        }
        ...
    }

parameters:

    $index              optional index for direct access,
                        C<undef> for reset of iterator

description:

When called with a (positive or negative) numeric index this method returns the container's element at that index. When called without parameter this method iterates over all elements until the end, when it returns undef and automatically resets the iterator. Calling the method with an explicit undef resets the iterator before it reaches the end. An empty string instead of undef is also possible to allow avoiding Perl bugs #7508 and #109726 in Perl versions prior to 5.20.

Note that removing takes care of keeping the index valid, so it's perfectly possible to use a loop to remove some or all children of a container.

Note that each container object can only have one active iterator at any time.

returns:

element at index or iterator, or undef if not existing or at end of iteration

SEE ALSO

UI::Various

LICENSE

Copyright (C) Thomas Dorner.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE file for more details.

AUTHOR

Thomas Dorner <dorner (at) cpan (dot) org>

cpanm UI::Various

perl -MCPAN -e shell
install UI::Various