/ 
UI-Various-0.24
River stage one • 1 direct dependent • 1 total dependent
/ UI::Various::Box

NAME

UI::Various::Box - general box widget of UI::Various

SYNOPSIS

use UI::Various;
my $main = UI::Various::main();
my $box = UI::Various::Box(border => 1, columns => 2, rows => 3);
$box->add(0, 0, UI::Various::Text->new(text => 'Hello World!'));
...
$box->add(2, 1, UI::Various::Button->new(text => 'Quit',
                                         code => sub{ exit(); }));
$main->window($box);
$main->mainloop();

ABSTRACT

This module defines a general box object of an application using UI::Various. A box is a container with rows and columns, where each field can contain exactly one other UI element. If more than one UI element must be placed in a field, simply put them in another box inside of it.

Note that the UI::Various::PoorTerm implementation does not display a box but simply prints the fields one after another, as that makes it easier to understand for the visually impaired or software parsing the output. Also note that a box in PoorTerm is always considered to be an active element, but its own active elements can only be selected after selecting the box itself first. (Exception: If a box contains only one own active element, it is selected directly.)

DESCRIPTION

Besides the common attributes inherited from UI::Various::widget and UI::Various::container the box widget knows the following additional attributes:

Attributes

border [rw, fixed, optional]

a flag to indicate if the borders around the box and between its elements are visible or not

A reference passed will be dereferenced and all values will be normalised to 0 or 1 according Perl's standard true/false conversions.

Note that visible borders currently do not work in Curses::UI as they currently do not use a proper Curses::UI element.

columns [rw, fixed, recommended]

the number of columns the box contains (numbering starts with 0)

rows [rw, fixed, recommended]

the number of rows the box contains (numbering starts with 0)

METHODS

Besides the accessors (attributes) described above and the attributes and methods of UI::Various::widget and UI::Various::container, the following additional methods are provided by the Box class itself (note the overloaded add method):

new - constructor

see UI::Various::core::construct

field - access child in specific field

$ui_element = $box->field($row, $column);

example:

$element_1 = $box->field(0, 0);

parameters:

$row                the UI element's row
$column             the UI element's column

description:

This method allows accessing the UI element of a specific field of the box.

returns:

the UI element in the specified field of the box

add - add new children

$ui_container->add([$row, [$column,]] $other_ui_element, ...);

example:

# example box using 2x2 fields:
$self->add(0, 0, $this);
$self->add($that);              # using next free position 0, 1
$self->add(1, 0, $foo, 1, 1, $bar);
$self->add(1, 0, $foo, $bar);   # the same but shorter

# first three example commands combined in one using defaults:
$self->add($this, $that, $foo, $bar);

parameters:

$row                the row of the box for the next UI element
$column             the column of the box for the next UI element
$other_ui_element   one ore more UI elements to be added to the box

description:

This method overloads the standard add method of UI::Various::container. It adds one or more to the box. If a specific field is given (row and column), this is used (unless it already contains something which produces an error). Otherwise the next free field after the "current" one in the same or a later row is used. Both row and column start counting with 0. Basically the algorithm fills a box row by row from left to right. If a UI element can not be placed, this is reported as error and the UI element is ignored.

Note that as in the standard add method of UI::Various::container children already having a parent are removed from their old parent first.

returns:

number of elements added

remove - remove children

This method overloads the standard remove method of UI::Various::container using the identical interface.

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>