view release on metacpan or  search on metacpan

lib/Chandra/ContextMenu.pm  view on Meta::CPAN

package Chandra::ContextMenu;

use strict;
use warnings;

use Chandra ();

our $VERSION = '0.24';

1;

__END__

=head1 NAME

Chandra::ContextMenu - Context menus for Chandra applications

=head1 SYNOPSIS

    use Chandra::App;

    my $app = Chandra::App->new(title => 'My App');

    # Quick static context menu
    $app->context_menu('#editor', [
        { label => 'Cut',   action => sub { cut() },   shortcut => 'Ctrl+X' },
        { label => 'Copy',  action => sub { copy() },  shortcut => 'Ctrl+C' },
        { label => 'Paste', action => sub { paste() }, shortcut => 'Ctrl+V' },
        { separator => 1 },
        { label => 'Select All', action => sub { select_all() }, shortcut => 'Ctrl+A' },
    ]);

    # Dynamic context menu (items generated per right-click)
    $app->context_menu('.file-item', sub {
        my ($target) = @_;
        return [
            { label => "Open",   action => sub { open_file($target) } },
            { label => 'Rename', action => sub { rename_file($target) } },
            { label => 'Delete', action => sub { delete_file($target) } },
        ];
    });

    # Advanced usage via instance
    my $menu = $app->context_menu_instance;
    $menu->attach_global;
    $menu->add_item({ label => 'About', action => sub { show_about() } });

    $app->run;

=head1 DESCRIPTION

Chandra::ContextMenu provides HTML-based right-click context menus for
Chandra applications. Menus support nested submenus, separators, disabled
items, checkable items, icons, and keyboard shortcut hints.

Menus can be attached to specific CSS selectors or globally to the
entire document. Items can be static (defined at creation) or dynamic
(generated per right-click via a callback).

=head1 METHODS

=head2 new

    my $menu = Chandra::ContextMenu->new(
        app   => $app,
        items => \@items,
    );

Create a new context menu. C<items> is an arrayref of item hashrefs.

=head2 attach

    $menu->attach('#selector');
    $menu->attach('.class', sub { my ($target) = @_; return \@items });

Attach the menu to elements matching the CSS selector. An optional
coderef generates items dynamically on each right-click.

=head2 detach

    $menu->detach('#selector');

Remove the menu from a selector.

=head2 attach_global

    $menu->attach_global;
    $menu->attach_global(sub { ... });

Attach the menu to the entire document.

=head2 detach_global

    $menu->detach_global;

Remove the global attachment.

=head2 show_at

    $menu->show_at($x, $y);

Programmatically show the menu at the given coordinates.

=head2 set_item

    $menu->set_item('Delete', disabled => 0);

Update properties of an item by label.

=head2 add_item

    $menu->add_item({ label => 'New', action => sub { ... } });

Append an item to the menu.

=head2 remove_item

    $menu->remove_item('New');

Remove an item by label.

=head2 items

    my $items = $menu->items;