The virtual key bindings shipped with IRIS IM match the default ones compiled into libXm. There is no assurance that users won't change their own bindings. Virtual key bindings are not synonyms for other keysyms. Instead, virtual key bindings replace other keysyms.

The OSF virtual key binding model translates a single keysym into a virtual keysym—for example, <Key>Left is translated to <Key>osfLeft. On Silicon Graphics keyboards, the arrows on the numeric keypad generate keypad arrows rather than arrows—for example, <Key>KP_Left instead of <Key>Left. The OSF virtual binding model is unable to accommodate multiple keysyms mapping to the same virtual keysym.

To accommodate the two types of arrows without introducing an incompatible syntax, Silicon Graphics has introduced internal virtual keysyms prefixed with _sg_KP (for example, _sg_KP_Left). These are mapped internally to the same key code as the OSF equivalent, so the net result is that both the numeric keypad and the other arrow keypad will generate the osf virtual bindings (for example, osfLeft).

Because the _sg_KP bindings are an internal mechanism that get translated to osf bindings, users should not use them directly. Bindings should not appear in translations; they may be removed from a future release.

For all IRIS IM widgets except for XmText and XmTextField, the numeric keypad is treated as pure arrow keys. For the XmText and XmTextField, the numeric keypad is treated as either arrows or numbers, depending on the state of the <Num Lock>, and <Shift> keys. If either <Shift> or <Num Lock> is on, numbers are sent, otherwise arrows are sent. It should be noted, however, that <Shift-Num Lock-KP_4> sends a shifted left arrow rather than an unshifted left arrow, which is treated differently by the text widget.

For writers of translations, whether in application default files or in widgets, it is important to understand how to write a translation so the numbers and the other keysyms work on the keypad.

If a translation of the form:

<Key>osfLeft:        action() \n \

is used, the action applies to both the left arrow key and to the numeric keypad <4> key (because it also has a left arrow on it), whether or not the <Shift> key is also pressed.

To permit the numeric keypad keys to function normally, the following form is recommended:

:<Key>KP_4:        self-insert() \n \
<Key>osfLeft:        action() \n \

The leading colon on the first translation states that the action “self-insert” should be executed if keypad <4> is pressed in such a manner that it would normally be interpreted as a digit—that is, either <Num Lock> or <Shift> is turned on, but not both. The second translation specifies that “action” should occur if <key>osfLeft is pressed in any other circumstances. Note that the action for :<key>KP_4 must come first.

So, if you are defining translations that affect the shifted keypad keys, the following translations should come first to also permit use of the digits from the numeric keypad:

:<Key>KP_0:        self-insert() \n \
:<Key>KP_1:        self-insert() \n \
:<Key>KP_2:        self-insert() \n \
:<Key>KP_3:        self-insert() \n \
:<Key>KP_4:        self-insert() \n \
:<Key>KP_5:        self-insert() \n \
:<Key>KP_6:        self-insert() \n \
:<Key>KP_7:        self-insert() \n \
:<Key>KP_8:        self-insert() \n \
:<Key>KP_9:        self-insert() \n \
:<Key>KP_Decimal:  self-insert() \n \\

Your IRIS IM software includes source for the demonstration programs provided by OSF. Many of them are contributed software—they are not part of the core product. These programs and their Imakefiles are in the subdirectories of /usr/src/X11/motif/osf_demos.

Here is important information about the demonstration programs provided by OSF:

Your IRIS IM software includes source for the overlay demonstration programs. These are slightly modified versions of the standard demonstration programs. Each source change has been clearly identified with #ifdef OVERLAY_DEMO statements. These programs and their Imakefiles are in the subdirectories of /usr/src/X11/motif/overlay_demos.

Here is important information about the overlay demonstration programs:

Your IRIS IM software includes source for the example programs in the book The X Window System: Programming and Applications with Xt, OSF/Motif Edition, Douglas A. Young, ISBN 0-13-497074-8.

These sample programs are provided to make it easier for you to use this book to learn IRIS IM. The examples also show how to use simple Makefiles with IRIS IM (as contrasted with the demonstration programs that show you how to use Imakefiles). Before you try to run an example program, be sure to read the README file in its directory.

The X defaults files for the example programs are in the AppDefaults subdirectory of /usr/src/X11/motif/book_examples.

Here is important information about the overlay demonstration programs:

On Silicon Graphics workstations, the display bitplanes are divided into framebuffers:

Note that only normal planes and popup planes are supported on all Silicon Graphics hardware. For more information on these framebuffers, including interactions between them, see the Graphics Library Programming Guide.

As part of the complete X visual, a hierarchy of six visual classes (colormap types) distinguishes between color/monochrome display, read-only/
read-write colormaps, and color index/RGB color representation.

All currently available Silicon Graphics workstations support an 8-bit PseudoColor visual, some workstations support 12-bit visuals, and X servers running on workstations with sufficient hardware support a 24-bit TrueColor visual. Other visuals may be available from a particular X server, depending largely on the type of workstation and its graphics capabilities. Various-depth visuals are available in static, dynamic, color, or gray classes.

Some workstations, such as the RealityEngine, support a 24-bit DirectColor visual. A workstation that supports DirectColor can support any of the six visual classes. There is no difference in the number of displayable colors between a 24-bit TrueColor visual and a 24-bit DirectColor visual; however, with a DirectColor visual, you can redefine the colormap to include only one color and thus obtain varying intensities of that color. TrueColor displays colors at full intensity only.

GL uses display modes to access and properly display visual data in the bitplanes of a Silicon Graphics workstation. X visuals are mapped to GL modes when an X window is prepared for GL rendering. Consult the OpenGL Programming Guide and The OpenGL Porting Guide for information on OpenGL rendering in X windows. Consult the Graphics Library Programming Tools and Techniques for information on IRIS GL rendering in X windows.

The size of the colormap depends on the number of bitplanes associated with the visual. To express interest in a colormap, use XSetWMColormapWindows(). This lets the window manager know which colormap(s) to install when your application gets focus. These are some important points about colormap sizes:

The same pixel location in different colormaps does not necessarily represent the same color. Be sure you use the correct pixel values for the colormap you are working with.

If you use a nondefault colormap, avoid color macros such as BlackPixel() and WhitePixel(). As is required by X11, these macros return pixel values that are correct for the default colormap. They will probably return inappropriate values for your application. The pixel is likely to represent a different color in your colormap, or worse yet, be out of range for it. If the pixel does not exist in your colormap (such as any pixel greater than three for a 2-bit overlay colormap), you will get an X protocol error.

You are most likely to make a “right index–wrong map” type of mistake if you use the macros BlackPixel() and WhitePixel(). For example, the BlackPixel() macro returns 0, which is black in the default colormap. That value is always transparent (not black) in the popup and overlay colormaps.

The need to deal with multiple colormaps of various sizes raises new issues. Some of these issues do not have well-defined solutions.

visual is a Shell widget resource. A Shell widget's visual resource is inherited by all widget descendants of that Shell widget (except for other Shell widgets), because their windows are descendants of the Shell's window.

colormap and depth are Core widget resources. They must always be consistent with the current visual setting. Generally, whenever you set visual, you also need to set colormap and depth.

Anything else that has an associated depth also needs to be consistent with the depth resource. The most common such consistency problem is using a pixmap at a depth different than the depth for which it was created.

---

Note: Use the new IRIS IM function XmGetPixmapByDepth() instead of XmGetPixmap().

---

When you put X toolkit components (for example, popup menus) into the overlay or popup planes, you must do this programmatically rather than from a resource file. The reasons are:

The Shell widget inherits all of the visual attributes it needs (such as colormap and depth) from its widget parent—except for the visual itself. The Shell inherits the actual visual from its window (not widget) parent. Inheriting things that must be consistent from two different places causes trouble when using nondefault visuals because the inherited values are almost certain to be inconsistent.

In practice, this usually means that the default colormap and depth come from the widget parent, but that the visual is inherited from the root window (and is therefore the default visual). This may cause an X11 server BADMATCH error when everything else pertains to a nondefault visual.

To get around this problem, you need to do one of two things:

---

Note: This modified Shell.c, and the modified Shell.o, are supplied solely on a demonstration software basis. They are not supported products and might not appear in future releases. If you link with one of them, you do not get any fixes to Shell.o that might appear in future versions of libXt.

---

Because the popup and 2-bit overlay framebuffers are two bits deep, the colormap for these framebuffers contains only four color values. In colormaps for popup or overlay framebuffers, pixel 0 is always reserved to mean transparent, which leaves room for three additional colors.

---

Note: On workstations with configurable framebuffers, for example workstations with RealityEngine graphics, pixel 0 is not reserved to mean transparent. You can use all color values on these workstations.

---

An IRIS IM widget generally uses at least four colors (foreground, background, top shadow color, bottom shadow color); however, allocating a fourth color fails. Silicon Graphics has modified certain color selection algorithms in libXm to deal with colormap overflow by choosing the “best” available color from those already in the colormap. The color chosen is not the background color (unless you are explicitly setting the background color), nor is it transparent.

Because of the limited number of choices, the “best” available color might not be very close to the one you actually requested. To produce the best possible appearance for the widget, be sure that you select your three colors carefully.

These Silicon Graphics modifications apply only to colors set in the IRIS IM library, libXm. Silicon Graphics did not modify color selection in libXt, which sets colors for things such as BorderColor. If Xt cannot allocate the color you request, it returns pixel 0, which is transparent in popups and overlays.

The IRIS IM MenuBar includes an optimization that uses a common shell for all of the pull-down menus of a single MenuBar, meaning that all such menus will be in the same visual; this should cause no practical problems.

As of Release 1.2 there is a new call, XmGetPixmapByDepth(), which you should use instead of XmGetPixmap().

XmGetPixmap() assumes DefaultDepth when it creates pixmaps and does not let you set the depth resource. You cannot use XmGetPixmap() to create pixmaps for use in a visual whose depth differs from the default depth.

Because the Xt resource converter uses the default depth, you cannot specify pixmaps in an application default file if they will be used in a visual whose depth is different from that of the default visual.

The IRIS IM resource manager (libMrm) has many visuals-related bugs that occur when you use a nondefault visual. Silicon Graphics has not fixed them. The bugs occur because libMrm relies on defaults, such as default depth and the default colormap. You can still use UIL, but use it with caution.

In your UIL file, avoid:

You can specify your colors in a resource file instead of the UIL file, but you must set up your bitmaps and pixmaps programmatically. The pixmap resource converter uses the default depth when converting a resource.