Kevin Ryde > Gtk2-Ex-Xor-22 > Gtk2::Ex::Lasso

Download:
Gtk2-Ex-Xor-22.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 22   Source  

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 { some_code() });
 $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" below), normally called from a button press or keypress event handler. When started from a button the lasso is active while the button is held down, ie. a drag. This is usual, but it 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" lets you move the initial corner if you didn't start at the right spot or change your mind. (This swap is only possible in Gtk 2.8 and up.)

See examples/lasso-area.pl in the Gtk2-Ex-Xor sources for a complete sample program.

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 with $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 so that end can use it for a final X,Y position and for a server timestamp if ungrabbing. Both are important if event processing in the client is slow for any reason.

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

For Gtk 2.6 and earlier there's no warp available and currently this method does nothing there.

PROPERTIES ^

widget (a Gtk2::Widget or undef)

The target widget to act on. This can be changed to act on a different widget. It works even when the lasso is active, though changing while active stands a good chance of confusing the user.

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)
foreground-name (string, default undef)
foreground-gdk (Gtk2::Gdk::Color object, default undef)

The colour for the lasso. This can be

  • undef (the default) for the widget style fg foreground colour (see Gtk2::Style).
  • A string colour name or #RGB form per Gtk2::Gdk::Color->parse (see Gtk2::Gdk::Color).
  • A Gtk2::Gdk::Color object with red, green, blue fields set. (A pixel value is looked up for the widget in use.)

All three foreground, foreground-name and foreground-gdk access the same underlying setting. foreground-name and foreground-gdk exist for use with Gtk2::Builder where the generic scalar foreground property can't be set.

In the current code, if the foreground is a Gtk2::Gdk::Color object then foreground-name reads as its to_string like "#11112222333", or if foreground is a string name then foreground-gdk reads as parsed to a Gtk2::Gdk::Color. Is this a good idea? Perhaps it will change in the future.

cursor (scalar, default "hand1")
cursor-name (string, cursor enum nick or "invisible", default "hand1")
cursor-object (Gtk2::Gdk::Cursor)

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 different cursor 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. The default "hand1" is meant to be reasonable.

The cursor-name and cursor-object properties access the same underlying cursor setting but with string or cursor object type respectively. They can be used from a Gtk2::Builder specification.

If using a Gtk2::Gdk::Cursor object remember that cursor objects are a per-display resource and it must be on the same display as the target widget.

The cursor can be changed while the lasso is active. Doing so is probably unusual but works and might be used for something creative like further visual feedback or maybe keeping an arrow outwards so as not to obscure the selected region.

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 (not when aborted). x2,y2 is the corner where the mouse finished, though it's unusual to care which way around the corners are.

aborted, parameters: lasso, userdata

Emitted when a region selection ends by the user aborting, which normally means no action on any region.

BUILDABLE ^

Lasso can be created from Gtk2::Builder the same as other objects. The class name is Gtk2__Ex__Lasso and it will normally be a top-level object with the widget property telling it what to act on.

    <object class="Gtk2__Ex__Lasso" id="mylasso">
      <property name="widget">drawingwidget</property>
      <property name="foreground-name">orange</property>
      <property name="cursor-name">umbrella</property>
      <signal name="ended" handler="do_lasso_ended"/>
    </object>

See examples/lasso-builder.pl in the Gtk2-Ex-Xor sources for a complete program.

The foreground-name property is the best way to control the colour. The generic foreground can't be used because it's a Perl scalar type. foreground-gdk works too since Gtk2::Builder knows how to parse a colour name to a Gtk2::Gdk::Color object, but in that case the Builder also allocates a pixel in the default colormap, which is unnecessary since the Lasso will do that itself on the target widget's colormap.

The cursor-name property is similarly the best way to control the mouse cursor type, if the default hand is not wanted. The generic cursor property can't be used because it's a Perl scalar type. The cursor-object probably can't be used since the Builder doesn't support cursor creation (as of Gtk circa 2.16).

OTHER NOTES ^

The lasso is drawn using xors in the widget window. See Gtk2::Ex::Xor for notes on this.

Keypresses are obtained from the Gtk "snooper" mechanism, so they work even if the lasso target widget doesn't have the focus. 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 events outside the widget window are 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 that's a bit obscure and might change.

If start() wants an explicit grab but can't get it (because another application or button hold down has a grab) then in the current code it carps a warning and continues anyway. Perhaps that will change, though it only affects the slightly unusual case of a keyboard initiated lasso.

SEE ALSO ^

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

HOME PAGE ^

http://user42.tuxfamily.org/gtk2-ex-xor/index.html

LICENSE ^

Copyright 2007, 2008, 2009, 2010, 2011 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/.

syntax highlighting: