Previous Book Contents Book Index Next

Inside Macintosh: Programmer's Guide to MacApp / Part 2 - Working With MacApp
Chapter 22 - Working With the Clipboard


The Macintosh Operating System provides a number of mechanisms for exchanging data between applications, from static copy and paste operations using the Clipboard, to drag-and-drop data transfer, to dynamic data exchange using the Edition Manager. Supporting the Macintosh Clipboard is a vital component of any application because users expect this capability to be available.

MacApp's Clipboard support is designed to help your application work with the Macintosh Clipboard. The following terms are used to describe Clipboard functions:

Basic Clipboard Operations

Clipboard support requires a combination of the following activities:

Using the Desk Scrap

An application supplies data for the Clipboard by putting it on the desk scrap, along with a data type to identify it. Data is put on the desk scrap with the Toolbox call PutScrap. An application can put more than one data type on the desk scrap. For example, it may put data in a private format, as well as in the public formats 'TEXT' and 'PICT'. There should not be more than one item on the desk scrap for each data type, so it is common to call the Toolbox routine ZeroScrap to clear the desk scrap, then make one or more calls to PutScrap to add data of different types.

An application's private desk scrap data types can be registered with Apple Computer so that they will not be used by other applications. You can register types at the World Wide Web location
When pasting data from the desk scrap, an application looks first for its most preferred data type, but it may use other data types if the preferred type is not available. To find out whether data of a desired type is available, an application uses the Toolbox call GetScrap, which is described in the next section.

Using the Toolbox GetScrap Routine

You use the GetScrap routine from the Macintosh Scrap Manager to copy data from the Clipboard. The GetScrap routine is declared as follows:

long GetScrap (Handle hDest, ResType theType, long& offset);
Depending on how you set the hDest parameter, you can use the GetScrap routine for one of two purposes: to determine if the scrap contains data of a specified type or to retrieve desk scrap data of the specified type in the passed handle.

You normally use GetScrap by calling it once to determine if the appropriate data type is in the scrap. If it is, you then allocate a handle for the data and call GetScrap again to copy the data into that handle. Code to read Clipboard data often looks something like the following:

long  datasize, offset, err;

// First see if your scrap type is present.
datasize = GetScrap(NULL, kMyPrivateScrapType, &offset);
if  (datasize > 0)
   // Now copy the scrap data into an existing handle field.
   // NOTE: Some apps set the handle size to the returned data size
   //     value before calling GetScrap the second time.
   err=  GetScrap(fMyDataHandle, kMyPrivateScrapType, &offset);
   // If we can't read data, cause a failure and display the error.
   if  (err < 0)
      FailOSErr((short) err);
In this example, the fMyDataHandle field is a data handle that was created earlier. For another example of reading desk scrap data, see "Recipe--Creating a Clipboard View for Your Private Data Type," beginning on page 508.

Within your application, you can get Clipboard data by calling the global Clipboard manager's GetDataToPaste method. The manager is described in "The Clipboard Manager," beginning on page 504.

Using a Private Scrap

Your application can set up a private scrap for storing data that is cut and pasted internally. If you cut and paste only the standard data types, it's probably easier to use the desk scrap, but if you need to work with large amounts of data, a private scrap may result in faster Clipboard operations within your application.

To use a private scrap, your application must be able to convert data from its private scrap format to a public desk scrap format when it is switched out, and back from the public desk scrap format to its private format when it is switched in. Figure 22-1 shows an application copying its private scrap to the Clipboard when a user quits the application.

Figure 22-1 An application copying its private scrap to the Clipboard

MacApp's Clipboard Support

MacApp's Clipboard support is designed to help your application manage a private scrap. It provides facilities to

When the user cuts or copies data in your application, you create a view to display and handle the data. The display view usually has the same view type as the one that originally displayed the data. This makes it convenient for Clipboard data to be stored in your application's private format, which is easy to use within the application. However, when the user quits or switches to another program, a well-behaved application puts information on the Clipboard in one or both of the standard data types (text and picture), for other applications to use, as well as in its private format.

MacApp's default Clipboard support provides the following features:

Your application can take advantage of MacApp's default Clipboard support by adding the following line to the file YourApp.r:

include "Defaults.rsrc" 'CMNU' (mEdit);
This line includes the 'CMNU' resource for the Edit menu, which is defined in the file Defaults.r.

You don't have to create a view to display 'PICT' or 'TEXT' data from the desk scrap. When your application starts, MacApp automatically creates an object of type TDeskScrapView to display these data types.

More Sophisticated Clipboard Support

With a little extra work, your application can support its own private desk scrap data types and provide more sophisticated Clipboard support. MacApp provides several facilities to help you do so.

The Clipboard Manager

The TClipboardMgr class is a subclass of TBehavior that manages the application's interaction with the Scrap Manager and maintains a view for the current Clipboard. MacApp creates a single TClipboardMgr object during initialization of your application and assigns it to the global variable gClipboardMgr. The Clipboard manager works together with your view, application, and document classes to support Clipboard activity in your application. The classes and methods used to provide Clipboard support are shown in Figure 22-2.

Figure 22-2 Classes and methods used to provide Clipboard support

MacApp calls methods of gClipboardMgr at the appropriate time; your application also calls methods of gClipboardMgr during Clipboard operations. The following methods of TClipboardMgr are the most frequently used:

MacApp calls the AboutToLoseControl method when your application is switched out. It gives the current Clipboard view a chance to write its data, converting from a private to a standard data type, if necessary.
Your view class calls CanPaste to let the Clipboard manager know what kind of data it can paste. If that data is available, the Clipboard manager enables the Paste menu command.
The GetDataToPaste method asks the current Clipboard view to return data of the specified type by calling the view's GivePasteData method. You override GivePasteData in the view class you use to provide a Clipboard view. Your Paste command object might call GetDataToPaste to get data to paste.
You pass a data handle and a data type to the PutDeskScrapData method; it writes the handle to the desk scrap.
MacApp calls RegainControl when your application is switched in. It calls CheckDeskScrap to see if there is any new data on the desk scrap. If so, your application gets a chance to make a view to read and display the new data.

Clipboard Support in TCommand

The TCommand class supplies several fields and methods that are used in working with the Clipboard:

The fClipboardView field identifies the view for displaying Clipboard data when a command is in the do or redo phase.
The fUndoClipboardView field identifies the view for displaying Clipboard data when the command is in the undo phase.
The AbandonClipboardView method frees the view referenced by fClipboardView, when appropriate.
The AbandonUndoClipboardView method frees the view referenced by fUndoClipboardView, when appropriate.
The ClaimClipboard method installs the passed view as the fClipboardView and saves the previous value of fClipboardView in fUndoClipboardView.
The UndoRedoClipboard method installs the appropriate Clipboard view, depending on whether the current request is to undo or redo the command.
The recipes that follow describe how your application works with MacApp to provide custom Clipboard support.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
25 JUL 1996