GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TK::CURSORCONTROL (3)

.ds Aq ’

NAME

Tk::CursorControl - Manipulate the mouse cursor programmatically

CONTENTS

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

<B>Tk::CursorControlB> is-<B>NOTB>-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.

STANDARD OPTIONS

<B>Tk::CursorControlB> does not accept any standard options

METHODS

The following methods are available:
$cursor-><B>confineB>( $widget ) Confine the cursor to stay within the bounding box of $widget.
$cursor-><B>jailB>( $widget ) Alias for the <B>confineB> method.
$cursor-><B>releaseB> Release the cursor. Used to restore proper cursor functionality after a confine. Note: $widget does <B>notB> need to be specified.
$cursor-><B>freeB> Alias for the <B>releaseB> method.
$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.

OR

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

OR

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

DEPENDENCIES

<B>Win32::APIB> is required on Win32 systems.

POSSIBLE USES

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.

BUGS & IDIOSYNCRASIES

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

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

<B>Win32B>

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 <B>releaseB> is automatically called if you try to confine the cursor to two widgets at the same time.

In other words, the last <B>confineB> always wins!

<B>UnixB>

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.

<B>movetoB>

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.

<B>OtherB>

Warping the cursor will cause problems for users of absolute location pointing devices (like graphics tablets). Users of graphics tablets should <B>notB> 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CURSORCONTROL (3) 2004-04-25

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.