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

=head1 NAME

IUP::Expander - [GUI element] container that can interactively show or hide its child

=head1 DESCRIPTION

Creates a void container that can interactively show or hide its child.

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

=begin HTML

<p>
  <table border="1">
    <tbody align="center">
      <tr>
        <td><strong>Container Expanded (STATE = "OPEN")</strong></td>
        <td><strong>Container Collapsed (STATE = "CLOSE")</strong></td>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupexpander_open.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupexpander_close.png"></td>
      </tr>
    </tbody>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 #standard way
 $mlist = IUP::Expander->new( child=>$child, ANYATTRIBUTE=>'any value' );
 #or with just 1 parameter
 $mlist = IUP::Expander->new($child);
 
B<child:> (named parameter) reference to an interface element.

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

I<(non inheritable)> enables the automatic show of the child
when mouse is over the handler more than 1 second. Default: No. See
=item * L<Notes|#Notes> bellow.

=item B<BARSIZE>

I<(non inheritable)> controls the size of the bar handler.
Default: the height of a text line plus 5 pixels.

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

ignored, transparent in all systems. Will use the background color of the native parent.

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

Text color. Default: the global attribute DLGFGCOLOR.

=item B<BARPOSITION>

I<(creation only)> Indicates the bar handler position.
Possible values are "TOP", "BOTTOM", "LEFT" or "RIGHT". Default: "TOP".

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

I<(non inheritable)> The default value is "YES".

=item B<STATE>

I<(non inheritable)> Show or hide the container elements.
Possible values: "OPEN" (expanded) or "CLOSE" (collapsed). Default:
OPEN. Setting this attribute will automatically change the layout of
the entire dialog so the child can be recomposed.

=item B<TITLE>

I<(non inheritable)> the title, shown in the title bar near the
expand or collapse symbol. Shown only when BARPOSITION=TOP.

=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<ACTIVE|IUP::Manual::03_Attributes/ACTIVE>,
L<FONT|IUP::Manual::03_Attributes/FONT>,
L<EXPAND|IUP::Manual::03_Attributes/EXPAND>,
L<SCREENPOSITION|IUP::Manual::03_Attributes/SCREENPOSITION>,
L<POSITION|IUP::Manual::03_Attributes/POSITION>,
L<MINSIZE|IUP::Manual::03_Attributes/MINSIZE>,
L<MAXSIZE|IUP::Manual::03_Attributes/MAXSIZE>,
L<WID|IUP::Manual::03_Attributes/WID>,
L<TIP|IUP::Manual::03_Attributes/TIP>,
L<SIZE|IUP::Manual::03_Attributes/SIZE>,
L<RASTERSIZE|IUP::Manual::03_Attributes/RASTERSIZE>,
L<ZORDER|IUP::Manual::03_Attributes/ZORDER>,
L<VISIBLE|IUP::Manual::03_Attributes/VISIBLE>

=back

=head2 CALLBACKS

For more info about concept of callbacks (setting callback handlers etc.)
see L<IUP::Manual::04_Callbacks|IUP::Manual::04_Callbacks>. Callbacks specific to this element:

=over

=item L<ACTION|IUP::Manual::04_Callbacks/ACTION>

Action generated expander state is interactively changed. (Since iup-3.9)

B<Callback handler prototype:>

 sub action_handler {
   my ($self) = @_;
   #...
 }

B<$self:> reference to the element (IUP::Expander) that activated the event

=back 
  
=head1 NOTES

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

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

When the TITLE is defined and BARPOSITION=TOP then the expand/collapse
symbol is left aligned. In all other situations the expand/collapse symbol is centered.

When AUTOSHOW=Yes the dialog layout is NOT recalculated. The child is
shown on top of the dialog, so the other children will not move or
redraw. After the mouse is move away from the child then it is
automatically hidden. B<IMPORTANT>: this feature will ONLY work if the
child is a native container like L<IUP::Frame>, L<IUP::ScrollBar|IUP::ScrollBar> or
L<IUP::Tabs|IUP::Tabs>.

=head1 EXAMPLES


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

=over

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

=back 



=head1 SEE ALSO

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

=cut