=for comment based on iup-3.5

=head1 NAME

IUP::Menu - [GUI element] menu which can group 3 types of elements: item, submenu, separator

=head1 DESCRIPTION

Creates a menu element, which groups 3 types of interface elements:
item, submenu and separator. Any other interface element defined inside
a menu will be an error.

=begin HTML

<p>
  <table border="1">
    <tbody align="center">
      <tr>
        <th>GTK</th>
        <th>Motif</th>
        <th>Windows Classic</th>
        <th>Windows w/ Style</th>
      </tr>
      <tr>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_gtk.png"></td>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_mot.png"></td>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_win2k.png"></td>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_winxp.png"></td>
      </tr>
      <tr>
        <th>RADIO=YES</th>
        <th>RADIO=YES</th>
        <th>RADIO=YES</th>
        <th>RADIO=YES</th>
      </tr>      
      <tr>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_gtk_radio.png"></td>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_mot_radio.png"></td>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_win2k_radio.png"></td>
        <td><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_winxp_radio.png"></td>
      </tr>
    </tbody>
  </table>
</p>
<p><img src="http://kmx.github.com/perl-iup/img-3.5/elem/iupmenu_fromsyntax.png"></p>

=end HTML

=head1 USAGE

=head2 CREATION - new() method

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

B<child:> (named parameter) List of the references to elements (or just a single element) that 
will be grouped by the menu.

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

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

The background color of the menu, affects all items in the menu. 

=item * B<X<RADIO>RADIO> (non inheritable)

Enables the automatic toggle of one
child item. When a child item is selected the other item is
automatically deselected. The menu acts like a L<IUP::Radio|IUP::Radio> for its
children. Submenus and their children are not affected.

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

In Windows, returns the HMENU of the menu.

=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<OPEN_CB|IUP::Manual::04_Callbacks/OPEN_CB>

Called just before the menu is opened.

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

Called just after the menu is closed.

=back

The following L<common callbacks|IUP::Manual::04_Callbacks/Common Callbacks> are also accepted:

=over

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

=back

=head1 NOTES

A menu can be a menu bar of a dialog, defined by the dialog's MENU
attribute, or a popup menu.

A popup menu is displayed for the user using the L<Popup|IUP::Manual::02_Elements/"Popup()"> function
(usually on the mouse position) and disappears when an item is
selected.

L<Destroy|IUP::Manual::02_Elements/"Destroy()"> should be called only for popup menus. Menu bars
associated with dialogs are automatically destroyed when the dialog is
destroyed. But if you change the menu of a dialog for another menu, the
previous one should be destroyed using L<Destroy|IUP::Manual::02_Elements/"Destroy()">. If you replace a
menu bar of a dialog, the previous menu is unmapped.

Any item inside a menu bar can retrieve attributes from the dialog
using L<GetAttribute|IUP::Manual::02_Elements/"GetAttribute()">. It is not necessary to call L<GetDialog|IUP::Manual::02_Elements/"GetDialog()">.

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

=over

=item * L<0-basic/dialog2.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/0-basic/dialog2.pl> - IUP::Dialog example

=item * L<0-basic/item.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/0-basic/item.pl> - IUP::Item Example

=item * L<0-basic/layoutdialog.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/0-basic/layoutdialog.pl> - IUP::LayoutDialog example

=item * L<0-basic/menu.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/0-basic/menu.pl> - IUP::Menu example

=item * L<0-basic/separator.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/0-basic/separator.pl> - IUP::Separator example

=item * L<0-basic/submenu.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/0-basic/submenu.pl> - IUP::Submenu example

=item * L<0-basic/tray.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/0-basic/tray.pl> - IUP::Dialog + TRAY / TRAYTIP / TRAYIMAGE example

=item * L<1-apps/app-mdi.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/1-apps/app-mdi.pl> - IUP app example

=item * L<1-apps/app-sample1.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/1-apps/app-sample1.pl> - example used for screenshot - IUP.pod

=item * L<1-apps/app-sample2.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/1-apps/app-sample2.pl> - example based on the original sample.c

=item * L<1-apps/app-simple-demo.pl|http://cpansearch.perl.org/src/KMX/IUP-0.002_08/examples/1-apps/app-simple-demo.pl> - example used for screenshot - IUP.pod

=back 



=head1 SEE ALSO

L<IUP::Dialog|IUP::Dialog>, L<IUP::Item|IUP::Item>,
L<IUP::Separator|IUP::Separator>, L<IUP::Submenu|IUP::Submenu>,
L<Popup|IUP::Manual::02_Elements/"Popup()">,
L<Destroy|IUP::Manual::02_Elements/"Destroy()">

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

=cut