/ 
Gtk2-Ex-Xor-7
River stage one • 1 direct dependent • 1 total dependent
/ Gtk2::Ex::CrossHair

NAME

Gtk2::Ex::CrossHair -- crosshair lines drawn following the mouse

SYNOPSIS

use Gtk2::Ex::CrossHair;
my $crosshair = Gtk2::Ex::CrossHair->new (widgets => [$w1,$w2]);
$crosshair->signal_connect (moved => sub { ... });

$crosshair->start ($event);
$crosshair->end ();

OBJECT HIERARCHY

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

Glib::Object
  Gtk2::Ex::CrossHair

DESCRIPTION

A CrossHair object draws a horizontal and vertical line through the mouse pointer position on top of one or more widgets' existing contents. This is intended as a visual guide for the user.

+-----------------+
|         |       |
|         | mouse |
|         |/      |
| --------+------ |
|         |       |
|         |       |
|         |       |
|         |       |
+-----------------+
+-----------------+
|         |       |
|         |       |
|         |       |
+-----------------+

The idea is to see relative positions. For example in a graph the horizontal line helps you see which of two peaks is the higher, and the vertical line can extend down to (or into) an X axis scale to help see where exactly a particular part of the graph lies.

The moved callback lets you update a text status line with a position in figures, etc (if you don't display something like that already, following the mouse all the time).

While the crosshair is active the mouse cursor is set invisible in the target windows, since the cross is enough feedback and a cursor tends to obscure the lines. This is done with the WidgetCursor mechanism (see Gtk2::Ex::WidgetCursor) and so cooperates with other widget or application uses of that.

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

FUNCTIONS

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

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

my $ch = Gtk2::Ex::CrossHair->new (widgets => [ $widget ],
                                   foreground => 'orange');
$crosshair->start ()
$crosshair->start ($event)
$crosshair->end ()

Start or end crosshair display.

For start the optional $event is a Gtk2::Gdk::Event. If it's a mouse button press then the crosshair is active as long as that button is pressed. If $event is a keypress, or undef, or not given, then the crosshair is active until explicitly stopped with an end call.

PROPERTIES

active (boolean)

True when the crosshair is to be drawn, moved, etc. Turning this on or off is the same as calling start or end above, except you can't pass a button press event.

widgets (array of Gtk2::Widget)

An arrayref of widgets to draw on. Often this will be just one widget, but multiple widgets can be given to draw in them all at the same time.

Widgets can be under different toplevels, but they should be all on the same screen (ie. Gtk2::Gdk::Screen) since mouse pointer movement in any of them is taken to be a position to draw through all of them (with coordinates translated).

widget (Gtk2::Widget)

A single widget to operate on. The widget and widgets properties access the same underlying set of widgets to operate on, you can set or get whichever best suits. But if there's more than one widget you can't get from the single widget.

foreground (colour scalar, default undef)

The colour for the crosshair. This can be

  • A string colour name or #RGB form per Gtk2::Gdk::Color->parse (see Gtk2::Gdk::Color).

  • A Gtk2::Gdk::Color object.

  • undef (the default) for the widget style fg foreground colour in each widget (see Gtk2::Style).

SIGNALS

moved (parameters: crosshair, widget, x, y, userdata)

Emitted when the crosshair moves to the given $widget and X,Y coordinates within that widget (widget relative coordinates). $widget is undef if the mouse moves outside any of the crosshair widgets.

It's worth noting a subtle difference in moved reporting when a crosshair is activated from a button or from the keyboard. A button press causes an implicit grab and all events are reported to that widget window. moved then gives that widget and an X,Y position which might be outside its window area (eg. negative). But for a keyboard or programmatic start moved reports the widget currently containing the mouse, or undef when not in any. Usually the button press grab is good thing, it means a dragged button keeps reporting about its original window.

BUGS

no-window widgets don't work properly, but instead should be put in a Gtk2::EventBox and that passed to the crosshair.

Parent window movement, including toplevel window movement, isn't noticed immediately, leaving the drawn crosshair away from the mouse. The next mouse movement updates all widgets though, and often parent widget moves provoke a redraw which will update the crosshair too.

SEE ALSO

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

HOME PAGE

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

LICENSE

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