Chapter 7. Interapplication Data Exchange
Prev | Part I. Getting the Right Look and Feel | Next

## Chapter 7. Interapplication Data Exchange

This chapter describes how to implement the recommended data exchange mechanisms in your applications. It contains these sections:

- “Data Exchange Overview” provides a brief description of how the Primary and Clipboard Transfer Models should work in your application. You should implement both.

- “Implementing the Primary Transfer Model” describes how to implement the Primary Transfer Model in your application.

- “Implementing the Clipboard Transfer Model” describes how to implement the Primary Transfer Model in your application.

- “Supported Target Formats” provides tables listing the atom names of supported data formats, along with brief descriptions of what each format is used for.

- “Data Conversion Service” describes the service available for converting files from one data format to another. For details on the process, refer to Appendix G, “Using GoldenGate Data Conversion Services”.

## Data Exchange Overview

As detailed in Chapter 5, “Data Exchange on the IRIX Interactive Desktop,” in the IRIX Interactive User Interface Guidelines, Silicon Graphics recommends that your application support both the Primary and Clipboard Transfer Models. The Primary Transfer Model allows users to copy data using mouse buttons, whereas the Clipboard Transfer model allows users to use the “Cut,” “Copy,” and “Paste” options from the Edit menu (or the corresponding keyboard accelerators) to transfer data.

| Note: Silicon Graphics recommends that you not use the IRIS IM clipboard routines for handling data exchange.

The data exchange model recommended by Silicon Graphics is based on the standard mechanisms provided by the X and Xt. You can consult the O'Reilly & Associates book The X Window System, Volume 4: X Toolkit Intrinsics Programming Manual by Adrian Nye for more information on the standard Xt data exchange methods.

The following sections describe:

- “Primary Transfer Model Overview”

- “Clipboard Transfer Model Overview”

- “Interaction Between the Primary and Clipboard Transfer Models”

### Primary Transfer Model Overview

When the user selects some data in an application, the application should highlight that data and assert ownership of the PRIMARY selection. Until the application loses the PRIMARY selection, it should then be prepared to respond to requests for the selected data in various target formats. “Supported Target Formats” describes the standard target formats.

When the user selects data in another application, your application loses ownership of the PRIMARY selection. In general, when your application loses the primary selection, it should keep its current selection highlighted. When a user has selections highlighted in more than one window at a time, the most recent selection is always the primary selection. This is consistent with the persistent always selection discussed in Section 4.2, “Selection Actions,” in the OSF/Motif Style Guide, Release 1.2. There is an exception to this guideline: those applications that use selection only for primary transfer, for example, the winterm shell window. The only reason for users to select text in a shell window is to transfer that text using the primary transfer mechanism. In this case, when the winterm window loses the primary selection, the highlighting is removed. This is referred to as nonpersistent selection in Section 4.2, “Selection Actions,” in the OSF/Motif Style Guide, Release 1.2.

The persistent always selection mechanism allows the user to have data selected in different applications. The user can still manipulate selected data using application controls. Furthermore, the user can reassert the selected data as the PRIMARY selection by pressing `<Alt–Insert>`.

When the user clicks the middle mouse button (BTransfer) in your application, your application should attempt to copy the primary selection to the current location of the mouse pointer. First, your application should request a list of target formats supported by the primary selection owner. Then your application should select the most appropriate target format and request the primary selection in that format.

“Supporting the Primary Transfer Model” in Chapter 5 of the IRIX Interactive User Interface Guidelines further discusses use of the Primary Transfer Model.

### Clipboard Transfer Model Overview

When the user selects the “Copy” option from your application's Edit menu (or uses the keyboard accelerator), your application should assert ownership of the CLIPBOARD selection. Until the application loses the CLIPBOARD selection, it should then be prepared to respond to requests for the data selected at the time your application took ownership of the CLIPBOARD selection. (In other words, your application must somehow store the value of the selection when the user performs the copy action; the application can then provide this value even if the user subsequently changes the application's selection.)

When the user selects the “Cut” option for your application's Edit menu (or uses the keyboard accelerator), your application should assert ownership of the CLIPBOARD selection. Your application must cut the selected data, but it should store the data and be prepared to respond to requests for the data until it loses ownership of the CLIPBOARD selection.

When the user selects the “Paste” option for your application's Edit menu (or uses the keyboard accelerator), your application should attempt to copy the clipboard selection to the current location of the location cursor. First, your application should request a list of target formats supported by the clipboard selection owner. Then your application should select the most appropriate target format and request the clipboard selection in that format.

“Supporting the Clipboard Transfer Model” in Chapter 5 of the IRIX Interactive User Interface Guidelines further discusses use of the Clipboard Transfer Model.

### Interaction Between the Primary and Clipboard Transfer Models

Silicon Graphics recommends that you implement the Primary and Clipboard Transfer Models so that they operate separately. The only complication is maintaining data in the PRIMARY selection when the user performs a cut action. Consider the following example:

1. The user selects data in an application. The application asserts ownership of the PRIMARY selection.

2. The user performs a cut action. The application asserts ownership of the CLIPBOARD selection and removes the selected data from the display.

3. The user goes to another application that already has data selected.

4. The user cuts the data selected in the second application. The second application asserts ownership of the CLIPBOARD selection and removes the selected data from the display.

The clipboard actions described above should not affect the PRIMARY selection. In this example, the first application should retain ownership of the PRIMARY selection and continue to be prepared to respond to requests for the value of the PRIMARY selection. To support this, the application should somehow store the value of the PRIMARY selection until it no longer owns the PRIMARY selection.

To properly handle the situation described above, your application should implement the following:

1. In the function that handles the Clipboard Transfer Model's cut action, test to see whether the application owns the PRIMARY selection. If it does, you should preserve the selected data. If selections in your application are typically small (for example, ASCII text), you might simply copy the data to a buffer. If selections in your application are typically large (for example, sound or movie clips), you might remove the data from the display but retain pointers to it.

2. In the function that handles losing the PRIMARY selection, test to see whether you have data preserved from a cut action. If so, and the application currently doesn't own the CLIPBOARD selection, you should free that data or reset the pointers to it.

## Implementing the Primary Transfer Model

This section describes how to implement support for the Primary Transfer Model in your application. Topics covered include:

- “Data Selection”

- “Requests for the Primary Selection”

- “Loss of the Primary Selection”

- “Inserting the Primary Selection”

  | Note: Silicon Graphics recommends that you don't use the IRIS IM clipboard routines, because they are not as flexible as the Xt selection routines.

### Data Selection

When the user selects data in a window of your application, it should call `XtOwnSelection(3Xt)` to assert ownership of the PRIMARY selection and highlight the selected data.

The code fragment in Example 7-1 shows a simple example of asserting ownership of the PRIMARY selection. For clarity, this example omits code for manipulating the selection itself (for example, setting up pointers to the selection).

“Selection” in Chapter 7 of the IRIX Interactive User Interface Guidelines discusses guidelines for allowing users to select data and for hightlighting selected data.

Example 7-1. Asserting Ownership of PRIMARY Selection

    Boolean ownPrimary;

    /*
       w is window in which selection occurred
       event is pointer to event that caused selection
    */

    void dataSelected(Widget w, XButtonEvent *event)
    {
    ...
      /*
         Assert ownership of PRIMARY selection.

         XA_PRIMARY is the slection.
         event->time is timestamp of the event.
         primaryRequestCallback is the function called
             whenever another application requests the
             value of the PRIMARY selection.
         lostPrimaryCallback is the function called whenever
             the application loses the selection.
      */

      ownPrimary = XtOwnSelection(w, XA_PRIMARY, event->time,
                                  primaryRequestCallback,
                                  lostPrimaryCallback,
                                  NULL);

      /*
         If we successfully obtained ownership, highlight
         the data; otherwise, clean up
      */

      if (ownPrimary)
        highlightSelection();
      else
        lostPrimaryCallback(w, XA_PRIMARY);
    ...
    }

### Requests for the Primary Selection

When you assert ownership of the PRIMARY selection, one of the parameters you pass to `XtOwnSelection()` is a callback function to handle requests for the value of the PRIMARY selection. When another application requests the value of the PRIMARY selection, the Xt selection mechanism invokes your application's callback function.

The requesting application indicates a desired target format. Typically, a requestor first asks for the special target format TARGETS. Your application should respond with a list of target formats it supports. The requestor then chooses an appropriate target format and requests the selection value in that format. “Supported Target Formats” describes some of the common target formats your application should support.

### Loss of the Primary Selection

When your application loses the PRIMARY selection and your application follows the persistent always selection model discussed in “Primary Transfer Model Overview”, don't remove the highlight from any selected data. The user should still be able to cut or copy any selected data using the Clipboard Transfer Model. If your application follows the nonpersistent selection model as discussed in “Primary Transfer Model Overview”, you should remove the highlight.

Your application should also test to see whether you have data preserved from a cut action (see “Cut Actions”). If so, and your application currently doesn't own the CLIPBOARD selection, you should free that data or reset the pointers to it. “Interaction Between the Primary and Clipboard Transfer Models” describes the rationale for this procedure.

| Note: To comply with the IRIX Interactive User Interface Guidelines, if the user presses `<Alt–Insert>` in your application, you should reassert ownership of PRIMARY for your application.

### Inserting the Primary Selection

When the user clicks the middle mouse button in your application, it should perform the steps described below.

1. Your application should ask the owner of the PRIMARY selection for a list of its TARGETS, using `XtGetSelectionValue()` with selection PRIMARY and target TARGETS.

2. Your application should look through the list of supported targets, select the one that is appropriate for your application, and call `XtGetSelectionValue()` again with that new target.

3. If the selection owner does not support TARGETS, then your application should ask for the target STRING, if it can support that target.

   Silicon Graphics recommends that you support STRING, even if your application doesn't support text. For instance, a movie player could get the selection as a string and try to parse it as a filename. That way users could select a filename in a terminal emulator window and paste it into another application.

## Implementing the Clipboard Transfer Model

This section describes how to implement support for the Clipboard Transfer Model in your application. Topics include:

- “Cut Actions”

- “Copy Actions”

- “Requests for the Clipboard Selection”

- “Paste Actions”

- “Loss of the Clipboard Selection”

### Cut Actions

When the user performs a cut action, your application should:

1. Call `XtOwnSelection(3Xt)` to assert ownership of the CLIPBOARD selection.

2. Remove the selected data from the display. Retain the selected data until your application loses ownership of the CLIPBOARD selection.

3. Test to see whether the application owns the PRIMARY selection. If it does, you should preserve the selected data, even after losing ownership of the CLIPBOARD selection. You should retain the data until your application also loses ownership of the PRIMARY selection.

   If selections in your application are typically small (for example, ASCII text), you might simply copy the data to a buffer. If selections in your application are typically large (for example, sound or movie clips), you might remove the data from the display but retain pointers to it.

The code fragment in Example 7-2 shows a simple example of handling a cut action and asserting ownership of the CLIPBOARD selection. For clarity, this example omits code for manipulating the selection itself (for example, setting up pointers to the selection).

Example 7-2. Handling Cut Actions in the Clipboard Transfer Model

    Boolean ownPrimary;
    Boolean primaryPreserved;
    /*
       w is window in which selection occurred
       event is pointer to event that caused selection
      */
    void selectionCut(Widget w, XButtonEvent *event)
    {
    ...
      /*
         Assert ownership of CLIPBOARD selection.

         XA_CLIPBOARD is the selection.
         event->time is timestamp of the event.
         clipboardRequestCallback is the function called
             whenever another application requests the
             value of the CLIPBOARD selection.
         lostClipboardCallback is the function called whenever
             the application loses the selection.
      */

      ownClipboard = XtOwnSelection(w, XA_CLIPBOARD, event->time,
                                    clipboardRequestCallback,
                                    lostClipboardCallback,
                                    NULL);

      if (ownClipboard)
      {
        /*
           Retain the selected data until the application loses
           ownership of the CLIPBOARD selection.
        */

        preserveClipboardSelection();

        /*
           If we also own the PRIMARY selection, we need to
           preserve the selected data separately so that we can
           continue to satisfy requests for the PRIMARY selection
           even if we lose the CLIPBOARD selection.
        */

        if (ownPrimary)
          primaryPreserved = preservePrimarySelection();
      }
    ...
    }

### Copy Actions

When the user performs a copy action, your application should call `XtOwnSelection(3Xt)` to assert ownership of the CLIPBOARD selection. No other actions are required.

### Requests for the Clipboard Selection

When you assert ownership of the CLIPBOARD selection, one of the parameters you pass to `XtOwnSelection()` is a callback function to handle requests for the value of the CLIPBOARD selection. When another application requests the value of the CLIPBOARD selection, the Xt selection mechanism invokes your application's callback function.

The requesting application indicates a desired target format. Typically, a requestor first asks for the special target format TARGETS. Your application should respond with a list of target formats it supports. The requestor then chooses an appropriate target format and requests the selection value in that format. “Supported Target Formats” describes some of the common target formats your application should support.

### Paste Actions

When the user selects “Paste” from the File menu, your application should:

1. Ask the owner of the CLIPBOARD selection for a list of its TARGETS, using `XtGetSelectionValue()` with selection CLIPBOARD and target TARGETS.

2. Look through the list of supported targets, select the one that is appropriate for your application, and call `XtGetSelectionValue()` again with that new target.

3. If the selection owner doesn't support TARGETS, then your application should ask for the target STRING, if it can support that target.

   Silicon Graphics recommends that you support STRING, even if your application doesn't support text. For instance, a movie player can get the selection as a string and try to parse it as a filename. That way users can select a filename in a terminal emulator window and paste it into another application.

### Loss of the Clipboard Selection

When your application loses the Clipboard selection, don't remove the highlight from any selected data. The user should still be able to cut or copy any selected data. Your application can discard any data it had retained as a result of a cut operation (see “Cut Actions”).

## Supported Target Formats

Every application should support the TARGETS, TIMESTAMP, MULTIPLE, and STRING targets. The Xt selection functions support the MULTIPLE targets for you. `XmuConvertStandardSelection()` supports the TIMESTAMP target. (Silicon Graphics recommends that applications use `XmuConvertStandardSelection()` because it also supports HOSTNAME, NAME, CLIENT_WINDOW, and a variety of other useful targets.) Your application must support the TARGETS and STRING targets itself. In addition, Silicon Graphics has defined other targets for data types used by Silicon Graphics applications and libraries.

The tables that follow list supported target formats:

- Table 7-1 lists target names for audio formats

- Table 7-2 shows target names for image formats

- Table 7-3 presents target names for movie formats

- Table 7-4 lists target names for 3D graphics formats

- Table 7-5 shows target names for Silicon Graphics data types

- Table 7-6 shows target names for World Wide Web formats

Table 7-1. Audio Formats

Name of Atom/Target | Description
--- | ---
AIFF_FILE | Audio Interchange Format, used on Apple systems.
AIFF_C_FILE | Modified version of Apple's AIFF, compatible with SGI systems.
NEXT_FILE | Used on Next and Sun systems.
SD2_FILE | Sound Designer 2 format
WAVE_FILE | Microsoft Wave format
MPEG_1_AUDIO_FILE | MPEG Audio. The name of a file that contains MPEG-1 audio data.
MPEG_1_AUDIO | Stream of audio data, in MPEG-1 Stream format.
SGI_AUDIO_FILE | The name of a file that contains Silicon Graphics format sound data, that can be read using libaudiofile. The file is the responsibility of the receiver, once the selection owner has generated it.
SGI_AUDIO | Stream of audio data, readable with the SGI audio library.

Table 7-2. Image Formats

Name of Atom/Target | Description
--- | ---
FITS_FILE | Flexible Image Transport System
GIF_89 | Graphics Interchange Format (streaming bit format)
GIF_89_FILE | Graphics Interchange Format (file format)
JFIF_FILE | JPEG File Interchange Format
DIB_FILE | Microsoft image format
PHOTO_CD_FILE | Kodak photo CD
PPM_FILE | Portable pixmap format
PNM_FILE | Portable anymap format
PGM_FILE | Portable graymap format
SGI_RGBIMAGE_FILE | The name of a file that contains a Silicon Graphics format image file. This is an rgb file. The file is the responsibility of the receiver, once the selection owner has generated it.
SGI_RGBIMAGE | The rgb image data stream.
TIFF_FILE | Tagged Image File Format

Table 7-3. Movie Formats

Name of Atom/Target | Description
--- | ---
APPLE_QUICKTIME_FILE | Apple Quicktime[tm] format
AVID_OMFI_FILE | AVID OMFI[tm]
AVI_FILE | Microsoft AVI[tm] format
MPEG_1_VIDEO_FILE | Motion Picture Experts Group MPEG-1 file
MPEG_1_VIDEO | Stream format
MPEG_1_SYSTEMS_FILE | Motion Picture Experts Group MPEG-1 systems file
MPEG_1_SYSTEMS | Stream format
SGI_MOVIE_FILE | SGI movie format
SGI_MOVIE | Stream format

Table 7-4. 3D Graphics Formats

Name of Atom/Target | Description
--- | ---
INVENTOR_2_1 | SGI Open Inventor V2.1 data
INVENTOR_2_1_FILE | SGI Open Inventor V2.1 file
AUTODESK_DXF_FILE | AUTODESK DXF[tm]
AUTODESK_3DS_FILE | AUTODESK 3DS[tm]
ALIAS_FILE | Alias wire file
IGES_FILE | IGES file
PIXAR_RIB_FILE | Pixar Renderman .RIB file
SOFTIMAGE_HRC_FILE | Softimage .hrc file
SOFTIMAGE_DSC_FILE | Softimage .dsc file
WAVEFRONT_OBJ_FILE | Wavefront .OBJ file
VRML_1_0_FILE | VRML 1.0 file

Table 7-5. Additional Data Types Supported by Silicon Graphics

Name of Atom/Target | Description
--- | ---
INVENTOR | Synonym for INVENTOR_2_0.
_SGI_RGB_IMAGE_FILENAME | Replaced by SGI_RGBIMAGE_FILE.
_SGI_RGB_IMAGE | Replaced by SGI_RGBIMAGE.
_SGI_AUDIO_FILENAME | Replaced by SGI_AUDIO_FILE.
_SGI_AUDIO | Replaced by SGI_AUDIO.
_SGI_MOVIE_FILENAME | Replaced by SGI_MOVIE_FILE.
_SGI_MOVIE | Replaced by SGI_MOVIE.
SGI_SHOWCASE_FILE | Name of file containing SGI Showcase data.

| Caution: Xt implements a timeout when transferring data using the selection mechanism. The default is five seconds. Often, this is inadequate for applications transferring audio, image, or movie data. Therefore, if your application supports receiving such selections, you should call `XtAppSetSelectionTimeout()` to change the timeout to a larger value.

Table 7-6. World Wide Web Targets

Type of Atom/Target | Description
--- | ---
HTML | Hypertext Markup Language as an ASCII Stream.
HTML_FILE | Name of the file containing HTML.

| Note: Silicon Graphics applications should also support the generic X11/ICCCM targets such as STRING and COMPOUND_TEXT.

## Data Conversion Service

Silicon Graphics provides GoldenGate data conversion service to help you convert data from one format to another, offloading the responsibility for data conversion from your application. See Appendix G, “Using GoldenGate Data Conversion Services”, for more information.

The GoldenGate conversion service consists of four elements:

- the header file, `/usr/include/convert/SgCvt.h`

- the conversion library, `libcvt.so`

- the converter registry file, `/etc/ConverterRegistry`

- a set of pluggable converters

The header file and library provide the Application Programmatic Interface (API) for the service. The converter registry file describes the converters available to the service. The actual code for the converters is stored in separate Dynamic Shared Objects (DSOs). When an application program tries to access a converter, the service dynamically loads the associated DSO.

The GoldenGate API uses Digital Media parameter-value lists to describe data formats. See the IRIS Media Libraries Programming Guide for information on how to use the Digital Media library to create and manipulate digital media parameter-value lists.

### The Converter Registry

The converter registry contains entries describing each converter available to the service. Each converter entry lists the data format that the converter takes as input, the format that the converter produces as output, and information that allows the service to locate the converter code.

The converter registry can also contain entries defining pipelines. A pipeline is a set of converters connected in series, with the output of one converter feeding the next. As far as application programs are concerned, a pipeline is just another converter.

### The GoldenGate API

All programs using the GoldenGate API should include the `libSgCvt` header file:

    #include <convert/SgCvt.h>

The GoldenGate API uses a fairly simple programming model. For application programs, the most complicated part of the conversion process is picking an appropriate converter.

Once the application program has picked a converter, it initializes the conversion pipeline, and proceeds to send data through the pipeline. The pipeline is a “black box.” It may consist of one converter, or several converters running in series. The API for application programs using the service is described in Appendix G, “Using GoldenGate Data Conversion Services”.

Converters, on the other hand, must read data from the pipeline, convert it, and write data back to the pipeline. Again, the pipeline is a black box. A converter can't tell if its input is coming from another converter, or from an application program. Likewise, it can't tell if its output is going to another converter or back to the application program. Designing converters is discussed in Appendix G, “Using GoldenGate Data Conversion Services”.

Prev | Table of Contents | Next
Chapter 6. Customizing Your Application's Minimized Windows |  | Chapter 8. Monitoring Changes to Files and Directories