Next Page >

Hide TOC

Legacy Document

Important: The Scrap Manager is deprecated in Mac OS X version 10.5 and later. The replacement API is the Pasteboard Manager. For more information, see Pasteboard Manager Programming Guide.

Scrap Manager Reference (Not Recommended)

Framework	Carbon/Carbon.h
Declared in	Scrap.h

Overview

Important: The Scrap Manager is deprecated in Mac OS X version 10.5 and later. The replacement API is the Pasteboard Manager. For more information, see Pasteboard Manager Programming Guide.

In Mac OS 9 and earlier, the Scrap Manager allowed applications to copy and paste data using the Clipboard. The Scrap Manager was included in Carbon to facilitate the porting of legacy applications to Mac OS X. Only the LoadScrap and UnloadScrap functions were retained from the original Scrap Manager. However, the Carbon Scrap Manager provided new features, including support for promises.

The Pasteboard Manager supersedes the Scrap Manager and the drag flavor functionality in the Drag Manager, adding greater flexibility in the type and quantity of data to be transferred. Pasteboard Manager pasteboards are also fully compatible with Cocoa pasteboards.

You should not use the Scrap Manager in new application development.

Functions by Task

Getting Information About the Scrap

Reading Information From the Scrap

Writing Information to the Scrap

Transferring Data Between the Scrap in Memory and the Scrap on Disk

Working With Scrap Promise Keeper Functions

Callbacks

ScrapPromiseKeeperProcPtr

Defines a pointer to a function the Scrap Manager calls to obtain promised scrap data for a specified flavor.

typedef OSStatus (*ScrapPromiseKeeperProcPtr)
(
   ScrapRef scrap,
   ScrapFlavorType flavorType,
   void * userData);

If you name your function MyScrapPromiseKeeperCallback, you would declare it like this:

OSStatus MyScrapPromiseKeeperCallback (

   ScrapRef scrap,
   ScrapFlavorType flavorType,
   void * userData);

Parameters

scrap

A reference to the scrap to which to supply the promised flavor data.

flavorType

The flavor type to supply the promised data for. Some scrap flavor types are described in “Scrap Flavor Types.”

userData

An untyped pointer to a buffer, local variable, or other storage location, created and disposed of by your application, and supplied to the Scrap Manager by a previous call to SetScrapPromiseKeeper. For example, this parameter might refer to a pointer or handle to some private scrap data which your promise-keeper function uses in fabricating one or more promised flavors.

This parameter may have a value of NULL.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

To provide a pointer to your promise-keeper function, you create a universal procedure pointer (UPP), using the function NewScrapPromiseKeeperUPP. You can do so with code similar to the following:

ScrapPromiseKeeperUPP MyPromiseKeeperUPP;

MyPromiseKeeperUPP = NewScrapPromiseKeeperUPP (&MyScrapPromiseKeeperCallback);

You can then associate the UPP with a scrap by passing MyScrapPromiseKeeperCallback as a parameter to the SetScrapPromiseKeeper function.

If a promised flavor is requested through GetScrapFlavorData or GetScrapFlavorSize, the Scrap Manager calls the application's ScrapPromiseKeeperProcPtr function. The scrap promise-keeper function should call PutScrapFlavor as appropriate to fulfill its promises. Failure to do so—including returning an error or simply neglecting to keep a promise for a flavor—will result in errors being returned to corresponding callers of GetScrapFlavorData or GetScrapFlavorSize.

Under Mac OS X, the scrap promise-keeper function can be called during any call to GetScrapFlavorData or GetScrapFlavorSize. Under Mac OS 8 and 9, the Carbon Scrap Manager still must support non-Carbon callers of GetScrap, which does not know about promised flavors. As a result, the Carbon Scrap Manager must make sure all promises have been kept when the application is suspended.

It is okay to keep a promise without ever receiving a call to a scrap promise-keeper function. You should not call WaitNextEvent or any similar function from your promise-keeper function because the promise-keeper might be running at suspend event time.

After you are finished with a promise-keeper function, and have removed it by passing NULL to the SetScrapPromiseKeeper function, you can dispose of the UPP with the DisposeScrapPromiseKeeperUPP function. However, don’t dispose of the UPP if any other scrap uses it or if you plan to use it again.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Scrap.h

Data Types

ScrapFlavorInfo

Describes a single flavor within a scrap.

struct ScrapFlavorInfo {
   ScrapFlavorType flavorType;
   ScrapFlavorFlags flavorFlags;
};
typedef struct ScrapFlavorInfo ScrapFlavorInfo;

Fields

flavorType: The flavor type for the flavor. Some values for flavor types are described in “Scrap Flavor Types.”
flavorFlags: The flavor flags for the flavor. Some values for flavor flags are described in “Scrap Flavor Flags.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

Scrap.h

ScrapRef

Defines a reference to a scrap.

typedef struct OpaqueScrapRef * ScrapRef;

Availability

Available in Mac OS X v10.0 and later.

Declared In

Scrap.h

ScrapPromiseKeeperUPP

Defines a universal procedure pointer to a scrap promise–keeper function.

typedef ScrapPromiseKeeperProcPtr ScrapPromiseKeeperUPP;

Discussion

See ScrapPromiseKeeperProcPtr for more information on scrap promise–keeper functions.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Scrap.h

ScrapFlavorType

Defines a scrap flavor type.

typedef FourCharCode ScrapFlavorType;

Discussion

Some values for scrap flavor types are shown in “Scrap Flavor Types.”

Availability

Available in Mac OS X v10.0 and later.

Declared In

Scrap.h

Constants

Scrap Flavor Types

Identify commonly used scrap flavor types.

enum {
   kScrapFlavorTypePicture = 'PICT',
   kScrapFlavorTypeText = 'TEXT',
   kScrapFlavorTypeTextStyle = 'styl',
   kScrapFlavorTypeMovie = 'moov',
   kScrapFlavorTypeSound = 'snd ',
   kScrapFlavorTypeUnicode = 'utxt',
   kScrapFlavorTypeUnicodeStyle = 'ustl'
};

Constants

kScrapFlavorTypePicture

Specifies the contents of a PicHandle.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorTypeText

Specifies a stream of text characters.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorTypeTextStyle

Specifies a style scrap structure. For more information, see TEGetStyleScrapHandle in Inside Mac OS X: TextEdit Reference.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorTypeMovie

Specifies a reference to a QuickTime movie.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorTypeSound

Specifies the contents of a 'snd ' resource. For more information, see the functions SndRecord and SndPlay in Inside Mac OS X: Sound Manager Reference.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorTypeUnicode

Specifies a stream of 16-bit Unicode characters.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorTypeUnicodeStyle

Specifies Unicode style information; defined by ATSUI and used by Textension.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

Scrap Flavor Flags

Describe attributes of a scrap flavor.

enum {
   kScrapFlavorMaskNone = 0x00000000,
   kScrapFlavorMaskSenderOnly = 0x00000001,
   kScrapFlavorMaskTranslated = 0x00000002
};
typedef UInt32 ScrapFlavorFlags;

Constants

kScrapFlavorMaskNone

No flavors in the scrap.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorMaskSenderOnly

The flavor is intended to be visible to the sender only. This is typically used to save a private flavor into the scrap so that other public promised flavors can be derived from it on demand. If another process put a flavor with this flag on the scrap, your process will never see the flavor, so you do not need to test for this flag.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

kScrapFlavorMaskTranslated

The flavor has been translated (or will be translated when the promise is kept) from some other flavor in the scrap, either by the sender or by the Translation Manager.

Available in Mac OS X v10.0 and later.

Declared in Scrap.h.

Discussion

To determine the attributes of a scrap flavor, call the GetScrapFlavorFlags function.

Reserved Flavor Type

Identifies a flavor type reserved by the Scrap Manager.

enum {
   kScrapReservedFlavorType = 'srft'
};

Discussion

kScrapReservedFlavorType is a flavor type which is reserved for use by the Scrap Manager. If you pass it to the Scrap Manager, it will be rejected.

Unknown Flavor Data Size Constant

Indicates that the size of the scrap flavor data is unknown.

enum {
   kScrapFlavorSizeUnknown = -1
};

Discussion

When promising a scrap flavor, it is okay if you don't yet know how big the flavor data will be. In this case, pass kScrapFlavorSizeUnknown for the flavor data size.

Options for the GetScrapByName Function

Define options passed to the GetScrapByName function.

enum {
   kScrapGetNamedScrap = 0,
   kScrapClearNamedScrap = 0x00000001
};

Constants

kScrapGetNamedScrap

Get current named scrap without bumping or clearing the scrap.

Available in Mac OS X v10.1 and later.

Declared in Scrap.h.

kScrapClearNamedScrap

Acquire the named scrap, bumping and clearing the scrap.

Available in Mac OS X v10.1 and later.

Declared in Scrap.h.

Invalid Scrap Reference

Defines an invalid scrap reference.

#define kScrapRefNone ((ScrapRef)NULL)

Discussion

kScrapRefNone is guaranteed to be an invalid ScrapRef. This is convenient when initializing application variables.

Named Scraps

Specify Apple–defined scrap names for the GetScrapByName function.

#define kScrapClipboardScrap CFSTR("com.apple.scrap.clipboard")
#define kScrapFindScrap CFSTR("com.apple.scrap.find")

Constants

kScrapClipboardScrap

Traditional clipboard scrap.

Available in Mac OS X v10.1 and later.

Declared in Scrap.h.

kScrapFindScrap

Compatible with Cocoa's global find scrap.

Available in Mac OS X v10.1 and later.

Declared in Scrap.h.

Result Codes

The most common result codes returned by Scrap Manager are listed below.

Result Code	Value	Description
`needClearScrapErr`	-100	Scrap does not exist (same as `noScrapErr`) Available in Mac OS X v10.0 and later.
`noScrapErr`	-100	Scrap does not exist (not initialized) Available in Mac OS X v10.0 and later.
`noTypeErr`	-102	No data of the requested format type in scrap Available in Mac OS X v10.0 and later.
`scrapFlavorNotFoundErr`	-102	No data of the requested format type in scrap (same as `noTypeErr`) Available in Mac OS X v10.0 and later.
`internalScrapErr`	-4988	Scrap Manager has encountered an internal error Available in Mac OS X v10.0 and later.
`duplicateScrapFlavorErr`	-4989	Data (or a promise for data) of the specified format already exists in the scrap Available in Mac OS X v10.0 and later.
`badScrapRefErr`	-4990	Invalid scrap reference Available in Mac OS X v10.0 and later.
`processStateIncorrectErr`	-4991	Available in Mac OS X v10.0 and later.
`scrapPromiseNotKeptErr`	-4992	No data supplied for the promised flavor Available in Mac OS X v10.0 and later.
`noScrapPromiseKeeperErr`	-4993	No scrap promise–keeper function set for the scrap Available in Mac OS X v10.0 and later.
`nilScrapFlavorDataErr`	-4994	Available in Mac OS X v10.0 and later.
`scrapFlavorFlagsMismatchErr`	-4995	Available in Mac OS X v10.0 and later.
`scrapFlavorSizeMismatchErr`	-4996	Available in Mac OS X v10.0 and later.
`illegalScrapFlavorFlagsErr`	-4997	Invalid scrap flavor flags Available in Mac OS X v10.0 and later.
`illegalScrapFlavorTypeErr`	-4998	Invalid scrap flavor Available in Mac OS X v10.0 and later.
`illegalScrapFlavorSizeErr`	-4999	Invalid size for scrap flavor data Available in Mac OS X v10.0 and later.

Gestalt Constants

You can check for version and feature availability information by using the Scrap Manager selectors defined in the Gestalt Manager. For more information see Gestalt Manager Reference.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.