1CursorControl(3) User Contributed Perl Documentation CursorControl(3)
2
6 Tk::CursorControl - Manipulate the mouse cursor programmatically
7
9 use Tk::CursorControl;
10 $cursor = $main->CursorControl;
11 # Lock the mouse cursor to $widget
13 $cursor->confine($widget);
14 # Free the cursor
16 $cursor->release;
17 # cursor disappears over $widget
19 $cursor->hide($widget);
20 # show cursor again over $widget
22 $cursor->show($widget);
23 # warp cursor to $widget (jump)
25 $cursor->warpto($widget);
26 # move cursor to $widget
28 $cursor->moveto($widget);
29
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
36 Tk::CursorControl does not accept any standard options
37
39 The following methods are available:
40 $cursor->confine( $widget )
42 Confine the cursor to stay within the bounding box of $widget.
43 $cursor->jail( $widget )
45 Alias for the confine method.
46 $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 $cursor->free
52 Alias for the release method.
53 $cursor->hide( @widgets )
55 Make cursor invisible over each widget in @widgets.
56 $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 $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 OR
67 $cursor->warpto( X,Y )
69 Warp the cursor to the specified X,Y screen coordinate.
70 $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 OR
80 $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
88 Win32::API is required on Win32 systems.
89
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 1. Confining a canvas item to remain within the Canvas boundaries on a
96 move. See the cursor demonstration in 'widget'.
97 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 3. Confining a window within another window (Tk::MDI should be upgraded
103 to 'use Tk::CursorControl')
104 4. A step by step, show and tell session on 'How to use this GUI'.
106 5. Make the cursor disappear for a keyboard only Tk::Canvas game.
108 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 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 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
125 Take ONE please!
126 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 Bindings
133 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 Win32
140 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 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 i.e. A release is automatically called if you try to confine the cursor
153 to two widgets at the same time.
154 In other words, the last confine always wins!
156 Unix
158 The methods for hiding and confining the cursor on Unix-based systems
160 is different than for Win32.
161 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 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 moveto
175 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 Other
184 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
190 Jack Dunnigan <dunniganj@cpan.org>.
191 Copyright (c) 2002-2004 Jack Dunnigan. All rights reserved.
193 This program is free software; you can redistribute it and/or modify it
195 under the same terms as Perl itself.
196 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.
201perl v5.34.0 2022-01-21 CursorControl(3)