Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 2 - Scrap Manager / Scrap Manager Reference

Routines / Writing Information to the Scrap

PutScrap

You can use the PutScrap function to write data in a specific format to the scrap.

FUNCTION PutScrap (length: LongInt; theType: ResType; source: Ptr)
                  : LongInt;

length

The number of bytes of data to write to the scrap.

theType

The scrap format type of the data to be written to the scrap. The scrap format type is a four-character sequence that refers to the particular
data format, such as 'TEXT', 'PICT', 'styl', 'snd ', or 'movv'.

source

A pointer to the data that the PutScrap function should write to the scrap.

DESCRIPTION

The PutScrap function writes the specified number of bytes of data from the memory location pointed to by the source parameter to the scrap. The Scrap Manager writes the data to the current location of the scrap (your application's heap or disk).

Whenever your application needs to write data to the scrap as a result of a cut or copy operation, your application uses the PutScrap function to write a representation of the data to the scrap. If your application uses a private scrap, it should copy data from its private scrap to the scrap using the PutScrap function whenever it receives a suspend event. Your application can use the PutScrap function multiple times to write different formats of the same data to the scrap.

IMPORTANT

Whenever your application needs to write data in one or more formats to the scrap, you should call ZeroScrap before the first time you call PutScrap.

If your application writes multiple formats to the scrap, you should write
your application's preferred scrap format type first. For example, if the SurfWriter application's preferred scrap format type is a private scrap format type called 'SURF' and SurfWriter also supports the scrap format types 'TEXT' and 'PICT', then SurfWriter should write the data to the scrap using the 'SURF' scrap format type first, and then write any other scrap format types that it supports in subsequent order of preference.

WARNING

Do not write data to the scrap that has the same scrap format type as any data already in the scrap. If you do so, the new data is appended to the scrap. Note that when you request data from the scrap using the GetScrap function, GetScrap returns the first data that it finds with the requested scrap format type; thus you cannot retrieve any appended data of the same format type using GetScrap.

If your application uses TextEdit to handle text in its documents, use TextEdit routines to implement cut and copy operations and to write the TextEdit scrap to the scrap. If your application uses the Dialog Manager to handle editable text in your application's dialog boxes and a dialog box is the frontmost window, use the Dialog Manager procedure DialogCut or DialogCopy to copy the data from the current editable text item to the scrap.

If the scrap does not already exist (in memory or on the disk), the PutScrap function returns a long integer with the value noScrapErr. The PutScrap function returns other nonzero values corresponding to result codes if an error occurs.

SPECIAL CONSIDERATIONS

The PutScrap function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

RESULT CODES

noErr	0	No error
noScrapErr	-100	Scrap does not exist (not initialized)

SEE ALSO

See Listing 2-1 on page 2-16, Listing 2-2 on page 2-18, and Listing 2-7 on page 2-27 for examples that write data to the scrap. If your application uses a private scrap, see "Handling Editing Operations in Dialog Boxes" on page 2-31 for information on maintaining consistency of the scrap when copying and pasting data between document windows and dialog boxes. See Inside Macintosh: Text for information on TextEdit. See Inside Macintosh: Imaging with QuickDraw for information on the QuickDraw 'PICT' format.