# Copyright 2007, 2008, 2009, 2010, 2011 Kevin Ryde
# This file is part of Gtk2-Ex-History.
#
# Gtk2-Ex-History is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the Free
# Software Foundation; either version 3, or (at your option) any later
# version.
#
# Gtk2-Ex-History is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License along
# with Gtk2-Ex-History. If not, see <http://www.gnu.org/licenses/>.
package Gtk2::Ex::History::Menu;
use 5.008;
use strict;
use warnings;
use Gtk2 1.220;
use Scalar::Util;
use Glib::Ex::ObjectBits;
use Gtk2::Ex::History;
use Gtk2::Ex::MenuView;
use Locale::TextDomain ('Gtk2-Ex-History');
use Locale::Messages;
BEGIN {
Locale::Messages::bind_textdomain_codeset ('Gtk2-Ex-History','UTF-8');
Locale::Messages::bind_textdomain_filter ('Gtk2-Ex-History',
\&Locale::Messages::turn_utf_8_on);
}
use Gtk2::Ex::Dashes::MenuItem;
# uncomment this to run the ### lines
#use Smart::Comments;
our $VERSION = 8;
use Glib::Object::Subclass
'Gtk2::Ex::MenuView',
signals => { item_create_or_update => \&_do_item_create_or_update,
activate => \&_do_activate,
},
properties => [ Glib::ParamSpec->object
('history',
__('History object'),
'The history object to present and act on.',
'Gtk2::Ex::History',
Glib::G_PARAM_READWRITE),
Glib::ParamSpec->enum
('way',
'Which way',
'Which way of the history to present, either back or forward.',
'Gtk2::Ex::History::Way',
'back',
Glib::G_PARAM_READWRITE),
];
sub INIT_INSTANCE {
my ($self) = @_;
my $dashesitem = Gtk2::Ex::Dashes::MenuItem->new (visible => 1);
$dashesitem->signal_connect (activate => \&_do_dashesitem_activate);
$self->prepend ($dashesitem);
Glib::Ex::ObjectBits::set_property_maybe
($dashesitem,
# tooltip-text new in Gtk 2.12
tooltip_text => __('Open the back/forward history dialog'));
}
sub SET_PROPERTY {
my ($self, $pspec, $newval) = @_;
my $pname = $pspec->get_name;
$self->{$pname} = $newval; # per default GET_PROPERTY
if ($pname eq 'history' || $pname eq 'way') {
my $history = $self->{'history'};
$self->set (model => $history && $history->model($self->get('way')));
#### History-Menu model: $self->get('model')
}
}
# 'activate' signal handler on Dashes::MenuItem tearoff
sub _do_dashesitem_activate {
my ($dashesitem) = @_;
my $self = $dashesitem->get_parent || return; # if orphaned somehow
require Gtk2::Ex::History::Dialog;
Gtk2::Ex::History::Dialog->popup ($self->{'history'}, $self);
}
# 'item-create-or-update' class closure handler
sub _do_item_create_or_update {
my ($self, $item, $model, $path, $iter) = @_;
#### History-Menu _do_item_create_or_update(): $path->to_string
$item ||= Gtk2::MenuItem->new_with_label ('');
my $place = $model->get ($iter, 0);
if (my $history = $self->{'history'}) {
# should always have the history obj when still have model ...
$item->get_child->set_use_markup ($history->get('use-markup'));
$place = $history->signal_emit ('place-to-text', $place);
}
$item->get_child->set_text ($place);
return $item;
}
# 'activate' class closure handler
sub _do_activate {
my ($self, $item, $model, $path, $iter) = @_;
my $history = $self->{'history'} || return;
my $way = $self->get('way');
my $n = ($path->get_indices)[0];
$history->$way ($n+1);
}
sub new_popup {
my ($class, %options) = @_;
### History-Menu new_popup()
my $event = delete $options{'event'};
my $self = $class->new (%options);
my $button = 0;
my $time = 0;
if ($event) {
if ($event->can('button')) {
$button = $event->button;
}
if ($event->can('time')) {
$time = $event->time;
}
if (my $window = $event->window) {
$self->set_screen ($window->get_screen);
}
}
### screen: $self->get_screen->make_display_name
### $button
### $time
$self->popup (undef, undef, undef, undef, $button, $time);
return $self;
}
1;
__END__
=for stopwords tearoff popup enum Ryde Gtk2-Ex-History
=head1 NAME
Gtk2::Ex::History::Menu -- menu of "back" or "forward" history items
=for test_synopsis my ($my_history)
=head1 SYNOPSIS
use Gtk2::Ex::History::Menu;
my $my_menu = Gtk2::Ex::History::Menu->new
(history => $my_history,
way => 'forward');
=head1 OBJECT HIERARCHY
C<Gtk2::Ex::History::Menu> is a subclass of C<Gtk2::Ex::MenuView>, though
that's only really an implementation detail and the suggestion is not to
rely on more than <Gtk2::Menu>.
Gtk2::Widget
Gtk2::Container
Gtk2::MenuShell
Gtk2::Menu
Gtk2::Ex::MenuView
Gtk2::Ex::History::Menu
=head1 DESCRIPTION
A C<Gtk2::Ex::History::Menu> presents a menu of either the "back" or
"forward" choices from a C<Gtk2::Ex::History> object. This menu is shown by
C<Gtk2::Ex::History::Button> and C<Gtk2::Ex::History::MenuToolButton>.
Selecting an item makes the History go back or forward to that item.
+--------------------+
| --- --- --- --- |
| Thing last visited |
| The thing before |
| An old thing |
+--------------------+
The dashed tearoff item opens a C<Gtk2::Ex::History::Dialog>. If there's no
items to go "back" or "forward" then that tearoff is all that's in the menu.
=head1 FUNCTIONS
=over 4
=item C<< $histmenu = Gtk2::Ex::History::Menu->new (key => value, ...) >>
Create and return a new history menu. Optional key/value pairs set initial
properties as per C<< Glib::Object->new >>. The C<history> property should
be set to say what to display, and C<way> for back or forward.
my $menu = Gtk2::Ex::History::Menu->new
(history => $my_history,
way => 'forward');
=item C<< $histmenu = Gtk2::Ex::History::Menu->new_popup (key => value, ...) >>
Create and popup a new history menu. The key/value parameters set initial
properties, plus an additional
event => Gtk2::Gdk::Event object or undef
If the event has C<button> and C<time> fields then they're used for the menu
popup, and if the C<window> field is set then that gives the screen
(C<Gtk2::Gdk::Screen>) the menu pops up on. For example,
sub my_button_press_handler {
my ($self, $event) = @_;
Gtk2::Ex::History::Menu->new_popup (history => $my_history,
way => 'back',
event => $event);
return Gtk2::EVENT_PROPAGATE; # other handlers
}
=back
=head1 PROPERTIES
=over 4
=item C<history> (C<Gtk2::Ex::History> object, default C<undef>)
The history object to display.
=item C<way> (enum C<Gtk2::Ex::History::Way>, default 'back')
The direction to display, either "back" or "forward".
=back
=head1 SEE ALSO
L<Gtk2::Ex::History>,
L<Gtk2::Ex::History::Button>,
L<Gtk2::Ex::History::MenuToolButton>,
L<Gtk2::Ex::History::Dialog>,
L<Gtk2::Ex::MenuView>,
L<Gtk2::Ex::Dashes::MenuItem>
=head1 HOME PAGE
L<http://user42.tuxfamily.org/gtk2-ex-history/index.html>
=head1 LICENSE
Gtk2-Ex-History is Copyright 2010, 2011 Kevin Ryde
Gtk2-Ex-History is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later
version.
Gtk2-Ex-History is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
Gtk2-Ex-History. If not, see L<http://www.gnu.org/licenses/>.
=cut
