2
File: QD/ATSUnicodeDirectAccess.h
4
Contains: Public Interfaces/Types for Low Level ATSUI
6
Version: Quickdraw-150~1
8
Copyright: � 2002-2003 by Apple Computer, Inc., all rights reserved.
10
Bugs?: For bug reports, consult the following page on
13
http://www.freepascal.org/bugs.html
16
{ Pascal Translation: Peter N Lewis, <peter@stairways.com.au>, 2004 }
20
Modified for use with Free Pascal
22
Please report any bugs to <gpc@microbizz.nl>
31
unit ATSUnicodeDirectAccess;
33
{$setc UNIVERSAL_INTERFACES_VERSION := $0342}
34
{$setc GAP_INTERFACES_VERSION := $0200}
36
{$ifc not defined USE_CFSTR_CONSTANT_MACROS}
37
{$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
40
{$ifc defined CPUPOWERPC and defined CPUI386}
41
{$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
43
{$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
44
{$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
47
{$ifc not defined __ppc__ and defined CPUPOWERPC}
52
{$ifc not defined __i386__ and defined CPUI386}
58
{$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
59
{$error Conflicting definitions for __ppc__ and __i386__}
62
{$ifc defined __ppc__ and __ppc__}
63
{$setc TARGET_CPU_PPC := TRUE}
64
{$setc TARGET_CPU_X86 := FALSE}
65
{$elifc defined __i386__ and __i386__}
66
{$setc TARGET_CPU_PPC := FALSE}
67
{$setc TARGET_CPU_X86 := TRUE}
69
{$error Neither __ppc__ nor __i386__ is defined.}
71
{$setc TARGET_CPU_PPC_64 := FALSE}
73
{$ifc defined FPC_BIG_ENDIAN}
74
{$setc TARGET_RT_BIG_ENDIAN := TRUE}
75
{$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
76
{$elifc defined FPC_LITTLE_ENDIAN}
77
{$setc TARGET_RT_BIG_ENDIAN := FALSE}
78
{$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
80
{$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
82
{$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
83
{$setc CALL_NOT_IN_CARBON := FALSE}
84
{$setc OLDROUTINENAMES := FALSE}
85
{$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
86
{$setc OPAQUE_UPP_TYPES := TRUE}
87
{$setc OTCARBONAPPLICATION := TRUE}
88
{$setc OTKERNEL := FALSE}
89
{$setc PM_USE_SESSION_APIS := TRUE}
90
{$setc TARGET_API_MAC_CARBON := TRUE}
91
{$setc TARGET_API_MAC_OS8 := FALSE}
92
{$setc TARGET_API_MAC_OSX := TRUE}
93
{$setc TARGET_CARBON := TRUE}
94
{$setc TARGET_CPU_68K := FALSE}
95
{$setc TARGET_CPU_MIPS := FALSE}
96
{$setc TARGET_CPU_SPARC := FALSE}
97
{$setc TARGET_OS_MAC := TRUE}
98
{$setc TARGET_OS_UNIX := FALSE}
99
{$setc TARGET_OS_WIN32 := FALSE}
100
{$setc TARGET_RT_MAC_68881 := FALSE}
101
{$setc TARGET_RT_MAC_CFM := FALSE}
102
{$setc TARGET_RT_MAC_MACHO := TRUE}
103
{$setc TYPED_FUNCTION_POINTERS := TRUE}
104
{$setc TYPE_BOOL := FALSE}
105
{$setc TYPE_EXTENDED := FALSE}
106
{$setc TYPE_LONGLONG := TRUE}
107
uses MacTypes,ATSLayoutTypes,ATSUnicodeTypes,TextCommon;
110
{ ---------------------------------------------------------------------------- }
112
{ ---------------------------------------------------------------------------- }
115
* ATSUDirectDataSelector
118
* These are the data selectors used in the
119
* ATSUDirectGetLayoutDataArrayPtr function to get the needed layout
120
* data array pointer.
122
type ATSUDirectDataSelector = UInt32;
126
* Returns the parallel advance delta (delta X) array. (Array Type):
127
* Fixed (Return Time): Constant, unless creation is necessary, or
128
* unless requested by ATSUDirectGetLayoutDataArrayPtrFromTextLayout.
129
* (Creation): This array is created only on demand. Thus, if any
130
* changes are to be made iCreate should be set to true. If the array
131
* had not been previously allocated it will be allocated and
132
* zero-filled when iCreate is set to true.
134
kATSUDirectDataAdvanceDeltaFixedArray = 0;
137
* Returns the parallel baseline delta (delta Y) array. (Array Type):
138
* Fixed (Return Time): Constant, unless creation is necessary, or
139
* unless requested by ATSUDirectGetLayoutDataArrayPtrFromTextLayout.
140
* (Creation): This array is created only on demand. Thus, if any
141
* changes are to be made iCreate should be set to true. If the array
142
* had not been previously allocated it will be allocated and
143
* zero-filled when iCreate is set to true.
145
kATSUDirectDataBaselineDeltaFixedArray = 1;
148
* Returns the parallel device delta array for device- specific
149
* tweaking. This is an array of values which are used to adjust
150
* truncated fractional values for devices that do not accept
151
* fractional positioning. It is also used to provide precise
152
* positioning for connected scripts. (Array Type): SInt16 (Return
153
* Time): Constant, unless creation is necessary, or unless requested
154
* by ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
155
* array is created only on demand. Thus, if any changes are to be
156
* made iCreate should be set to true. If the array had not been
157
* previously allocated it will be allocated and zero-filled when
158
* iCreate is set to true.
160
kATSUDirectDataDeviceDeltaSInt16Array = 2;
163
* Returns the parallel style index array. The indexes setting in the
164
* array are indexes into the the StyleSetting array, which can be
166
* kATSUDirectDataStyleSettingATSUStyleSettingRefArray below. (Array
167
* Type): UInt16 (Return Time): Constant, unless creation is
168
* necessary, or unless requested by
169
* ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
170
* array is created only on demand. Thus, if any changes are to be
171
* made iCreate should be set to true. If the array had not been
172
* previously allocated it will be allocated and zero-filled when
173
* iCreate is set to true.
175
kATSUDirectDataStyleIndexUInt16Array = 3;
178
* Returns the style setting ref array. (Array Type):
179
* ATSUStyleSettingRef (Return Time): Linear, based on the number of
180
* styles applied to the given line. (Creation): This array is always
181
* present if the layout has any text assigned to it at all. Setting
182
* iCreate has no effect.
184
kATSUDirectDataStyleSettingATSUStyleSettingRefArray = 4;
187
* Returns the ATSLayoutRecord, version 1 array. This should not be
188
* used directly at all. Rather, use the
189
* kATSUDirectDataLayoutRecordATSLayoutRecordCurrent selector below.
190
* This will ensure that the code will always be using the most
191
* current version of the ATSLayoutRecord, should there ever be a
192
* change. ATSUI will only ensure the most efficient processing will
193
* occur for the latest version of ATSLayoutRecord. (Array Type):
194
* ATSLayoutRecord, version 1 (Return Time): Constant, unless
195
* creation is necessary, or unless requested by
196
* ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
197
* array is always present if the layout has any text assigned to it
198
* at all. Setting iCreate has no effect
200
kATSUDirectDataLayoutRecordATSLayoutRecordVersion1 = 100;
203
* Returns the ATSLayoutRecord. This will return the most current
204
* version of the ATSLayoutRecord, and the one that's defined in this
205
* file. Always use kATSUDirectDataLayoutRecordATSLayoutRecordCurrent
206
* to get the array of ATSLayoutRecords. (Array Type):
207
* ATSLayoutRecord (Return Time): Constant, unless creation is
208
* necessary, or unless requested by
209
* ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
210
* array is always present if the layout has any text assigned to it
211
* at all. Setting iCreate has no effect.
213
kATSUDirectDataLayoutRecordATSLayoutRecordCurrent = kATSUDirectDataLayoutRecordATSLayoutRecordVersion1;
215
{ ---------------------------------------------------------------------------- }
217
{ ---------------------------------------------------------------------------- }
220
* ATSUStyleSettingRef
223
* A reference to a style setting object that represents an
224
* ATSUStyle plus any cached/set information about that style.
227
ATSUStyleSettingRef = ^SInt32; { an opaque 32-bit type }
228
{ ---------------------------------------------------------------------------- }
230
{ ---------------------------------------------------------------------------- }
232
* ATSUDirectGetLayoutDataArrayPtrFromLineRef()
235
* Returns the data pointer specified by iDataSelector and
236
* referenced by iLineRef.
239
* This function simply returns the data pointer specified by
240
* iDataSelector and referenced by iLineRef. This data pointer
241
* should not be freed directly after it's been used. Rather, it
242
* should be released using ATSUDirectReleaseLayoutDataArrayPtr.
243
* Doing so serves as a signal to ATSUI that the caller is done with
244
* the data and that it can merge it in smoothly and adjust its
245
* internal processes. Furthermore, it may be the case that the
246
* pointer returned may be dynamically allocated one or contain
247
* dynamically allocated data. If it's not properly freed, a memory
248
* leak may result. This function may only be called within the
249
* context of an ATSUDirectLayoutOperationOverrideUPP callback. The
250
* pointer returned points to the exact data referenced by the
251
* ATSUTextLayout object that triggered the callback call. This is
252
* by far the most efficient way to use the direct access calls
253
* because for most requested data, no allocation and copy is done.
254
* Furthermore, because this a direct pointer to the data that ATSUI
255
* will use for it's layout, the data arrays returned by this can be
256
* tweaked and edited. Many of the requested arrays are created by
257
* ATSUI only when necessary. If these arrays are to be altered,
258
* then be sure to set iCreate to true. This will ensure that this
259
* array is created. If the arrays are not created, ATSUI
260
* automatically assumes that all entries in the array are zero. The
261
* pointer returned by this function is only valid within the
262
* context of the callback. Do not attempt to retain it for later
268
* The ATSULineRef which was passed into a
269
* ATSUDirectLayoutOperationOverrideUPP callback function as a
273
* The selector for the data that is being requested.
276
* If the ATSULineRef passed in iLineRef does not reference the
277
* requested array, then a zero-filled one will be created and
278
* returned in oLayoutDataArray if this is set to true. For some
279
* ATSUDirectDataSelectors, these cannot be simply created. Thus,
280
* this flag will have no affect on these few
281
* ATSUDirectDataSelectors.
283
* oLayoutDataArrayPtr:
284
* Upon sucessful return, this parameter will contain a pointer to
285
* an array of the requested values if the ATSULineRef passed in
286
* iLineRef references those values. If this is not the case, then
287
* NULL will be returned, unless iCreate is set to true and the
288
* array can be created. This parameter itself may be set to NULL
289
* if only a count of the entries is needed. can be NULL
292
* Upon sucessful return, this parameter will contain a count of
293
* the entries in the array returned in oLayoutDataArray.
296
* Mac OS X: in version 10.2 and later in ApplicationServices.framework
297
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
298
* Non-Carbon CFM: not available
300
// AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
301
function ATSUDirectGetLayoutDataArrayPtrFromLineRef( iLineRef: ATSULineRef; iDataSelector: ATSUDirectDataSelector; iCreate: Boolean; oLayoutDataArrayPtr: PtrPtr; var oLayoutDataCount: ItemCount ): OSStatus; external name '_ATSUDirectGetLayoutDataArrayPtrFromLineRef';
304
{ ---------------------------------------------------------------------------- }
306
* ATSUDirectGetLayoutDataArrayPtrFromTextLayout()
309
* Returns the data pointer specified by iDataSelector and
310
* referenced by iTextLayout for the line starting at iLineOffset.
313
* This function simply returns the data pointer specified by
314
* iDataSelector and referenced by iTextLayout for the line starting
315
* at iLineOffset. This data pointer should not be freed directly
316
* after it's been used. Rather, it should be released using
317
* ATSUDirectReleaseLayoutDataArrayPtr. Doing so serves as a signal
318
* to ATSUI that the caller is done with the data. Furthermore, it
319
* may be the case that the pointer returned may be dynamically
320
* allocated one or contain dynamically allocated data. If it's not
321
* properly freed, a memory leak may result. This function may not
322
* be called inside the context of an
323
* ATSUDirectLayoutOperationOverrideUPP callback for the
324
* ATSUTextLayout data that triggered the callback. All data
325
* returned will be a copy of the data in the object requested. This
326
* means two things: first of all, this means that it's a very
327
* inefficient way of using the data. All of the selectors that
328
* would have returned in constant time now would be forced to
329
* return in order-n time. Second of all, this means that the
330
* developer cannot change any of the data. Any changes the
331
* developer makes to the arrays returned by this API will have no
332
* effect on the layout. Using the
333
* kATSULayoutOperationPostLayoutAdjustment operation selector
334
* override and the ATSUDirectGetLayoutDataArrayPtrFromLineRef is a
335
* great alternative to using this API. Many of the requested arrays
336
* are created by ATSUI only when necessary. This means that it's
337
* possible that this API will return NULL pointer and a count of 0.
338
* In this case, if there's no error returned, the array simply
339
* doesn't exist and the caller should treat all of the entries in
340
* the array that they would have recieved as being 0.
345
* The ATSUTextLayout object from which the requested data will
349
* The edge offset that corresponds to the beginning of the range
350
* of text of the line of the requested data. If the text has
351
* multiple lines, then ATSUDirectGetLayoutDataArrayPtrFromLineRef
352
* will need to be called for each of the lines in which the
353
* requested data is needed.
356
* The selector for the data that is being requested.
358
* oLayoutDataArrayPtr:
359
* Upon sucessful return, this parameter will contain a pointer to
360
* an array of the requested values if the ATSUTextLayout passed
361
* in iTextLayout references those values for the line offset
362
* iLineOffset. If this is not the case, then NULL will be
363
* returned. This parameter itself may be set to NULL if only a
364
* count of the entries is needed. can be NULL
367
* Upon sucessful return, this parameter will contain a count of
368
* the entries in the array returned in oLayoutDataArray.
371
* Mac OS X: in version 10.2 and later in ApplicationServices.framework
372
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
373
* Non-Carbon CFM: not available
375
// AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
376
function ATSUDirectGetLayoutDataArrayPtrFromTextLayout( iTextLayout: ATSUTextLayout; iLineOffset: UniCharArrayOffset; iDataSelector: ATSUDirectDataSelector; oLayoutDataArrayPtr: PtrPtr; var oLayoutDataCount: ItemCount ): OSStatus; external name '_ATSUDirectGetLayoutDataArrayPtrFromTextLayout';
379
{ ---------------------------------------------------------------------------- }
381
* ATSUDirectReleaseLayoutDataArrayPtr()
384
* Properly releases of an array pointer returned by
385
* ATSUDirectGetLayoutDataArrayPtrFromLineRef() or
386
* ATSUDirectGetLayoutDataArrayPtrFromTextLayout.
389
* This function is needed to let ATSUI know that the caller is
390
* finished with the pointer that was previously requested by
391
* ATSUDirectGetLayoutDataArrayPtrFromLineRef() or
392
* ATSUDirectGetLayoutDataArrayPtrFromTextLayout(). This is needed
393
* in case ATSUI needs to make any internal adjustments to it's
394
* internal structures.
399
* The lineRef from which the layout data array pointer came from.
400
* If the layout data array pointer did not come from a lineRef,
401
* then set this to NULL. can be NULL
404
* The selector for which iLayoutDataArrayPtr was obtained.
406
* iLayoutDataArrayPtr:
407
* A pointer to the layout data array which is to be disposed of.
410
* Mac OS X: in version 10.2 and later in ApplicationServices.framework
411
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
412
* Non-Carbon CFM: not available
414
// AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
415
function ATSUDirectReleaseLayoutDataArrayPtr( iLineRef: ATSULineRef; iDataSelector: ATSUDirectDataSelector; iLayoutDataArrayPtr: PtrPtr ): OSStatus; external name '_ATSUDirectReleaseLayoutDataArrayPtr';
418
{ ---------------------------------------------------------------------------- }
420
* ATSUDirectAddStyleSettingRef()
423
* This function will fetch a style index for the
424
* ATSUStyleSettingRef passed in.
427
* This function allows for glyph replacement or substitution from
428
* one layout or line to another layout or line. Not only will it
429
* look up the style index for iStyleSettingRef, but if the
430
* ATSUStyleSettingRef passed in iStyleSettingRef is not yet part of
431
* the line referenced by iLineRef, it will add it. If there is an
432
* outstanding ATSUStyleSettingRef array obtained by using the
433
* kATSUDirectDataStyleSettingATSUStyleSettingRefArray selector, the
434
* pointer obtained for this may no longer be valid after this
435
* function has been called. These pointers should be freed before
436
* calling this function and re-obtained afterwards.
441
* An ATSULineRef which was passed into a
442
* ATSUDirectLayoutOperationOverrideUPP callback function as a
446
* The ATSUStyleSettingRef to be looked up or added to the
447
* ATSUTextLayout referenced by iTextLayout for the line starting
448
* at the offset iLineOffset.
451
* Upon sucessful return, this will parameter will be set to the
452
* index of the ATSUStyleSettingRef passed in iStyleSettingRef for
453
* the line referenced by iLineRef. If the ATSUStyleSettingRef
454
* does not exist, in that context, then it will be added and the
455
* new index will be returned here.
458
* Mac OS X: in version 10.2 and later in ApplicationServices.framework
459
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
460
* Non-Carbon CFM: not available
462
// AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
463
function ATSUDirectAddStyleSettingRef( iLineRef: ATSULineRef; iStyleSettingRef: ATSUStyleSettingRef; var oStyleIndex: UInt16 ): OSStatus; external name '_ATSUDirectAddStyleSettingRef';