view release on metacpan or  search on metacpan

lib/Gtk2/Ex/History.pm  view on Meta::CPAN

# 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;
use 5.008;
use strict;
use warnings;
use Gtk2 1.220;
use POSIX ();
use Scalar::Util;

use Gtk2;
use Glib::Ex::SignalBits;
use Glib::Ex::FreezeNotify;

# uncomment this to run the ### lines
#use Smart::Comments;

our $VERSION = 8;


# place-to-icon-pixbuf
# $h->dialog_class, default sub of self
# $h->dialog_popup (parent => ...)
# $h->menu_popup (parent => ..., way => ..., event => ...)
# MenuBits popup_for_event (parent, event)

# place-to-renderers
# place-to-cellinfo
# place-serialize     \ or Storable freeze
# place-unserialize   /

# place-to-selectiondata
#    default place-to-text
#    flag for set, or emptiness of SelectionData
# selectiondata-to-place
# Gtk2::SelectionData


use Glib::Object::Subclass
  'Glib::Object',
  signals => { 'place-to-text' =>
               { param_types   => ['Glib::Scalar'],
                 return_type   => 'Glib::String',
                 flags         => ['run-last'],
                 class_closure => \&_default_place_to_text,
                 accumulator   => \&Glib::Ex::SignalBits::accumulator_first_defined },

               'place-equal' =>
               { param_types   => ['Glib::Scalar', 'Glib::Scalar'],
                 return_type   => 'Glib::Boolean',
                 flags         => ['run-last'],
                 class_closure => \&_default_place_equal,
                 accumulator   => \&Glib::Ex::SignalBits::accumulator_first },
             },

  properties => [ Glib::ParamSpec->scalar
                  ('current',
                   'Current place object',
                   'Current place object in the history.',
                   Glib::G_PARAM_READWRITE),

                  Glib::ParamSpec->int
                  ('max-history',
                   'Maximum history count',
                   'The maximum number of places to keep in the history (backwards and forwards counted separately currently).',
                   0,                  # min
                   POSIX::INT_MAX(),   # max
                   40,                 # default
                   Glib::G_PARAM_READWRITE),

                  # this one not documented yet ...
                  Glib::ParamSpec->boolean
                  ('use-markup',
                   'Use markup',
                   'Blurb.',
                   0,  # default
                   Glib::G_PARAM_READWRITE),
                ];

BEGIN {
  Glib::Type->register_enum ('Gtk2::Ex::History::Way',
                             back    => 0,
                             forward => 1);
}

lib/Gtk2/Ex/History.pm  view on Meta::CPAN

to hold multiple bits together identifying a place.

=head1 FUNCTIONS

=over 4

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

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

=cut

=item C<< $history->goto ($place) >>

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

=item C<< $place = $history->back () >>

=item C<< $place = $history->back ($n) >>

=item C<< $place = $history->forward () >>

=item C<< $place = $history->forward ($n) >>

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

=item C<< $history->remove ($place) >>

Remove C<$place> from the history.

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

=back

=head1 PROPERTIES

=over 4

=item C<current> (scalar, default C<undef>)

The current place.

=item C<max-history> (integer, default 40)

The maximum number of items to record in the history.

=back

=head1 SIGNALS

=over 4

=item C<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 C<"$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 C<Glib::filename_display_name()> (see L<Glib>) gives a
reasonable form to display, interpreting non-ASCII in the filesystem locale
charset.

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

=item C<place-equal> (scalar, scalar; return boolean)

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

=back

=head1 SEE ALSO

L<Gtk2::Ex::History::Action>,
L<Gtk2::Ex::History::Button>,
L<Gtk2::Ex::History::Dialog>,
L<Gtk2::Ex::History::Menu>,
L<Glib::Object>

=head1 HOME PAGE

L<http://usr42.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