=for comment based on iup-3.5 - http://www.tecgraf.puc-rio.br/iup/en/elem/iupmenu.html
=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.io/perl-iup/img-3.9/elem/iupmenu_gtk.png"></td>
<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupmenu_mot.png"></td>
<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupmenu_win2k.png"></td>
<td><img src="http://kmx.github.io/perl-iup/img-3.9/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.io/perl-iup/img-3.9/elem/iupmenu_gtk_radio.png"></td>
<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupmenu_mot_radio.png"></td>
<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupmenu_win2k_radio.png"></td>
<td><img src="http://kmx.github.io/perl-iup/img-3.9/elem/iupmenu_winxp_radio.png"></td>
</tr>
</tbody>
</table>
</p>
<p><img src="http://kmx.github.io/perl-iup/img-3.9/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/"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>
The background color of the menu, affects all items in the menu.
=item B<RADIO>
I<(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>
I<(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|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/dialog2.pl> - IUP::Dialog example
=item * L<0-basic/item.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/item.pl> - IUP::Item Example
=item * L<0-basic/layoutdialog.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/layoutdialog.pl> - IUP::LayoutDialog example
=item * L<0-basic/menu.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/menu.pl> - IUP::Menu example
=item * L<0-basic/separator.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/separator.pl> - IUP::Separator example
=item * L<0-basic/submenu.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/submenu.pl> - IUP::Submenu example
=item * L<0-basic/tray.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/0-basic/tray.pl> - IUP::Dialog + TRAY / TRAYTIP / TRAYIMAGE example
=item * L<1-apps/app-mdi.pl|https://metacpan.org/source/KMX/IUP-0.305/examples/1-apps/app-mdi.pl> - IUP app example
=item * L<1-apps/app-sample1.pl|https://metacpan.org/source/KMX/IUP-0.305/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.305/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.305/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