1 {
2 File: HIToolbox/Scrap.h
3
4 Contains: Scrap Manager Interfaces.
5
6 Version: HIToolbox-437~1
7
8 Copyright: � 1985-2008 by Apple Computer, Inc., all rights reserved
9
10 Bugs?: For bug reports, consult the following page on
11 the World Wide Web:
12
13 http://bugs.freepascal.org
14
15 }
16 { Pascal Translation Updated: Peter N Lewis, <peter@stairways.com.au>, August 2005 }
17 { Pascal Translation Updated: Jonas Maebe, <jonas@freepascal.org>, October 2009 }
18 { Pascal Translation Updated: Jonas Maebe, <jonas@freepascal.org>, October 2012 }
19 {
20 Modified for use with Free Pascal
21 Version 308
22 Please report any bugs to <gpc@microbizz.nl>
23 }
24
25 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
26 {$mode macpas}
27 {$modeswitch cblocks}
28 {$packenum 1}
29 {$macro on}
30 {$inline on}
31 {$calling mwpascal}
32
33 unit Scrap;
34 interface
35 {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
36 {$setc GAP_INTERFACES_VERSION := $0308}
37
38 {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
39 {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
40 {$endc}
41
42 {$ifc defined CPUPOWERPC and defined CPUI386}
43 {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
44 {$endc}
45 {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
46 {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
47 {$endc}
48
49 {$ifc not defined __ppc__ and defined CPUPOWERPC32}
50 {$setc __ppc__ := 1}
51 {$elsec}
52 {$setc __ppc__ := 0}
53 {$endc}
54 {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
55 {$setc __ppc64__ := 1}
56 {$elsec}
57 {$setc __ppc64__ := 0}
58 {$endc}
59 {$ifc not defined __i386__ and defined CPUI386}
60 {$setc __i386__ := 1}
61 {$elsec}
62 {$setc __i386__ := 0}
63 {$endc}
64 {$ifc not defined __x86_64__ and defined CPUX86_64}
65 {$setc __x86_64__ := 1}
66 {$elsec}
67 {$setc __x86_64__ := 0}
68 {$endc}
69 {$ifc not defined __arm__ and defined CPUARM}
70 {$setc __arm__ := 1}
71 {$elsec}
72 {$setc __arm__ := 0}
73 {$endc}
74 {$ifc not defined __arm64__ and defined CPUAARCH64}
75 {$setc __arm64__ := 1}
76 {$elsec}
77 {$setc __arm64__ := 0}
78 {$endc}
79
80 {$ifc defined cpu64}
81 {$setc __LP64__ := 1}
82 {$elsec}
83 {$setc __LP64__ := 0}
84 {$endc}
85
86
87 {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
88 {$error Conflicting definitions for __ppc__ and __i386__}
89 {$endc}
90
91 {$ifc defined __ppc__ and __ppc__}
92 {$setc TARGET_CPU_PPC := TRUE}
93 {$setc TARGET_CPU_PPC64 := FALSE}
94 {$setc TARGET_CPU_X86 := FALSE}
95 {$setc TARGET_CPU_X86_64 := FALSE}
96 {$setc TARGET_CPU_ARM := FALSE}
97 {$setc TARGET_CPU_ARM64 := FALSE}
98 {$setc TARGET_OS_MAC := TRUE}
99 {$setc TARGET_OS_IPHONE := FALSE}
100 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
101 {$setc TARGET_OS_EMBEDDED := FALSE}
102 {$elifc defined __ppc64__ and __ppc64__}
103 {$setc TARGET_CPU_PPC := FALSE}
104 {$setc TARGET_CPU_PPC64 := TRUE}
105 {$setc TARGET_CPU_X86 := FALSE}
106 {$setc TARGET_CPU_X86_64 := FALSE}
107 {$setc TARGET_CPU_ARM := FALSE}
108 {$setc TARGET_CPU_ARM64 := FALSE}
109 {$setc TARGET_OS_MAC := TRUE}
110 {$setc TARGET_OS_IPHONE := FALSE}
111 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
112 {$setc TARGET_OS_EMBEDDED := FALSE}
113 {$elifc defined __i386__ and __i386__}
114 {$setc TARGET_CPU_PPC := FALSE}
115 {$setc TARGET_CPU_PPC64 := FALSE}
116 {$setc TARGET_CPU_X86 := TRUE}
117 {$setc TARGET_CPU_X86_64 := FALSE}
118 {$setc TARGET_CPU_ARM := FALSE}
119 {$setc TARGET_CPU_ARM64 := FALSE}
120 {$ifc defined iphonesim}
121 {$setc TARGET_OS_MAC := FALSE}
122 {$setc TARGET_OS_IPHONE := TRUE}
123 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
124 {$elsec}
125 {$setc TARGET_OS_MAC := TRUE}
126 {$setc TARGET_OS_IPHONE := FALSE}
127 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
128 {$endc}
129 {$setc TARGET_OS_EMBEDDED := FALSE}
130 {$elifc defined __x86_64__ and __x86_64__}
131 {$setc TARGET_CPU_PPC := FALSE}
132 {$setc TARGET_CPU_PPC64 := FALSE}
133 {$setc TARGET_CPU_X86 := FALSE}
134 {$setc TARGET_CPU_X86_64 := TRUE}
135 {$setc TARGET_CPU_ARM := FALSE}
136 {$setc TARGET_CPU_ARM64 := FALSE}
137 {$ifc defined iphonesim}
138 {$setc TARGET_OS_MAC := FALSE}
139 {$setc TARGET_OS_IPHONE := TRUE}
140 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
141 {$elsec}
142 {$setc TARGET_OS_MAC := TRUE}
143 {$setc TARGET_OS_IPHONE := FALSE}
144 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
145 {$endc}
146 {$setc TARGET_OS_EMBEDDED := FALSE}
147 {$elifc defined __arm__ and __arm__}
148 {$setc TARGET_CPU_PPC := FALSE}
149 {$setc TARGET_CPU_PPC64 := FALSE}
150 {$setc TARGET_CPU_X86 := FALSE}
151 {$setc TARGET_CPU_X86_64 := FALSE}
152 {$setc TARGET_CPU_ARM := TRUE}
153 {$setc TARGET_CPU_ARM64 := FALSE}
154 {$setc TARGET_OS_MAC := FALSE}
155 {$setc TARGET_OS_IPHONE := TRUE}
156 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
157 {$setc TARGET_OS_EMBEDDED := TRUE}
158 {$elifc defined __arm64__ and __arm64__}
159 {$setc TARGET_CPU_PPC := FALSE}
160 {$setc TARGET_CPU_PPC64 := FALSE}
161 {$setc TARGET_CPU_X86 := FALSE}
162 {$setc TARGET_CPU_X86_64 := FALSE}
163 {$setc TARGET_CPU_ARM := FALSE}
164 {$setc TARGET_CPU_ARM64 := TRUE}
165 {$ifc defined ios}
166 {$setc TARGET_OS_MAC := FALSE}
167 {$setc TARGET_OS_IPHONE := TRUE}
168 {$setc TARGET_OS_EMBEDDED := TRUE}
169 {$elsec}
170 {$setc TARGET_OS_MAC := TRUE}
171 {$setc TARGET_OS_IPHONE := FALSE}
172 {$setc TARGET_OS_EMBEDDED := FALSE}
173 {$endc}
174 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
175 {$elsec}
176 {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
177 {$endc}
178
179 {$ifc defined __LP64__ and __LP64__ }
180 {$setc TARGET_CPU_64 := TRUE}
181 {$elsec}
182 {$setc TARGET_CPU_64 := FALSE}
183 {$endc}
184
185 {$ifc defined FPC_BIG_ENDIAN}
186 {$setc TARGET_RT_BIG_ENDIAN := TRUE}
187 {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
188 {$elifc defined FPC_LITTLE_ENDIAN}
189 {$setc TARGET_RT_BIG_ENDIAN := FALSE}
190 {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
191 {$elsec}
192 {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
193 {$endc}
194 {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
195 {$setc CALL_NOT_IN_CARBON := FALSE}
196 {$setc OLDROUTINENAMES := FALSE}
197 {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
198 {$setc OPAQUE_UPP_TYPES := TRUE}
199 {$setc OTCARBONAPPLICATION := TRUE}
200 {$setc OTKERNEL := FALSE}
201 {$setc PM_USE_SESSION_APIS := TRUE}
202 {$setc TARGET_API_MAC_CARBON := TRUE}
203 {$setc TARGET_API_MAC_OS8 := FALSE}
204 {$setc TARGET_API_MAC_OSX := TRUE}
205 {$setc TARGET_CARBON := TRUE}
206 {$setc TARGET_CPU_68K := FALSE}
207 {$setc TARGET_CPU_MIPS := FALSE}
208 {$setc TARGET_CPU_SPARC := FALSE}
209 {$setc TARGET_OS_UNIX := FALSE}
210 {$setc TARGET_OS_WIN32 := FALSE}
211 {$setc TARGET_RT_MAC_68881 := FALSE}
212 {$setc TARGET_RT_MAC_CFM := FALSE}
213 {$setc TARGET_RT_MAC_MACHO := TRUE}
214 {$setc TYPED_FUNCTION_POINTERS := TRUE}
215 {$setc TYPE_BOOL := FALSE}
216 {$setc TYPE_EXTENDED := FALSE}
217 {$setc TYPE_LONGLONG := TRUE}
218 uses MacTypes,CFBase,MixedMode,MacErrors,CFString;
219 {$endc} {not MACOSALLINCLUDE}
220
221
222 {$ifc TARGET_OS_MAC}
223
224 {$ALIGN MAC68K}
225
226 {
227 ________________________________________________________________
228 UNIVERSAL SCRAP MANAGER INTERFACES
229 ________________________________________________________________
230 The following interfaces are available when compiling for BOTH
231 Carbon AND Mac OS 8.
232 ________________________________________________________________
233 }
234 {
235 While we're in here mucking about, we defined a new type to
236 to put some confusion to rest. The old calls, as well as the
237 new calls, use the new type. Existing clients should be
238 blissfully ignorant.
239 }
240
241 type
242 ScrapFlavorType = FourCharCode;
243 {
244 Newsflash! After 15 years of arduous toil, it's finally possible
245 for specially trained typists wielding advanced text editing
246 technology to define symbolic names for commonly used scrap
247 flavor type constants! Apple triumphs again!
248 }
249 const
250 kScrapFlavorTypePicture = FourCharCode('PICT'); { contents of a PicHandle}
251 kScrapFlavorTypeText = FourCharCode('TEXT'); { stream of characters}
252 kScrapFlavorTypeTextStyle = FourCharCode('styl'); { see TEGetStyleScrapHandle}
253 kScrapFlavorTypeMovie = FourCharCode('moov'); { reference to a movie}
254 kScrapFlavorTypeSound = FourCharCode('snd '); { see SndRecord and SndPlay}
255 kScrapFlavorTypeUnicode = FourCharCode('utxt'); { stream of UTF16 characters (internal representation)}
256 kScrapFlavorTypeUTF16External = FourCharCode('ut16'); { stream of UTF16 characters (external representation)}
257 kScrapFlavorTypeUnicodeStyle = FourCharCode('ustl'); { ATSUI defines; Textension uses}
258
259 {
260 If you are a Carbon client and you need to run on Mac OS 8,
261 you may still need to load and unload the scrap. Under Mac OS
262 X, the scrap is held by the pasteboard server instead of in a
263 handle in your app's heap, so LoadScrap and UnloadScrap do
264 nothing when called under Mac OS X.
265 }
266
267 {$ifc not TARGET_CPU_64}
268 {
269 * LoadScrap() *** DEPRECATED ***
270 *
271 * Deprecated:
272 * LoadScrap does nothing on Mac OS X.
273 *
274 * Mac OS X threading:
275 * Not thread safe
276 *
277 * Availability:
278 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
279 * CarbonLib: in CarbonLib 1.0 and later
280 * Non-Carbon CFM: in InterfaceLib 7.1 and later
281 }
LoadScrapnull282 function LoadScrap: OSStatus; external name '_LoadScrap';
283 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
284
285
286 {
287 * UnloadScrap() *** DEPRECATED ***
288 *
289 * Deprecated:
290 * UnloadScrap does nothing on Mac OS X.
291 *
292 * Mac OS X threading:
293 * Not thread safe
294 *
295 * Availability:
296 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
297 * CarbonLib: in CarbonLib 1.0 and later
298 * Non-Carbon CFM: in InterfaceLib 7.1 and later
299 }
UnloadScrapnull300 function UnloadScrap: OSStatus; external name '_UnloadScrap';
301 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
302
303
304 {
305 ________________________________________________________________
306 CARBON SCRAP MANAGER INTERFACES
307 ________________________________________________________________
308 The following interfaces are available only when compiling for
309 Carbon.
310 ________________________________________________________________
311 }
312
313 {
314 When promising a scrap flavor, it's OK if you
315 don't yet know how big the flavor data will be.
316 In this case, just pass kScrapFlavorSizeUnknown
317 for the flavor data size.
318 }
319
320 {$endc} {not TARGET_CPU_64}
321
322 const
323 kScrapFlavorSizeUnknown = -1;
324
325 {
326 kScrapReservedFlavorType is a flavor type which is reserved
327 for use by Scrap Manager. If you pass it to Scrap Manager,
328 it will be rejected.
329 }
330
331 const
332 kScrapReservedFlavorType = FourCharCode('srft');
333
334 {
335 We've added scrap flavor flags ala Drag Manager.
336
337 kScrapFlavorMaskNone means you want none of the flags.
338
339 kScrapFlavorSenderOnlyMask means only the process which
340 put the flavor on the scrap can see it. If some other
341 process put a flavor with this flag on the scrap,
342 your process will never see the flavor, so there's
343 no point in testing for this flag.
344
345 kScrapFlavorTranslated means the flavor was translated
346 from some other flavor in the scrap by Translation Manager.
347 Most callers should not care about this bit.
348 }
349 const
350 kScrapFlavorMaskNone = $00000000;
351 kScrapFlavorMaskSenderOnly = $00000001;
352 kScrapFlavorMaskTranslated = $00000002;
353
354 type
355 ScrapFlavorFlags = UInt32;
356 {
357 ScrapFlavorInfo describes a single flavor within
358 a scrap.
359 }
360 type
361 ScrapFlavorInfoPtr = ^ScrapFlavorInfo;
362 ScrapFlavorInfo = record
363 flavorType: ScrapFlavorType;
364 flavorFlags: ScrapFlavorFlags;
365 end;
366 type
367 ScrapRef = ^OpaqueScrapRef; { an opaque type }
368 OpaqueScrapRef = record end;
369 {
370 kScrapRefNone is guaranteed to be an invalid ScrapRef. This
371 is convenient when initializing application variables.
372 }
373 const
374 kScrapRefNone = nil;
375 {
376 Defined Apple scrap names for GetScrapByName
377 kScrapClipboardScrap traditional clipboard scrap
378 kScrapFindScrap compatible with Cocoa's global find scrap
379 }
380 {$ifc USE_CFSTR_CONSTANT_MACROS}
381 {$definec kScrapClipboardScrap CFSTRP('com.apple.scrap.clipboard')}
382 {$endc}
383 {$ifc USE_CFSTR_CONSTANT_MACROS}
384 {$definec kScrapFindScrap CFSTRP('com.apple.scrap.find')}
385 {$endc}
386
387 { Enumerated options to be passed to GetScrapByName}
388
389 const
390 kScrapGetNamedScrap = 0; { get current named scrap without bumping}
391 kScrapClearNamedScrap = 1 shl 0; { acquire the named scrap, bumping and clearing}
392
393 {
394 GetScrapByName allows access to an indefinite number of public or private
395 scraps. The constant kScrapClipboardScrap refers to the "current" scrap
396 we've all come to know and love. kScrapFindScrap allows Carbon apps to
397 interact seamlessly with Cocoa's global find scrap. Note that calling:
398
399 GetScrapByName( kScrapClipboardScrap, kScrapGetNamedScrap, &scrap );
400
401 is an exact match to the call:
402
403 GetCurrentScrap( &scrap );
404
405 Additionally, a call to:
406
407 GetScrapByName( kScrapClipboardScrap, kScrapClearNamedScrap, &scrap );
408
409 is a replacement for the sequence:
410
411 ClearCurrentScrap();
412 GetCurrentScrap( &scrap );
413
414 You can use this API to generate your own private scraps to use as a high
415 level interprocess communication between your main and helper apps. The Java
416 naming convention is suggested for your scraps ( ie. com.joeco.scrap.secret ).
417
418 CarbonLib does not support arbitrary named scraps; when calling this API on
419 CarbonLib, kScrapClipboardScrap is the only supported value for the name parameter.
420 }
421 {$ifc not TARGET_CPU_64}
422 {
423 * GetScrapByName() *** DEPRECATED ***
424 *
425 * Deprecated:
426 * The Scrap Manager is deprecated. Use PasteboardCreate instead.
427 *
428 * Mac OS X threading:
429 * Not thread safe
430 *
431 * Availability:
432 * Mac OS X: in version 10.1 and later in Carbon.framework [32-bit only] but deprecated in 10.5
433 * CarbonLib: in CarbonLib 1.5 and later
434 * Non-Carbon CFM: not available
435 }
GetScrapByNamenull436 function GetScrapByName( name: CFStringRef; options: OptionBits; var scrap: ScrapRef ): OSStatus; external name '_GetScrapByName';
437 (* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
438
439
440 {
441 GetCurrentScrap obtains a reference to the current scrap.
442 The ScrapRef obtained via GetCurrentScrap will become
443 invalid and unusable after the scrap is cleared.
444 }
445
446 {
447 * GetCurrentScrap() *** DEPRECATED ***
448 *
449 * Deprecated:
450 * The Scrap Manager is deprecated. Use PasteboardCreate instead.
451 *
452 * Mac OS X threading:
453 * Not thread safe
454 *
455 * Availability:
456 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
457 * CarbonLib: in CarbonLib 1.0 and later
458 * Non-Carbon CFM: not available
459 }
GetCurrentScrapnull460 function GetCurrentScrap( var scrap: ScrapRef ): OSStatus; external name '_GetCurrentScrap';
461 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
462
463
464 {
465 GetScrapFlavorFlags tells you [a] whether the scrap contains
466 data for a particular flavor and [b] some things about that
467 flavor if it exists. This call never blocks, and is useful
468 for deciding whether to enable the Paste item in your Edit
469 menu, among other things.
470 }
471
472 {
473 * GetScrapFlavorFlags() *** DEPRECATED ***
474 *
475 * Deprecated:
476 * The Scrap Manager is deprecated. Use PasteboardGetItemFlavorFlags
477 * instead.
478 *
479 * Mac OS X threading:
480 * Not thread safe
481 *
482 * Availability:
483 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
484 * CarbonLib: in CarbonLib 1.0 and later
485 * Non-Carbon CFM: not available
486 }
GetScrapFlavorFlagsnull487 function GetScrapFlavorFlags( scrap: ScrapRef; flavorType: ScrapFlavorType; var flavorFlags: ScrapFlavorFlags ): OSStatus; external name '_GetScrapFlavorFlags';
488 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
489
490
491 {
492 GetScrapFlavorSize gets the size of the data of the specified
493 flavor. This function blocks until the specified flavor
494 data is available. GetScrapFlavorSize is intended as a prelude
495 to allocating memory and calling GetScrapFlavorData.
496 }
497
498 {
499 * GetScrapFlavorSize() *** DEPRECATED ***
500 *
501 * Deprecated:
502 * The Scrap Manager is deprecated. Use PasteboardCopyItemFlavorData
503 * instead.
504 *
505 * Mac OS X threading:
506 * Not thread safe
507 *
508 * Availability:
509 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
510 * CarbonLib: in CarbonLib 1.0 and later
511 * Non-Carbon CFM: not available
512 }
GetScrapFlavorSizenull513 function GetScrapFlavorSize( scrap: ScrapRef; flavorType: ScrapFlavorType; var byteCount: Size ): OSStatus; external name '_GetScrapFlavorSize';
514 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
515
516
517 {
518 GetScrapFlavorData gets the data from the specified flavor in the
519 specified scrap. This function blocks until the specified flavor
520 data is available. Specify the maximum size your buffer can contain;
521 on output, this function produces the number of bytes that were
522 available (even if this is more than you requested).
523 }
524
525 {
526 * GetScrapFlavorData() *** DEPRECATED ***
527 *
528 * Deprecated:
529 * The Scrap Manager is deprecated. Use PasteboardCopyItemFlavorData
530 * instead.
531 *
532 * Mac OS X threading:
533 * Not thread safe
534 *
535 * Availability:
536 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
537 * CarbonLib: in CarbonLib 1.0 and later
538 * Non-Carbon CFM: not available
539 }
GetScrapFlavorDatanull540 function GetScrapFlavorData( scrap: ScrapRef; flavorType: ScrapFlavorType; var byteCount: Size; destination: UnivPtr ): OSStatus; external name '_GetScrapFlavorData';
541 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
542
543
544 {
545 ClearCurrentScrap clears the current scrap. Call this
546 first when the user requests a Copy or Cut operation --
547 even if you maintain a private scrap! You should not wait
548 until receiving a suspend event to call ClearCurrentScrap. Call
549 it immediately after the user requests a Copy or Cut operation.
550 You don't need to put any data on the scrap immediately (although
551 it's perfectly fine to do so). You DO need to call GetCurrentScrap
552 after ClearCurrentScrap so you'll have a valid ScrapRef to pass
553 to other functions.
554 }
555
556 {
557 * ClearCurrentScrap() *** DEPRECATED ***
558 *
559 * Deprecated:
560 * The Scrap Manager is deprecated. Use PasteboardClear instead.
561 *
562 * Mac OS X threading:
563 * Not thread safe
564 *
565 * Availability:
566 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
567 * CarbonLib: in CarbonLib 1.0 and later
568 * Non-Carbon CFM: not available
569 }
ClearCurrentScrapnull570 function ClearCurrentScrap: OSStatus; external name '_ClearCurrentScrap';
571 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
572
573
574 {
575 ClearScrap will clear the scrap passed in and return the bumped
576 ScrapRef value. ClearScrap behaves similarly to GetScrapByName
577 when called with the kScrapClearNamedScrap option with the
578 benefit of not requiring a name in the event one is not available.
579
580 CarbonLib does not support arbitrary named scraps; when calling this
581 API on CarbonLib, only clearing the current scrap is supported.
582 }
583 {
584 * ClearScrap() *** DEPRECATED ***
585 *
586 * Deprecated:
587 * The Scrap Manager is deprecated. Use PasteboardClear instead.
588 *
589 * Mac OS X threading:
590 * Not thread safe
591 *
592 * Availability:
593 * Mac OS X: in version 10.1 and later in Carbon.framework [32-bit only] but deprecated in 10.5
594 * CarbonLib: in CarbonLib 1.5 and later
595 * Non-Carbon CFM: not available
596 }
ClearScrapnull597 function ClearScrap( var inOutScrap: ScrapRef ): OSStatus; external name '_ClearScrap';
598 (* AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
599
600
601 {
602 PutScrapFlavor is a lot like PutScrap, with two differences:
603 we added a ScrapRef parameter at the beginning and you can
604 "promise" various aspects of a flavor. If you pass a NIL
605 data pointer, this is a promise that in the future you
606 will provide data for this flavor. Provide the data
607 through a subsequent call to PutScrapFlavor, either later
608 in the same code flow or during a scrap promise keeper proc.
609 If you know how big the data is, you can pass the size as
610 well, and this may allow subsequent callers of GetScrapFlavorInfo
611 to avoid blocking. If you don't know the size, pass -1.
612 If you pass a 0 size, you are telling Scrap Manager not to
613 expect any data for this flavor. In this case, the flavor
614 data pointer is ignored. NOTE: the last time you can provide
615 scrap flavor data is when your scrap promise keeper gets
616 called. It is NOT possible to call PutScrapFlavor while
617 handling a suspend event; suspend events under Carbon
618 simply don't work the way they do under Mac OS 8.
619
620 The method for setting Scrap Manager promises differs from that for Drag Manger promises.
621 This chart describes the method for setting scrap promises via PutScrapFlavor().
622
623 dataPtr dataSize result
624 pointer value actual data size The data of size dataSize pointed to by dataPtr is added to the scrap.
625 0 actual data size A promise for data of size dataSize is placed on the scrap.
626 0 -1 A promise for data of an undetermined size is placed on the scrap.
627 ignored 0 A flavor with no data expected is placed on the scrap. This is not a promise.
628 }
629 {
630 * PutScrapFlavor() *** DEPRECATED ***
631 *
632 * Deprecated:
633 * The Scrap Manager is deprecated. Use PasteboardPutItemFlavor
634 * instead.
635 *
636 * Mac OS X threading:
637 * Not thread safe
638 *
639 * Availability:
640 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
641 * CarbonLib: in CarbonLib 1.0 and later
642 * Non-Carbon CFM: not available
643 }
PutScrapFlavornull644 function PutScrapFlavor( scrap: ScrapRef; flavorType: ScrapFlavorType; flavorFlags: ScrapFlavorFlags; flavorSize: Size; flavorData: {const} UnivPtr { can be NULL } ): OSStatus; external name '_PutScrapFlavor';
645 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
646
647
648 {
649 ScrapPromiseKeeper is a function you write which is called by
650 Scrap Manager as needed to keep your earlier promise of a
651 particular scrap flavor. When your function is called, deliver
652 the requested data by calling PutScrapFlavor.
653 }
654
655 {$endc} {not TARGET_CPU_64}
656
657 type
scrapnull658 ScrapPromiseKeeperProcPtr = function( scrap: ScrapRef; flavorType: ScrapFlavorType; userData: UnivPtr ): OSStatus;
659 ScrapPromiseKeeperUPP = ScrapPromiseKeeperProcPtr;
660 {
661 * NewScrapPromiseKeeperUPP()
662 *
663 * Availability:
664 * Mac OS X: in version 10.0 and later in Carbon.framework
665 * CarbonLib: in CarbonLib 1.0 and later
666 * Non-Carbon CFM: available as macro/inline
667 }
NewScrapPromiseKeeperUPPnull668 function NewScrapPromiseKeeperUPP( userRoutine: ScrapPromiseKeeperProcPtr ): ScrapPromiseKeeperUPP; external name '_NewScrapPromiseKeeperUPP';
669 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
670
671 {
672 * DisposeScrapPromiseKeeperUPP()
673 *
674 * Availability:
675 * Mac OS X: in version 10.0 and later in Carbon.framework
676 * CarbonLib: in CarbonLib 1.0 and later
677 * Non-Carbon CFM: available as macro/inline
678 }
679 procedure DisposeScrapPromiseKeeperUPP( userUPP: ScrapPromiseKeeperUPP ); external name '_DisposeScrapPromiseKeeperUPP';
680 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
681
682 {
683 * InvokeScrapPromiseKeeperUPP()
684 *
685 * Availability:
686 * Mac OS X: in version 10.0 and later in Carbon.framework
687 * CarbonLib: in CarbonLib 1.0 and later
688 * Non-Carbon CFM: available as macro/inline
689 }
InvokeScrapPromiseKeeperUPPnull690 function InvokeScrapPromiseKeeperUPP( scrap: ScrapRef; flavorType: ScrapFlavorType; userData: UnivPtr; userUPP: ScrapPromiseKeeperUPP ): OSStatus; external name '_InvokeScrapPromiseKeeperUPP';
691 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
692
693 {
694 SetScrapPromiseKeeper associates a ScrapPromiseKeeper with a
695 scrap. You can remove a ScrapPromiseKeeper from a scrap by
696 passing a NIL ScrapPromiseKeeper to SetScrapPromiseKeeper.
697 Pass whatever you like in the last parameter; its value will
698 be passed to your ScrapPromiseKeeper, which can do whatever
699 it likes with the value. You might choose to pass a pointer
700 or handle to some private scrap data which the
701 ScrapPromiseKeeper could use in fabricating one or more
702 promised flavors.
703 }
704 {$ifc not TARGET_CPU_64}
705 {
706 * SetScrapPromiseKeeper() *** DEPRECATED ***
707 *
708 * Deprecated:
709 * The Scrap Manager is deprecated. Use PasteboardSetPromiseKeeper
710 * instead.
711 *
712 * Mac OS X threading:
713 * Not thread safe
714 *
715 * Availability:
716 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
717 * CarbonLib: in CarbonLib 1.0 and later
718 * Non-Carbon CFM: not available
719 }
SetScrapPromiseKeepernull720 function SetScrapPromiseKeeper( scrap: ScrapRef; upp: ScrapPromiseKeeperUPP; userData: {const} UnivPtr ): OSStatus; external name '_SetScrapPromiseKeeper';
721 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
722
723
724 {
725 GetScrapFlavorCount produces the number of
726 items which can be obtained by GetScrapFlavorInfoList.
727 }
728
729 {
730 * GetScrapFlavorCount() *** DEPRECATED ***
731 *
732 * Deprecated:
733 * The Scrap Manager is deprecated. Use PasteboardCopyItemFlavors
734 * instead.
735 *
736 * Mac OS X threading:
737 * Not thread safe
738 *
739 * Availability:
740 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
741 * CarbonLib: in CarbonLib 1.0 and later
742 * Non-Carbon CFM: not available
743 }
GetScrapFlavorCountnull744 function GetScrapFlavorCount( scrap: ScrapRef; var infoCount: UInt32 ): OSStatus; external name '_GetScrapFlavorCount';
745 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
746
747
748 {
749 GetScrapFlavorInfoList fills a list (array)
750 of items which each describe the corresponding
751 flavor in the scrap. It fills no more array
752 elements as are specified. On exit, it produces
753 the count of elements it filled (which may be
754 smaller than the count requested). Yes, YOU
755 must provide the memory for the array.
756 }
757
758 {
759 * GetScrapFlavorInfoList() *** DEPRECATED ***
760 *
761 * Deprecated:
762 * The Scrap Manager is deprecated. Use PasteboardCopyItemFlavors
763 * instead.
764 *
765 * Mac OS X threading:
766 * Not thread safe
767 *
768 * Availability:
769 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
770 * CarbonLib: in CarbonLib 1.0 and later
771 * Non-Carbon CFM: not available
772 }
GetScrapFlavorInfoListnull773 function GetScrapFlavorInfoList( scrap: ScrapRef; var infoCount: UInt32; info: {variable-size-array} ScrapFlavorInfoPtr ): OSStatus; external name '_GetScrapFlavorInfoList';
774 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
775
776
777 {
778 CallInScrapPromises forces all promises to be kept.
779 If your application promises at least one flavor
780 AND it does NOT adopt the new event model, you
781 should call this function when your application
782 is about to quit. If your app promises no flavors,
783 there is no need to call this function, and if
784 your app adopts the new event model, this function
785 will be called automagically for you. It doesn't
786 hurt to call this function more than once, though
787 promise keepers may be asked to keep promises
788 they already tried and failed.
789 }
790
791 {
792 * CallInScrapPromises() *** DEPRECATED ***
793 *
794 * Deprecated:
795 * The Scrap Manager is deprecated. Use PasteboardResolvePromises
796 * instead.
797 *
798 * Mac OS X threading:
799 * Not thread safe
800 *
801 * Availability:
802 * Mac OS X: in version 10.0 and later in Carbon.framework [32-bit only] but deprecated in 10.5
803 * CarbonLib: in CarbonLib 1.0 and later
804 * Non-Carbon CFM: not available
805 }
CallInScrapPromisesnull806 function CallInScrapPromises: OSStatus; external name '_CallInScrapPromises';
807 (* AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5 *)
808
809
810 {$endc} {not TARGET_CPU_64}
811
812 {$endc} {TARGET_OS_MAC}
813 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
814
815 end.
816 {$endc} {not MACOSALLINCLUDE}
817