WMCTRL(1)                       General Commands Manual                       WMCTRL(1)

NAME
       wmctrl - interact with a EWMH/NetWM compatible X Window Manager.

SYNOPSIS
       wmctrl [ options | actions ]...

DESCRIPTION
       wmctrl  is  a command that can be used to interact with an X Window manager that
       is compatible with the EWMH/NetWM specification.  wmctrl can  query  the  window
       manager  for  information, and it can request that certain window management ac‐
       tions be taken.

       wmctrl is controlled entirely by its command line arguments.  The  command  line
       arguments are used to specify the action to be performed (with options that mod‐
       ify behavior) and any arguments that might be needed to perform the actions.

       The following sections define the supported actions and  options.  Arguments  to
       the  actions  and  options are written in the form <ARGNAME> in the descriptions
       below. The detailed syntax for writing arguments are in a single  section  dedi‐
       cated to that purpose.

ACTIONS
       The following command line arguments can be specified to invoke a wmctrl action.
       Only one action can be executed with the invocation of the wmctrl command.

       -a <WIN>
              Switch to the desktop containing the window <WIN>, raise the window,  and
              give it focus.

       -b  ( add | remove | toggle),prop1 [,prop2 ]
              Add,  remove,  or  toggle up to two window properties simultaneously. The
              window that is being modified must be identified with a  -r  action.  The
              property  change  is achived by using the EWMH _NET_WM_STATE request. The
              supported property  names  (for  prop1  and  prop2)  are  modal,  sticky,
              maximized_vert, maximized_horz, shaded, skip_taskbar, skip_pager, hidden,
              fullscreen, above and below.  Two properties are supported to allow oper‐
              ations  like  maximizing a window to full screen mode. Note that this ac‐
              tion is made up of exactly two shell command line arguments.

       -c <WIN>
              Close the window <WIN> gracefully.

       -d     List all desktops managed by the window manager. One line is  output  for
              each  desktop,  with the line broken up into space separated columns. The
              first column contains an integer desktop number. The second  column  con‐
              tains  a  '*'  character for the current desktop, otherwise it contains a
              '-' character. The next two columns contain the fixed string DG: and then
              the  desktop  geometry as '<width>x<height>' (e.g. '1280x1024'). The fol‐
              lowing two columns contain the fixed string VP: and then the viewport po‐
              sition in the format '<y>,<y>' (e.g. '0,0'). The next three columns after
              this contains the fixed string WA: and then two columns with the workarea
              geometry  as  'X,Y  and  WxH' (e.g. '0,0 1280x998'). The rest of the line
              contains the name of the desktop (possibly containing multiple spaces).

       -e <MVARG>
              Resize and move a window that has been specified with a -r action accord‐
              ing to the <MVARG> argument.

       -g w,h Change  the  geometry  (common size) of all desktops so they are w pixels
              wide and h pixels high. w and h must be positive integers. A window  man‐
              ager may ignore this request.

       -h     Print help text about program usage.

       -I name
              Set the icon name (short title) of the window specified by a -r action to
              name.

       -k  ( on  |  off  )
              Turn on or off the window manager's "show the desktop" mode (if the  win‐
              dow manager implements this feature).

       -l     List  the windows being managed by the window manager. One line is output
              for each window, with the line broken up into  space  separated  columns.
              The first column always contains the window identity as a hexadecimal in‐
              teger, and the second column always contains the desktop number (a -1  is
              used to identify a sticky window). If the -p option is specified the next
              column will contain the PID for the window as a decimal integer.  If  the
              -G  option  is specified then four integer columns will follow: x-offset,
              y-offset, width and height. The next column always  contains  the  client
              machine name. The remainder of the line contains the window title (possi‐
              bly with multiple spaces in the title).

       -m     Display information about the window manager and the environment.

       -n N   Change the number of desktops to N (a non-negative integer).

       -N name
              Set the name (long title) of the window specified by a -r action to name.

       -o x,y Change the viewport for the current desktop. The values x and y  are  nu‐
              meric  offsets  that  specify  the position of the top left corner of the
              viewport. A window manager may ignore this request.

       -r <WIN>
              Specify a target window for an action.

       -R <WIN>
              Move the window <WIN> to the current desktop, raise the window, and  give
              it focus.

       -s <DESK>
              Switch to the desktop <DESK>.

       -t <DESK>
              Move  a  window that has been specified with the -r action to the desktop
              <DESK>.

       -T name
              Set the both the name (long title) and icon name  (short  title)  of  the
              window  specified  by a -r action to name.  This action is like using the
              -N and -I actions at the same time (which would otherwise  be  impossible
              since wmctrl can execute only one action at a time).

OPTIONS
       The following options modify the default actions, or they modify the interpreta‐
       tion of arguments.

       -F     Window name arguments (<WIN>) are to be treated as  exact  window  titles
              that  are  case sensitive. Without this options window titles are consid‐
              ered to be case insensitive substrings of the full window title.

       -G     Include geometry information in the output of the -l action.

       -i     Interpret window arguments (<WIN>) as  a  numeric  value  rather  than  a
              string  name  for the window. If the numeric value starts with the prefix
              '0x' it is assumed to be a hexadecimal number.

       -p     Include PIDs in the window list printed by the -l action. Prints a PID of
              '0' if the application owning the window does not support it.

       -u     Override auto-detection and force UTF-8 mode.

       -v     Provide  verbose  output. This is really useful when debugging wmctrl it‐
              self.

       -w [ <WORKAROUND>[,<WORKAROUND>]... ]
              Use workarounds specified in the argument.

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

ARGUMENTS
       <DESK> A  Desktop is always specified by an integer which represents the desktop
              numbers. Desktop numbers start at 0.

       <MVARG>
              A move and resize argument has the format 'g,x,y,w,h'.  All  five  compo‐
              nents  are  integers.  The  first value, g, is the gravity of the window,
              with 0 being the most common value (the default value  for  the  window).
              Please see the EWMH specification for other values.

              The  four  remaining values are a standard geometry specification: x,y is
              the position of the top left corner of the window, and w,h is  the  width
              and  height of the window, with the exception that the value of -1 in any
              position is interpreted to mean that the current  geometry  value  should
              not be modified.

       <WIN>  This  argument specifies a window that is the target of an action. By de‐
              fault the argument is treated as if were a string, and windows are  exam‐
              ined until one is found with a title the contains the specified string as
              a substring. The substring matching is done in a case insensitive manner.
              The  -F option may be used to force exact, case sensitive title matching.
              The option -i may be used to interpret the window  target  as  a  numeric
              window identity instead of a string.

              The window name string :SELECT: is treated specially. If this window name
              is used then wmctrl waits for the user to select  the  target  window  by
              clicking on it.

              The window name string :ACTIVE: may be used to instruct wmctrl to use the
              currently active window for the action.

       <WORKAROUND>
              There is only one work around currently implemeted. It  is  specified  by
              using  the  string DESKTOP_TITLES_INVALID_UTF8 and it causes the printing
              of non-ASCII desktop tiles correctly when using Window Maker.

EXAMPLES
       Getting a list of windows managed by the window manager

              wmctrl -l

       Getting a list of windows with PID and geometry information.

              wmctrl -p -G -l

       Going to the window with a name containing 'emacs' in it

              wmctrl -a emacs

       Shade a window with a title that contains the word 'mozilla'

              wmctrl -r mozilla -b add,shaded

       Close a very specifically titled window sticky

              wmctrl -F -c 'Debian bug tracking system - Mozilla'

       Toggle the 'stickiness' of a window with a specific window identity

              wmctrl -i -r 0x0120002 -b add,sticky

       Change the title of window to a specified string but choose the window by click‐
       ing on it

              wmctrl -r :SELECT: -T "Selected Window"

SEE ALSO
       zenity(1) is a useful dialog program for building scripts with wmctrl.

       Some  examples  of EWMH/NetWM compatible window managers include recent versions
       of Enlightenment, Icewm, Kwin, Sawfish and Xfce.

AUTHOR
       wmctrl was written by Tomas Styblo <tripie@cpan.org>.

       This manual page was written by Shyamal Prasad <shyamal@member.fsf.org> for  the
       Debian project (but may be used by others).

                                   December 12, 2004                          WMCTRL(1)

wmctrl 1.07
Usage: wmctrl [OPTION]...
Actions:
  -m                   Show information about the window manager and
                       about the environment.
  -l                   List windows managed by the window manager.
  -d                   List desktops. The current desktop is marked
                       with an asterisk.
  -s <DESK>            Switch to the specified desktop.
  -a <WIN>             Activate the window by switching to its desktop and
                       raising it.
  -c <WIN>             Close the window gracefully.
  -R <WIN>             Move the window to the current desktop and
                       activate it.
  -r <WIN> -t <DESK>   Move the window to the specified desktop.
  -r <WIN> -e <MVARG>  Resize and move the window around the desktop.
                       The format of the <MVARG> argument is described below.
  -r <WIN> -b <STARG>  Change the state of the window. Using this option it's
                       possible for example to make the window maximized,
                       minimized or fullscreen. The format of the <STARG>
                       argument and list of possible states is given below.
  -r <WIN> -N <STR>    Set the name (long title) of the window.
  -r <WIN> -I <STR>    Set the icon name (short title) of the window.
  -r <WIN> -T <STR>    Set both the name and the icon name of the window.
  -k (on|off)          Activate or deactivate window manager's
                       "showing the desktop" mode. Many window managers
                       do not implement this mode.
  -o <X>,<Y>           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.
  -n <NUM>             Change number of desktops.
                       The window manager may ignore the request.
  -g <W>,<H>           Change geometry (common size) of all desktops.
                       The window manager may ignore the request.
  -h                   Print help.

Options:
  -i                   Interpret <WIN> as a numerical window ID.
  -p                   Include PIDs in the window list. Very few
                       X applications support this feature.
  -G                   Include geometry in the window list.
  -x                   Include WM_CLASS in the window list or
                       interpret <WIN> as the WM_CLASS name.
  -u                   Override auto-detection and force UTF-8 mode.
  -F                   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.
  -v                   Be verbose. Useful for debugging.
  -w <WA>              Use a workaround. The option may appear multiple
                       times. List of available workarounds is given below.

Arguments:
  <WIN>                This argument specifies the window. By default it's
                       interpreted as a string. The string is matched
                       against the window titles and the first matching
                       window is used. The matching isn't case sensitive
                       and the string may appear in any position
                       of the title.

                       The -i option may be used to interpret the argument
                       as a numerical window ID represented as a decimal
                       number. If it starts with "0x", then
                       it will be interpreted as a hexadecimal number.

                       The -x option may be used to interpret the argument
                       as a string, which is matched against the window's
                       class name (WM_CLASS property). Th first matching
                       window is used. The matching isn't case sensitive
                       and the string may appear in any position
                       of the class name. So it's recommended to  always use
                       the -F option in conjunction with the -x option.

                       The special string ":SELECT:" (without the quotes)
                       may be used to instruct wmctrl to let you select the
                       window by clicking on it.

                       The special string ":ACTIVE:" (without the quotes)
                       may be used to instruct wmctrl to use the currently
                       active window for the action.

  <DESK>               A desktop number. Desktops are counted from zero.

  <MVARG>              Specifies a change to the position and size
                       of the window. The format of the argument is:

                       <G>,<X>,<Y>,<W>,<H>

                       <G>: Gravity specified as a number. The numbers are
                          defined in the EWMH specification. The value of
                          zero is particularly useful, it means "use the
                          default gravity of the window".
                       <X>,<Y>: Coordinates of new position of the window.
                       <W>,<H>: New width and height of the window.

                       The value of -1 may appear in place of
                       any of the <X>, <Y>, <W> and <H> properties
                       to left the property unchanged.

  <STARG>              Specifies a change to the state of the window
                       by the means of _NET_WM_STATE request.
                       This option allows two properties to be changed
                       simultaneously, specifically to allow both
                       horizontal and vertical maximization to be
                       altered together.

                       The format of the argument is:

                       (remove|add|toggle),<PROP1>[,<PROP2>]

                       The EWMH specification defines the
                       following properties:

                           modal, sticky, maximized_vert, maximized_horz,
                           shaded, skip_taskbar, skip_pager, hidden,
                           fullscreen, above, below

Workarounds:

  DESKTOP_TITLES_INVALID_UTF8      Print non-ASCII desktop titles correctly
                                   when using Window Maker.

The format of the window list:

  <window ID> <desktop ID> <client machine> <window title>

The format of the desktop list:

  <desktop ID> [-*] <geometry> <viewport> <workarea> <title>


Author, current maintainer: Tomas Styblo <tripie (at) cpan (dot) org>
Released under the GNU General Public License.
Copyright (C) 2003