/ 
Gtk2-Ex-Xor-2
River stage one • 1 direct dependent • 1 total dependent
/ Gtk2::Ex::Lasso

NAME

Gtk2::Ex::Lasso -- drag the mouse to lasso a rectangular region

SYNOPSIS

use Gtk2::Ex::Lasso;
my $lasso = Gtk2::Ex::Lasso->new (widget => $widget);
$lasso->signal_connect (ended => sub { ... });
$lasso->start ($event);

OBJECT HIERARCHY

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

Glib::Object
  Gtk2::Ex::Lasso

DESCRIPTION

A Gtk2::Ex::Lasso object implements a "lasso" style user selection of a rectangular region in a widget window, drawing dashed lines as visual feedback while selecting.

+-------------------------+
|                         |
|   +-----------+         |
|   |           |         |
|   |           |         |
|   +-----------*         |
|                \mouse   |
|                         |
|                         |
+-------------------------+

The lasso is activated by the start function (see "FUNCTIONS"). You setup your button press or keypress code to call that. When started from a button the lasso is active while the button is held down, ie. a drag. This is the usual way, but you can also begin from a keypress, or even something strange like a menu entry.

The following keys are recognised while lassoing,

Return      end selection
Esc         abort the selection
Space       swap the mouse pointer to the opposite corner

Other keys are propagated to normal processing. The space to "swap" is designed to let you move the opposite corner if you didn't start at the right spot, or change your mind.

FUNCTIONS

Gtk2::Ex::Lasso->new (key => value, ...)

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

my $ch = Gtk2::Ex::Lasso->new (widget => $widget);
$lasso->start ()
$lasso->start ($event)

Start a lasso selection on $lasso. If $event is a Gtk2::Gdk::Event::Button then releasing that button ends the selection. For other event types or for undef or omitted the selection ends only with the Return key or an end call.

$lasso->end ()
$lasso->end ($event)

End the $lasso selection and emit the ended signal, or if $lasso is already inactive then do nothing. This is the user Return key or button release.

If you end a lasso in response to a button release, another button press, a motion notify, or similar, then pass the Gtk2::Gdk::Event as the optional $event parameter. end will use it for a final X,Y position, and for a server timestamp if ungrabbing. This can be important if event processing is a bit lagged.

$lasso->abort ()

Abort the $lasso selection and emit the aborted signal, or if $lasso is already inactive then do nothing. This is the user Esc key.

$lasso->swap_corners()

Swap the mouse pointer to the opposite corner of the selection, by a "warp" of the pointer (ie. a forcible movement). This is the user Space key.

PROPERTIES

widget (a Gtk2::Widget, or undef)

The target widget to act on.

active (boolean, default false)

True while lasso selection is in progress. Turning this on or off is the same as calling start or end above (except you can't pass events).

foreground (scalar, default undef)

The foreground colour to draw the lasso. This can be a string name (or hexadecimal RGB), a Gtk2::Gdk::Color object with an allocated pixel value, or undef for the widget's Gtk2::Style foreground.

cursor (scalar, default "hand1")

The mouse cursor type to display while lassoing. This can be any string or object understood by Gtk2::Ex::WidgetCursor, or undef for no cursor change.

A cursor change is highly desirable because when starting a lasso it's normally too small for the user to see and so really needs another visual indication that selection has begun.

SIGNALS

moved, parameters: lasso, x1, y1, x2, y2, userdata

Emitted whenever the in-progress selected region changes (but not when it ends). x2,y2 is the corner with the mouse.

ended, parameters: lasso, x1, y1, x2, y2, userdata

Emitted when a selection is complete and accepted by the user (as opposed to aborted). x2,y2 is the corner where the mouse finished (though it's unusual to care which is which).

aborted, parameters: lasso, userdata

Emitted when a region selection ends by the user wanting to abort, meaning basically wanting no action on the region.

OTHER NOTES

The lasso is drawn with an XOR between the requested foreground and a background established by Gtk2::Ex::Xor. This is fast and portable but only really suitable for a widget with a single dominant background pixel.

Expose events during lasso selection work, though they assume the target widget's expose redraws only the expose event region given, as opposed to doing a full window redraw. Clipping the redraw is usual, and indeed desirable.

Keypresses are obtained from the Gtk "snooper" mechanism, so they work even if the lasso target widget doesn't have the focus, including when it's a no-focus widget. Keys not for the lasso are propagated in the usual way.

When the lasso is started from a keypress etc, not a button drag, an explicit pointer grab is used so motion outside the widget window can be seen. In the current code a further start call with a button press event will switch to drag mode, so the corresponding release has the expected effect. But maybe that's a bit obscure, so perhaps in the future the way this works will change.

BUGS

Changing the widget property works, but doing so while the lasso is active is unlikely to be good for the user.

SEE ALSO

Gtk2::Ex::CrossHair, Glib::Object, Gtk2::Ex::WidgetCursor,

HOME PAGE

http://www.geocities.com/user42_kevin/gtk2-ex-xor/index.html

LICENSE

Copyright 2007, 2008 Kevin Ryde

Gtk2-Ex-Xor 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-Xor 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-Xor. If not, see http://www.gnu.org/licenses/.