Intro Introduction

Name

Intro – overview of reference page format.

Syntax

This section describes the command line syntax for invoking the client. Anything in bold type should be typed exactly as shown. Items in italics are parameters that should be replaced by
actual values when you enter the command. Anything enclosed in brackets is optional.
For example:

bitmap [options] filename

means to type the command bitmap followed by zero or more options from the list of options later on the reference page, followed by the name of the file containing the bitmap to be edited.

Description

This section explains the operation of the client. In some cases, there are additional descriptive sections later on the reference page.

Options

This section lists available command line options. In some cases, reference is made to “all of the standard X Toolkit command line options.” These X Toolkit options are listed in Chapter 9 of this guide, as well as in the first reference page in this section, which is simply labled X.

Resources

This section lists the resource variable names that can be specified in an .Xresources or other resource file. In some cases, reference is made to “all the core resource names and classes.” A list of the core names and classes appears in Appendix G, Athena Widget Resources. Syntax rules and examples appear in Chapter 10, Setting Resources. For complete information, see Volume Four, X Toolkit Intrinsics Programming Manual.

Widget Hierarchy

Applications written with the X Toolkit are comprised of widgets, which are pre-defined user interface components or objects. Typical widgets create graphical features such as menus, command buttons, dialog boxes, and scrollbars. Applications composed of widgets are always window-based (such as xterm, xclock, and xman). X also provides clients that are not window-based (such as xlsfonts, xwininfo, and xlsclients) and thus do not use widgets.

If present on a reference page, the section “Widget Hierarchy” diagrams the relationship of the widgets within the application. The widget hierarchy is significant in specifying client resources. Most Toolkit clients accept both application-specific resources (listed in the “Resources” section) and resources for the component widgets. Appendix G lists the user-settable resources for the Athena widgets and explains the somewhat complicated mechanisms by which resources are interpreted.

Files

If present, this section lists the system and/or application-specific files relevant to the application.

Environment

If present, this section lists shell environment variables used by the client. This section does not list the DISPLAY and XENVIRONMENT variables, which are used by all clients. These variables are used as follows:

DISPLAY

To get the default host and display number. The DISPLAY variable typically has the form:

hostname: display.screen

(for example, isla: 0.0).

XENVIRONMENT

To get the name of a resource file containing host-specific resources. If this variable is not set, the resource manager will look for a file called .Xdefaults-hostname (where hostname is the name of a particular host) in the user's home directory. See the X reference page for more information.

See Also

This section lists other reference pages in Part Three of this guide that may also be of interest. Note that versions of these pages may have been installed in the usual online manual hierarchy, and may be available via the UNIX man(1) command. References such as stat(2) can be found in the standard UNIX documentation. This section may also include references to documentation on Xlib, the X Toolkit, various widgets, etc.

Bugs

If present, this section lists areas in which the author of the program thinks it could be improved.

Author

The authors of the program and (generally) the reference page as well. Most of the reference pages are subject to the copyright provisions in the “Copyright” section of the X reference page. Where appropriate, additional copyrights are noted on individual pages.

Note, however, that those portions of this document that are based on the original X11 documentation and other source materials have been revised and that all such revisions are copyright © 1987, 1988, 1989 O'Reilly & Associates, Inc. Inasmuch as the proprietary revisions can't be separated from the freely copyable MIT source material, the net result is that copying of this document is not allowed. Sorry for the doublespeak!

X The X Window System

Name

X – a portable, network-transparent window system.

Description

X is a network-transparent window system developed at MIT that runs on a wide range of computing and graphics machines. The Release 4 core distribution from MIT supports the following operating systems:

Ultrix 3.1 (Digital)
SunOS 4.0.3 (Sun)
HP-UX 6.5 (Hewlett-Packard)
Domain/OS 10.1 (HP/Apollo)
A/UX 1.1 (Apple)
AIX RT-2.2 and PS/2-1.1 (IBM)
AOS-4.3 (IBM)
UTEK 4.0 (Tektronix)
NEWS-OS 3.2 (Sony; client only)
UNICOS 5.0.1 (Cray; client only)
UNIX™ System V, Release 3.2 (AT&T 6386 WGS; client only)

It should be relatively easy to build the client-side software on a variety of other systems. Commercial Implementations are also available for a much wider range of platforms.

The X Consortium requests that the following names be used when referring to this software:

X
X Window System
X Version 11
X Window System, Version 11
X11

The name “X Windows” should not be used. X Window System is a trademark of the Massachusetts Institute of Technology.

X window system servers run on computers with bitmap displays. The server distributes user input to and accepts output requests from various client programs through a variety of different interprocess communication channels. Although the most common case is for the client programs to be running on the same machine as the server, clients can also be run transparently from other machines, including machines with different architectures and operating systems).

X supports overlapping hierarchical subwindows and text and graphics operations, on both monochrome and color displays. For a full explanation of the functions that are available, see Volume One, Xlib Programming Manual, and Volume Two, Xlib Reference Manual.

The number of programs that use X is growing rapidly. Of particular interest are: a terminal emulator (xterm), a window manager (twm), a display manager (xdm), mail managing utilities (xmh and xbiff), a manual page browser (xman), a bitmap editor (bitmap), access control programs (xauth and xhost), user preference setting programs (xrdb, xset, xsetroot, and xmodmap), a load monitor (xload), clocks (oclock and xclock), a font displayer (xfd), utilities for listing information about fonts, windows, and displays (xlsfonts, xfontsel, xlswins, xwininfo, xdpyinfo, xlsclients, and xprop), a diagnostic for seeing what events are generated and when (xev), screen image manipulation utilities (xwd, xwud, xpr, and xmag), and various demos (xeyes, ico, muncher, puzzle, xgc, etc.).

Many other utilities, window managers, games, toolkits, and so on are available from the user-contributed distribution. See your site administrator for details.

Starting Up

There are two ways of starting the X server and an initial set of client applications. The particular method used depends on which operating system you are running and on whether or not you use other window systems in addition to X. The methods are:

xdm (the X Display Manager)

If you want to have X running on your display at all times, your site administrator can set up your machine to use the X Display Manager xdm. This program is typically started by the system at boot time and takes care of keeping the server running and getting users logged in. If you are running xdm, you will see a window on the screen welcoming you to the system and asking for your username and password. Simply type them in as you would at a normal terminal, pressing the Return key after each. If you make a mistake, xdm will display an error message and ask you to try again. After you have successfully logged in, xdm will start up your X environment. By default, if you have an executable file named .xsession in your home directory, xdm will treat it as a program (or shell script) to be run to start up your initial clients (such as terminal emulators, clocks, a window manager, user settings for things like the background, the speed of the pointer, etc.). Your site administrator can provide details.

xinit (run manually from the shell)

Sites that support more than one window system might choose to use the xinit program for starting X manually. If this is true for your machine, your site administrator will probably have provided a program named “x11”, “startx”, or “xstart” that will do site-specific initialization in a nice way (such as loading convenient default resources, running a window manager, displaying a clock, and starting several terminal emulators). If not, you can build such a script using the xinit program. This utility simply runs one user-specified program to start the server, runs another to start up any desired clients, and then waits for either to finish. Since either or both of the user-specified programs may be a shell script, this gives substantial flexibility at the expense of a nice interface. For this reason, xinit is not intended for end users.

Display Names

From the user's perspective, every X server has a displayname of the form:

host:display.screen

This information is used by the application to determine how it should connect to the server and which screen it should use by default (on displays with multiple monitors):

host

The name of the machine to which the display is physically connected. If the host name is not given, the most efficient way of communicating to a server on the same machine will be used.

display

The display number. The phrase “display” is usually used to refer to a collection of monitors that share a common keyboard and pointer (mouse, tablet, etc.). Most workstations tend to have only one keyboard, and therefore only one display. Larger, multi-user systems, however, will frequently have several displays so that more than one person can be doing graphics work at once. To avoid confusion, each display on a machine is assigned a display number (beginning at 0) when the X server for that display is started. The display number must always be given in a display name. In this guide, the display number is also referred to as the server number (referring to the phrase display server).

screen

The screen number. Some displays share a single keyboard and pointer among two or more monitors. Since each monitor has its own set of windows, each screen is assigned a screen number (beginning at 0) when the X server for that display is started. If the screen number is not given, then screen 0 will be used.

On POSIX systems, the default display name is stored in your DISPLAY environment variable. This variable is set automatically by the xterm terminal emulator. However, when you log into another machine on a network, you'll need to set DISPLAY by hand to point to your display. For example:

% setenv DISPLAY myws:0          (C Shell)
$ DISPLAY=myws:0; export DISPLAY (Bourne Shell)

Finally, most X programs accept a command line option of –display displayname to temporarily override the contents of DISPLAY. This is most commonly used to pop windows on another person's screen or as part of a “remote shell” command to start an xterm pointing back to your display. For example:

% xeyes -display joesws:0 -geometry 1000x1000+0+0
% rsh big xterm -display myws:0 -ls </dev/null &

X servers listen for connections on a variety of different communications channels (network byte streams, shared memory, etc.). Since there can be more than one way of contacting a given server, the host name part of the display name is used to determine the type of channel (also called a transport layer) to be used. The sample servers from MIT support the following types of connections:

local

The host part of the display name should be the empty string. For example: :0, :1, and :0.1. The most efficient local transport will be chosen.

TCP/IP

The host part of the display name should be the server machine's IP address name. Full Internet names, abbreviated names, and IP addresses are all allowed. For example: expo.lcs.mit.edu:0, expo:0, 18.30.0.212:0, bigmachine: 1, and hydra:0.1.

DECnet

The host part of the display name should be the server machine's nodename followed by two colons instead of one. For example: myws::0, big::1, and hydra::0.1.

Access Control

The sample server provides two types of access control: an authorization protocol that provides a list of “magic cookies” that clients can send to request access (available as of Release 4); and a list of hosts from which connections are always accepted. xdm initializes magic cookies in the server, and also places them in a file accessible to the user. Normally, the list of hosts from which connections are always accepted should be empty, so that only clients that are explicitly authorized can connect to the display. When you add entries to the host list (with xhost), the server no longer performs any authorization on connections from those machines. Be careful with this.

The file for authorization used by both xdm and Xlib can be specified with the environment variable XAUTHORITY, and defaults to the file .Xauthority in the home directory. xdm uses $HOME/.Xauthority and will create it or merge in authorization records if it already exists when a user logs in.

To manage a collection of authorization files containing a collection of authorization records, use xauth. This program allows you to extract records and insert them into other files. Using this, you can send authorization to remote machines when you log in. As the files are machine-independent, you can also simply copy the files or use NFS to share them. If you use several machines, and share a common home directory with NFS, then you never really have to worry about authorization files—the system should work correctly by default. Note that magic cookies transmitted “in the clear” over NFS or using ftp or rcp can be “stolen” by a network eaves-dropper, and as such may enable unauthorized access. In many environments this level of security is not a concern, but if it is, you need to know the exact semantics of the particular magic cookie to know if this is actually a problem.

Geometry Specifications

One of the advantages of using window systems instead of hardwired terminals is that applications don't have to be restricted to a particular size or location on the screen. Although the layout of windows on a display is controlled by the window manager that the user is running (described below), most X programs accept a command line argument of the form -geometry widthxheight±xoff±yoff (where width, height, xoff, and yoff are numbers) for specifying a preferred size and location for this application's main window.

The width and height parts of the geometry specification are usually measured in either pixels or characters, depending on the application. The xoff and yoff parts are measured in pixels and are used to specify the distance of the window from the left or right and top and bottom edges of the screen, respectively. Both types of offsets are measured from the indicated edge of the screen to the corresponding edge of the window. The x offset may be specified in the following ways:

+xoff

The left edge of the window is to be placed xoff pixels in from the left edge of the screen (i.e., the x coordinate of the window's origin will be xoff). xoff may be negative, in which case the window's left edge will be off the screen.

-xoff

The right edge of the window is to be placed xoff pixels in from the right edge of the screen. xoff may be negative, in which case the window's right edge will be off the screen.

The y offset has similar meanings:

+yoff

The top edge of the window is to be yoff pixels below the top edge of the screen (i.e., the y coordinate of the window's origin will be yoff). yoff may be negative, in which case the window's top edge will be off the screen.

-yoff

The bottom edge of the window is to be yoff pixels above the bottom edge of the screen. yoff may be negative, in which case the window's bottom edge will be off the screen.

Offsets must be given as pairs; in other words, in order to specify either xoff or yoff both must be present. Windows can be placed in the four corners of the screen using the following specifications:

+0+0    The upper-left corner.

−0+0    The upper-right corner.

−0−0    The lower-right corner.

+0−0    The lower-left corner.

In the following examples, a terminal emulator will be placed in roughly the center of the screen and a load average monitor, mailbox, and clock will be placed in the upper-right corner:

% xterm -fn 6x10 -geometry 80x24+30+200 &
% xclock -geometry 48x48−0+0 &
% xload -geometry 48x48−96+0 &
% xbiff -geometry 48x48−48+0 &

Window Managers

The layout of windows on the screen is controlled by special programs called window managers. Although many window managers will honor geometry specifications as given, others may choose to ignore them (requiring the user to explicitly draw the window's region on the screen with the pointer, for example).

Since window managers are regular (albeit complex) client programs, a variety of different user interfaces can be built. The core distribution comes with a window manager named twm, which supports overlapping windows, popup menus, point-and-click or click-to-type input models, titlebars, nice icons (and an icon manager for those who don't like separate icon windows).

Several other window managers are available in the user-contributed distribution: uwm, gwm, m_swm, olwm, and tekwm.

Font Names

Collections of characters for displaying text and symbols in X are known as fonts. A font typically contains images that share a common appearance and look nice together (for example, a single size, boldness, slant, and character set). Similarly, collections of fonts that are based on a common type face (the variations are usually called roman, bold, italic, bold italic, oblique, and bold oblique) are called families.

Sets of font families of the same resolution (usually measured in dots-per-inch) are further grouped into directories (so named because they were initially stored in file system directories). Each directory contains a database that lists the name of the font and information on how to find the font. The server uses these databases to translate font names (which have nothing to do with filenames) into font data.

The list of font directories in which the server looks when trying to find a font is controlled by the font path. Although most installations will choose to have the server start up with all of the commonly used font directories, the font path can be changed at any time with the xset program. However, it is important to remember that the directory names are on the server's machine, not on the application's.

The default font path for the sample server contains three directories:

/usr/lib/X11/fonts/misc

This directory contains several miscellaneous fonts that are useful on all systems. It contains a small family of fixed-width fonts in pixel heights 5 through 10, a family of fixed-width fonts from Dale Schumacher in similar pixel heights, several Kana fonts from Sony Corporation, a Kanji font, the standard cursor font, two cursor fonts from Digital Equipment Corporation, and OPEN LOOK cursor and glyph fonts from Sun Microsystems, Inc. It also has font name aliases for the fonts fixed and variable.

/usr/lib/X11/fonts/75dpi

This directory contains fonts contributed by Adobe Systems, Inc., Digital Equipment Corporation, Bitstream, Inc., Bigelow and Holmes, and Sun Microsystems, Inc. for 75 dots-per-inch displays. An integrated selection of sizes, styles, and weights is provided for each family.

/usr/lib/X11/fonts/100dpi

This directory contains 100 dots per inch versions of the fonts in the 75dpi directory.

Font databases are created by running the mkfontdir program in the directory containing the source or compiled versions of the fonts (in both compressed and uncompressed formats). Whenever fonts are added to a directory, mkfontdir should be rerun so that the server can find the new fonts. To make the server reread the font database, reset the font path with the xset program. For example, to add a font to a private directory, the following commands could be used:

% cp newfont.snf ~/myfonts
% mkfontdir ~/myfonts
% xset fp rehash

The xlsfonts program can be used to list all of the fonts that are found in font databases in the current font path. Font names tend to be fairly long as they contain all of the information needed to uniquely identify individual fonts. However, the sample server supports wildcarding of font names, so the full specification:

-adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1

could be abbreviated as:

*-courier-medium-r-normal--*-100-*

Because the shell also has special meanings for * and ?, wildcarded font names should be quoted:

% xlsfonts -fn ‘*-courier-medium-r-normal--*-100-*’

If more than one font in a given directory in the font path matches a wildcarded font name, the choice of which particular font to return is left to the server. However, if fonts from more than one directory match a name, the returned font will always be from the first such directory in the font path. The example given above will match fonts in both the 75dpi and 100dpi directories; if the 75dpi directory is ahead of the 100dpi directory in the font path, the smaller version of the font will be used.

Color Names

Most applications provide ways of tailoring (usually through resources or command line arguments) the colors of various elements in the text and graphics they display. Although black and white displays don't provide much of a choice, color displays frequently allow anywhere between 16 and 16 million different colors.

Colors are usually specified by their commonly-used names (for example, red, white, or medium slate blue). The server translates these names into appropriate screen colors using a color database that can usually be found in /usr/lib/X11/rgb.txt. Color names are case-insensitive, meaning that red, Red, and RED all refer to the same color.

Many applications also accept color specifications of the following form:

#rgb
#rrggbb
#rrrgggbbb
#rrrrggggbbbb

where r, g, and b are hexidecimal numbers indicating how much red, green, and blue should be displayed (zero being none and ffff being on full). Each field in the specification must have the same number of digits (e.g., #rrgb or #gbb are not allowed). Fields that have fewer than four digits (e.g., #rgb) are padded out with zeros following each digit (i.e., #r000g000b000). The eight primary colors can be represented as:

black          #000000000000 (no color at all)
red             #ffff00000000
green         #0000ffff0000
blue           #00000000ffff
yellow       #ffffffff0000 (full red and green, no blue)
magenta    #ffff0000ffff (full red and blue, no green)
cyan         #0000ffffffff (full green and blue, no red)
white        #ffffffffffff (full red, green, and blue)

Unfortunately, RGB color specifications are highly unportable since different monitors produce different shades when given the same inputs. Similarly, color names aren't portable because there is no standard naming scheme and because the color database needs to be tuned for each monitor. Application developers should take care to make then colors tailorable.

Keys

The X keyboard model is broken into two layers: server-specific codes (called keycodes), which represent the physical keys, and server-independent symbols (called keysyms), which represent the letters or words that appear on the keys. Two tables are kept in the server for converting keycodes to keysyms:

modifier list

Some keys (such as Shift, Control, and Caps Lock) are known as modifier keys and are used to select different symbols that are attached to a single key (such as Shift-a generates a capital A, and Control-L generates a formfeed character ˆL). The server keeps a list of keycodes corresponding to the various modifier keys. Whenever a key is pressed or released, the server generates an event that contains the keycode of the indicated key as well as a mask that specifies which of the modifer keys are currently pressed. Most servers set up this list to initially contain the various shift, control, and shift lock keys on the keyboard.

keymap table

Applications translate event keycodes and modifier masks into keysyms using a keymap table which contains one row for each keycode and one column for each of the modifiers. This table is initialized by the server to correspond to normal typewriter conventions, but is used only by client programs.

Although most programs deal with keysyms directly (such as those written with the X Toolkit Intrinsics), most programming libraries provide routines for converting keysyms into the appropriate type of string (such as ISO Latin-1).

Options

Most X programs attempt to use the same names for command line options and arguments. All applications written with the X Toolkit Intrinsics automatically accept the following options:

-display [host]:server[.screen]

Specifies the name of the display to use. host specifies the machine, server specifies the display server number, and screen specifies the screen number. Either or both of the host and screen elements to the display specification can be omitted. If host is omitted, the local machine is assumed. If screen is omitted, screen 0 is assumed (and the period is unnecessary). The colon and (display) server are necessary in all cases.

For example, the following command creates an xclock window on screen 1 on server 0 on the machine your_node.

xclock -display your_node:0.1

The -display option can be abbreviated as -d, unless the client accepts another option that begins with “d.”

-geometry geometry

Specifies the initial size and location of the application window. The -geometry option can be (and often is) abbreviated to -g, unless there is a conflicting option that begins with “g.” The argument (geometry) is referred to as a “standard geometry string,” and has the form widthxheight±xoff±yoff.

The -geometry option can be abbreviated as -g, unless the client accepts another option that begins with “g.”

-bg color, -background color

Either option specifies the color to use for the window background.

-bd color, -bordercolor color

Either option specifies the color to use for the window border.

-bw pixels, -borderwidth pixels

Either option specifies the width in pixels of the window border.

-fg color, -foreground color

Either option specifies the color to use for text or graphics.

-fn font, -font font

Either option specifies the font to use for displaying text.

-iconic

Indicates that the user would prefer that the application's windows initially not be visible, as if the windows had been immediately iconified by the user. Window managers may choose not to honor the application's request.

-name app_name

Specifies the name under which resources for the application should be found. This option is useful in shell aliases to distinguish between invocations of an application, without resorting to creating links to alter the executable filename.

-rv, -reverse

Either option indicates that the program should simulate reverse video if possible, often by swapping the foreground and background colors. Not all programs honor this or implement it correctly. It is usually used only on monochrome displays.

+rv

Indicates that the program should not simulate reverse video. This is used to override any defaults since reverse video doesn't always work properly.

-selectionTimeout milliseconds

Specifies the timeout in milliseconds within which two communicating applications must respond to one another for a selection request.

-synchronous

Indicates that requests to the X server should be sent synchronously, instead of asynchronously. Since Xlib normally buffers requests to the server, errors are not necessarily reported immediately after they occur. This option turns off the buffering so that the application can be debugged. It should never be used with a working program.

-title string

Specifies the title to be used for this window. This information is sometimes used by a window manager to provide some sort of header identifying the window.

-xnllanguage language[_territory][.codeset]

Specifies the language, territory, and codeset for use in resolving resource and other filenames.

-xrm resourcestring

Specifies a resource name and value to override any defaults. It is very useful for setting resources that don't have explicit command line arguments.

Resources

To make the tailoring of applications to personal preferences easier, X supports several mechanisms for storing default values for program resources (e.g., background color, window title, etc.). Resources are specified as strings of the form:

appname* subname*subsubname…:value

that are read in from various places when an application is run.

By convention, the application class name is the same as the program name, but with the first letter capitalized (e.g., Bitmap or Emacs) although some programs that begin with the letter “x” also capitalize the second letter for historical reasons. The precise syntax for resources is:

ResourceLine  =  Comment | ResourceSpec
Comment       =  “!” string | <empty line>
ResourceSpec  =  WhiteSpace ResourceName WhiteSpace “:” WhiteSpace value
ResourceName  = [Binding] ComponentName {Binding ComponentName}
Binding       = “.” | “*”
WhiteSpace    = {“ ” | “	”}
ComponentName = {“a”-“z” | “A”-“Z” | “0”-“9” | “_“ | “-”}
value         = string
string        = {<any character not including “
”>}

Note that elements enclosed in curly braces ({…}) indicate zero or more occurrences of the enclosed elements.

To allow values to contain arbitrary octets, the 4-character sequence nn, where n is a digit in the range of “0”–“7”, is recognized and replaced with a single byte that contains this sequence interpreted as an octal number. For example, a value containing a NULL byte can be stored by specifying “00”.

The Xlib routine XGetDefault (3X) and the resource utilities within the X Toolkit obtain resources from the following sources:

RESOURCE_MANAGER root window property

Any global resources that should be available to clients on all machines should be stored in the RESOURCE_MANAGER property on the root window using the xrdb programs. This is frequently taken care of when the user starts up X through the display manager or xinit.

application-specific files

Programs that use the X Toolkit Intrinsics will also look in the directories named by the environment variable XUSERFILESEARCHPATH or the environment variable XAPPLRESDIR, plus directories in a standard place (usually under /usr/lib/X11/, but this can be overriden with the XFILESEARCHPATH environment variable) for application-specific resource files. Files are generally named Class—for the class name of the application.

XAPPLRESDIR configuration files are actually loaded before the RESOURCE_MANAGER property, so that the property can override the values. See Volume Four, X Toolkit Intrinsics Programming Manual, for details.

XENVIRONMENT

Any user- and machine-specific resources may be specified by setting the XENVIRONMENT environment variable to the name of a resource file to be loaded by all applications. If this variable is not defined, a file named $HOME/.Xdefaults-hostname is looked for instead, where hostname is the name of the host where the application is executing.

-xrm resourcestring

Applications that use the X Toolkit can have resources specified from the command line. The resourcestring is a single resource name and value as shown above. Note that if the string contains characters interpreted by the shell (e.g., asterisk), they must be quoted. Any number of -xrm arguments may be given on the command line.

Program resources are organized into groups called classes, so that collections of individual resources (each of which is called instances) can be set all at once. By convention, the instance name of a resource begins with a lowercase letter and class name with an uppercase letter. Multiple word resources are concatentated with the first letter of the succeeding words capitalized. Applications written with the X Toolkit Intrinsics will have at least the following resources:

background (class Background)

Specifies the color to use for the window background.

borderWidth (class BorderWidth)

Specifies the width in pixels of the window border.

borderColor (class BorderColor)

Specifies the color to use for the window border.

Most applications using the X Toolkit Intrinsics also have the resource foreground (class Foreground), specifying the color to use for text and graphics within the window.

By combining class and instance specifications, application preferences can be set quickly and easily. Users of color displays will frequently want to set Background and Foreground classes to particular defaults. Specific color instances such as text cursors can then be overridden without having to define all of the related resources. For example,

bitmap*Dashed:  off
XTerm*cursorColor:  gold
XTerm*multiScroll:  on
XTerm*jumpScroll:  on
XTerm*reverseWrap:  on
XTerm*curses:  on
XTerm*Font:  6x10
XTerm*scrollBar:  on
XTerm*scrollbar*thickness:  5
XTerm*multiClickTime:  500
XTerm*charClass:  33:48,37:48,45-47:48,64:48
XTerm*cutNewline:  off
XTerm*cutToBeginningOfLine:  off
XTerm*titeInhibit:  on
XTerm*ttyModes:  intr ˆc erase ˆ? kill ˆu
XLoad*Background:  gold
XLoad*Foreground:  red
XLoad*highlight: black
XLoad*borderWidth:  0
emacs*Geometry:  80x65-0-0
emacs*Background:  #5b7686
emacs*Foreground:  white
emacs*Cursor:  white
emacs*BorderColor:  white
emacs*Font:  6x10
xmag*geometry:  −0-0
xmag*borderColor:  white

If these resources were stored in a file called .Xresources in your home directory, they could be added to any existing resources in the server with the following command:

% xrdb -merge $HOME/.Xresources

This is frequently how user-friendly startup scripts merge user-specific defaults into any site-wide defaults. All sites are encouraged to set up convenient ways of automatically loading resources.

Examples

The following is a collection of sample command lines for some of the more frequently used commands. For more information on a particular command, please refer to that command's reference page.

% xrdb -load $HOME/.Xresources
% xmodmap -e ‘keysym Backspace = Delete’
% mkfontdir /usr/local/lib/X11/otherfonts
% xset fp+ /usr/local/lib/X11/otherfonts
% xmodmap $HOME/.keymap.km
% xsetroot -solid ‘#888’
% xset b 100 400 c 50 s 1800 r on
% xset q
% twm
% xmag
% xclock -geometry 48x48−0+0 -bg blue -fg white
% xeyes -geometry 48x48−48+0
% xbiff -update 20
% xlsfonts ‘*helvetica*’
% xlswins -1
% xwininfo -root
% xdpyinfo -display joesworkstation:0
% xhost -joesworkstation
% xrefresh
% xwd | xwud
% bitmap companylogo.bm 32x32
% xcalc -bg blue -fg magenta
% xterm -geometry 80x66-0-0 -name myxterm

Diagnostics

A wide variety of error messages are generated from various programs. Various toolkits are encouraged to provide a common mechanism for locating error text so that applications can be tailored easily. Programs written to interface directly to the Xlib C language library are expected to do their own error checking.

The default error handler in Xlib (also used by many toolkits) uses standard resources to construct diagnostic messages when errors occur. The defaults for these messages are usually stored in /usr/lib/X11/XErrorDB. If this file is not present, error messages will be rather terse and cryptic.

When the X Toolkit Intrinsics encounter errors converting resource strings to the appropriate internal format, no error messages are printed. This is convenient when it is desirable to have one set of resources across a variety of displays (e.g., color versus monochrome, lots of fonts versus very few, etc.), although it can pose problems in trying to determine why an application might be failing. This behavior can be overridden by setting the StringConversionWarning resource.

To force the X Toolkit Intrinsics to always print string conversion error messages, the following resource should be placed at the top of the file that is loaded onto the RESOURCE_MANAGER property using the xrdb program (frequently called .Xresources or .Xres in the user's home directory):

*StringConversionWarnings: on

To have conversion messages printed for just a particular application, the appropriate instance name can be placed before the asterisk:

xterm*StringConversionWarnings: on

Bugs

If you encounter a repeatable bug, please contact your site administrator for instructions on how to submit an X Bug Report.

See Also

XConsortium(1), XStandards(1), Xserver, mkfontdir, bdftosnf, bitmap, bsdtosnf, oclock, showsnf, twm, uwm, x10tox11, xauth, xbiff, xcalc, xclock, resize, xdpyinfo, xedit, xev, xfd, xfontsel, xhost, xinit, xkill, xload, xlogo, xlsclients, xlsfonts, xlswins, xmag, xman, xmh, xmodmap, xpr, xprop, xrdb, xrefresh, xset, xsetroot, biff(1), mh(1), init(8), ttys(5); Volume One, Xlib Programming Manual; Volume Two, Xlib Reference Manual; Volume Four, X Toolkit Intrinsics Programming Manual; Volume Five, X Toolkit Intrinsics Reference Manual.

Copyright

The following copyright and permission notice outlines the rights and restrictions covering most parts of the standard distribution of the X Window System from MIT. Other parts have additional or different copyrights and permissions; see the individual source files.

Copyright 1984, 1985, 1986, 1987, 1988, 1989 Massachusetts Institute of Technology.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty.

This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California.

Trademarks

UNIX and OPEN LOOK are trademarks of AT&T. X Window System is a trademark of MIT.

Authors

A cast of thousands. See the file doc/contributors in the standard sources for some of the names.

Xserver X Window System Server

Name

X - X Window System server.

Syntax

X [:displaynumber] [options] [ttyname]

Description

X is the generic name for the X Window System server. It is frequently a link to or a copy of the appropriate server binary for driving the most frequently used server on a given machine. The sample server from MIT supports the following platforms:

Starting the Server

The server is usually started from the X Display Manager program, xdm. This utility is run from the system boot files and takes care of keeping the server running, prompting for user-names and passwords, and starting up user sessions. It is easily configured for sites that wish to provide consistent interfaces for novice users (loading convenient sets of resources, starting up a window manager, clock, and a wide selection of terminal emulator windows).

Since xdm now handles automatic starting of the server in a portable way, the -L option to xterm is now considered obsolete. As of Release 4, support for starting a login window from BSD 4.3-derived /etc/ttys files is no longer included.

Installations that run more than one window system will still need to use the xinit utility. However, xinit is to be considered a tool for building startup scripts and is not intended for use by end users. Site adminstrators are strongly urged to build more friendly interfaces for novice users.

When the sample server starts up, it takes over the display. If you are running on a workstation whose console is the display, you cannot log into the console while the server is running.

Network Connections

The sample server supports connections made using the following reliable byte-streams:

TCP/IP The server listens on port htons(6000+n), where n is the display number.

UNIX Domain

The sample server uses /tmp/.X11-unix/Xn as the filename for the socket, where n is the display number.

DECnet

The server responds to connections to object X$Xn, where n is the display number.

Options

All of the sample servers accept the following command line options:

-a number

Sets pointer acceleration (i.e., the ratio of how much is reported to how much the user actually moved the pointer).

-auth authorization_file

Specifies a file that contains a collection of authorization records used to authenticate access. (Available as of Release 4.)

bc

Disables certain kinds of error checking, for bug compatibility with previous releases (e.g., to work around bugs in Release 2 and Release 3 versions of xterm and the toolkits). Use of this option is discouraged. (Available as of Release 4.)

-bs

Disables backing store support on all screens.

-c

Turns off key-click.

c volume

Sets key-click volume (allowable range: 0-8).

-cc class

Sets the visual class for the root window of color screens. The class numbers are as specified in the X protocol. Not obeyed by all servers. (Available as of Release 4.)

-dpi resolution

Sets the resolution of the screen, in dots-per-inch. To be used when the server cannot determine the screen size from the hardware.

-f volume

Sets beep (bell) volume (allowable range: 0-7).

-I

Causes all remaining command line arguments to be ignored. (Available as of Release 4.)

-ld kilobytes

Sets the data space limit of the server to the specified number of kilobytes. The default value is zero, making the data size as large as possible. A value of −1 leaves the data space limit unchanged. (Available as of Release 4. Not available in all operating systems.)

-ls kilobytes

Sets the stack space limit of the server to the specified number of kilobytes. The default value is zero, making the stack size as large as possible. A value of −1 leaves the stack space limit unchanged. (Available as of Release 4. Not available in all operating systems.)

-logo

Turns on the X Window System logo display in the screen saver. There is currently no way to change this from a client.

nologo

Turns off the X Window System logo display in the screen saver. There is currently no way to change this from a client.

-p minutes

Sets screen saver pattern cycle time, in minutes.

-r

Turns off auto-repeat.

r

Turns on auto-repeat.

-s minutes

Sets screen saver timeout, in minutes.

-su

Disables save under support on all screens.

-t numbers

Sets pointer acceleration threshold, in pixels (i.e., after how many pixels pointer acceleration should take effect).

-to seconds

Sets default screen saver timeout, in seconds.

v

Sets video-on screen saver preference.

-v

Sets video-off screen saver preference.

-co filename

Sets the name of the RGB color database.

-help

Prints a usage message.

-fp font_path

Sets the search path for fonts. This path is a comma-separated list of directories that the server searches for font databases.

-fc cursor_font

Sets the default cursor font.

-fn font

Sets the default font.

-wm

Forces the default backing-store of all windows to be WhenMapped; a cheap-trick way of getting backing-store to apply to all windows.

-x extension

Loads the specified extension at init. (Available as of Release 4; not supported in most implementations.)

XDMCP-specific Options (Release 4)

You can also have the X server connect to xdm using XDMCP. Although this is not typically useful, because it doesn't allow xdm to manage the server process, it can be used to debug XDMCP implementations, and servers as a sample implementation of the server side of XDMCP. For more information on this protocol, see the XDMCP specification in the MIT X distribution under the filename docs/XDMCP/xdmcp.ms. The following options control the behavior of XDMCP:

-query host_name

Enables XDMCP and sends Query packets to the specified host.

-broadcast

Enables XDMCP and broadcasts BroadcastQuery packets to the network. The first responding display manager will be chosen for the session.

-indirect host_name

Enables XDMCP and sends IndirectQuery packets to the specified host.

-port port_num

Specifies an alternate port number for XDMCP packets. Must be specified before any -query, -broadcast, or -indirect options.

-once

Makes the server exit after the first session is over. Normally, the server keeps starting sessions, one after the other.

-class display_class

XDMCP has an additional display qualifier used in resource lookup for display-specific options. This option sets that value; by default, it is “MIT-Unspecified” (not a very useful value).

-cookie xdm_auth_bits

When testing XDM-AUTHENTICATION-1, a private key is shared between the server and the manager. This option sets the value of that private data (not that it's very private, being on the command line).

-displayID display_id

Yet another XDMCP-specific value, this one allows the display manager to identify each display so that it can locate the shared key.

May servers also have device-specific command line options. For more details, see the manual pages for the individual servers.

Security

As of Release 4, the sample server implements a simplistic authorization protocol, MIT-MAGIC-COOKIE-1, which uses data private to authorized clients and the server. This is a rather trivial scheme; if the client passes authorization data which is the same as the data the server has, it is allowed access. This scheme is worse than the host-based access control mechanisms in environments with unsecure networks because it allows any host to connect, given that it has discovered the private key. But in many environments, this level of security is better than the host-based scheme, because it allows access to be controlled per-user instead of per-host.

In addition, the server provides support for a DES-based authorization scheme, XDM-AUTHORIZATION-1, which is more secure (given a secure key distribution mechanism), but as DES is not generally distributable, the implementation is missing routines to encrypt and decrypt the authorization data. This authorization scheme can be used in conjunction with XDMCP's authentication scheme, XDM-AUTHENTICATION-1, or in isolation.

The authorization data is passed to the server in a private file named with the -auth command line option. Each time the server is about to accept the first connection after a reset (or when the server is starting), it reads this file. If this file contains any authorization records, the local host is not automatically allowed access to the server, and only clients which send one of the authorization records contained in the file in the connection setup information will be allowed access. See the Xau manual page for a description of the binary format of this file. Maintenance of this file, and distribution of its contents to remote sites for use there, is left as an exercise for the reader.

The sample server also uses a host-based access control list for deciding whether or not to accept connections from clients on a particular machine. This list initially consists of the host on which the server is running as well as any machines listed in the file /etc/Xn.hosts, where n is the display number of the server. Each line of the file should contain either an Internet hostname (e.g., expo.lcs.mit.edu) or a DECnet hostname in double colon format (e.g., hydra::). There should be no leading or trailing spaces on any lines. For example:

joesworkstation
corporate.company.com
star::
bigcpu::

Users can add or remove hosts from this list and enable or disable access control using the xhost command from the same machine as the server. For example:

% xhost +janesworkstation     janesworkstation added to access control list
% xhost −star::               star:: removed from access control list
% xhost +                     all hosts allowed (access control disabled)
% xhost −                     all hosts restricted (access control enabled)
% xhost
access control enabled (only the following hosts are allowed)
joesworkstation
janesworkstation
corporate.company.com
bigcpu::

Unlike some window systems, X does not have any notion of window operation permissions or place any restrictions on what a client can do; if a program can connect to a display, it has full run of the screen. Sites that have authentication and authorization systems (such as Kerberos) might wish to make use of the hooks in the libraries and the server to provide additional security.

Signals

The sample server attaches special meaning to the following signals:

SIGHUP

Causes the server to close all existing connections, free all resources, and restore all defaults. It is sent by the display manager whenever the main user's primary application (usually an xterm or window manager) exits to force the server to clean up and prepare for the next user.

SIGTERM

Causes the server to exit cleanly.

SIGUSR1

This signal is used quite differently from either of the above. When the server starts, it checks to see if it has inherited SIGUSR1 as SIG_IGN instead of the usual SIG_DFL. In this case, the server sends a SIGUSR1 to its parent process, after it has set up the various connection schemes. xdm uses this feature to recognize when it is possible to connect to the server.

Fonts

Fonts are usually stored as individual files in directories. The list of directories in which the server looks when trying to open a font is controlled by the font path. Although most sites will choose to have the server start up with the appropriate font path (using the -fp option mentioned above), it can be overridden using the xset program.

The default font path for the sample server contains three directories:

/usr/lib/X11/fonts/misc

This directory contains several miscellaneous fonts that are useful on all systems. It contains a small family of fixed-width fonts in pixel heights 5 through 10, a family of fixed-width fonts from Dale Schumacher in similar pixel heights, several Kana fonts from Sony Corporation, a Kanji font, the standard cursor font, two cursor fonts from Digital Equipment Corporation, and OPEN LOOK cursor and glyph fonts from Sun Microsystems, Inc. It also has font name aliases for the fonts fixed and variable.

/usr/lib/X11/fonts/75dpi

This directory contains fonts contributed by Adobe Systems, Inc., Digital Equipment Corporation, Bitstream, Inc., Bigelow and Holmes, and Sun Microsystems, Inc. for 75 dots per inch displays. An integrated selection of sizes, styles, and weights is provided for each family.

/usr/lib/X11/fonts/100dpi

This directory contains versions of the fonts in the 75dpi directory for 100 dots-per-inch displays.

Font databases are created by running the mkfontdir program in the directory containing the compiled versions of the fonts (the .snf files). Whenever fonts are added to a directory, mkfontdir should be rerun so that the server can find the new fonts. If mkfontdir is not run, the server will not be able to find any fonts in the directory.

Diagnostics

Too numerous to list them all. If run from init(8), errors are logged in the file /usr/adm/Xnmsgs.

Flies

/etc/Xn.hosts

Initial access control list.

/usr/lib/X11/fonts/misc, /usr/lib/X11/fonts/75dpi, /usr/lib/X11/fonts/100dpi

Font directories.

/usr/lib/X11/rgb.txt

Color database.

/tmp/.X11-unix/Xn

UNIX domain socket.

/usr/adm/Xnmsgs

Error log file.

See Also

X, mkfontdir, twm, uwm, xauth, xdm, xhost, xinit, xset, xsetroot, xterm, ttys(5), init(8); X Window System Protocol; Definition of the Porting Layer for the X v11 Sample Server; Strategies for Porting the X v11 Sample Server; Godzilla's Guide to Porting the X V11 Sample Server.

Bugs

The option syntax is inconsistent with itself and xset.

The acceleration option should take a numerator and a denominator like the protocol.

If X dies before its clients, new clients won't be able to connect until all existing connections have their TCP TIME_WAIT timers expire.

The color database is missing a large number of colors. However, there doesn't seem to be a better one available that can generate RGB values tailorable to particular displays.

Authors

The sample server was originally written by Susan Angebranndt, Raymond Drewry, Philip Karlton, and Todd Newman, of Digital Equipment Corporation, with support from a large cast. It has since been extensively rewritten by Keith Packard and Bob Scheifler of MIT.

appres List Application Resources

Name

appres – list application resource database.

Syntax

appres [[classname][instancename]] [-xrm resource]

Description

Available as of Release 4, the appres client prints the resources seen by an application of the specified classname and instancename. It is used to help determine which resources a particular program would load from the various sources of resource specifications.

Note that appres doesn't really know anything about classes and instances as they may be defined by the client itself. As a result, it takes no account of conflicts between different resource settings, or their correctness. It simply loads the resource database into a temporary file and does a string comparison on the strings:

[*.]
classname[*.]
instancename[*.]

(where [*.] means either * or .) and then prints out the lines that match. Basically, appres searches for occurrences of any class and/or instance name supplied to it. In addition, appres searches for resources not assigned to a particular client—i.e., resources beginning with an asterisk or a dot. (These resources may or may not apply to the client whose class and instance names you supply.)

For example:

% appres XTerm

would list the resources that include the classname XTerm, as well as any resources beginning with an asterisk or dot.

To also match particular instance names, you can enter both an instance and a class name, as in the following:

% appres XTerm myxterm

In this case, appres would list the resources that include any of the following terms: the classname XTerm; the instance name myxterm; or an initial asterisk or dot.

If no application class is specified, the class -NoSuchClass- (which should have no defaults) is used.

Keep in mind the limitations of supplying only one argument (either a class name or an instance name). For example, if resources are specified in the database for the instance name xterm, typing appres XTerm will not list them; and if they are specified for class name XTerm, typing appres xterm will not list them. To be safe, you should specify both the class name and the instance name.

Options

appres supports the following command line option:

-xrm resource

Specifies that, in addition to the current application resources, appres should return the resource specified as an argument to -xrm, if that resource would apply to the classname or instancename. You must specify both a classname and an instancename in order to use the -xrm option. (Note that -xrm does not actually load any resources.)

Without any arguments, appres returns those resources that might apply to any application (for example, those beginning with an asterisk in your .Xresources file).

See Also

X, xrdb, listres.

Author

Jim Fulton, MIT X Consortium.

bdftosnf BDF to SNF Font Compiler

Name

bdftosnf – BDF to SNF font compiler for X11.

Syntax

bdftosnf [options] bdf_file

Description

bdftosnf reads a Bitmap Distribution Format (BDF) font from the specified file (or from standard input if no file is specified) and writes an X11 Server Natural Format (SNF) font to standard output.

Options

bdftosnf accepts the following options:

-pnumber

Forces the glyph padding to a specific number. The legal values are 1, 2, 4, and 8.

-unumber

Forces the scanline unit padding to a specific number. The legal values are 1, 2, and 4.

-m

Forces the bit order to most significant bit first.

-l

Forces the bit order to least significant bit first.

-M

Forces the byte order to most significant byte first.

-L

Forces the byte order to least significant byte first.

-w

Prints warnings if the character bitmaps have bits set to one outside of their defined widths.

-W

Prints warnings for characters with an encoding of −1; the default is to silently ignore such characters.

-t

Expands glyphs in “terminal-emulator” fonts to fill the bounding box.

-i

Suppresses computation of correct ink metrics for “terminal-emulator” fonts.

See Also

X, Xserver, Appendix F, Logical Font Description Conventions, in Volume 0, X Protocol Reference Manual. Also see the document Bitmap Distribution Format, in the MIT distribution.

bitmap System Bitmap Editor

Name

bitmap, bmtoa, atobm – system bitmap editor and conversion utilities.

Syntax

bitmap [options] filename [WIDTHxHEIGHT]

bmtoa [options] filename

atobm [options] filename

Description

bitmap allows you to create and edit small bitmaps that you can use to create backgrounds, icons, and pointers. A bitmap is a grid of pixels, or picture elements, each of which is white, black, or, in the case of color displays, a color.

The bmtoa and atobm filters convert bitmap files to and from ASCII strings. They are most commonly used to quickly print out bitmaps and to generate versions for inclusion in text.

The window that bitmap creates has three sections (see Figure 7-1 in Part One of this guide). The largest section is the checkerboard grid, which is a magnified version of the bitmap you are editing. Squares on the grid can be set, cleared, or inverted directly with the buttons on the pointer. A menu of higher-level operations, such as drawing lines and circles, is provided to the right of the grid. You can invoke these menu commands by clicking with any mouse button. Beneath the menu commands is an actual size picture of the bitmap you are editing; below this is an inverted version of the same bitmap. Each time the grid changes, the same change occurs in the actual-size bitmap and its inverse. If the specified filename is new (i.e., the file is empty), bitmap will display a blank image area, suitable for you to begin editing.

If the bitmap is to be used for defining a cursor, one of the squares in the image may be designated as the hot spot. This determines where the cursor is actually pointing. For cursors with sharp tips (such as arrows or fingers), this is usually at the end of the tip; for symmetric cursors (such as crosses or bullseyes), this is usually at the center.

Bitmaps are stored as small C code fragments suitable for including in applications. They provide an array of bits as well as symbolic constants giving the width, height, and hot spot (if specified) that may be used in creating cursors, icons, and tiles. A selection of commonly-used bitmaps is stored in /usr/include/x11/bitmaps on UNIX systems.

The WIDTHxHEIGHT argument is used only when creating a new bitmap. It gives the size in pixels of the bitmap to be created (and consequently, the number of cells in the bitmap editing area). Existing bitmaps are always edited at their current size. The default size for new bitmaps is 16x16. (This is a little small—an icon such as the mailbox displayed by xbiff, is 48x48 pixels.)

Note that there is an interaction between the size of the bitmap being edited and the size of the bitmap window. By default, each cell in the bitmap editing area is 13 pixels square. If the bitmap being edited is large, this may result in an application window larger than the screen. Specifying an explicit size for the overall application using the -geometry option (or resizing it with the window manager) will work because bitmap will automatically adjust the size of each editing cell to fit. But this adjustment is useful only up to a point. The minimum size defined in the code for the cells in the bitmap editing area is 3 pixels (that is, each pixel in the bitmap itself will be represented by a cell 3 pixels square in the editing area). And even at that size, it is extremely difficult to edit individual pixels. At any rate, beyond a certain bitmap size, the constraint on the size of the cells will override your geometry specification; the editing area will be three times the dimensions of the actual bitmap, with the rest of the application sized to match.

bitmap should really be implemented with a scrollable editing area, so that the size of the application can be completely independent of the size of the bitmap being edited.

Options: bitmap

bitmap accepts all of the standard X Toolkit command line options, which are listed on the X reference page. (We've included some of the more commonly used Toolkit options later in this section.) In addition, bitmap accepts the following application-specific options:

-help

Prints a brief description of the allowable options.

-hl color

Specifies the color to be used for highlighting.

-ms color

Specifies the color to be used for the pointer (mouse). Default is black.

-name variable

Specifies the variable name to be used when writing out the bitmap file. The default is to use the basename of the filename command line argument.

-nodashed

Specifies that the grid lines in the bitmap window are drawn as solid lines, not as dashed lines. Default is dashed lines. On some servers, dashed lines are significantly slower.

WIDTHxHEIGHT

Two numbers, separated by the letter “x”, which specify the size of the checkerboard grid within the bitmap window (e.g., 9x13). The first number is the grid's width; the second number is its height. Default is 16x16.

The following standard X Toolkit options are commonly used with bitmap:

-display [host]:server[.screen]

Allows you to specify the host, server, and screen on which to create the bitmap window. host specifies the machine, server specifies the server number, and screen specifies the screen number. For example:

bitmap -display your_node:0.1

creates a bitmap window on screen 1 of server 0 on the machine your_node. If the host is omitted, the local machine is assumed. If the screen is omitted, screen 0 is assumed; the server and colon (:) are necessary in all cases.

-geometry geometry

The bitmap is created with the specified size and location determined by the supplied geometry specification. The -geometry option can be (and often is) abbreviated to -g, unless there is a conflicting option that begins with “g.” The argument to the geometry option (geometry) has the form widthxheight±xoff±yoff, where both the size (width and height) and position on the screen (± xoff ± yoff) are given in pixels. If you do not specify the geometry, the window manager may place the window automatically; if not, bitmap will ask you for window placement when it starts up. See “Window Geometry: Specifying Size and Location” in Chapter 3 of this guide for details.

-fg color

Specifies the color to be used for the foreground. Default is black.

-bg color

Specifies the color to be used for the background. Default is white.

-bd color

Specifies the color to be used for the window border.

-bw number

Specifies the border width in pixels of the bitmap window. Default is 3 pixels.

-fn font

Specifies the font to be used in the command buttons (refer to the “Menu Commands” section below). Default is fixed, a 6x13 pixel, monospaced font.

Options: bmtoa

The bmtoa conversion program accepts the following option:

-chars cc

Specifies the pair of characters to use in the string version of the bitmap. The first character is used for 0 bits and the second character is used for 1 bits. The default is to use dashes (-) for 0s and number signs (#) for 1s.

Options: atobm

The atobm conversion program accepts the following options:

-chars cc

Specifies the pair of characters to use when converting string bitmaps into arrays of numbers. The first character represents a 0 bit and the second character represents a 1 bit. The default is to use dashes (−) for 0s and number signs (#) for 1s.

-name variable

Specifies the variable name to be used when writing out the bitmap file. The default is to use the basename of the filename command line argument or leave it blank if the standard input is read.

-xhot number

Specifies the X coordinate of the hot spot. Only positive values are allowed. By default, no hot spot information is included.

-yhot number

Specifies the Y coordinate of the hot spot. Only positive values are allowed. By default, no hot spot information is included.

Resources

The bitmap program accepts the following resources. The foreground, background, and highlight colors are ignored unless you specify new values for all three options.

Background

Determines the window's background color. Bits which are 0 in the bitmap are displayed in this color. Default is white.

BodyFont

Determines the text font. Default is fixed, a 6x13 pixel, monospaced font.

BorderColor

Determines the color of the border. Default is black.

BorderWidth

Determines the border width. Default is 2 pixels.

Dashed

Determines whether dashed or solid lines are used for the bitmap grid. (On specifies dashed lines, off specifies solid.) Default is on. (Available as of Release 4.)

Foreground

Determines the foreground color. Bits which are 1 in the bitmap are displayed in this color. Default is black.

Highlight

Determines the highlight color. bitmap uses this color to show the hot spot and to indicate rectangular areas that are affected by the Move Area, Copy Area, Set Area, Clear Area, and Invert Area commands. If a highlight color is not given, then bitmap highlights by inverting. For example, if you have a black rectangular area selected for a move, white Xs appear in the rectangle.

Mouse

Determines the pointer's color. Default is black.

Geometry

Determines the size and location of the bitmap window.

Dimensions

Determines the WIDTHxHEIGHT of the checkerboard grid within the bitmap window. Default is 16x16.

Changing Grid Squares

Grid squares may be set, cleared, or inverted by pointing to them and clicking one of the buttons indicated below. Multiple squares can be changed at once by holding the button down and dragging the cursor across them. Set squares are filled and represent 1s in the bitmap; clear squares are empty and represent 0s.

Button 1 (usually the left)

Changes one or more grid squares to the foreground color and sets the corresponding bits in the bitmap to 1.

Button 2 (usually the middle)

Inverts one or more grid squares. The corresponding bit or bits in the bitmap are inverted (1s become 0s and 0s become 1s).

Button 3 (usually the right)

Changes one or more grid squares to the background color and sets the corresponding bits in the bitmap to 0.

Menu Commands

To make defining shapes easier, bitmap provides 13 commands for drawing whole sections of the grid at once, two commands for manipulating the hot spot, and two commands for updating the bitmap file and exiting. A command button for each of these operations is located to the right of the grid.

Several of the commands operate on rectangular portions of the grid. These areas are selected after the command button is pressed by moving the cursor to the upper-left square of the desired area, pressing a pointer button, dragging the cursor to the lower right-hand corner (with the button still pressed), and then releasing the button. The command may be aborted by pressing any other button while dragging or by releasing outside the grid.

To invoke a command, move the pointer over that command and click any button.

The following command descriptions assume that black is the foreground color and white is the background color (the defaults).

Clear All

Turns all the grid squares white and sets all bitmap bits to 0. This is irreversible, so invoke it with caution.

Set All

Turns all the grid squares black and sets all bitmap bits to 1. This is also irreversible, so invoke it with caution.

Clear Area

Clears a rectangular area of the grid, turning it white and setting the corresponding bitmap to 0. After you click on this command, the cursor turns into a corner cursor representing the upper-left corner of the area you want to clear. Press and hold down any mouse button while moving the mouse to the lower-right corner of the area you want to clear, then release the button.

While you are holding down the button, the selected area is covered with Xs, and the cursor changes to a lower-right corner cursor. If you now wish to abort the command without clearing an area, either press another mouse button, move the cursor outside the grid, or move the cursor to the left of or above the left corner.

Set Area

Turns a rectangular area of the grid black and sets the corresponding bitmap bits to 1. It works the same way as the Clear Area command.

Invert Area

Inverts rectangular area of the grid. It works the same way as the Clear Area command.

Copy Area

Copies a rectangular area from one part of the grid to another. First, you select the rectangle to be copied, in the manner described under Clear Area above.

Once you have selected the area to copy, the cursor changes to an upper-left corner cursor. When you press a mouse button, a destination rectangle overlays the grid; moving the mouse while holding down the button moves this destination rectangle. The copy occurs when you release the button. To cancel the copy, move the mouse outside the grid and then release the button.

Move Area

Works identically to Copy Area, except it clears the source rectangle after copying to the destination.

Overlay Area

Lays a rectangular area from one part of the grid over a rectangular area in another part of the grid. Select the area as described under Clear Area. Overlay is not a pixel for pixel replacement: those pixels that are clear (bitmap bits set to 0) allow those pixels that are set (bitmap bits set to 1) to show through the overlay.

Line

Draws a line between two points. When you select this menu option, the cursor changes to a dot shape. Position the cursor over the first point of the line you want to draw and click any mouse button. Then position the cursor over the end point of the line and click any mouse button. A black line is drawn between the two points.

Circle

Draws a circle. When you select this menu option, the cursor changes to a dot shape. First, position the cursor over the point you want to specify as the center and click any mouse button. Then position the cursor over a point you want to specify as the radius and click any mouse button. A black circle is drawn.

Filled Circle

Draws a filled circle when you specify the center and radius of the circle as with Circle.

Flood Fill

Fills all clear squares in a closed shape you specify. When you select this menu option, the cursor changes to a dot shape. Click on any clear square inside the shape you want to fill and all clear squares are filled out to the border of the closed shape. If the shape is not closed, the entire grid will be filled. (Closed shapes to be filled may be drawn by setting individual pixels or using the Line command.)

Set Hot Spot

Designates a point on the bitmap as the “hot spot.” If a program is using your bitmap as a cursor, the hot spot indicates which point on the bitmap is the “actual” location of the cursor. For instance, if your cursor is an arrow, the hot spot could be the tip of the arrow; if your cursor is a cross, the hot spot should be where the perpendicular lines intersect.

Clear Hot Spot

Removes any hot spot that was defined for this bitmap.

Write Output

Writes the current bitmap value to the file specified in the command line. If the file already exists, the original file is first renamed to filename~ (in the manner of emacs(1) and other text editors).

If either the renaming or the writing causes an error, a dialog box will appear asking if you want to write the file /tmp/filename instead. If you say yes, all future Write Output commands are written to /tmp/filename as well. See File Format below for the format of the output file.

Quit

Exits the bitmap program. If you have edited the bitmap and have not invoked Write Output, or you have edited since the last time you invoked Write Output, a dialog window appears, asking if you want to save changes before quitting. “Yes” does a Write Output before exiting. “No” just exits, losing the edits. “Cancel” means you decided not to quit after all and you can continue with your editing.

You can also terminate bitmap by typing Control-C or q anywhere in the window. If you have edited the bitmap and have not invoked Write Output, a dialog window appears, asking if you want to save changes before quitting.

File Format

The Write Output command stores bitmaps as simple C program fragments that can be compiled into programs, referred to by X Toolkit pixmap resources, manipulated by other programs (such as xsetroot), or read in using utility routines in the various programming libraries. The width and height of the bitmap as well as the hot spot, if specified, are written as preprocessor symbols at the start of the file. The bitmap image is then written out as an array of characters:

#define name_width 11
#define name_height 5
#define name_x_hot 5
#define name_y_hot 2

static char name_bits[] = {
    0x91, 0x04, 0xca, 0x06, 0x84,
    0x04, 0x8a, 0x04, 0x91, 0x04
};

The variables ending with _x_hot and _y_hot are optional; they must be present only if a hot spot has been defined for this bitmap. The other variables must be present.

In place of name, the five variables are prefixed with a string derived from the name of the file specified on the original command line. Any directories are stripped off the front of the filename and any suffix (including the preceding period) is stripped off the end. Any remaining non-alphabetic characters are replaced with underscores.

For example, invoking bitmap with filename /usr/include/bitmaps/cross.bitmap produces a file with variable names cross_width, cross_height, and cross_bits (and cross_x_hot and cross_y_hot, if a hot spot is defined).

Each character in the the array contains 8 bits from one row of the image (rows are padded out at the end to a multiple of 8 to make this possible). Rows are written out from left to right and top to bottom. The first character of the array holds the leftmost 8 bits of top line, and the last character holds the rightmost 8 bits (including padding) of the bottom line. Within each character, the leftmost bit in the bitmap is the least significant bit in the character.

This process can be demonstrated visually by splitting a row into words containing 8 bits each, reversing the bits in each word (since Arabic numbers have the significant digit on the right and images have the least significant bit on the left), and translating each word from binary to hexadecimal.

In the following example, the array of 1s and 0s on the left represents a bitmap containing 5 rows and 11 columns that spells X11. To its right is the same array split into 8-bit words with each row padded with 0s so that it is a multiple of 8 in length (16):

10001001001         10001001 00100000
01010011011         01010011 01100000
00100001001         00100001 00100000
01010001001         01010001 00100000
10001001001         10001001 00100000

Reversing the bits in each word of the padded, split version of the bitmap yields the left-hand figure below. Interpreting each word as hexadecimal number yields the array of numbers on the right:

10010001  00000100         0x91  0x04
11001010  00000110         0xca  0x06
10000100  00000100         0x84  0x04
10001010  00000100         0x8a  0x04
10010001  00000100         0x91  0x04

The character array can then be generated by reading each row from left to right, top to bottom:

static char name_bits[] = {
   0x91, 0x04, 0xca, 0x06, 0x84,
   0x04, 0x8a, 0x04, 0x91, 0x04
};

The bmtoa program may be used to convert bitmap files into arrays of characters for printing or including in text files. The atobm program can be used to convert strings back to bitmap format.

Using Bitmaps in Programs

To define a bitmap or pointer in an X program, include (#include) a bitmap file and refer to its variables. For instance, to use a pointer defined in the files this.cursor and this_mask.cursor, write:

#include “this.cursor”
#include “this_mask.cursor”
XColor foreground background;
Pixmap source = XCreateBitmapFromData (display, drawable, this_bits,
   this_width, this_height);
Pixmap mask = XCreateBitmapFromData (display, drawable, this_mask_bits,
   this_mask_width, this_mask_height);
Cursor cursor = XCreatePixmapCursor (display, source, mask, foreground,
   background, this_x_hot, this_y_hot);

where foreground and background are XColor values.

Additional routines are available for reading in bitmap files and returning the data in the file in bitmap (single-plane pixmap for use with routines that require stipples) or full depth Pixmaps (often used for window backgrounds and borders). Applications writers should be careful to understand the difference between bitmaps and pixmaps so that their programs function correctly on color and monochrome displays.

For backward compatibility, bitmap will also accept X10 format bitmap files. However, when the file is written out again it will be in X11 format.

Files

Many standard bitmaps can be found in the directory /usr/include/X11/bitmaps.

Bugs

The old command line arguments aren't consistent with other X programs.

If you move the pointer too fast while holding a pointer button down, some squares may be missed. This is caused by limitations in how frequently the X server can sample the pointer location.

There is no way to write to a file other than the one specified on the command line.

There is no way to change the size of the bitmap once the program has started.

There is no Undo command.

See Also

Chapter 7 of this guide; Volume One, Xlib Programming Manual; XmuReadBitmapDataFromFile.

Author

bitmap by Ron Newman, MIT Project Athena; bmtoa and atobm by Jim Fulton, MIT X Consortium.

listres List Widget Resources

Name

listres – list resources in widgets.

Syntax

listres [options] [widget …]

Description

Available as of Release 4, the listres program generates a list of each specified widget's resource database. The list includes the class in which each resource is first defined, the instance and class name, and the type of each resource.

If no specific widgets are given, a two-column list of known widget names and their class hierarchies is printed. In the MIT distribution, this includes the intrinsics-defined widget classes Core, Composite, Constraint, and Shell (and Shell's six subclasses), plus the Athena widgets.

Case is not significant when specifying the name of the widget or widgets whose resources are to be printed. For example:

% listres Core

is equivalent to:

% listres CORE

Options

listres accepts the following application-specific options:

-all

Indicates that listres should print information for all known widgets and objects.

-nosuper

Indicates that resources that are inherited from a superclass should not be listed. This is useful for determining which resources are new to a subclass.

-variable

Indicates that widgets should be identified by the names of the class record variables rather than the class name given in the variable. This is useful for distinguishing subclasses that have the same class name as their superclasses.

-top name

Specifies the name of the widget to be treated as the top of the hierarchy. Case is not significant, and the name may match either the class variable name or the class name. The default is Core.

-format printf_string

Specifies the printf-style format string to be used to print out the name, instance, class, and type of each resource.

listres also recognizes all of the standard X Toolkit options (i.e., the program will run); however, since listres is not a window-based application, it does not use them.

See Also

X, xrdb; Volume Four, X Toolkit Intrinsics Programming Manual; Volume Five, X Toolkit Intrinsics Reference Manual; Appendix G, Athena Widget Resources, in this guide.

Bugs

On operating systems that do not support dynamic linking of run-time routines, this program must have all of its known widgets compiled in. The sources provide several tools for automating this process for various widget sets.

Author

Jim Fulton, MIT X Consortium.

mkfontdir Create fonts.dir Files

Name

mkfontdir – creates a fonts.dir file for each specified directory of font files.

Syntax

mkfontdir [directory-names]

Description

For each directory argument, mkfontdir reads all of the font files in the directory and searches for properties named “FONT”, or (failing that) the name of the file stripped of its suffix. These are used as font names, which are written out to the file fonts.dir in the directory, along with the name of the font file.

The kinds of font files read by mkfontdir depend on configuration parameters, but typically include SNF (suffix .snf), compressed SNF (suffix .snf.Z), BDF (suffix .bdf), and compressed BDF (suffix .bdf.Z). If a font exists in multiple formats, the most efficient format will be used.

Font Name Aliases

The file fonts.alias, which can be put in any directory of the font path, is used to map new names to existing fonts, and should be edited by hand. The format is straightforward enough: two white-space separated columns, the first containing aliases and the second containing fontname patterns.

When a font alias is used, the name it references is searched for in the normal manner, looking through each font directory in turn. This means that the aliases need not mention fonts in the same directory as the alias file.

To embed white space in either name, simply enclose the name in double-quote marks. To embed double-quote marks (or any other special character), precede it with a backslash:

“magic-alias with spaces”    ““fontname” with quotes”
regular alias                        fontname

Usage

Xserver looks for both fonts.dir and fonts.alias in each directory in the font path each time the font path is set (see xset).

See Also

X, Xserver, xset, Chapter 6, Font Specification, Appendix M, Logical Font Description Conventions, in Volume 0, X Protocol Reference Manual.

mwm Motif window manager

Name

mwm – the Motif window manager.

Syntax

mwm [options]

Description

The Motif window manager, mwm, provides all of the standard window management functions. It allows you to move, resize, iconify/deiconify, maximize, and close windows and icons, focus input to a window or icon, refresh the display, etc. mwm provides much of its functionality via a frame that (by default) is placed around every window on the display. The mwm frame has the three-dimensional appearance characteristic of the OSF/Motif graphical user interface.

Chapters 3 and 4 of this guide discuss input focus, the components of the mwm frame, and the various window management functions you can perform using the pointer on the frame. In addition, Chapter 4 describes how to perform window/icon management functions using mwm's Window Menu (as well as keyboard shortcuts for menu functions), Chapter 4 also describes the Root Menu, which provides commands that can be thought of as affecting the display as a whole.

By default, mwm manages only screen 0. (You can specify an alternate screen by setting the DISPLAY environment variable or using the -display option.) If you want mwm to manage all screens on the display, use the -multiscreen option or set the multiScreen resource to True. (See “mwm-specific Appearance and Behavior Resources.”)

You can customize dozens of mwm features by editing a startup file (.mwmrc) and/or by specifying resources for the mwm client. You can place mwm resources in your regular resource file (often called .Xresources) in your home directory; or you can create a file called Mwm (also in your home directory) for mwm resources only. If you place conflicting specifications in both files, the resources in .Xresources (presuming they are loaded into the RESOURCE_MANAGER) take precedence. (These files are generally kept in the user's home directory. Note, however, that the actual location of resource files may depend on certain environment variables. See the section “Environment Variables” for more information.)

Chapter 11 of this guide describes the syntax of the .mwmrc file and of mwm resource specifications. Chapter 11 also describes how to use an icon box, which can be set up to organize icons on the display.

The current reference page primarily describes the actions and resources by mwm. This reference page should assist you in customizing mwm, according to the guidelines specified in Chapter 11.

Options

-display [host]:server[.screen]

Specifies the name of the display on which to run mwm. host specifies the machine, server specifies the display server number, and screen specifies the screen number. Either or both of the host and screen elements can be omitted. If host is omitted, the local machine is assumed. If screen is omitted, screen 0 is assumed (and the period is unnecessary). The colon and (display) server are necessary in all cases.

For example, the following command runs mwm on screen 1 on server 0 on the machine your_node.

mwm -display your_node:0.1

-multiscreen

Specifies that mwm should manage all screens on the display. The default is to manage only screen 0. You can specify an alternate screen by setting the DISPLAY environment variable or using the -display option.

You can also specify that mwm manage all screen by assigning a value of True to the multiScreen resource variable. See “mwm-specific Appearance and Behavior Resources.”

-name app_name

Specifies the name under which resources for the window manager should be found.

-screens screen_name [screen_name]…

Assigns resource names to the screens mwm is managing. If mwm is managing a single screen, only the first name in the list is used. If mwm is managing multiple screens, the names are assigned to the screens in order, starting with screen 0. If there are more screens than names, resources for the remaining screens will be retrieved using the first screen_name.

-xrm resourcestring

Specifies a resource name and value to override any defaults. This option is very useful for setting resources that don't have explicit command line arguments.

.mwmrc Startup File

The default operation of mwm is largely controlled by a system-wide file, called system.mwmrc, which establishes the contents of the Root Menu and Window Menu, how menu functions are invoked, and what key and button combinations can be used to manage windows. To modify the behavior of mwm, you can edit a copy of this file in your home directory. The version of this file in your home directory should be called .mwmrc. (You can specify an alternate startup file using the configFile resource variable.)

The syntax of the system.mwmrc file is described in Chapter 11 of this guide. Chapter 11 also examines how to create menus, how to modify existing menus, and how to bind window manager functions to keystrokes, pointer button actions, or a combination of keys and buttons.

In describing the syntax of button and key bindings, Chapter 11 refers to the variables modifier_key and button_event. Acceptable values for modifier_key are: Ctrl, Shift, Alt, Meta, Lock, Mod1, Mod2, Mod3, Mod4, and Mod5. mwm considers Alt and Meta to be equivalent. See Chapter 12, Setup Clients, for a discussion of modifier keys and key mapping.

The acceptable values for button_event are:

Btn1Down
Btn1Up
Btn1Click
Btn1Click2
Btn2Down
Btn2Up
Btn2Click
Btn2Click2
   .
   .
   .
Btn5Down
Btn5Up
Btn5Click
Btn5Click2

Most of these button actions are obvious. (A specification ending in Click2 refers to a double click. Thus, Button1Click2 means to double click button 1.) Note that the list indicates a range between button 1 and button 5 (i.e., the same button events can be specified for buttons 2, 3, and 4).

mwm Functions

This section describes the functions you can specify in an mwm startup file.

Unless otherwise noted, you can specify that each action is invoked:

• In any of the following contexts: root, window, and icon;
• Using button bindings, key binding, or menu items.

When a function is specified with the context icon | window and you invoke the function from the icon box, the function applies to the icon box itself (rather than to any of the icons it contains).

A function is treated as f.nop when it is:

• Not a valid function name.
• Specified inappropriately (e.g., mapped to a button when the function cannot be invoked using button bindings).
• Invoked in an invalid context; (For example, you cannot invoke f.minimize on a window that is already iconified).

See Chapter 11 for a discussion of context, bindings, and menus.

mwm recognizes the following functions:

f.beep

Causes a beep from the keyboard.

f.circle_down [icon | window]

Causes the window or icon on the top of the stack to be lowered to the bottom of the stack. If the icon argument is specified, the function applies only to icons. If the window argument is specified, the function applies only to windows.

This function is invoked by the Shuffle Down item on the default Root Menu.

f.circle_up [icon | window]

Causes the window or icon on the bottom of the stack to be raised to the top. If the icon argument is specified, the function applies only to icons. If the window argument is specified, the function applies only to windows.

This function is invoked by the Shuffle Up item on the default Root Menu.

f.exec [command]

Or:

! [command]

Executes command using the shell specified by the MWMSHELL environment variable. (If MWMSHELL isn't set, the command is executed using the shell specified by the SHELL environment variable; otherwise, using /bin/sh).

f.focus_color

Sets the colormap focus to a client window. If this function is invoked in the root context, the default colormap (specified by X for the screen where mwm is running) is installed and there is no specific client window colormap focus. For the f.focus_color function to work, the colormapFocusPolicy should be specified as explicit; otherwise the function is treated as f.nop.

f.focus_key

Sets the input focus to a window or icon. For the f.focus_key function to work, the keyboardFocusPolicy should be specified as explicit. If keyboardFocusPolicy is not explicit, or if the function is invoked in the root context, it is treated as f.nop.

f.kill

Terminates a client. Specifically, sends the WM_DELETE_WINDOW message to the selected window if the client application has requested it through the WM_PROTOCOLS property. The application is supposed to respond to the message by removing the indicated window. If the WM_SAVE_YOURSELF protocol is set up and the WM_DELETE_WINDOW protocol is not, the client is sent a message, indicating that the client needs to prepare to be terminated. If the client does not have the WM_DELETE_WINDOW or WM_SAVE_YOURSELF protocol set, the f.kill function causes a client's X connection to be terminated (usually resulting in termination of the client).

This function is invoked by the Close item on the default Window Menu. The f.kill function can only be invoked in the contexts window and icon.

See also the quitTimeout resource.

f.lower [-client]

Lowers a window or icon to the bottom of the stack. By default, the context in which the function is invoked indicates the window or icon to lower. This function is invoked by the Lower item on the default Window Menu.

If the -client argument is specified, the function is invoked on the named client. (client must be the instance or class name of a program.)

f.maximize

Causes a window to be redisplayed at its maximum size. The f.maximize function is invoked by the Maximize item on the default Window Menu. This function cannot be invoked in the context root or on a window that is already maximized.

f.menu menu_name

Associates a cascading (i.e., pull-right) menu with a menu item (from which the cascading menu is displayed); or associates a menu with a button or key binding. The menu_name argument specifies the menu.

f.minimize

Causes a window to be minimized (i.e., iconified). When no icon box is being used, icons are placed on the bottom of the stack (generally in the lower-left corner of the screen; see also iconPlacement in “mwm-specific Appearance and Behavior Resources”). If an icon box is being used, icons are placed inside the box.

The f.minimize function is invoked by the Minimize item on the default Window Menu. This function cannot be invoked in the context root or on an iconified window.

f.move

Allows you to move a window interactively, using the pointer. This function is invoked by the Move item on the default Window Menu.

f.next_cmap

Installs the next colormap in the list of colormaps for the window with the colormap focus. (See f.focus_color.)

f.next_key [icon | window | transient]

Without any arguments, this function advances the input focus to the next window or icon in the stack. You can specify only icon or window to make the function apply only to icons or windows, respectively.

Generally, the focus is moved only to windows that do not have an associated secondary window that is application modal. (An active dialog box is application modal.) If the transient argument is specified, transient (secondary) windows are also traversed. Otherwise, if only window is specified, focus is moved only to the last window in a transient group to have the focus.

For this function to work, keyboardFocusPolicy must be explicit; otherwise, the function is treated as f.nop. See Chapter 4 for the default key combinations to move the focus.

f.nop

Specifies no operation. (In other words, it does nothing.)

f.normalize

Causes a client window to be displayed at its normal size. The f.normalize function is invoked by the Restore item on the default Window Menu. This function cannot be invoked in the context root or on a window that is already at its normal size.

f.normalize_and_raise

Causes the client window to be displayed at its normal size and raised to the top of the stack. This function cannot be invoked in the context root.

f.pack_icons

Rearranges icons in an optimal fashion (based on the layout policy being used), either on the root window or in the icon box. See iconPlacement in “mwm-specific Appearance and Behavior Resources.” (See Chapter 11 for instructions on using an icon box.)

f.pass_keys

Toggles processing of key bindings for window manager functions. When key binding processing is disabled, all keys are passed to the window with the keyboard input focus and no window manager functions are invoked. If the f.pass_keys function is set up to be invoked with a key binding, the binding can be used to toggle (enable/disable) key binding processing.

f.post_wmenu

Displays the Window Menu. If a key is used to display the menu and a Window Menu command button is present, the upper-left corner of the menu is placed at the lower-left corner of the command button. If no Window Menu command button is present, the menu is placed in the upper-left corner of the window.

f.prev_cmap

This function installs the previous colormap in the list of colormaps for the window with the colormap focus. (See f.focus_color.)

f.prev_key [icon | window | transient]

Without any arguments, this function moves the input focus to the previous window or icon in the stack. You can specify only icon or window to make the function apply only to icons or windows, respectively.

Generally, the focus is moved only to windows that do not have an associated secondary window that is application modal. (An active dialog box is application modal.) If the transient argument is specified, transient (secondary) windows are also traversed. Otherwise, if only window is specified, focus is moved only to the last window in a transient group to have the focus.

For this function to work, keyboardFocusPolicy must be explicit; otherwise, the function is treated as f.nop. See Chapter 4 for the default key combinations to move the focus.

f.quit_mwm

Stops the mwm window manager. Note that this function does not stop the X server.

f.raise [-client]

Raises a window or icon to the top of the stack. By default, the context in which the function is invoked indicates the window or icon to raise. If the -client argument is specified, the function is invoked on the named client. (client must be the instance or class name of a program.)

f.raise_lower

Raises a window to the top of the stack or lowers a window to the bottom of the stack, as appropriate to the context.

f.refresh

Redraws all windows. This function is invoked by the Refresh item on the default Root Menu.

f.refresh_win

Redraws a single window.

f.resize

Allows you to resize a window interactively, using the pointer. This function is invoked by the Size item on the default Window Menu.

f.restart

Restarts the mwm window manager. (Specifically, this function causes the current mwm process to be stopped and a new mwm process to be started.) This function is invoked by the Restart … item on the default Root Menu.

f.send_msg message_number

Sends a message of the type _MOTIF_WM_MESSAGES to a client; the message type is indicated by the message_number argument. The message is sent only if the client's _MOTIF_WM_MESSAGES property includes message_number.

If a menu item is set up to invoke f.send_msg and the message_number is not included in the client's _MOTIF_WM_MESSAGES property, the menu item label is greyed out (indicating that it is not available for selection).

f.separator

Creates a divider line in a menu. Any associated label is ignored.

f.set_behavior

Restarts mwm with the default behavior for the particular system. By default this function is invoked using the following key sequence: Shift Ctrl Meta !.

f.title

Specifies the title of a menu. The title string is separated from the menu items by a double divider line.

Resources

mwm resources are considered to fall into three categories:

• mwm component appearance resources. These resources set the characteristics of mwm's component features, such as the window frame, menus, and icons.
• mwm-specific appearance and behavior resources. These resources set characteristics of the window manager client, such as focus policy, key and button bindings, and so forth.
• Client-specific resources. These mwm resources can be used to set the appearance and behavior of a particular client or class of clients.

The following sections simply describe the valid resources. For a discussion of mwm resource syntax, see Chapter 11 in this guide. (For more information about basic resource syntax and the precedence of resource specifications, see Chapter 10.)

Note that you can specify resources for multiple screens using the names supplied to the -screens command line option in place of mwm or Mwm in the resource line. (See “Options.”)

mwm Component Appearance Resources

The Motif window manager can be considered to be made up of components: client window frames, menus, icons, and feedback (dialog) boxes. Some component appearance resources can be set for all of these components; others can be set only for the frame and icons.

Unless a default is specified, the default varies based on system specifics (such as screen type, color resources, etc.).

The following component appearance resources apply to all window manager components:

background (class Background)

Specifies the background color.

backgroundPixmap (class BackgroundPixmap)

Specifies the background pixmap of the mwm decoration when the window does not have the input focus (i.e., is inactive).

bottomShadowColor(class Foreground)

Specifies the color to be used for the lower and right bevels of the window manager decoration.

bottomShadowPixmap (class BottomShadowPixmap)

Specifies the pixmap to be used for the lower and right bevels of the window manager decoration.

fontList (class FontList)

Specifies the font to be used in the window manager decoration. The default is fixed.

foreground (class Foreground)

Specifies the foreground color.

saveUnder (class SaveUnder)

Specifies whether save unders are used for mwm components. By default (False), save unders will not be used on any window manager frames.

Save unders must be implemented by the X server for this function to to take effect. When save unders are implemented, the X server saves the contents of windows obscured by other windows that have the save under attribute set. If the saveUnder resource is True, mwm will set the save under attribute on the frame of any client that has it set.

topShadowColor (class Background)

Specifies the color to be used for the upper and left bevels of the window manager decoration.

topShadowPixmap (class TopShadowPixmap)

Specifies the pixmap to be used for the upper and left bevels of the window manager decoration.

The following component appearance resources apply to the window frame and icons:

activeBackground (class Background)

Specifies the background color of the mwm decoration when the window has the input focus (i.e., is active).

activeBackgroundPixmap (class ActiveBackgroundPixmap)

Specifies the background pixmap of the mwm decoration when the window has the input focus (i.e., is active).

activeBottomShadowColor (class Foreground)

Specifies the bottom shadow color of the mwm decoration when the window has the input focus (i.e., is active).

activeBottomShadowPixmap (class BottomShadowPixmap)

Specifies the bottom shadow pixmap of the mwm decoration when the window has the input focus (i.e., is active).

activeForeground (class Foreground)

Specifies the foreground color of the mwm decoration when the window has the input focus (i.e., is active).

activeTopShadowColor (class Background)

Specifies the top shadow color of the mwm decoration when the window has the input focus (i.e., is active).

activeTopShadowPixmap (class TopShadowPixmap)

Specifies the top shadow Pixmap of the mwm decoration when the window has the input focus (i.e., is active).

mwm-specific Appearance and Behavior Resources

The mwm-specific resources control aspects of what you probably think of as the window manager application itself, features such as the focus policy, whether windows are placed on the display automatically or interactively, which set(s) of button and key bindings are used, whether an icon box is used, and so forth.

The following mwm-specific appearance and behavior resources can be specified:

autoKeyFocus (class AutoKeyFocus)

If True (the default), when the focus window is withdrawn from window management or is iconified, the focus bounces back to the window that previously had the focus. This resource is available only when keyboardFocusPolicy is explicit. If False, the input focus is not set automatically.

autoRaiseDelay (class AutoRaiseDelay)

Specifies the amount of time (in milliseconds) that mwm will wait before raising a window after it receives the input focus. The default is 500. This resource is available only when focusAutoRaise is True and the keyboardFocusPolicy is pointer.

bitmapDirectory (class BitmapDirectory)

Identifies the directory to be searched for bitmaps referenced by mwm resources (if an absolute pathname to the bitmap file is not given). The default is /usr/include/X11/bitmaps, the standard location of the system bitmap directory.

buttonBindings (class ButtonBindings)

Identifies the set of button bindings to be used for window management functions; must correspond to a set of button bindings specified in the mwm startup file. Button bindings specified in the startup file are merged with built-in default bindings. The default is DefaultButtonBindings.

cleanText (class CleanText)

Specifies whether text that appears in mwm title and feedback windows is displayed over the existing background pattern. If True (the default), text is drawn with a clear (no stipple) background. (Only the stippling in the area immediately around the text is cleared.) This enhances readability, especially on monochrome systems where a backgroundPixmap is specified. If False, text is drawn on top of the existing background.

clientAutoPlace (class ClientAutoPlace)

Specifies the location of a window when the user has not specified a location. When True (the default), windows are positioned with the upper-left corners of the frames offset horizontally and vertically (so that no two windows completely overlap).

If False, the currently configured position of the window is used.

In either case, mwm will attempt to place the windows totally on screen.

colormapFocusPolicy (class ColormapFocusPolicy)

Specifies the colormap focus policy. Takes three possible values: keyboard, pointer, and explicit. If keyboard (the default) is specified, the input focus window has the colormap focus. If explicit is specified, a colormap selection action is done on a client window to set the colormap focus to that window. If pointer is specified, the client window containing the pointer has the colormap focus.

configFile (class ConfigFile)

Specifies the pathname for the mwm startup file. The default startup file is .mwmrc.

mwm searches for the configuration file in the user's home directory. If the configFile resource is not specified or the file does not exist, mwm defaults to /usr/lib/X11/system.mwmrc.

If the LANG environment variable is set, mwm looks for the configuration file in a $LANG subdirectory first. For example, if the LANG environment variable is set to Fr_FR, mwm searches for the configuration file in $HOME/Fr_FR before it looks in $HOME. Similarly, if the configFile resource is not specified or the file does not exist, mwm defaults to /usr/lib/X11/$LANG/system.mwmrc before it reads /usr/lib/X11/system.mwmrc.

If the configFile pathname does not begin with “~/”, mwm considers it to be relative to the current working directory.

configFile (class ConfigFile)

Specifies the pathname for the mwm startup file.

If the LANG environment variable is set, mwm looks for $HOME/$LANG/configFile. If that file does not exist or if LANG is not set, mwm looks for $HOME/configFile.

If the configFile pathname does not begin with “~/”, mwm considers it to be relative to the current working directory.

If the configFile resource is not specified or if that file does not exist, mwm uses several default paths to find a configuration file. If the LANG environment variable is set, mwm looks for the configuration file first in $HOME/$LANG/.mwmrc. If that file does not exist or if LANG is not set, mwm looks for $HOME/.mwmrc. If that file does not exist and if LANG is set, mwm next looks for /usr/lib/X11/$LANG/system.mwmrc. If that file does not exist or if LANG is not set, mwm looks for /usr/lib/X11/system.mwmrc.

deiconifyKeyFocus (class DeiconifyKeyFocus)

If True (the default), a window receives the input focus when it is normalized (deiconified). This resource applies only when the keyboardFocusPolicy is explicit.

doubleClickTime (class DoubleClickTime)

Specifies the maximum time (in milliseconds) between the two clicks of a double click. The default is the display's multi-click time.

enableWarp (class EnableWarp)

When True (the default), causes mwm to warp the pointer to the center of the selected window during resize and move operations invoked using keyboard accelerators. (The cursor symbol disappears from its current location and reappears at the center of the window.) If False, mwm leaves the pointer at its original place on the screen, unless the user explicitly moves it.

enforceKeyFocus (class EnforceKeyFocus)

If True (the default), the input focus is always explicitly set to selected windows even if there is an indication that they are “globally active” input windows. (An example of a globally active window is a scrollbar that can be operated without setting the focus to that client.) If the resource is False, the keyboard input focus is not explicitly set to globally active windows.

fadeNormalIcon (class FadeNormalIcon)

If True, an icon is greyed out when it has been normalized. The default is False.

frameBorderWidth (class FrameBorderWidth)

Specifies the width in pixels of a window frame border, without resize handles. (The border width includes the three-dimensional shadows.) The default is 5.

iconAutoPlace (class IconAutoPlace)

Specifies whether the window manager arranges icons in a particular area of the screen or places each icon where the window was when it was iconified. If True (the default), icons are arranged in a particular area of the screen, determined by the iconPlacement resource. If False, an icon is placed at the location of the window when it is iconified.

iconBoxGeometry (class IconBoxGeometry)

Specifies the initial position and size of the icon box. Takes as its argument the standard geometry string:

widthxheight+−xoff+−yoff

where width and height are measured in icons. The default geometry string is 6x1+0−0, which places an icon box six icons wide by one icon high in the lower-left corner of the screen.

You can omit either the dimensions or the x and y offsets from the geometry string and the defaults apply. If the offsets are not provided, the iconPlacement resource is used to determine the initial placement.

The actual screen size of the icon box depends on the iconImageMaximum and iconDecoration resources, which specify icon size and padding. The default value for size is (6 x icon_width + padding) wide by (1 x icon_height + padding) high.

iconBoxName (class IconBoxName)

Specifies the name under which icon box resources are to be found. The default is iconbox.

iconBoxSBDisplayPolicy (class IconBoxSBDisplayPolicy)

Specifies what scrollbars are displayed in the icon box. The resource has three possible values: all, vertical, and horizontal. If all is specified (the default), both vertical and horizontal scrollbars are displayed at all times. vertical specifies that a single vertical scrollbar is displayed (this also sets the orientation of the icon box to horizontal—regardless of the iconBoxGeometry specification). horizontal specifies that a single horizontal scrollbar is displayed in the icon box (this also sets the orientation of the icon box to vertical—regardless of the iconBoxGeometry specification).

iconBoxTitle (class IconBoxTitle)

Specifies the name to be used in the title area of the icon box. The default is Icons.

iconClick (class IconClick)

When True (the default), the Window Menu is displayed and displayed when the pointer is clicked on an icon.

iconDecoration (class IconDecoration)

Specifies how much icon decoration is used. The resource value takes four possible values (multiple values can also be supplied): label, which specifies that only the label is displayed; image, which specifies that only the image is displayed; and activelabel, which specifies that a label (not truncated to the width of the icon) is used when the icon has the focus.

The default decoration for icons in an icon box is label image, which specifies that both the label and image parts are displayed. The default decoration for individual icons on the screen proper is activelabel label image.

iconImageMaximum (class IconImageMaximum)

Specifies the maximum size of the icon image. Takes a value of widthxheight (e.g., 80x80). The maximum size supported is 128x128. The default is 50x50.

iconImageMinimum (class IconImageMinimum)

Specifies the minimum size of the icon image. Takes a value of widthxheight (e.g., 36x48). The minimum size supported is 16x16 (which is also the default).

iconPlacement (class IconPlacement)

Specifies an icon placement scheme. The resource takes a value of the syntax:

  primary_layout    secondary_layout

There are four possible layout policies:

top, which specifies that icons are placed from the top of the screen to the bottom; bottom, which specifies a bottom to top arrangement; left, which specifies that icons are placed from the left to the right; right, which specifies a right to left arrangement.

The primary_layout specifies whether icons are placed in a row or a column and the direction of placement. The secondary_layout specifies where to place new rows or columns. For example, a value of top right specifies that icons should be placed from top to bottom on the screen and that columns should be added from right to left on the screen.

A horizontal (vertical) layout value should not be used for both the primary_layout and the secondary_layout. For example, don't use top for the primary_layout and bottom for the secondary_layout.

The default placement is left bottom (i.e., icons are placed left to right on the screen, with the first row on the bottom of the screen, and new rows added from the bottom of the screen to the top of the screen).

iconPlacementMargin (class IconPlacementMargin)

Sets the distance from the edge of the screen at which icons are placed. (The value should be greater than or equal to 0. A default value is used if an invalid distance is specified.) The default value is equal to the space between icons as they are placed on the screen (which is is based on maximizing the number of icons in each row and column).

interactivePlacement (class InteractivePlacement)

If True, specifies that new windows are to be placed interactively on the screen using the pointer. When a client is run, the pointer shape changes to an upper-left corner cursor; move the pointer to the location you want the window to appear and click the first button; the window is displayed in the selected location. If False (the default), windows are placed according to the initial window configuration attributes.

keyBindings (class KeyBindings)

Identifies the set of key bindings to be used for window management functions; must correspond to a set of key bindings specified in the mwm startup file. Note that key bindings specified in the startup file replace the built-in default bindings. The default is DefaultKeyBindings.

keyboardFocusPolicy (class KeyboardFocusPolicy)

If explicit focus is specified (the default), placing the pointer on a window (including the frame) or icon and pressing the first pointer button focuses keyboard input on the client. If pointer is specified, the keyboard input focus is directed to the client window on which the pointer rests (the pointer can also rest on the frame).

limitResize (class LimitResize)

If True (the default), the user is not allowed to resize a window to greater than the maximum size.

lowerOnIconify (class LowerOnIconify)

If True (the default), a window's icon is placed on the bottom of the stack when the window is iconified. If False, the icon is placed in the stacking order at the same place as its associated window.

maximumMaximumSize (class MaximumMaximumSize)

Specifies the maximum size of a client window (as set by the user or client), Takes a value of widthxheight (e.g., 1024x1024) where width and height are in pixels. The default is twice the screen width and height.

moveThreshold (class MoveThreshold)

Controls the sensitivity of dragging operations (such as those used to move windows and icons on the display). Takes a value of the number of pixels that the pointing device is moved while a button is held down before the move operation is initiated. The default is 4. This resource helps prevent a window or icon from moving when you click or double click and inadvertently jostle the pointer while a button is down.

multiScreen (class MultiScreen)

If False (the default), mwm manages only a single screen. If True, mwm manages all screens on the display. (See “Options.”)

passButtons (class PassButtons)

Specifies whether button press events are passed to clients after the events are used to invoke a window manager function (in the client context). If False (the default), button presses are not passed to the client. If True, button presses are passed to the client. (Note that the window manager function is done in either case.)

passSelectButton (class PassSelectButton)

Specifies whether select button press events are passed to clients after the events are used to invoke a window manager function (in the client context). If True (the default), button presses are passed to the client window. If False, button presses are not passed to the client. (Note that the window manager function is done in either case.)

positionIsFrame (class PositionIsFrame)

Specifies how mwm should interpret window position information (from the WM_NORMAL_HINTS property and from configuration requests). If True (the default), the information is interpreted as the position of the mwm client window frame. If False, it is interpreted as being the position of the client area of the window.

positionOnScreen (class PositionOnScreen)

If True (the default), specifies that windows should initially be placed (if possible) so that they are not clipped by the edge of the screen. (If a window is larger than the size of the screen, at least the upper-left corner of the window is placed is on the screen.) If False, windows are placed in the requested position even if totally off the screen.

quitTimeout (class QuitTimeout)

Specifies the amount of time (in milliseconds) that mwm will wait for a client to update the WM_COMMAND property after mwm has sent the WM_SAVE_YOURSELF message. This protocol is used only for those clients that have a WM_SAVE_YOURSELF atom and no WM_DELETE_WINDOW atom in the WM_PROTOCOLS client window property. The default is 1000. (See the f.kill function for additional information.)

raiseKeyFocus (class RaiseKeyFocus)

When True, specifies that a window raised by means of the f.normalize_and_raise function also receives the input focus. This function is available only when the keyboardFocusPolicy is explicit. The default is False.

resizeBorderWidth (class ResizeBorderWidth)

Specifies the width in pixels of a window frame border, with resize handles. (The border width includes the three-dimensional shadows.) The default is 10.

resizeCursors (class ResizeCursors)

If True (the default), the resize cursors are always displayed when the pointer is in the window resize border.

screens (class Screens)

Assigns resource names to the screens mwm is managing. If mwm is managing a single screen, only the first name in the list is used. If mwm is managing multiple screens, the names are assigned to the screens in order, starting with screen 0. (See also “Options.”)

showFeedback (class ShowFeedback)

Specifies when client feedback information is displayed. This resource controls feedback relating to the position and size of a window both during a move or resize operation and during initial window placement (if interactive placement is specified). This resource also controls window manager message and dialog boxes.

This resource accepts a list of options to be enabled or disabled. If an option is preceded by a minus sign, that option is excluded from the list (i.e., disabled). The sign of the first item in the list determines the initial set of options. If the sign of the first option is a minus, mwm assumes all options are present and starts subtracting from that set. If the sign of the first option is a plus (or no sign is used), mwm assumes no options and creates a list of enabled options from the resource value.

The possible feedback options are: all, which specifies that mwm show all feedback (this is the default); behavior, which specifies that feedback is displayed to confirm a behavior switch; kill, which specifies that feedback is confirm on receipt of KILL signal move, a box displays the coordinates of a window or icon during a move; placement, displays the position and size of a window during initial placement; quit, which specifies that a dialog box is displayed so that the user can confirm quitting mwm; resize, a box displays the window size during a resize operation; restart, displays a dialog box so that the user can confirm an mwm restart procedure; an option of none specifies that no feedback is shown.

The syntax can be confusing, but let's take a look at the following sample resource specification:

Mwm*showFeedback: resize placement restart

This resource specifies that: size information is displayed when a window is resized and that coordinates are displayed when a window is placed interactively on the screen; a dialog box is displayed so that the user can confirm or cancel a window manager restart request.

The default is all.

startupKeyFocus (class StartupKeyFocus)

When True (the default), the input focus is transferred to a window when the window is mapped (i.e,, initially managed by the window manager). This function is available only when keyboardFocusPolicy is explicit.

transientDecoration (class TransientDecoration)

Specifies the amount of decoration mwm puts on transient windows. The decoration specification is exactly the same as for the clientDecoration (client-specific) resource. Transient windows are identified by the WM_TRANSIENT_FOR property, which is added by the client to indicate a relatively temporary window. The default is menu title, which specifies that transient windows have resize borders and a titlebar with a Window Menu command button.

transientFunctions (class TransientFunctions)

Specifies which window management functions are applicable (or not applicable) to transient windows. The function specification is exactly the same as for the clientFunctions (client-specific) resource. The default is -minimize -maximize.

useIconBox (class UseIconBox)

If True, icons are placed in an icon box. By default, the individual icons are placed on the root window.

wMenuButtonClick (class WMenuButtonClick)

If True (the default), a pointer button click on the Window Menu button displays the Window Menu and leaves it displayed.

wMenuButtonClick2 (class WMenuButtonClick2)

If True, double clicking on the Window Menu command button removes the client window (actually invokes the f.kill function).

Clint-specific Resources

Some mwm resources can be set to apply to certain client applications or classes of applications. Many of the client-specific resources provide what might be considered advanced customization.

The following client-specific resources can be specified:

clientDecoration (class ClientDecoration)

Specifies the amount of window frame decoration. The resource is specified as a list of decorations to be included in or excluded from the frame. If a decoration is preceded by a minus sign, that decoration is excluded from the frame. The sign of the first item in the list determines the initial amount of decoration. If the sign of the first decoration is minus, mwm assumes all decorations are present and starts subtracting from that set. If the sign of the first decoration is plus (or not specified), then mwm starts with no decoration and creates a list using the items supplied to the resource.

The acceptable values are: all, which specifies that all decorations are included (this is the default); border, which specifies that a border is included; maximize, which specifies that the Maximize button is included (includes title bar); minimize, which specifies that a Minimize button is included (includes title bar); resizeh, which specifies that border resize handles are used (includes the border); menu, a Window Menu button should be included (includes titlebar); title, include a titlebar (includes border); and none, which specifies that no decorations are used.

For example:

Mwm*XCalc*clientDecoration: -resizeh -maximize

removes the resize handles and Maximize button from xcalc windows.

Mwm*XCalc*clientDecoration: menu minimize border

This does the same thing as the first specification. Note that either menu or minimize implies title.

clientFunctions (class ClientFunctions)

Specifies which mwm functions should be applicable to the client window. This resource consists of a list of functions, each preceded by either a minus sign or a plus sign, separated by spaces. If the function is preceded by a plus sign, the function is made applicable to the client window; If the function is preceded by a minus sign, the function is not applicable.

The default list of functions is determined by the first character in the list. If the first function in the list is preceded by a minus sign, then all functions are assumed to be applicable, with the exception of the functions listed with minus signs. If the first function in the list is preceded by a plus sign, then no functions are assumed, and the functions listed with plus signs are the only ones that become applicable to the client window.

The functions available for this resource are as follows:

focusAutoRaise (class FocusAutoRaise)

When True, a client is raised when it receives the input focus. Otherwise, the stacking of windows on the display is not changed when a window receives the input focus.

The default is determined by the keyboardFocusPolicy resource. If the keyboardFocusPolicy is explicit, the default for focusAutoRaise is True. If the keyboardFocusPolicy is pointer, the default for focusAutoRaise is False.

iconImage (class IconImage)

Specifies the pathname of a bitmap file to be used as an icon image for a client (for example, Mwm*xclock*iconImage: ~/bitmaps/bigben). The default is to display an icon image supplied by the window manager.

Use the useClientIcon resource to determine whether to use user-supplied icon images instead of client-supplied icon images.

iconImageBackground (class Background)

Specifies the background color of the icon image. The default is the icon background color specified by Mwm*background or Mwm*icon*background.

iconImageBottomShadowColor (class Foreground)

Specifies the bottom shadow color of the icon image. The default is the icon bottom shadow color specified by Mwm*icon*bottomShadowColor.

iconImageBottomShadowPixmap (class BottomShadowPixmap)

Specifies the bottom shadow Pixmap of the icon image. The default is the icon bottom shadow Pixmap specified by Mwm*icon*bottomShadowPixmap.

iconImageForeground (class Foreground)

Specifies the foreground color of the icon image. The default varies on on the icon background.

iconImageTopShadowColor (class Background)

Specifies the top shadow color of the icon image. The default is the icon top shadow color specified by Mwm*icon*topShadowColor.

iconImageTopShadowPixmap (class TopShadowPixmap)

Specifies the top shadow Pixmap of the icon image. The default is the icon top shadow pixmap specified by Mwm*icon*topShadowPixmap.

matteBackground (class Background)

Specifies the background color of the matte. The default is the client background color specified by Mwm*background or Mwm*client*background. This resource is only relevant if matteWidth is positive.

matteBottomShadowColor (class Foreground)

Specifies the bottom shadow color of the matte. The default is the client bottom shadow color specified by Mwm*bottomShadowColor or Mwm*client*bottomShadowColor. This resource is only relevant if matteWidth is positive.

matteBottomShadowPixmap(class BottomShadowPixmap)

Specifies the bottom shadow pixmap of the matte. This resource is only relevant if matteWidth is positive. The default is the client bottom shadow pixmap specified by Mwm*bottomShadowPixmap or Mwm*client*bottomShadowPixmap.

matteForeground (class Foreground)

Specifies the foreground color of the matte. The default is the client foreground color specified by Mwm*foreground or Mwm*client*foreground. This resource is only relevant if matteWidth is positive.

matteTopShadowColor (class Background)

Specifies the top shadow color of the matte. The default is the client top shadow color specified by Mwm*topShadowColor or Mwm*client*topShadowColor. This resource is only relevant if matteWidth is positive.

matteTopShadowPixmap (class TopShadowPixmap)

Specifies the top shadow pixmap of the matte. The default is the client top shadow pixmap specified by Mwm*topShadowPixmap or Mwm*client*topShadowPixmap. This resource is only relevant if matteWidth is positive.

matteWidth (class MatteWidth)

Specifies the width of the matte. The default is 0, disabling the matte.

maximumClientSize (class MaximumClientSize)

Specifies the size for a maximized window as as widthxheight. If the WM_NORMAL_HINTS property is set, the default is obtained from it. If WM_NORMAL_HINTS is not set, the default is the size that fills the screen (including borders).

Note that the width and height are interpreted in units used by the client. For example, the icon box uses the height and width of an icon as units, so the size of a maximized icon box might be 8x4, giving eight icons across and four icons down. Similarly, an xterm window uses the height and width of a character as units.

useClientIcon (class UseClientIcon)

If True, an icon image supplied by the client takes precedence over an icon image supplied by the user. The default is False.

windowMenu (class WindowMenu)

Specifies the name of the window menu (which must be defined in the startup file). The default is DefaultWindowMenu.

Environment Variables

The following environment variables are used by mwm:

HOME

Specifies the user's home directory.

LANG

Specifies the user's choice of language for the mwm message catalog and the mwm startup file.

XFILESEARCHPATH, XUSERFILESEARCHPATH, XAPPLRESDIR, XENVIRONMENT, LANG, HOME

Determines the search paths for files specifying defaults for resources. The location of the system-wide class resource file is determined on the XFILESEARCHPATH environment variable, and the location of the user-specific class resource file is determined on the XUSERFILESEARCHPATH and XAPPLRESDIR environment variables. In addition, if the LANG environment variable is set, the $LANG subdirectories are also searched.

$HOME/.motifbind

Installs the virtual key bindings property on the root window.

MWMSHELL, SHELL

Specifies the shell to use when executing commands via the f.exec function. SHELL is used only if MWMSHELL is not set.

Files

/usr/lib/X11/$LANG/system.mwmrc
/usr/lib/X11/system.mwmrc
/usr/lib/X11/app-defaults/Mwm
$HOME/Mwm
$HOME/.Xdefaults
$HOME/$LANG/.mwmrc
$HOME/.mwmrc
$HOME/.motifbind

See Also

X VendorShell(3X), VirtualBindings(3X), XmInstallImage(3X).

Copyrights

Copyright 1989, 1990 by Open Software Foundation, Inc. All Rights Reserved.

Copyright 1987, 1988, 1989, by Hewlett-Packard Company.

Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, MA. All Rights Reserved.

oclock Analog Clock

Name

oclock –display time of day in analog form.

Syntax

oclock [options]

Description

Available as of Release 4, oclock displays the current time on an analog display. The clock face is smaller and more stylized than that for xclock. For example, there are no tick-marks, save for a “jewel” at the 12 o'clock position. The chief virtue of oclock, and the one thing that has made it popular, is that it makes use of the X shape extension, which supports non-rectangular windows. The default oclock window is round, but it can be resized into all kinds of interesting ovals.

Options

oclock accepts all of the standard X Toolkit command line options, which are listed on the X reference page. (We've included some of the more commonly used Toolkit options later in this section.) In addition, oclock accepts the following application-specific options:

-jewel color

Specifies a color for the jewel on the clock.

-minute color

Specifies a color for the minute hand of the clock.

-hour color

Specifies a color for the hour hand of the clock.

-backing level

Selects an appropriate level of backing store.

-noshape

Causes the clock not to use the shape extension for non-rectangular windows; in short, with -noshape, you get a square or rectangular clock. Note that the behavior is still different from xclock -analog. If you resize xclock so that its window is rectangular, the round clockface image is centered in the rectangle. With oclock, the border of the window is always the shape of the clock.

The following standard X Toolkit options are commonly used with oclock:

-bw pixels

Specifies a width in pixels for the window border. As the Clock widget changes its border around quite a bit, this is most usefully set to zero.

-fg color

Specifies a color for both the hands and the jewel of the clock.

-bg color

Specifies a color for the background.

oclock Analog Clock

Name

oclock – display time of day in analog form.

Syntax

oclock [options]

Description

Available as of Release 4, oclock displays the current time on an analog display. The clock face is smaller and more stylized than that for xclock. For example, there are no tick-marks, save for a “jewel” at the 12 o'clock position. The chief virtue of oclock, and the one thing that has made it popular, is that it makes use of the X shape extension, which supports non-rectangular windows. The default oclock window is round, but it can be resized into all kinds of interesting ovals.

Options

oclock accepts all of the standard X Toolkit command line options, which are listed on the X reference page. (We've included some of the more commonly used Toolkit options later in this section.) In addition, oclock accepts the following application-specific options:

-jewel color

Specifies a color for the jewel on the clock.

-minute color

Specifies a color for the minute hand of the clock.

-hour color

Specifies a color for the hour hand of the clock.

-backing level

Selects an appropriate level of backing store.

-noshape

Causes the clock not to use the shape extension for non-rectangular windows; in short, with -noshape, you get a square or rectangular clock. Note that the behavior is still different from xclock -analog. If you resize xclock so that its window is rectangular, the round clockface image is centered in the rectangle. With oclock, the border of the window is always the shape of the clock.

The following standard X Toolkit options are commonly used with oclock:

-bw pixels

Specifies a width in pixels for the window border. As the Clock widget changes its border around quite a bit, this is most usefully set to zero.

-fg color

Specifies a color for both the hands and the jewel of the clock.

-bg color

Specifies a color for the background.

Colors

Although the default colors for the Clock widget are black and white, the widget was designed in color; unfortunately, the toolkit makes specifying these colors in a device-independent manner difficult. If you want to see the correct colors, add the following lines to your resource file:

Clock*Background: grey
Clock*BorderColor: light blue
Clock*hour: yellow
Clock*jewel: yellow
Clock*minute: yellow

See Also

X; Volume Four, X Toolkit Intrinsics Programming Manual; Volume Five, X Toolkit Intrinsics Reference Manual.

Author

Keith Packard, MIT X Consortium.

resize Reset Terminal for Window Size

Name

resize – utility to set TERMCAP and terminal settings to the current window size.

Syntax

resize [options]

Description

The resize client is provided for use with systems that lack the ability to automatically notify processes of window size changes. Normally, on operating systems that support this feature, xterm sends a signal (e.g., SIGWINCH on BSD 4.3-derived UNIX systems) to notify processes running in the window that the window size has changed. These programs can adjust their behavior if necessary.

resize prints a shell command for setting the TERM and TERMCAP environment variables to indicate the current size of the xterm window from which the command is run. For this output to take effect, resize must either be evaluated as part of the command line (usually done with a shell alias or function) or else redirected to a file which can then be read in. From the C shell (usually known as /bin/csh), the following alias could be defined in the user's .cshrc:

% alias rs ‘set noglob; eval ‘resize’; unset noglob’

After resizing the window, the user would type:

% rs

Users of versions of the Bourne shell (usually known as /bin/sh) that don't have command functions will need to send the output to a temporary file and then read it back in with the “.” command:

$ resize >/tmp/out
$ . /tmp/out

Options

resize accepts the following options:

-u

Indicates that Bourne shell commands should be generated even if the user's current shell isn't /bin/sh.

-c

Indicates that C shell commands should be generated even if the user's current shell isn't /bin/csh.

-s [rows columns]

Indicates that Sun console escape sequences will be used instead of the special xterm escape code. If rows and columns are given, resize will ask the xterm to resize itself. However, the window manager may choose to disallow the change.

The -u or -c must appear to the left of -s if both are specified.

Files

/etc/termcap

For the base termcap entry to modify.

~/.cshrc

User's alias for the command.

See Also

csh(1), tset(1), xterm.

Bugs

There should be some global notion of display size; termcap and terminfo need to be rethought in the context of window systems. (Fixed in BSD 4.3 and Ultrix-32 1.2.)

Authors

Mark Vandevoorde, MIT Project Athena, and Edward Moy Berkeley.

Copyright (c) 1984, 1985 by Massachusetts Institute of Technology.

See X for a complete copyright notice.

showsnf Print SNF File

Name

showsnf – print contents of an SNF file to standard output.

Syntax

showsnf [options] snf_file

Description

showsnf displays the contents of font files in the Server Natural Format produced by bdftosnf. The information displayed includes the value of each of the font properties (see Appendix M, Logical Font Description Conventions, in Volume 0, X Protocol Reference Manual), as well as information on font metrics (see section 6.2.3, Character Metrics, in Volume 1, Xlib Programming Manual).

showsnf is usually used only to verify that a font file hasn't been corrupted or to convert the individual glyphs into arrays of characters for proofreading or for conversion to some other format.

Options

showsnf accepts the following options:

-v

Indicates that bearings and sizes should be printed for each character in the font. (These are in an ASCII format similar to that produced by bmtoa. They can be converted to standard X bitmaps using atobm, and then edited with bitmap.)

-g

Indicates that character glyph bitmaps should be printed.

-m

Indicates that the bit order of the font is most significant bit first.

-l

Indicates that the bit order of the font is least significant bit first.

-M

Indicates that the byte order of the font is most significant byte first.

-L

Indicates that the byte order of the font is least significant byte first.

-pnumber

Specifies the glyph padding of the font.

-unumber

Specifies the scanline unit of the font.

See Also

X, Xserver, bdftosnf, bitmap.

Bugs

There is no way to print out only a single glyph.

xauth Authority File Utility

Name

xauth – X authority file utility.

Syntax

xauth [options] [command arguments]

Description

Available as of Release 4, the xauth program is used to edit and display authorization information used when connecting to the X server. This program is generally used to extract authorization records from one machine and merge them in on another (as is the case when using remote logins or to grant access to other users). Note that this program does not contact the X server.

Options

The following options may be used with xauth. They may be given individually (for example, -q -i) or may be combined (for example, -qi):

-f authfile

Specifies the name of the authority file to use. By default, xauth will use the file specified by the XAUTHORITY environment variable or .Xauthority in the user's home directory.

-q

Indicates that xauth should operate quietly and not print unsolicited status messages. This is the default if an xauth command is given on the command line or if the standard output is not directed to a terminal.

-v

Indicates that xauth should operate verbosely and print status messages indicating the results of various operations (for example, how many records have been read in or written out). This is the default if xauth is reading commands from its standard input and its standard output is directed to a terminal.

-i

Indicates that xauth should ignore any authority file locks. Normally, xauth will refuse to read or edit any authority files that have been locked by other programs (usually xdm or another xauth).

-b

Indicates that xauth should attempt to break any authority file locks before proceeding and should only be used to clean up stale locks.

Commands

Commands may be entered interactively, on the xauth command line, or in scripts. The following commands may be used to manipulate authority files:

add displayname protocolname hexkey

An authorization entry for the indicated displayname using the given protocolname and hexkey data is added to the authorization file.

.5i

The hexkey data is specified as an even-lengthed string of hexadecimal digits, each pair representing one octet. The first digit gives the most significant 4 bits of the octet and the second digit gives the least significant 4 bits. At present, only the protocolname MIT-MAGIC-COOKIE-1 is supported in the MIT distribution. The use of more secure protocols is limited by export limits on DES encryption. A protocol name consisting of just a single period is treated as an abbreviation for MIT-MAGIC-COOKIE-1. Note that xauth will not give you an error if you specify an invalid protocol name.

[n]extract filename displayname …

Authorization entries for each of the specified displays are written to the indicated file. If the nextract command is used, the entries are written in a numeric format suitable for non-binary transmission (such as secure electronic mail). The extracted entries can be read back in using the merge and nmerge commands. If the filename consists of just a single dash, the entries will be written to the standard output.

[n]list [displayname …]

Authorization entries for each of the specified displays (or all, if no displays are named) are printed on the standard output. If the nlist command is used, entries will be shown in the numeric format used by the nextract command; otherwise, they are shown in a textual format. Key data is always displayed in the hexadecimal format given in the description of the add command.

[n]merge [filename …]

Authorization entries are read from the specified files and are merged into the authorization database, superceding any matching existing entries. If the nmerge command is used, the numeric format given in the description of the extract command is used. If a filename consists of just a single dash, the standard input will be read if it hasn't been read before.

remove displayname …

Authorization entries matching the specified displays are removed from the authority file.

source filename

The specified filename is treated as a script containing xauth commands to execute. In such a file, blank lines and lines beginning with a sharp sign (#) are ignored. A single dash may be used to indicate the standard input, if it hasn't already been read.

info

Information describing the authorization file, whether or not any changes have been made, and from where xauth commands are being read is printed on the standard output.

exit

If any modifications have been made, the authority file is written out (if allowed), and the program exits. An end-of-file is treated as an implicit exit command.

quit

The program exits, ignoring any modifications. This may also be accomplished by pressing the interrupt character.

help [string]

A description of all commands that begin with the given string (or all commands, if no string is given) is printed on the standard output.

?

A short list of the valid commands is printed on the standard output.

Display Names

Display names for the add,[n]extract, [n]list, [n]merge, and remove commands use the same format as the DISPLAY environment variable and the common -display command line option. Display-specific information (such as the screen number) is unnecessary and will be ignored. Same-machine connections (such as local-host sockets, shared memory, and the Internet Protocol hostname localhost) are referred to as hostname/unix:displaynumber so that local entries for different machines may be stored in one authority file.

Example

The most common use for xauth is to extract the entry for the current display, copy it to another machine, and merge it into the user's authority file on the remote machine:

% xauth extract - $DISPLAY | rsh other xauth merge -

Environment Variables

This xauth program uses the following environment variables:

XAUTHORITY

To get the name of the authority file to use if the -f option isn't used. If this variable is not set, xauth will use .Xauthority in the user's home directory.

HOME

To get the user's home directory if XAUTHORITY isn't defined.

Bugs

Users that have unsecure networks should take care to use encrypted file transfer mechanisms to copy authorization entries between machines. Similarly, the MIT-MAGIC-COOKIE-1 protocol is not very useful in unsecure environments. Sites that are interested in additional security may need to use encrypted authorization mechanisms such as Kerberos.

Spaces are currently not allowed in the protocol name. Quoting could be added for the truly perverse.

See Also

X, Xserver, xdm.

Author

Jim Fulton, MIT X Consortium.

xbiff Mail Notification

Name

xbiff – mail notification program for X.

Syntax

xbiff [options]

Description

The xbiff program displays a little image of a mailbox. When there is no mail in the user's mailbox, the flag on the mailbox is down. When mail arrives, the flag goes up and the mailbox beeps. By default, pressing any mouse button in the image forces xbiff to remember the current size of the mail file as being the “empty” size and to lower the flag.

This program is nothing more than a wrapper around the Athena Mailbox widget.

Options

xbiff accepts all of the standard X Toolkit command line options, which are listed on the X reference page. (We've Included some of the more commonly used Toolkit options later in this section.) In addition, xbiff accepts the following application-specific options:

-help

Indicates that a brief summary of the allowed options should be printed on the standard error.

-update seconds

Specifies the frequency in seconds at which xbiff should update its display. If the mailbox is obscured and then exposed, it will be updated immediately. The default is 60 seconds.

-file filename

Specifies the name of the file that should be monitored. By default, xbiff watches /usr/spool/mail/username, where username is your login name.

-shape

Indicates that the mailbox window should be shaped if masks for the empty or full images are given. (Available as of Release 4.)

-volume percentage

Specifies how loud the bell should be rung when new mail comes in.

The following standard X Toolkit options are commonly used with xbiff:

-geometry geometry

Specifies the size and location of the mailbox window. The -geometry option can be (and often is) abbreviated to -g, unless there is a conflicting option that begins with “g.” The argument to the geometry option (geometry) is referred to as a “standard geometry string,” and has the form widthxheight±xoff±yoff. If you do not specify the geometry, the window manager may place the window automatically; if not, xbiff will ask you for window placement when it starts up. See “Window Geometry: Specifying Size and Location” in Chapter 3 of this guide for details. The default mailbox is 48 pixels on each side and is centered in the window.

-xrm resourcestring

Specifies a resource string to be used. This is especially useful for setting resources that do not have separate command line options.

Resources

xbiff is implemented using a simple widget, the Mailbox widget from the Athena Widget Set. It understands all of the core resource names and classes as well as those from the Mailbox widget. The resources you might want to set are listed below:

checkCommand (class CheckCommand)

Specifies a shell command to be executed to check for new mail rather than examining the size of file. The specified string value is used as the argument to a system(3) call and may therefore contain I/O redirection. An exit status of 0 indicates that new mail is waiting, 1 indicates that there has been no change in size, and 2 indicates that the mail has been cleared.

file (class File)

Specifies the name of the file to monitor. The default is to watch /usr/spool/mail/username, where username is your login name.

flip (class Flip)

Specifies whether or not the image that is shown when mail has arrived should be inverted. The default is true. (Available as of Release 4.)

fullPixmap (class Pixmap)

Specifies a bitmap to be shown when new mail has arrived. (Available as of Release 4.)

fullPixmapMask (class PixmapMask)

Specifies a mask for the bitmap to be shown when new mail has arrived. (Available as of Release 4.)

emptyPixmap (class Pixmap)

Specifies a bitmap to be shown when no new mail is present. (Available as of Release 4.)

emptyPixmapMask (class PixmapMask)

Specifies a mask for the bitmap to be shown when no new mail is present. (Available as of Release 4.)

width (class Width)

Specifies the width of the mailbox. The default is 48 pixels.

height (class Height)

Specifies the height of the mailbox. The default is 48 pixels.

onceOnly (class Boolean)

Specifies that the bell is rung only the first time new mail is found and is not rung again until at least one interval has passed with no mail waiting. The window will continue to indicate the presence of new mail until it has been retrieved.

shapeWindow (class ShapeWindow)

Specifies whether or not the mailbox window should be shaped to the given fullPixmapMask and emptyPixmapMask. (Available as of Release 4.)

update (class Interval)

Specifies the frequency in seconds at which the mail should be checked.

volume (class Volume)

Specifies how loud the bell should be rung. The default is 33 percent.

foreground (class Foreground)

Specifies the color for the foreground. The default is black since the core default for background is white.

reverseVideo (class ReverseVideo)

Specifies that the foreground and background should be reversed.

Widget Hierarchy

xbiff is implemented using a single widget, the Athena Mailbox widget. All applicable resources of the widget are listed above. The class and instance hierarchy is shown below:

Xbiff   xbiff
    Mailbox  mailbox

See Appendix G, Athena Widget Resources for a list of resources that can be set for the Athena widgets.

Actions

The Mailbox widget provides the following actions for use in event translations:

check()

Causes the widget to check for new mail and display the flag appropriately.

unset()

Causes the widget to lower the flag until new mail comes in.

set()

Causes the widget to raise the flag until the user resets it.

The default translation is:

<ButtonPress>:unset()

See Also

X, xrdb, stat(2).

Author

Jim Fulton, MIT X Consortium; Additional hacks by Ralph Swick, DEC/MIT Project Athena.

xcalc X-Based Scientific Calculator

Name

xcalc – scientific calculator for X.

Syntax

xcalc [options]

Description

xcalc is a scientific calculator desktop accessory that can emulate a TI-30 or an HP-10C The Release 4 version of xcalc has been rewritten to use the X Toolkit. Also as of Release 4, the number in the calculator display can be selected, allowing you to paste the result of a calculation into text.

In Release 4, the xcalc buttons have been changed to an oval shape (they are rectangular in the Release 3 version) and the window is somewhat smaller overall than it is in the Release 3 version. For those of you who like the size of the calculator under R3, try a geometry specification of approximately 167x222 (under mwm) and specify rectangular buttons using the resource setting:

xcalc*shapeStyle: rectangular

As of Release 4, xcalc no longer emulates a slide rule. (The -analog option has been eliminated.)

Options

xcalc accepts all of the standard X Toolkit command line options, which are listed on the X reference page. In addition, xcalc accepts the following application-specific options:

-rpn

Indicates that Reverse Polish Notation should be used. In this mode, the calculator will look and behave like an HP-10C. Without this flag, it will emulate a TI-30.

-stip, -stipple

Indicates that the background of the calculator should be drawn using a stipple of the foreground and background colors. On monochrome displays, this improves the appearance. The -stipple version of this option is available as of Release 4. The -stip option can also still be used.

Calculator Operations

Pointer Usage

Operations may be performed with pointer button 1 (usually the leftmost button), or in many cases, with the keyboard. Many common calculator operations have keyboard equivalents, which are called accelerators, because they facilitate data entry. There are several ways to cause xcalc to exit: pressing the AC key of the TI calculator or the ON key of the HP calculator with pointer button 3 (usually the rightmost button); typing q, Q, or Control-C while the pointer is in the xcalc window.

Calculator Key Usage (TI Mode)

The number keys, the +/− key, and the +, −, *, /, and = keys all do exactly what you would expect them to. It should be noted that the operators obey the standard rules of precedence. Thus, entering “3+4*5=” results in 23, not 35. Parentheses can be used to override this. For example, “(1+2+3)*(4+5+6)=” is evaluated as “6*15=” which results in 90.

The action associated with each function is given below. These are useful if you are interested in defining a custom calculator. The action used for all digit keys is digit (n), where n is the corresponding digit, 0-9. (The actions are available as of Release 4).

The keys are described below:

1/x

Replaces the number in the display with its reciprocal. The corresponding action is reciprocal().

xˆ2

Squares the number in the display. The corresponding action is square().

SQRT

Evaluates the square root of the number in the display. The corresponding action is squareRoot().

CE/C

When pressed once, clears the number in the display without clearing the state of the machine. Allows you to re-enter a number if you make a mistake. Pressing it twice clears the state also. The corresponding action is clear().

AC

Clears everything: the display, the state, and the memory. Pressing it with the third (usually the right) button “turns off” the calculator, in that it exits the program. The corresponding action to clear the state is off(); to quit, the action is quit().

INV

Inverts the meaning of the function keys. See the individual function keys for details. The corresponding action is inverse().

sin

Computes the sine of the number in the display, as interpreted by the current DRG mode (see DRG, below). If inverted, it computes the arcsine. The corresponding action is sine().

cos

Computes the cosine, or arccosine when inverted. The corresponding action is cosine().

tan

Computes the tangent, or arctangent when inverted. The corresponding action is tangent().

DRG

Changes the DRG mode, as indicated by DEG, RAD, or GRAD at the bottom of the calculator “liquid crystal” display. When in DEG mode, numbers in the display are taken as being degrees. In RAD mode, numbers are in radians, and in GRAD mode, numbers are in gradians. When inverted, the DRG key has the handy feature of converting degrees to radians to gradians and vice versa. For example, put the calculator into DEG mode and type “45 INV DRG”. The calculator should display approximately .785398, which is 45 degrees converted to radians. The corresponding action is degree().

e

Is the constant “e” (2.7182818 …). The corresponding action is e().

EE

Is used for entering exponential numbers. For example, to enter “−2 . 3E−4” you would type “2 . 3 +/− EE 4 +/−”. The corresponding action is scientific().

log

Calculates the log (base 10) of the number in the display. When inverted, it raises 10.0 to the number in the display. For example, entering “3 INV log” should result in 1000. The corresponding action is logarithm().

In

Calculates the log (base e) of the number in the display. When inverted, it raises “e” to the number in the display. For example, entering “e ln” should result in 1. The corresponding action is naturalLog().

yˆx

Raises the number on the left to the power of the number on the right. For example, “2 yˆx 3 =” results in 8, which is 2ˆ3. Also, “(1+2+3) yˆx (1+2) =” is evaluated as “6 yˆx 3=” which results in 216. The corresponding action is power().

PI

The constant “pi”. (3.1415927 ….) The corresponding action is pi().

xl

Computes the factorial of the number in the display. The number in the display must be an integer in the range 0-500, though depending on your math library, it might overflow long before that. The corresponding action is factorial().

(

Left parenthesis. The corresponding action for TI calculators is left-Paren().

)

Right parenthesis. The corresponding action for TI calculators is right-Paren().

/

Division. The corresponding action is divide().

*

Multiplication. The corresponding action is multiply().

−

Subtraction. The corresponding action is subtract().

+

Addition. The corresponding action is add().

=

Perform calculation. The TI-specific action is equal().

STO

Copies the number in the display to the memory location. The corresponding action is store().

RCL

Copies the number from the memory location to the display. The corresponding action is recall().

SUM

Adds the number in the display to the number in the memory location. The corresponding action is sum().

EXC

Swaps the number in the display with the number in the memory location. The corresponding action is exchange().

+/−

Negate (change sign). The corresponding action is negate().

.

Decimal point. The corresponding action is decimal().

Calculator Key Usage (RPN mode)

The number keys, CHS (change sign), +, −, *, /, and ENTR keys all do exactly what you would expect them to. Many of the remaining keys are the same as in TI (default) mode. The differences are detailed below. The action for the ENTR key is enter().

<−

Is a backspace key that can be used while entering a number. It will erase digits from the display. (See “Bugs.”) Inverse backspace clears the X register. The corresponding action is back().

ON

Clears everything: the display, the state, and the memory. Pressing it with the third (usually the right) pointer button “turns off” the calculator, in that it exits the program. The corresponding action to clear the state is off(); to quit, the action is quit().

INV

Inverts the meaning of the function keys. This would be the “f” key on an HP calculator, but xcalc does not display multiple legends on each key. See the individual function keys for details.

10ˆx

Raises 10.0 to the number in the top of the stack. When inverted, it calculates the log (base 10) of the number in the display. The corresponding action is tenpower().

eˆx

Raises “e” to the number in the top of the stack. When inverted, it calculates the log (base e) of the number in the display. The corresponding action is epower().

STO

Copies the number in the top of the stack to one of ten memory locations. The desired memory is specified by pressing this key and then pressing a digit key.

RCL

Pushes the number from the specified memory location onto the stack.

SUM

Adds the number on top of the stack to the number in the specified memory location.

x:y

Exchanges the numbers in the top two stack positions, the X and Y registers. The corresponding action is XexchangeY().

Rv

Rolls the stack downward. When inverted, it rolls the stack upward. The corresponding action is roll().

Blank keys were used for programming functions on the HP-10C. Their functionality has not been duplicated in xcalc.

Keyboard Equivalents (Accelerators)

If you have the pointer in the xcalc window, you can use the keyboard to enter numbers and other keys. Almost all of the calculator keys have keyboard equivalents, which are known as accelerators because they speed entry. The number keys, the operator keys, and the parentheses all have the obvious equivalents. The accelerators defined by xcalc are listed in the following table:

Note that the use of the “e” keyboard accelerator to invoke the “e” calculator key is new as of Release 4. In the Release 3 version of xcalc, the “e” keyboard accelerator corresponds to the EE calculator key.

Resources

xcalc defines the following application resources:

rpn (class Rpn)

A Boolean value that specifies whether or not the rpn mode should be used. The default is off—that is, the calculator will be used in TI mode.

stipple (class Stipple)

A Boolean value that indicates whether or not the background should be stippled. The default is on for monochrome displays, and off for color displays.

cursor (class Cursor)

The name of the symbol used to represent the pointer. The default is hand2. See Appendix D for a list of cursor names.

Widget Hierarchy

In addition, you can specify resources for each of the widgets that make up xcalc. In the notation below, indentation indicates the hierarchical structure of the widgets. The widget class name is given first, followed by the widget instance name.

XCalc xcalc
                Form  ti  or  rpn          (the name depends on the mode)
                    Form  bevel
                       Form  screen
                          Label   M        (the memory indicator on the screen)
                          Toggle  LCD      (where the data is displayed)
                          Label   INV      (the inverted indicator on the display)
                          Label   DEG      (the degrees indicator on the display)
                          Label   RAD      (the radians indicator on the display)
                          Label   GRAD     (the gradians indicator on the display)
                          Label   P        (the Parenthesis indicator on the display)
                    Command  button1       (the actual calculator buttons)
                    Command  button2       (buttons are numbered from right to left)
                    Command  button3       (See the app-defaults file for associations and so on…)
                    Command  button38      (between widget names and default labels)
                    Command  button39
                    Command  button40      (Only 39 buttons in HP mode)

See Appendix G, Athena Widget Resources for a list of resources that can be set for the Athena widgets.

Customization

The application class name is XCalc.

As of Release 4, xcalc has an enormous application defaults file, which specifies the position, label, and function of each key on the calculator. It also gives translations to serve as keyboard accelerators. Because these resources are not specified in the source code, you can create a customized calculator by writing a private application defaults file, using the Athena Command and Form widget resources to specify the size and position of buttons, the label for each button, and the function of each button.

The foreground and background colors of each calculator key can be individually specified. For the TI calculator, a classical color resource specification might be:

XCalc.ti.Command.background:     grey50
XCalc.ti.Command.foreground:     white

For each of buttons 20, 25, 30, 35, and 40, specify:

XCalc.ti.button20.background:    black
XCalc.ti.button20.foreground:    white

For each of buttons 22, 23, 24, 27, 28, 29, 32, 33, 34, 37, 38, and 39:

XCalc.ti.button22.background:     white
XCalc.ti.button22.foreground:     black

Bugs

In HP mode, a bug report claims that the sequence of keys 5, ENTR, and <− should clear the display, but it doesn't.

See Also

X, xrdb, and Appendix G, Athena Widget Resources.

Authors

John Bradley, University of Pennsylvania;
Mark Rosenstein, MIT Project Athena.

xclipboard X Clipboard Client

Name

xclipboard – X clipboard client.

Syntax

xclipboard [options]

Description

The xclipboard program is used to collect and display text selections that are sent to the CLIPBOARD by other clients. It is typically used to save CLIPBOARD selections for later use.

Since xclipboard uses a Text widget to display the contents of the clipboard, text sent to the CLIPBOARD may be re-selected for use in other applications. The contents may also be edited, using any of the editing commands built into the Text widget. (See the reference page for xedit for details.)

xclipboard stores each CLIPBOARD selection as a separate string, each of which can be selected. Each time CLIPBOARD is asserted by another application, xclipboard transfers the contents of that selection to a new buffer and displays it in the text window. Buffers are never automatically deleted, so you'll want to use the delete button to get rid of useless items.

xclipboard also responds to requests for the CLIPBOARD selection from other clients by sending the entire contents of the currently displayed buffer.

An xclipboard window has the following buttons across the top:

quit

When this button is pressed, xclipboard exits.

delete

When this button is pressed, the current buffer is deleted and the next one displayed.

new

Creates a new buffer with no contents. Useful in constructing a new CLIPBOARD selection by hand.

next

Displays the next buffer in the list.

previous

Displays the previous buffer.

Options

xclipboard accepts all of the standard X Toolkit command line options, which are listed on the X reference page. In addition, bitmap accepts the following application-specific options:

-w

Indicates that lines of text that are too long to be displayed on one line in the clipboard should wrap around to the following lines.

-nw

Indicates that long lines of text should not wrap around. This is the default behavior.

Sending and Retrieving Clipboard Contents

Text is copied to the clipboard whenever a client asserts ownership of the CLIPBOARD selection. Text is copied from the clipboard whenever a client requests the contents of the CLIPBOARD selection. This doesn't necessarily happen automatically; you must add translations for each application that you want to have work with xclipboard. Examples of event bindings that a user may wish to include in a resource configuration file to use the clipboard from xterm are:

*VT100.Translations: #override 

    Button1 <Btn3Up>:  select-end(CLIPBOARD) 

    ~Ctrl ~Meta  <Btn2Up>:   insert-selection(PRIMARY,CLIPBOARD) 

    <Btn2Down>:ignore()

The first translation, Button1 <Btn3Up>: select-end (CLIPBOARD), specifies that if button 3 is clicked while button 1 is held down, the selection will be added to the CLIPBOARD. If button 3 isn't clicked while button 1 is held down, the default xterm translation, namely to add the selection to the PRIMARY selection and CUT_BUFFER0 on any key up, takes effect instead.

On paste, the translation ~Ctrl ~Meta <Btn2Up>: insert-selection (PRIMARY, CLIPBOARD) will paste the PRIMARY selection if one is available (that is, if it is still high-lighted in a window); otherwise, it will paste the current contents of the xclipboard window (Note that this is a small change in the normal xterm selection behavior, in that usually, the PRIMARY selection would stay asserted until another selection was made, even if the selected text was no longer highlighted.) ~Ctrl and ~Meta are specified to keep this translation from conflicting with the translations that invoke the xterm menus. The ignore() action is provided to keep the <Btn2Down> event from invoking any other action.

In the notation below, indentation indicates the hierarchical structure of the widgets. The widget class name is given first, followed by the widget instance name. The first line shows the application class and instance names:

XClipboard xclipboard
        Form form
               Command  quit
               Command  delete
               Command  new
               Command  next
               Command  prev
               Text     text

For information on the resources available in each of the Athena widgets, see Appendix G, Athena Widget Resources.

Files

/usr/lib/X11/app-defaults/XClipboard

Specifies required resources (as of Release 4).

See Also

X, xcutsel, xterm, individual client documentation for how to make a selection and send it to the CLIPBOARD.

Author

Ralph R. Swick, DEC/MIT Project Athena;
Chris Peterson, MIT X Consortium;

Keith Packard, MIT X Consortium.