CursorControl(3)

🎀 CursorControl(3) — the Perl/Tk module that moves your mouse around for you 💅

okay bestie, this is a User Contributed Perl Documentation page for Tk::CursorControl, and honestly? it's giving puppet-master energy. let's get into it 🫶

---

✨ 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 ✨

okay so first things first: Tk::CursorControl is-NOT-a Tk::Widget. nope. it's literally not that. instead it leans on Tk and is basically a lil collection of methods you use to manipulate the cursor (aka the pointer, the lil arrow, the main character of your screen) programmatically from inside a Tk program. 💖

---

✨ STANDARD OPTIONS ✨

Tk::CursorControl does not accept any standard options. that's it, that's the whole section. no options bestie, she doesn't do options. 💅

---

✨ METHODS ✨

here's the roster, the whole lineup:

• $cursor->confine( $widget ) — traps the cursor so it stays inside the bounding box of $widget. like a lil fence but for your mouse 🦋
  • $cursor->jail( $widget ) — an alias for the confine method.
• $cursor->release — releases the cursor. you use this to bring back normal cursor behaviour after a confine. note: you do not need to specify $widget here. 👑
  • $cursor->free — an alias for the release method.
• $cursor->hide( @widgets ) — makes the cursor invisible over every widget in @widgets. poof, gone, she's not there 🙈
• $cursor->show( @widgets ) — makes the cursor visible over every widget in @widgets. you use this after a hide. note: Show (capital S) works just as well too. ✨
• $cursor->warpto( $widget ?x,y? ) — warps the cursor to the specified ?x,y? position inside $widget. if you don't give the x,y values, then the center of the widget gets used as the target. 🎯

OR

• $cursor->warpto( X,Y ) — warps the cursor to the specified X,Y screen coordinate. 🌈
• $cursor->moveto( $widget ?x,y?, -time=>integer in milliseconds) — moves the cursor to the specified ?x,y? position inside $widget in -time milliseconds. if the x,y values aren't specified, then the center of the widget is the target. -time defaults to 1000ms (1 second) if you don't say anything. the smaller the time, the faster the cursor moves. the time you give will not be exact — see bugs below. 😭

OR

• $cursor->moveto( X,Y, -time=>integer in milliseconds) — moves the cursor to the specified X,Y screen coordinate in -time milliseconds. -time defaults to 1000ms (1 second) if not specified. the smaller the time, the faster the cursor moves. the time given will not be exact. see bugs below. 💀

---

✨ DEPENDENCIES ✨

Win32::API is required on Win32 systems. that's the whole tea. 🍓

---

✨ POSSIBLE USES ✨

okay so, don't e-mail the author to debate whether or not a program should warp or hide a cursor. he will simply not be entertaining that. instead he's gonna 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! do not start making the cursor warp all over the screen or making it disappear sporadically. that is a misuse of the functionality, and we do not do that here. 🚫

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?! the author will bet you didn't even know that this existed until now. 😭

if you discover another good use for this module, he would definitely like to hear about it ! that is the type of e-mail he 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-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.

---

okay that's the whole page bestie, you ate that 💅✨

this lil time capsule was rendered by perl v5.42.0 on 2025-07-25, and yes it's still filed under CursorControl(3) in the User Contributed Perl Documentation section 🎀