ATSUnicodeDirectAccess.pas 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465
  1. {
  2. File: QD/ATSUnicodeDirectAccess.h
  3. Contains: Public Interfaces/Types for Low Level ATSUI
  4. Version: Quickdraw-150~1
  5. Copyright: © 2002-2003 by Apple Computer, Inc., all rights reserved.
  6. Bugs?: For bug reports, consult the following page on
  7. the World Wide Web:
  8. http://www.freepascal.org/bugs.html
  9. }
  10. { Pascal Translation: Peter N Lewis, <[email protected]>, 2004 }
  11. {
  12. Modified for use with Free Pascal
  13. Version 200
  14. Please report any bugs to <[email protected]>
  15. }
  16. {$mode macpas}
  17. {$packenum 1}
  18. {$macro on}
  19. {$inline on}
  20. {$CALLING MWPASCAL}
  21. unit ATSUnicodeDirectAccess;
  22. interface
  23. {$setc UNIVERSAL_INTERFACES_VERSION := $0342}
  24. {$setc GAP_INTERFACES_VERSION := $0200}
  25. {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
  26. {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
  27. {$endc}
  28. {$ifc defined CPUPOWERPC and defined CPUI386}
  29. {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
  30. {$endc}
  31. {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
  32. {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
  33. {$endc}
  34. {$ifc not defined __ppc__ and defined CPUPOWERPC}
  35. {$setc __ppc__ := 1}
  36. {$elsec}
  37. {$setc __ppc__ := 0}
  38. {$endc}
  39. {$ifc not defined __i386__ and defined CPUI386}
  40. {$setc __i386__ := 1}
  41. {$elsec}
  42. {$setc __i386__ := 0}
  43. {$endc}
  44. {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
  45. {$error Conflicting definitions for __ppc__ and __i386__}
  46. {$endc}
  47. {$ifc defined __ppc__ and __ppc__}
  48. {$setc TARGET_CPU_PPC := TRUE}
  49. {$setc TARGET_CPU_X86 := FALSE}
  50. {$elifc defined __i386__ and __i386__}
  51. {$setc TARGET_CPU_PPC := FALSE}
  52. {$setc TARGET_CPU_X86 := TRUE}
  53. {$elsec}
  54. {$error Neither __ppc__ nor __i386__ is defined.}
  55. {$endc}
  56. {$setc TARGET_CPU_PPC_64 := FALSE}
  57. {$ifc defined FPC_BIG_ENDIAN}
  58. {$setc TARGET_RT_BIG_ENDIAN := TRUE}
  59. {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
  60. {$elifc defined FPC_LITTLE_ENDIAN}
  61. {$setc TARGET_RT_BIG_ENDIAN := FALSE}
  62. {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
  63. {$elsec}
  64. {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
  65. {$endc}
  66. {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
  67. {$setc CALL_NOT_IN_CARBON := FALSE}
  68. {$setc OLDROUTINENAMES := FALSE}
  69. {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
  70. {$setc OPAQUE_UPP_TYPES := TRUE}
  71. {$setc OTCARBONAPPLICATION := TRUE}
  72. {$setc OTKERNEL := FALSE}
  73. {$setc PM_USE_SESSION_APIS := TRUE}
  74. {$setc TARGET_API_MAC_CARBON := TRUE}
  75. {$setc TARGET_API_MAC_OS8 := FALSE}
  76. {$setc TARGET_API_MAC_OSX := TRUE}
  77. {$setc TARGET_CARBON := TRUE}
  78. {$setc TARGET_CPU_68K := FALSE}
  79. {$setc TARGET_CPU_MIPS := FALSE}
  80. {$setc TARGET_CPU_SPARC := FALSE}
  81. {$setc TARGET_OS_MAC := TRUE}
  82. {$setc TARGET_OS_UNIX := FALSE}
  83. {$setc TARGET_OS_WIN32 := FALSE}
  84. {$setc TARGET_RT_MAC_68881 := FALSE}
  85. {$setc TARGET_RT_MAC_CFM := FALSE}
  86. {$setc TARGET_RT_MAC_MACHO := TRUE}
  87. {$setc TYPED_FUNCTION_POINTERS := TRUE}
  88. {$setc TYPE_BOOL := FALSE}
  89. {$setc TYPE_EXTENDED := FALSE}
  90. {$setc TYPE_LONGLONG := TRUE}
  91. uses MacTypes,ATSLayoutTypes,ATSUnicodeTypes,TextCommon;
  92. {$ALIGN MAC68K}
  93. { ---------------------------------------------------------------------------- }
  94. { Constants }
  95. { ---------------------------------------------------------------------------- }
  96. {
  97. * ATSUDirectDataSelector
  98. *
  99. * Summary:
  100. * These are the data selectors used in the
  101. * ATSUDirectGetLayoutDataArrayPtr function to get the needed layout
  102. * data array pointer.
  103. }
  104. type ATSUDirectDataSelector = UInt32;
  105. const
  106. {
  107. * Returns the parallel advance delta (delta X) array. (Array Type):
  108. * Fixed (Return Time): Constant, unless creation is necessary, or
  109. * unless requested by ATSUDirectGetLayoutDataArrayPtrFromTextLayout.
  110. * (Creation): This array is created only on demand. Thus, if any
  111. * changes are to be made iCreate should be set to true. If the array
  112. * had not been previously allocated it will be allocated and
  113. * zero-filled when iCreate is set to true.
  114. }
  115. kATSUDirectDataAdvanceDeltaFixedArray = 0;
  116. {
  117. * Returns the parallel baseline delta (delta Y) array. (Array Type):
  118. * Fixed (Return Time): Constant, unless creation is necessary, or
  119. * unless requested by ATSUDirectGetLayoutDataArrayPtrFromTextLayout.
  120. * (Creation): This array is created only on demand. Thus, if any
  121. * changes are to be made iCreate should be set to true. If the array
  122. * had not been previously allocated it will be allocated and
  123. * zero-filled when iCreate is set to true.
  124. }
  125. kATSUDirectDataBaselineDeltaFixedArray = 1;
  126. {
  127. * Returns the parallel device delta array for device- specific
  128. * tweaking. This is an array of values which are used to adjust
  129. * truncated fractional values for devices that do not accept
  130. * fractional positioning. It is also used to provide precise
  131. * positioning for connected scripts. (Array Type): SInt16 (Return
  132. * Time): Constant, unless creation is necessary, or unless requested
  133. * by ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
  134. * array is created only on demand. Thus, if any changes are to be
  135. * made iCreate should be set to true. If the array had not been
  136. * previously allocated it will be allocated and zero-filled when
  137. * iCreate is set to true.
  138. }
  139. kATSUDirectDataDeviceDeltaSInt16Array = 2;
  140. {
  141. * Returns the parallel style index array. The indexes setting in the
  142. * array are indexes into the the StyleSetting array, which can be
  143. * obtained using the
  144. * kATSUDirectDataStyleSettingATSUStyleSettingRefArray below. (Array
  145. * Type): UInt16 (Return Time): Constant, unless creation is
  146. * necessary, or unless requested by
  147. * ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
  148. * array is created only on demand. Thus, if any changes are to be
  149. * made iCreate should be set to true. If the array had not been
  150. * previously allocated it will be allocated and zero-filled when
  151. * iCreate is set to true.
  152. }
  153. kATSUDirectDataStyleIndexUInt16Array = 3;
  154. {
  155. * Returns the style setting ref array. (Array Type):
  156. * ATSUStyleSettingRef (Return Time): Linear, based on the number of
  157. * styles applied to the given line. (Creation): This array is always
  158. * present if the layout has any text assigned to it at all. Setting
  159. * iCreate has no effect.
  160. }
  161. kATSUDirectDataStyleSettingATSUStyleSettingRefArray = 4;
  162. {
  163. * Returns the ATSLayoutRecord, version 1 array. This should not be
  164. * used directly at all. Rather, use the
  165. * kATSUDirectDataLayoutRecordATSLayoutRecordCurrent selector below.
  166. * This will ensure that the code will always be using the most
  167. * current version of the ATSLayoutRecord, should there ever be a
  168. * change. ATSUI will only ensure the most efficient processing will
  169. * occur for the latest version of ATSLayoutRecord. (Array Type):
  170. * ATSLayoutRecord, version 1 (Return Time): Constant, unless
  171. * creation is necessary, or unless requested by
  172. * ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
  173. * array is always present if the layout has any text assigned to it
  174. * at all. Setting iCreate has no effect
  175. }
  176. kATSUDirectDataLayoutRecordATSLayoutRecordVersion1 = 100;
  177. {
  178. * Returns the ATSLayoutRecord. This will return the most current
  179. * version of the ATSLayoutRecord, and the one that's defined in this
  180. * file. Always use kATSUDirectDataLayoutRecordATSLayoutRecordCurrent
  181. * to get the array of ATSLayoutRecords. (Array Type):
  182. * ATSLayoutRecord (Return Time): Constant, unless creation is
  183. * necessary, or unless requested by
  184. * ATSUDirectGetLayoutDataArrayPtrFromTextLayout. (Creation): This
  185. * array is always present if the layout has any text assigned to it
  186. * at all. Setting iCreate has no effect.
  187. }
  188. kATSUDirectDataLayoutRecordATSLayoutRecordCurrent = kATSUDirectDataLayoutRecordATSLayoutRecordVersion1;
  189. { ---------------------------------------------------------------------------- }
  190. { Data Types }
  191. { ---------------------------------------------------------------------------- }
  192. {
  193. * ATSUStyleSettingRef
  194. *
  195. * Summary:
  196. * A reference to a style setting object that represents an
  197. * ATSUStyle plus any cached/set information about that style.
  198. }
  199. type
  200. ATSUStyleSettingRef = ^SInt32; { an opaque 32-bit type }
  201. { ---------------------------------------------------------------------------- }
  202. { Direct Accessors }
  203. { ---------------------------------------------------------------------------- }
  204. {
  205. * ATSUDirectGetLayoutDataArrayPtrFromLineRef()
  206. *
  207. * Summary:
  208. * Returns the data pointer specified by iDataSelector and
  209. * referenced by iLineRef.
  210. *
  211. * Discussion:
  212. * This function simply returns the data pointer specified by
  213. * iDataSelector and referenced by iLineRef. This data pointer
  214. * should not be freed directly after it's been used. Rather, it
  215. * should be released using ATSUDirectReleaseLayoutDataArrayPtr.
  216. * Doing so serves as a signal to ATSUI that the caller is done with
  217. * the data and that it can merge it in smoothly and adjust its
  218. * internal processes. Furthermore, it may be the case that the
  219. * pointer returned may be dynamically allocated one or contain
  220. * dynamically allocated data. If it's not properly freed, a memory
  221. * leak may result. This function may only be called within the
  222. * context of an ATSUDirectLayoutOperationOverrideUPP callback. The
  223. * pointer returned points to the exact data referenced by the
  224. * ATSUTextLayout object that triggered the callback call. This is
  225. * by far the most efficient way to use the direct access calls
  226. * because for most requested data, no allocation and copy is done.
  227. * Furthermore, because this a direct pointer to the data that ATSUI
  228. * will use for it's layout, the data arrays returned by this can be
  229. * tweaked and edited. Many of the requested arrays are created by
  230. * ATSUI only when necessary. If these arrays are to be altered,
  231. * then be sure to set iCreate to true. This will ensure that this
  232. * array is created. If the arrays are not created, ATSUI
  233. * automatically assumes that all entries in the array are zero. The
  234. * pointer returned by this function is only valid within the
  235. * context of the callback. Do not attempt to retain it for later
  236. * use.
  237. *
  238. * Parameters:
  239. *
  240. * iLineRef:
  241. * The ATSULineRef which was passed into a
  242. * ATSUDirectLayoutOperationOverrideUPP callback function as a
  243. * parameter.
  244. *
  245. * iDataSelector:
  246. * The selector for the data that is being requested.
  247. *
  248. * iCreate:
  249. * If the ATSULineRef passed in iLineRef does not reference the
  250. * requested array, then a zero-filled one will be created and
  251. * returned in oLayoutDataArray if this is set to true. For some
  252. * ATSUDirectDataSelectors, these cannot be simply created. Thus,
  253. * this flag will have no affect on these few
  254. * ATSUDirectDataSelectors.
  255. *
  256. * oLayoutDataArrayPtr:
  257. * Upon sucessful return, this parameter will contain a pointer to
  258. * an array of the requested values if the ATSULineRef passed in
  259. * iLineRef references those values. If this is not the case, then
  260. * NULL will be returned, unless iCreate is set to true and the
  261. * array can be created. This parameter itself may be set to NULL
  262. * if only a count of the entries is needed. can be NULL
  263. *
  264. * oLayoutDataCount:
  265. * Upon sucessful return, this parameter will contain a count of
  266. * the entries in the array returned in oLayoutDataArray.
  267. *
  268. * Availability:
  269. * Mac OS X: in version 10.2 and later in ApplicationServices.framework
  270. * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
  271. * Non-Carbon CFM: not available
  272. }
  273. // AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
  274. function ATSUDirectGetLayoutDataArrayPtrFromLineRef( iLineRef: ATSULineRef; iDataSelector: ATSUDirectDataSelector; iCreate: Boolean; oLayoutDataArrayPtr: PtrPtr; var oLayoutDataCount: ItemCount ): OSStatus; external name '_ATSUDirectGetLayoutDataArrayPtrFromLineRef';
  275. { ---------------------------------------------------------------------------- }
  276. {
  277. * ATSUDirectGetLayoutDataArrayPtrFromTextLayout()
  278. *
  279. * Summary:
  280. * Returns the data pointer specified by iDataSelector and
  281. * referenced by iTextLayout for the line starting at iLineOffset.
  282. *
  283. * Discussion:
  284. * This function simply returns the data pointer specified by
  285. * iDataSelector and referenced by iTextLayout for the line starting
  286. * at iLineOffset. This data pointer should not be freed directly
  287. * after it's been used. Rather, it should be released using
  288. * ATSUDirectReleaseLayoutDataArrayPtr. Doing so serves as a signal
  289. * to ATSUI that the caller is done with the data. Furthermore, it
  290. * may be the case that the pointer returned may be dynamically
  291. * allocated one or contain dynamically allocated data. If it's not
  292. * properly freed, a memory leak may result. This function may not
  293. * be called inside the context of an
  294. * ATSUDirectLayoutOperationOverrideUPP callback for the
  295. * ATSUTextLayout data that triggered the callback. All data
  296. * returned will be a copy of the data in the object requested. This
  297. * means two things: first of all, this means that it's a very
  298. * inefficient way of using the data. All of the selectors that
  299. * would have returned in constant time now would be forced to
  300. * return in order-n time. Second of all, this means that the
  301. * developer cannot change any of the data. Any changes the
  302. * developer makes to the arrays returned by this API will have no
  303. * effect on the layout. Using the
  304. * kATSULayoutOperationPostLayoutAdjustment operation selector
  305. * override and the ATSUDirectGetLayoutDataArrayPtrFromLineRef is a
  306. * great alternative to using this API. Many of the requested arrays
  307. * are created by ATSUI only when necessary. This means that it's
  308. * possible that this API will return NULL pointer and a count of 0.
  309. * In this case, if there's no error returned, the array simply
  310. * doesn't exist and the caller should treat all of the entries in
  311. * the array that they would have recieved as being 0.
  312. *
  313. * Parameters:
  314. *
  315. * iTextLayout:
  316. * The ATSUTextLayout object from which the requested data will
  317. * come from.
  318. *
  319. * iLineOffset:
  320. * The edge offset that corresponds to the beginning of the range
  321. * of text of the line of the requested data. If the text has
  322. * multiple lines, then ATSUDirectGetLayoutDataArrayPtrFromLineRef
  323. * will need to be called for each of the lines in which the
  324. * requested data is needed.
  325. *
  326. * iDataSelector:
  327. * The selector for the data that is being requested.
  328. *
  329. * oLayoutDataArrayPtr:
  330. * Upon sucessful return, this parameter will contain a pointer to
  331. * an array of the requested values if the ATSUTextLayout passed
  332. * in iTextLayout references those values for the line offset
  333. * iLineOffset. If this is not the case, then NULL will be
  334. * returned. This parameter itself may be set to NULL if only a
  335. * count of the entries is needed. can be NULL
  336. *
  337. * oLayoutDataCount:
  338. * Upon sucessful return, this parameter will contain a count of
  339. * the entries in the array returned in oLayoutDataArray.
  340. *
  341. * Availability:
  342. * Mac OS X: in version 10.2 and later in ApplicationServices.framework
  343. * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
  344. * Non-Carbon CFM: not available
  345. }
  346. // AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
  347. function ATSUDirectGetLayoutDataArrayPtrFromTextLayout( iTextLayout: ATSUTextLayout; iLineOffset: UniCharArrayOffset; iDataSelector: ATSUDirectDataSelector; oLayoutDataArrayPtr: PtrPtr; var oLayoutDataCount: ItemCount ): OSStatus; external name '_ATSUDirectGetLayoutDataArrayPtrFromTextLayout';
  348. { ---------------------------------------------------------------------------- }
  349. {
  350. * ATSUDirectReleaseLayoutDataArrayPtr()
  351. *
  352. * Summary:
  353. * Properly releases of an array pointer returned by
  354. * ATSUDirectGetLayoutDataArrayPtrFromLineRef() or
  355. * ATSUDirectGetLayoutDataArrayPtrFromTextLayout.
  356. *
  357. * Discussion:
  358. * This function is needed to let ATSUI know that the caller is
  359. * finished with the pointer that was previously requested by
  360. * ATSUDirectGetLayoutDataArrayPtrFromLineRef() or
  361. * ATSUDirectGetLayoutDataArrayPtrFromTextLayout(). This is needed
  362. * in case ATSUI needs to make any internal adjustments to it's
  363. * internal structures.
  364. *
  365. * Parameters:
  366. *
  367. * iLineRef:
  368. * The lineRef from which the layout data array pointer came from.
  369. * If the layout data array pointer did not come from a lineRef,
  370. * then set this to NULL. can be NULL
  371. *
  372. * iDataSelector:
  373. * The selector for which iLayoutDataArrayPtr was obtained.
  374. *
  375. * iLayoutDataArrayPtr:
  376. * A pointer to the layout data array which is to be disposed of.
  377. *
  378. * Availability:
  379. * Mac OS X: in version 10.2 and later in ApplicationServices.framework
  380. * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
  381. * Non-Carbon CFM: not available
  382. }
  383. // AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
  384. function ATSUDirectReleaseLayoutDataArrayPtr( iLineRef: ATSULineRef; iDataSelector: ATSUDirectDataSelector; iLayoutDataArrayPtr: PtrPtr ): OSStatus; external name '_ATSUDirectReleaseLayoutDataArrayPtr';
  385. { ---------------------------------------------------------------------------- }
  386. {
  387. * ATSUDirectAddStyleSettingRef()
  388. *
  389. * Summary:
  390. * This function will fetch a style index for the
  391. * ATSUStyleSettingRef passed in.
  392. *
  393. * Discussion:
  394. * This function allows for glyph replacement or substitution from
  395. * one layout or line to another layout or line. Not only will it
  396. * look up the style index for iStyleSettingRef, but if the
  397. * ATSUStyleSettingRef passed in iStyleSettingRef is not yet part of
  398. * the line referenced by iLineRef, it will add it. If there is an
  399. * outstanding ATSUStyleSettingRef array obtained by using the
  400. * kATSUDirectDataStyleSettingATSUStyleSettingRefArray selector, the
  401. * pointer obtained for this may no longer be valid after this
  402. * function has been called. These pointers should be freed before
  403. * calling this function and re-obtained afterwards.
  404. *
  405. * Parameters:
  406. *
  407. * iLineRef:
  408. * An ATSULineRef which was passed into a
  409. * ATSUDirectLayoutOperationOverrideUPP callback function as a
  410. * parameter.
  411. *
  412. * iStyleSettingRef:
  413. * The ATSUStyleSettingRef to be looked up or added to the
  414. * ATSUTextLayout referenced by iTextLayout for the line starting
  415. * at the offset iLineOffset.
  416. *
  417. * oStyleIndex:
  418. * Upon sucessful return, this will parameter will be set to the
  419. * index of the ATSUStyleSettingRef passed in iStyleSettingRef for
  420. * the line referenced by iLineRef. If the ATSUStyleSettingRef
  421. * does not exist, in that context, then it will be added and the
  422. * new index will be returned here.
  423. *
  424. * Availability:
  425. * Mac OS X: in version 10.2 and later in ApplicationServices.framework
  426. * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
  427. * Non-Carbon CFM: not available
  428. }
  429. // AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
  430. function ATSUDirectAddStyleSettingRef( iLineRef: ATSULineRef; iStyleSettingRef: ATSUStyleSettingRef; var oStyleIndex: UInt16 ): OSStatus; external name '_ATSUDirectAddStyleSettingRef';
  431. end.