Volume 6A: Motif Programming Manual

way to allow interactive placement without allowing the user to resize the window.

The Shell widget class defines the XmNallowShellResize resource that is inherited by all of its subclasses. This

resource specifies whether or not the shell allows itself to be resized when its widget children are resized, but it does

not affect whether the user can resize the window. For example, if the number of items in a List widget grows, the

widget tries to increase its own size, which causes a rippling effect that eventually reaches the top−level window. If

XmNallowShellResize is True for this shell, it grows, subject to the window manager's approval, of course.

However, if the resource is False, the shell does not even consult the window manager because it knows that it

doesn't want to resize. This resource only prevents the shell from resizing after it has been realized, so it does not

interfere with the initial sizing of the shell.

17.2.3 The Shell's Icon

Shells can be in one of three states: normal, iconic, or withdrawn. When a shell is in its normal state, the user can

interact with the user−interface elements in the expected way. If a shell is withdrawn, it is still active, but the user

cannot interact with it directly. When a shell is iconic, its window is not mapped to the screen, but instead it displays a

smaller image, or icon, that represents the entire window. The application is still running in this state, but the program

does not expect any user interaction. The icon window usually displays a visual image that suggests some connection

to the window from which it came. Some window managers, like mwm, also allow a label to be attached to the icon's

window.

The XmNiconPixmap resource specifies the pixmap that is used when an application is in an iconic state. the source

code shows a simple application that sets its icon pixmap. XtSetLanguageProc() is only available in X11R5;

there is no corresponding function in X11R4.

#include <Xm/Xm.h>

#include <X11/bitmaps/mailfull>

main(argc, argv)

int argc;

char *argv[];

{

Widget toplevel;

XtAppContext app;

Pixmap bitmap;

XtSetLanguageProc (NULL, NULL, NULL);

toplevel = XtVaAppInitialize (&app, "Demos",

NULL, 0, &argc, argv, NULL,

XmNwidth, 100, /* size is irrelevant −− toplevel is iconified */

XmNheight, 100, /* it just can't be 0, or Xt complains */

XmNiconic, True,

NULL);

bitmap = XCreatePixmapFromBitmapData (XtDisplay (toplevel),

RootWindowOfScreen (XtScreen (toplevel)),

mailfull_bits, mailfull_width, mailfull_height, 1, 0, 1);

XtVaSetValues (toplevel,

XmNiconPixmap, bitmap,

NULL);

XtRealizeWidget (toplevel);

XtAppMainLoop (app);

}

17 Interacting With the Window Manager 17.2.3 The Shell's Icon

477

The program creates an ApplicationShell and sets the XmNiconic resource to True to cause the application to

appear iconified. The bitmap variable is initialized to contain the bitmap described by the file

/usr/include/X11/bitmaps/mailfull, and the XmNiconPixmap resource for the shell is set to the bitmap.

When we set the XmNiconPixmap and XmNiconic resources, we are actually sending hints to the window

manager that we would like the icon window to display the given pixmap and that we would like to be in the iconic

state. These requests are called hints because the window manager does not have to comply with the requests.

However, if the icon pixmap or iconic state is ignored, it is most likely a bug in the window manager, or an

incomplete implementation of one, which is often the case for older versions of many window managers, including

mwm (Version 1.0).

One workaround for a window manager that ignores the icon pixmap is to set the XmNiconWindow resource. This

resource sets the entire icon window, rather than just its image. In environments where the user may not be running

the most up−to−date window manager, it may be best to create the icon window directly and then paint an image in

that window. the source code contains a routine that demonstrates this technique. This routine creates a shell's icon

window and can be called repeatedly to dynamically update its image.

void

SetIconWindow(shell, image)

Widget shell;

Pixmap image;

{

Window window, root;

unsigned int width, height, border_width, depth;

int x, y;

Display *dpy = XtDisplay (shell);

/* Get the current icon window associated with the shell */

XtVaGetValues (shell, XmNiconWindow, &window, NULL);

if (!window) {

/* If there is no window associated with the shell, create one.

* Make it at least as big as the pixmap we're

* going to use. The icon window only needs to be a simple window.

*/

if (!XGetGeometry (dpy, image, &root, &x, &y,

&width, &height, &border_width, &depth) ||

!(window = XCreateSimpleWindow (dpy, root, 0, 0, width, height,

(unsigned)0, CopyFromParent, CopyFromParent))) {

XtVaSetValues (shell, XmNiconPixmap, image, NULL);

return;

}

/* Now that the window is created, set it ... */

XtVaSetValues (shell, XmNiconWindow, window, NULL);

}

/* Set the window's background pixmap to be the image. */

XSetWindowBackgroundPixmap (dpy, window, image);

/* cause a redisplay of this window, if exposed */

XClearWindow (dpy, window);

}

SetIconWindow() takes two parameters: a shell and an image. If the icon window for shell has not yet been

set, we create a window using XCreateSimpleWindow(). The size of the window is set to the size of the image,

which is retrieved with XGetGeometry(). This function is used to get the size of the image, but it can be used on

windows as well. In the unlikely event that one of these routines fails, we fall back to using XmNiconPixmap to

specify the image and hope the window manager understands it. Otherwise, we set the XmNiconWindow resource to

17 Interacting With the Window Manager 17.2.3 The Shell's Icon

478