File: xdotool.pod

package info (click to toggle)
xdotool 1%3A1.20100302.2708-1
  • links: PTS
  • area: main
  • in suites: squeeze
  • size: 272 kB
  • ctags: 186
  • sloc: ansic: 2,762; sh: 137; makefile: 98
file content (469 lines) | stat: -rw-r--r-- 11,334 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
=pod

=head1 NAME

xdotool - command-line X11 automation tool

=head1 SYNOPSIS

B<xdotool> I<cmd> I<args...>

=head1 DESCRIPTION

B<xdotool> lets you programatically (or manually) simulate keyboard input and
mouse activity, move and resize windows, etc. It does this using X11's
XTEST extension and other Xlib functions.

There is some support for Extended Window Manager Hints (aka EWMH or NetWM).
See the L</EXTENDED WINDOW MANAGER HINTS> section for more information.

=head1 KEYBOARD COMMANDS

=over

=item B<key> I<[options]> I<keystroke>

Options:

=over

=item B<--window windowid> 

Send keystrokes to a specific window id. See SENDEVENT below.

=item B<--clearmodifiers> 

Clear modifiers before sending keystrokes. See CLEARMODIFIERS below.

=back

Type a given keystroke. Examples being "alt+r", "Control_L+J",
"ctrl+alt+n", "BackSpace".

Generally, any valid X Keysym string will work. Multiple keys are
separated by '+'. Aliases exist for "alt", "ctrl", "shift", "super",
and "meta" which all map to Foo_L, such as Alt_L and Control_L, etc.

In cases where your keyboard doesn't actually have the key you want to type,
xdotool will automatically find an unused keycode and use that to type the key.

Example: Send the keystroke "F2"
 xdotool key F2

Example: Send 'a' with an accent over it (not on english keyboards, but still
works with xdotool)
 xdotool key Aacute

=item B<keydown> I<[options]> I<keystroke>

Same as above, except only keydown events are sent.

=item B<keyup> I<keystroke>

Same as above, except only keyup events are sent.

=item B<type> I<[options]> I<something to type>

Options:

=over

=item B<--window windowid> 

Send keystrokes to a specific window id. See SENDEVENT below.

=item B<--delay milliseconds> 

Delay between keystrokes. Default is 12ms.

=item B<--clearmodifiers> 

Clear modifiers before sending keystrokes. See CLEARMODIFIERS below.

=back

Types as if you had typed it. Supports newlines and tabs (ASCII newline and
tab). Each keystroke is separated by a delay given by the delay option.

Example: to type 'Hello world!' you would do:
 xdotool type 'Hello world!'

=back

=head1 MOUSE COMMANDS

=over 

=item B<mousemove> I<[options]> I<x> I<y>

Move the mouse to the specific X and Y coordinates on the screen

=over

=item B<--window WINDOW> 

Specify a window to move relative to. Coordinates 0,0
are at the top left of the window you choose.

=item B<--clearmodifiers> 

See CLEARMODIFIERS

=back

=item B<click> I<[options]> I<button>

Send mousedown followed by mouseup for the given button

=over

=item B<--clearmodifiers> 

Clear modifiers before clicking. See CLEARMODIFIERS below.

=item B<--window> 

WINDOW - Specify a window to send a click to. See SENDEVENT below for caveats.
Uses the current mouse position when generating the event.

=back

=item B<mousedown> I<[options]> I<button>

Same as above, except only a mouse down is sent.

=item B<mouseup> I<[options]> I<button>

Same as above, except only a mouse up is sent.

=item B<getmouselocation>

Outputs the x, y, and screen location of the mouse cursor. Screen numbers will
be nonzero if you have multiple monitors and are not using Xinerama.

=back

=head1 WINDOW COMMANDS

=over

=item B<search> I<[options]> I<somestring>

Search  for windows with titles, names, or classes matching somestring.  The
output is line-delimited list of X window identifiers

The options available are:

=over

=item B<--class> 

Match against the window class

=item B<--maxdepth> N 

Set recursion/child search depth. Default is -1,
meaning infinite. 0 means no depth, aka no results. If you only want toplevel
windows, set maxdepth of 1.

=item B<--name>

Match against the window name

=item B<--onlyvisible> 

Show only visible windows in the results.

=item B<--pid PID> 

Match windows that belong to a specific process id. This may not work for some
X applications that do not set this metadata on its windows.

=item B<--screen N>

Select windows only on a specific screen. Default is to
search all screens. Only meaningful if you have multiple displays and are not
using Xinerama.

=item B<--title> 

Match against the window title (what's displayed in the titlebar of the window)

=back

The default options are C<--title --name --class>

=item B<getwindowfocus> [-f]

Prints the window id of the currently focused window. 

If the current window has no WM_CLASS property, we assume it is not a normal
top-level window and traverse up the parents until we find a window with a
WM_CLASS set and return that window id.

If you really want the window currently having focus and don't care if it has a
WM_CLASS setting, then use 'getwindowfocus -f'

=item B<windowsize> [options] windowid width height

Set the window size of the given window

The options available are:

=over

=item B<--usehints> 

Use window sizing hints (when available) to set width and height.  This is
useful on terminals for setting the size based on row/column of text rather
than pixels.

=back

Example: To set a terminal to be 80x24 characters, you would use:
C<xdotool windowsize --usehints windowid 80 24>

=item B<windowmove> I<windowid> I<x> I<y>

Move the window to the given position

=item B<windowfocus> I<windowid>

Focus the window

=item B<windowmap> I<window_id>

Map a window. In X11 terminology, mapping a window means making it visible on
the screen.

=item B<windowraise> I<window_id>

Raise the window to the top of the stack. This may not work on all window managers.

=item B<windowunmap> I<window_id>

Unmap a window, making it no longer appear on your screen.

=item B<set_window> I<[options]> I<windowid>

Set properties about a window.

Options:

=over

=item B<--name newname> 

Set window WM_NAME (the window title, usually)

=item B<--icon-name newiconname> 

Set window WM_ICON_NAME (the window title when minimized, usually)

=item B<--role newrole>

Set window WM_WINDOW_ROLE

=item B<--classname newclassname>

Set window class name (not to be confused with window class)

=item B<--class newclass>

Set window class (not to be confused with window class name)

=back

=back

=head1 DESKTOP AND WINDOW COMMANDS

These commands follow the EWMH standard. See the section L<EXTENDED WINDOW
MANAGER HINTS> for more information.

=over 

=item B<windowactivate> I<windowid>

Activate the window. This command is different from windowfocus:
if the window is on another desktop, we will switch to that desktop. It also
uses a different method for bringing the window up. I recommend trying this
command before using windowfocus, as it will work on more window managers.

=item B<getactivewindow>

Output the current active window. This command is often more reliable than
getwindowfocus.

=item B<set_num_desktops> I<number>

Changes the number of desktops or workspaces.

=item B<get_num_desktops>

Output the current number of desktops.

=item B<set_desktop> I<desktop_number>

Change the current view to the specified desktop.

=item B<get_desktop>

Output the current desktop in view.

=item B<set_desktop_for_window> I<window_id> I<desktop_number>

Move a window to a different desktop.

=item B<get_desktop_for_window> I<window_id>

Output the desktop currently containing the given window.

=back

=head1 SCRIPTS

xdotool can read a list of commands via stdin or a file if you want. A script
will when any command fails.

=over

=item * Read commands from a file:

 xdotool filename

=item * Read commands from stdin:

 xdotool -

=item * Read commands from a redirected file

 xdotool - < myfile

=back

You can also write scripts that only execute xdotool. Example:

 #!/usr/local/bin/xdotool
 windowactivate $WINDOWID
 mousemove -window $WINDOWID 50 50
 click 1
 click 1

All commands are run as if you had typed 'xdotool <line>' via /bin/sh. This
means any shell magic should work here, too, including the use of environment
variables. For above, here's how you'd set the value of WINDOWID:

 % WINDOWID=1234 ./myscript

=head1 CLEARMODIFIERS

Any command taking the I<--clearmodifiers> flag will attempt to clear any
active input modifiers during the command and restore them afterwards.

For example, if you were to run this command:
 xdotool key a

The result would be 'a' or 'A' depending on whether or not you were holding the
shift key on your keyboard. Often it is undesirable to have any modifiers
active, so you can tell xdotool to clear any active modifiers. 

The order of operations if you hold shift while running 'xdotool key --clearmodifiers a' is this:

=over

=item 1. Query for all active modifiers (finds shift, in this case)

=item 2. Try to clear shift by sending 'key up' for the shift key

=item 3. Runs normal 'xdotool key a'

=item 4. Restore shift key by sending 'key down' for shift

=back

The I<--clearmodifiers> flag can currently clear of the following:

=over

=item * any key in your active keymap that has a modifier associated with it.
(See L<xmodmap(1)>'s 'xmodmap -pm' output)

=item * mouse buttons (1, 2, 3, 4, and 5)

=item * caps lock


=back

=head1 SENDEVENT NOTES

If you are trying to send key input to a specific window, and it does not
appear to be working, then it's likely your application is ignoring the events
xdotool is generating. This is fairly common.

Sending keystrokes to a specific window uses a different API than simply typing
to the active window. If you specify 'xdotool type --window 12345 hello'
xdotool will generate key events and send them directly to window 12345.
However, X11 servers will set a special flag on all events generated in this
way (see XEvent.xany.send_event in X11's manual). Many programs observe this
flag and reject these events.

Some programs can be configured to accept events even if they are generated by
xdotool. Seek the documentation of your application for help.

Specific application notes (from the author's testing):
* Firefox 3 seems to ignore all input when it does not have focus.
* xterm can be configured while running with ctrl+leftclick, 'Allow SendEvents'
* gnome-terminal appears to accept generated input by default.

=head1 EXTENDED WINDOW MANAGER HINTS

The following pieces of the EWMH standard are supported:

=over 

=item _NET_SUPPORTED

Asks the window manager what is supported

=item _NET_CURRENT_DESKTOP

Query and set the current desktop. Support for this enables these commands:
C<set_desktop>, C<get_desktop>.

=item _NET_WM_DESKTOP

Query and set what desktop a window is living in. Support for this enables
these commands: C<set_desktop_for_window>, C<get_desktop_for_window>.

=item _NET_ACTIVE_WINDOW

Allows you to query and set the active window by asking the window manager to
bring it forward. Support for this enables these commands: C<windowactivate>, C<getactivewindow>.

=back

=head1 SEE ALSO

L<xprop(1)>, L<xwininfo(1)>, 

Project site: L<http://www.semicomplete.com/projects/xdotool>

Google Code: L<http://semicomplete.googlecode.com/>

=head1 CONTACT

Please send questions to xdotool-users@googlegroups.com. File bugs and feature requests at the following URL:

L<http://code.google.com/p/semicomplete/issues/list>

=head1 AUTHOR

xdotool was written by Jordan Sissel.

This manual page was written originally by Daniel Kahn Gillmor
E<lt>dkg@fifthhorseman.netE<gt> for the Debian project (but may be
used by others). It is maintained by Jordan Sissel.

=cut