|$cursor-><B>confineB>( $widget )||
Confine the cursor to stay within the bounding box of $widget.
Release the cursor. Used to restore proper cursor functionality
after a confine. Note: $widget does <B>notB> need to be specified.
|$cursor-><B>hideB>( @widgets )||Make cursor invisible over each widget in @widgets.|
|$cursor-><B>showB>( @widgets )||Make cursor visible over each widget in @widgets. This is used after a <B>hideB>. <B>Note: SB>how (capital S) can be used as well.|
|$cursor-><B>warptoB>( $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-><B>warptoB>( X,Y )||Warp the cursor to the specified X,Y screen coordinate.|
|$cursor-><B>movetoB>( $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-><B>movetoB>( 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.|
Dont 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.
4. A step by step, show and tell session on How to use this GUI.
The key to using this module properly, is subtlety! Dont 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?! Ill bet you didnt 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.
<B>Take ONE please!B>
<B>Tk::CursorControlB> only allows ONE object per MainWindow! If you try to create more than one, <B>only the first object created will be returnedB>. This will also be true if using a widget or module which already defines a Tk::CursorControl object.
<B>Tk::CursorControlB> 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 APIs 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 doesnt disappear forever or get locked within a widget.
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 <B>Tk->FindINCB> 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.
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 <B>moreB> than the time you specified. This time difference will be greater on slower computers. The time error will also increase for higher time values.
Jack Dunnigan <email@example.com>.
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.20.3||CURSORCONTROL (3)||2004-04-25|