Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
WMCTRL(1)		    General Commands Manual		     WMCTRL(1)

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

       wmctrl [	options	| actions ]...

       wmctrl  is a command that can be	used to	interact with an X Window man-
       ager that is compatible with the	EWMH/NetWM specification.  wmctrl  can
       query  the window manager for information, and it can request that cer-
       tain window management actions be taken.

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

       The  following sections define the supported actions and	options. Argu-
       ments 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 dedicated to	that purpose.

       The following command line arguments can	be specified to	invoke a  wmc-
       trl  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 simultane-
	      ously. 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 operations like
	      maximizing a window to full screen mode. Note that  this	action
	      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	 contains  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 following
	      two columns contain the fixed string VP: and then	 the  viewport
	      position	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 according 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 manager 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 window 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 integer, 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	(possibly with multiple	spaces in  the

       -m     Display	information   about   the   window   manager  and  the

       -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 numeric offsets that specify the position of	the  top  left
	      corner  of  the  viewport.  A  window  manager  may  ignore this

       -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).

       The following options modify the	default	actions, or  they  modify  the
       interpretation 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  considered 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 itself.

       -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.

       _DESK_ A	Desktop	is always specified by an integer which	represents the
	      desktop numbers. Desktop numbers start at	0.

	      A	move and resize	argument has the format	'g,x,y,w,h'.  All five
	      components 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 default the argument is treated as if were a  string,
	      and  windows  are	 examined  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.

	      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.

       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 clicking on it

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

       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.

       wmctrl was written by Tomas Styblo <>.

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

			       December	12, 2004		     WMCTRL(1)


Want to link to this manual page? Use this URL:

home | help