- Generated by
1.9.1
|
Mac OS 9
|
Scrap Manager Interfaces. More...
Go to the source code of this file.
Data Structures | |
| struct | ScrapStuff |
| struct | ScrapFlavorInfo |
Macros | |
| #define | kScrapRefNone ((ScrapRef)NULL) |
| #define | kScrapClipboardScrap CFSTR("com.apple.scrap.clipboard") |
| #define | kScrapFindScrap CFSTR("com.apple.scrap.find") |
| #define | NewScrapPromiseKeeperUPP(userRoutine) |
| #define | DisposeScrapPromiseKeeperUPP(userUPP) DisposeRoutineDescriptor(userUPP) |
| #define | InvokeScrapPromiseKeeperUPP(scrap, flavorType, userData, userUPP) |
| #define | NewScrapPromiseKeeperProc(userRoutine) NewScrapPromiseKeeperUPP(userRoutine) |
| #define | CallScrapPromiseKeeperProc(userRoutine, scrap, flavorType, userData) InvokeScrapPromiseKeeperUPP(scrap, flavorType, userData, userRoutine) |
Typedefs | |
| typedef FourCharCode | ScrapFlavorType |
| typedef struct ScrapStuff | ScrapStuff |
| typedef ScrapStuff * | PScrapStuff |
| typedef ScrapStuff * | ScrapStuffPtr |
| typedef UInt32 | ScrapFlavorFlags |
| typedef struct ScrapFlavorInfo | ScrapFlavorInfo |
| typedef struct OpaqueScrapRef * | ScrapRef |
| typedef ScrapFlavorType | flavorType |
| typedef ScrapFlavorType void * | userData |
Enumerations | |
| enum | { kScrapFlavorTypePicture , kScrapFlavorTypeText = FOUR_CHAR_CODE('TEXT') , kScrapFlavorTypeTextStyle , kScrapFlavorTypeMovie = FOUR_CHAR_CODE('moov') , kScrapFlavorTypeSound , kScrapFlavorTypeUnicode , kScrapFlavorTypeUnicodeStyle } |
| enum | { kScrapFlavorSizeUnknown = -1 } |
| enum | { kScrapReservedFlavorType = FOUR_CHAR_CODE('srft') } |
| enum | { kScrapFlavorMaskNone = 0x00000000 , kScrapFlavorMaskSenderOnly = 0x00000001 , kScrapFlavorMaskTranslated = 0x00000002 } |
| enum | { kScrapGetNamedScrap = 0 , kScrapClearNamedScrap } |
| enum | { uppScrapPromiseKeeperProcInfo = 0x00000FF0 } |
Functions | |
| OSStatus | LoadScrap (void) |
| OSStatus | UnloadScrap (void) |
| ScrapStuffPtr | InfoScrap (void) |
| long | GetScrap (Handle destination, ScrapFlavorType flavorType, SInt32 *offset) |
| OSStatus | ZeroScrap (void) |
| OSStatus | PutScrap (SInt32 sourceBufferByteCount, ScrapFlavorType flavorType, const void *sourceBuffer) |
| OSStatus | GetScrapByName (CFStringRef name, OptionBits options, ScrapRef *scrap) |
| OSStatus | GetCurrentScrap (ScrapRef *scrap) |
| OSStatus | GetScrapFlavorFlags (ScrapRef scrap, ScrapFlavorType flavorType, ScrapFlavorFlags *flavorFlags) |
| OSStatus | GetScrapFlavorSize (ScrapRef scrap, ScrapFlavorType flavorType, Size *byteCount) |
| OSStatus | GetScrapFlavorData (ScrapRef scrap, ScrapFlavorType flavorType, Size *byteCount, void *destination) |
| OSStatus | ClearCurrentScrap (void) |
| OSStatus | ClearScrap (ScrapRef *inOutScrap) |
| OSStatus | PutScrapFlavor (ScrapRef scrap, ScrapFlavorType flavorType, ScrapFlavorFlags flavorFlags, Size flavorSize, const void *flavorData) |
| typedef | CALLBACK_API (OSStatus, ScrapPromiseKeeperProcPtr)(ScrapRef scrap |
| typedef | STACK_UPP_TYPE (ScrapPromiseKeeperProcPtr) ScrapPromiseKeeperUPP |
| ScrapPromiseKeeperUPP | NewScrapPromiseKeeperUPP (ScrapPromiseKeeperProcPtr userRoutine) |
| void | DisposeScrapPromiseKeeperUPP (ScrapPromiseKeeperUPP userUPP) |
| OSStatus | InvokeScrapPromiseKeeperUPP (ScrapRef scrap, ScrapFlavorType flavorType, void *userData, ScrapPromiseKeeperUPP userUPP) |
| OSStatus | SetScrapPromiseKeeper (ScrapRef scrap, ScrapPromiseKeeperUPP upp, const void *userData) |
| OSStatus | GetScrapFlavorCount (ScrapRef scrap, UInt32 *infoCount) |
| OSStatus | GetScrapFlavorInfoList (ScrapRef scrap, UInt32 *infoCount, ScrapFlavorInfo info[]) |
| OSStatus | CallInScrapPromises (void) |
Scrap Manager Interfaces.
For bug reports, consult the following page on the World Wide Web:
http://developer.apple.com/bugreporter/
| #define InvokeScrapPromiseKeeperUPP | ( | scrap, | |
| flavorType, | |||
| userData, | |||
| userUPP | |||
| ) |
| #define kScrapClipboardScrap CFSTR("com.apple.scrap.clipboard") |
Defined Apple scrap names for GetScrapByName kScrapClipboardScrap traditional clipboard scrap kScrapFindScrap compatable with Cocoa's global find scrap
| #define kScrapRefNone ((ScrapRef)NULL) |
kScrapRefNone is guaranteed to be an invalid ScrapRef. This is convenient when initializing application variables.
| #define NewScrapPromiseKeeperProc | ( | userRoutine | ) | NewScrapPromiseKeeperUPP(userRoutine) |
support for pre-Carbon UPP routines: New...Proc and Call...Proc
| #define NewScrapPromiseKeeperUPP | ( | userRoutine | ) |
pascal 4_bytes Func(4_bytes, 4_bytes, 4_bytes)
| typedef FourCharCode ScrapFlavorType |
UNIVERSAL SCRAP MANAGER INTERFACES
The following interfaces are available when compiling for BOTH Carbon AND Mac OS 8.
While we're in here mucking about, we defined a new type to to put some confusion to rest. The old calls, as well as the new calls, use the new type. Existing clients should be blissfully ignorant.
| anonymous enum |
Newsflash! After 15 years of arduous toil, it's finally possible for specially trained typists wielding advanced text editing technology to define symbolic names for commonly used scrap flavor type constants! Apple triumphs again!
| anonymous enum |
CARBON SCRAP MANAGER INTERFACES
The following interfaces are available only when compiling for Carbon.
When promising a scrap flavor, it's OK if you don't yet know how big the flavor data will be. In this case, just pass kScrapFlavorSizeUnknown for the flavor data size. CALL_NOT_IN_CARBON
| anonymous enum |
kScrapReservedFlavorType is a flavor type which is reserved for use by Scrap Manager. If you pass it to Scrap Manager, it will be rejected.
| anonymous enum |
We've added scrap flavor flags ala Drag Manager.
kScrapFlavorMaskNone means you want none of the flags.
kScrapFlavorSenderOnlyMask means only the process which put the flavor on the scrap can see it. If some other process put a flavor with this flag on the scrap, your process will never see the flavor, so there's no point in testing for this flag.
kScrapFlavorTranslated means the flavor was translated from some other flavor in the scrap by Translation Manager. Most callers should not care about this bit.
| anonymous enum |
| typedef CALLBACK_API | ( | OSStatus | , |
| ScrapPromiseKeeperProcPtr | |||
| ) |
can be NULL ScrapPromiseKeeper is a function you write which is called by Scrap Manager as needed to keep your earlier promise of a particular scrap flavor. When your function is called, deliver the requested data by calling PutScrapFlavor.
| OSStatus CallInScrapPromises | ( | void | ) |
CallInScrapPromises forces all promises to be kept. If your application promises at least one flavor AND it does NOT adopt the new event model, you should call this function when your application is about to quit. If your app promises no flavors, there is no need to call this function, and if your app adopts the new event model, this function will be called automagically for you. It doesn't hurt to call this function more than once, though promise keepers may be asked to keep promises they already tried and failed. CallInScrapPromises()
| OSStatus ClearCurrentScrap | ( | void | ) |
ClearCurrentScrap clears the current scrap. Call this first when the user requests a Copy or Cut operation – even if you maintain a private scrap! You should not wait until receiving a suspend event to call ClearCurrentScrap. Call it immediately after the user requests a Copy or Cut operation. You don't need to put any data on the scrap immediately (although it's perfectly fine to do so). You DO need to call GetCurrentScrap after ClearCurrentScrap so you'll have a valid ScrapRef to pass to other functions. ClearCurrentScrap()
| OSStatus ClearScrap | ( | ScrapRef * | inOutScrap | ) |
ClearScrap will clear the scrap passed in and return the bumped ScrapRef value. ClearScrap behaves similarly to GetScrapByName when called with the kScrapClearNamedScrap option with the benefit of not requiring a name in the event one is not available.
CarbonLib does not support arbitrary named scraps; when calling this API on CarbonLib, only clearing the current scrap is supported. ClearScrap()
| void DisposeScrapPromiseKeeperUPP | ( | ScrapPromiseKeeperUPP | userUPP | ) |
DisposeScrapPromiseKeeperUPP()
| OSStatus GetCurrentScrap | ( | ScrapRef * | scrap | ) |
GetCurrentScrap obtains a reference to the current scrap. The ScrapRef obtained via GetCurrentScrap will become invalid and unusable after the scrap is cleared. GetCurrentScrap()
| long GetScrap | ( | Handle | destination, |
| ScrapFlavorType | flavorType, | ||
| SInt32 * | offset | ||
| ) |
| OSStatus GetScrapByName | ( | CFStringRef | name, |
| OptionBits | options, | ||
| ScrapRef * | scrap | ||
| ) |
GetScrapByName allows access to an indefinite number of public or private scraps. The constant kScrapClipboardScrap refers to the "current" scrap we've all come to know and love. kScrapFindScrap allows Carbon apps to interact seamlessly with Cocoa's global find scrap. Note that calling:
GetScrapByName( kScrapClipboardScrap, kScrapGetNamedScrap, &scrap );
is an exact match to the call:
GetCurrentScrap( &scrap );
Additionally, a call to:
GetScrapByName( kScrapClipboardScrap, kScrapClearNamedScrap, &scrap );
is a replacement for the sequence:
ClearCurrentScrap(); GetCurrentScrap( &scrap );
You can use this API to generate your own private scraps to use as a high level interprocess communication between your main and helper apps. The Java naming convention is suggested for your scraps ( ie. com.joeco.scrap.secret ).
CarbonLib does not support arbitrary named scraps; when calling this API on CarbonLib, kScrapClipboardScrap is the only supported value for the name parameter. GetScrapByName()
| OSStatus GetScrapFlavorCount | ( | ScrapRef | scrap, |
| UInt32 * | infoCount | ||
| ) |
GetScrapFlavorCount produces the number of items which can be obtained by GetScrapFlavorInfoList. GetScrapFlavorCount()
| OSStatus GetScrapFlavorData | ( | ScrapRef | scrap, |
| ScrapFlavorType | flavorType, | ||
| Size * | byteCount, | ||
| void * | destination | ||
| ) |
GetScrapFlavorData gets the data from the specified flavor in the specified scrap. This function blocks until the specified flavor data is available. Specify the maximum size your buffer can contain; on output, this function produces the number of bytes that were available (even if this is more than you requested). GetScrapFlavorData()
| OSStatus GetScrapFlavorFlags | ( | ScrapRef | scrap, |
| ScrapFlavorType | flavorType, | ||
| ScrapFlavorFlags * | flavorFlags | ||
| ) |
GetScrapFlavorFlags tells you [a] whether the scrap contains data for a particular flavor and [b] some things about that flavor if it exists. This call never blocks, and is useful for deciding whether to enable the Paste item in your Edit menu, among other things. GetScrapFlavorFlags()
| OSStatus GetScrapFlavorInfoList | ( | ScrapRef | scrap, |
| UInt32 * | infoCount, | ||
| ScrapFlavorInfo | info[] | ||
| ) |
GetScrapFlavorInfoList fills a list (array) of items which each describe the corresponding flavor in the scrap. It fills no more array elements as are specified. On exit, it produces the count of elements it filled (which may be smaller than the count requested). Yes, YOU must provide the memory for the array. GetScrapFlavorInfoList()
| OSStatus GetScrapFlavorSize | ( | ScrapRef | scrap, |
| ScrapFlavorType | flavorType, | ||
| Size * | byteCount | ||
| ) |
GetScrapFlavorSize gets the size of the data of the specified flavor. This function blocks until the specified flavor data is available. GetScrapFlavorSize is intended as a prelude to allocating memory and calling GetScrapFlavorData. GetScrapFlavorSize()
| ScrapStuffPtr InfoScrap | ( | void | ) |
CALL_NOT_IN_CARBON
\brief Get information about the desk scrap <pre>Use InfoScrap to learn the size of the desk scrap, whether it is currently in
memory or on disk, and other information.
a pointer to the global scrap information packet (a 16-byte ScrapStuff structure).
In the 128K ROMs, InfoScrap performs the additional function of calling ZeroScrap if the scrap is uninitialized. C programmers may prefer to access the global variable ScrapInfo (a ScrapStuff structure starting at 0x0960), e.g., if ( ScrapStuff .scrapState > 0 ) { ... scrap is currently in memory ... } Note that this technique does not automatically call ZeroScrap -something you should do if ScrapStuff .scrapState is negative (uninitialized). If your application displays the Clipboard or uses a private scrap, you may wish to check the value of the scrapCount field on each pass through the main event loop. If this value changes, it is a pretty good indication that some new data has been placed into the scrap (since applications and DAs usually call ZeroScrap before calling PutScrap ).
| OSStatus InvokeScrapPromiseKeeperUPP | ( | ScrapRef | scrap, |
| ScrapFlavorType | flavorType, | ||
| void * | userData, | ||
| ScrapPromiseKeeperUPP | userUPP | ||
| ) |
| OSStatus LoadScrap | ( | void | ) |
If you are a Carbon client and you need to run on Mac OS 8, you may still need to load and unload the scrap. Under Mac OS X, the scrap is held by the pasteboard server instead of in a handle in your app's heap, so LoadScrap and UnloadScrap do nothing when called under Mac OS X. LoadScrap()
| ScrapPromiseKeeperUPP NewScrapPromiseKeeperUPP | ( | ScrapPromiseKeeperProcPtr | userRoutine | ) |
| OSStatus PutScrap | ( | SInt32 | sourceBufferByteCount, |
| ScrapFlavorType | flavorType, | ||
| const void * | sourceBuffer | ||
| ) |
| OSStatus PutScrapFlavor | ( | ScrapRef | scrap, |
| ScrapFlavorType | flavorType, | ||
| ScrapFlavorFlags | flavorFlags, | ||
| Size | flavorSize, | ||
| const void * | flavorData | ||
| ) |
PutScrapFlavor is a lot like PutScrap, with two differences: we added a ScrapRef parameter at the beginning and you can "promise" various aspects of a flavor. If you pass a NIL data pointer, this is a promise that in the future you will provide data for this flavor. Provide the data through a subsequent call to PutScrapFlavor, either later in the same code flow or during a scrap promise keeper proc. If you know how big the data is, you can pass the size as well, and this may allow subsequent callers of GetScrapFlavorInfo to avoid blocking. If you don't know the size, pass -1. If you pass a 0 size, you are telling Scrap Manager not to expect any data for this flavor. In this case, the flavor data pointer is ignored. NOTE: the last time you can provide scrap flavor data is when your scrap promise keeper gets called. It is NOT possible to call PutScrapFlavor while handling a suspend event; suspend events under Carbon simply don't work the way they do under Mac OS 8. The method for setting Scrap Manager promises differs from that for Drag
Manger promises. This chart describes the method for setting scrap promises via PutScrapFlavor().
dataPtr dataSize result
pointer value actual data size The data of size dataSize pointed to by dataPtr is added to the scrap. 0 actual data size A promise for data of size dataSize is placed on the scrap. 0 -1 A promise for data of an undetermined size is placed on the scrap. ignored 0 A flavor with no data expected is placed on the scrap. This is not a promise. PutScrapFlavor()
| OSStatus SetScrapPromiseKeeper | ( | ScrapRef | scrap, |
| ScrapPromiseKeeperUPP | upp, | ||
| const void * | userData | ||
| ) |
CALL_NOT_IN_CARBON SetScrapPromiseKeeper associates a ScrapPromiseKeeper with a scrap. You can remove a ScrapPromiseKeeper from a scrap by passing a NIL ScrapPromiseKeeper to SetScrapPromiseKeeper. Pass whatever you like in the last parameter; its value will be passed to your ScrapPromiseKeeper, which can do whatever it likes with the value. You might choose to pass a pointer or handle to some private scrap data which the ScrapPromiseKeeper could use in fabricating one or more promised flavors. SetScrapPromiseKeeper()
| OSStatus UnloadScrap | ( | void | ) |
| OSStatus ZeroScrap | ( | void | ) |
1.9.1