ctrlsel.3

.Dd March 6, 2023
.Dt CTRLSEL 3
.Os
.Sh NAME
.Nm ctrlsel_filltarget ,
.Nm ctrlsel_request ,
.Nm ctrlsel_receive ,
.Nm ctrlsel_cancel ,
.Nm ctrlsel_setowner ,
.Nm ctrlsel_send ,
.Nm ctrlsel_disown ,
.Nm ctrlsel_dndwatch ,
.Nm ctrlsel_dndreceive ,
.Nm ctrlsel_dndclose ,
.Nm ctrlsel_dndown ,
.Nm ctrlsel_dndsend ,
.Nm ctrlsel_dnddisown
.Nd X11 selection ownership and request helper functions
.Sh SYNOPSIS
.In "X11/Xlib.h"
.In "control/ctrlsel.h"
.Ft void
.Fo "ctrlsel_filltarget"
.Fa "Atom target"
.Fa "Atom type"
.Fa "int format"
.Fa "unsigned char *buffer"
.Fa "unsigned long size"
.Fa "struct CtrlSelTarget *target_fill"
.Fc
.Ft "CtrlSelContext *"
.Fo "ctrlsel_request"
.Fa "Display *display"
.Fa "Window window"
.Fa "Atom selection"
.Fa "Time time"
.Fa "struct CtrlSelTarget targets[]"
.Fa "unsigned long ntargets"
.Fc
.Ft int
.Fo "ctrlsel_receive"
.Fa "CtrlSelContext *context"
.Fa "XEvent *event"
.Fc
.Ft void
.Fo "ctrlsel_cancel"
.Fa "CtrlSelContext *context"
.Fc
.Ft "CtrlSelContext *"
.Fo "ctrlsel_setowner"
.Fa "Display *display"
.Fa "Window window"
.Fa "Atom selection"
.Fa "Time time"
.Fa "Bool ismanager"
.Fa "struct CtrlSelTarget targets[]"
.Fa "unsigned long ntargets"
.Fc
.Ft int
.Fo "ctrlsel_send"
.Fa "CtrlSelContext *context"
.Fa "XEvent *event"
.Fc
.Ft void
.Fo "ctrlsel_disown"
.Fa "CtrlSelContext *context"
.Fc
.Ft "CtrlSelContext *"
.Fo "ctrlsel_dndwatch"
.Fa "Display *display"
.Fa "Window window"
.Fa "unsigned int actions"
.Fa "struct CtrlSelTarget targets[]"
.Fa "unsigned long ntargets"
.Fc
.Ft int
.Fo "ctrlsel_dndreceive"
.Fa "CtrlSelContext *"
.Fa "XEvent *event"
.Fc
.Ft void
.Fo "ctrlsel_dndclose"
.Fa "CtrlSelContext *context"
.Fc
.Ft "CtrlSelContext *"
.Fo "ctrlsel_dndown"
.Fa "Display *display"
.Fa "Window window"
.Fa "Window miniature"
.Fa "Time time"
.Fa "struct CtrlSelTarget targets[]"
.Fa "unsigned long ntargets"
.Fa "Window *receiver_ret"
.Fc
.Ft int
.Fo "ctrlsel_dndsend"
.Fa "CtrlSelContext *context"
.Fa "XEvent *event"
.Fc
.Ft void
.Fo "ctrlsel_dnddisown"
.Fa "CtrlSelContext *context"
.Fc
.Sh ARGUMENTS
.Bl -tag -width Ds
.It Fa "actions"
Specifies the supported drag-and-drop actions.
Its value should be a bitwise OR of supported actions:
.Ic "CTRLSEL_COPY" ,
.Ic "CTRLSEL_MOVE" ,
.Ic "CTRLSEL_LINK" ,
.Ic "CTRLSEL_ASK" ,
or
.Ic "CTRLSEL_PRIVATE" .
.It Fa "buffer"
Specifies the data of the selection in the target.
If the
.Fa "target_fill"
argument is for a selection to be owned,
.Fa buffer
should exist (not be freed) until the selection is lost or disowned.
If the
.Fa "target_fill"
argument is for a selection to be requested,
then any value (such as
.Ic "NULL" )
can be given, for the selection content is yet to be requested.
.It Fa context
Specifies the pointer to a
.Ft CtrlSelContext
structure containing the context of the selection request or ownership.
.It Fa display
Specifies the connection to the X server.
.It Fa "event"
Specifies the pointer to a
.Ft "XEvent"
to be filtered.
.It Fa "format"
Specifies the format of each member of the selection content converted into the target.
It should be either
.Ic "8"
.Pq Ft "char" ,
.Ic "16"
.Pq Ft "short" ,
or
.Ic "32"
.Pq Ft "long" .
This argument need only be set when the
.Fa "target_fill"
argument is for a selection to be owned (given to
.Fn "ctrlsel_setowner" ) ,
for the content type is already known.
If
.Fa "target_fill"
is for a selection to be requested (that is, given to
.Fn "ctrlsel_request" ) ,
then any value (such as
.Ic "0" )
can be given,
for the format is not known yet.
.It Fa "ismanager"
Specifies whether the selection whose ownership is being asked by
.Fn "ctrlsel_setowner"
is a manager selection.
.It Fa "miniature"
Specifies the window of the miniature (aka "icon") to follow the mouse pointer during a drag-and-drop (aka "dnd") operation.
This argument can be
.Ic "None" ,
in which case no miniature/icon will follow the pointer;
but that is discouraged,
for the user may not have a visual response of the drag-and-drop, if the mouse cursor theme does not support the dragging cursor.
.It Fa "ntargets"
Specifies the number of members of the
.Fa targets
array.
.It Fa receiver_ret
Returns the window that received the drop of a drag-and-drop operation
(or
.Ic None
if the operation was cancelled,
the user dropped on a non-dndaware window,
or an error occurred).
.It Fa "selection"
Specifies the atom identifying the requested selection (for
.Fn "ctrlsel_request" ) ,
or the selection to be owned (for
.Fn "ctrlsel_setowner" ) .
.It Fa "size"
Specifies the size, in bytes, of
.Fa "buffer" .
Ignored if the target is to be requested.
.It Fa "target"
Specifies the atom identifying a target which the selection can be converted to.
.It Fa "targets"
Specifies a pointer of
.Fa "ntargets"
structures of type
.Ft "struct CtrlSelTarget"
to be included in the
.Fa "context" .
.Fa "targets"
must be accessible (not freed) until the selection request or ownership is done;
that is, until
.Fn "ctrlsel_receive"
returns
.Ic "CTRLSEL_ERROR"
or
.Fn "ctrlsel_cancel"
is called, for selection requests; or until
.Fn "ctrlsel_send"
returns
.Ic "CTRLSEL_LOST"
or
.Fn "ctrlsel_disown"
is called, for selection ownerships.
.It Fa "target_fill"
Specifies the pointer to a
.Ft "struct CtrlSelTarget"
structure whose members will be defined.
.It Fa "time"
specifies the timestamp of the selection request (for
.Fn "ctrlsel_request" )
or the selection ownership (for
.Fn "ctrlsel_setowner" ) .
.It Fa "type"
Specifies the atom identifying the type of the content of the selection in the target.
It is usually the same atom as the target.
This argument need only be set when the
.Fa "target_fill"
argument is for a selection to be owned (that is, given to
.Fn "ctrlsel_setowner" ) ,
for the content is already converted into the target.
If
.Fa "target_fill"
is for a selection to be requested (that is, given to
.Fn "ctrlsel_request" ) ,
then any value (such as
.Ic "None" )
can be given, for the type is not known yet.
.It Fa "window"
Specifies the window requesting (for
.Fn "ctrlsel_request"
and
.Fn "ctrlsel_dndwatch" )
or willing to own (for
.Fn "ctrlsel_setowner"
and
.Fn "ctrlsel_dndown" )
the given
.Fa "selection" .
.El
.Sh DESCRIPTION
These functions and related data structures provide management of ownership and request of X11 selections, including for drag-and-drop operations.
In addition to the
.Fn "ctrlsel_filltarget"
function (used to set up
.Ft "struct CtrlSelTarget"
structures,
there are the following four triplets of functions that deal with the ownership and request of arbitrary selections and the drag-and-drop selection:
.Bl -bullet
.It
The
.Fn "ctrlsel_request" ,
.Fn "ctrlsel_receive" ,
and
.Fn "ctrlsel_cancel"
functions request the contents of a selection,
receive the requested contents,
and cancel the request, respectively.
The
.Fn "ctrlsel_receive"
and
.Fn "ctrlsel_cancel"
functions must only be called after
.Fn "ctrlsel_request"
with the
.Fa context
returned by it.
.It
The
.Fn "ctrlsel_setowner" ,
.Fn "ctrlsel_send" ,
and
.Fn "ctrlsel_disown"
functions make a window the owner of a selection,
send the selection contents to requestor clients,
and disown the selection ownership, respectively.
The
.Fn "ctrlsel_send"
and
.Fn "ctrlsel_disown"
functions must only be called after
.Fn "ctrlsel_setowner"
with the
.Fa context
returned by it.
.It
The
.Fn "ctrlsel_dndwatch" ,
.Fn "ctrlsel_dndreceive" ,
and
.Fn "ctrlsel_dndclose"
functions initiate the watching for dropped contents on a window,
receive dropped contents,
and cancel the watching, respectively.
The
.Fn "ctrlsel_dndreceive"
and
.Fn "ctrlsel_dndclose"
functions must only be called after
.Fn "ctrlsel_dndwatch"
with the
.Fa context
returned by it.
.It
The
.Fn "ctrlsel_dndown" ,
.Fn "ctrlsel_dndsend" ,
and
.Fn "ctrlsel_dnddisown"
functions initiate a drag-and-drop operation,
send the dropped content to a watching window,
and interrupts the drag-and-drop operation, respectively.
The
.Fn "ctrlsel_dndsend"
and
.Fn "ctrlsel_dnddisown"
functions must only be called after
.Fn "ctrlsel_dndown"
with the
.Fa context
returned by it.
.El
.Ss Target-handling functions
The
.Fn "ctrlsel_filltarget"
function fills in the members of the
.Fa "target_fill"
structure with the values given in as arguments and other values computed from those.
.Fa "target_fill"
could be initialized or assigned manually by the programmer; however it is recommended to use the
.Fn ctrlsel_filltarget
function instead because it both provides compile-time checking of whether all the members have been properly assigned,
and also compute and defines the
.Fn "nitems"
member, which is derived from the other ones.
.Ss Selection requesting functions
The
.Fn "ctrlsel_request"
function asks the
.Xr Xserver 1
represented by
.Fa "display"
to convert the
.Fa "selection"
into all the
.Fa "targets"
for the
.Fa "window" .
It returns a pointer to a newly allocated
.Ft CtrlSelContext
to be passed to the
.Fn "ctrlsel_receive"
and
.Fn "ctrlsel_cancel"
functions.
It returns NULL on error.
.Pp
The
.Fn "ctrlsel_receive"
function filters the X event pointed to by
.Fa "event" ,
checks whether it is related to the
.Fa context
returned by
.Fn "ctrlsel_request" ,
and receives part or all of the content of the requested selection into the requested targets.
One of the following enum constants is returned:
.Bl -tag -width Ds
.It Ic "CTRLSEL_NONE"
The event is not related to the request.
The caller can further process the event.
.It Ic "CTRLSEL_RECEIVED"
The selection have been successfully converted into all the targets.
All the
.Fa "buffer"
members of the
.Ft "struct CtrlSelTarget"
structures in the array given to
.Fn "ctrlsel_request"
have been allocated and set to the selection content in that target.
The
.Fa "bufsize" ,
.Fa "format" ,
.Fa "nitems" ,
and
.Fa "type"
members are set to the size in bytes of the content, format of the
content, number of items and type of the content, respectively.
The caller should not further process the event.
The caller can then use the
.Fa "buffer" ,
and must
.Xr free 3
it when done with it.
.It Ic CTRLSEL_INTERNAL
The selection has been partially converted into the targets.
The caller should not further process the event.
.It Ic CTRLSEL_ERROR
An error has occurred during the selection conversion.
The caller should not further process the event.
Any allocated
.Fa "buffer"
is freed by the function, so the caller should not free it.
.El
.Pp
The
.Fn "ctrlsel_cancel"
function cancels the selection conversion represented by the
.Fa "context" ,
terminates any incremental transference in progress,
and frees the context itself and any allocated buffer.
.Ss Selection ownership functions
The
.Fn "ctrlsel_setowner"
function asks the
.Xr Xserver 1
represented to by
.Fa "display"
to own the
.Fa "selection"
for the
.Fa "window" ,
so it can provide the contents of all
.Fa "targets" .
If the
.Fa "selection"
is a manager selection, the
.Fa "ismanager"
argument must be set to nonzero.
It returns a pointer to a newly allocated
.Ft CtrlSelContext
to be passed to the
.Fn "ctrlsel_send"
and
.Fn "ctrlsel_disown"
functions.
It returns NULL on error.
.Pp
The
.Fn "ctrlsel_send"
function filters the X event pointed to by
.Fa "event" ,
checks whether it is related to the
.Fa context
returned by
.Fn "ctrlsel_setowner" ,
and sends the converted selection to any requestor client.
One of the following enum constants is returned:
.Bl -tag -width Ds
.It Ic "CTRLSEL_NONE"
The event is not related to the ownership.
The caller can further process the event.
.It Ic "CTRLSEL_INTERNAL"
The selection is converted to a requestor client who have requested the selection.
The caller should not further process the event.
.It Ic "CTRLSEL_LOST"
The selection ownership has been lost.
The caller should not further process the event.
.El
.Pp
The
.Fn "ctrlsel_disown"
function cancels the selection ownership represented by the
.Fa "context" ,
terminates any incremental transference in progress, and frees the context itself.
This function does not free any buffer.
.Ss Drag-and-drop request functions
The
.Fn "ctrlsel_dndwatch"
function begins watching dropped content on
.Fa "window"
in the
.Xr Xserver 1
represented by
.Fa display .
The content must be on the specified
.Fa "targets"
and must be dropped by the specified
.Fa "actions" .
It returns a pointer to a
.Ft CtrlSelContext
to be passed to the
.Fn "ctrlsel_dndreceive"
and
.Fn "ctrlsel_dndclose"
functions.
It returns NULL on error.
This function should be called once, at program initialization.
.Pp
The
.Fn "ctrlsel_dndreceive"
function filters the X event pointed to by
.Fa "event" ,
checks whether it is related to the
.Fa context
returned by
.Fn ctrlsel_dndwatch ,
and receives part or all of the dropped content.
One of the following enum constants is returned:
.Bl -tag -width Ds
.It Ic CTRLSEL_NONE
The event is not related to the drop watch.
The caller can further process the event.
.It Ic CTRLSEL_RECEIVED
A content has been dropped into one of the targets.
The
.Fa buffer
member of one of the
.Ft struct CtrlSelTarget
structures in the array given to
.Fn ctrlsel_dndwatch
has been allocated and set to the dropped content in that target.
The
.Fa bufsize ,
.Fa format ,
.Fa nitems ,
.Fa type ,
and
.Fa action
members are set to the size in bytes of the content,
format of the content,
number of items,
type of the content, and
action that resulted on the drop, respectively.
The caller should not further process the event.
The caller can then use the
.Fa buffer ,
and must
.Xr free 3
it when done with it.
.It Ic CTRLSEL_INTERNAL
A drop has been partially converted into a target.
The caller should not further process the event.
.El
.Pp
The
.Fn ctrlsel_dndclose
function cancels the watch for drops represented by
.Fa context ,
terminates any incremental transference in progress,
and frees the context itself and any allocated buffer.
.Ss Drag-and-drop ownership functions
The
.Fn ctrlsel_dndown
function asks the
.Xr Xserver 1
represented to by
.Fa display
to own the drag-and-drop selection for
.Fa window ,
so it can provide the contents of all
.Fa targets .
This function blocks until the user drops the dragged content
(by releasing a mouse button),
or cancels the drag-and-drop operation (by pressing ESC).
If the given
.Fa miniature
window is not
.Ic None ,
the window is mapped, raised and moved around to follow the user's mouse pointer.
It returns a pointer to a newly allocated
.Ft CtrlSelContext
to be passed to the
.Fn ctrlsel_dndsend
and
.Fn ctrlsel_dnddisown
functions.
.Pp
If the pointer
.Fa receiver_ret
is not
.Ic NULL ,
it stores in that address the window that received the drop of the drag-and-drop operation
(or
.Ic None
if the operation was cancelled,
the user dropped on a non-dndaware window,
or an error occurred).
Note that the receiver window can be the
.Fa window
that owns the drag-and-drop selection itself
(a case known as
.Em self-drop ,
where the user drops something from a window into the same window).
When a self-drop occurs, the drag-and-drop operation is over,
because there is no need to send the content to another client
(the current client already has access to the content);
in this case
.Fn ctrlsel_dndown
returns NULL.
.Pp
The
.Fn ctrlsel_dndsend
function
filters the X event pointed to by
.Fa event ,
checks whether it is related to the
.Fa context
returned by
.Fn ctrlsel_dndown ,
and sends the dropped content to the window it was dropped on.
One of the following enum constants is returned:
.Bl -tag -width Ds
.It Ic CTRLSEL_NONE
The event is not related to the drag-and-drop operation.
The caller can further process the event.
.It Ic CTRLSEL_LOST
The drag-and-drop ownership has been lost.
The caller should not further process the event.
.It Ic CTRLSEL_SENT
The content was fully sent to the window it was dropped on.
The caller should not further process the event.
.It Ic CTRLSEL_INTERNAL
The content is being sent to the window it was dropped on.
The caller should not further process the event.
.El
.Pp
The
.Fn ctrlsel_dnddisown
function cancels the transference of the dropped content represented by the
.Fa context ,
and frees the context itself.
This function does not free any buffer.
.Sh STRUCTURES
The
.Ft "struct CtrlSelTarget"
structure contains:
.Bd -literal -offset indent
struct CtrlSelTarget {
	Atom            target;
	Atom            type;
	int             format;
	unsigned int    action;
	unsigned long   nitems;
	unsigned long   bufsize;
	unsigned char  *buffer;
};
.Ed
.Pp
A
.Ft "struct CtrlSelTarget"
structure
could be set manually by the programmer; however it is recommended to use the
.Fn ctrlsel_filltarget
as explained earlier.
The structure members must be  as follows:
.Bl -tag -width Ds
.It Fa "action"
The action that resulted on the drop of a content by a drag-and-drop operation.
Its value is equal to one of the supported actions:
.Ic "CTRLSEL_COPY" ,
.Ic "CTRLSEL_MOVE" ,
.Ic "CTRLSEL_LINK" ,
.Ic "CTRLSEL_ASK" ,
or
.Ic "CTRLSEL_PRIVATE" .
This member is only set by the
.Fn ctrlsel_dndreceive
function.
.It Fa "target"
The atom identifying the target.
Its value is either defined in
.In "X11/Xatom.h"
or obtained from the
.Xr XInternAtom 3
or
.Xr XInternAtoms 3
functions.
.It Fa "type"
The atom identifying the type of the target content.
Its value is usually the same as
.Fa "target" ,
but not always (it depends on the target).
Its value is either defined in
.In "X11/Xatom.h"
or obtained from the
.Xr XInternAtom 3
or
.Xr XInternAtoms 3
functions.
.It Fa "format"
The format of each member of the target content.
It should be
.Ic "8"
.Pq Ft "char"
for most
.Fa types
of targets.
Exceptions are types like
.Ic "XA_ATOM"
and
.Ic "XA_WINDOW" ,
which require the
.Ic "32"
.Pq Ft "long"
format; and types for width, height or RGB color values, which require the
.Ic "16"
.Pq Ft "short"
format.
.It Fa "nitems"
The number of items in
.Fa "buffer"
according to the target
.Fa "format".
If format is
.Ic "8" ,
its value is the same as
.Fa "bufsize" .
If the format is
.Ic "16"
or
.Ic "32" ,
it is the number of
.Ft "short"
or
.Ft "long"
(either signed or unsigned) elements in the buffer, respectively;
that is, it is equal to
.Fa bufsize
divided by
.Ic "sizeof(short)"
or
.Ic "sizeof(long)" .
.It Fa "bufsize"
The size in bytes of
.Fa "buffer" .
.It Fa "buffer"
The buffer containing the selection content converted into
.Fa "target" .
.El
.Sh RETURN VALUES
Upon error,
the
.Fn "ctrlsel_request"
and
.Fn "ctrlsel_setowner"
functions return zero; and the
.Fn "ctrlsel_receive"
function returns
.Ic "CTRLSEL_ERROR" .
.Sh EXAMPLES
The following is an example of the implementation of a function requesting the contents of the primary selection into two targets.
The contents of the selection must be received in a loop because the content can be too long for a single transference.
If the request is triggered by an event (for example, the user pressed the mouse's middle button), the variable
.Fa "time"
must be the timestamp of the event that caused it
(for example, in a
.Xr XButtonEvent 3
event).
If the request is not triggered by an event, the value
.Ic "CurrentTime"
must be given instead.
.Bd -literal -offset indent
CtrlSelContext *context;
struct CtrlSelTarget targets[2];
XEvent event;
Display *display;
Window window;
Atom utf8, html;
Time time;

/* step 0: fill targets */
utf8 = XInternAtom(display, "UTF8_STRING", False);
html = XInternAtom(display, "text/html", False);
ctrlsel_filltarget(utf8, utf8, 0, NULL, 0, &targets[0]);
ctrlsel_filltarget(html, html, 0, NULL, 0, &targets[1]);

/* step 1: request selection contents */
context = ctrlsel_request(display, window, XA_PRIMARY,
                          time, targets, 2);
if (context == NULL) {
	fprintf(stderr, "could not request selection");
	return;
}

/* step 2: receive selection contents */
for (;;) {
	(void)XNextEvent(display, &event);
	switch (ctrlsel_receive(context, &event)) {
	case CTRLSEL_NONE:
		/* call event handler */
		break;
	case CTRLSEL_RECEIVED:
		goto done;
	case CTRLSEL_INTERNAL:
		continue;
	case CTRLSEL_ERROR:
		fprintf(stderr, "warning: could not get selection");
		goto error;
	}
}

/* step 3: process selection contents; and free them */
done:
	printf("plain text: %.*s\n",
	       targets[0].bufsize,
	       targets[0].buffer);
	printf("html text:  %.*s\n",
	       targets[1].bufsize,
	       targets[1].buffer);
	free(targets[0].buffer);
	free(targets[1].buffer);

/* step 4: free the selection context */
error:
	ctrlsel_cancel(context);
	context = NULL;
.Ed
.Pp
The following is an example of the implementation of a function asking for the ownership of the primary selection with two targets.
The contents of the selection must be sent to requestors in a loop,
because other clients can request the selection asynchronously at any time.
If the ownership is triggered by an event (for example, the user selected a text with the mouse), the variable
.Fa time
must be the timestamp of the event that caused it (for example, in a
.Xr XButtonEvent 3
event).
If the ownership is not triggered by an event, the value
.Ic CurrentTime
must be given instead.
.Bd -literal -offset indent
CtrlSelContext *context;
struct CtrlSelTarget targets[2];
XEvent event;
Display *display;
Window window;
Atom utf8, html;
char *plain, *markd;
Time time;

/* step 0: fill targets */
plain = "Hello World!"
markd = "<p>Hello <i>World</i>!</p>"
utf8 = XInternAtom(display, "UTF8_STRING", False);
html = XInternAtom(display, "text/html", False);
ctrlsel_filltarget(utf8, utf8, 8, plain, strlen(plain), &targets[0]);
ctrlsel_filltarget(html, html, 8, markd, strlen(markd), &targets[1]);

/* step 1: ask for selection ownership */
context = ctrlsel_setowner(display, window, XA_PRIMARY,
                           time, 0, targets, 2);
if (context == NULL) {
	fprintf(stderr, "warning: could not own selection");
	return;
}

/* step 2: provide selection contents */
for (;;) {
	(void)XNextEvent(display, &event);
	switch (ctrlsel_send(context, &event)) {
	case CTRLSEL_NONE:
		/* call event handler */
		break;
	case CTRLSEL_INTERNAL:
		continue;
	case CTRLSEL_LOST:
		break;
	}
}

/* step 3: free the contents */
ctrlsel_disown(context);
context = NULL;
.Ed
.Sh SEE ALSO
.Xr X 1 ,
.Xr xclipd 1
.Rs
.%Q "X Consortium Standard"
.%B "Xlib - C Language X Interface"
.Re
.Rs
.%Q "X Consortium Standard"
.%B "Inter-Client Communication Conventions Manual"
.Re