The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
=for comment based on iup-3.5 - http://www.tecgraf.puc-rio.br/iup/en/elem/iupsbox.html

=head1 NAME

IUP::Sbox - [GUI element] container for expanding/contracting the child size in one direction

=head1 DESCRIPTION

Creates a void container that allows its child to be resized. Allows
expanding and contracting the child B<size> in one direction.

It does not have a native representation but it contains also a
L<IUP::Canvas> to implement the bar handler.

=begin HTML

<p>
  <table border="1">
    <tbody align="center">    
        <tr>
	  <th>Natural Size</th>
	  <th>After Expanding the Sbox</th>
	  <th>Expanding the Dialog</th>
	  <th>After Expanding the Sbox</th>
	</tr>
	<tr>
	  <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupsbox1.png"></td>
	  <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupsbox2.png"></td>
	  <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupsbox3.png"></td>
	  <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupsbox4.png"></td>
	</tr>
    </tbody>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

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

B<child:> (named parameter) List of the references to elements (or just a single element) that 
will receive the box. It can be C<undef> or ommited. 

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<COLOR>

Changes the color of the bar handler. The value should be
given in "R G B" color style. Default: "192 192 192".

=item B<DIRECTION>

I<(creation only)>

Indicates the direction of the resize and
the position of the bar handler. Possible values are "NORTH", "SOUTH"
(vertical direction), "EAST" or "WEST" (horizontal direction). Default:
"EAST".

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

I<(non inheritable)>

It will expand automatically only in the direction opposite to the handler.

=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<SIZE|IUP::Manual::03_Attributes/SIZE>,
L<RASTERSIZE|IUP::Manual::03_Attributes/RASTERSIZE>,
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 controls that you want to be resized must have the EXPAND=YES
attribute set. The control inside the sbox will not be resized with a
size lesser than its B<Natural> size. See the L<IUP::Manual::05_DialogLayout> for mode details on sizes.

The L<IUP::Canvas|IUP::Canvas> bar handler is always the first child of the sbox. It
can be obtained using L<GetChild|IUP::Manual::02_Elements/"GetChild()"> or L<GetNextChild|IUP::Manual::02_Elements/"GetNextChild()">.

L<IUP::Sbox|IUP::Sbox> can be resized above the maximum size so some controls go to
outside the dialog area at right or bottom. In fact this is part of the
dynamic layout default reposition of controls inside the dialog. See
the L<Refresh|IUP::Manual::02_Elements/"Refresh()"> function. The IUP layout does not have a maximum
limit only a minimum, except if you use the MAXSIZE common attribute.

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()">.

=head1 EXAMPLES


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

=over

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

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

=back 



=head1 SEE ALSO

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

=cut