ellis@cadillac.siemens.COM (Ellis Cohen) (10/02/87)
USING WM_CLASS, WM_NAME and WM_ICON_NAME
A GUIDE FOR APPLICATIONS AND WINDOW MANAGERS
The new WM_CLASS property has been added to the collection of X standard
properties primarily at the urging of the Tiled Window Project.
(However, we did not contribute its description in section 9.1.8 in the
Xlib manual). This note explains how we believe it should be used, and
how it differs from WM_NAME and WM_ICON_NAME.
To Application Writers
----------------------
After creating a window, the very first thing an application should do is
set its WM_CLASS. WM_CLASS contains two strings, the succintly named
"res-name" and "res-class".
The Xlib manual describes these strings in the following way:
res_name: used for the application name
res_class: used for the application class
Readers may find this a bit confusing, since if the application name is
"emacs", what should the class be if not also "emacs"?
From our discussions leading up to the introduction of WM_CLASS, we
believe a clearer description should be:
res_name: a fixed unique name that identifies a particular instance
of this application (e.g. "Main_Emacs_Window")
res_class: the application name (e.g. "emacs")
Clearly the application knows what "res_class" ought to be, but where
does it get "res_name"? Well, "res_name" should be determined either
by the user (who thinks this instance of emacs is the
"Main_Emacs_Window"), or from some sort of "session manager".
We recommend that applications
o Support a switch that can be used to set "res_name", such as
xterm's "-n" switch.
o Look for an environment variable named WM_IDENTITY that can be
used to set "res_name" (the switch, if present, should override
the environment variable)
o Leave res_name empty if neither the switch nor the environment
variable is provided.
WM_CLASS should only be set once! In this way, it differs from
WM_NAME and WM_ICON_NAME.
WM_NAME determines what appears in the window header. We recommend that
applications include the following in WM_NAME:
o res_name (if there is one)
o res_class (possibly only if there is no res_name)
o the machine on which the client is running
o Some indication of program state if appropriate (this is the place
to let the user know that you are trying to read a file or open a
connection). Since this can change, WM_NAME should be changed
each time the program state changes.
o (For applications like xterm or emacs that execute user scripts) --
a string that can be set (and queried) by the script. Typically,
scripts will use this string to store the current directory, the
current file being worked on, etc.
[ Some window managers, ours included, have options that can
automatically put the contents of WM_CLIENT_MACHINE, WM_CLASS, and/or
WM_COMMAND in the header along with WM_NAME. We believe all
intelligent window managers ought to do this, which means that WM_NAME
ought to contain only transitory information (i.e. the program state
and the string used by scripts). Since there is no agreement on this,
however, we cannot currently recommend this course of action. ]
WM_ICON_NAME is similar to WM_NAME, but should be shorter since it will
have to fit in an icon. It is hard to make specific suggestions, but in
our environemnt, we have found it important to include res_name,
res_class, and the client machine in the icon, finding the transitory
information (program state and the the script string) less important when
the window is iconized.
To Window Manager Writers
-------------------------
WM_CLASS is new. Beware! Not all applications will use it or use it
correctly.
Use WM_CLASS to retrieve the application's resources from the application
database. Consider an application with an res_name of
"Main_Emacs_Window" and an res_class of "emacs". To find a resource,
for example, the background color to be used in the header, you should
first look for
Main_Emacs_Window.header.background
and if that fails, try
emacs.header.background
Since some applications will forget to use WM_CLASS, if WM_NAME has been
specified, but not WM_CLASS, treat the contents of WM_NAME as the class.
Many window manager writers will want to provide a snapshot facility:
That is, a file produced by the window manager that contains a
description of each window known to the window manager, including
WM_CLASS, WM_CLIENT_MACHINE, WM_COMMAND, its state
(Inactive/Iconized/Normal/Zoomed), the geometry of the window and its
icon, and various window specific internal state and option settings.
When the window manager starts up, it should look at the windows and
icons currently open. Each one that matches an entry in the snapshot
file should be configured to match its geometry as specified in the
snapshot file.
Each application that is specified in the snapshot file which is not
running (i.e. doesn't match a window or icon already on the screen)
should be restarted by the window manager using the saved WM_COMMAND.
When it starts the application, the saved res_name in WM_CLASS should be
placed by the window manager in the application's environment as
WM_IDENTITY. An application should use WM_IDENTITY to re-initialize
res_name, which will allow the window manager to match the newly opened
window with the correct snapshot file entry, and initialize its geometry
correctly.
Ellis Cohen
Siemens RTL Tiled Window Project
(609) 734-6524
ellis.cohen@a.gp.cs.cmu.edu