xtconvertse(3x) [hpux man page]

XtConvertSe(3X) 														   XtConvertSe(3X)

NOTE

       You have selected a name that conflicts with one or more
       other names.  To display the manpage you want, enter the
       man command again with one of the following names.

If you want:		     Enter the name:
----------------------------------------------

XtConvertSelectionIncrProc   XtConvertSA
XtConvertSelectionProc	     XtConvertSB

																   XtConvertSe(3X)

XtConvertSelectionProc()												  XtConvertSelectionProc()

Name
  XtConvertSelectionProc - interface definition for a procedure to return requested selection data.

Synopsis
  typedef Boolean (*XtConvertSelectionProc)(Widget, Atom *, Atom *, Atom *, XtPointer *, unsigned long *, int *);
	 Widget w;
	 Atom *selection;
	 Atom *target;
	 Atom *type_return;
	 XtPointer *value_return;
	 unsigned long *length_return;
	 int *format_return;

Inputs
  w	      Specifies the widget that currently owns the selection.

  selection   Specifies the atom that describes the selection requested (usually XA_PRIMARY or XA_SECONDARY).

  target      Specifies the type of information requested about the selection (FILENAME, TEXT, or XA_WINDOW, for example).

Outputs
  type_return Returns the property type of the converted value of the selection.  (Both FILENAME and TEXT might have property type XA_STRING,
	      for example.)

  value_return
	      Returns the address of the converted value of the selection.  The selection owner is responsible for allocating this storage.

  length_return
	      Returns the length of the value in value_return, in units as specified by format_return.

  format_return
	      Returns the size in bits of each of the length_return elements of value_return.  Must be 8, 16, or 32; this information  allows
	      the X server to byte-swap the data if necessary.

Returns
  True if the conversion is successful; False otherwise.

Description
  An  XtConvertSelectionProc  is  registered  in a call to XtOwnSelection() when a client requests to become the owner of a selection.	It is
  called when the value of the selection is requested.

  If an XtConvertSelectionProc cannot convert the selection data to the requested target type, it should return False.	Otherwise, it  should
  convert  the value, allocating memory for it if necessary.  It should store the type of the converted data (which is generally not the same
  as target) in type_return, store the address of the converted value in value_return, store the  number  of  blocks  of  converted  data  in
  length_return, store the size of each of those blocks of converted data in format_return, and return True.

  If  an XtSelectionDoneProc was registered with the XtConvertSelectionProc, then this procedure will be called when the requestor has copied
  the converted data, and should free any memory allocated for that data.  If no XtSelectionDoneProc was registered, then the Intrinsics will
  automatically free the returned value by calling XtFree().

  Each	XtConvertSelectionProc	should	respond to target value TARGETS by returning a value containing the list of the targets they are pre-
  pared to convert their selection into.  The list of targets should be an array of interned Atoms, and type_return should be XA_ATOM.

  An	  XtConvertSelectionProc      will	not	 be	 called      with      a      target	  of	  MULTIPLE	or	 TIME
  STAMP  (see  Section 2.6.2 of the Inter-Client Communications Conventions Manual, Appendix L in Volume Zero).  The Intrinsics automatically
  break a MULTIPLE request into a series of calls to the procedure, and automatically respond to a TIMESTAMP request using the time passed to
  XtOwnSelection().

Usage
  Most	widgets  that  display data of any sort should make that data selectable by the user, and should call XtOwnSelection() with an XtCon-
  vertSelectionProc when data is selected by the user.

  Although it is usually widgets that handle selections, there are times when an application might want to export selected data.  A  calcula-
  tor  program	might  have  a	menu item labeled "Cut", for example, which would call XtOwnSelection() to make the currently displayed value
  available for pasting.  (It would probably also have a "Paste" command that  would  call  XtGetSelectionValue()  to  obtain  the  currently
  selected value and use it, if it is a number.)

  An XtConvertSelectionProc transfers the selection value in a single block, and relies on the Intrinsics to break that block up and reassem-
  ble it as necessary if it is larger than the maximum size for a single transfer to the X server.  This procedure and	the  XtOwnSelection()
  function  that  registers  it  are part of the Intrinsics atomic selection transfer mechanism.  In Release 4 and later, the Intrinsics also
  support an incremental transfer mechanism which allows the selection owner to return the selection value a piece at a time.  If there is  a
  large  amount of selected data, the incremental interface means that it does not have to be copied all at once-on systems with limited mem-
  ory, this can be important.  Also, some selections, such as disjoint pieces of text in a text widget, are  more  naturally  transferred  in
  separate pieces.  See XtOwnSelectionIncremental(1) and XtConvertSelectionIncrProc(2) for more information.

  The  Xmu  function  XmuConvertStandardSelection()  converts  the  selection  to  the following standard targets: CLASS, CLIENT_WINDOW, DEC-
  NET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS, TARGETS, TIMESTAMP, and USER.  It is used in the example shown below.  See Section 2.6.5
  of  the  Inter-Client  Communications Conventions Manual for the meaning of these standard targets.  See XmuConvertStandardSelection(6) for
  more information.

  When working with selections, you will have to work with Atoms.  Many standard Atoms are defined in <X11/Xatom.h>.  Those that are not (for
  example,  TARGETS)  may  be interned explicitly as Atoms by calling the Xlib function XInternAtom().	The Xmu library provides an alternate
  function, XmuInternAtom(), which caches Atoms on the client side.  Additionally, the header <Xmu/Atoms.h> defines a number of macros,  such
  as XA_TARGETS(dpy), which call XmuInternAtom() and take a Display pointer as their single argument.

Example
  The example XtConvertSelectionProc below is from the client xclipboard.  It can be easily adapted for use by most widgets and applications.
  Note the use of predefined Atoms and the Xmu Atom macros.  XmuConvertStandardSelection() is used to convert to the standard  target  types,
  and  also  (when  the  target  is TARGETS) to return a list of those standard types that it supports.  This list is then augmented with the
  types supported explicitly by the procedure.

     #include <X11/Xatom.h>
     #include <X11/Xmu/Atoms.h>
     #include <X11/Xmu/StdSel.h>

     static Boolean ConvertSelection(w, selection, target,
				     type, value, length, format)
	 Widget w;
	 Atom *selection, *target, *type;
	 XtPointer *value;
	 unsigned long *length;
	 int *format;
     {
	 Display* d = XtDisplay(w);
	 XSelectionRequestEvent* req =
	     XtGetSelectionRequest(w, *selection, (XtRequestId)NULL);

	 if (*target == XA_TARGETS(d)) {
	     Atom* targetP;
	     Atom* std_targets;
	     unsigned long std_length;
	     XmuConvertStandardSelection(w, req->time, selection, target, type,
				       (caddr_t*)&std_targets, &std_length, format);
	     *value = XtMalloc(sizeof(Atom)*(std_length + 5));
	     targetP = *(Atom**)value;
	     *targetP++ = XA_STRING;
	     *targetP++ = XA_TEXT(d);
	     *targetP++ = XA_LENGTH(d);
	     *targetP++ = XA_LIST_LENGTH(d);
	     *targetP++ = XA_CHARACTER_POSITION(d);
	     *length = std_length + (targetP - (*(Atom **) value));
	     bcopy((char*)std_targets, (char*)targetP, sizeof(Atom)*std_length);
	     XtFree((char*)std_targets);
	     *type = XA_ATOM;
	     *format = 32;
	     return True;
	 }

	 if (*target == XA_LIST_LENGTH(d)
	     *target == XA_LENGTH(d))
	 {
	     long * temp;

	     temp = (long *) XtMalloc(sizeof(long));
	     if (*target == XA_LIST_LENGTH(d))
	       *temp = 1L;
	     else		     /* *target == XA_LENGTH(d) */
	       *temp = (long) TextLength (text);

	     *value = (caddr_t) temp;
	     *type = XA_INTEGER;
	     *length = 1L;
	     *format = 32;
	     return True;
	 }

	 if (*target == XA_CHARACTER_POSITION(d))
	 {
	     long * temp;

	     temp = (long *) XtMalloc(2 * sizeof(long));
	     temp[0] = (long) 0;
	     temp[1] = TextLength (text);
	     *value = (caddr_t) temp;
	     *type = XA_SPAN(d);
	     *length = 2L;
	     *format = 32;
	     return True;
	 }

	 if (*target == XA_STRING
	   *target == XA_TEXT(d)
	   *target == XA_COMPOUND_TEXT(d))
	 {
	     extern char *_XawTextGetSTRING();
	     if (*target == XA_COMPOUND_TEXT(d))
		 *type = *target;
	     else
		 *type = XA_STRING;
	     *length = TextLength (text);
	     *value = _XawTextGetSTRING((TextWidget) text, 0, *length);
	     *format = 8;
	     return True;
	 }

	 if (XmuConvertStandardSelection(w, req->time, selection, target, type,
					 (caddr_t *)value, length, format))
	     return True;

	 return False;
     }

See Also
  XtGetSelectionValue(1), XtOwnSelection(1),
  XtConvertSelectionIncrProc(2), XtSelectionDoneProc(2),
  XmuConvertStandardSelection(6).

Xt - Selections 													  XtConvertSelectionProc()