Important: The information in this document is obsolete and should not be used for new development.
PutScrap
You can use thePutScrap
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
ThePutScrap
function writes the specified number of bytes of data from the memory location pointed to by thesource
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 thePutScrap
function whenever it receives a suspend event. Your application can use thePutScrap
function multiple times to write different formats of the same data to the scrap.
If your application writes multiple formats to the scrap, you should write
- 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 callPutScrap
.
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.
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
- 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 usingGetScrap
.DialogCut
orDialogCopy
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 valuenoScrapErr
. ThePutScrap
function returns other nonzero values corresponding to result codes if an error occurs.SPECIAL CONSIDERATIONS
ThePutScrap
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.