# Generated by PerlDox 0.013

=head1 NAME

Menu::Builder - Simple menu builder for Perl Tk

=head1 SYNOPSIS

    use Tk;
    use Tk::Menu;
    use Menu::Builder;

    my $checkbox;

    my $menuCfg = [
        File => [
            New  => \&FileNew,
            Save => \&FileSave,
            Exit => \&FileExit,
        ],
        Options => [
            Fancy => { -type => 'checkbutton', -variable => \$checkbox },
        ],
        Help => [
            Help  => \&HelpHelp,
            About => \&HelpAbout,
        ],
    ];

    my $mw      = MainWindow->new(-title => 'Menu Builder Test');
    my $menuBar = $mw->Menu(-tearoff => 0);
    $mw->configure(-menu => $menuBar);
    Menu::Builder::BuildMenu($menuBar, $menuCfg);

=head1 DESCRIPTION

This is a tool for quickly and easily building multi-level Menu Systems,
such as, but not limited to, a menubar. The main focus is commands and
cascades. Other menu entry types are also supported.

(Although -menuitems, in Tk::Menu:Item, provides similar functionality,
building cascade menus can get very complicated. This tool simplifies
that, as well as simple commands, while providing means to describe other
menu item types and full options for commands.)

=head2 Defining Menu Systems

A Menu System is defined, to this tool, by an array ref. The referenced
array is a an ordered set of name/value pairs. (Since hashes are unordered,
they do not work for this.) Each pair is taken as an entry name and content.

If the content specifier is a code ref, a commend entry is created with
the specified name and code ref.

If the content specifier is an array ref, a cascade is created with the
specified name and the array is processed into the associated submenu.
Cascades may be nested to an arbitrary width and depth, limited only by
the resources available.

If the content specifier is a hash ref whose hash contains at least a
-type key/value pair, a menu item of the specified name and type is
created, via the add method of Tk::Menu, using the remaining pairs in the
hash as options.

=head2 Functions


=head3 Function BuildMenu

Create the widget tree for the menu.


=head4 Parameter scalar $menu

Reference of Tk::Menu widget in which to build the menu.


=head4 Parameter scalar $desc

Reference of array containing menu description.

=head1 CAVEATS

This module is a tool, not a new widget. You supply it with a reference to
the menu widget to be populated. Additional menu widgets are created as
needed.

=head1 SEE ALSO

C<Tk::Menu>, C<Tk::Menu:Item>

=head1 AUTHOR

RonW of perlmonks.org

=head1 COPYRIGHT

Copyright 2013, RonW of perlmonks.org. All rights reserved.

=head1 LICENSE

This tool is open source software. You may redistribute it and/or modify
it under the same terms as Perl itself.

