1WMCTRL(1) General Commands Manual WMCTRL(1)
2
6 wmctrl - interact with a EWMH/NetWM compatible X Window Manager.
7
9 wmctrl [ options | actions ]...
10
14 wmctrl is a command that can be used to interact with an X Window man‐
15 ager that is compatible with the EWMH/NetWM specification. wmctrl can
16 query the window manager for information, and it can request that cer‐
17 tain window management actions be taken.
18 wmctrl is controlled entirely by its command line arguments. The com‐
21 mand line arguments are used to specify the action to be performed
22 (with options that modify behavior) and any arguments that might be
23 needed to perform the actions.
24 The following sections define the supported actions and options. Argu‐
27 ments to the actions and options are written in the form <ARGNAME> in
28 the descriptions below. The detailed syntax for writing arguments are
29 in a single section dedicated to that purpose.
30
35 The following command line arguments can be specified to invoke a wmc‐
36 trl action. Only one action can be executed with the invocation of the
37 wmctrl command.
38 -a <WIN>
41 Switch to the desktop containing the window <WIN>, raise the
42 window, and give it focus.
43 -b ( add | remove | toggle),prop1 [,prop2 ]
46 Add, remove, or toggle up to two window properties simultane‐
47 ously. The window that is being modified must be identified with
48 a -r action. The property change is achived by using the EWMH
49 _NET_WM_STATE request. The supported property names (for prop1
50 and prop2) are modal, sticky, maximized_vert, maximized_horz,
51 shaded, skip_taskbar, skip_pager, hidden, fullscreen, above and
52 below. Two properties are supported to allow operations like
53 maximizing a window to full screen mode. Note that this action
54 is made up of exactly two shell command line arguments.
55 -c <WIN>
59 Close the window <WIN> gracefully.
60 -d List all desktops managed by the window manager. One line is
63 output for each desktop, with the line broken up into space
64 separated columns. The first column contains an integer desktop
65 number. The second column contains a '*' character for the
66 current desktop, otherwise it contains a '-' character. The next
67 two columns contain the fixed string DG: and then the desktop
68 geometry as '<width>x<height>' (e.g. '1280x1024'). The following
69 two columns contain the fixed string VP: and then the viewport
70 position in the format '<y>,<y>' (e.g. '0,0'). The next three
71 columns after this contains the fixed string WA: and then two
72 columns with the workarea geometry as 'X,Y and WxH' (e.g. '0,0
73 1280x998'). The rest of the line contains the name of the
74 desktop (possibly containing multiple spaces).
75 -e <MVARG>
78 Resize and move a window that has been specified with a -r
79 action according to the <MVARG> argument.
80 -g w,h Change the geometry (common size) of all desktops so they are w
83 pixels wide and h pixels high. w and h must be positive
84 integers. A window manager may ignore this request.
85 -h Print help text about program usage.
88 -I name
91 Set the icon name (short title) of the window specified by a -r
92 action to name.
93 -k ( on | off )
96 Turn on or off the window manager's "show the desktop" mode (if
97 the window manager implements this feature).
98 -l List the windows being managed by the window manager. One line
101 is output for each window, with the line broken up into space
102 separated columns. The first column always contains the window
103 identity as a hexadecimal integer, and the second column always
104 contains the desktop number (a -1 is used to identify a sticky
105 window). If the -p option is specified the next column will
106 contain the PID for the window as a decimal integer. If the -G
107 option is specified then four integer columns will follow: x-
108 offset, y-offset, width and height. The next column always
109 contains the client machine name. The remainder of the line
110 contains the window title (possibly with multiple spaces in the
111 title).
112 -m Display information about the window manager and the
115 environment.
116 -n N Change the number of desktops to N (a non-negative integer).
119 -N name
122 Set the name (long title) of the window specified by a -r action
123 to name.
124 -o x,y Change the viewport for the current desktop. The values x and y
128 are numeric offsets that specify the position of the top left
129 corner of the viewport. A window manager may ignore this
130 request.
131 -r <WIN>
134 Specify a target window for an action.
135 -R <WIN>
138 Move the window <WIN> to the current desktop, raise the window,
139 and give it focus.
140 -s <DESK>
143 Switch to the desktop <DESK>.
144 -t <DESK>
147 Move a window that has been specified with the -r action to the
148 desktop <DESK>.
149 -T name
152 Set the both the name (long title) and icon name (short title)
153 of the window specified by a -r action to name. This action is
154 like using the -N and -I actions at the same time (which would
155 otherwise be impossible since wmctrl can execute only one action
156 at a time).
157
161 The following options modify the default actions, or they modify the
162 interpretation of arguments.
163 -F Window name arguments (<WIN>) are to be treated as exact window
166 titles that are case sensitive. Without this options window
167 titles are considered to be case insensitive substrings of the
168 full window title.
169 -G Include geometry information in the output of the -l action.
172 -i Interpret window arguments (<WIN>) as a numeric value rather
175 than a string name for the window. If the numeric value starts
176 with the prefix '0x' it is assumed to be a hexadecimal number.
177 -p Include PIDs in the window list printed by the -l action. Prints
180 a PID of '0' if the application owning the window does not
181 support it.
182 -u Override auto-detection and force UTF-8 mode.
185 -v Provide verbose output. This is really useful when debugging
188 wmctrl itself.
189 -w [ <WORKAROUND>[,<WORKAROUND>]... ]
192 Use workarounds specified in the argument.
193 -x Include WM_CLASS in the window list or interpret <WIN> as the
196 WM_CLASS name.
197
201 <DESK> A Desktop is always specified by an integer which represents the
202 desktop numbers. Desktop numbers start at 0. Use -1 to pin to
203 all desktops.
204 <MVARG>
207 A move and resize argument has the format 'g,x,y,w,h'. All five
208 components are integers. The first value, g, is the gravity of
209 the window, with 0 being the most common value (the default
210 value for the window). Please see the EWMH specification for
211 other values.
212 The four remaining values are a standard geometry specification:
214 x,y is the position of the top left corner of the window, and
215 w,h is the width and height of the window, with the exception
216 that the value of -1 in any position is interpreted to mean that
217 the current geometry value should not be modified.
218 <WIN> This argument specifies a window that is the target of an
222 action. By default the argument is treated as if were a string,
223 and windows are examined until one is found with a title the
224 contains the specified string as a substring. The substring
225 matching is done in a case insensitive manner. The -F option may
226 be used to force exact, case sensitive title matching. The
227 option -i may be used to interpret the window target as a
228 numeric window identity instead of a string.
229 The window name string :SELECT: is treated specially. If this
231 window name is used then wmctrl waits for the user to select the
232 target window by clicking on it.
233 The window name string :ACTIVE: may be used to instruct wmctrl
235 to use the currently active window for the action.
236 <WORKAROUND>
240 There is only one work around currently implemeted. It is
241 specified by using the string DESKTOP_TITLES_INVALID_UTF8 and it
242 causes the printing of non-ASCII desktop tiles correctly when
243 using Window Maker.
244
249 Getting a list of windows managed by the window manager
250 wmctrl -l
252 Getting a list of windows with PID and geometry information.
254 wmctrl -p -G -l
256 Going to the window with a name containing 'emacs' in it
258 wmctrl -a emacs
260 Shade a window with a title that contains the word 'mozilla'
262 wmctrl -r mozilla -b add,shaded
264 Close a very specifically titled window sticky
266 wmctrl -F -c 'Debian bug tracking system - Mozilla'
268 Toggle the 'stickiness' of a window with a specific window identity
270 wmctrl -i -r 0x0120002 -b add,sticky
272 Change the title of window to a specified string but choose the window
274 by clicking on it
275 wmctrl -r :SELECT: -T "Selected Window"
277
279 zenity(1) is a useful dialog program for building scripts with wmctrl.
280 Some examples of EWMH/NetWM compatible window managers include recent
282 versions of Enlightenment, Icewm, Kwin, Sawfish and Xfce.
283
285 wmctrl was written by Tomas Styblo <tripie@cpan.org>.
286 This manual page was written by Shyamal Prasad <shyamal@member.fsf.org>
288 for the Debian project (but may be used by others).
289 December 12, 2004 WMCTRL(1)