/ 
IUP-0.304_1
River stage zero No dependents
/ IUP::GridBox

NAME

IUP::GridBox - [GUI element] container for composing elements in a regular grid

DESCRIPTION

Creates a void container for composing elements in a regular grid. It is a box that arranges the elements it contains from top to bottom and from left to right, but can distribute the elements in lines or in columns.

The child elements are added to the control just like a IUP::Vbox and IUP::Hbox, sequentially. Then they are distributed accordingly the attributes ORIENTATION and NUMDIV. When ORIENTATION=HORIZONTAL children are distributed from left to right on the first line until NUMDIV, then on the second line, and so on. When ORIENTATION=VERTICAL children are distributed from top to bottom on the first column until NUMDIV, then on the second column, and so on. The number of lines and the number of columns can be easily obtained from the combination of these attributes:

if ($g->ORIENTATION eq 'HORIZONTAL') {
  $num_lin = $child_count / $g->NUMDIV;
  $num_col = $g->NUMDIV;
}
else {
  $num_lin = $g->NUMDIV;
  $num_col = $child_count / $g->NUMDIV;
}

Notice that the total number of spaces can be larger than the number of actual children, the last line or column can be incomplete.

The column sizes will be based only on the width of the children of the reference line, usually line 0. The line sizes will be based only on the height of the children of the reference column, usually column 0.

It does not have a native representation.

DEFAULT NORMALIZE=BOTH EXPANDCHILDREN=YES

USAGE

CREATION - new() method

#standard way
my $gridbox = IUP::GridBox->new( child=>[$elem1, $elem2], ANYATTRIBUTE=>'any value' );
 
#or with just 1 parameter (arrayref)
my $gridbox = IUP::GridBox->new( [$elem1, $elem2] );

child: (named parameter) List of the references to elements (or just a single element) that will be placed in the box.

Returns: the identifier of the created element, or undef if an error occurs.

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.

ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:

ALIGNMENTLIN

(non inheritable) Vertically aligns the elements within each line. Possible values: "ATOP", "ACENTER", "ABOTTOM". Default: "ATOP". The alignment of a single line can also be set using "ALIGNMENTLIN(n)", where "n" is the line index, starting at 0 from top to bottom.

ALIGNMENTCOL

(non inheritable) Horizontally aligns the elements within each column. Possible values: "ALEFT", "ACENTER", "ARIGHT". Default: "ALEFT". The alignment of a single column can also be set using "ALIGNMENTCOL(n)", where "n" is the column index, starting at 0 from left to right.

EXPAND

(non inheritable*) The default value is "YES". See the documentation of the attribute for EXPAND inheritance.

EXPANDCHILDREN

(non inheritable) forces all children to expand in the given direction and to fully occupy its space available inside the box. Can be YES (both directions), HORIZONTAL, VERTICAL or NO. Default: "NO". This has the same effect as setting EXPAND on each child, but the box expansion will not be affected.

GAPLIN, CGAPLIN

Defines a vertical space in pixels between lines, CGAPLIN is in the same units of the SIZE attribute for the height. Default "0".

GAPCOL, CGAPCOL

Defines a horizontal space in pixels between columns, CGAPCOL is in the same units of the SIZE attribute for the height. Default: "0".

NGAPLIN, NCGAPLIN, NGAPCOL, NCGAPCOL

(non inheritable) Same as *GAP* but are non inheritable.

HOMOGENEOUSLIN

(non inheritable) forces all lines to have the same vertical space, or height. The line height will be based on the highest child of the reference line (See SIZELIN). Default: "NO". Notice that this does not changes the children size, only the available space for each one of them to expand.

HOMOGENEOUSCOL

(non inheritable) forces all columns to have the same horizontal space, or width. The column width will be based on the largest child of the reference column (See SIZECOL). Default: "NO". Notice that this does not changes the children size, only the available space for each one of them to expand.

MARGIN, CMARGIN

Defines a margin in pixels, CMARGIN is in the same units of the SIZE attribute. Its value has the format "widthxheight", where width and height are integer values corresponding to the horizontal and vertical margins, respectively. Default: "0x0" (no margin).

NMARGIN, NCMARGIN

(non inheritable) Same as MARGIN but are non inheritable.

NUMDIV

controls the number of divisions along the distribution according to ORIENTATION. When ORIENTATION=HORIZONTAL, NUMDIV is the number of columns, when ORIENTATION=VERTICAL, NUMDIV is the number of lines. When value is AUTO, its actual value will be calculated to fit the maximum number of elements in the orientation direction. Default: AUTO.

NUMCOL

(read-only) returns the number of columns.

NUMLIN

(read-only) returns the number of lines.

NORMALIZESIZE

(non inheritable) normalizes all children natural size to be the biggest natural size among the reference line and the reference column. All natural width will be set to the biggest width, and all natural height will be set to the biggest height according to is value. Can be NO, HORIZONTAL, VERTICAL or BOTH. Default: "NO". Same as using IUP::Normalizer.

ORIENTATION

(non inheritable) controls the distribution of the children in lines or in columns. Can be: HORIZONTAL or VERTICAL. Default: HORIZONTAL.

SIZECOL

(non inheritable) index of the column that will be used as reference when calculating the height of the lines. Default: 0.

SIZELIN

(non inheritable) index of the line that will be used as reference when calculating the width of the columns. Default: 0.

WID

(read-only) returns -1 if mapped.

The following common attributes are also accepted:

Attributes at children only:

FLOATING

(non inheritable) If a child has FLOATING=YES then its size and position will be ignored by the layout processing. Default: "NO".

NOTES

The box can be created with no elements and be dynamic filled using Append or Insert.

The box will NOT expand its children, it will allow its children to expand according to the space left in the box parent. So for the expansion to occur, the children must be expandable with EXPAND!=NO, and there must be room in the box parent.

EXAMPLES

The element IUP::GridBox is used in the following sample scripts:

SEE ALSO

IUP::Vbox, IUP::Hbox

The original doc: iupgridbox.html