This chapter describes the VkCutPaste class, which provides copy, paste, drag, and drop capabilities. Figure 10-1 shows the inheritance graph for VkCutPaste.
The VkCutPaste class provides a simple C++ API that helps developers add inter-application Copy, Paste, Drag, and Drop capabilities to their applications easily, and with little or no worrying about the complex protocols of Motif and the X Window System. However, developers should be familiar with the style guidelines covered in the Inter-Client Communication Conventions Manual, IRIX Interactive Desktop User Interface Guidelines, and IRIX Interactive Desktop Integration Guide in order to provide a consistent look and feel in their applications.
Although it is called VkCutPaste, this class does not provide a specific cut function. However, a cut can be implemented in virtually all programs by calling the copy functions, followed by calling a delete function specific to your program.
The VkCutPaste class uses the Xt Intrinsics and Motif to implement a standard X Selection ICCCM compliant communication, so your application must link with those libraries to use this API. VkCutPaste does not require other parts of ViewKit, and can be used in a standard Motif application.
If you wish to examine a sample program using VkCutPaste, you can find one at /usr/share/src/ViewKit/CutPasteDragDrop/cutpaste1.c++.
VkCutPaste supports both the Primary Transfer Model and the Clipboard Transfer Model (see Chapter 7, “Interapplication Data Exchange,” in the IRIX Interactive Desktop Integration Guide for more information on these transfer models). PRIMARY refers to copying data by highlighting it using the mouse. When the middle mouse button is clicked, the data is pasted to the current location of the mouse pointer. CLIPBOARD refers to copying data by using a menu selection (for instance, Copy in an Edit menu) or a keyboard accelerator (Ctrl+c). The user must use another menu selection (for example, Paste in an Edit menu) or keyboard accelerator (Ctrl+v) to paste the data at the desired location.
The behavior of the PRIMARY and CLIPBOARD selections depend entirely on how you choose to implement them. VkCutPaste does not dictate any particular behavior. However, by custom, data on the CLIPBOARD selection tends to be more permanent. It normally remains even if the original data is cut or no longer selected, and even if new data has since been selected. It generally is cleared only if the user makes another selection, and then uses a menu selection or keyboard accelerator to place the new selection on the clipboard.
Also by custom, data on the PRIMARY selection tends to be more transient. It normally is replaced when different data is highlighted. Depending on how you implement the PRIMARY selection, it may also be cleared when the selected data is cut or no longer highlighted.
Consult the Inter-Client Communication Conventions Manual, IRIX Interactive Desktop User Interface Guidelines, and IRIX Interactive Desktop Integration Guide for style guidelines.
The following are the VkCutPaste constructor and destructor.
In order to use the copy and paste or drag and drop capabilities, you must instantiate the VkCutPaste class in your program (probably at program start-up). You can do this with the following two lines of code, where someWidget is any widget in your Motif or ViewKit program that will be valid during the lifetime of the VkCutPaste class:
#include <Vk/VkCutPaste.h> VkCutPaste *cnp = new VkCutPaste(someWidget); |
For most purposes, VkCutPaste::clear(), VkCutPaste::putCopy(), and VkCutPaste export() are the only functions necessary to implement a copy capability. VkCutPaste::registerLoseSelection() handles the occasions when your application loses ownership of one of the selections.
The following code fragment, which would appear in a menu callback, demonstrates the use of these copying functions. In this case, the user has highlighted an XPM image and selected Copy from the Edit menu:
extern VkCutPaste *cnp; extern XtPointer image; // pointer to XPM image buffer extern unsigned long numBytes; // number of bytes of image data Atom xaClipboard = XmInternAtom(dpy, “CLIPBOARD”, False); // get clipboard atom Atom xaXPM = XmInternAtom(dpy, “XPM”, False); // get XPM atom cnp->clear(xaCLIPBOARD); // clear clipboard cnp->putCopy(xaCLIPBOARD, xaXPM, image, numBytes); // make copy of XPM image cnp->export(xaCLIPBOARD); // make data available |
Once this code has run, any application on your desktop that has implemented the standard X Window Copy and Paste protocol can paste the XPM image.
To make this image available on the PRIMARY selection, you simply substitute XA_PRIMARY for xaCLIPBOARD.
In most cases, the recommended function for pasting data into an application is VkCutPaste::importImmediate(). In some rare instances, however, you may need to use VkCutPaste::import().
| importImmediate() |
Imports Copy and Paste data from any ICCCM client. This function blocks until the data is retrieved. The selection is either “CLIPBOARD” or “PRIMARY”. The interestList is an array of targets this application accepts, in order of preference. For example, interestList[0] might be XPM, interestList[1] might be GIF_89, and interestList[2] might be STRING. interestListLen would then be 3. For a list of registered targets, see the VkCutPaste(3x) reference page. importImmediate() accepts any target on the interestList or any target that can be converted to one of the targets on the list (see “Using Data Type Converters” for more information on data type conversion). The function returns an XtPointer to the data or a NULL pointer (meaning that none of the requested targets were available). In the above example, if an acceptable target were found, targetRet would be XPM, GIF_89, or STRING. importImmediate() makes a copy of the interestList, so you can free the memory immediately after this call completes. Since this function uses its own secondary event loop, some clients might want to avoid this call. | |||
| import() | void import(Atom selection,
Acts like importImmediate() except that it is non-blocking and requires a callback. For instance, your application could call importimmediate() with an interestList containing XPM, GIF_89, and STRING. If at least one of those targets is available, then importProc is called with data set to a valid XtPointer. If none of the acceptable targets are available, importProc is called with data set to NULL. Since import() makes a copy of the interestList, you can free the memory immediately after this call completes, even if the importProc has not yet been called. The prototype for the ImportCallbackProc is as follows:
|
The following code sample, which would appear in a menu callback, illustrates the paste capability. In this example, the application accepts a GIF image or an XPM image (your list of acceptable formats can be as long as you like; this example just happens to use two). The user has selected Paste from the Edit menu.
XtPointer image;
unsigned long numBytes;
Atom xaClipboard = XmInternAtom(dpy, “CLIPBOARD”, False);
Atom xaGIF_89 = XmInternAtom(dpy, “GIF_89”, False);
Atom xaXPM = XmInternAtom(dpy,”XPM”, False);
Atom interestList[2];
interestList[0] = xaGIF_89;
interestList[1] = xaXPM;
int numItemsInList = 2;
image = cnp->importImmediate(xaCLIPBOARD, interestList, numItemsInList,
&targetRet, &numBytes);
if (image == NULL)
printf(“No images available”);
else if (targetRet ==xaGIF_89)
printf(“GIF image received”);
else if (targetRet == xaXPM)
printf(“XPM image received”);
|
The image that is returned should eventually be freed as follows:
XtFree(image); |
The VkCutPaste class provides two dragging functions. VkCutPaste::dragAwayCopy() are sufficient for most needs. The advanced programmer may want more control, however, and so may wish to use VkCutPaste::dragAwayCopyExtended().
| dragAwayCopy() |
Drags away data from the current application. You can free data immediately after calling this function, because dragAwayCopy() makes a copy of the data for its own use. The XEvent should be the ButtonPress event that initiated the drag. The optional dragAwayProc is called after the drag completes. One of the parameters to dragAwayProc indicates if the drag was successful or not. dragAwayCopy() returns the DragContext created for this drag and drop transaction (see the XmDragStart(3X) reference page). The prototype for the DragAwayCallbackProc is as follows:
| |||
| dragAwayCopyExtended() |
Does exactly what dragAwayCopy() does, but provides more options for the advanced programmer. For example, you could specify the drag away data as more than one target (it should be the same conceptual object, just in different formats, like GIF and XPM format data of the same image). You could also use this function to create various drag icons by specifying those parameters in the args argument. args and numArgs are passed off to XmDragStart(). Several args are not allowed: XmNconvertProc, XmNdragOperations, XmNexportTargets, XmNnumExportTargets, and XmNclientData. See the XmDragContext(3X) reference page for more information on other, valid arguments. The Motif Drop Copy protocol (XmDROP_COPY) is the only drag-and-drop operation that the VkCutPaste class supports. dragAwayCopyExtended() returns the DragContext created for this drag-and-drop transaction (see the XmDragStart(3X) reference page). The following is the prototype for the DragAwayCallbackProc:
|
The following code sample illustrates dragging. The user has just clicked a mouse button on an XPM image and has begun dragging it out of your application:
extern VkCutPaste *cnp;
extern XtPointer image; // pointer to the XPM image data
extern unsigned long numBytes // number of bytes of image data
extern Widget theWidget; // widget where drag began
extern XEvent *xev; // ButtonPress Event that
// triggered the drag
Atom xaXPM = XmInternAtom(dpy, “XPM”, False);
cnp->dragAwayCopy(theWidget, xev, xaXPM, image, numBytes);
// at this point, you can free the data
|
The two optional parameters, dragAwayProc and clientData, are not usually specified, but if you want to be notified when the drag is finished, or if it was successful, you can pass in a callback procedure and any data you want. For example:
// dragAwayCB is invoked after completion of the drag
void dragAwayCB(Widget w, Boolean dragSuccess, XtPointer clientData)
{
printf(“Drag success = %d”, dragSuccess);
printf(“ClientData = 0x%x”, clientData);
}
|
Your call to dragAwayCopy() would then be like this:
cnp->dragAwayCopy(theWidget, xev, xaXPM, image, numBytes,
dragAwayCB, (XtPointer) 123);
|
ViewKit provides two functions for creating a drop site. VkCutPaste::registerDropSite() is sufficient for most needs. The advanced programmer may want more control, however, and so may wish to use VkCutPaste::registerDropSiteExtended(). If you are interacting with the Silicon Graphics IRIX Interactive Desktop, see “Accepting Drops From the IRIX Interactive Desktop”.
| registerDropSite() |
Registers a widget as a drop site. The interestList argument is a list of what data targets the drop site accepts, in order of preference. When another client drops data on this widget, the dropProc is called. The target passed to dropProc is the first target in the interestList that the other client can supply, or for which a converter exists (see “Using Data Type Converters” for more information about converting data types). The following is the prototype for the DropSiteCallbackProc: typedef void (*DropSiteCallbackProc)(Widget w,
| ||||
| registerDropSiteExtended() |
Does exactly what registerDropSite() does, but provides more options for the advanced programmer. For example, you could create various drop icons by specifying those parameters in the args argument. args and numArgs are passed off to XmDropSiteRegister(). Some args are not allowed: XmNdragProc, XmNdropProc, XmNdropSiteOperations, XmNimportTargets, and XmNnumImportTargets. See the XmDropSite(3X) reference page for information on other, valid arguments. The Motif Drop Copy protocol (XmDROP_COPY) is the only drag-and-drop operation the VkCutPaste class supports. The DropSiteCallbackProc is called when the user drops some data on the specified widget. The target passed to the DropSiteCallbackProc is the first target found in interestList that the other client is offering, or for which a converter exists (see “Using Data Type Converters”). The prototype for the DropSiteCallbackProc is as follows:
The DragCallbackProc is called when the user drags some data over the specified widget. The target passed to the DragCallbackProc is the first target found in interestList that the other client is offering, or for which a converter exists (see “Using Data Type Converters”). The following is the prototype of the DragCallbackProc:
These are the reasons that can be passed to the dragCallbackProc:
| ||||
| unregisterDropSite() |
Unregisters a drop site, making it stop accepting drops of any kind. |
The following code sample illustrates a drop. In this example, the application's widget accepts an XPM image or a GIF image (your list of acceptable formats can be as long as you like; this example just happens to use two). After creating the widget, you might include something like this:
Atom xaXPM = XmInternAtom(dpy, “XPM”, False);
Atom xaGIF_89 = XmInternAtom(dpy, “GIF_89”, False);
// dropProcCB wil be invoked whenever an image is dropped on the widget
void dropProcCB(Widget w, Atom target, XtPointer data,
unsigned long numBytes, int x, int y,
XtPointer clientData)
{
if (target == xaXPM)
printf(“XPM Image dropped at x=%d, y=%d.”, x, y);
else if (target == xaGIF_89)
printf(“GIF Image dropped at x=%d, y=%d.”, x, y);
// at some point, you should “XtFree(data)” to free the memory
}
// this code is done once, and makes the indicated widget a drop site
//
extern Widget theWidget; // widget that is to become a drop site
Atom interestList[2];
interestList[0] = xaXPM; // we first prefer XPM
interestList[1] = xaGIF_89; // we also accept GIF
int numItemsInList = 2;
cnp->registerDropSite(theWidget, interestList,
numItemsInList, dropProcCB, (XtPointer) 123);
|
When a user drags a file icon from the IRIX Interactive Desktop, the Desktop transfers the file information via an _SGI_ICON target. The VkCutPaste class provides some convenience routines for parsing this data:
| getFilenamesFromSGI_ICON() |
Parses the data of target _SGI_ICON that the IRIX Interactive Desktop uses to drag one or more files around. This is a convenience function that facilitates your application's acceptance of files from the desktop. You can call this function from a DropSiteCallbackProc when your application receives a target of _SGI_ICON. After your application is finished with the filename list, you should free the memory allocated inside getFilenamesFromSGI_ICON() by calling freeFilenamesFromSGI_ICON(). | ||
| freeFilenamesFromSGI_ICON() |
This frees the data returned from getFilenamesFromSGI_ICON(). |
The following code fragment illustrates the use of getFilenamesFromSGI_ICON() and freeFilenamesFromSGI_ICON() within a DropSiteCallbackProc:
Atom xaSGI_ICON = XmInternAtom(dpy, “_SGI_ICON”, False);
void dropProcCB(Widget w, Atom target, XtPointer data,
unsigned long numBytes,
int x, int y, XtPointer clientData);
{
if (target == xaSGI_ICON)
{
int numFilenames = 0;
char **filenames = NULL;
printf(“drop of _SGI_ICON at %d, %d\n”, x, y);
if (cnp->getFilenamesFromSGI_ICON((char *)data, numBytes,
&filenames, &numFilenames))
{
int i;
for (i = 0; i < numFilenames; i++)
{
printf(“\tdropped file %d: %s\n”, i, filenames[i]);
}
cnp->freeFilenamesFromSGI_ICON(filenames, numFilenames);
}
}
if (data != NULL)
{
XtFree(data);
}
}
// this code is done once, and makes the indicated widget a drop site
extern Widget theWidget; // widget that is to become a drop site
Atom interestList[1];
interestList[0] = xaSGI_ICON; // only interested in _SGI_ICON
int numItemsInList = 1;
cnp->registerDropSite(theWidget, interestList, numItemsInList,
dropProcCB, (XtPointer)123);
|
Before you can pass a particular target to a VKCutPaste method, the VkCutPaste class must be aware of the target and its properties. The VkCutPaste class has a long list of known targets (see the VkCutPaste(3x) reference page). However, if your application creates a new, custom target, you must describe it by calling VkCutPaste::registerDataType().
| registerDataType() |
Registers a data target with the VkCutPaste class, and at the same time tells the class what the type, format, and flags are (for more information on targets, types, and formats, see the Inter-Client Communication Conventions Manual). This is commonly done only once per data type, immediately after the creation of the instance of the VkCutPaste class. You must register a data type only for types not already in VkCutPaste's list of registered targets. See the VkCutPaste(3x) reference page for a list of registered targets. For the purposes of this chapter, the term “filename type” refers to a string type that is the name of a file being copied and pasted or dragged and dropped. The term “normal type” refers to a large block of malloc'ed memory that is being copied and pasted or dragged and dropped. The flags argument is a bit mask of the following flags:
A CUTPASTE_HIDDEN_TYPE means that this target will never be published to other clients. This is unusual, but can be useful if you are using an internal representation you do not wish to expose. You must flag any new “filename” target as a CUTPASTE_FILENAME_TYPE so that the VkCutPaste class can deal with it properly. When registering a new filename target, you must also pass in a destroyProc that can be called to remove the file when necessary. The prototype for the DestroyProc is as follows:
The DestroyProc cleans up any auxiliary data that is no longer needed. The VkCutPaste class calls the DestroyProc at various times, immediately after deleting a target from an internal buffer. The most common use of a DestroyProc is when the target is a filename target. The filename is the actual target, and the cloned file on disk is the auxiliary data. The DestroyProc removes the cloned file when the VkCutPaste class no longer needs it. The DestroyProc should NOT free the filename memory. The following DestroyProc can be used verbatim for any filename type:
The following code fragment illustrates the use of registerDataType(). You do not need to use this code, since the XPM_FILE target is already a registered data type. However, this code does serve as a valid example:
| |||||
| getDataTypeInfo() |
Receives a target, and passes back the target's type and format (as specified in the Inter-Client Communication Conventions Manual), and any associated flags. getDataTypeInfo() returns True if it finds the target, and False otherwise. The VkCutPaste class already has an extensive list of registered targets. You can add types to this list by calling registerDataType(). |
The VkCutPaste class provides integral support for converters from one data type to another. Converters are used to increase the number of targets your application can offer (copying and dragging), or accept (pasting and dropping). For example, if you call dragAwayCopy() with XPM data, and a drop site in another ICCCM application only accepts images of type GIF_89, then the drop would normally fail. However, if you have registered a converter from XPM to GIF_89, the VkCutPaste class automatically calls your converter and successfully drops the GIF_89 on the destination client.
| registerConverter() |
Registers a converter between two data targets. For example, if you have registered a converter from XPM to GIF_89, and you dragAwayCopy() an XPM, the VkCutPaste class automatically calls your converter when the drop site accepts only GIF_89. The prototype for the converter is as follows:
The VkCutPaste class provides the ability to use an optional canConvertProc so that your application can conditionally offer conversion support for a given target. The canConvertProc returns True if the converter can perform the requested conversion, and False otherwise. The VkCutPaste class calls the canConvertProc to ensure that VkCutPaste does not offer targets that it cannot actually produce. If your conversions always work under all circumstances, do not register a CanConvertProc. This is the prototype for the CanConvertProc:
|
Example 10-1 demonstrates registering a XPM to GIF_89 converter:
Example 10-1. Registering an XPM to GIF89 Converter
extern Display *dpy;
Atom xaXPM = XmInternAtom(dpy, “XPM”, False);
Atom xaGIF_89 = XmInternAtom(dpy, “GIF_89”, False);
Boolean xpmToGifConverter(Widget w, Atom selection,
void *clientData,
Atom srcTarget, XtPointer src,
unsigned long numSrcBytes,
Atom dstTarget, XtPointer *dst,
unsigned long *numDstBytes)
{
if (srcTarget != xaXPM || dstTarget != xaGIF_89)
return(False); // this should never happen
*numDstBytes = /* calculate enough memory for Gif */
*dst = (XtPointer) malloc(*numDstBytes);
// insert code here to convert from the source XPM image
// into a GIF, and place it in the newly malloced memory.
return(True); // return True if the conversion is successful
}
Boolean xpmToGifConversionIsPossible(Widget w, Atom selection,
void *clientData,
Atom srcTarget,
XtPointer src,
unsigned long numSrcBytes,
Atom dstTarget)
{
if (srcTarget != xaXPM || dstTarget != xaGIF_89)
return(False); // this should never happen
numberOfColorsInXPM = discoverNumberOfColorsInXPM(src);
if (numberOfColorsInXPM < 256) // GIF only has 256 colors
return(True);
else
return(False); // we cannot convert this GIF
}
cnp->registerConverter(xaXPM, xaGIF_89, xpmToGifConverter,
xpmToGifConversionIsPossible, NULL);
|
After this single registerConverter() call, your converter is automatically called in each of four possible scenarios:
If you export an XPM, but the importing client accepts only GIF_89.
If you dragAway XPM, but the client you drop on accepts only GIF_89.
If you want to import a GIF_89, but the sending client doesn't offer GIF_89, but does offer XPM.
If a drop on you only offers XPM, but you accept only GIF_89.
Changes in the ownership of files and data during copy, paste, drag, and drop operations can be difficult to trace. The pseudocode examples in this section detail the ownership changes during different stages of data transfer. The examples show code implementing copy, paste, drag, and drop of both normal data and filename data.
Filename data simply means the data being transferred is a filename. For example, when transferring an XPM_FILE target, the data transferred is actually the filename, not the data contained in the file. The receiving application needs to retrieve the filename, then access the file. Normal data means that the data being transferred is a block of malloc'ed memory.
The VkCutPaste class recognizes targets as being filename targets only if they have been registered with the CUTPASTE_FILENAME_TYPE flag. See the VkCutPaste(3x) reference page for a list of registered targets.
 | Note: Applications should seldom need to use filename targets for cut, paste, drag, and drop operations. In fact, exchanging filenames with other applications does not work when the sender and receiver applications are running on different computers. When given a choice between filename targets and the corresponding normal targets, applications should always exchange the normal targets. |
In these pseudocode samples (Example 10-2 to Example 10-10), cnp is an instance of the VkCutPaste class, and the filename target is any target that has been registered with the CUTPASTE_FILENAME_TYPE flag.
Example 10-2. Data and File Ownership Changes While Copying Filenames
// Create a file on disk. Ownership of the file will be transferred // to the VkCutPaste class at putCopy() time. char *filename = create a file, return the malloced filename; // Clear any prior putCopy() or export(). cnp->clear(); // Copy the filename `filename', and transfer the ownership of the // file on disk to the VkCutPaste class. Note that the file itself // is NOT copied, only the filename. The client can now free the // memory used by filename, but must NOT reference the disk file again. // NOTE: If the client has registered a destroyProc for this // filename type, the VkCutPaste class might call that destroyProc to // remove the original disk file. In that case, the client should honor // the request and remove the file. cnp->putCopy(filename); // The VkCutPaste class has made a copy of the filename, so the // original data should be freed by the client. free(filename); // Make the data available to other clients. cnp->export(); ... // Some time later, if the VkCutPaste class gets a request for this // filename, the VkCutPaste class will clone the file, and hand off to // the requesting client the cloned filename. Ownership of this // cloned file is transferred to the requesting client. ... // The next time clear() is called, any data that has been copied // during prior putCopy() calls is freed, and any files that the // VkCutPaste class has obtained ownership of during prior putCopy() // calls are removed. After this clear(), this VkCutPaste instance // no longer has any data available for export. cnp->clear(); |
Example 10-3. Data and File Ownership Changes While Pasting Filenames
// Client requests a filename target. The filename returned and the // corresponding file on disk are now owned by this client. It is // therefore the responsibility of the requesting client to remove // (unlink()) the file when the client is finished with it, and // free the filename. filename = cnp->importImmediate(); // After this client is done with the file, the file must be // removed, and the filename freed. unlink(filename); XtFree(filename); |
Example 10-4. Data and File Ownership Changes While Copying Normal Data
// Create some data in memory. char *data = create some data; // Clear any prior putCopy() or export(). cnp->clear(); // The VkCutPaste class makes a copy of the data. This copy of // the data will be freed during the next “clear()” operation. cnp->putCopy(data); // The VkCutPaste class has made a copy of the data, so the original // data should be freed by the client. free(data); // Make the data available to other clients. cnp->export(); ... // The next time clear() is called, any data that has been copied // during prior putCopy() calls is freed, and any files that the // VkCutPaste class has obtained ownership of during prior putCopy() // calls are removed. After this clear(), this VkCutPaste instance no // longer has any data available for export. cnp->clear(); |
Example 10-5. Data and File Ownership Changes While Pasting Normal Data
// Client requests the data. This data is now owned by this // client. The client will use the data, and should free it when // it is done processing the data. data = cnp->importImmediate(); // Free the imported data when you are done processing it. XtFree(data); |
Example 10-6. Data and File Ownership Changes While Dragging Filename Data
// Create a file on disk. Ownership of the file will be // transferred to the VkCutPaste class at dragAwayCopy() time. char *filename = create a file, return the malloced filename; // Copy the filename `filename', and transfer the ownership of the // file on disk to the VkCutPaste class. Note that the file itself // is NOT copied, only the filename. The client can now free the // memory used by filename, but must NOT reference the disk file // again. The VkCutPaste class will free this copy of the data, and // remove the file when the drag and drop operation is complete. // // NOTE: If the client has registered a destroyProc for this filename // type, the VkCutPaste class might call that destroyProc to remove // the original disk file. In that case, the client should honor the // request and remove the file. cnp->dragAwayCopy(filename); // The VkCutPaste class has made a copy of the filename, so the // original data should be freed by the client. free(filename); ... // Some time later, if the VkCutPaste class gets a request for this // filename, the VkCutPaste class will clone the file, and hand off // the cloned filename to the requesting client. Ownership of this // cloned file is transferred to the requesting client. The // original file is removed when the drag and drop operation is // complete. |
Example 10-7. Data and File Ownership Changes While Accepting Filename Data
// The “drop” client registers a drop site.
cnp->registerDropSite(dropFilenameCallback);
...
// Some time later, the dropFilenameCallback() routine is called.
// Inside of the dropFilenameCallback, the filename passed in and
// the corresponding file on disk are now owned by this client. It
// is therefore the responsibility of the requesting client to remove
// (unlink()) the file when the client is finished with it, and free
// the filename.
dropFilenameCallback(filename)
{
// Do some processing on the file.
unlink(filename);
// After this client is done with
// the file, the file must be removed,
// and the filename freed.
XtFree(filename);
}
|
Example 10-8. Data and File Ownership Changes While Dragging Normal Data
// Create some data in memory. char *data = create some data; // The VkCutPaste class makes a copy of the data. The VkCutPaste // class will free this copy of the data when the drag and drop // operation is complete. cnp->dragAwayCopy(data); // The client can now free the original data. free(data); |
Example 10-9. Data and File Ownership Changes While Accepting Normal Data
// The “drop” client registers a drop site.
cnp->registerDropSite(dropDataCallback);
...
//
// Some time later, the dropDataCallback() routine is called.
dropDataCallback(data)
{
// Do some processing with this data.
...
// Free the data when you are done processing it.
XtFree(data);
}
|
Example 10-10. Data and File Ownership Changes While Accepting _SGI_ICON Data
// The drop client registers a drop site that accepts _SGI_ICON data
cnp->registerDropSite(dropSGI_ICONcallback);
...
// Some time later, the dropSGI_ICONcallback() routine is called.
// Inside the dropSGI_ICONcallback, this client reads the filenames
// out of the _SGI_ICON data, but DOES NOT own the files and must not
// modify them or remove them. This client does need to free the
// _SGI_ICONdata.
dropSGI_ICONcallback(_SGI_ICONdata)
{
// Get the filenames, read some data from the files, etc.
XtFree(_SGI_ICONdata);
}
|
The VkCutPaste class also provides several utility functions that you may find useful.
| primaryAtom() |
Returns the PRIMARY atom. This is a convenience function, and returns exactly the same thing as XmInternAtom(dpy, “PRIMARY”, False). | ||
| clipboardAtom() |
Returns the CLIPBOARD atom. This is a convenience function, and returns exactly the same thing as XmInternAtom(dpy, “CLIPBOARD”, False). | ||
| getVersion() | unsigned long getVersion(void) Returns the version number of this implementation of the VkCutPaste class. For example, version 1.0 would be 0x010000, version 2.01 would be 0x020100, and so on. | ||
| getWidget() | Widget getWidget(void) Returns the widget that was originally passed to the VkCutPaste constructor. | ||
| getXServerTime() |
Invokes a round trip to the X-Server, and returns a server time stamp. You should try to avoid this call. Instead, you should pass the CurrentTime flag to VkCutPaste functions, or (even better) use the time stamp of a recent X-Event. However, there may be some rare situations where there are no X-Events available and CurrentTime does not work, so this convenience function provides a fail-safe way to get a valid server time stamp. | ||
| setTransactionsTimeout() |
Sets the transaction time-out. The default Motif time-out is 5 seconds, which means that if the remote client does not respond to a request for data within 5 seconds, the transaction is cancelled and no data is transferred. For some large data targets, or those that require long conversions, 5 seconds may not be adequate. | ||
| isOwnedByMe() |
Returns True if the selection is currently owned by the calling client. This can be used to optimize the speed of Paste() when the client would have exchanged data with itself anyway. | ||
| isOwnedbyLocalHost() |
Returns True if the indicated selection is currently owned by a client running on the same machine as this client. This call is useful if you are planning to copy and paste filenames with other clients, since a file that is on a different machine is not accessible to your client. Some examples of filename targets are XPM_FILE and GIF_89_FILE. Normal types like XPM and GIF_89 are always safe and always work, and should be used instead, unless there is some overwhelming reason to exchange filenames. | ||
| getLocalReference() |
Allows you to retrieve the contents of the local export selection. This is not based on X Selections. This only gives you a pointer, so the data must not be freed or modified. Returns a pointer to the data at index (if multiple putCopy() were called, the first one is at index 0, the second is at index 1, and so on). | ||
| getLocalTypeReference() |
Does exactly the same thing as getLocalReference(), but instead of specifying an index, you specify the target you wish to retrieve from the exported selection. | ||
| putReference() |
Can be used instead of putCopy() when the data is so large that an extra copy would be impossible or impractical. This function does not make a copy of the data, so you should never free data until after you call remove() to remove the currently exported data from the selection. If, for some reason, the data becomes invalid, you must call remove(). | ||
| remove() | Boolean remove(Atom selection, Atom target); Removes the indicated target from the currently exported selection. For example, if you had called putReference(XPM) earlier, and now for some reason, the XPM data is no longer valid, you must call remove(XPM).
|