xse(1)

XSE(1)

General Commands Manual

XSE(1)

NAME

xse - an interface to XSendEvent()

SYNOPSIS

xse [XToolkit options] [-window win] [-file filename] -version] -Debug] [event specifiers]

DESCRIPTION

Xse provides a way to send arbitrary XEvents to a window, sort of the opposite of xev(1). There are three modes of operation:

If event specifiers are given on the command line, then they are parsed and sent to the appropriate window;
If the -file option is given, then xse reads event specifiers from the given file, and sends them to the appropriate window.
Otherwise, a tool is created by parsing the widgets resource and creating the specified widgets. These can then use the registered action procedures to send events to various windows.

The following sections describe the options in detail, the syntax of event specifiers, and the resources used to customize xse.

OPTIONS

The following non-widget resources can be set from the command-line or in a resource file. As usual, when given on the command line they can be abbreviated to their shortest unique prefix, often the first letter. Furthermore xse accepts all the standard X Toolkit options (see X(1)).

-window win: Specifies which window to send events to. A window can be specified by giving it's name, in which case the first child of the root window whose name matches the given string will be used, or by giving it's XID, as obtained, e.g. from xwininfo(1), The keywords PointerWindow, InputFocus, or ClickWindow can also be used. PointerWindow will send the event to the window that the pointer is over, InputFocus will send it to the window with the input focus, and ClickWindow will allow you to select the window which will receive the event by clicking in it. This option corresponds to the window resource. The default is ClickWindow.
-file file: If given, then xse reads event specifiers from the given file and sends them to the appropriate file. The option corresponds to the file resource. It is an error for this option to be given along with event specifiers on the command line.
-version: If given, xse simply prints its version information to stdout and exits. This option corresponds to the versionOnly resource.
-Debug: Enables lots of ugly verbosity about parsing event specifications. Unlikely to be useful to anybody but parser debuggers.

If additional arguments are given on the command line (and -file was not given), they are taken to be event specifiers (see below) and no tool is created. Each argument is parsed into an event sequence which is sent to the specified window. If no extra arguments are present, then a tool is created using the widgets resource. To customize this tool, see below under CUSTOMIZING.

SPECIFYING EVENTS

The syntax for specifying events is modelled after that described in Appendix B of the XToolkit Intrinsics (Xt) manual for specifying translations. It is extended to allow more complete specification of fields that are not needed for recognition but are useful for generation. Complete semantics of the different event types and their components (fields) is given in Chapter 8 of the Xlib manual.

The following notation is used in these descriptions:

Except in keysyms and atoms, case is not significant.
Where integers are called for, they are parsed such that a leading zero (`0') indicates octal, and a leading `0x' or `0X' indicates hexadecimal.
Where windows are called for, they can be specified either as an integer representing the XID of the window (as obtained, e.g., from xwininfo(1)), or by giving one of the following keywords:

PointerWindow: Identifies the window that the mouse pointer is in.
InputFocus: Identifies the window with the keyboard focus.
Window: Identifes the window to which the events are being sent (see the -window option, above).
Parent: Identifies the parent window of whichever window was identified previously. Note that specifying this when the previous window is not really a window will cause an X error and a crash.
None: Identifes no window, i.e. the constant zero (`0').

: If the window specification is non-numeric and not one of these strings, then the window hierarchy is searched for a window whose name matches. If no such window is found, xse reports an error.

-: A Boolean is one of "True" or "False", "Yes" or "No", or "On" or "Off".

When reading from a file (see the -file option, above), each event specifier must on a single line in the file. Lines starting with a pound (or hash) symbol (`#') are treated as comments and ignored.

An event specifier is an optional list of modifiers, followed by an event type description in angle brackets (`<' and `>'), followed by an optional repeat count in parentheses (`(' and `)'), followed by field specifiers that depend on the type of the event.

The list of modifiers is a whitespace-separated list of the following symbols:

		Shift	s		Mod1		Button1
		Lock		l		Mod2		Button2
		Ctrl		c		Mod3		Button3
						Mod4		Button4
						Mod5		Button5

The effect of specifying these is to inclusively-OR the approriate mask into the state field of events for which this field exists (Key, Button, Motion, Enter, and Leave events). They are ignored for other events.

The event type should be one of the following list, which includes all possible types of XEvent. They are described along with possible field specifiers. Certain event types have shorthands that are also described. A vertical bar (`|') separates required fields from optional ones. Default values of optional fields are indicated in square brackets. All fields must be given in the order listed.

Keyboard and Pointer Events

This class of events all share the same optional fields.

KeyPress keycode | x [0] y [0] xroot [0] yroot [0] time [CurrentTime] same_screen [True] subwindow [None] window [Window] root [Root] KeyDown keycode ... Key keycode ...

These event types use XStringToKeysym(3X) and XKeysymToKeycode(3X) to translate the detail (a keysym) into the keycode to send. Keysyms may also be specified by numeric value, though symbolic interpretation takes precedence over numeric interpretation (this affects only keysyms XK_0 through XK_9). Thus <Key>9 refers to the keysym XK_9 whose value is 0x039, not the keysym, if any, whose numeric value is 9. If the latter is desired you can write it as <Key>011 (octal notation) or <Key>0x9.

KeyPress++ keycode ... KeyDown++ keycode ... Key++ keycode ...

These event types are similar to the KeyPress, KeyDown, and Key events except that after mapping the specified keysym into a keycode, the modifiers necessary to reconstruct the specified keysym from that keycode are automatically added to the constructed event. For example, assuming the XK_dollar keysym is a shifted XK_4 keysym, then the `<Key>dollar' event would map into the keycode for the `4' key with no modifiers, while the `<Key++>dollar' event would map into the same keycode but with the Shift modifier set for you. This provides a degree of independence of the particular keyboard map that happens to be installed in the server--to send a `$' character you can simply use a `<Key++>dollar' event instead of having to know that the keyboard mapping would otherwise require a `Shift<Key>4' event.

KeyRelease keycode ... KeyUp keycode ...

The fields of these event types are as for KeyPress events.

Shift keycode ... Ctrl keycode ...

These event types correspond to a KeyPress event with the appropriate modifier bit set.

Shift++ keycode ... Ctrl++ keycode ...

These event types correspond to a KeyPress++ event with the appropriate modifier bit set.

Shift++ keycode ... Ctrl++ keycode ...

These event types correspond to a KeyPress++ event with the appropriate modifier bit set.

ButtonPress button | x [0] y [0] xroot [0] yroot [0] time [CurrentTime] same_screen [True] subwindow [None] window [Window] root [Root] BtnDown button ...

The `button' field should specify which button is involved, in the form ButtonX (for X a digit from 1 to 5).

ButtonRelease button ... BtnUp button ...

The fields of these event types are as for ButtonPress events.

Btn1Down ... Btn2Down ... Btn3Down ... Btn4Down ... Btn5Down ...

These event types correspond to a ButtonPress event with the appropriate setting of the `button' field.

Btn1Up ... Btn2Up ... Btn3Up ... Btn4Up ... Btn5Up ...

These event types correspond to a ButtonRelease event with the appropriate setting of the `button' field.

MotionNotify is_hint | x [0] y [0] xroot [0] yroot [0] time [CurrentTime] same_screen [True] subwindow [None] window [Window] root [Root] PtrMoved is_hint ... Motion is_hint ... MouseMoved is_hint ...

The `is_hint' field should be one of Normal or Hint.

Btn1Motion is_hint ... Btn2Motion is_hint ... Btn3Motion is_hint ... Btn4Motion is_hint ... Btn5Motion is_hint ...

Shorthand for a MotionNotify event with the appropriate modifier bit set.

Window Entry and Exit Events

This class of events uses the same set of optional fields as the Keyboard and Pointer events described in the previous section.

EnterNotify mode detail | focus [True] x [0] y [0] xroot [0] yroot [0] time [CurrentTime] same_screen [True] subwindow [None] window [Window] root [Root] Enter mode detail ... EnterWindow mode detail ... LeaveNotify mode detail ... Leave mode detail ... LeaveWindow mode detail ...

The `mode' field should be one of Normal, Grab, Ungrab, or WhileGrabbed. The `detail' field can be one of Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual, Pointer, PointerRoot, or DetailNone.

Input Focus Events

For this class of events, the `mode' and `detail' fields should be as for window entry/exit events described in the previous section.

FocusIn mode detail | window [Window] FocusOut mode detail ...

Key Map State Notification Events

KeymapNotify | key_vector

The key_vector should be a whitespace-separated list of up to thirty-two integers representing the keyboard bitmap. It is an error for any of these values to be greater than 255.

Exposure Events

For this class of events, the `major_code' field (where required) should be one of CopyArea or CopyPlane. The `minor_code' field (where allowed) should be an integer. The other fields, such as `x', `y', `width', `height', and `count' should all be integers.

Expose x y width height | count [0] window [Window] Exp x y width height ...

GraphicsExpose x y width height major_code | minor_code [0] count [0] window [Window] GrExp x y width height major_code ...

NoExpose major_code | minor_code [0] drawable [Window] NoExp major_code ...

Window State Change Events

In this class of events, the `event' field defaults to whatever the `window' field gets set to (Window by default).

CirculateNotify place | window [Window] event [same] Circ place ...

The `place' field should be one of PlaceOnTop, OnTop, PlaceOnBottom, or OnBottom.

ConfigureNotify x y width height border_width above |

window [Window] event [same] override_redirect [False] Configure x y width height border_width above ...

All required fields should be integers except the `above' field that should be a window.

CreateNotify x y width height border_width above |

window [Window] parent [same] override_redirect [False] Create x y width height border_width above ...

All fields are as above, except that the `parent' field behaves exactly like the `event' field does in the other events of this class: it defaults to whatever the `window' field gets set to. Use the value Parent to set it to the parent of whatever `window' gets set to.

DestroyNotify | window [Window] event [same] Destroy ...

GravityNotify x y | window [Window] event [same] Grav x y ...

Both required fields should be integers.

MapNotify | window [Window] event [same] override_redirect [False] Map ...

MappingNotify request | [first_keycode count] Mapping request ...

The request field should be one of Modifier, Keyboard, or Pointer. If it is Keyboard, then `first_keycode' and `count' should be integers and default to zero.

ReparentNotify parent x y | window [Window] event [same] override_redirect [False] Reparent parent x y ...

The `parent' field should be a window (the Parent keyword is probably not useful in this context since you are specifying the new parent).

UnmapNotify | window [Window] event [same] from_configure [False] Unmap ...

VisibilityNotify state | window [Window] Visibility state ... Visible state ...

The `state' field should be one of Unobscured, PartiallyObscured, or FullyObscured.

Structure Control Events

For this class of events, the `parent' field (where it is used) defaults to whatever the `window' field gets set to (Window by default). This may not be the most useful thing, but it can't be set to the parent of that window automatically since attempting to find the parent of a non-window would cause a crash. Like above, use the Parent keyword to explicitly specify the parent of the window referred to by the `window' field.

CirculateRequest place | window [Window] CircReq place ...

The `place' field should be one of PlaceOnTop, OnTop, PlaceOnBottom, or OnBottom.

ConfigureRequest x y width height border_width above |

stack_mode [Above] mask [0] window [Window] parent [same] ConfigureReq x y width height border_width above ...

All required fields should be integers except the `above' field that should be a window. The `stack_mode' field should be one of Above, Below, TopIf, BottomIf, or Opposite. The `mask' field should be a integer representing a bitmask.

MapRequest | window [Window] parent [same] MapReq ...

ResizeRequest width height | window [Window] ResReq width height ...

Both required fields should be integers.

Colormap State Change Events

This type of event cannot currently be sent by xse because there is no way to effectively specifiy a colormap in the event specification. Attempting to send such an event will cause an error.

Client Communication Events

For this class of events, the `time' field should be an integer (defaults to CurrentTime) and all the various window fields like `target', `owner', and `requestor' default to Window. Recall that atoms are case-sensitive sequences of non-whitespace characters. Xse uses XInternAtom(3X) with the `only_if_exists' flag set to False, so unrecognized atoms are created as necessary.

ClientMessage message_type format data | window [Window] Message message_type format data ...

The `message_type' field should be an atom. The `format' field can be b, s, l, or c. In the first three cases, the `data' field should be a whitespace-separated list of twenty bytes, ten shorts, or five longs. The integers are checked for range violations. If `format' is c then the `data' field should a sequence of twenty characters not separated by whitespace. The following escapes are recognized: \n (newline), \t (tab), \r (carriage return), \f (formfeed), and \b (backspace). As well, the sequence \XXX where each X is an octal digit is recognized (all three digits must be given).

PropertyNotify atom state | window [Window] time [CurrentTime] Prop atom state ...

The `atom' field should be an atom and the `state' field should be one of NewValue or Delete.

SelectionClear selection | window [Window] time [CurrentTime] SelClr selection ...

The `selection' field should be an atom.

SelectionRequest selection target | property [None] owner [Window] requestor [[same]] time [CurrentTime] SelReq selection target ...

Both required fields should be atoms. The `property' field should be an atom or the special value None.

SelectionNotify selection target | property [None] requestor [Window] time [CurrentTime] Select selection target ...

The fields are as for SelectionRequest events.

EXAMPLES

The following command would cause ls(1) to be executed in the window labelled "Test Window":



    % xse -win 'Test Window' '<Key>l' '<Key>s' '<Key>Return'

(but see the BUGS section if this is to work with xterm(1)). The quotes are protecting the brackets from the shell — they would not be needed if the event specifiers were given in a file as in:



    % cat events


    <Key>d


    <Key>a


    <Key>t


    <Key>e


    <Key>Return


    % xse -file events

In this case the user would be prompted to click on a window and the date(1) command would be sent to that window (see the BUGS section regarding using ClickWindow with virtual-root window managers). As another example, you could indicate that Button1 was pressed at coordinates (100,200) while Shift was down by doing:



    % xse -win 0x500001 'Shift<Btn1Down> 100 200'
or


    % xse -win 0x500001 'Shift<ButtonPress>Button1 100 200'

The events would go to the window with XID 0x500001 (as reported by, say, xwininfo(1)). You could send a keystroke to a window three times by doing



    % xse '<KeyPress>(3) a'

for example. Finally, you might simulate "Meta-x" by sending



    % xse '<Key>Meta-L' '<Key>x' '<KeyUp>x' <KeyUp>Meta-L'

You can from this that Meta is not handled like a modifier key.

CUSTOMIZING XSE

The following section applies only when xse is run in tool mode (ie., when -file was not given and no event specifiers were given on the command line).

Xse has a default set of (probably unuseful) resources built-in. To customize its behaviour, copy the default application defaults file (see below under FILES) and edit it to add your own buttons and actions. Then set the environment variable XAPPLRESDIR to point to the directory where your copy lives. Alternatively, you can place entries in your .Xresources or .Xdefaults file.

The application class is Xse. The resource widgets determines what widgets will be created. This should be a list of whitespace-separated triples specifying the WidgetClass, name, and parent widget name for each widget desired. For example, the default configuration is:

	Xse.widgets: \
		Form		form		toplevel \n\
		Command	button1	form \n\
		Command	button2	form \n
		Command	button3	form \n

This creates three vertically-stacked buttons (Command widgets) in a Form. Note that the widget toplevel is predefined (class ApplicationShell) and other names must be in a form acceptable to XtNameToWidget(3X). In particular, they must be fully specified using periods (`.') to separate the components below toplevel (although this is not illsutrated in the example, a child of button1 would specify "form.button1" as its parent, not just "button1").

You can create different versions of xse from the same application defaults file by specifying different program names in place of the class name "Xse" in the defaults file, and making links to the xse executable with those names. For example, "xse-vi.widgets" applies when the command "xse-vi" is executed. This command can either be a link to xse or you can specify the alternate name with the -name XToolkit option. The default resource file includes a more complicated example for you to look at.

Translation Actions

There are only two translation actions:

xse-quit(): Exit xse.
xse-send(): Sends an event sequence to a window. With no arguments, the event causing the action to be invoked is passed to the default window. If only one argument is given, it is taken to be an event specifier and the event(s) are sent to the default window. If two arguments are given, the first is the window and the second the event sequence. Note that if ClickWindow is given as the window specifier, the user will be prompted to click again. See also the BUGS section about using name lookup in this context.

ENVIRONMENT

XAPPLRESDIR application defaults directory

FILES

$LIBDIR/app-defaults/Xse default resource file

DIAGNOSTICS

A variety of messages can be generated if xse cannot parse an event sequence. These should give enough information and context for debugging. In addition, bad window specifications and the like are flagged by the ever-popular default X mechanism of printing lots of error messages and exiting.

BUGS

Xse cannot send ColormapNotify events, at least not yet.

Xse can get confused by virtual-root window managers, so that if ClickWindow is given as the window to send events to (it is the default), then events can simply "vanish". The root window finding code is known to work with tvtwm(1), and probably not to work with olvwm(1).

It is quite costly to look up windows by name, either to interpret a field specifier or to determine what name to send to in the xse-send() actoin. The solution is to use XID's obtained from xwininfo(1) instead.

Not really a bug, but if you are using xse to send events to an xterm(1), make sure to enable send events using the main menu or the allowSendEvents resource.

Also not really a bug, but note that while sending a Unmap event will cause a window to disappear, sending a Map event will not make it reappear. There are other events and event sequences that can cause massive confusion when they arrive unexpectedly from xse.

AUTHOR

George Ferguson (ferguson@cs.rochester.edu).

4 Apr 1993

U of Rochester