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) ]
                
        );