spiralofhope logo
spiralofhope logo

S
piral of Hope
Better software is possible.
Styles
Table of Contents

wmctrl >


Pre-intro

/Continued from GNU Proofreaders shut down, and a rant on documentation. /

wmctrl is one of very few programs which give control over your various windows within X. kde (with a GUI) and openbox (via rc.xml) have a way, and some other applications include Devil's Pie, and some tools which come with X; xdpyinfo; xprop; xlsclients; xlsatoms; and xwininfo. Please contact me if you find any other interesting tools.

Notice that in this list there are two third-party programs. Two. Of all of these, wmctrl seems to be the only tool which can actually do things to an existing window from the commandline. It was last updated in 2005. Seriously, we all use X daily but the tools are .. I don't even have the words; welcome to the world of Linux.

I'm not even going to go into the rant of users needing creating the documentation for the software they use. I've already covered that in my previous post.

Introduction

Sometime in 2007 I did a lot of work to figure wmctrl out. I essentially cleaned up its man page and created examples. I also came up with quite a number of questions along the way. Just the other day I was prompted to find those old notes and post them. I intended to get wmctrl and re-test things, but I have issues compiling it, probably because of my 64bit awesomeness and newer x libraries. .. and that damned type declaration. I don't feel like hacking around in the wmctrl source code (right now?) or getting help for it, but I'll get those notes for you anyway. The notes ought to still be good since the "latest" wmctrl version has not changed. However, the transition from one format to another might mean there are odd mistakes (missing spaces, incorrect characters) so please contact me if you have any issues or you'd like an update. This is probably the best piece of documentation on wmctrl and I demand perfection out of my docs. I'm the kind of guy who will put two spaces after a period in HTML (where the second is discarded).

There are two reasons I was hesitant to just copy-and-paste my notes. One is that I intended to put them up on my CMS when it got built. The other is that I really wanted to re-test everything and provide even better examples. I've learned in the few years that I've played with wmctrl, and I'm positive I could build some cool scripts to really help people out. But until things come together, I suppose this'll get trapped in a blog post.

Blogs are SO inappropriate for resources like this which ought to be kept up-to-date. Wikis ftw.

Show information about the window manager and about the environment.

wmctrl -m

Name: Blackbox
Class: N/A
PID: N/A
Window manager's "showing the desktop" mode: N/A

List windows managed by the window manager.

wmctrl -l

0x0080006a -1 localhost panel
0x0180007c  0 localhost Mozilla Firefox
0x02600007  3 localhost user@localhost: /home/user - Shell - Konsole
0x00600011  1 localhost KTorrent
0x02200007  0 localhost user@localhost: /home/user - Shell - Konsole
1           2 3         4
The columns:
  1. The window ID. This is used for the [#i -i] switch.
  2. The desktop ID. It begins counting at 0. -1 means that window is on all desktops. Used with [#d -d] and more.
  3. The client machine
  4. The name (long title) of the window. Used with [#r -r] mostly, and can be renamed with [#N -N] and [#T -T].

List desktops.

List desktops. The current desktop is marked with an asterisk.

wmctrl -d

0  * DG: 1920x1200  VP: 0,0  WA: 0,0 1920x1200
1  - DG: 1920x1200  VP: N/A  WA: 0,0 1920x1200
2  - DG: 1920x1200  VP: N/A  WA: 0,0 1920x1200
3  - DG: 1920x1200  VP: N/A  WA: 0,0 1920x1200
1  2 3              4        5
The columns:

  1. the desktop number. It begins counting at 0.
  2. '*' means it's the current desktop
  3. geometry
  4. viewport
  5. workarea
  6. TODO: title -- the man page describes this, but it's missing from the command. File a bug report.

Switch to the specified desktop.

# Create two desktops:
wmctrl [#n -n] 1
  1. Switch to desktop 1
wmctrl -s 1
notes
  • The programmer starts counting at 0. So 1 means the second desktop.
  • Your window manager must be configured to provide multiple desktops for this to mean anything.

Activate a window.

Activate the window by switching to its desktop and raising it.

# Create two desktops:
wmctrl [#n -n] 1
  1. Switch to desktop 1:
wmctrl [#s -s] 0
  1. Move the window to another desktop:
wmctrl [#r -r] "KTorrent" -t 1
  1. Activate the window by switching to its desktop and raising it:
wmctrl -a "KTorrent"
notes:

Close the window gracefully.

wmctrl -c [#r -r] "KTorrent"
notes:

Move the window to the current desktop and activate it.

# Create two desktops:
wmctrl [#n -n] 1
  1. Switch to desktop 1:
wmctrl [#s -s] 0
  1. Move the window to another desktop:
wmctrl [#r -r] "KTorrent" -t 1
  1. Switch to that window's desktop and activate that window:
wmctrl -R "KTorrent"
notes:

Move the window to the specified desktop.

# Create two desktops:
wmctrl [#n -n] 1
  1. Switch to desktop 1:
wmctrl [#s -s] 0
  1. Move the window to another desktop:
wmctrl [#r -r] "KTorrent" -t 1
notes:

Resize and move the window around the desktop.

wmctrl [#r -r] "KTorrent" -e 1,0,0,800,600
                             1 2 3 4   5
This example will move the window to the top-left of the screen (0,0) and resize it to 800x600 pixels. The five options are: "gravity,X,Y,width,height":

  1. gravity -- I'm not sure what this
    1. 0 means 'default' and the coordinates of 0,0 will move the window too high up.
    2. 1 seems to look good for me.
  2. X -- The X coordinates. How far from the left the window will begin. Use -1 to leave this value as-is.
  3. Y -- The Y coordinates. How far from the top the window will begin. Use -1 to leave this value as-is.
  4. width -- The new window width in pixels Use -1 to leave this value as-is.
  5. height -- The new window hight in pixels. Use -1 to leave this value as-is.
notes:

Change the state of the window.

Change the state of the window. Using this option it's possible for example to make the window maximized, minimized or fullscreen.

1.07 fullscreen issue (see below)

  • above -- works
  • below -- works
  • TODO: demands_attention -- this is defined in the EWMH specs but was not listed in the wmctrl manual and does not appear to be supported. Request it.
  • Examples:
    wmctrl [#r -r] "KTorrent" -b add,shaded
    wmctrl [#r -r] "KTorrent" -b remove,shaded
    wmctrl [#r -r] "KTorrent" -b toggle,shaded
    
    Multiple commands at once are done like this:
    wmctrl [#r -r] "KTorrent" -b toggle,shaded,maximized_horz
    

    Set the long title of the window.

    Set the name (long title) of the window.

    wmctrl [#r -r] "KTorrent" -N "something"
    wmctrl [#r -r] "something" -N "KTorrent"
    
    notes: Their example shows 'zenity' but I prefer kdialog. In a terminal emulator window, do:
    title=`kdialog --title "Change window title" \
      --inputbox "New window title"`; \
      wmctrl -r :SELECT: -T "$title"
    
    complex stuff:

    It would be nice if I could have regular expressions which could match a title. I can partially understand how it could be done, but I don't want to bother implementing the feature myself. =/ Some nonsense like this:

    wmtrl -r `wmtrl -l|grep title|othergrep <first 10 characters>` -N "new title"
    
    Where the othergrep thing matches the 10 characters at the beginning of each line. I don't know how to do that though. Something like (^..........) or (^.{10}) I think.

    Set the short title of the window.

    Set the icon name (short title) of the window.

    wmctrl -r "KTorrent" -I "string"
    
    notes:

    Set both the long and short title of the window.

    wmctrl -r "KTorrent" -T "string"
    
    notes:

    Activate or deactivate the window manager's "showing the desktop" mode.

    Activate or deactivate window manager's "showing the desktop" mode. Many window managers do not implement this mode.

    wmctrl -k on
    wmctrl -k off
    
    notes:

    Change the viewport for the current desktop.

    Change the viewport for the current desktop. The X and Y values are separated with a comma. They define the top left corner of the viewport. The window manager may ignore the request.

    wmctrl -o 1024,768
    
    notes:

    Change the number of desktops.

    Change number of desktops. The window manager may ignore the request.

    Learn how many desktops you have:

    $ wmctrl [#d -d]
    0  * DG: 1920x1200  VP: 0,0  WA: 0,0 1920x1200
    1  - DG: 1920x1200  VP: N/A  WA: 0,0 1920x1200
    2  - DG: 1920x1200  VP: N/A  WA: 0,0 1920x1200
    3  - DG: 1920x1200  VP: N/A  WA: 0,0 1920x1200
    
    
    Create two desktops:
    wmctrl -n 1
    
    Now check again:
    $ wmctrl [#d -d]
    0  * DG: 1920x1200  VP: 0,0  WA: 0,0 1920x1200
    1  - DG: 1920x1200  VP: N/A  WA: 0,0 1920x1200
    
    notes:

    Change the geometry of all desktops.

    Change geometry (common size) of all desktops. The window manager may ignore the request.

    wmctrl -g 1024,768
    
    notes:

    Print help.

    wmctrl -h
    
    (basically prints the man page)

    Options and misc.

    --version
    

    Interpret <WIN> as a numerical window ID.

    The -i option may be used to interpret the argument as a numerical window ID

    $wmctrl [#l -l]
    0x00600056 -1 localhost panel
    0x02000143  0 localhost Mozilla Firefox
    0x00400007  0 localhost user@localhost: /home/user - Shell - Konsole
    0x00e00011  0 localhost KTorrent
    wmctrl -i 0x00e00011 [#b -b] toggle,shaded
    
    notes:
    • This is an alternate to using [#r -r].
    • Defaults to use a decimal number.
    • If it starts with "0x", then it's assumed to be a hexadecimal number.
    • TODO: <WIN> as a numerical window ID doesn't seem to work consistently. Perhaps not all options support it or something crazy is going on. It used to work very well for me. Re-test.

    Include PIDs in the window list.

    Include PIDs in the window list. Very few X applications support this feature.

    wmctrl [#l -l] -p
    
    0x00600056 -1 4302   localhost panel
    0x02000143  0 5964   localhost Mozilla Firefox
    0x00400007  0 8639   localhost user@localhost: /home/user - Shell - Konsole
    0x00e00011  0 8706   localhost KTorrent
    
    notes:
    • blackbox supports this. =)

    Include geometry in the window list.

    wmctrl [#l -l] -G
    
    0x00600056 -1 0    1174 1920 26   localhost panel
    0x02000143  0 649  25   1285 1147 localhost Mozilla Firefox
    0x00400007  0 43   59   1092 481  localhost user@localhost: /home/user - Shell - Konsole
    0x00e00011  0 51   653  904  509  localhost KTorrent
    

    Include WM_CLASS in the window list or interpret <WIN> as the WM_CLASS name.

    wmctrl -l -x
    
    0x00600056 -1 panel.fbpanel         localhost panel
    0x02000143  0 Gecko.Mozilla-firefox-bin  localhost Mozilla Firefox
    0x00400007  0 Qt-subapplication.    localhost user@localhost: /home/user - Shell - Konsole
    0x00e00011  0 ktorrent.Ktorrent     localhost KTorrent
    
    notes:
    • TODO: describe interpreting <WIN> as the WM_CLASS name. Useful for: [#a -a], [#c -c], [#R -R] and [#r -r].

    Override auto-detection and force UTF-8 mode.

    wmctrl -u (other switches)
    

    Match the full window title and be case-sensitive

    Modifies the behavior of the window title matching algorithm. It will match only the full window title instead of a substring, when this option is used. Furthermore it makes the matching case sensitive.

    wmctrl -F (other switches)
    

    Be verbose.

    Be verbose. Useful for debugging.

    wmctrl [#l -l]
    0x00600056 -1 localhost panel
    0x02000143  0 localhost Mozilla Firefox
    0x00400007  0 localhost user@localhost: /home/user - Shell - Konsole
    0x00e00011  0 localhost KTorrent
    
    wmctrl [#l -l] -v
    envir_utf8: 1
    0x00600056 -1 localhost panel
    0x02000143  0 localhost Mozilla Firefox
    Invalid type of WM_NAME property.
    0x00400007  0 localhost user@localhost: /home/user - Shell - Konsole
    Invalid type of WM_NAME property.
    0x00e00011  0 localhost KTorrent
    

    Use a workaround.

    Use a workaround. The option may appear multiple times

    wmctrl -w DESKTOP_TITLES_INVALID_UTF8 (other switches)
    
    list of options as of 1.07
    • DESKTOP_TITLES_INVALID_UTF8 -- Print non-ASCII desktop titles correctly when using Window Maker.

    -r

    wmctrl -r is used to specify the window name (long title) to act on. It is used for a number of features:

    notes:
    • It's interpreted as a string.
    • It's matched against the window name (long title)
    • Only the first matching window is used.
    • The matching isn't case sensitive
    • The string may appear in any position of the title.
    • If you don't want to use the name of the window, then try the [#i -i] switch.

    acting on a mouse-selected window

    Select the window by clicking on it.

    wmctrl [#b -b] toggle,shaded [#r -r] :SELECT:
    

    acting on the current window

    Use the currently active window for the action.

    wmctrl [#b -b] toggle,shaded [#r -r] :ACTIVE:
    

    real-world examples

    force window dimensions when launching an app

    A bbkeys hotkey can be set up to use xtoolwait and wmctrl to force a specific size. If a second occurrence is launched, I can relocate that one and resize it.

    [Execute] (Mod1-Control-F) {xtoolwait yourapp & wmpid=$! && wait $wmpid && wmctrl -F -r "yourapp title" -e 1,0,0,800,1148 && wmctrl -F -r "yourapp other title" -e 1,800,0,800,1148}
    
    It's not hard to have this as a simple script like this:
    xtoolwait yourapp & wmpid=$!
    wait $wmpid
    wmctrl -F -r "yourapp title" -e 1,0,0,800,1148
    
    I'd bet that anyone decent with bash could whip up something that's nice and reusable too. (TODO)

    Also, I'm going to post a user addition here. I'm unable to do any real testing on it without wmctrl working.

    wmctrl -ir `wmctrl -lx | grep Pidgin.Pidgin | cut -d" " -f1` -e 0,1200,0,-1,-1
    
    I also just bumped into some patches for wmctrl. I haven't read any further and haven't tested them out.

    Issues

    Fullscreen Issue

    Proof that wmctrl usually works

    (Blackbox 0.70.1)

    1) Start xine windowed

    xine dvd://
    
    2) alt-tab back to your term

    3) Prove that wmctrl can communicate to xine and fullscreen works:

    wmctrl -r "xine" -b toggle,fullscreen
    
    (fullscreen now)

    4) alt-tab back to your term (you might need to do it twice)

    5) Prove that wmctrl can remove fullscreen:

    wmctrl -r "xine" -b toggle,fullscreen
    
    (windowed now)

    6) Another proof:

    wmctrl -r "xine" -b toggle,fullscreen
    
    (fullscreen now)

    wmctrl -r "xine" -b remove,fullscreen
    
    (windowed now)

    Proof of an issue when the app starts fullscreen

    1) Start xine fullscreen

    xine -f dvd://
    
    2) Now alt-tab back out to your term. You might have to click on the xine window for alt-tab to work.

    3) try to remove fullscreen

    wmctrl -r "xine" -b remove,fullscreen
    
    This does not do anything.

    wmctrl -r "xine" -b toggle,fullscreen
    
    This does not do anything.

    Firefox is not visible in the list of managed windows

    0x00c0001e 4294967295 localhost.localdomain panel
    0x01400033  1 localhost.localdomain 37. 3 Doors Down - The Better Life - Be Like That (4:25) - Audacious
    0x0140003a  1 localhost.localdomain Audacious Playlist Editor
    0x00800003  0 localhost.localdomain *compile.rb - /home/user/live/Projects/compiled-website/0.5.3/rb - Geany
    
    Where the hell is Firefox?