NAME

X11::SendEvent - a module for sending events to X windows

SYNOPSIS

use X11::SendEvent;

$win = X11::SendEvent->new(win => "MyWindowName");
$win->SendString("testing", ["Return"]);

DESCRIPTION

This module presents a simple interface for sending events, keycodes, keysyms and strings to an X window from a perl application.

METHODS

An object oriented interface is provided as follows:

new [options-hash]

Used to initialise the system and create a module instance. The optional hash may contain any of the following keys:

disp

Specifies X display to use. If this item is not provided, the environment variable DISPLAY is used. If the aforementioned variable is not set the item defaults to localhost:0.0

x

The caller may pass an X connection independently generated using the X11::Protocol module. When both disp and x are passed, x takes precedence.

win => [criteria]

Setting this item instructs the module to automatically find a window to be used for sending events to. The value passed must be an array reference of values which are handed "as is" to the ->FindWin() method; for further information please refer to its description below.

debug

Turns debugging output on.

[win-ref] = FindWin <string> [property = "WM_NAME"]

This method can find a window by specifying certain criteria. The required string is used to compare against the selected window property which, if left unspecified, defaults as shown above.

The the return value is an object reference which may be used to call methods. When multiple windows are found, any method called on the object will operate on all windows. If no windows are found the method returns undef.

- exempli gratia -

$win = $self->FindWin("x");
$win->SendString("HELLO");

the code above finds all windows containing the string x in their names and sends them the string HELLO.

SendEvent [args]

Use this method to send generic events to a window. The arguments are passed as a hash, where valid keys are as follows:

type

A string containing the event type of event to send e.g. IKeyPress, IKeyRelease etc.

win

The id of the window to which to send the event. If omitted, the window identified in the call to ->new() (if any is used), else the function warns and returns.

detail, state

For more information on both of these keys, please refer to the X11 protocol specification.

SendKeycode <keycode> [state = 0]

Use this method to send a keycode to the window. A shift state may also be specified, defaulting to the value shown above.

SendKeycode [list-ref = $_]

Alternatively, the arguments may be passed as a list reference, which defaults to $_.

SendKeysym <keysym-name>

This method translates the given keysym name into a keycode and sends it to the window.

SendString <string[-list]>

Use this method to send strings to a window. Keysyms and/or keycode/states may be interspersed in the parameter list via the inclusion of array references. The arrays passed may contain either a keysym name or a keycode and state (separated by a slash).

- exempli gratia -

$win->SendString("user", ["Return"], "joe", ["9/1"]);

In the above example, the string user is sent to the application, followed by a return key. Then the string joe is sent, followed by the shifted keycode 9.

AUTHOR

Erick Calder <ecalder@cpan.org>

AVAILABILITY + SUPPORT

For support e-mail the author. This module may be found on the CPAN. Additionally, both the module and its RPM package are available from:

http://perl.arix.com

DATE

$Date: 2002/12/04 22:10:13 $

VERSION

$Revision: 1.3 $

LICENSE AND COPYRIGHT

Copyright (c) 2002 Erick Calder. This product is distributed under the MIT License. A copy of this license was included in a file called LICENSE. If for some reason, this file was not included, please see http://www.opensource.org/licenses/mit-license.html to obtain a copy of this license.

cpanm X11::SendEvent

perl -MCPAN -e shell
install X11::SendEvent