Volume 7A: XView Programming Manual

A

The Selection Service

This appendix describes the compatibility procedures and attributes that support the XView

Selection Service. If you are creating a new application that uses selections, refer to Chapter

18, Selections. This appendix is provided only for those who need to use the selection ser-

vice for compatibility reasons. It contains the text on selections that was found in older ver-

sions of this book. XView still supports the procedures and attributes described in this

appendix. Details on these procedures and attributes may be found in appendices in the

XView Reference Manual.

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 the selection service. A

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

selection mechanism that X provides is discussed in Volume One, Xlib Programming Man-

ual. This chapter addresses XView’s programmatic interface to the selection service pro-

vided by the X server.

While XView provides all the functions for applications to set and get selections of various

sorts, OPEN LOOK applications must follow the conventions outlined in the OPEN LOOK GUI

Specification Guide. All XView packages that have interactive text entry support the ability

to make selections and to get selections from the server. In OPEN LOOK, you select objects in

basically the same way that you select windows or icons—using the SELECT and ADJUST

mouse buttons. OPEN LOOK describes three functions that operate on selected objects: CUT,

COPY, and PASTE. These are core functions that are accessed from the keyboard.* CUT,

COPY, and PASTE operations use the clipboard to keep track of selected objects. The clip-

board temporarily stores items selected via the selection service; it does not store selected

windows or icons since these are not considered selectable objects by the selection service.

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

model of the computer.

The Selection

Service

The Selection Service 635

Table A-1 summarizes text selection for the OPEN LOOK GUI.

Table A-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.

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

sequences outlined in Table A-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.

A.1 The XView Selection Model

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

munications. The owner has the data representing the value of its selection, and the reques-

tor receives it.

In the X environment, all data transferred between an owner and a requestor must transfer via

the server. An X client cannot assume that another client can open the same files or even

communicate directly. Such assumptions might result in an application that does not work in

all network configurations or across heterogeneous computer architectures.

X makes provisions for selections and therefore generates certain events such as Proper-

tyNotify when a selection is acquired. For XView to implement its selection service,

XView tracks all events that might be generated from selections. Because of this, you cannot

use any of the selection mechanisms provided by Xlib. If you do, you will generate events

that you will not be able to receive and that XView will be confused about.

636 XView Programming Manual

The XView selection library deals with four discrete ranks under the general term selection.

Those ranks are: primary, secondary, shelf, and caret. Most familiar is the primary selection,

which is normally indicated on the screen by inverting (highlighting) its contents. Selections

made while a function key is held down (usually indicated with an underscore under the

selection) are considered secondary selections.* These selections are used when the primary

selection must be left undisturbed. The shelf (or clipboard) selection is used by the CUT and

COPY operations to load the selection, while the PASTE operation retrieves the selection.

Finally, the caret (the insertion point for interactive text objects) is also treated as a selection

even though it has no contents.

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

selection, it must have a selection client. Through this client, the text subwindow can acquire

a selection rank (primary, secondary, etc) and provide it with data (text). An application can

have many such clients, but there is typically one client per XView object. Each selection

rank is associated with each client—a separate client need not be created just to utilize other

selection ranks. However, only one client can be the holder of a particular selection rank at

any one time. If a client wishes to acquire the selection, the current selection holder must

yield the selection to the new requestor. The client becomes the new holder of the selection

and might provide any data it chooses.

A.2 Using the Selection Service

It is not necessary to create a selection service client just to query the holder of a selection or

to get its contents. Since this is the most common usage, most of this chapter is dedicated to

explaining this level of functionality. Creating a selection is typically used internally by

packages in the XView library or by applications that wish to create their own objects that

need to communicate via the selection service. Doing this is generally very intricate and

complicated and is beyond the scope of this manual.

Nevertheless, to understand how to create a selection service client, it is best to learn how to

request information from an existing client. Once you understand what to expect from a

selection, you can understand how to create a client that provides information from other

requests. Therefore, the bulk of the chapter addresses the process of querying for selections

already provided by XView packages or other X-based applications.

OPEN LOOK assigns to function keys the special functions COPY, CUT, and PASTE. The

function keys generate and correspond to the XView events ACTION_CUT, ACTION_COPY,

and ACTION_PASTE. An OPEN LOOK application checks the state of these keys and modifies

the selection rank accordingly. Note that it is the responsibility of the XView application

(more specifically, each XView package) to set the state of the server’s selection rank

according to the state of some function keys. Unless you are writing your own XView pack-

age (a topic that this book does not address), you need not concern yourself about it.

*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.

The Selection

Service

The Selection Service 637

Even though XView packages might query for the state of function keys, this does not inter-

fere with normal event processing. All events that your application has registered to receive

are not affected by the selection service. Note, however, that while the selection service

might react to the state of these function keys, any action you take as a result of these keys

might result in a dual action and might confuse the user. For example, if your application is

coded to change the font of a text subwindow in the event of an L8-up event, you will not

only get that event, but the selection service also gets it and will PASTE the contents of the

shelf selection.

Whenever using the selection service either as a client or to query the selection from another

client, application code must include the header file <xview/seln.h>. This file includes the

files <xview/sel_svc.h> and <xview/sel_attrs.h>, which provide external declarations of

available functions and data types.

A.3 Getting the Current Selection

Determining the current selection involves two steps: determining the holder of the current

selection and getting the actual selection data from the holder. To determine who is holding

the selection of a specified rank:

Seln_holder

selection_inquire(server, rank)

Xv_Server server;

Seln_rank rank;

The returned holder is used in other selection routines that allow you to access selection

data for that rank. For example, the call selection_ask() asks for the data held by the

holder of the selection. The form of the call is:

Seln_request *

selection_ask(server, holder,

attrs

)

Xv_Server server;

Seln_holder *holder;

<attribute-value list>

attrs

The holder in this case is the address of the holder returned from the call to

selection_inquire().

The server is important to all the selection service routines because it identifies the X server

in which the selection is associated. Because X applications can communicate with more

than one server, specifying different servers can result in getting different selections.

The Seln_rank specifies which selection type you want. Its value corresponds with the

four selection ranks outlined in the beginning of the chapter. However, there are six legal

values in this enumerated data type:

SELN_UNKNOWN This is an error value, not a value you would use as a parameter or

a legal or known rank.

SELN_CARET The caret selection is used with text subwindows and text panel

items. It is usually used to describe where the insertion point is

within the corresponding text stream of the object so there is no

638 XView Programming Manual

data associated with the caret selection. This selection type is not

very widely used.

SELN_PRIMARY The primary selection is the most widely used and is usually the

default type in most user interfaces and applications.

SELN_SECONDARY As noted earlier, the secondary selection is only used if the pri-

mary selection must not be removed or lost—or if it must remain

clearly visible (visually selected) on the screen.

SELN_SHELF The selection buffers are stored in files. Clients of the selection

service do not access these files; the selection service just uses

them as temporary storage for data. As noted, this is not a good

place to hold selections.

SELN_UNSPECIFIED When this rank is used, either the primary or the secondary

selection is used depending on the state of the appropriate function

keys. This is usually passed as the rank parameter to

selection_inquire().

selection_ask() returns a pointer to a Seln_request data structure. The function

goes out and asks the server for the selection associated with the rank described in the

holder parameter. All the information about the selection is held in this data structure.

The attribute-value list following the holder parameter describes the attributes of the

selection you are interested in.

Before we go on, let’s show an example program that illustrates what we have covered so far.

The simple program in Example A-1 has a panel button that prints the current primary

selection to the standard output. The selection can be held by any client on the server.

Example A-1. The simple_seln.c program

/*

* simple_seln.c -- print the primary selection by pressing the panel

* button. The selection may have originated from any window or

* application on the server.

*/

#include <stdio.h>

#include <xview/xview.h>

#include <xview/panel.h>

#include <xview/server.h>

#include <xview/seln.h>

Xv_Server server;

main(argc, argv)

char *argv[ ];

{

Frame frame;

Panel panel;

void exit();

int print_seln();

xv_init(XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

The Selection

Service

The Selection Service 639