Working with Icons

Icons provide a handy way to straighten up a cluttered workspace.

Figure 7-3 The Parts of an Icon

An icon image (a bitmap) is the actual graphic illustration of the icon. An image can come from any one of the following three sources, listed in order of precedence:

user: You can specify an icon image using the iconImage resource.
client: A client can use the WM_HINTS window property to specify either an icon window or a bitmap for the window manager to use as the icon image.
default: The window manager will use its own built-in default icon image if an image is not specified elsewhere.

The window manager searches for an icon image in the order shown above. It stops searching when it finds the first image that meets the selection criteria.

The resource useClientIcon lets you interchange the precedence of user-supplied icon images and client-supplied icon images. The default value is "False." When the resource is set to "True," client-specified icon images have precedence over user-supplied icon images.

Controlling Icon Placement

By default, the window manager places icons in the lower left corner of the root window. Successive icons are placed in a row proceeding toward the right. Icons are prevented from overlapping. An icon will be placed in the position it last occupied if no icon is already there. If that place is taken, the icon will be placed at the next free location.

The following three resources enable you to control the placement of icons:

Table 7-9 Controlling Icon Placement with Window Manager Resources

To specify this...	Use this resource...	The default value is...
A placement scheme for icons.	`iconPlacement`	left bottom
The distance between screen edge and icons.	`iconPlacementMargin`	the default space between icons
Automatic icon placement by the window manager.	`iconAutoPlace`	True

The following table lists the icon placement schemes available to you:

Table 7-10 Schemes for Automatic Placement of Icons

If you want this icon placement...	Choose this scheme...
From left to right across the top of the screen.	`left top`
From right to left across the top of the screen.	`right top`
From left to right across the bottom of the screen.	`left bottom`
From right to left across the bottom of the screen.	`right bottom`
From bottom to top along the left of the screen.	`bottom left`
From bottom to top along the right of the screen.	`bottom right`
From top to bottom along the left of the screen.	`top left`
From top to bottom along the right of the screen.	`top right`

For example, if you want automatic placement of icons starting at the top of the screen and proceeding down the right side, you would have the following lines in your personal resource specifications:

   Mwm*iconPlacement:  top right       Specifies the placement scheme. 

   Mwm*iconAutoPlace:  True            Specifies automatic placement.

Controlling Icon Appearance and Behavior

mwm offers you a number of resources to control the specific appearance and behavior of icons.

Selecting Icon Decoration

Using the iconDecoration resource, you can select exactly what parts of an icon you want to display:

Table 7-11 The Values That Control the Appearance of Icons

If you want an icon that looks like this...	Use this value...
Just the label.	`label`
Just the image.	`image`
Both label and image.	`label image`
The label of an active icon isn't truncated.	`label activelabel`

Sizing Icons

Each icon image has a maximum and minimum size. mwm has both default sizes as well as maximum and minimum allowable sizes.

Table 7-12 The Maximum and Minimum Sizes for Icon Images

	Maximum Size	Minimum Size
Default	50×50 pixels	32×32 pixels
Allowable	128×128 pixels	16×16 pixels

How the window manager treats an icon depends on the size of the image in relation to the maximum and minimum sizes.

Table 7-13 Image Size Affects Icon Treatment

If an icon image is...	The window manager will...
Smaller than the minimum size.	Act as if you specified no image.
Within maximum and minimum limits.	Center the image within the maximum area.
Larger than the maximum size.	Clip the right side and bottom of the image to fit the maximum size.

You can use the following two resources to control icon image size:

Table 7-14 Controlling Icon Image Size

To specify this...	Use this resource...
Maximum size of an icon image.	`iconImageMaximum`
Minimum size of an icon image.	`iconImageMinimum`

Bear in mind that the overall width of an icon is the image width plus border padding and the image height is the icon height plus border padding.

Using Custom Pixmaps

When you iconify a client, either the client supplies its own icon image, the window manager supplies a default image, or you supply an image of your own.

There are two resources that tell the window manager where custom icons are located:

The iconImage resource specifies the bitmap for a particular icon image. Its value is the path to the file containing the bitmap. If this resource is specified, it overrides any client-specified images.
The bitmapDirectory resource causes the window manager to search a specified directory for bitmaps. The bitmapDirectory resource causes the window manager to search the specified directory whenever a bitmap is named with no complete path. The default value for bitmapDirectory is /usr/include/X11/bitmaps.

Coloring and Tiling Icons

A number of resources enable you to specify the colors of icon elements.

Table 7-15 Coloring and Tiling Icon Resources

To color this...	Use this resource...
Icon image background.	`iconImageBackground`
Left and upper bevel of icon image.	`iconImageTopShadowColor`
Right and lower bevel of icon image.	`iconImageBottomShadowColor`
Icon image foreground.	`iconImageForeground`
Right and lower bevels of an icon image.	`iconImageBottomShadowPixmap`
Left and upper bevels of an icon image.	`iconImageTopShadowPixmap`

Default values for these resources are the icon's bottom and top shadow pixmaps specified using the bottomShadowPixmap and topShandowPixmap resources set by the entries Mwm*icon*resource or Mwm*resource.

Using the Icon Box to Hold Icons

The icon box allows you to use an icon box to contain icons, rather than having stand-alone icons on the workspace.

Figure 7-4 Icon Box

The icon box is a scrollable window that displays icons in a grid (rows and columns). Icons in the icon box do not overlap. If there are icons that cannot be displayed in the visible part of the icon box, you can scroll to see the icons. The sliders within the scroll bars show the extent of the icon grid that is visible.

The icon box can be minimized (iconified) just like any other window. If the icon box is minimized, it is placed into the icon grid on the workspace.

Specifying the Icon Box

Several resources specify whether an icon box is used, define its geometry and location, and specify its name (for looking up resources) and title.

The useIconBox resource specifies whether or not an icon box is used. A value of of "True" places icons in an icon box. The default value of "False" places icons on the root window.
The iconBoxGeometry resource sets the initial size and placement of the icon box. If the iconBoxGeometry resource is used, the largest dimension of the size determines if the icons are placed in a row or a column. The default policy is to place icons in a row going from left to right, top to bottom.
The value of the iconBoxGeometry resource is a standard window geometry string with the following syntax:
- Width × Height [± x ± y]
If x and y are not provided, the icon box is placed at +0-0.
The actual size of the icon box window depends on the iconImageMaximum (size) and iconDecoration resources. The default value for size is (6 * iconWidth + padding) wide by (1 * iconHeight + padding) high.
The iconBoxName resource specifies the name that is used to look up icon box resources. The default name is "iconbox."
The iconBoxTitle resource specifies the name that is used in the title area of the icon box frame. The default name is "Icons."

For example, the following line specifies that icons will be placed in an icon box:

   Mwm*useIconBox:  True

Controlling the Appearance of Icon Boxes

The icon box is displayed in a standard window management client frame. Client-specific resources for the icon box can be specified using "iconbox" as the client name.

Mwm*iconbox*resource: value

Resources that can be used with the icon box to change its appearance are:

iconDecoration.
The mwm resources dealing with mattes and icon appearance. (The icon appearance resources affect the icon displayed when the icon box is minimized.)

The Icon Box Window Menu

The window menu for the icon box differs from the standard window menu in that it does not contain the "Close" selection. In its place is the "PackIcons" selection, which shifts icons to fill empty spaces in the icon placement grid so that the icons appear in neat, complete rows.

Controlling Icons in the Icon Box

Every client window that can be iconified has an icon in the icon box, even when the window is in the normal state. The icon for a client is put into the icon box when the client becomes managed by the window manager, and is removed from the icon box when the client stops.

Icons for windows in the normal (open) state are visually distinct from icons for windows that are iconified. Icons for windows that are iconified look like stand-alone icons. Icons for windows that are in the normal state appear flat and are optionally grayed-out. The value of "True" for the fadeNormalIcon resource grays out icons for normalized windows. The default value is "False."

The text and image attributes of icons in icon boxes are determined in the same way as for stand-alone icons, using the iconDecoration resource.

A standard "control" location cursor is used to indicate the particular icon in the icon box to which keyboard actions apply. The location cursor is an unfilled rectangle that surrounds the icon.

Icons contained in the icon box can be manipulated with the mouse and from the keyboard. Mouse button actions apply whenever the pointer is on any part of the icon.

Table 7-16 Controlling Icons in the Icon Box With a Mouse

If you want to...	Do this...
Select an icon.	Press button 1.
Normalize (open) an iconified window.	Double-click mouse button 1.
Raise a normalized window to the top of the stack.	Double-click mouse button 1.
Move an icon within the icon box.	Drag button 1.

To manipulate an icon from the keyboard, make the icon box the active window and use the arrow keys to traverse the icons in the icon box. Pressing Return does the default action for the selected icon: for an icon of a normalized window, the window is raised; for an icon of an iconified window, the window is normalized. The arrow keys move the focus around the icons that are visible. The Tab key moves the keyboard input focus around the box in this order: icons, horizontal scroll bar, vertical scroll bar, icons. Shift Tab moves the focus in the opposite direction.