/ 
Tk-VisualBrowser-0.14
River stage zero No dependents
/ Tk::VisualBrowser

NAME

Tk::VisualBrowser - Visual Browser for image directories

SYNOPSIS

use Tk;
use Tk::VisualBrowser;

my $top = MainWindow->new();

my $vsb = $top->VisualBrowser;

my @PICTURES = qw( f1.jpg f2.jpg f3.gif);

$vsb->configure(
  -rows => 5,  -cols => 6,
  -pictures          => \@PICTURES,
  -thumbnail         => \&thumbnail_handler,
  -special_color         => \&special_color_handler,
  -b1_handler        => \&my_b1_handler,
  -b2_handler        => \&my_b2_handler,
  -b3_handler        => \&my_b3_handler,
  -double_b1_handler => \&my_bdouble_1_handler,
  -double_b2_handler => \&my_bdouble_2_handler,
  -double_b3_handler => \&my_bdouble_3_handler,
);

$vsb->scroll(0);  # scroll to first picture
                  # this will implicitely load the pictures

DESCRIPTION

Tk::VisualBrowser is a megawidget which displays a matrix of (-rows) x (-cols) Labels with thumbnail images. It can be used, for example, to create a visual directory browser for image directories or an interactive program for sorting images (dia-sorter.pl).

The application program must provide a reference to a list of image filenames and a handler which returns the filename of a corresponding thumbnail GIF image for a given image filename. 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 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.

CONFIGURATION

There are the following possibilities for configuring the VisualBrowser:

Rows and Columns

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

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

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

List of Images

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

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

The 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.

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;
}

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 -active_color option. Moving them around will highlight the thumbnail under the cursor with -highlight color to indicate the current insert position.

NOTE: Color options must be specified at the very beginning, when the 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
}

Labels and Balloons

It is possible to use Labels for each image and to have balloon messages on each image (i. e. a small window with text pops up when the cursor hovers over an image). In order to activate this features use the following options:

-use_labels      => 1
-use_balloons    => 1

The default text for labels and balloons are the basenames of the image filenames. You can, however, set the labels and balloon texts indiviually by passing references to corresponding arrays the the VisualBrowser:

-balloon_texts => \@Array_with_balloon_texts
-label_texts   => \@Array_with_label_texts

This may be used, for example, to prepare an array with text for each image which contains the filename and EXIF information for the image.

METHODS

The following methods are available:

my @SELECTED = $vsb->get_selected;

Returns the list of currently selected images. The list contains the filenames of the selected pictures. This might be useful for the creation of a slideshow control file with the names of the selected images.

my @SELECTED = $vsb->get_selected_idx;

Returns the list of currently selected images. The list contains the index numbers, not the filenames.

$vsb->select($idx);

Select specified picture with index $idx. Note that other pictures are not deselected automatically.

$vsb->select_all;

Selectes all pictures together.

$vsb->deselect_all;

Deselectes all pictures.

$vsb->remove_selected;

This command removes the selected images from the list of pictures. Note that the original list is changed because you passed a reference to this list via -pictures.

$vsb->swap_selected;

Swaps two selected pictures. Returns 1 in case of success and 0 otherwise. NOTE: The user must have selected exactly two pictures.

$vsb->scroll(<position>);

Scrolls the VisualBrowser to the specified position. <position> may have the following values:

<number>  adjust the view so that the image with index <number>
          appears in the upper left corner.
"p"       go back one line (previous line)
"pp"      go back one page (previous page)
"n"       scroll forward one line (next line)
"nn"      scroll forward one page (next page)
"l"       scroll to last image

In order to go to the first image, you should use the numeric value 0.

AUTHOR

Lorenz Domke, <lorenz.domke@gmx.de>

BUGS AND KNOWN ISSUES

Sure you will find some ...

Most important: it is not possible to specify the rows and columns during instantiation:

$vb = $parent->VisualBrowser(-rows => 3, -cols => 4);

does not work! You must configure rows and columns after that:

$vb->configure(-rows => 3, -cols => 4);

It is not yet possible to use PNG files or other formats for the thumbnail pictures. Maybe in one of the next releases.

The options -use_labels and -use_balloons must be specified durung instantiation:

$vb = $parent->VisualBrowser(-use_labels => 1, -use_balloons => 1);

It is not possible to change this via $vb->configure.

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Lorenz Domke

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.