There are several types of Shell widgets. The Shell widget class itself, specified by the class structure pointer shellWidgetClass, is never instantiated directly in applications. Only its subclasses are used. You have seen two subclasses of the Shell widget used earlier in this books: the one used for the application's top-level widget and the one used for popups. The application's top-level widget is created by passing the class structure pointer applicationShellWidgetClass as the widget class argument to XtAppCreateShell(); this call is also made internally by XtAppInitialize(). Popup shells for dialog boxes are created by passing transientShellWidgetClass as the widget class argument to XtCreatePopupShell(). There are two other subclasses of Shell that are commonly used in applications. One is the OverrideShellWidgetClass, passed to XtCreatePopupShell() when the shell is used for popup menus. The convention is this: the shell should be an OverrideShell when the pointer is grabbed to prevent other windows from getting input while the popup is up, and the shell should be TransientShell for other popups. This is discussed further in Chapter 13, Menus, Gadgets, and Cascaded Popups.

The other additional subclass of Shell is topLevelShellWidgetClass, which is used to create additional, non-popup, top-level shells. Some applications have multiple permanent top-level windows. One of the top-level shells would be of the applicationShellWidgetClass, and the rest would be of the topLevelShellWidgetClass. Each would have a separate icon.

Shell resources are primarily a way for the user and the application to send in data to be communicated to the window manager. These window manager hints control several major areas of window manager activity: they manage screen space, icons, and keyboard input. We'll discuss these areas one at a time in the following sections. Table 11-1 lists the Shell widget's resources with a brief description of what they control, and whether the application, the user, or Xt normally sets them.

As indicated in Column 3 of the table, some Shell resources are intended to be set only once. These set-once resources can be left to their default values, set in the app-defaults file, or they can be set in the code before the Shell widget is realized; but they should not be set with XtSetValues() after realization.

Several of the Shell resources are set automatically by Xt or the window manager and under normal circumstances should not be modified by an application:

The XmNgeometry and XmNiconic resources are intended to be specified by the user. Only these two resources use standard command-line options. The XmNgeometry resource is settable using a command-line option of the form:

-geometry [width{x}height][{+-}xposition{+-}yposition]

(Either the size or position portion of the geometry string may be omitted, as indicated by the square brackets. In specifying the x or y position, a positive value, indicated by a plus sign, is relative to the top or left side of the reference window, while a negative value, indicated by a minus sign, is relative to the bottom or right side.)

The -iconic command-line option, if present, sets the XmNiconic resource, indicating to the window manager that the application should start up as an icon.

The XmNicon_x and XmNicon_y icon position hints are best left specified by the user. Icons' positions are determined by the window manager based on these hints or on an icon-positioning policy. An application with several top-level windows could set the icon position hints in its app-defaults file so that the icons for each top-level window appear side-by-side.

We will discuss the remaining resources in related groups. Section 11.1.3, "Screen Space" discusses the ones related to the size of the application's main window and other screen space issues. Section 11.1.4, "Input Model" describes the keyboard input model hint. Section 11.1.5, "Colormaps" describes how applications should handle colormaps to cooperate with the window manager. Section 11.1.6, "Icons" describes the ones that apply to the application's icon.

The Shell widgets of each application have windows that are children of the root window. These are called top-level windows. The window manager directly controls the size and position of the top-level windows of each application. The window manager does not control the geometry of other widgets that are the descendants of the Shells, except indirectly through the geometry management mechanism described in Chapter 12, Geometry Management.

The most basic size hint, the one that specifies simply the desired initial height and width, is automatically set by Xt based on the size of the child of the Shell widget. This hint is used by most window managers to display the outline of your application when it first appears on the screen, ready for the user to place and/or size the application. If your application does not have specific size needs, you need not set any additional resources.

The additional size hints specify the application's range of desired sizes, desired increments of sizes, and desired range of aspect ratios. These are set by the XmNbaseHeight, XmNbaseWidth, XmNminWidth, XmNminHeight, XmNmaxWidth, XmNmaxHeight, XmNwidthInc, XmNheightInc, XmNminAspectX, XmNminAspectY, XmNmaxAspectX, and XmNmaxAspectY resources.

Size increment hints are useful for applications that prefer to be in units of a particular number of pixels. Window managers that listen for this hint always resize the window to the base size (for each dimension), plus or minus an integral multiple of the size increment hint for that dimension. If the base size resource has not been set, the minimum size is used as the base. For example, xterm uses the font width and font height as width and height increment hints, because it prefers not to have partial characters or dead space around the edges. The bitmap editor application described in Chapter 4, An Example Application, should probably set both the width and height increments to the cell_size_in_pixels, since the bitmap cells are square.

Most applications that use size increment hints redefine the interpretation of geometry specifications (the XmNgeometry resource, settable through the -geometry standard command-line option) to reflect the size increments. For example, the width and height in xterm geometry specifications are in units of characters, not pixels. The Vt100 widget within xterm implements this by having an XmNgeometry resource separate from the shell geometry resource with that name. The entry for this resource in the widget resource list specifies the Vt100 instance structure field, not the shell instance structure field. Then the realize method for the Vt100 parses the geometry string with XParseGeometry() (an Xlib routine that returns four separate variables containing the size and position from the geometry string) and sets the width and height fields of the core structure and the various size hints according to the returned variables. (The Vt100 within xterm is not a real, self-sufficient widget. For one thing, it has no set_values method. For any real widget to implement this approach to interpreting geometry specifications, the set_values method would have to multiply the XmNwidth and XmNheight resource settings by the increment hints.)

An aspect ratio is the ratio of the width to height measurement or vice versa. The XmNminAspectX and XmNminAspectY resources are used together to determine one extreme of acceptable aspect ratios, and XmNmaxAspectX and XmNmaxAspectY determine the other extreme. For example, to suggest that the xmh application never be more than four times larger in one direction than it is in the other, the following values (as they would appear in the app-defaults file) would suffice:

xmh*topLevel.minAspectX:    1
xmh*topLevel.minAspectY:    1
xmh*topLevel.maxAspectX:    4
xmh*topLevel.maxAspectY:    4

Remember that every application must be able to do something reasonable given any size for its top-level window, even if the window is too small to be useful or if any of these hints are ignored by the window manager.

Window managers also control which window keyboard input will be delivered to by setting the keyboard focus window (sometimes called just the keyboard focus) to an application's top-level window. The distribution of events according to the current keyboard focus is handled by the server; it is a basic feature of X, not of Xt. Some window managers, like twm, use the pointer-following (also called real-estate-driven) model of keyboard input; the window containing the pointer gets the keyboard input. Setting the keyboard focus once to the root window implements the pointer-following model. Other window managers use the click-to-type model, exemplified by the Macintosh™ user interface, requiring that the user click the pointer in the window where keyboard input is to go. The window manager sets the keyboard focus to the window the user clicks on. mwm lets the user select between these two focus models by setting a resource.

With some window managers other than mwm, how the window manager treats an application window can be modified by the input model hint, which is set by the XmNinput resource. Even though mwm doesn't use the value of this hint, Motif applications should set it in case they are used under a window manager that does use the hint.

If XmNinput is set to True, the window manager will set the keyboard focus to this application or not, according to its pointer-following or click-to-type model of keyboard input. However, if it is set to False, the window manager will not set the keyboard focus to this application. If the application sets this resource to False and wants input, it will have to forcefully take the keyboard focus, and then put it back to the original window when finished.

For historical (not logical) reasons, the Intrinsics default for the XmNinput resource is False. However, there is a special internal Shell widget class called VendorShell, which sets appropriate resources for a given widget set. The proper default for a given widget set (which usually has an accompanying window manager) is set by that widget set's VendorShell. The majority of applications need XmNinput set to True unless they don't require keyboard input (and expect never to have accelerators).

There are four models of client input handling defined by the ICCCM:

Note that even if the XmNinput resource is not set to True, your application will still work under some window managers, including uwm, twm, and mwm. This is because these window managers use the pointer-following keyboard focus model or ignore this hint. However, it is not wise to assume that all window managers will ignore this hint. Therefore, if your application expects keyboard input, and is not of the globally active type described above, you can use the code shown in Example 11-1 to set the XmNinput resource.

main(argc, argv)
int argc;
char *argv[];
{
      .
      .
      .
    /* create the Shell widget, setting resource */
    topLevel = XtVaAppInitialize(&app_context, "Xmh",
            table, XtNumber(table),
            &argc, argv, NULL,
            XmNinput, (XtArgVal)True,
            NULL);
      .
      .
      .
}

Note that the XmNinput resource should always be hardcoded, since the application may fail if the user is allowed to change the expected style of keyboard focus.

For a further discussion of the keyboard focus, see Section 14.4, "The accept_focus Method and the Keyboard Focus."

On most color systems, the display uses one or more hardware registers called colormaps to store the mapping between pixel values and actual colors, which are specified as relative intensities of red, green, and blue primaries (RGB values).

X allows virtual colormaps to be created by applications. Some high-performance systems even allow all virtual colormaps to be installed in hardware colormaps and used at the same time, even to the level of one colormap per window. Far more commonly, though, there is only one hardware colormap, and virtual colormaps have to be copied into the hardware colormap one at a time as needed. Copying a virtual colormap into the hardware colormap is called installing the colormap, and the reverse process where the default colormap is installed is called uninstalling. The window manager is responsible for installing and uninstalling colormaps.

If your application has standard color needs (decoration only), then you do not have to worry about the effects of colormaps being installed and uninstalled. Your application should use the standard XmRString to XmRPixel converter to translate color names into pixel values. If the colormap is full, or becomes full at any of the color allocations in the converter, the warning messages place the burden on the user to kill some applications in order to free some colormap cells. (If the converter cannot allocate the desired color, it prints a warning message, and the default for that resource is used. If the default is not XtDefaultForeground or XtDefaultBackground, it also must be converted and this may also fail. If both allocations fail, the color will default to black. If this is not acceptable, then you will need to write your own type converter.)

If your application absolutely requires accurate colors, a certain number of distinguishable colors, or dynamically changeable colors, you will need to write your own converter to allocate colors. For example, if a color allocation for a known correct color name string fails, it means that all the colormap entries have already been allocated and no entry for that color is available. In this case, your converter might call the Xlib call XCopyColormapAndFree() to copy the allocations your application has already made into a new colormap. Then the converter would allocate the color (and all subsequent colors) from the new colormap.

See Chapter 7, Color, in Volume One, Xlib Programming Manual, for details of various color allocation techniques.

The window manager is responsible for installing and uninstalling colormaps according to its own policy. Typically, the policy is to install the colormap of the application that has the keyboard focus or that contains the pointer. When an application has created a new colormap on a system that supports only one hardware colormap, and that colormap is installed, all applications that were using the other colormap will be displayed using the new colormap. Since the pixel values from the old colormap have not been allocated in the new colormap, all applications that use the old colormap will be displayed with false colors. This is known as “going technicolor.”

The window manager or some other client may also create standard colormaps to facilitate the sharing of colors between applications. A standard colormap is a colormap allocated with a publicly known arrangement of colors. The Xlib routine XGetStandardColormap() allows an application to determine whether the window manager has created a specific standard colormap, and it gets a structure describing the colormap. Xmu provides numerous utilities for creating and using standard colormaps--see Volumes One and Two for a description.

If your application requires more than one colormap, each installed at the same time in a different window, you need to tell the window manager about this so that these colormaps can be properly installed when the application is active. You do this by calling XtSetWMColormapWindows(), specifying the ApplicationShell widget as the first argument, a list of widgets that need certain colormaps as the second argument, and the length of the list as the third argument. This instructs the window manager to read the colormap window attribute of each of the listed widgets, and to install that colormap in each widget (if possible) whenever the application is active. (Of course, any application that depends on the existence of multiple simultaneous colormaps is doomed to run on only a small percentage of existing systems.)

The colormap window attribute of a window is an unchangeable characteristic of that window, that is assigned when the window is created (when the widget is realized). The Core realize method sets it based on the XmNcolormap Core resource of the widget. Therefore, if a widget must have a certain colormap, you must set its XmNcolormap resource while creating the widget. Attempting to set XmNcolormap after a widget is created will have no effect on its colormap window attribute.

The window manager always manages the icons for each application. Depending on the window manager, these icons may simply contain a text string called the icon name, or they may contain a pattern that identifies the application, called the icon pixmap. The window manager is not obligated to display the application's icon pixmap (by default, mwm and twm do not display the icon pixmap). However, the window manager will always display at least the icon name.

An application may supply an icon name by setting the XmNiconName resource; if it does not, the window manager will usually use the application name or the value of the XmNtitle resource.

The application should supply the pattern for the icon, in the form of a single-plane pixmap, as the XmNiconPixmap resource. There are two basic ways to do this: one is by including bitmap data, and the other is by reading it in at run time. The former is easy to do with an Xlib call; the code that needs to be added is shown in Example 11-2. The latter technique, because it involves building a filename and looking in a number of locations for the file, is better done with a converter defined by the Xmu library. This converter technique is more complicated because the converter has to be registered and called with the proper arguments. The example using a converter is provided in the example source code for this book (xicon2), but is not shown here. See Chapter 10, Resource Management and Type Conversion, for more information on invoking converters.

  .
  .
  .
/*
 * The following needed if not using Motif:
 *  #include <X11/Shell.h>
 */
#include "icon"
main(argc, argv)
int argc;
char **argv;
{
    Pixmap icon_pixmap;
      .
      .
      .
    /* create topLevel here */
    icon_pixmap = XCreateBitmapFromData(XtDisplay(topLevel),
            RootWindowOfScreen(XtScreen(topLevel)),
            icon_bits,
            icon_width, icon_height );
    XtVaSetValues(topLevel, XmNiconPixmap, icon_pixmap, NULL);
      .
      .
      .
    /* realize widgets */
}

The included file, icon, is in standard X11 bitmap file format. You can create such a file using the bitmap application from the standard distribution, or xbitmap5 from the examples for this book.

The window manager may have a preferred standard size for icons. If so, it will set a property. The application can read this property with the Xlib call XGetIconSizes(). To fully support a variety of window managers, an application should be capable of creating icon pixmaps of different sizes, depending on the values returned by XGetIconSizes().

An application has the option of creating its own icon window, and then passing its ID to the window manager for management. This might be done so that the application can draw a multi-colored picture in the icon, instead of the traditional two-color bitmap, or animate the icon. However, as with all hints, the window manager is not guaranteed to honor your desires and may just ignore the icon window you provide. But if you want to try anyway, create the window using Xlib calls, and select input on it so that your application receives Expose events when they occur. Then set the ID of the window using the XmNiconWindow resource, before realizing the application. Then make sure your event loop redraws the icon when it receives Expose events on it. Accomplishing this will require writing your own modified version of XtAppMainLoop() to handle the icon events.

Virtually all current window managers decorate windows on the screen.^[73]These decorations typically include a title bar for the window with gizmos for moving and resizing the window. Current decorating window managers include twm, awm, mwm, olwm, and gwm.

The way these decorations are implemented can have an impact on Toolkit applications. The window manager places the decorations in a window slightly bigger than the application, and then reparents the application's top-level window into the decoration window. Reparenting gives the top-level window a new parent instead of the root window. The window manager actually creates the frame window as a child of the root window, then reparents the application's top-level window into the frame, and then maps the frame window.

Reparenting affects the application mainly when you try to determine a global position (relative to the root window) from the XmNx and XmNy resources of the Shell widget. This is usually done in order to place popups. Under a nonreparenting window manager such as uwm, these coordinates are indeed relative to the root window, because the parent of the shell is the root window. However, under a window manager that reparents, the coordinates of the application's main Shell widget are relative to the decoration window, not the root window. Therefore, these coordinates cannot be used for placing popups within the application. Motif's internal code that places a popup uses XtTranslateCoords() instead of relying on the position resources.

The application and mwm can communicate back and forth through properties stored on the server. The properties are associated with the top-level window of your application, so unlike selections, similar communications can be going on at the same time between different clients and the window manager without interference. The ICCCM, Inter-Client Communication Conventions Manual, defines a starting point for what information can be sent back and forth.^[74] mwm also defines some other information it is willing to send and receive.

All Shell widgets handle the required communication with the window manager; this section concerns optional communication. Note that applications should not depend on this type of communication. An application may run under a different window manager that doesn't listen to this type of message. Furthermore, an application is not required to use this type of communication, because mwm runs fine without it. This type of communication is just icing on the cake. (If you want to know whether mwm is running anyway, use the XmIsMotifWMRunning() function.)

The next three sections describe the two major groups of protocols and a set of supplementary window manager hints. The first protocol group is defined by the ICCCM, and the second by Motif. You must include the header file <X11/Protocols.h> to use any of these features.

Before you can use these features, you must also prepare the required atoms. The type Atom is an ID for the string name for a property. All applications know the name of the property they will use for communication (such as WM_PROTOCOLS), but they don't know the ID for it since it changes each time the server is run. You can get the Atom for a property name by calling XmInternAtom(). This is called interning the atom. All the fully capitalized words used in this section are property names, and must be interned before use.

Both of the following sets of protocols work in the same way. You indicate interest in participating in one or more of them by calling XmAddProtocols(). Then you register a function, using XmAddProtocolCallback(), to be called when the window manager sends you a message on a particular protocol. Of course, it is possible to resign from any of the protocols whenever you want.

Selections communicate between an owner widget and a requestor widget.^[76] The owner has the data and the requestor wants it. The owner is the widget in which the user has selected something, and the requestor is the widget in which the user has clicked to paste that something. Many widgets need to act as both owner and requester at different times. The code to handle each of the two roles is separate.

Here is a brief overview of the steps that take place during a single transfer of data from one widget to another. We'll assume we have two instances of the same widget class, which can operate either as the owner or the requestor. Initially, both widgets are in exactly the same state, neither having any text selected, and neither being the owner or requestor. We'll also assume that selections are implemented using actions tied to pointer buttons, as in existing widgets that use selections.

Figure 11-1 shows this procedure in graphic form.

The code to implement selections is divided logically into a number of functions within the widget. The next sections show the code necessary to implement both the owner and the requestor roles. The code for each role is separate and cannot share any widget variables with the other role because the transaction may be between two different widget instances.

As an example, we will add support for selections to the BitmapEdit widget described in Chapter 6, Inside a Widget, and Chapter 7, Basic Widget Methods. Little of the existing code in that widget needs to be changed. The examples show only the code added to implement selections, and describe where to add it.

We will start with the owner role, and then proceed to the requestor role, and then back to the owner role.

Figure 11-1. The process of selection transfer

The selection process begins when the user selects some text in Widget A. The widget code for the owner role must contain some code to identify the area or items selected and to highlight the text (or whatever) being selected. This user-interface portion of the owner role is carried out by actions added to the widget. Some event sequences that are not already in use must be mapped to these actions. In existing applications that support selections of text:

It is a good idea to stick with existing conventions for the user interface of highlighting a selection, so that your application will operate in a familiar way. But since BitmapEdit already uses all three pointer buttons, unmodified, to set, unset, and toggle bitmap cells, we cannot use unmodified button presses to control selections. But we can (and will) use these same buttons modified by Shift.

A selection in BitmapEdit is any rectangular set of bitmap cells. Accordingly, BitmapEdit will use Shift<Btn1Down> to set the top-left corner of a selection rectangle, Shift<Btn1Motion> to follow dragging, and Shift<Btn1Up> to set the bottom right corner.^[77] Each of these events will invoke a separate action routine, StartHighlight, ExtendHighlight, and MakeSelection, respectively. These translations are added to the widget's default translation table, and the actions are added to the actions table. Example 11-3 shows the action table, the translation table, and the three action routines.

static char defaultTranslations[] =
        "Shift<Btn1Down>:   StartHighlight()    \n\
        Shift<Btn1Motion>:  ExtendHighlight()   \n\
        Shift<Btn1Up>:      MakeSelection()     \n\
        Shift<Btn2Down>:    PasteSelection()    \n\
        ~Shift<Btn1Down>:   DoCell()            \n\
        ~Shift<Btn2Down>:   UndoCell()          \n\
        ~Shift<Btn3Down>:   ToggleCell()        \n\
        ~Shift<Btn1Motion>: DoCell()            \n\
        ~Shift<Btn2Motion>: UndoCell()          \n\
        ~Shift<Btn3Motion>: ToggleCell()";
static XtActionsRec actions[] = {
    {"DoCell", DoCell},
    {"UndoCell", UndoCell},
    {"ToggleCell", ToggleCell},
    {"StartHighlight", StartHighlight},
    {"ExtendHighlight", ExtendHighlight},
    {"MakeSelection", MakeSelection},
    {"PasteSelection", PasteSelection},
};
  .
  .
  .
/*
 *  User presses first button (by default), starting highlighting.
 */
static void
StartHighlight(w, event)
Widget w;
XButtonEvent *event;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    cw->bitmapEdit.first_box = False;
    cw->bitmapEdit.select_start_x = (cw->bitmapEdit.cur_x + event->x)
            / cw->bitmapEdit.cell_size_in_pixels;
    cw->bitmapEdit.select_start_y = (cw->bitmapEdit.cur_y + event->y)
            / cw->bitmapEdit.cell_size_in_pixels;
    /* clear old selection */
    Redisplay(cw, NULL);
}
/*
 * MakeSelection is call when the first button is released (by
 * default).  This finishes the user's highlighting, and means
 * triggers ownership of the PRIMARY selection.
 */
static void
MakeSelection(w, event)
Widget w;
XButtonEvent *event;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    int temp;
    cw->bitmapEdit.select_end_x = (cw->bitmapEdit.cur_x + event->x)
            / cw->bitmapEdit.cell_size_in_pixels;
    cw->bitmapEdit.select_end_y = (cw->bitmapEdit.cur_y + event->y)
            / cw->bitmapEdit.cell_size_in_pixels;
    if ((cw->bitmapEdit.select_end_x == cw->bitmapEdit.select_start_x)
            && (cw->bitmapEdit.select_end_y ==
            cw->bitmapEdit.select_start_y))  {
        Redisplay(cw, NULL);
        return; /* no selection */
    }
    /* swap start and end if end is greater than start */
    if (cw->bitmapEdit.select_end_x < cw->bitmapEdit.select_start_x) {
        temp = cw->bitmapEdit.select_end_x;
        cw->bitmapEdit.select_end_x = cw->bitmapEdit.select_start_x;
        cw->bitmapEdit.select_start_x = temp;
    }
    if (cw->bitmapEdit.select_end_y
            < cw->bitmapEdit.select_start_y) {
        temp = cw->bitmapEdit.select_end_y;
        cw->bitmapEdit.select_end_y =
                cw->bitmapEdit.select_start_y;
        cw->bitmapEdit.select_start_y = temp;
    }
    if (XtOwnSelection(cw, XA_PRIMARY, event->time, convert_proc,
            lose_ownership_proc, transfer_done_proc) ==
            False) {
        XtWarning("bitmapEdit: failed attempting to become
                selection owner; make a new selection. \n");
        /* Clear old selection, because lose_ownership_proc
         * isn't registered. */
        Redisplay(cw, NULL);
    }
}
/*
 * ExtendHighlight is called when the mouse is being dragged with
 * the first button down (by default).  During this time, the
 * bitmap cells that are selected (by crosses) are dynamically
 * changed as the mouse moves.
 */
static void
ExtendHighlight(w, event)
Widget w;
XMotionEvent *event;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    static int last_drawn_x, last_drawn_y;
    int event_cell_x, event_cell_y;
    event_cell_x = cw->bitmapEdit.cur_x + (event->x /
            cw->bitmapEdit.cell_size_in_pixels);
    event_cell_y = cw->bitmapEdit.cur_y + (event->y /
            cw->bitmapEdit.cell_size_in_pixels);
    if ((event_cell_x == last_drawn_x) && (event_cell_y ==
            last_drawn_y))
        return;
    if (cw->bitmapEdit.first_box) {
        DrawBoxOfXs(cw, last_drawn_x, last_drawn_y, False);
        DrawBoxOfXs(cw, event_cell_x, event_cell_y, True);
    }
    else {
        DrawBoxOfXs(cw, event_cell_x, event_cell_y, True);
        cw->bitmapEdit.first_box = True;
    }
    last_drawn_x = event_cell_x;
    last_drawn_y = event_cell_y;
}
/*
 *  DrawBoxOfXs fills a rectangular set of bitmap cells with
 *  crosses, or erases them.
 */
static void
DrawBoxOfXs(w, x, y, draw)
Widget w;
Position x, y;
Bool draw;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    Position start_pos_x, start_pos_y;
    Dimension width, height;
    GC gc;
    int i, j;
    start_pos_x = cw->bitmapEdit.cur_x +
            cw->bitmapEdit.select_start_x;
    start_pos_y = cw->bitmapEdit.cur_x +
            cw->bitmapEdit.select_start_y;
    /* swap start and end if end is greater than start */
    if (x < start_pos_x) {
        width = start_pos_x - x;
        start_pos_x = x;
    }
    else {
        width = x - start_pos_x;
    }
    if (y < start_pos_y) {
        height = start_pos_y - y;
        start_pos_y = y;
    }
    else {
        height = y - start_pos_y;
    }
    for (i=start_pos_x;i < start_pos_x + width;i++)
         for (j=start_pos_y;j < start_pos_y + height;j++)
              DrawX(cw, i, j, draw);
}
/*
 * DrawX draws an X in a bitmap cell, in white if a black cell, and
 * in black if a white cell.
 */
DrawX(cw, x, y, draw)
BitmapEditWidget cw;
Position x, y;
Bool draw;
{
    GC gc;
    if (cw->bitmapEdit.cell[x + y *
            cw->bitmapEdit.pixmap_width_in_cells] == DRAWN)
        if (draw)
            gc = cw->bitmapEdit.deep_undraw_gc;
        else
            gc = cw->bitmapEdit.deep_draw_gc;
    else
        if (draw)
            gc = cw->bitmapEdit.deep_draw_gc;
        else
            gc = cw->bitmapEdit.deep_undraw_gc;
    XDrawLine(XtDisplay(cw), XtWindow(cw), gc,
            x * cw->bitmapEdit.cell_size_in_pixels,
            y * cw->bitmapEdit.cell_size_in_pixels,
            (x + 1) * cw->bitmapEdit.cell_size_in_pixels,
            (y + 1) * cw->bitmapEdit.cell_size_in_pixels);
    XDrawLine(XtDisplay(cw), XtWindow(cw), gc,
            x * cw->bitmapEdit.cell_size_in_pixels,
            (y + 1) * cw->bitmapEdit.cell_size_in_pixels,
            (x + 1) * cw->bitmapEdit.cell_size_in_pixels,
            y * cw->bitmapEdit.cell_size_in_pixels);
}

The actions shown in Example 11-3 reference some new instance part fields we have added to BitmapEditP.h to store the state of the selection. Four of these variables are the x and y coordinates in cells of the top-left and bottom-right corners of the highlighted area: select_start_x, select_start_y, select_end_x, and select_end_y. These coordinates will be used throughout the owner code. (Because these fields are in units of bitmap cells, not pixels, their type is int rather than Position.)

The StartHighlight action is quite simple. It sets the upper-left corner instance part fields based on the button press position in the triggering event. It also clears the highlighting of the old selection, if one exists, and sets a flag to indicate that this is the beginning of a new selection. The first_box flag is added as an instance part field because it will be needed in the ExtendHighlight action.

ExtendHighlight is responsible for drawing Xs dynamically on the selected cells, much as the window manager draws the outline of a window while it is being moved. Xs are drawn on each cell in a rectangle of bitmap cells beginning from the cell selected in the StartHighlight action and ending at the cell the pointer button was released in. ExtendHighlight is triggered by pointer motion events that occur while the first button is held down. It calculates which bitmap cell the pointer is in, and if the cell is not the same as the cell the pointer was in the last time ExtendHighlight was called, it erases the previous Xs and draws new ones. This is done using two different GCs--one for drawing in black and the other in white, so the color that contrasts with the current state of each cell can be used. The black GC is also used to copy the main pixmap to the screen, and the latter is just for doing the highlighting.

Code was added to the initialize method to create this latter GC. (See the example code distribution for this modified widget instance structure.)

The MakeSelection action is triggered when the button is released after dragging, indicating that the selection is complete. This action sets the select_end_x and select_end_y instance part variables to reflect the bottom-right corner of the selection, and then swaps the top-left and bottom-right coordinates if the end coordinate is to the left or above the start coordinate. If the start and end coordinates are the same, then the action returns, since no selection was made. If a selection was made, MakeSelection calls XtOwnSelection().

Once the area is highlighted, Widget A calls XtOwnSelection() to assert that it wants the right to set the value of a property that will be used to transfer information.

XtOwnSelection() is called with six arguments:

Boolean XtOwnSelection(widget, selection, time, convert_proc,
        lose_ownership_proc, transfer_done_proc)
    Widget widget;
    Atom selection;
    Time time;
    XtConvertSelectionProc convert_proc;
    XtLoseSelectionProc lose_ownership_proc;
    XtSelectionDoneProc transfer_done_proc;

The selection argument specifies an Atom--a number representing a property. Properties are arbitrarily named pieces of data stored on the server. To simplify communication with the server, a property is never referenced by name, but by a unique integer ID called an atom. Standard atoms are defined in <Xatom.h> using defined symbols beginning with XA_; nonstandard atoms can be obtained from the server by calling the Xlib function XtInternAtom.

Widgets that support one selection at a time pass the predefined XA_PRIMARY atom to XtOwnSelection(). The ICCCM also allows you to use the XA_SECONDARY and XA_CLIPBOARD atoms. XA_SECONDARY would be used by widgets implementing behavior involving more than one selection (for example, allowing the user to make two selections, and to exchange the data they contain). No current clients implement this behavior. The XA_CLIPBOARD atom should be used by a widget that allows the user to delete a selection. We'll talk more about the properties referenced by the XA_SECONDARY and XA_CLIPBOARD atoms in Section 11.3, "Motif Cut and Paste Functions and the Clipboard."

The purpose of the XtOwnSelection() call is to make sure that only one widget has the right to set the XA_PRIMARY selection property at a time, and to assert that this widget is prepared to honor requests for this data. Notice that when you select text with xterm, that text is highlighted only until you select a different area in a different window.

The next three arguments to XtOwnSelection() specify procedures that will carry out essential parts of the selection operation:

The XtOwnSelection() call also takes a time argument--this should be the time from the event that completed the highlighting, not the constant CurrentTime. If XtOwnSelection() returns False, it means that because of network conditions another client has called XtOwnSelection() with a more recent time argument.

XtOwnSelection() returns True or False to indicate whether Widget A has been granted ownership. If True, and if this widget was not already the owner, then the old owner (if any) will receive a SelectionClear event and will clear its highlighted area. The process may end here if the user never pastes the selected data anywhere. If the user selects a different piece of data, the selection owner will receive a SelectionClear itself before ever having converted the data for a requestor.

Otherwise the owner code waits to hear from the requestor that it is ready to paste the selection.

When the user pastes the selection into Widget B, Widget B becomes the requestor and the second part of the process begins. First of all, Widget B needs a translation that maps a certain key or button event to an action that pastes data. This action calls XtGetSelectionValue().

XtGetSelectionValue() is called with six arguments:

    void XtGetSelectionValue (widget, selection, target, callback,
        client_data, time)
    Widget widget;
    Atom selection;
    Atom target;
    XtSelectionCallbackProc callback;
    XtPointer client_data;
    Time time;

The selection argument is an atom specifying which property is being used to transfer the selection. This will typically be XA_PRIMARY, though in theory two widgets (or two instances of the same widget) could agree to transfer some particular data using other properties.

The target argument is another atom, this one specifying a target representation type in which the requestor wants the information. We'll talk more about the possible values for this atom in a moment.

The callback argument is a pointer to a callback procedure that actually pastes the data. Xt will call this procedure when the owner has converted the data. The XtGetSelectionValue() call registers the callback with Xt, and sends a SelectionRequest event to the owner.

When the selection owner has successfully converted the data, the owner sends back a SelectionNotify event to Xt. Xt then calls the requestor's callback procedure. The callback procedure must handle the pasting of the data into the widget's data structures, and it must handle the case where the data could not be converted into the requested representation. We'll discuss the responsibilities of this procedure in more detail once we've seen the owner's conversion procedure.

The client_data argument of XGetSelectionValue() is normally used to pass the event that triggered the pasting into the requestor callback. The callback will use the coordinates at which the event occurred as the location at which to paste the data.

As in the call to XtOwnSelection(), the time argument should be the time from the event that initiated the pasting, not the constant CurrentTime.

XA_STRING
XA_INTEGER
XA_BITMAP

/* ARGSUSED */
static void
Initialize(request, new)
BitmapEditWidget request, new;
{
      .
      .
      .
    new->bitmapEdit.target_atom = XInternAtom(XtDisplay(new),
            "CELL_ARRAY," False);

static void
PasteSelection(w, event)
Widget w;
XButtonEvent *event;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    XtGetSelectionValue(cw, XA_PRIMARY, cw->bitmapEdit.target_atom,
            requestor_callback, event,
            event->time);
}

The real challenge in handling selections is writing the convert_proc, which converts data to the format specified by the requestor and prepares it for transfer.

As mentioned above, the widget's convert_proc is called by Xt when the requestor calls XtGetSelectionValue(). The procedure is passed the selection atom and the target atom, and is expected to return in its arguments the type, value, size, and format of the converted selection data.

To support the possibility of having to convert the data to any one of several targets, the code branches according to the value of the target passed in, and does its conversions accordingly. In the version of BitmapEdit's convert_proc shown here, only one target type is handled. Section 11.2.9, "ICCCM Compliance" describes how to add more target types, including some that are required by the ICCCM such as TARGETS.

Once the conversion is made, the procedure sets the value_return argument passed in to a pointer to a block of memory, and length_return to the size of the block. This block of memory will be set into a property by Xt and passed to the requestor's callback in the same form--as a pointer to a block of memory and a length. This puts constraints on the formats that can be used for the data.

For text selections, the data is usually a simple character string. The convert_proc simply needs to set *value_return to a pointer to the string, and length_return to the length of the string. For BitmapEdit, however, the required data is a string (of bitmap cell states) plus width and height values. Since C provides easy ways to put numeric values into strings and to get them out again at the other end, we've chosen to handle this data by converting the numbers to characters and tacking them on to the beginning of the string.

If your selection is composed of a number of numeric values, you can create a structure containing the values and then pass a pointer to the structure. However, the structure cannot contain pointers, because the data pointed to by these pointers will not be set into the selection property. For example, BitmapEdit cannot pass a pointer to a structure containing a string pointer field and width and height fields because the block of memory pointed to by the string pointer will not be copied.

In this case, the type_return can simply be the target atom that was passed in, indicating that the data is of the requested type.

The format_return is the size in bits of each element in the array. Since we are passing a compound string, this value is 8. If we were passing a structure, length_return would be 1 and *format_return would be 8 times the size of the structure in bytes.

Example 11-6 shows BitmapEdit's convert_proc.

static Boolean
convert_proc(w, selection, target, type_return, value_return,
        length_return, format_return)
Widget w;
Atom *selection;
Atom *target;
Atom *type_return;
XtPointer *value_return;
unsigned long *length_return;
int *format_return;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    int x, y;
    int width, height;
    /* handle all required atoms, and the one that we use */
    /* Xt already handles MULTIPLE, no branch necessary */
    if (*target == XA_TARGETS(XtDisplay(cw))) {
        /* Required atom: see Example 10-10 */
          .
          .
          .
    }
    else if (*target == cw->bitmapEdit.target_atom) {
        char *data;
        width = cw->bitmapEdit.select_end_x -
                cw->bitmapEdit.select_start_x;
        height = cw->bitmapEdit.select_end_y -
                cw->bitmapEdit.select_start_y;
                /* 8 chars is enough for two 3-digit
                 * numbers and two delimiters */
        *length_return = ((width * height) + 8) * sizeof(char);
        data = XtMalloc(*length_return);
        sprintf(data, "%d@%d~", width, height);
        for (x = 0; x < width; x++) {
            for (y = 0; y < height; y++) {
                data[8 + x + (y * width)] = cw->bitmapEdit.cell[(x +
                        cw->bitmapEdit.select_start_x) +
                        ((y + cw->bitmapEdit.select_start_y) *
                        cw->bitmapEdit.pixmap_width_in_cells)];
            }
        }
        *value_return = data;
        *type_return = cw->bitmapEdit.target_atom;
        *format_return = 8;  /* number of bits in char */
        return(True);
    }
    else {
        /* code to handle standard selections: see Example 10-10 */
          .
          .
          .
    }
}

This code determines the width and height of the selected rectangle from the instance part fields, and then allocates enough memory to fit a character array big enough to fit the width and height values, delimiters, and a width by height character array. Then it copies the current contents of the selected area into the allocated character array. Finally, it sets *value_return to point to the compound string, and sets *length_return to the length of this string. *format_return is the size in bits of each element in the array, which in this case is 8 bits.

When the owner's convert_proc returns, Xt sends a SelectionNotify event to the requestor. The Xt code on the requestor side then invokes the callback routine the requestor registered with the call to XtGetSelectionValue().

The requestor_callback function is passed all the same arguments that the owner received in the convert_proc, plus the values that the owner returned through the argument of convert_proc. In the BitmapEdit widget, it sets instance part fields to paste the data.

Example 11-7 shows the requestor callback function from BitmapEdit.

/* ARGSUSED */
static void
requestor_callback(w,client_data,selection,type,value,length,format)
Widget w;
XtPointer client_data;  /* cast to XButtonEvent below */
Atom *selection;
Atom *type;
XtPointer value;
unsigned long *length;
int *format;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    if ((*value == NULL) && (*length == 0)) {
        XBell(XtDisplay(cw), 100);
        XtWarning("bitmapEdit: no selection or selection timed out:\
               try again\n");
    }
    else {
        XButtonEvent *event = (XButtonEvent *) client_data;
        int width, height;
        int x, y;
        int dst_offset_x, dst_offset_y;
        char *ptr;
        dst_offset_x = (cw->bitmapEdit.cur_x + event->x) /
                cw->bitmapEdit.cell_size_in_pixels;
        dst_offset_y = (cw->bitmapEdit.cur_y + event->y) /
                cw->bitmapEdit.cell_size_in_pixels;
        printf("dst offset is %d, %d, dst_offset_x, dst_offset_y);
        ptr = (char *) value;
        width = atoi(ptr);
        ptr = index(ptr, '@');
        ptr++;
        height = atoi(ptr);
        ptr = &value[8];
        for (x = 0; x < width; x++) {
            for (y = 0; y < height; y++) {
                /* range checking */
                if (((dst_offset_x + x) >
                        cw->bitmapEdit.pixmap_width_in_cells)
                        || ((dst_offset_x + x) < 0))
                    break;
                if (((dst_offset_y + y) >
                        cw->bitmapEdit.pixmap_height_in_cells)
                        || ((dst_offset_y + y) < 0))
                    break;
                cw->bitmapEdit.cell[(dst_offset_x + x)
                        + ((dst_offset_y + y) *
                        cw->bitmapEdit.pixmap_width_in_cells)]
                        = ptr[x + (y * width)];
                if (cw->bitmapEdit.cell[(dst_offset_x + x)
                        + ((dst_offset_y + y) *
                        cw->bitmapEdit.pixmap_width_in_cells)]
                        == DRAWN)
                    DrawCell(cw, dst_offset_x + x,
                            dst_offset_y + y,
                            cw->bitmapEdit.draw_gc);
                else
                    DrawCell(cw, dst_offset_x + x,
                            dst_offset_y + y,
                            cw->bitmapEdit.undraw_gc);
            }
        }
        /* Regardless of the presence of a
         * transfer_done_proc in the owner,
         * the requestor must free the data passed by
         * Xt after using it. */
        XtFree(value);
        Redisplay(cw, NULL);
    }
}

The requestor_callback first determines whether the conversion was a success by checking the value and data length. If it was not, it beeps and prints a message. This can happen if no selection has been made, or if there is some delay that causes the selection to have timed out before the owner could convert the data.

If the conversion was a success, the requestor_callback pastes the data. In BitmapEdit's case, the requestor must first convert the data into a more useful form. This means extracting the width and height values, and then setting the widget's cell array based on the data in the character array passed in. Note that the code should check to make sure that the data can be pasted in the desired position. BitmapEdit must make sure that no attempt is made to set a cell array member outside of the bitmap. The routine then updates the screen display of the widget.

The final responsibility of the requestor_callback is to free the memory passed in by Xt.

If the owner loses the selection, either because the selection timed out or because the user made a different selection, the lose_ownership_proc that was registered with its call to XtOwnSelection() will be invoked. Typically, this function simply clears any highlighting or other visual feedback about the selection, and resets to their initial state any internal variables used in handling selections.

Example 11-8 shows the lose_ownership_proc from the BitmapEdit widget.

/* ARGSUSED */
static void
lose_ownership_proc(w, selection)
Widget w;
Atom *selection;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    /* clear old selection */
    cw->bitmapEdit.first_box = False;
    cw->bitmapEdit.select_start_x = 0;
    cw->bitmapEdit.select_start_y = 0;
    cw->bitmapEdit.select_end_x = 0;
    cw->bitmapEdit.select_end_y = 0;
    Redisplay(cw, NULL);
}

The transfer_done_proc, registered in the call to XtOwnSelection(), is called when the transfer is complete. Its job is to do any processing necessary to get ready for the next selection request. In many cases no processing is necessary and this function can be NULL in the call to XtOwnSelection(). However, this function might clear variables or free memory. Some transfers are intended to be made only once to make sure that there is no duplication of information. In these cases, the transfer_done_proc would do a lot more, including erasing the visual selection, calling XtDisownSelection() (and perhaps even erasing the data that was selected).

For any two widgets to be able to transparently transfer different types of data, there must be agreement about the possible target types and their contents. The ICCCM suggests a list of possible target types, as shown in Table 11-2. If you can, use one of these target types since this will increase the chances that your widget will be able to communicate with widgets written by other people.

Because not every widget will support every possible target type, the ICCCM specifies a target type of XA_TARGETS, to which the owner is required to respond by returning a list of the target types into which it is capable of converting data.

Normally, a requestor would first call XtGetSelectionValue() for XA_TARGETS, and then in the callback determine which target it wants to request from the list, and then call XtGetSelectionValue() again for the desired target with a separate callback to process the actual data. This is really two separate selection transfers.

XA_TARGETS is not a predefined atom.^[80] To use it, you must use the Xmu atom caching mechanism described in Section 11.2.9.1, "Xmu Atom Caching."

Fortunately, there is existing template code that you can copy to handle XA_TARGETS and some other standard target types that are required by the ICCCM.

This template code uses the Xmu routine XmuConvertStandardSelection. It also uses an Xmu atom-caching facility that eliminates the need for you to make XInternAtom() calls for each of the ICCCM standard target atoms.

#define XA_TARGETS(d)        XmuInternAtom(d, _XA_TARGETS)

if (*target == XA_TARGETS(XtDisplay(w))) { ...

(void) XmuInternAtom( XtDisplay(new), XmuMakeAtom("NULL") );

static Boolean
convert_proc(w, selection, target, type_return, value_return,
        length_return, format_return)
Widget w;
Atom *selection;
Atom *target;
Atom *type_return;
XtPointer *value_return;
unsigned long *length_return;
int *format_return;
{
    BitmapEditWidget cw = (BitmapEditWidget) w;
    int x, y;
    int width, height;
    XSelectionRequestEvent* req = XtGetSelectionRequest(w,
            *selection, (XtRequestId) NULL);
    /* handle all required atoms, and the one that we use */
    if (*target == XA_TARGETS(XtDisplay(cw))) {
        /* TARGETS handling copied from xclipboard.c */
        Atom* targetP;
        Atom* std_targets;
        unsigned long std_length;
        XmuConvertStandardSelection(cw, req->time, selection,
                target, type_return,
                (XtPointer*)&std_targets,
                &std_length, format_return);
        *value_return = XtMalloc(sizeof(Atom)*(std_length + 1));
        targetP = *(Atom**)value_return;
        *length_return = std_length + 1;
        *targetP++ = cw->bitmapEdit.target_atom;
        bcopy((char*)std_targets, (char*)targetP,
                sizeof(Atom)*std_length);
        XtFree((char*)std_targets);
        *type_return = XA_ATOM;
        *format_return = sizeof(Atom) * 8;
        return(True);
    }
    /* Xt already handles MULTIPLE, no branch necessary */
    else if (*target == cw->bitmapEdit.target_atom) {
         /* handle normal selection - code shown in Example 10-6 */
          .
          .
          .
    }
    else {
        if (XmuConvertStandardSelection(cw, CurrentTime, selection,
                target, type_return, value_return,
                length_return, format_return))
            return True;
        else {
            XtWarning("bitmapEdit: requestor is requesting\
                     unsupported selection target type. \n");
            return(False);
        }
    }
}

An incremental selection is very similar to an atomic transfer, except that you use different set of routines and procedure types, and Xt calls the procedures you register multiple times instead of just once as in atomic transfers. Incremental transfers and atomic transfers are mutually exclusive--an owner can support both, but if the owner doesn't, a requestor cannot use the incremental routines to request a selection owned atomically, or vice versa.

As in an atomic transfer, the owner and the requestor in an incremental transfer only have to make one call each in order to initiate this multiple-section transfer. Here is the procedure:

This was the process of a successful transfer. All the remaining callback functions registered are for less common occurrences or unsuccessful transfers. The cancel_callback is called by Xt on timeout. This means that the transfer is considered complete even though it failed. In this process the owner frees memory allocated for the transfer.

Calls of the lose_ownership_proc do not indicate completion of in-progress transfers--these transfers should continue. It just means that the owner lost ownership of the selection, so that the owner should unhighlight what the user selected.

If transfer_done_proc is specified, the owner allocates and frees storage. If transfer_done_proc is NULL, convert_proc must allocate storage using XtMalloc(), XtCalloc() or XtRealloc(), but Xt will free that memory. The owner may use XtDisownSelection() to relinquish ownership. (This is the same routine used to relinquish ownership of an atomic selection.)

If the user deletes the information selected, the owner should call XtDisownSelection(). XtSetSelectionTimeout() sets the time in which widgets must respond to one another. This is initially set by the XmNselectionTimeout resource, and defaults to 5 seconds. The selection timeout prevents hanging when the user pastes but the current owner is slow or hung. XtGetSelectionTimeout() reads the current selection timeout value. Widgets should not normally require these two calls, since the selection timeout should remain under the user's control.

If the requestor can request more than one target type, such as TARGETS and its normal selection target, it normally does so using separate actions. (Both actions can be invoked by the same triggering event, if desired.) Each action specifies a different target type and a different requestor callback. That way, each requestor callback handles only one type of target.

Beware: there is a danger in this approach. The selection owner might change between the repeated XtGetSelectionValue() calls. XtGetSelectionValues() (plural) can be used instead if the requestor would like to receive the data in more than one representation. The requestor's single callback function would then be called once for each representation. (The owner's convert_proc would also be called once per representation.)