Volume 7A: XView Programming Manual

18

Selections

The X Window System provides several methods for separate applications to exchange infor-

mation with one another. One of these methods is the use of selections. A selection transfers

arbitrary information between two clients. An in-depth discussion of the selection mecha-

nism that X provides is available in the Xlib Programming Manual. This chapter describes

XView’s new selection package. Previous revisions of XView provided a selection mecha-

nism that did not use objects.

The selection mechanism for previous versions of XView used special functions and struc-

tures to implement selections. The older selection mechanism is still supported and it is

described in Appendix A, The Selection Service. The new package implements selections as

objects. The application programmer interface for the new selection package conforms to the

standard XView model, using xv_create(), xv_set(), and xv_get().

XView selections are used to exchange data between different applications or for commu-

nications within a single application. Many, but not all selections use text; a section of text is

selected, then the selected text is cut or copied, and pasted to another area. The selection

mechanism is not limited to text. For example, selections can be used to transfer filenames,

sound data, a file’s timestamp, or other information. Selections require only that the sender

and the recipient have knowledge of the format of the data being transferred. Therefore,

selections can be used to transfer graphics between applications that can understand a com-

mon format for communicating graphics. XView selections conform to the conventions in

the ICCCM (Interclient Communications Conventions Manual). For a description of the

ICCCM conventions, refer to Volume Zero, X Protocol Reference Manual.

In OPEN LOOK, you select objects in basically the same way that you select windows or icons

—using the SELECT and ADJUST mouse buttons. Figure 18-1, from the OPEN LOOK GUI

Specification Guide, shows one way to select text. OPEN LOOK describes three functions that

operate on selected objects: CUT, COPY, and PASTE. These are core functions that are

accessed from the keyboard.* Table 18-1 summarizes text selection for the OPENLOOK GUI.

*The function keys that are bound to these functions vary from keyboard to keyboard depending on the make and

model of the computer.

Selections

Selections 393

Figure 18-1. Dragging the pointer to select text

Table 18-1. Selecting Text

Action Off Selection On Selection

Click

SELECT

Insert point is set at the pointer loca-

tion.

When SELECT is released, insert point

is set at pointer location and selection

is cleared.

Drag

SELECT

Text is highlighted as pointer is

dragged (wipe-through selection).

Text move pointer is displayed.

When you release SELECT, text is

moved to pointer location if that loca-

tion is outside the highlighted area.

Click

ADJUST

Extends the highlighting to the

pointer location extending either the

beginning or the end of the current

selection.

Moves the end of the highlighting to

the pointer location. Beginning of

selection is preserved.

Drag

ADJUST

Adjusts an existing selection as the

pointer is dragged (wipe-through).

Beginning of selection is anchored at

insert point.

Adjusts an existing selection as

pointer is dragged (wipe-through).

Beginning of selection is anchored at

insert point.

If an application uses objects such as TEXTSW or PANEL_TEXT_ITEM, the CUT, COPY, and

PASTE command keys are internally implemented. These selection functions are built-in for

these objects.

Note that although OPEN LOOK specifies the selection of graphic objects, no XView objects

currently support selection of graphical objects. A possible implementation is to have a can-

vas object, which has graphic objects displayed in it, set selections based on the event

394 XView Programming Manual

sequences outlined in Table 18-1. A draw application might consider a drawn geometric

shape as a graphic object, whereas a paint application might consider the pixels in an arbi-

trary area as the graphical object.

18.1 The XView Selection Model

The XView selection model is based upon the requestor/owner model of peer-to-peer com-

munications. Selections communicate data between an owner client and a requestor client.

An owner client has the selection data and the requestor client wants that data. XView uses

an object instantiated from the SELECTION_OWNER package to handle the selection owner,

and an object instantiated from the SELECTION_REQUESTOR package to handle the selection

requestor. Besides the owner and requestor objects, there is an XView hidden class,

SELECTION, that handles information common to both a requestor and an owner. XView also

provides an optional selection-item object, instantiated from the SELECTION_ITEM package,

that can simplify the owner side of selections (to simplify this discussion, we do not cover the

selection item until later in this chapter).

For XView to implement selections, XView tracks all X events that are generated from

selections. These events are:

SEL_CLEAR, SEL_NOTIFY, and SEL_REQUEST (X selection

events are mapped to these XView events). Your application should ignore these events if

you are using the selection package. If you want to implement selections with Xlib routines,

then you can use these events; however, mixing is not allowed. That is, do not try to use both

these events and use the XView the selection package.

The selection package allows you to select the rank of your selection. The rank is an atom

representing a name on the server. The default rank is called the primary rank (XA_PRI-

MARY

). For selections involving text, the primary rank is normally indicated on the screen by

inverting (highlighting) its contents. Selections made while a function key is held down are

considered secondary selections* (for text selections this is usually indicated with an under-

score under the selection).

Other ranks are also available;

OPEN LOOK uses the CLIPBOARD rank to hold data that has

been cut or copied, using the cut or copy operations (with the CUT or COPY keys). This

selection is inserted into an application with the paste operation (using the PASTE key).

Atoms take up server resources, therefore the primary, secondary, and clipboard ranks are

commonly used for selections; they are used over and over unless more than three selections

need to be created. Other selections are used when the primary selection must be left undis-

turbed.

When a user interface element, such as a text subwindow wants to allow the user to make a

selection, internally, it creates a selection-owner object. Through this selection-owner

object, the text subwindow can acquire a selection rank (primary, secondary, etc) and provide

it with data. An application can have many such selection owners, but there is typically one

selection owner per XView object. Normally a selection rank is associated with an owner—a

*Which function key depends on your particular computer. By default the L6 function key should work for Sun

Workstations or the F6 key for other computers.

Selections

Selections 395

separate owner need not be created just to utilize other selection ranks. However, only one

owner can acquire a particular selection rank at any one time. If one application acquires a

selection, and then another application acquires the same selection, the first application loses

the selection ownership. The application that becomes the new selection owner may change

the data associated with the selection.

Since the selection package conforms to the conventions of the ICCCM, selections between

non-XView applications should be seamless.

18.2 How Selection Works (Without a Selection Item)

Here is a brief overview of the steps that take place during a single transfer of data from one

XView application to another. We’ll assume we have two applications, application A and

application B, either of which can operate as the owner or the requestor.

Initially, both applications are in exactly the same state, neither has acquired any selections,

and neither is the owner or the requestor. We’ll also assume that selections are implemented

using actions tied to mouse buttons or the

CUT and PASTE function keys.

1. The user selects an item in application A and the application highlights the item. At this

time, application A would acquire the primary selection.

2. In the XView Selection Owner package, nothing further happens until an ACTION_COPY

event is delivered. At this time, application A acquires the selection and the primary

selection is copied to the clipboard.

3. The user pastes the selected data into application B, causing an ACTION_PASTE to be sent

to application B.

4. The ACTION_PASTE event may cause the selection requestor to request to receive the

selected data into application B.

5. The selection data request invokes an application-defined conversion procedure which is

associated with the Selection Owner in application A. It is the responsibility of the

Selection Owner to convert the data into a format specified by application B or to reject

the request.

6. Once the data conversion is finished, successfully or unsuccessfully, an application-

defined reply procedure is invoked in application B. This procedure is associated with the

selection requestor and either displays the data in application B, if the data conversion

was successful, or indicates that the kind of data selected in application A cannot be

pasted in application B, or that the kind of data requested by B cannot be supplied by A.

7. Once the selection data transfer is completed, a application-defined done procedure may

be called by the selection owner. The done procedure may be used to free the memory

associated with the selection, or perform other cleanup that is required.

8. If another application acquires the selection, application A’s “lose” procedure is called.

This procedure is used to tell the selection owner (application A) that it has lost

396 XView Programming Manual

ownership of the selection. For example, the lose procedure might unhighlight text that

was previously selected and highlighted.

18.2.1 Highlighting the Selection (Selection Owner)

The first task for the application that is to become the selection owner is to mark the

selection. For example, in a selection transfer involving text, when the pointer is placed over

the text, an ACTION_SELECT should highlight the selection. While LOC_DRAG occurs, the

highlight would be extended over the selection. If you are creating your own selections and

you want your application to be OPEN LOOK compliant, you need to handle events and high-

lighting as specified in the OPEN LOOK GUI Functional Specification. Some XView pack-

ages, such as TEXTSW and PANEL_TEXT_ITEM, provide this functionality internally.

18.2.2 Making the Selection (Selection Owner)

After the user selects an item and it is highlighted, the application waits to receive an event

of interest. For example, in a text subwindow the act of highlighting an item causes the pri-

mary selection to be acquired. At this time the XView application creates a selection owner

object, if one was not previously created. For the text subwindow example, an

ACTION_COPY

event causes the CLIPBOARD selection to be acquired (note that in this case two selections

are acquired since the COPY operation in OPEN LOOK uses the CLIPBOARD).

Applications perform three steps to become the selection owner:

1. A Selection_owner object is created using xv_create() (assuming a previously

created selection owner is not being reused).

2. A mechanism for replying to the selection request should be set. This may be accom-

plished either by setting a conversion procedure or by creating a selection item (see Sec-

tion 18.3.1, “The Selection Item”). The conversion procedure, or the selection item,

allows the selection data to be associated with the selection owner and converted to the

type a requestor expects.

3. The selection must be acquired.

A selection-owner object is created using xv_create():

Selection_owner sel_owner;

sel_owner = xv_create(window, SELECTION_OWNER,

NULL);

A selection-owner object’s owner is a window or a window based object. The

SELECTION_OWNER package is defined in the header file <xview/sel_pkg.h>. Programs that

use a selection owner must include this file. Figure 18-2 shows the class hierarchy for the

selection-owner object.

Selections

Selections 397