Your application specifies the format, or formats, in which data is written to, and read from, the desk scrap. Your application should write that data using the so-called standard formats (in addition to any other format it might specify), since this ensures that a user can copy and paste data between documents created by your application and other applications as well as within and between documents created by your application. The ultimate aim is to allow the user to:

• Copy and paste data within a document created by your application.

• Copy and paste data between different documents created by your application.

• Copy and paste data between documents created by your application and documents created by other applications.

• 'TEXT', that is, a series of ASCII characters.

• 'PICT', that is, a QuickDraw picture.

• 'snd ', that is, a series of bytes which define a sound, and which have the same format as a 'snd ' resource.

• 'movv', that is, a series of bytes which define a movie, and which have the same format as a 'movv' resource.

• 'styl', that is, a series of bytes which have the same format as a TextEdit 'styl' resource, and which describe styled text data.

When system software launches an application, it copies the data from the scrap of the previously active application into the application heap of the newly active application. If the scrap is too large to fit in the application's application heap, system software copies the scrap to disk and sets the value of the handle to the scrap in the application's heap to NULL to indicate that the scrap is on disk.

Getting Information About the Desk Scrap

• The size, in bytes, of the scrap.

• A handle to the scrap (if it is in memory).

• The location of the scrap (memory or disk).

• The filename of the scrap when it is on disk.

Note that, if your application implements a Clear command, it should remove the data in the current selection range but should not save the data to the desk scrap.

Cut and Copy - Putting Data in the Scrap

• Determine whether the frontmost window is a document window or a dialog box.

• If the frontmost window is a document window:

  • Call an application-defined function which determines whether the current selection contains text or whether it contains graphics.

  • Get a pointer to the selection range data and get the selection length.

  • Call ZeroScrap to purge the current contents of the desk scrap.

  • Call PutScrap to write the data to the scrap, specifying 'TEXT' or 'PICT', as appropriate, as the format type.

  • If the command was the Cut command, delete the selection from the current document.

• If the frontmost window is a dialog box, use the Dialog Manager functions DialogCut or DialogCopy, as appropriate, to write the selected data to the scrap.

When you read the data from the scrap, your application should request the data in the application's preferred format type. If your application determines that that format does not exist in the scrap, it should then request the data in another format. If your application does not have a preferred format type, it should read each format type that your application supports.

If you request a scrap format that is not in the scrap, the Scrap Manager uses the Translation Manager to convert any one of the scrap format types currently in the scrap into the scrap format requested by your application. The Translation Manager looks in the Extensions folder for a translator that can perform one of these translations. If such a translator is available, the Translation Manager uses the translator to translate the data in the scrap into the requested format type.

A typical approach, for an application that prefers a data format other than 'TEXT' or 'PICT' as its first preference, is as follows:

• Determine whether the frontmost window is a document window or a dialog box.

• If the frontmost window is a document window:

  • Call GetScrap to search the scrap for the preferred format type. (If you specify a NULL handle as the location to which to return the data, GetScrap does not return the data but does return as its function result the number of bytes (if any) of data in the specified format that exists in the scrap. Thus, if GetScrap returns a non-positive value, data of that format type does not exist.)

  • If data of the specified format does exist, allocate a handle to hold the data from the scrap and call GetScrap again to read in the data in that format. (GetScrap automatically resizes the handle passed to it to the required size.)

  • If the scrap does not contain data of the preferred format type, repeat the above process specifying 'TEXT' as the format type in the calls to GetScrap. If this is not successful, repeat the process again specifying 'PICT' as the format type.

  • Paste the data to the current document.

• If the frontmost window is a dialog box, use the Dialog Manager function DialogPaste to paste the text from the scrap in the dialog.

In the first case, the source application has chosen to write only the 'PICT' format to the desk scrap, and the destination application has pasted the data to its document in that format.

In the second case, the source application has chosen to write both the 'PICT' and the 'TEXT' formats to the desk scrap, and the destination application has chosen the 'TEXT' format as the preferred format for the paste. The data is thus inserted into the document as editable text.

The Clipboard

Although multiple scrap format types can reside in the desk scrap, applications which support a Clipboard window typically display the data in one format only.

Transferring the Desk Scrap to Disk

In addition, an application which uses a private scrap must take the following actions on receipt of suspend and resume events:

• Suspend Event. On receipt of a suspend event, the data from the private scrap must be copied to the desk scrap. If your application supports the Show Clipboard command, the Clipboard window must be hidden if it is currently showing (because the contents of the scrap may change while the application yields time to another application).

• Resume Event. On receipt of a resume event, your application must determine if the data in the desk scrap has changed since the previous suspend event and, if so, copy the data from the desk scrap to its private scrap either immediately or when the user next chooses the Paste command. In addition, if your application supports the Show Clipboard command, and if the data in the desk scrap has changed, your application must update the contents of the Clipboard window.

The process of copying data between an application's document, an application's private scrap, and the desk scrap in response to suspend and resume events is shown diagrammatically at Fig 2.

Copying Data Between Private Scrap and the Desk Scrap

• Resume Event. When a resume event is received, and a check indicates that the contents of the desk scrap have changed since the last suspend event:

  • Call GetScrap, with NULL passed as the destHandle parameter, to determine if the scrap contains data in the 'PICT' format type. If data of that format type exists:

    • Allocate a handle to hold the data from the scrap and call GetScrap again to read in the data.

    • Call an application-defined function to copy the data to the private scrap.

    • Dispose of the handle.

  • If data of the 'PICT' format type does not exist in the scrap, repeat this process specifying 'TEXT' as the data format type.

• Suspend Event. When a suspend event is received:

  • Call an application-defined function which determines if there is any data in the private scrap. If there is data in the private scrap, call ZeroScrap to empty the desk scrap.

  • Create a non-relocatable block to receive the private scrap data.

  • For each appropriate data format type:

    • Determine if data in that format exists in the private scrap.

    • If data in that format type exists in the private scrap, call an application-defined function which gets the data from the private scrap into the nonrelocatable block. Then call PutScrap to copy the data from the nonrelocatable block to the scrap.

  • Dispose of the nonrelocatable block.

If your application uses TextEdit in its windows, be aware that TextEdit maintains its own private scrap. Accordingly:

• PutScrap is not used and the special TextEdit functions TECut, TECopy, and TEToScrap are used in the processes of cutting text from the document and copying text to the TextEdit private scrap and to the desk scrap.

• GetScrap is not used and the special TextEdit functions TEPaste, TEStylePaste, and TEFromScrap are used in the processes of pasting text from the TextEdit private scrap and copying text from the desk scrap to the TextEdit private scrap.

You can use the Dialog Manager to handle most editing operations within dialog boxes. The Dialog Manager functions DialogCut, DialogCopy, and DialogPaste may be used to implement Cut, Copy and Paste commands within editable text items in dialog boxes. (See the demonstration program at Chapter 8 - Dialogs and Alerts.)

TextEdit's private scrap facilitates the copying and pasting of data between dialog boxes. However, your application must ensure that the user can copy and paste data between your application's dialog boxes and its document windows. If your application uses TextEdit for all editing operations within its document windows, this is easily achieved because TextEdit's TECut, TECopy, TEPaste, and TEStylePaste functions and the Dialog Manager's DialogCut, DialogCopy, and DialogPaste functions all use TextEdit's private scrap.

If your application does not use TextEdit for text handling within its document windows, and if it uses a private scrap, then, when the user activates a dialog box, you should copy any data in your private scrap to TextEdit's private scrap. Also, when a document window becomes active, and there is data in TextEdit's private scrap, that data should be copied to your application's private scrap (or to the desk scrap if your application does not use a private scrap).

Similarly, before displaying the Standard File Package's save dialog box, your application should copy any text data in its private scrap to the desk scrap. The Standard File Package reads the data from the desk scrap whenever the user chooses an editing operation and a standard file dialog box is active. Accordingly, your application needs to put the text data (if any) from the last cut or copy in the desk scrap before calling StandardPutFile.

Main Scrap Manager Data Types and Functions

struct ScrapStuff
{
  SInt32    scrapSize;    // Size of scrap in bytes.
  Handle    scrapHandle;  // Handle to scrap.
  SInt16    scrapCount;   // Indicates whether contents of scrap have changed.
  SInt16    scrapState;   // Indicates state and location of scrap
  StringPtr scrapName;    // Filename of scrap.
};
typedef struct ScrapStuff ScrapStuff;
typedef ScrapStuff *PScrapStuff;
typedef ScrapStuff *ScrapStuffPtr;

ScrapStuffPtr  InfoScrap(void);

SInt32  ZeroScrap(void);
SInt32  PutScrap(long length,ResType theType,void *source);

SInt32  GetScrap(Handle hDest,ResType theType,long *offset);

SInt32  UnloadScrap(void);
SInt32  LoadScrap(void);