NAME

Gtk2::Ex::History -- previously visited things

SYNOPSIS

use Gtk2::Ex::History;
my $history = Gtk2::Ex::History->new;

OBJECT HIERARCHY

Gtk2::Ex::History is a subclass of Glib::Object.

Glib::Object
  Gtk2::Ex::History

DESCRIPTION

A Gtk2::Ex::History object records visited places and allows the user to go "back" and "forward" with control buttons, menus, dialog, including through a UIManager action. (See Gtk2::Ex::History::Button etc.)

A place is any Perl scalar. It could be a byte string filename, a wide-char document name, an object such as a URI, or a little hashref or arrayref to hold multiple bits together identifying a place.

FUNCTIONS

$history = Gtk2::Ex::History->new (key => value, ...)

Create and return a new history object. Optional key/value pairs set initial properties as per Glib::Object->new.

$history->goto ($place)

Set $place as the current place in $history. If the current is different from $place then that previous current is pushed onto the "back" list.

$place = $history->back ()

$place = $history->back ($n)

$place = $history->forward ()

$place = $history->forward ($n)

Go back or forward in $history one place, or a given $n places. The return is the new current place, or undef if nothing further to go to.

$history->remove ($place)

Remove $place from the history.

(At present it's not removed from the "current", only from the back and forward lists. This will probably change ...)

PROPERTIES

current (scalar, default undef)

The current place.

max-history (integer, default 40)

The maximum number of items to record in the history.

SIGNALS

place-to-text (scalar; return string)

This signal is emitted to turn a place object into text to display in the Menu and Dialog user elements. The default is a Perl stringize "$place".

A handler should return a wide-char string. If it's bytes then they're "upgraded" in the usual way (treating the bytes as Latin-1).

For filenames Glib::filename_display_name() (see Glib) gives a reasonable form to display, interpreting non-ASCII in the filesystem locale charset.

See examples/iri.pl in the Gtk2-Ex-History sources for a complete program turning URL internationalized %-encodings into wide characters for display.

place-equal (scalar, scalar; return boolean)

This signal is emitted to check equality of two places. goto and other things use it to avoid pushing multiple copies of the same place onto the history. The default handler compares with Perl eq.

SEE ALSO

Gtk2::Ex::History::Action, Gtk2::Ex::History::Button, Gtk2::Ex::History::Dialog, Gtk2::Ex::History::Menu, Glib::Object

HOME PAGE

http://usr42.tuxfamily.org/gtk2-ex-history/index.html

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 http://www.gnu.org/licenses/.