/ 
Tk-CursorControl-0.3
River stage zero No dependents
/ Tk::CursorControl

NAME

Tk::CursorControl - Manipulate the mouse cursor programmatically

SYNOPSIS

use Tk::CursorControl;
$cursor = $main->CursorControl;

# Lock the mouse cursor to $widget
$cursor->confine($widget);

# Free the cursor
$cursor->release;

# cursor disappears over $widget
$cursor->hide($widget);

# show cursor again over $widget
$cursor->show($widget);

# warp cursor to $widget (jump)
$cursor->warpto($widget);

# move cursor to $widget
$cursor->moveto($widget);

DESCRIPTION

Tk::CursorControl is-NOT-a Tk::Widget. Rather, it uses Tk and encompasses a collection of methods used to manipulate the cursor (aka pointer) programmatically from a Tk program.

STANDARD OPTIONS

Tk::CursorControl does not accept any standard options

METHODS

The following methods are available:

$cursor->confine( $widget )

Confine the cursor to stay within the bounding box of $widget.

$cursor->jail( $widget )

Alias for the confine method.

$cursor->release

Release the cursor. Used to restore proper cursor functionality after a confine. Note: $widget does not need to be specified.

$cursor->free

Alias for the release method.

$cursor->hide( @widgets )

Make cursor invisible over each widget in @widgets.

$cursor->show( @widgets )

Make cursor visible over each widget in @widgets. This is used after a hide. Note: Show (capital S) can be used as well.

$cursor->warpto( $widget ?x,y?)

Warp the cursor to the specified (?x,y?) position in $widget. If the x,y values are not specified, then the center of the widget is used as the target.

OR

$cursor->warpto( X,Y )

Warp the cursor to the specified X,Y screen coordinate.

$cursor->moveto( $widget ?x,y?, -time=>integer in milliseconds)

Move the cursor to the specified (?x,y?) position in $widget in -time milliseconds. If the x,y values are not specified, then the center of the widget is used as the target. The -time value defaults to 1000ms (1 second) if not specified. The smaller the time, the faster the cursor will move. The time given will not be exact. See bugs below.

OR

$cursor->moveto( X,Y, -time=>integer in milliseconds)

Move the cursor to the specified X,Y screen coordinate in -time milliseconds. The -time value defaults to 1000ms (1 second) if not specified. The smaller the time, the faster the cursor will move. The time given will not be exact. See bugs below.

DEPENDENCIES

Win32::API is required on Win32 systems.

POSSIBLE USES

Don't e-mail me to debate whether or not a program should warp or hide a cursor. I will give you a few instances where "I think" a module like this could come in handy.

1. Confining a canvas item to remain within the Canvas boundaries on a move. See the cursor demonstration in 'widget'.

2. Giving the user some 'leeway' on clicking near an item. Say, clicking on the picture of a thermometer, warps the cursor to a Tk::Scale (right beside it) which actually controls that thermometer.

3. Confining a window within another window (Tk::MDI will likely be upgraded to 'use Tk::CursorControl')

4. A step by step, show and tell session on 'How to use this GUI'.

5. Make the cursor disappear for a keyboard only Tk::Canvas game.

The key to using this module properly, is subtlety! Don't start making the cursor warp all over the screen or making it disappear sporadically. That is a misuse of the functionality.

For some 'real world' applications which already have these types of functionality, see any Multiple Document Interface (MDI); such as in Excel or Word). Also have a look at the Win32 color chooser. The cursor will be confined to the color palette while the button is pressed. Also, try clicking on the gradient bar to the right of the palette. See what happens to the mouse cursor?! I'll bet you didn't even know that this existed until now.

If you discover another good use for this module, I would definitely like to hear about it ! That is the type of e-mail I would welcome.

BUGS & IDIOSYNCRASIES

Take ONE please!

Tk::CursorControl only allows ONE object per MainWindow! If you try to create more than one, only the first object created will be returned. This will also be true if using a widget or module which already defines a Tk::CursorControl object.

Bindings

Tk::CursorControl internally generates <Enter>, <Leave> and <Motion> bindings for the $widget passed. Any user-defined bindings of the same type for $widget should still get executed. This feature has not been completely tested.

Win32

This module makes heavy use of the ShowCursor and ClipCursor API's on Win32. Be aware that when you change a cursor using the API, you are doing so for your entire system. You, (the programmer) are responsible for generating the show/hide and confine/release commands in the proper order.

For every hide - you *will* want a show. For every confine - you *should* have a release. There are cautionary measures built-in to ensure that the cursor doesn't disappear forever or get locked within a widget.

i.e. A release is automatically called if you try to confine the cursor to two widgets at the same time.

In other words, the last confine always wins!

Unix

The methods for hiding and confining the cursor on Unix-based systems is different than for Win32.

A blank cursor is defined using the Tk::Widget configure method for each widget passed. Two files have been provided for this purpose in the installation - trans_cur.xbm and trans_cur.mask. These files must exist under a Tk->FindINC directory.

Confining a cursor on *nix does not use any sort of API or Xlib calls. Motion events are generated on the toplevel window to confine the cursor to the proper widget. On slow systems, this will make the cursor look like it is attached to the widget sides with a spring. On faster systems, while still there, this bouncing type action is much less noticible.

moveto

The time parameter passed to a moveto method will not be exact. The reason for this is because a crude Tk::After command is used to wait for a very short period. You will find that the actual time taken for the cursor to stop is alway slightly more than the time you specified. This time difference will be greater on slower computers. The time error will also increase for higher time values.

Other

Warping the cursor will cause problems for users of absolute location pointing devices (like graphics tablets). Users of graphics tablets should not use this module.

AUTHOR

Jack Dunnigan <dunniganj@cpan.org>.

Copyright (c) 2002,2003 Jack Dunnigan. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

My thanks to Tk gurus Steve Lidie and Slaven Rezic for their suggestions and their patches. This is my first module on CPAN and I appreciate their help. Thanks to Ala Qumsieh for utilizing the power of my module in Tk::Toolbar.