Example 18-4. Sample reply procedure
SelectionReplyProc (continued)
if (target == ATOM(server, "STRING")) {
static int incr = False;
if (type == ATOM(server, "INCR")) {
textsw_insert(textsw, "Contents of the selection:\n", 27);
incr = True;
}
else
if (length) {
if (!incr)
textsw_insert(textsw, "Contents of the selection:\n", 27);
textsw_insert(textsw, (char *)value, length);
textsw_insert(textsw, "\n", 1);
}
else
incr = False;
}
else
if (target == ATOM(server, "DELETE")) {
textsw_insert(textsw, "The Selection has been deleted\n", 31);
}
textsw_insert(textsw, LINE, strlen(LINE));
}
18.2.5.1 Handling selection reply procedure errors
If the selection conversion fails, and you are using a non-blocking request, the reply proce-
dure is called with replyValue set to an error code and length set to SEL_ERROR. The reply
procedure error codes are defined in sel_pkg.h and shown in Table 18-2.
If the selection conversion fails, and you are using a blocking request without a reply proce-
dure defined, the xv_get() returns with the length argument set to SEL_ERROR, format set
to 0, and a NULL value is returned. If a reply procedure is defined, its replyValue argument is
set to one of the error codes shown in Table 18-2.
Table 18-2. Error Codes
Code Description
SEL_BAD_CONVERSION If the conversion is refused by the selection holder or there
is no holder of the selection, this value is returned. This
may mean that there is no owner for the selection, that the
owner does not support the conversion implied by target, or
that the server did not have sufficient space.
SEL_BAD_TIME The SelectionNotify time does not match the package time
value.
SEL_BAD_WIN_ID The SelectionNotify requestor ID does not match the pack-
age requestor ID.
408 XView Programming Manual
Table 18-2. Error Codes (continued)
Code Description
SEL_BAD_PROPERTY Obsolete.
SEL_BAD_PROPERTY_EVENT Obsolete.
SEL_PROPERTY_DELETED Obsolete.
SEL_TIMEDOUT Selection timed out.
A sample application-defined errror routine, for a non-blocking error handler, is shown in
Example 18-5. Code similar to this should be invoked to handle errors in your selection
application.
Example 18-5. Sample selection reply error handler
SelectionError(sel, target, errorCode)
Selection_requestor sel;
Atom target;
int errorCode;
{
Atom rank;
char *rank_string;
char *target_string = (char *)xv_get(server,
SERVER_ATOM_NAME, target);
char msg[100];
rank = (Atom)xv_get(sel, SEL_RANK);
rank_string = (char *)xv_get(server, SERVER_ATOM_NAME, rank);
sprintf(msg, "Selection failed for rank %s on target %s: ",
rank_string, target_string);
textsw_insert(textsw, msg, strlen(msg));
switch(errorCode) {
case SEL_BAD_CONVERSION :
textsw_insert(textsw, "Conversion Rejected",
strlen("Conversion Rejected"));
break;
case SEL_BAD_TIME:
textsw_insert(textsw, "Bad Time Match",
strlen("Bad Time Match"));
break;
case SEL_BAD_WIN_ID:
textsw_insert(textsw, "Bad Window Match",
strlen("Bad Window Match"));
break;
case SEL_TIMEDOUT:
textsw_insert(textsw, "Timeout", strlen("Timeout"));
break;
}
}
Selections
Selections 409
18.2.6 If the Selection is Lost (Selection Owner)
If the owner loses the selection, because someone else acquired the same rank selection, the
lose procedure is called. The selection-owner object attribute SEL_LOSE_PROC specifies the
selection owner’s lose procedure. This procedure is called by the toolkit, to inform the
selection owner that it has lost the ownership of the given selection. The form of the lose
procedure is shown below:
void
lose_proc( sel )
Selection_owner sel;
sel specifies the selection-owner object.
One example of lose_proc() usage is for unhighlighting the highlighted text in a
textsw. The code fragment below shows a selection lose procedure that simply informs the
user that the selection was lost.
void
SelectionLoseProc(sel)
Selection_owner sel;
{
xv_set(frame, FRAME_LEFT_FOOTER, "Lost Selection...", NULL);
}
18.2.7 Cleanup – When the Selection Completes (Selection Owner)
The attribute
SEL_DONE_PROC
specifies the application-defined done procedure that is called
by the toolkit when a selection request has successfully completed. It is called once follow-
ing each successful transfer of data to the requestor. Thus, if the selection request is a multi-
ple, or results in an incremental reply, the done procedure is called more than once. This pro-
cedure can be used to deallocate any selection replies allocated in the conversion procedure.
void
done_proc( sel, replyBuff, target )
Selection_owner sel;
Xv_opaque replyBuff;
Atom target;
The argument sel specifies the selection-owner object. replyBuff specifies the address which
contains the converted data. target specifies the target type returned by the conversion pro-
cedure.
410 XView Programming Manual
Example 18-6 shows a sample done procedure.
Example 18-6. Sample done procedure
SelectionDoneProc
void
SelectionDoneProc(sel, data, target)
Selection_owner sel;
Xv_opaque data;
Atom target;
{
if (target == ATOM(server, "STRING"))
free((char *)data);
}
18.3 How Selection Works (With a Selection Item)
This section describes using a selection item that can eliminate the selection owner’s need for
a conversion procedure. This may simplify the programmer’s job of implementing a
selection transfer.
Selection items are good to use for conversions that involve static data—data that will not
change over the lifetime of the selection. Do not use a selection item for selections where the
data associated with the selection is not known until the selection request is received (using a
selection conversion procedure is best for this case). Also, do not use a selection item for any
selection conversion that has side effects (for example, a delete request).
Below is a brief overview of the steps that take place during a single transfer of data from
one XView application to another using a selection item. We’ll assume we have two applica-
tions, application A and application B, either of which can operate as the owner or the reques-
tor.
1. (Owner side.) The user makes a selection in application A and the application highlights
the selection.
2. (Owner side.) The user may pre-register a conversion for a particular target by creating a
selection-item object and setting its attributes.
3. (Owner side.) In the XView Selection package, nothing further happens until an event of
interest is detected, for example, an ACTION_COPY event. At this time, a selection item
may claim ownership of the current selection in application A. Also at this time,
selection data may be attached to the selection-item object.
4. (Requestor side.) The user pastes the selected data into application B, causing an
ACTION_PASTE event to occur.
5. (Requestor side.) The ACTION_PASTE event may cause the Selection Requestor to make
a non-blocking request to receive the selected data into application B.
Selections
Selections 411
6. (Owner side.) When there is a match between a selection-item object’s target type, and a
requested target, the selection package converts and sends the selection data to the
selection requestor. XView internally handles the data conversion by calling the pack-
age’s default conversion procedure sel_convert_proc().
7. (Requestor side.) Once the data conversion has completed (either successfully or unsuc-
cessfully), the application-defined reply procedure is invoked. The data may displayed in
application B (if the conversion routine was successful) or the user may simply be given
some indication that data was received. Other possibilities include: 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.
8. (Owner side.) Once the selection transfer is complete, an application-defined “done” pro-
cedure may be called by the selection owner. The done procedure may be used to free the
memory associated with the selection, or to perform other cleanup that is required.
9. (Owner side.) If another application acquires the selection, application A’s “lose” proce-
dure is called. This procedure is used to handle notification of loosing selection owner-
ship. It tells the selection owner (application A) that it has lost ownership of the
selection. For example, the lose procedure might unhighlight text that was previously
selected and highlighted.
18.3.1 The Selection Item
The first task for the application that is to become the selection owner, using a selection-item
object, is to pre-register a conversion or several conversions. Below, we describe this step in
detail. Also, the selection needs to be marked. For example, when the pointer is placed over
text in a canvas, an
ACTION_SELECT should highlight the selection. While LOC_DRAG occurs,
the highlight would be extended over the selection.
After the user makes a selection and it is marked, the application waits to receive an event of
interest. For example, in a text subwindow, the act of selecting an item causes the primary
rank to be acquired. 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).
With a selection item, applications perform three steps to become the selection owner:
1. A Selection_owner object must be created using xv_create() (assuming a previ-
ously created selection-owner object is not being re-used.) A selection-item object is
created and its attributes are set.
2. The selection must be acquired.
3. The selection data is associated with the selection item.
412 XView Programming Manual

Get Volume 7A: XView Programming Manual now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.