Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 2 - Scrap Manager / Scrap Manager Reference

Routines / Reading Information From the Scrap

GetScrap

You can use the GetScrap function to read data of a specific format from the scrap.

FUNCTION GetScrap (hDest: Handle; theType: ResType; 
                   VAR offset: LongInt): LongInt;

hDest

A handle to the memory location where the GetScrap function should place the data from the scrap. If you specify NIL in this parameter, the GetScrap function does not read in the data but does return the offset of the data in the scrap and the number of bytes of the requested scrap data type if the requested type exists in the scrap.

theType

The scrap format type of the data to be read from the scrap.

offset

The GetScrap function returns in this parameter the location of the data in the scrap. This value is expressed as an offset (in bytes) from the beginning of the scrap. If the Translation Manager is available, the value of the offset parameter is undefined.

DESCRIPTION

The GetScrap function looks in the scrap for any data of the requested scrap format type and returns the first data of the requested type that it finds. The GetScrap function writes the data to the memory location specified by the hDest parameter.

The GetScrap function reads the data from the scrap, makes a copy of it in memory, and sets the handle specified by the hDest parameter to refer to this copy. The GetScrap function resizes the handle specified by the hDest parameter if necessary.

Your application can use the GetScrap function multiple times to read different formats of the same data from the scrap. If more than one format of the same scrap format type exists in the scrap, the GetScrap function returns the first occurrence of that format type that it finds. For example, if data of type 'TEXT', 'PICT', and 'TEXT' exist on the scrap, and your application requests the data in the scrap with scrap format type 'TEXT', the GetScrap function returns the first data of type 'TEXT' that it finds.

If your application supports more than one scrap format type, your application should attempt to read its preferred scrap format type first. If your application doesn't prefer one scrap format type over any other type, it should try reading each of the scrap format types that it supports and use the type that returns the lowest offset. The scrap
format type with the lowest offset indicates that this format type was written before any of the others and therefore was preferred by the application that wrote it.

Note

The returned value for the offset parameter is valid only if the Translation Manager isn't available; if the Translation Manager is available, then your application should not rely on the offset value.

If you request a scrap format type that isn't in the scrap and the Translation Manager is available, the Scrap Manager uses the Translation Manager to convert the data of a scrap format type that does exist in the scrap into the scrap format type requested by your application. For example, if the SurfWriter application requests data from the scrap in the 'SURF' scrap format type, and the data in the scrap is available in the format types 'TEXT', 'PICT', and 'SDBS'(SurfDB's private scrap format type ), the Scrap Manager uses the Translation Manager to convert any one of the scrap format types 'TEXT', 'PICT', or'SDBS' into the 'SURF' scrap format type. The Translation Manager looks for a translator that can perform one of these translations. If such a translator is available (for example, a translator that can translate the 'SDBS' scrap format type into the 'SURF' scrap format type), the Translation Manager uses the translator to translate the data in the scrap into the requested scrap format type. If the translation is successful, the Scrap Manager returns to your application the data from the scrap in the requested scrap format type.

If your application uses TextEdit to handle text in its documents, use TextEdit routines to implement the paste operation and to copy data from the scrap to the TextEdit scrap. If your application uses the Dialog Manager to handle editable text items in your application's dialog boxes and a dialog box is the frontmost window, use the Dialog Manager procedure DialogPaste to copy data from the scrap to the current editable text item.

If the GetScrap function successfully reads the data of the requested scrap format type from the scrap, GetScrap returns as its function result the length (in bytes) of the data. Otherwise, GetScrap returns a negative function result that indicates the error. If GetScrap returns the constant noTypeErr, then the data in the scrap isn't available in the scrap format type requested by your application. If the Translation Manager is available and GetScrap returns the constant noTypeErr, this value also indicates that the Translation Manager could not find any translators to convert the data into the scrap format type requested by your application.

CONST noTypeErr = -102;{no data of the requested scrap format type}

SPECIAL CONSIDERATIONS

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

SEE ALSO

See Listing 2-4 on page 2-21, Listing 2-5 on page 2-24, and Listing 2-7 on page 2-27 for examples that read data from 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.