=for comment based on iup-3.5 - http://www.tecgraf.puc-rio.br/iup/en/elem/iupvbox.html

=head1 NAME

IUP::Vbox - [GUI element] container for composing elements vertically

=head1 DESCRIPTION

Creates a void container for composing elements vertically. It is a box
that arranges the elements it contains from top to bottom.

It does not have a native representation.

=begin HTML

<p><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupvbox_align.png"></p>
<p>
  <table border="1">
    <col style="vertical-align:top;background-color: rgb(236, 233, 216);">
    <col style="vertical-align:top;background-color: rgb(236, 233, 216);">
    <col style="vertical-align:top;background-color: rgb(236, 233, 216);">
    <tbody align="center">
        <tr>
		<th>default layout</th>
		<th>HOMOGENEOUS=YES</th>
		<th>EXPANDCHILDREN=YES</th>
	</tr>
	<tr>
		<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupvbox.png"></td>
		<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupvbox_homogeneous.png"></td>
		<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupvbox_expandchildren.png"></td>
	</tr>
        <tr>
		<th>default layout</th>
		<th>child "2": VISIBLE=NO</th>
		<th>child "2": VISIBLE=NO, FLOATING=YES</th>
	</tr>
	<tr>
		<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupvbox.png"></td>
		<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupvbox_visible.png"></td>
		<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupvbox_floating.png"></td>
	</tr>
    </tbody>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 #standard way
 my $vbox = IUP::Vbox->new( child=>[$elem1, $elem2], ANYATTRIBUTE=>'any value' );
 
 #or with just a single child
 my $vbox = IUP::Vbox->new( child=>$elem, ANYATTRIBUTE=>'any value' );
 
 #or with just 1 parameter (arrayref)
 my $vbox = IUP::Vbox->new( [$elem1, $elem2] );
 
 #or with just 1 parameter (reference to child elements)
 my $vbox = IUP::Vbox->new( $elem );

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

B<Returns:> the identifier of the created element, or C<undef> if an error occurs.

NOTE: You can pass to C<new()> other C<ATTRIBUTE=E<gt>'value'> or C<CALLBACKNAME=E<gt>\&func> pairs relevant
to this element - see L<IUP::Manual::02_Elements|IUP::Manual::02_Elements/"new()">.

=head2 ATTRIBUTES

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

=over

=item B<ALIGNMENT>

I<(non inheritable)>

Horizontally aligns the elements.
Possible values: "ALEFT", "ACENTER", "ARIGHT". Default: "ALEFT".

=item L<EXPAND|IUP::Manual::03_Attributes/EXPAND>

I<(non inheritable*)>

The default
value is "YES". See the documentation of the attribute for EXPAND
inheritance.

=item B<EXPANDCHILDREN>

I<(non inheritable)>

Forces all children to expand
horizontally. Default: "NO". This has the same effect as setting
EXPAND=HORIZONTAL on each child, but their vertical expansion will be
preserved. 

=item B<EXPANDWEIGHT>

I<(non inheritable) B<(at children only)>>

If a child
defines the expand weight, then it is used to multiply the free space
used for expansion. (since iup-3.1)

=item L<FLOATING|IUP::Manual::03_Attributes/FLOATING>

I<(non inheritable) B<(at>
children only)>

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

=item B<GAP, CGAP>

Defines a vertical space in pixels between the children,
=item B<CGAP> is in the same units of the B<SIZE> attribute for the height.
Default "0". (CGAP since iup-3.0)

=item B<NGAP, NCGAP>

I<(non inheritable)>

Same as B<GAP> but are non inheritable. 

=item B<HOMOGENEOUS>

I<(non inheritable)>

Forces all children to get equal
vertical space. The natural size height will be based on the highest
child. Default: "NO". Notice that this does not changes the children
size, only the available space for each one of them to expand. (since iup-3.0)

=item B<MARGIN, CMARGIN>

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

=item B<NMARGIN, NCMARGIN>

I<(non inheritable)>

Same as B<MARGIN> but are non
inheritable. 

=item B<NORMALIZESIZE>

I<(non inheritable)>

normalizes all children natural
size to be the biggest natural size among them. 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". 

=item L<SIZE|IUP::Manual::03_Attributes/SIZE> / L<RASTERSIZE|IUP::Manual::03_Attributes/RASTERSIZE> (non inheritable)

Defines the height of the box. When consulted behaves as the standard
SIZE/RASTERSIZE attributes. The standard format "wxh" can also be used,
but width will be ignored (since iup-3.3).

=item B<WID>

I<(read-only)>

Returns -1 if mapped.

=back

The following L<common attributes|IUP::Manual::03_Attributes/Common Attributes> are also accepted:

=over

=item * L<FONT|IUP::Manual::03_Attributes/FONT>,
L<CLIENTSIZE|IUP::Manual::03_Attributes/CLIENTSIZE>,
L<CLIENTOFFSET|IUP::Manual::03_Attributes/CLIENTOFFSET>,
L<POSITION|IUP::Manual::03_Attributes/POSITION>,
L<MINSIZE|IUP::Manual::03_Attributes/MINSIZE>,
L<MAXSIZE|IUP::Manual::03_Attributes/MAXSIZE>

=back

=head1 NOTES

The box can be created with no elements and be dynamic filled using
L<Append|IUP::Manual::02_Elements/"Append()"> or L<Insert|IUP::Manual::02_Elements/"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.

=head1 EXAMPLES


The element B<IUP::Vbox> is used in the following sample scripts:

=over

=item * L<0-basic/button.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/button.pl> - IUP::Button example

=item * L<0-basic/canvas1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/canvas1.pl> - IUP::Canvas example

=item * L<0-basic/canvas2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/canvas2.pl> - IUP::Canvas example

=item * L<0-basic/canvas3.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/canvas3.pl> - IUP::Canvas example

=item * L<0-basic/cbox.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/cbox.pl> - IUP::Cbox example

=item * L<0-basic/cells_degrade.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/cells_degrade.pl> - IUP::Cells example

=item * L<0-basic/colorbrowser.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/colorbrowser.pl> - IUP::ColorBrowser example

=item * L<0-basic/dial.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/dial.pl> - IUP::Dial example

=item * L<0-basic/dialog1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/dialog1.pl> - IUP::Dialog example

=item * L<0-basic/dialog2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/dialog2.pl> - IUP::Dialog example

=item * L<0-basic/expander.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/expander.pl> - IUP::Expander example

=item * L<0-basic/fill.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/fill.pl> - IUP::Fill Example

=item * L<0-basic/gauge.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/gauge.pl> - IUP::Gauge example

=item * L<0-basic/hbox.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/hbox.pl> - IUP::Hbox example

=item * L<0-basic/idle.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/idle.pl> - IUP->SetIdle Example

=item * L<0-basic/image.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/image.pl> - IUP::Image example

=item * L<0-basic/label.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/label.pl> - IUP::Label and IUP::Link example

=item * L<0-basic/layoutdialog.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/layoutdialog.pl> - IUP::LayoutDialog example

=item * L<0-basic/list2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/list2.pl> - IUP::List example

=item * L<0-basic/matrixlist.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/matrixlist.pl> - IUP::MatrixList example

=item * L<0-basic/matrix_basic.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/matrix_basic.pl> - IUP::Matrix example

=item * L<0-basic/message_clone.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/message_clone.pl>

=item * L<0-basic/plot_advanced.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/plot_advanced.pl> - Plot controls

=item * L<0-basic/progressbar2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/progressbar2.pl> - IUP::ProgressBar example

=item * L<0-basic/progressbar3.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/progressbar3.pl> - IUP::ProgressBar example

=item * L<0-basic/radio.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/radio.pl> - IUP::Radio example

=item * L<0-basic/sbox1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/sbox1.pl> - IUP::Sbox example

=item * L<0-basic/sbox2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/sbox2.pl> - IUP::Sbox example

=item * L<0-basic/tabs1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/tabs1.pl> - IUP::Tabs example 

=item * L<0-basic/tabs3.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/tabs3.pl> - IUP::Tabs example 

=item * L<0-basic/text2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/text2.pl> - IUP::Text example

=item * L<0-basic/text_format.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/text_format.pl> - IUP::Text (formating) example

=item * L<0-basic/toggle.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/toggle.pl> - IUP::Toggle example

=item * L<0-basic/tree1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/tree1.pl> - IUP::Tree example (animals) - using helper methods e.g. TreeAddNodes()

=item * L<0-basic/tree_set_attrs.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/tree_set_attrs.pl> - IUP::Tree example (attributes)

=item * L<0-basic/val.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/val.pl> - IUP::Val example

=item * L<0-basic/vbox.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/vbox.pl> - IUP::Vbox example

=item * L<0-basic/zbox.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/zbox.pl> - IUP::Zbox example

=item * L<1-apps/app-mdi.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-mdi.pl> - IUP app example

=item * L<1-apps/app-plot-demo.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-plot-demo.pl> - dials for zooming

=item * L<1-apps/app-sample1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-sample1.pl> - example used for screenshot - IUP.pod

=item * L<1-apps/app-sample2.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-sample2.pl> - example based on the original sample.c

=item * L<1-apps/app-simple-demo.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/1-apps/app-simple-demo.pl> - example used for screenshot - IUP.pod

=back 



=head1 SEE ALSO

L<IUP::Zbox|IUP::Zbox>, L<IUP::Hbox|IUP::Hbox>

The original doc: L<iupvbox.html|http://www.tecgraf.puc-rio.br/iup/en/elem/iupvbox.html>
 

=cut