NAME
    Tk::ToolBar - A toolbar widget for Perl/Tk

SYNOPSIS
            use Tk;
            use Tk::ToolBar;

            my $mw = new MainWindow;
            my $tb = $mw->ToolBar(qw/-movable 1 -side top/);

            $tb->ToolButton  (-text  => 'Button',
                              -tip   => 'tool tip',
                              -command => sub { print "hi\n" });
            $tb->ToolLabel   (-text  => 'A Label');
            $tb->Label       (-text  => 'Another Label');
            $tb->ToolLabEntry(-label => 'A LabEntry',
                              -labelPack => [-side => "left",
                                             -anchor => "w"]);

            MainLoop;

DESCRIPTION
    This module implements a dockable toolbar. It is in the same spirit as
    the "short-cut" toolbars found in most major applications, such as most
    web browsers and text editors (where you find the "back" or "save" and
    other shortcut buttons).

    Buttons of any type (regular, menu, check, radio) can be created inside
    this widget. You can also create Label, Entry and LabEntry widgets.
    Moreover, the ToolBar itself can be made dockable, such that it can be
    dragged to any edge of your window. Dragging is done in "real-time" so
    that you can see the contents of your ToolBar as you are dragging it.
    Furthermore, if you are close to a stickable edge, a visual indicator
    will show up along that edge to guide you. Also, multiple ToolBars are
    embeddable inside each other.

    If you drag a ToolBar to within 15 pixels of an edge, it will stick to
    that edge. If the ToolBar is further than 15 pixels away from an edge,
    but you release it over another ToolBar widget, then it will be embedded
    inside the second ToolBar. You can "un-embed" an embedded ToolBar simply
    by dragging it out. You can change the 15 pixel limit using the -close
    option.

    The ToolBar is supposed to be created as a child of a Toplevel
    (MainWindow is a Toplevel widget) or a Frame. You are free to experiment
    otherwise, but expect the unexpected :-)

WIDGET-SPECIFIC OPTIONS
    The ToolBar widget takes the following arguments:

    -side
        This option tells the ToolBar what edge to *initially* stick to. Can
        be one of 'top', 'bottom', 'left' or 'right'. Defaults to 'top'.
        This option can be set only during object creation. Default is
        'top'.

    -movable
        This option specifies whether the ToolBar is dockable or not. A
        dockable ToolBar can be dragged around with the mouse to any edge of
        the window, subject to the sticky constraints defined by *-sticky*.
        Default is 1.

    -close
        This option specifies, in pixels, how close we have to drag the
        ToolBar an edge for the ToolBar to stick to it. Default is 15.

    -sticky
        This option specifies which sides the toolbar is allowed to stick
        to. The value must be a string of the following characters 'nsew'. A
        string of 'ns' means that the ToolBar can only stick to the north
        (top) or south (bottom) sides. Defaults to 'nsew'. This option can
        be set only during object creation.

WIDGET METHODS
    The following methods are used to create widgets that are placed inside
    the ToolBar. Widgets are ordered in the same order they are created,
    left to right.

    For all widgets, except Labels, a tooltip can be specified via the -tip
    option.

    *$ToolBar*->ToolButton(?-type => *buttonType*,? *options*)
    *$ToolBar*->Button(?-type => *buttonType*,? *options*)
        This method creates a new Button inside the ToolBar. The *-type*
        option can be used to specify what kind of button to create. Can be
        on of 'Button', 'Checkbutton', 'Menubutton', or 'Radiobutton'. A
        tooltip message can be specified via the -tip option. Any other
        options will be passed directly to the constructor of the button.
        The Button object is returned.

    *$ToolBar*->ToolLabel(*options*)
    *$ToolBar*->Label(*options*)
        This method creates a new Label inside the ToolBar. Any options will
        be passed directly to the constructor of the label. The Label object
        is returned.

    *$ToolBar*->ToolEntry(*options*)
    *$ToolBar*->Entry(*options*)
        This method creates a new Entry inside the ToolBar. A tooltip
        message can be specified via the -tip option. Any other options will
        be passed directly to the constructor of the entry. The Entry object
        is returned.

    *$ToolBar*->ToolLabEntry(*options*)
    *$ToolBar*->LabEntry(*options*)
        This method creates a new LabEntry inside the ToolBar. A tooltip
        message can be specified via the -tip option. Any other options will
        be passed directly to the constructor of the labentry. The LabEntry
        object is returned. In horizontal ToolBars, the label of the
        LabEntry widget will be packed to the left of the entry. On vertical
        ToolBars, the label will be packed on top of the entry.

    *$ToolBar*->separator
        This method inserts a separator.

BUGS
    Not really a bug, but a feature ;-) The ToolBar widget assumes that you
    use *pack* in its parent. Actually, it will *pack()* itself inside its
    parent. If you are using another geometry manager, then you *MIGHT* get
    some weird behaviour. I have tested it very quickly, and found no
    surprises, but let me know if you do.

TODO
    I have implemented everything I wanted, and then some. Here are things
    that were requested, but are not implemented yet. If you want more, send
    me requests.

    o   Allow buttons to be "tied" to menu items.

    o   Include some built-in pixmaps for some of the more common
        ToolButtons, like "Save", "New", "Open", etc ..

    o   Allow movable and fixed separators.

    o   Constrain cursor within Toplevel window.

INSTALLATION
    Either the usual:

            perl Makefile.PL
            make
            make install

    or just stick it somewhere in @INC where perl can find it. It's in pure
    Perl.

ACKNOWLEDGEMENTS
    The following people have given me helpful comments and bug reports to
    keep me busy: Chris Whiting, Jack Dunnigan and Robert Brooks.

AUTHOR
    Ala Qumsieh *aqumsieh@cpan.org*

COPYRIGHTS
    This module is distributed under the same terms as Perl itself.