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.

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.

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:

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:

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.

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);
...
}

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.

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.

---

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

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

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).

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();
  }
...
}

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.

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.

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

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”).

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.

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”.