1CursorControl(3)      User Contributed Perl Documentation     CursorControl(3)
2
3
4

NAME

6       Tk::CursorControl - Manipulate the mouse cursor programmatically
7

SYNOPSIS

9           use Tk::CursorControl;
10           $cursor = $main->CursorControl;
11
12           # Lock the mouse cursor to $widget
13           $cursor->confine($widget);
14
15           # Free the cursor
16           $cursor->release;
17
18           # cursor disappears over $widget
19           $cursor->hide($widget);
20
21           # show cursor again over $widget
22           $cursor->show($widget);
23
24           # warp cursor to $widget (jump)
25           $cursor->warpto($widget);
26
27           # move cursor to $widget
28           $cursor->moveto($widget);
29

DESCRIPTION

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

STANDARD OPTIONS

36       Tk::CursorControl does not accept any standard options
37

METHODS

39       The following methods are available:
40
41       $cursor->confine( $widget )
42           Confine the cursor to stay within the bounding box of $widget.
43
44           $cursor->jail( $widget )
45               Alias for the confine method.
46
47       $cursor->release
48           Release the cursor. Used to restore proper cursor functionality
49           after a confine. Note: $widget does not need to be specified.
50
51           $cursor->free
52               Alias for the release method.
53
54       $cursor->hide( @widgets )
55           Make cursor invisible over each widget in @widgets.
56
57       $cursor->show( @widgets )
58           Make cursor visible over each widget in @widgets. This is used
59           after a hide.  Note: Show (capital S) can be used as well.
60
61       $cursor->warpto( $widget ?x,y?)
62           Warp the cursor to the specified (?x,y?) position in $widget. If
63           the x,y values are not specified, then the center of the widget is
64           used as the target.
65
66           OR
67
68       $cursor->warpto( X,Y )
69           Warp the cursor to the specified X,Y screen coordinate.
70
71       $cursor->moveto( $widget ?x,y?, -time=>integer in milliseconds)
72           Move the cursor to the specified (?x,y?) position in $widget in
73           -time milliseconds.  If the x,y values are not specified, then the
74           center of the widget is used as the target. The -time value
75           defaults to 1000ms (1 second) if not specified. The smaller the
76           time, the faster the cursor will move. The time given will not be
77           exact. See bugs below.
78
79           OR
80
81       $cursor->moveto( X,Y, -time=>integer in milliseconds)
82           Move the cursor to the specified X,Y screen coordinate in -time
83           milliseconds.  The -time value defaults to 1000ms (1 second) if not
84           specified. The smaller the time, the faster the cursor will move.
85           The time given will not be exact. See bugs below.
86

DEPENDENCIES

88       Win32::API is required on Win32 systems.
89

POSSIBLE USES

91       Don't e-mail me to debate whether or not a program should warp or hide
92       a cursor. I will give you a few instances where "I think" a module like
93       this could come in handy.
94
95       1. Confining a canvas item to remain within the Canvas boundaries on a
96       move. See the cursor demonstration in 'widget'.
97
98       2. Giving the user some 'leeway' on clicking near an item. Say,
99       clicking on the picture of a thermometer, warps the cursor to a
100       Tk::Scale (right beside it) which actually controls that thermometer.
101
102       3. Confining a window within another window (Tk::MDI should be upgraded
103       to 'use Tk::CursorControl')
104
105       4. A step by step, show and tell session on 'How to use this GUI'.
106
107       5. Make the cursor disappear for a keyboard only Tk::Canvas game.
108
109       The key to using this module properly, is subtlety! Don't start making
110       the cursor warp all over the screen or making it disappear
111       sporadically.  That is a misuse of the functionality.
112
113       For some 'real world' applications which already have these types of
114       functionality, see any Multiple Document Interface (MDI); such as in
115       Excel or Word). Also have a look at the Win32 color chooser. The cursor
116       will be confined to the color palette while the button is pressed.
117       Also, try clicking on the gradient bar to the right of the palette. See
118       what happens to the mouse cursor?!  I'll bet you didn't even know that
119       this existed until now.
120
121       If you discover another good use for this module, I would definitely
122       like to hear about it ! That is the type of e-mail I would welcome.
123

BUGS & IDIOSYNCRASIES

125       Take ONE please!
126
127       Tk::CursorControl only allows ONE object per MainWindow! If you try to
128       create more than one, only the first object created will be returned.
129       This will also be true if using a widget or module which already
130       defines a Tk::CursorControl object.
131
132       Bindings
133
134       Tk::CursorControl internally generates <Enter>, <Leave> and <Motion>
135       bindings for the $widget passed. Any user-defined bindings of the same
136       type for $widget should still get executed. This feature has not been
137       completely tested.
138
139       Win32
140
141       This module makes heavy use of the ShowCursor and ClipCursor API's on
142       Win32. Be aware that when you change a cursor using the API, you are
143       doing so for your entire system. You, (the programmer) are responsible
144       for generating the show/hide and confine/release commands in the proper
145       order.
146
147       For every hide - you *will* want a show. For every confine - you
148       *should* have a release. There are cautionary measures built-in to
149       ensure that the cursor doesn't disappear forever or get locked within a
150       widget.
151
152       i.e. A release is automatically called if you try to confine the cursor
153       to two widgets at the same time.
154
155       In other words, the last confine always wins!
156
157       Unix
158
159       The methods for hiding and confining the cursor on Unix-based systems
160       is different than for Win32.
161
162       A blank cursor is defined using the Tk::Widget configure method for
163       each widget passed. Two files have been provided for this purpose in
164       the installation - trans_cur.xbm and trans_cur.mask. These files must
165       exist under a Tk->FindINC directory.
166
167       Confining a cursor on *nix does not use any sort of API or Xlib calls.
168       Motion events are generated on the toplevel window to confine the
169       cursor to the proper widget. On slow systems, this will make the cursor
170       look like it is attached to the widget sides with a spring.  On faster
171       systems, while still there, this bouncing type action is much less
172       noticible.
173
174       moveto
175
176       The time parameter passed to a moveto method will not be exact. The
177       reason for this is because a crude Tk::After command is used to wait
178       for a very short period. You will find that the actual time taken for
179       the cursor to stop is alway slightly more than the time you specified.
180       This time difference will be greater on slower computers. The time
181       error will also increase for higher time values.
182
183       Other
184
185       Warping the cursor will cause problems for users of absolute location
186       pointing devices (like graphics tablets). Users of graphics tablets
187       should not use this module.
188

AUTHOR

190       Jack Dunnigan <dunniganj@cpan.org>.
191
192       Copyright (c) 2002-2004 Jack Dunnigan. All rights reserved.
193
194       This program is free software; you can redistribute it and/or modify it
195       under the same terms as Perl itself.
196
197       My thanks to Tk gurus Steve Lidie and Slaven Rezic for their
198       suggestions and their patches. This is my first module on CPAN and I
199       appreciate their help. Thanks to Ala Qumsieh for utilizing the power of
200       my module in Tk::Toolbar.
201
202
203
204perl v5.34.0                      2022-01-21                  CursorControl(3)
Impressum