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 aGtk2::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, orundef
, or omitted, then the crosshair is active until explicitly stopped with anend
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
orend
above, except you can't pass a button press event. widgets
(array ofGtk2::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
orundef
)-
A single widget to operate on. The
widget
andwidgets
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 singlewidget
. add-widget
(Gtk2::Widget
, write-only)-
Add a widget to those in the crosshair. This is good for use from
Gtk2::Builder
where awidgets
arrayref cannot be set. foreground
(colour scalar, defaultundef
)foreground-name
(string, defaultundef
)foreground-gdk
(Gtk2::Gdk::Color
object, defaultundef
)-
The colour for the crosshair. This can be
undef
(the default) for the widget stylefg
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 withred
,green
,blue
fields set. (A pixel value will be looked up in each widget.)
All three
foreground
,foreground-name
andforeground-gdk
access the same underlying setting.foreground-name
andforeground-gdk
exist for use withGtk2::Builder
where the generic scalarforeground
property can't be set.In the current code, if the foreground is a
Gtk2::Gdk::Color
object thenforeground-name
reads as itsto_string
like "#11112222333", or if foreground is a string name thenforeground-gdk
reads as parsed to aGtk2::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
isundef
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 startmoved
reports the widget currently containing the mouse, orundef
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/.