view release on metacpan or  search on metacpan

lib/Tk/VisualBrowser.pm  view on Meta::CPAN

C<Tk::VisualBrowser> displays the thumbnail pictures and provides some
navigation buttons for scrolling linewise or pagewise through the list.
A scrollbar is also attached to the widget.

It is possible to select thumbnails with the left moust button or to
select ranges of thumbnails with shift-click (as you would select files in
normal file browser). Ctrl-click allows adding or removing single thumbnails
from a selection.

The selected thumbnails may be moved around with the left mouse button.
The cursor image changes and all thumbnails which are currently under the
mouse will be highlighted while moving around. Releasing the mouse button
inserts the selected thumbnails before the current position.

When moving around, an automatic scroll up or down is triggered when the
mouse comes close to the upper or lower margin of the C<VisualBrowser>.
But only one linewise scroll is triggered at a time (in order to avoid the
scrollbar from running away). Try going back and forth with the mouse
to trigger further scrolls as needed.

=head1 CONFIGURATION

There are the following possibilities for configuring the C<VisualBrowser>:

=head2 Rows and Columns

Use C<-rows> and C<-cols> to specify the number of rows and columns
of the C<VisualBrowser:>

  $vsb->configure(-rows => 4, -cols => 8);

NOTE: C<-cols> and/or C<-rows> B<must> be configured in order to
get the C<VisualBrowser> up and running: Only when configuring
columns or rows the C<VisualBrowser> will be (re-)built.

=head2 List of Images

The list of images to be displayed is passed as a reference via 
the C<-pictures> option:

  $vsb->configure(-pictures => \@PICTURES);

The C<VisualBrowser> needs GIF images for each image filename in the list.
To this end a handler is specified which returns the name of the
corresponding GIF image when fed with an image filename:

  $vsb->configure(-thumbnail => \&thumbnail_handler);

  sub thumbnail_handler {
    my ($image_filename) = @_;

    # for example: (assuming that the thumbnails are
    # in the same directory but with .gif extension):

    $image_filename =~ s/\.jpg/.gif/i;
    return $image_filename;
  }

It could also be arranged that the thumbnail_handler creates the GIF
images when they do not yet exist. So the viewing of an image directory
would automatically create the thumbnails (with Image::Magick, for example).

NOTE: The names in the @PICTURES array need not be valid filenames, 
although they normally are. The names of the GIF files
provided by the thumbnail_handler must be valid filenames,
either relative to the current working directory or absolute
pathnames.

=head2 Handlers for Mouse Button Events

The application can specify its own handlers for mousebutton events, e. g.:

  $vsb->configure(-doubel_b1_handler => \&my_double_1);

  sub my_double_1 {
    my ($image_filename) = @_;

    # display $image_filename in a Toplevel Window:
    require Tk::JPEG;
    my $show = $top->Toplevel();
    my $image = $top->Photo('-format' => "jpeg", 
                         -file => $image_filename);
    $show->Label(-image => $image)->pack;
  }

=head2 Colors

The following table shows the possible color options:

  -highlight     => "#rrggbb"    color for moving around
  -active_color  => "#rrggbb"    color for selected thumbs
  -bg_color1     => "#rrggbb"    background color for plane
  -bg_color      => "#rrggbb"    background color for thumbs
  -cursor_bg     => "#rrggbb"    background color for cursor
  -cursor_fg     => "#rrggbb"    foreground color for cursor

When you have selected some thumbnails, they are colored with the
C<-active_color> option. Moving them around will highlight the
thumbnail under the cursor with C<-highlight> color to indicate the
current insert position.

NOTE: Color options must be specified at the very beginning, when the
C<VisualBrowser> is instantiated. Later reconfigurations may have no effect.

It is possible to provide a handler which makes sure that certain images
get a different background color (for example to indicate that these
images have been changed recently):

  $vsb->configure(-special_color => \&my_color_hdlr);

  sub my_color_hdlr {
    my ($image_filename) = @_;

    # decide if $image_filname needs to be displayed with a different
    # background color:
    if ( -M $image_filename < 7 ) {
      return "#cc2222"; # use special bg color
    }

    return 0; # no special color
  }