NAME

       Gtk2::ImageView::Tool::Selector -  Image tool for selecting rectangular regions

HIERARCHY

         Glib::Object
         +----Gtk2::ImageView::Tool::Selector

INTERFACES

         Gtk2::ImageView::Tool

DESCRIPTION

       Gtk2::ImageView::Tool::Selector is a tool for selecting areas of an image. It is useful
       for cropping an image, for example. The tool is an implementor of the
       Gtk2::ImageView::Tool inteface which means that it can be plugged into a Gtk2::ImageView
       by using the Gtk2::ImageView::Tool::set_tool() method.

       Gtk2::ImageView::Tool::Selector changes the default display of the Gtk2::ImageView. It
       darkens down the unselected region of the image which provides a nice effect and makes it
       clearer what part of the image that is currently selected. Unfortunately, this effect is
       somewhat incompatible with how Gtk2::ImageView::Nav behaves because that widget will show
       the image without darkening it.

       The tool also changes the default behaviour of the mouse. When a
       Gtk2::ImageView::Tool::Selector is set on a Gtk2::ImageView, mouse presses do not "grab"
       the image and you cannot scroll by dragging. Instead mouse presses and dragging is used to
       resize and move the selection rectangle. When the mouse drags the selection rectangle to
       the border of the widget, the view autoscrolls which is a convenient way for a user to
       position the selection.

       Please note that Gtk2::ImageView::Tool::Selector draws the image in two layers.  One
       darkened and the selection rectangle in normal luminosity. Because it uses two draw
       operations instead one one like Gtk2::ImageView::Tool::Dragger does, it is significantly
       slower than that tool. Therefore, it makes sense for a user of this library to set the
       interpolation to GDK_INTERP_NEAREST when using this tool to ensure that performance is
       acceptable to the users of the program.

   Zoom bug
       There is a small bug in Gtk2::ImageView::Tool::Selector that becomes apparent when the
       zoom factor is greater than about 30. The edge of the selection rectangle may in that case
       intersect a pixel.

       The bug is caused by bug 389832 in gdk-pixbuf. There is no way to solve this bug on
       Gtk2::ImageView's level (but if someone knows how, I'd really like to know).

METHODS

   tool = Gtk2::ImageView::Tool::Selector->new ($view)
       •   $view (Gtk2::ImageView)

       Returns a new selector tool for the specified view with the following default values:

       selection : (0, 0) - [0, 0]

   rectangle = $selector->get_selection
       Returns a Gtk2::Gdk::Rectangle with the current selection. If either the width or the
       height of the selection is zero, then nothing is selected and undef is returned. See
       "selection-changed" for an example.

   $selector->set_selection ($rect)
       •   $rect (Gtk2::Gdk::Rectangle)

       Sets the selection rectangle for the tool. Setting this attribute will cause the widget to
       immidiately repaint itself if its view is realized.

       This method does nothing under the following circumstances:

       If the views pixbuf is undef.
       If rect is wider or taller than the size of the pixbuf
       If rect equals the current selection rectangle.

       If the selection falls outside the pixbufs area, its position is moved so that it is
       within the pixbuf.

       Calling this method causes the ::selection-changed signal to be emitted.

       The default selection is (0,0) - [0,0].

       selector : a Gtk2::ImageView::Tool::Selector
       rect : Selection rectangle in image space coordinates.

PROPERTIES

       'view' (Gtk2::ImageView : default undef : writable / construct-only)
           Image View to navigate

SIGNALS

       selection-changed (Gtk2::ImageView::Tool::Selector)

SEE ALSO

       Gtk2::ImageView, Glib::Object

COPYRIGHT

       Copyright (C) 2007 by Jeffrey Ratcliffe.

       This software is licensed under the GPL-3; see Gtk2::ImageView for a full notice.