2
File: HIToolbox/HIObject.h
4
Contains: Base object for HIToolbox
6
Version: HIToolbox-219.4.81~2
8
Copyright: � 2001-2005 by Apple Computer, Inc., all rights reserved.
10
Bugs?: For bug reports, consult the following page on
13
http://www.freepascal.org/bugs.html
17
Change History (most recent first):
19
<4> 5/8/04 GRP Updated comments to match changes in HIObject.h, version HIToolbox-145.33~1.
20
<3> 4/8/04 PNL Moved HIObjectxxxx type declarations to HIObjectCore to fix cyclic dependency problem.
21
<2> 10/02/04 GRP Added support for GPC as well as CodeWarrior Pascal.
22
<1> 9/8/03 GRP First Pascal translation of HIObject.h, version HIToolbox-123.6~10.
24
{This file was processed by Dan's Source Converter}
25
{version 1.3 (this version modified by Ingemar Ragnemalm)}
26
{ Pascal Translation Updated: Peter N Lewis, <peter@stairways.com.au>, August 2005 }
28
Modified for use with Free Pascal
30
Please report any bugs to <gpc@microbizz.nl>
41
{$setc UNIVERSAL_INTERFACES_VERSION := $0342}
42
{$setc GAP_INTERFACES_VERSION := $0200}
44
{$ifc not defined USE_CFSTR_CONSTANT_MACROS}
45
{$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
48
{$ifc defined CPUPOWERPC and defined CPUI386}
49
{$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
51
{$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
52
{$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
55
{$ifc not defined __ppc__ and defined CPUPOWERPC}
60
{$ifc not defined __i386__ and defined CPUI386}
66
{$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
67
{$error Conflicting definitions for __ppc__ and __i386__}
70
{$ifc defined __ppc__ and __ppc__}
71
{$setc TARGET_CPU_PPC := TRUE}
72
{$setc TARGET_CPU_X86 := FALSE}
73
{$elifc defined __i386__ and __i386__}
74
{$setc TARGET_CPU_PPC := FALSE}
75
{$setc TARGET_CPU_X86 := TRUE}
77
{$error Neither __ppc__ nor __i386__ is defined.}
79
{$setc TARGET_CPU_PPC_64 := FALSE}
81
{$ifc defined FPC_BIG_ENDIAN}
82
{$setc TARGET_RT_BIG_ENDIAN := TRUE}
83
{$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
84
{$elifc defined FPC_LITTLE_ENDIAN}
85
{$setc TARGET_RT_BIG_ENDIAN := FALSE}
86
{$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
88
{$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
90
{$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
91
{$setc CALL_NOT_IN_CARBON := FALSE}
92
{$setc OLDROUTINENAMES := FALSE}
93
{$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
94
{$setc OPAQUE_UPP_TYPES := TRUE}
95
{$setc OTCARBONAPPLICATION := TRUE}
96
{$setc OTKERNEL := FALSE}
97
{$setc PM_USE_SESSION_APIS := TRUE}
98
{$setc TARGET_API_MAC_CARBON := TRUE}
99
{$setc TARGET_API_MAC_OS8 := FALSE}
100
{$setc TARGET_API_MAC_OSX := TRUE}
101
{$setc TARGET_CARBON := TRUE}
102
{$setc TARGET_CPU_68K := FALSE}
103
{$setc TARGET_CPU_MIPS := FALSE}
104
{$setc TARGET_CPU_SPARC := FALSE}
105
{$setc TARGET_OS_MAC := TRUE}
106
{$setc TARGET_OS_UNIX := FALSE}
107
{$setc TARGET_OS_WIN32 := FALSE}
108
{$setc TARGET_RT_MAC_68881 := FALSE}
109
{$setc TARGET_RT_MAC_CFM := FALSE}
110
{$setc TARGET_RT_MAC_MACHO := TRUE}
111
{$setc TYPED_FUNCTION_POINTERS := TRUE}
112
{$setc TYPE_BOOL := FALSE}
113
{$setc TYPE_EXTENDED := FALSE}
114
{$setc TYPE_LONGLONG := TRUE}
115
uses MacTypes,CFBase,CFBundle,Events,CarbonEvents,HIObjectCore,AXUIElement,CFDictionary,CarbonEventsCore;
124
* HIObject is the HIToolbox's base class for various objects. Over
125
* time, all of our common objects (controls, windows, menus, etc.)
126
* will be derived from HIObject. Code which is external to
127
* HIToolbox can also create its own subclasses of our objects using
128
* the routines contained in this file. There are also polymorphic
129
* functions one can use on any HIObject for getting the class ID,
132
* HIObjects are actually CF types under the hood. This means that
133
* they can be put into CF collections and retain/release can be
136
* An HIObject is essentially a very basic building-block object
137
* which contains an event target. You can create these objects to
138
* use as your own Carbon Event receptors in your application, or
139
* you can subclass existing Toolbox object to suit your needs.
142
* You register your subclasses with HIObjectRegisterSubclass,
143
* passing your class ID, the parent class, and an event handler.
144
* You also pass a list of events the handler is interested in.
147
* To create an object of your subclass, you call HIObjectCreate,
148
* passing the class ref you registered, as well as an
149
* initialization event.
151
* Construction is two-phase: first the basic construction of the
152
* object is done, then initialization is performed. The toolbox
153
* sends construction events bottom-up, as you would expect in C++
154
* or the like. Here is the list of what goes on to create an
157
* 1) The Toolbox creates the base HIObject
159
* 2) It then installs the event handler you specified when you
160
* registered your subclass. Your handler must listen for
161
* kEventHIObjectConstruct and kEventHIObjectDestruct events. If it
162
* does not, the class cannot be registered (you will get a
165
* 3) Next, the Toolbox _directly_ calls your handler with an
166
* kEventHIObjectConstruct event. When called like this, you are not
167
* really being called in the context of a handler stack, so you
168
* cannot do things like CallNextEventHandler. The userData
169
* parameter is what you specified when you registered the class.
170
* Typically, during construction you will allocate memory yourself
171
* to store your own instance data; this allocation might be as
172
* simple as calling malloc or NewPtr, or it might involve creating
173
* your own C++ object. In the construct event, you are passed the
174
* base HIObjectRef of the object being created. Typically you would
175
* store this HIObjectRef in your own instance data for later use.
176
* When handling this construct event, you should be sure to use
177
* SetEventParameter to set the kEventParamHIObjectInstance
178
* parameter in the construction event with your own instance data.
179
* You must use typeVoidPtr as the type.
181
* 4) The Toolbox looks for your instance of typeVoidPtr after you
182
* handle the construct event. It then takes that data and stores it
183
* off with the object and also sets the user data of the event
184
* handler it installed to be this instance data. This means that
185
* following the construct event, all calls to your event handler
186
* will have the instance data you returned to us.
188
* 5) Once construction has completed successfully, we will send
189
* your object the initialize event passed into HIObjectCreate. At
190
* this point, all events are now sent to your object using standard
191
* Carbon Events mechanisms (it is only the construct event which is
192
* special). When we send the initialization event to your subclass,
193
* you should pass the event to your superclass before proceeding.
194
* You do this with CallNextEventHandler. Once back from that call,
195
* you should verify that the result is noErr, indicating that the
196
* superclass did in fact initialize properly. If it did not, your
197
* should return the error that CallNextEventHandler returned from
198
* your handler as well. The object will be destroyed by the
199
* Toolbox. Your object should be able to be destroyed in a
200
* partially initialized state such as this. This stage is optional,
201
* i.e. an object does not need to respond to the initialize event
202
* unless it is expecting certain parameters to be passed to it at
203
* creation time. This is where those parameters can be fetched.
206
* 6) Once initialization is successful, the HIObjectRef is
207
* returned to the caller of HIObjectCreate. From there, you can
208
* have all sorts of cool fun.
210
* When someone has called CFRelease enough such that the refcount
211
* of the object drops to zero, the object is destroyed. The Toolbox
212
* will send a kEventHIObjectDestruct event to your object. DO NOT
213
* CALL CALLNEXTEVENTHANDLER. You will be setting yourself up for
214
* some hurt. Just clean up and return from your handler.
217
The declarations for HIObjectClassRef, HIObjectClassRefPtr, and HIObjectRef
218
have been moved to HIObjectCore. See HIObjectCore.p[.pas] for reason.
226
* You are trying to register a class ID that already exists.
228
hiObjectClassExistsErr = -22080;
231
* You are trying to unregister a class which has instances which
232
* still exist. You must destroy them first, before they destroy you!
234
hiObjectClassHasInstancesErr = -22081;
235
hiObjectClassHasSubclassesErr = -22082;
238
* You are trying to create an HIObject class that is defined as
239
* being abstract. You must subclass it instead. Oh yes. Don't make
242
hiObjectClassIsAbstractErr = -22083;
247
* The event class for HIObject events.
249
kEventClassHIObject = $68696F62 (* 'hiob' *);
252
kEventParamHIObjectInstance = $68696F69 (* 'hioi' *);
253
kEventParamHIArchive = $68696163 (* 'hiac' *); { typeCFTypeRef }
254
typeHIObjectRef = $68696F62 (* 'hiob' *);
257
kEventClassHIObject quick reference:
259
These are the events for base class functionality of HIObjects. You should only need to be
260
aware of these if you are implementing a subclass of HIObject.
262
kEventHIObjectConstruct = 1,
263
kEventHIObjectInitialize = 2,
264
kEventHIObjectDestruct = 3,
265
kEventHIObjectIsEqual = 4,
266
kEventHIObjectPrintDebugInfo = 5,
267
kEventHIObjectEncode = 6
270
* kEventClassHIObject / kEventHIObjectConstruct
273
* Your object is being constructed. You should allocate instance
274
* data for your object.
277
* When your event handler is called with this event, it is being
278
* called directly and not through the normal event dispatching
279
* mechanism. This means that the EventHandlerCallRef passed to your
280
* handler will be NULL and CallNextEventHandler will not work. You
281
* are passed the actual HIObjectRef of your base class for you to
282
* record in your instance data.
284
* Mac OS X threading:
289
* <-> kEventParamHIObjectInstance (in/out, typeHIObjectRef)
290
* On entry, this parameter is typeHIObjectRef, and is the
291
* HIObjectRef of your instance�s base class. Typically you
292
* will read this parameter from the event and store it in
293
* your instance data so that when your instance needs to call
294
* HIObject APIs, it can use this HIObjectRef.
296
* On exit, this parameter is typeVoidPtr, and should be a
297
* pointer to your instance data that you have written into
298
* the event with SetEventParameter. After your event handler
299
* returns, the toolbox reads your instance data pointer from
300
* the event, installs the event handlers that were passed to
301
* HIObjectRegisterSubclass on the new object, and uses the
302
* instance data pointer as the refcon for those event
303
* handlers. This allows your event handlers to retrieve your
304
* instance data pointer from the refcon.
307
* Mac OS X: in version 10.2 and later in Carbon.framework
308
* CarbonLib: not available
311
kEventHIObjectConstruct = 1;
314
* kEventClassHIObject / kEventHIObjectInitialize
317
* Your object is being initialized. You should read initialization
318
* data from the event and store it into your instance data.
321
* Your handler should pass this event on to the superclass first
322
* before handling this event. This is done by calling
323
* CallNextEventHandler with the event. When that function returns,
324
* you should make sure the result is noErr. If not, you should NOT
325
* continue to initialize your class.
327
* Assuming that CallNextEventHandler returned noErr, you may then
328
* proceed to read initialization data from the event parameters, if
329
* any. For example, you might be create an object that includes a
330
* string as part of its instance data. The caller of HIObjectCreate
331
* would create an EventRef and add a string to the event using a
332
* parameter name and type defined by your object. In your object�s
333
* kEventHIObjectInitialize event handler, you would read the string
334
* from the event parameter and store it into your instance
337
* The parameters of this event, therefore, contain the union of all
338
* parameters needed by all base classes of this object to properly
339
* construct themselves.
341
* Mac OS X threading:
346
* --> kEventParamHIArchive (in, typeCFTypeRef)
347
* The HIArchive reference from which the HIObject should be
348
* decoded. This parameter will only exist when the HIObject
349
* is requested to initialize itself from a decoded archive.
350
* Otherwise, the HIObject should initialize itself normally.
353
* Mac OS X: in version 10.2 and later in Carbon.framework
354
* CarbonLib: not available
357
kEventHIObjectInitialize = 2;
360
* kEventClassHIObject / kEventHIObjectDestruct
363
* Your object is being destroyed. This is your chance to dispose of
364
* anything you might have allocated for your object�s instance data.
367
* Do NOT call through with CallNextEventHandler, as you will
368
* disrupt the fabric of space-time. An HIObject is destroyed in
369
* most-derived to least-derived order, and if you call through,
370
* your base class can be destroyed before you destroy your own
371
* data, which can cause undefined results.
373
* Note that the refcon of your event handler for this event will be
374
* the instance data pointer allocated and returned by your
375
* kEventHIObjectConstruct handler in the
376
* kEventParamHIObjectInstance parameter.
378
* Mac OS X threading:
382
* Mac OS X: in version 10.2 and later in Carbon.framework
383
* CarbonLib: not available
386
kEventHIObjectDestruct = 3;
389
* kEventClassHIObject / kEventHIObjectIsEqual
392
* HIObjectIsEqual has been called, and you are being asked to
393
* determine if your object is equivalent to the one being passed to
397
* The base HIObject class handles this event by comparing the
398
* HIObjectRef values for pointer equality. Your subclass may choose
399
* to also compare the contents of the HIObject instance data.
401
* Mac OS X threading:
406
* --> kEventParamDirectObject (in, typeHIObjectRef)
407
* The object to which your object should be compared.
409
* <-- kEventParamResult (out, typeBoolean)
410
* If your object is equivalent to the direct object, you
411
* should return true in this parameter; otherwise, return
415
* Mac OS X: in version 10.2 and later in Carbon.framework
416
* CarbonLib: not available
419
kEventHIObjectIsEqual = 4;
422
* kEventClassHIObject / kEventHIObjectPrintDebugInfo
425
* HIObjectPrintDebugInfo has been called, and you are being asked
426
* to print your information to stdout.
429
* This event is sent to all handlers registered for it. You should
430
* NOT call CallNextEventHandler.
432
* Mac OS X threading:
436
* Mac OS X: in version 10.2 and later in Carbon.framework
437
* CarbonLib: not available
440
kEventHIObjectPrintDebugInfo = 5;
443
* kEventClassHIObject / kEventHIObjectEncode
446
* Your object is being requested to encode itself into an archive.
449
* Your handler should pass this event on to the superclass first
450
* before handling this event. This is done by calling
451
* CallNextEventHandler with the event. When that function returns,
452
* you should make sure the result is noErr. If not, you should NOT
453
* continue to initialize your class.
455
* HIArchiveEncodeHIObject has been called on your HIObject. At this
456
* point all relevant long term data should be encoded to the
457
* HIArchive provided.
459
* Mac OS X threading:
464
* --> kEventParamHIArchive (in, typeCFTypeRef)
465
* The HIArchive reference into which the HIObject should be
469
* Mac OS X: in version 10.4 and later in Carbon.framework
470
* CarbonLib: not available
473
kEventHIObjectEncode = 6;
476
* HIObjectRegisterSubclass()
479
* Registers a class with the Toolbox for creation later.
481
* Mac OS X threading:
487
* The class ID of your class. It should be unique. We recommend
488
* using Java-style com.company.foo naming conventions to avoid
492
* The class ID of the class you derive from. Passing NULL
493
* indicates you wish to subclass HIObject (the base class)
497
* Any special options for your class. Currently you must pass 0
498
* for this parameter.
501
* The construction proc for this subclass. You pass the address
502
* of an event handler into this parameter. This handler is called
503
* directly, rather than through the normal event dispatching
504
* mechanism. This means that the EventHandlerCallRef passed in
505
* will be NULL, and you cannot use it for calls like
506
* CallNextEventHandler. Other than that, you should return a
507
* result as usual. After your object is constructed, this proc
508
* will be installed as the event handler for the remaining events
509
* specified in the inEventList parameter. On Mac OS X 10.4 and
510
* later, you may pass NULL to create an "abstract class" that
511
* cannot be instantiated, but can still be used as a base class
512
* for subclasses; if you pass NULL, HIObjectCreate on the class
513
* ID will return hiObjectClassIsAbstractErr.
516
* The number of events you are installing.
519
* The events your handler wishes to receive. If you are not
520
* creating an abstract class, then you must handle the
521
* kEventHIObjectConstruct and kEventHIObjectDestruct event. If
522
* these events are not specified, an error is returned. An
523
* abstract class may pass 0 for the inNumEvents parameter and
524
* NULL for the inEventList parameter.
527
* Pass any info you want passed into your event handler here. For
528
* a C++ hierarchy based on HIObjects, you might actually pass a
529
* static method to construct your object here, and the base class
530
* event handler to do construction as your event handler.
533
* The newly created class reference. Pass NULL if you don't care.
536
* An operating system result code.
539
* Mac OS X: in version 10.2 and later in Carbon.framework
540
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
541
* Non-Carbon CFM: not available
543
function HIObjectRegisterSubclass( inClassID: CFStringRef; inBaseClassID: CFStringRef; inOptions: OptionBits; inConstructProc: EventHandlerUPP { can be NULL }; inNumEvents: UInt32; {const} inEventList: {variable-size-array} EventTypeSpecPtr; inConstructData: UnivPtr; outClassRef: HIObjectClassRefPtr { can be NULL } ): OSStatus; external name '_HIObjectRegisterSubclass';
544
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
548
* HIObjectUnregisterClass()
551
* Unregisters a previously registered subclass of HIObject. You
552
* will receive an error if there are subclasses of your class or
553
* instances of it which still exist. All instances and subclasses
554
* must be disposed of and unregistered first.
556
* Mac OS X threading:
562
* The class ref of the class of object you wish to unregister.
565
* Mac OS X: in version 10.2 and later in Carbon.framework
566
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
567
* Non-Carbon CFM: not available
569
function HIObjectUnregisterClass( inClassRef: HIObjectClassRef ): OSStatus; external name '_HIObjectUnregisterClass';
570
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
577
* Creates an object derived from HIObject.
579
* Mac OS X threading:
585
* The class ID of the class of object you wish to instantiate.
588
* If your class (or any class you derive from) accepts creation
589
* parameters, you need to pass an event into this parameter. The
590
* class must be kEventClassHIObject, and the kind should be
591
* kEventHIObjectInitialize. Any other parameters should be added
592
* as necessary. Specific subclasses of HIObject which require
593
* initialization parameters will specify those parameters in the
594
* appropriate headers.
597
* The instance of the object you create.
600
* An operating system result code. A return value of
601
* hiObjectClassIsAbstractErr indicates that the inConstructProc
602
* parameter to HIObjectRegisterSubclass was NULL; instances of such
603
* a class may not be created, only subclassed.
606
* Mac OS X: in version 10.2 and later in Carbon.framework
607
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
608
* Non-Carbon CFM: not available
610
function HIObjectCreate( inClassID: CFStringRef; inConstructData: EventRef; var outObject: HIObjectRef ): OSStatus; external name '_HIObjectCreate';
611
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
615
* HIObjectGetEventTarget()
618
* Returns the event target of an HIObjectRef.
620
* Mac OS X threading:
626
* The object whose target you want.
632
* Mac OS X: in version 10.2 and later in Carbon.framework
633
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
634
* Non-Carbon CFM: not available
636
function HIObjectGetEventTarget( inObject: HIObjectRef ): EventTargetRef; external name '_HIObjectGetEventTarget';
637
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
641
* HIObjectPrintDebugInfo()
644
* Prints the internal information of an HIObject for debugging
645
* purposes. It outputs the info to stdout.
647
* Mac OS X threading:
653
* The object to inspect.
656
* Mac OS X: in version 10.2 and later in Carbon.framework
657
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
658
* Non-Carbon CFM: not available
660
procedure HIObjectPrintDebugInfo( inObject: HIObjectRef ); external name '_HIObjectPrintDebugInfo';
661
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
665
* HIObjectCopyClassID()
668
* Returns the class ID of a given HIObject.
670
* Mac OS X threading:
676
* The object whose class ID you are interested in.
679
* A CFStringRef containing the object's class ID.
682
* Mac OS X: in version 10.2 and later in Carbon.framework
683
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
684
* Non-Carbon CFM: not available
686
function HIObjectCopyClassID( inObject: HIObjectRef ): CFStringRef; external name '_HIObjectCopyClassID';
687
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
691
* HIObjectIsOfClass()
694
* Returns whether or not an object is of a certain class. You can
695
* us this to see whether or not an object you have derives from an
696
* expected superclass.
698
* Mac OS X threading:
704
* The object whose class ID you wish to check.
707
* The class ID in question.
710
* A Boolean result indicating whether or not the object is of the
714
* Mac OS X: in version 10.2 and later in Carbon.framework
715
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
716
* Non-Carbon CFM: not available
718
function HIObjectIsOfClass( inObject: HIObjectRef; inObjectClassID: CFStringRef ): Boolean; external name '_HIObjectIsOfClass';
719
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
723
* HIObjectDynamicCast()
726
* Returns the instance data for a specific class of an HIObject.
727
* The instance data returned is the same instance data the class's
728
* construction event handler returns in the instance data
729
* parameter. This is stored off with the class reference so that it
730
* can be fetched later for use by this function. It allows your
731
* subclass to easily get at the data it created, if your subclass
732
* needs that data outside of an event handler. (Inside an event
733
* handler, your subclass can get at its instance data via the
734
* userData parameter to the event handler.)
736
* Mac OS X threading:
742
* The object whose class ID you wish to check.
745
* The class ID to get the instance data for.
748
* A void * result which contains the instance data for the object,
749
* or NULL if the object is not an instance of the class.
752
* Mac OS X: in version 10.2 and later in Carbon.framework
753
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
754
* Non-Carbon CFM: not available
756
function HIObjectDynamicCast( inObject: HIObjectRef; inClassID: CFStringRef ): UnivPtr; external name '_HIObjectDynamicCast';
757
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
761
* HIObjectCreateFromBundle()
764
* Returns the HIObject for the given bundle. A bundle can be
765
* designed to communicate with an app through an HIObject. The
766
* bundle must be designed to create an HIObject and have a defined
767
* suite of CarbonEvents that clients can use to communicate with
768
* the bundle's HIObject. Given a CFBundleRef, this API will tell
769
* the bundle to create the HIObject and return it to the caller.
771
* Mac OS X threading:
777
* The bundle that you wish to communicate with.
780
* The HIObject associated with the bundle.
783
* An operating system result code. If the bundle's HIObject
784
* creation function cannot be found, cfragNoSymbolErr will be
788
* Mac OS X: in version 10.2 and later in Carbon.framework
789
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
790
* Non-Carbon CFM: not available
792
function HIObjectCreateFromBundle( inBundle: CFBundleRef; var outObject: HIObjectRef ): OSStatus; external name '_HIObjectCreateFromBundle';
793
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
797
* HIObjectIsAccessibilityIgnored()
800
* Reports whether or not the given HIObject is marked as ignored
803
* See the discussion of HIObjectSetAccessibilityIgnored for details
804
* on what it means to be accessibility ignored.
806
* Mac OS X threading:
812
* The object whose accessibility ignored state you wish to query.
815
* A Boolean value indicating whether or not the HIObject is ignored
819
* Mac OS X: in version 10.2 and later in Carbon.framework
820
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
821
* Non-Carbon CFM: not available
823
function HIObjectIsAccessibilityIgnored( inObject: HIObjectRef ): Boolean; external name '_HIObjectIsAccessibilityIgnored';
824
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
828
* HIObjectSetAccessibilityIgnored()
831
* Marks an HIObject as ignored (or not) for the purposes of the
832
* accessibility APIs.
834
* An HIObject that is ignored for accessibility will never be shown
835
* to an assistive application that uses the accessibility APIs to
836
* examine an interface. Your application's accessibility
837
* implementation can (and should) still report an ignored HIObject
838
* as usual. Carbon's accessibility engine will automatically prune
839
* any ignored HIObjects out of the data that is shown to an
840
* assistive application.
841
* <BR>By default, an HIObject is *not* accessibility ignored.
843
* Mac OS X threading:
849
* The object whose accessibility ignored state you wish to change.
852
* A Boolean value indicating whether or not to ignore the object.
855
* An OSStatus signifying success or failure.
858
* Mac OS X: in version 10.2 and later in Carbon.framework
859
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
860
* Non-Carbon CFM: not available
862
function HIObjectSetAccessibilityIgnored( inObject: HIObjectRef; inIgnored: Boolean ): OSStatus; external name '_HIObjectSetAccessibilityIgnored';
863
(* AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER *)
867
* HIObjectSetAuxiliaryAccessibilityAttribute()
870
* Associates an additional accessibility attribute with a UIElement
871
* that is used to represent a given HIObject or a part thereof.
874
* This routine lets your application provide the name of and data
875
* for an accessibility attribute that you want to add to the
876
* UIElement used to represent a given HIObject-identifier pair.
877
* Normally, accessibility attributes can only be supplied
878
* dynamically via Carbon Events, but this routine allows you to
879
* supply them statically.
881
* When an accessibility attribute Carbon Event is handled by the
882
* HIObject with a given identifier, the toolbox automatically
883
* supplies the names and/or values of any auxiliary attributes
884
* associated with that HIObject- identifier pair.
886
* This routine is particularly useful for supplying values for the
887
* kAXDescriptionAttribute, kAXTitleUIElementAttribute,
888
* kAXServesAsTitleUIElementAttribute, kAXLinkedUIElementsAttribute
889
* and other attributes whose value is specific to the layout and
890
* usage of your application.
892
* This routine only allows you to associate attributes whose values
893
* never change. If you need to supply attributes whose values are
894
* determined dynamically or whose values are settable, you must
895
* install the normal accessibility Carbon Event handlers.
897
* The auxiliary attribute store is consulted during the HIObject's
898
* default handling of the accessibility attribute Carbon Events.
899
* This means that any programmatic handling of a given
900
* accessibility attribute will have a chance to override or block
901
* the consultation of the store. The general rule is that if the
902
* toolbox or a Carbon Event handler can provide the attribute value
903
* some other way, the store will not be consulted.
905
* Mac OS X threading:
911
* The HIObjectRef part of the object-identifier pair to which the
912
* attribute data is associated.
915
* The 64-bit identifier part of the object-identifier pair to
916
* which the attribute data is associated. When you want to
917
* associate the attribute data to the HIObject as a whole -- such
918
* as when you want to give a description attribute to a push
919
* button -- you should pass zero in this parameter.
922
* A CFStringRef of the name of the attribute you wish to
923
* associate with the object-identifier pair. This string will be
924
* retained before adding it to the auxiliary attribute store.
927
* A CFTypeRef with the data to be supplied as the attribute's
928
* value. This data will be retained before adding it to the
929
* auxiliary attribute store; you may release inAttributeData
930
* after you have called this routine. The inAttributeData
931
* parameter may also be NULL, which indicates that the named
932
* auxiliary attribute should no longer be associated with the
933
* object-identifier pair; any named attribute data previously
934
* associated with the object-identifier pair will be released.
937
* An OSStatus result code. The function will return noErr if it was
938
* able to associate the attribute data with the HIObjectRef. If the
939
* HIObjectRef is invalid, paramErr will be returned. Other results
940
* may be returned in other situations.
943
* Mac OS X: in version 10.4 and later in Carbon.framework
944
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.4 and later
945
* Non-Carbon CFM: not available
947
function HIObjectSetAuxiliaryAccessibilityAttribute( inHIObject: HIObjectRef; inIdentifier: UInt64; inAttributeName: CFStringRef; inAttributeData: CFTypeRef { can be NULL } ): OSStatus; external name '_HIObjectSetAuxiliaryAccessibilityAttribute';
948
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
952
* HIObjectOverrideAccessibilityContainment()
955
* Allows you to override the AXUIElementRefs that an HIObject would
956
* normally supply as the values of its AXParent, AXWindow, and
957
* AXTopLevelUIElement attributes.
960
* This routine allows you to change the parent that an HIObject
961
* would normally supply in the accessibility hierarchy. For
962
* instance, a popup control could call this routine on its menu so
963
* that the menu returned the popup control as the menu's parent;
964
* normally the menu would return the application as its parent.
965
* Optionally, this routine also allows you to change the window and
966
* top-level element that an HIObject would normally supply.
968
* If the input HIObject is a standard toolbox construct like an
969
* HIView or a Menu, the input HIObject will not be added as an
970
* accessibility child of its normal parent. In all other cases, it
971
* is the client's responsibility to ensure that the input HIObject
972
* is not added as an accessibility child of its normal parent.
974
* If the desired AXUIElementRef parent represents an HIView, a
975
* Menu, or a Window, the input HIObject will be automatically added
976
* as an accessibility child of the specified parent. In all other
977
* cases, it is the client's responsibility to manually add the
978
* input HIObject as a child of the specified parent. To represent
979
* an HIView, a Menu, or a Window, an AXUIElementRef must contain
980
* the appropriate HIObjectRef as well as an identifier value of
983
* Similar rules don't have to apply for the handling of the window
984
* and top-level element attributes because those attributes don't
985
* represent two-way relationships.
987
* A containment override is not necessarily supported by every type
988
* of HIObject. Currently, it is supported by HIViews, Menus, and
991
* Mac OS X threading:
997
* The HIObjectRef whose parent attribute you want to override.
1000
* The AXUIElementRef that you wish the HIObject to return as the
1001
* value of its AXParent attribute. This routine makes a copy of
1002
* the AXUIElementRef; you must release inDesiredParent after you
1003
* have called this routine. Passing NULL indicates that you want
1004
* the HIObject to revert to its normal, un-overridden behavior.
1007
* The AXUIElementRef that you wish the HIObject to return as the
1008
* value of its AXWindow attribute. This routine makes a copy of
1009
* the AXUIElementRef; you must release inDesiredWindow after you
1010
* have called this routine. Passing NULL indicates that you want
1011
* the HIObject to report its normal window, if any.
1013
* inDesiredTopLevelUIElement:
1014
* The AXUIElementRef that you wish the HIObject to return as the
1015
* value of its AXTopLevelUIElement attribute. This routine makes
1016
* a copy of the AXUIElementRef; you must release
1017
* inDesiredTopLevelUIElement after you have called this routine.
1018
* Passing NULL indicates that you want the HIObject to report its
1019
* normal top-level element, if any.
1022
* An OSStatus result code. If the HIObjectRef is invalid, this
1023
* routine will return paramErr.
1026
* Mac OS X: in version 10.4 and later in Carbon.framework
1027
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.4 and later
1028
* Non-Carbon CFM: not available
1030
function HIObjectOverrideAccessibilityContainment( inHIObject: HIObjectRef; inDesiredParent: AXUIElementRef; inDesiredWindow: AXUIElementRef; inDesiredTopLevelUIElement: AXUIElementRef ): OSStatus; external name '_HIObjectOverrideAccessibilityContainment';
1031
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1035
* HIObjectIsArchivingIgnored()
1038
* Reports whether or not the given HIObject is marked as ignored
1040
* See the discussion of HIObjectSetArchivingIgnored for details on
1041
* what it means to be archiving ignored.
1043
* Mac OS X threading:
1049
* The object whose archiving ignored state you wish to query.
1052
* A Boolean value indicating whether or not the HIObject is ignored
1056
* Mac OS X: in version 10.4 and later in Carbon.framework
1057
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.4 and later
1058
* Non-Carbon CFM: not available
1060
function HIObjectIsArchivingIgnored( inObject: HIObjectRef ): Boolean; external name '_HIObjectIsArchivingIgnored';
1061
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1065
* HIObjectSetArchivingIgnored()
1068
* Marks an HIObject as ignored (or not) for the purposes of the
1070
* An HIObject that is ignored for archiving will never be requested
1071
* to encode itself into an archive. This is a statement that the
1072
* HIObject does not handle the archiving protocol.
1073
* By default, an HIObject *is* archiving ignored.
1075
* Mac OS X threading:
1081
* The object whose archiving ignored state you wish to change.
1084
* A Boolean value indicating whether or not to ignore the object.
1087
* An OSStatus signifying success or failure.
1090
* Mac OS X: in version 10.4 and later in Carbon.framework
1091
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.4 and later
1092
* Non-Carbon CFM: not available
1094
function HIObjectSetArchivingIgnored( inObject: HIObjectRef; inIgnored: Boolean ): OSStatus; external name '_HIObjectSetArchivingIgnored';
1095
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1099
Standard custom archive data dictionary keys describing custom initialize event parameters.
1100
Each keyed value is an array of OSTypes represented by CFStrings. Use UTCreateStringForOSType
1101
and UTGetOSTypeFromString in UTType.h for CFStringRef <-> OSType conversion.
1104
* kHIObjectCustomDataParameterNamesKey
1106
* Mac OS X threading:
1110
* Mac OS X: in version 10.4 and later in Carbon.framework
1111
* CarbonLib: not available
1112
* Non-Carbon CFM: not available
1114
var kHIObjectCustomDataParameterNamesKey: CFStringRef; external name '_kHIObjectCustomDataParameterNamesKey'; (* attribute const *)
1115
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1117
* kHIObjectCustomDataParameterTypesKey
1119
* Mac OS X threading:
1123
* Mac OS X: in version 10.4 and later in Carbon.framework
1124
* CarbonLib: not available
1125
* Non-Carbon CFM: not available
1127
var kHIObjectCustomDataParameterTypesKey: CFStringRef; external name '_kHIObjectCustomDataParameterTypesKey'; (* attribute const *)
1128
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1130
* kHIObjectCustomDataParameterValuesKey
1132
* Mac OS X threading:
1136
* Mac OS X: in version 10.4 and later in Carbon.framework
1137
* CarbonLib: not available
1138
* Non-Carbon CFM: not available
1140
var kHIObjectCustomDataParameterValuesKey: CFStringRef; external name '_kHIObjectCustomDataParameterValuesKey'; (* attribute const *)
1141
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1144
Standard custom archive data dictionary keys defining a class and superclass for clients who do
1145
not implement the object's true class. Each keyed value is a CFStringRef based HIObject class ID.
1148
* kHIObjectCustomDataClassIDKey
1150
* Mac OS X threading:
1154
* Mac OS X: in version 10.4 and later in Carbon.framework
1155
* CarbonLib: not available
1156
* Non-Carbon CFM: not available
1158
var kHIObjectCustomDataClassIDKey: CFStringRef; external name '_kHIObjectCustomDataClassIDKey'; (* attribute const *)
1159
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1161
* kHIObjectCustomDataSuperClassIDKey
1163
* Mac OS X threading:
1167
* Mac OS X: in version 10.4 and later in Carbon.framework
1168
* CarbonLib: not available
1169
* Non-Carbon CFM: not available
1171
var kHIObjectCustomDataSuperClassIDKey: CFStringRef; external name '_kHIObjectCustomDataSuperClassIDKey'; (* attribute const *)
1172
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1175
Standard custom archive data dictionary key for ProcPointer based CDEFs. The key value is a
1176
CFString based SInt16. Use CFStringGetIntValue in CFString.h for CFStringRef <-> SInt16 conversion.
1179
* kHIObjectCustomDataCDEFProcIDKey
1181
* Mac OS X threading:
1185
* Mac OS X: in version 10.4 and later in Carbon.framework
1186
* CarbonLib: not available
1187
* Non-Carbon CFM: not available
1189
var kHIObjectCustomDataCDEFProcIDKey: CFStringRef; external name '_kHIObjectCustomDataCDEFProcIDKey'; (* attribute const *)
1190
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1193
* HIObjectCopyCustomArchiveData()
1196
* Copies the custom archive data associated with an HIObject that
1197
* has been read from or will be written to an archive. Useful for
1198
* an archive editor that has read a custom object from an archive
1199
* and would like to edit its custom data.
1201
* Mac OS X threading:
1207
* The object whose custom archive data you wish to retrieve.
1210
* On return, a CFDictionaryRef containing the custom data. The
1211
* client is responsible for releasing the dictionary. NULL will
1212
* be returned if there is no custom archive data available.
1215
* An OSStatus signifying success or failure.
1218
* Mac OS X: in version 10.4 and later in Carbon.framework
1219
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.4 and later
1220
* Non-Carbon CFM: not available
1222
function HIObjectCopyCustomArchiveData( inObject: HIObjectRef; var outCustomData: CFDictionaryRef ): OSStatus; external name '_HIObjectCopyCustomArchiveData';
1223
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
1227
* HIObjectSetCustomArchiveData()
1230
* Retrieves the custom archive data associated with an HIObject
1231
* that has been read from or will be written to an archive. Useful
1232
* for an archive editor that has edited a custom object's custom
1233
* data and would like it to be written to an archive with the
1236
* Mac OS X threading:
1242
* The object whose custom archive data you wish to change.
1245
* A CFDictionaryRef containing the custom archive data you would
1246
* like to associate with the object. Setting custom data will
1247
* replace any existing custom data. Passing NULL will clear the
1248
* custom archive data. The dictionary's keys and values must use
1249
* CFType callbacks for archiving purposes.
1252
* An OSStatus signifying success or failure.
1255
* Mac OS X: in version 10.4 and later in Carbon.framework
1256
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.4 and later
1257
* Non-Carbon CFM: not available
1259
function HIObjectSetCustomArchiveData( inObject: HIObjectRef; inCustomData: CFDictionaryRef { can be NULL } ): OSStatus; external name '_HIObjectSetCustomArchiveData';
1260
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)