NAME

Tcl::pTk::XEvent - Limited Support for perl/tk's XEvent in Tcl::pTk

SYNOPSIS

       # Create binding on a widget, using XEvent to get
       #   the mouse x/y position
       $widget->bind(
               '<Motion>',
               sub {
                          
                        my $e = $widget->XEvent;
                        
                        # Get mouse x/y position in the widget
                        my $mouseX = $e->x;
                        my $mouseY = $e->y;

                        print "mouse X/Y = $mouseX/$mouseY\n";
               }
               );

DESCRIPTION

Tcl::pTk::XEvent provides (very) limited support for perl/tk's XEvent mechanism in Tcl::pTk. Currently it only provides support for the x and y calls. Other calls will generate an error message.

For XEvent calls other than x and y, bindings should be converted to use the equivalent Ev() calling as shown below.

Perl/Tk's XEvent Mechanism

Perl/Tk (Tk) provides an additional method (The XEvent mechanism) to get event information during event processing. This was added to perl/tk by adding c-code functions (Tk_EventInfo in tkbind.c and others) to the original Tcl/Tk c-code.

Although the XEvent mechanism is not described in the documents included in the perl/tk package, it is used in many places in the perl/tk code, and in other external perl/tk widgets. The alternative to XEvent is the Ev mechanism, which is documented in the Tk::bind docs (Binding Callbacks and Substitution section).

Example of XEvent and an Ev Equivalent

Example of XEvent

       # Create binding on a widget, using XEvent to get
       #   the mouse x/y position
       $widget->bind(
               '<Motion>',
               sub {
                        my $w = shift;  # Get the event widget
                        my $e = $w->XEvent;
                        
                        # Get mouse x/y position in the widget
                        my $mouseX = $e->x;
                        my $mouseY = $e->y;

                        print "mouse X/Y = $mouseX/$mouseY\n";
               }
               );

Equivalent Example using Ev() calls

This is how a XEvent call should be converted to using the Ev() calls, which are fully supported in Tcl/Tk.

# Create binding on a widget, using Ev calls to get
#   the mouse x/y position
$widget->bind(
        '<Motion>',
        [ sub {
                 my $w = shift;  # Get the event widget
                 my ($x, $y) = @_; # Get x/y passed in from the Ev() calls
                 
                 # Get mouse x/y position in the widget
                 my $mouseX = $x;
                 my $mouseY = $y;

                 print "mouse X/Y = $mouseX/$mouseY\n";
        }, 
           Ev('x'), Ev('y') ]
        
);