/ 
Gtk2-Ex-Xor-23
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 { print_pos() });

$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 help 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 see where exactly a 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 already display something like that following the mouse all the time).

When 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 module or application uses of that.

The crosshair is drawn using xors in the widget window (see Gtk2::Ex::Xor). See the examples directory for some variously contrived complete programs.

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 $event is a mouse button press then the crosshair is active as long as that button is pressed. If $event is a keypress, or undef, or omitted, 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 all of them at the same time.

The widgets can be under different toplevel windows, but they should be all on the same screen (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 appropriately).

widget (Gtk2::Widget or undef)

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.

add-widget (Gtk2::Widget, write-only)

Add a widget to those in the crosshair. This is good for use from Gtk2::Builder where a widgets arrayref cannot be set.

foreground (colour scalar, default undef)
foreground-name (string, default undef)
foreground-gdk (Gtk2::Gdk::Color object, default undef)

The colour for the crosshair. This can be

  • undef (the default) for the widget style fg foreground colour in each widget (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 will be looked up in each widget.)

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.

line-width (integer, default 0)

The width in pixels of the crosshair lines. The default 0 means a 1-pixel "fast" line. Usually 1 pixel is enough but 2 or 3 may make the lines more visible on a high resolution screen.

SIGNALS

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

Emitted when the crosshair moves to the given $widget and at 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's window. moved then gives that widget and an X,Y position which might be outside the 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 the original window.

BUILDABLE

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

<object class="Gtk2__Ex__CrossHair" id="mycross">
  <property name="widget">drawingwidget</property>
  <property name="foreground-name">orange</property>
  <signal name="moved" handler="do_cross_moved"/>
</object>

See examples/cross-builder.pl 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. The foreground-gdk works 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 CrossHair will do that itself on the target widget's colormap.

BUGS

no-window widgets don't work properly, but instead should be put in a Gtk2::EventBox or similar windowed widget 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 anyway.

If a crosshair widget's window is partly overlapped by another window then a keyboard mode start with the pointer in that other window isn't recognised as outside the crosshair window. This results in an initial draw but then no updating until the pointer moves into the crosshaired window. It should be possible to do this correctly.

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, 2010, 2011, 2017, 2019 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/.