Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CursorControl(3)      User Contributed Perl Documentation     CursorControl(3)

       Tk::CursorControl - Manipulate the mouse	cursor programmatically

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

	   # Lock the mouse cursor to $widget

	   # Free the cursor

	   # cursor disappears over $widget

	   # show cursor again over $widget

	   # warp cursor to $widget (jump)

	   # move cursor to $widget

       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.

       Tk::CursorControl does not accept any standard options

       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.

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

	       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.


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


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

       Win32::API is required on Win32 systems.

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

       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.


       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.


       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

       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

       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!


       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


       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.


       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.

       Jack Dunnigan <>.

       Copyright (c) 2002-2004 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.

perl v5.32.1			  2004-04-25		      CursorControl(3)


Want to link to this manual page? Use this URL:

home | help