Query: xtconvertsb
OS: hpux
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
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()