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

=head1 NAME

IUP::Frame - [GUI element] frame with a title around an interface element

=head1 DESCRIPTION

Creates a Frame interface element, which draws a frame with a title
around an interface element.

=begin HTML

<p>
  <table border="1">
    <col style="background-color: rgb(239, 235, 231);" width="350">
    <col style="background-color: rgb(173, 177, 194);" width="350">
    <tbody align="center">
      <tr>
        <th style="text-align: center;">GTK</th>
        <th style="text-align: center;">Motif</th>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupframe_gtk.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupframe_mot.png"></td>
      </tr>
    </tbody>
  </table>
  <br>
  <table border="1">
    <col style="background-color: rgb(212, 208, 200);" width="350">
    <col style="background-color: rgb(236, 233, 216);" width="350">
    <tbody align="center">
      <tr>
        <th style="text-align: center;">Windows Classic</th>
        <th style="text-align: center;">Windows XP Style</th>
      </tr>
      <tr>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupframe_win2k.png"></td>
        <td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupframe_winxp.png"></td>
      </tr>
    </tbody>
  </table>
</p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

 $frame = IUP::Frame->new(Ihandle *child);

B<child>: Identifier of an interface element which will receive the
frame around. It 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 L<BGCOLOR|IUP::Manual::03_Attributes/BGCOLOR>

ignored, transparent in all
systems. Will use the background color of the native parent. Except if
TITLE is not defined and BGCOLOR is defined before map (can be changed
later), then the frame will have a color background.

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

I<(non inheritable)>

The default
value is "YES".

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

Text title color. Not available
in Windows when using Windows Visual Styles. Default: the global
attribute DLGFGCOLOR.

=item B<SUNKEN>

I<(creation only)>

When not using a title, the frame line
defines a sunken area (lowered area). Valid values: YES or NOI<.>
Default: NO.

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

I<(non inheritable)>

Text the user will
see at the top of the frame. If not defined during creation it can not
be added lately, to be changed it must be at least "" during creation.

=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<SCREENPOSITION|IUP::Manual::03_Attributes/SCREENPOSITION>,
L<POSITION|IUP::Manual::03_Attributes/POSITION>,
L<CLIENTSIZE|IUP::Manual::03_Attributes/CLIENTSIZE>,
L<CLIENTOFFSET|IUP::Manual::03_Attributes/CLIENTOFFSET>,
L<MINSIZE|IUP::Manual::03_Attributes/MINSIZE>,
L<MAXSIZE|IUP::Manual::03_Attributes/MAXSIZE>, L<WID|IUP::Manual::03_Attributes/WID>,
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<MAP_CB|IUP::Manual::04_Callbacks/MAP_CB>

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

=back

=head1 NOTES

In Windows, a Frame with C<TITLE==undef> is not the same control as then
C<TITLE!=undef>. When C<TITLE==undef> it does not have Visual Styles and uses a
sharp rectangle border. When C<TITLE!=undef> it has Visual Styles and the
border is a rounded rectangle. To always use Visual Styles set the
title to "" before mapping, but be aware that a vertical space for the
title will be always reserved at the top border.

The frame 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::Frame> is used in the following sample scripts:

=over

=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/dial.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/dial.pl> - IUP::Dial 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/frame1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/frame1.pl> - IUP::Frame Example

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

=item * L<0-basic/gridbox.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/gridbox.pl> - IUP::GridBox 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/image.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/image.pl> - IUP::Image 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/list1.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/list1.pl> - IUP::List example

=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/radio.pl|https://metacpan.org/source/KMX/IUP-0.303/examples/0-basic/radio.pl> - IUP::Radio example

=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

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

=cut