2
File: QD/ATSUnicodeDrawing.h
4
Contains: ATSUI drawing, measuring, and highlighting functions.
6
Version: Quickdraw-150~1
8
Copyright: � 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 ATSUnicodeDrawing;
33
{$setc UNIVERSAL_INTERFACES_VERSION := $0342}
34
{$setc GAP_INTERFACES_VERSION := $0210}
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,TextCommon,Quickdraw,ATSLayoutTypes,ATSUnicodeTypes;
110
{ ---------------------------------------------------------------------------- }
111
{ ATSUI drawing and measuring }
112
{ ---------------------------------------------------------------------------- }
118
* Draws a specified range of text in a QuickDraw graphics port or
119
* Quartz graphics context.
122
* Before calling ATSUDrawText, you will most likely want to call
123
* ATSUSetLayoutControls to set a value for the kATSUCGContextTag
124
* attribute in order to specify your current graphics context.
125
* Otherwise, ATSUI will attempt to draw using Quickdraw style text
126
* rendering in whatever Quickdraw GrafPort is currently active (use
127
* SetPort to determine the currently active Quickdraw GrafPort, see
128
* Quickdraw.h). Carbon applications can create a CGContext from a
129
* Quickdraw GrafPort using the functions QDBeginCGContext and
130
* QDEndCGContext (see Quickdraw.h). Cocoa applications can call the
131
* method "graphicsPort" on the current NSGraphicsContext in order
132
* to get a CGContextRef to pass into ATSUI (use the method
133
* "currentContext" to obtain the current NSGraphicsContext, see
134
* NSGraphicsContext.h for more information). ATSUDrawText examines
135
* the text layout object to ensure that each of the characters in
136
* the range is assigned to a style run. If there are gaps between
137
* style runs, ATSUI assigns the characters in the gap to the style
138
* run that precedes (in storage order) the gap. If there is no
139
* style run at the beginning of the text range, ATSUI assigns these
140
* characters to the first style run it finds. If there is no style
141
* run at the end of the text range, ATSUI assigns the remaining
142
* characters to the last style run it finds. If you want to draw a
143
* range of text that spans multiple lines, you should call
144
* ATSUDrawText for each line of text to draw, even if all the lines
145
* are in the same text layout object. You should adjust the
146
* iLineOffset parameter to reflect the beginning of each line to be
147
* drawn. Please note that when drawing into a GrafPort, calls to
148
* QDSwapTextFlags have no effect on ATSUI text rendering. The
149
* proper way to achieve Quartz text rendering from ATSUI is to use
150
* the kATSUCGContextTag attribute to specify a CGContextRef in each
151
* ATSUTextLayout before calling ATSUDrawText.
156
* A layout containing text to draw.
159
* The starting offset of the range of text to draw. To specify
160
* the beginning of the text buffer, pass kATSUFromTextBeginning
161
* for this parameter.
164
* The length of the range of text to draw. To specify a range
165
* that continues to the end of the text buffer, pass
166
* kATSUToTextEnd for this parameter.
169
* The x-coordinate of the origin (in either the current graphics
170
* port or Quartz graphics context) of the line containing the
171
* text range to render. Note that the ATSUTextMeasurement type is
172
* defined as a Fixed value, so you must ensure that your
173
* coordinates are converted to Fixed values before passing them
174
* to this function (see FixMath.h for conversion functions). Pass
175
* the constant kATSUUseGrafPortPenLoc to draw relative to the
176
* current pen location in the current graphics port.
179
* The y-coordinate of the origin (in either the current graphics
180
* port or Quartz graphics context) of the line containing the
181
* text range to render. Note that the ATSUTextMeasurement type is
182
* defined as a Fixed value, so you must ensure that your
183
* coordinates are converted to Fixed values before passing them
184
* to this function (see FixMath.h for conversion functions). Pass
185
* the constant kATSUUseGrafPortPenLoc to draw relative to the
186
* current pen location in the current graphics port.
189
* On success, noErr is returned. See MacErrors.h for possible error
193
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
194
* CarbonLib: in CarbonLib 1.0 and later
195
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
197
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
198
function ATSUDrawText( iTextLayout: ATSUTextLayout; iLineOffset: UniCharArrayOffset; iLineLength: UniCharCount; iLocationX: ATSUTextMeasurement; iLocationY: ATSUTextMeasurement ): OSStatus; external name '_ATSUDrawText';
202
* ATSUGetUnjustifiedBounds()
205
* Obtains the typographic bounding rectangle for a line of text
206
* prior to final layout.
209
* This function calculates the typographic bounds (in coordinates
210
* independent of the rendering device) for a line of text. Note
211
* that ATSUGetUnjustifiedBounds calculates these bounds prior to
212
* the text's final layout, and therefore, the calculated bounds
213
* might not reflect those of the final laid-out line.
214
* Justification, truncation, and device level positioning are not
215
* taken into account. To obtain the typographic bounds of a line
216
* after it is laid out, you can call the function
217
* ATSUGetGlyphBounds. For more infomration about the difference
218
* between typographic and image bounds, please refer to the ATSUI
219
* documentation. Note that ATSUGetUnjustifiedBounds treats the
220
* specified text range as a single line. That is, if the range of
221
* text you specify is less than a line, it nevertheless treats the
222
* initial character in the range as the start of a line, for
223
* measuring purposes. If the range of text extends beyond a line,
224
* ATSUGetUnjustifiedBounds ignores soft line breaks, again,
225
* treating the text as a single line.
230
* The text layout object to obtain bounds information for.
233
* The start of the line of text to obtain bounds information for.
234
* To indicate that the line starts at the beginning of the text
235
* buffer, you can pass the constant kATSUFromTextBeginning . To
236
* specify the entire text buffer, pass kATSUFromTextBeginning in
237
* this parameter and kATSUToTextEnd in the iLineLength parameter.
240
* The length of the line to obtain bounds information for. If you
241
* want the line to extend to the end of the text buffer, you can
242
* pass the constant kATSUToTextEnd .
245
* On return, the value specifies the starting point of the
246
* typographic bounds for the line, relative to the origin (0,0)
247
* of the line and taking into account cross-stream shifting. Note
248
* that the ATSUMeasureText function might produce negative values
249
* for the typographic starting point of the line if, for example,
250
* the initial character of the line is allowed to hang into the
251
* margin. For horizontal text, this value corresponds to the left
252
* side of the bounding rectangle.
255
* On return, the end point of the typographic bounds for the
256
* line, relative to the origin (0,0) of the line and taking into
257
* account cross-stream shifting. For horizontal text, this value
258
* corresponds to the right side of the bounding rectangle.
261
* On return, the typographic bounds for the line, relative to the
262
* origin (0,0) of the line and taking into account cross-stream
263
* shifting. For horizontal text, this value corresponds to the
264
* top side of the bounding rectangle.
267
* On return, the typographic bounds for the line, relative to the
268
* origin (0,0) of the line and taking into account cross-stream
269
* shifting. For horizontal text, this value corresponds to the
270
* bottom side of the bounding rectangle.
273
* On success, noErr is returned. See MacErrors.h for possible error
277
* Mac OS X: in version 10.2 and later in ApplicationServices.framework
278
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
279
* Non-Carbon CFM: not available
281
// AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
282
function ATSUGetUnjustifiedBounds( iTextLayout: ATSUTextLayout; iLineStart: UniCharArrayOffset; iLineLength: UniCharCount; var oTextBefore: ATSUTextMeasurement; var oTextAfter: ATSUTextMeasurement; var oAscent: ATSUTextMeasurement; var oDescent: ATSUTextMeasurement ): OSStatus; external name '_ATSUGetUnjustifiedBounds';
286
* ATSUMeasureTextImage()
289
* Obtains the image bounding rectangle for a line of text after
293
* This function obtains the image bounds of a laid-out line of
294
* text. These bounds are described by the smallest rectangle that
295
* completely encloses the filled or framed parts of a block of
296
* text�that is, the text's "inked" glyphs. In measuring the line,
297
* the ATSUMeasureTextImage function takes into account line
298
* rotation, alignment, and justification, as well as other
299
* characteristics that affect layout, such as hanging punctuation.
300
* (If the line is rotated, the sides of the rectangle are parallel
301
* to the coordinate axes and encompass the rotated line.) If no
302
* attributes are set for the line, ATSUMeasureTextImage uses the
303
* global attributes set for the text layout object. Because the
304
* height of the image bounding rectangle is determined by the
305
* actual device metrics, ATSUMeasureTextImage ignores any
306
* previously set line ascent and descent values for the line it is
312
* The text layout for which to obtain image bounds.
315
* The first character of the line to examine. To indicate that
316
* the specified line starts at the beginning of the text buffer,
317
* you can pass the constant kATSUFromTextBeginning . To specify
318
* the entire text buffer, pass kATSUFromTextBeginning in this
319
* parameter and kATSUToTextEnd in the iLineLength parameter.
322
* The length of the text range. If you want the range of text to
323
* extend to the end of the text buffer, you can pass the constant
324
* kATSUToTextEnd . However, the image bounds is restricted to the
325
* line in which iLineOffset resides.
328
* The x-coordinate of the line's origin in the current graphics
329
* port or Quartz graphics context. Pass the constant
330
* kATSUUseGrafPortPenLoc for the dimensions of the bounds
331
* relative to the current pen location in the current graphics
332
* port or graphics context. You can pass 0to obtain only the
333
* dimensions of the bounding rectangle relative to one another,
334
* not their actual onscreen position.
337
* The y-coordinate of the line's origin in the current graphics
338
* port or Quartz graphics context. Pass the constant
339
* kATSUUseGrafPortPenLoc for the dimensions of the bounds
340
* relative to the current pen location in the current graphics
341
* port or graphics context. You can pass 0to obtain only the
342
* dimensions of the bounding rectangle relative to one another,
343
* not their actual onscreen position.
346
* On return, the dimensions of the image bounding rectangle for
347
* the text, offset by the values specified in the iLocationX and
348
* iLocationY parameters. If the line is rotated, the sides of the
349
* rectangle are parallel to the coordinate axis.
352
* On success, noErr is returned. See MacErrors.h for possible error
356
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
357
* CarbonLib: in CarbonLib 1.0 and later
358
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
360
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
361
function ATSUMeasureTextImage( iTextLayout: ATSUTextLayout; iLineOffset: UniCharArrayOffset; iLineLength: UniCharCount; iLocationX: ATSUTextMeasurement; iLocationY: ATSUTextMeasurement; var oTextImageRect: Rect ): OSStatus; external name '_ATSUMeasureTextImage';
365
* ATSUGetGlyphBounds()
368
* Obtains the typographic bounds of a line of glyphs after final
372
* This function produces the enclosing trapezoid(s) that represent
373
* the typographic bounds for glyphs in a final, laid-out range of
374
* text. You typically call this function when you need to obtain an
375
* enclosing trapezoid for a line, taking rotation and all other
376
* layout attributes into account. ATSUI determines the height of
377
* each trapezoid by examining any line ascent and descent attribute
378
* values you may have set for the line. If you have not set these
379
* attributes for the line, the ATSUGetGlyphBounds function uses any
380
* line ascent and descent values you may have set for the text
381
* layout object containing the line. If these are not set,
382
* ATSUGetGlyphBounds uses the font's natural line ascent and
383
* descent values for the line. If these are previously set,
384
* ATSUGetGlyphBounds uses the ATSUStyle ascent and or
385
* descent/leading values. Note that the coordinates produced for
386
* the trapezoid(s) are offset by the amount specified in the
387
* iTextBasePointX and iTextBasePointY parameters. If your goal in
388
* calling the ATSUGetGlyphBounds function is to obtain metrics for
389
* drawing the typographic bounds on the screen, pass the position
390
* of the origin of the line in the current graphics port or
391
* graphics context in these parameters. This enables
392
* ATSUGetGlyphBounds to match the trapezoids to their onscreen
393
* image. When the range specified by the iBoundsCharStart and
394
* iBoundsCharLength parameters covers an entire line, you are
395
* guaranteed to receive only one trapezoid on return. Otherwise,
396
* multiple trapezoids may be returned to cover incomplete sections
397
* of bidi runs. In such cases, you would typically call
398
* ATSUGetGlyphBounds twice, as follows: (1) Pass NULL for the
399
* oGlyphBounds parameter, 0 for the iMaxNumberOfBounds parameter,
400
* and valid values for the other parameters. The ATSUGetGlyphBounds
401
* function returns the actual number of trapezoids needed to
402
* enclose the glyphs in the oActualNumberOfBounds parameter. (2)
403
* Allocate enough space for a buffer of the returned size, then
404
* call the function again, passing a valid pointer to the buffer in
405
* the oGlyphBounds parameter. On return, the buffer contains the
406
* trapezoids for the glyphs' typographic bounds. To obtain the
407
* typographic bounds of a line of text prior to line layout, call
408
* the function ATSUGetUnjustifiedBounds. To calculate the image
409
* bounding rectangle for a final laid-out line, call the function
410
* ATSUMeasureTextImage. For more infomration about the difference
411
* between typographic and image bounds, please refer to the ATSUI
417
* The text layout object for which glyph bounds are to be
421
* The x-coordinate of the origin of the line containing the
422
* glyphs in the current graphics port or Quartz graphics context.
423
* Pass the constant kATSUUseGrafPortPenLoc to obtain the glyph
424
* bounds relative to the current pen location in the current
425
* graphics port or graphics context. You may pass 0 to obtain
426
* only the dimensions of the bounds relative to one another, not
427
* their actual onscreen position.
430
* The y-coordinate of the origin of the line containing the
431
* glyphs in the current graphics port or Quartz graphics context.
432
* Pass the constant kATSUUseGrafPortPenLoc to obtain the glyph
433
* bounds relative to the current pen location in the current
434
* graphics port or graphics context. You may pass 0 to obtain
435
* only the dimensions of the bounds relative to one another, not
436
* their actual onscreen position.
439
* The offset from the beginning of the text buffer to the
440
* character corresponding to the first glyph to measure. To
441
* indicate that the text range starts at the beginning of the
442
* text buffer, you can pass the constant kATSUFromTextBeginning.
445
* The length of text range to measure. If you want the range to
446
* extend to the end of the text buffer, you can pass the constant
450
* The type of bounds you wish to obtain. See ATSLayoutTypes.h for
451
* a list of possible values to pass in here.
453
* iMaxNumberOfBounds:
454
* The maximum number of bounding trapezoids to obtain. Typically,
455
* this is equivalent to the number of bounds in the oGlyphBounds
456
* array. To determine this value, see the Discussion.
459
* A pointer to memory you have allocated for an array of
460
* ATSTrapezoid values. On return, the array contains a trapezoid
461
* representing the typographic bounds for glyphs in the text
462
* range. If the specified range of text encloses nested
463
* bidirectional text, ATSUGetGlyphBounds produces multiple
464
* trapezoids defining these regions.In ATSUI 1.1, the maximum
465
* number of enclosing trapezoids that can be returned is 31; in
466
* ATSUI 1.2, the maximum number is 127. If you pass a range that
467
* covers an entire line, ATSUGetGlyphBounds always returns only 1
468
* trapezoid. If you are uncertain of how much memory to allocate
469
* for this array, see the Discussion. can be NULL
471
* oActualNumberOfBounds:
472
* On return, the value specifies the actual number of enclosing
473
* trapezoids bounding the specified characters. This may be
474
* greater than the value you provide in the iMaxNumberOfBounds
475
* parameter. can be NULL
478
* On success, noErr is returned. See MacErrors.h for possible error
482
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
483
* CarbonLib: in CarbonLib 1.0 and later
484
* Non-Carbon CFM: in ATSUnicodeLib 8.6 and later
486
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
487
function ATSUGetGlyphBounds( iTextLayout: ATSUTextLayout; iTextBasePointX: ATSUTextMeasurement; iTextBasePointY: ATSUTextMeasurement; iBoundsCharStart: UniCharArrayOffset; iBoundsCharLength: UniCharCount; iTypeOfBounds: UInt16; iMaxNumberOfBounds: ItemCount; oGlyphBounds: ATSTrapezoidPtr; var oActualNumberOfBounds: ItemCount ): OSStatus; external name '_ATSUGetGlyphBounds';
490
{ ---------------------------------------------------------------------------- }
491
{ ATSUI line breaking }
492
{ ---------------------------------------------------------------------------- }
494
* ATSUBatchBreakLines()
497
* Soft wraps a range of text in a layout to a constant line width.
500
* Equivalent to repeatedly calling the ATSUBreakLine function with
501
* the parameter iUseAsSoftLineBreak set to true. Use this function
502
* to gain a substantial performance increase over the use of
503
* ATSUBreakLine. It will set soft breaks in a layout for multiple
504
* lines in a single call. It assumes constant line width. Soft line
505
* breaks within a layout are what divide it into lines. You can
506
* manipulate the soft breaks that are currently set within a layout
507
* using the functions ATSUGetSoftLineBreaks, ATSUSetSoftLineBreak,
508
* and ATSUClearSoftLineBreaks.
513
* The layout containing text to be soft wrapped.
516
* Beginning offset for the rage of text to be soft wrapped.
519
* The length of the range of text to be soft wrapped.
522
* The line width at which to force soft wrapping of text. Note
523
* that this parameter is of type ATSUTextMeasurement, which is
524
* defined as Fixed. See FixMath.h for conversion routines for
525
* fixed point values.
528
* On return, the number of soft breaks that were set in the
529
* layout. Use this to determine how much memory to allocate when
530
* calling ATSUGetSoftLineBreaks. can be NULL
533
* On success, noErr is returned. See MacErrors.h for possible error
537
* Mac OS X: in version 10.2 and later in ApplicationServices.framework
538
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
539
* Non-Carbon CFM: not available
541
// AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
542
function ATSUBatchBreakLines( iTextLayout: ATSUTextLayout; iRangeStart: UniCharArrayOffset; iRangeLength: UniCharCount; iLineWidth: ATSUTextMeasurement; oBreakCount: ItemCountPtr ): OSStatus; external name '_ATSUBatchBreakLines';
549
* Soft wraps a single line of text within a layout.
552
* This function will automatically determine the optimal place to
553
* set a soft break in a given range of text. It suggests a soft
554
* line break each time it encounters a hard line break character
555
* such as a carriage return, line feed, form feed, line separator,
556
* or paragraph separator. If ATSUBreakLine does not encounter a
557
* hard line break, it uses the line width you specify to determine
558
* how many characters fit on a line and suggests soft line breaks
559
* accordingly. You can loop over ATSUBreakLine, repeatedly calling
560
* it on the same layout, until all the text in the entire layout
561
* has been soft wrapped. However, for maximum efficiency, you
562
* should use ATSUBatchBreakLines. ATSUBreakLine should only be used
563
* if you have special needs, such as a non-constant line width.
568
* The layout containing text to be soft wrapped.
571
* The beginning of the line you wish to soft wrap. To specify the
572
* beginning of the text buffer, pass the constant
573
* kATSUFromTextBeginning.
576
* The line width at which to force soft wrapping of text. Note
577
* that this parameter is of type ATSUTextMeasurement, which is
578
* defined as Fixed. See FixMath.h for conversion routines for
579
* fixed point values.
581
* iUseAsSoftLineBreak:
582
* A Boolean value indicating whether ATSUBreakLine should
583
* automatically set the line break produced in the oLineBreak
584
* parameter. If true ,ATSUBreakLine sets the line break and
585
* clears any previously-set soft line breaks that precede the new
586
* break in the line but lie after the offset specified by
587
* iLineStart. You should ususally pass true for this parameter,
588
* unless you plan to use ATSUSetSoftLineBreak to set the soft
589
* break somewhere other than what is suggested by ATSUBreakLine.
592
* On return, the value specifies the soft line break as
593
* determined by ATSUBreakLine. If the value returned is the same
594
* value as specified in iLineStart , you have made an input
595
* parameter error. In this case, check to make sure that the line
596
* width specified in iLineWidth is big enough for ATSUBreakLine
597
* to perform line breaking. ATSUBreakLine does not return an
598
* error in this case.
601
* On success, noErr is returned. TSUI usually calculates a soft
602
* line break to be at the beginning of the first word that does ont
603
* fit on the line. But if ATSUBreakLine calculates the most optimal
604
* line break to be in the middle of a word, it returns the result
605
* code kATSULineBreakInWord. Note that ATSUI produces a line break
606
* in the middle of a word only as a last resort. See MacErrors.h
607
* for other possible error codes. can be NULL
610
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
611
* CarbonLib: in CarbonLib 1.0 and later
612
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
614
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
615
function ATSUBreakLine( iTextLayout: ATSUTextLayout; iLineStart: UniCharArrayOffset; iLineWidth: ATSUTextMeasurement; iUseAsSoftLineBreak: Boolean; oLineBreak: UniCharArrayOffsetPtr ): OSStatus; external name '_ATSUBreakLine';
619
* ATSUSetSoftLineBreak()
622
* Sets a soft line break at the specified point in a text layout.
625
* You should typically only call ATSUSetSoftLineBreak to set line
626
* breaks when you are using your own line-breaking algorithm to
627
* calculate these breaks. For optimal performance, you should use
628
* ATSUBatchBreakLines to both calculate and set soft line breaks in
629
* your text. After calling ATSUSetSoftLineBreak , you should call
630
* the function ATSUGetUnjustifiedBounds to determine whether the
631
* characters still fit within the line, which is necessary due to
632
* end-of-line effects such as swashes.
637
* The layout in which to set the soft break.
640
* An offset into the text buffer specifying the location to set
644
* On success, noErr is returned. See MacErrors.h for possible error
648
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
649
* CarbonLib: in CarbonLib 1.0 and later
650
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
652
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
653
function ATSUSetSoftLineBreak( iTextLayout: ATSUTextLayout; iLineBreak: UniCharArrayOffset ): OSStatus; external name '_ATSUSetSoftLineBreak';
657
* ATSUGetSoftLineBreaks()
660
* Obtains the soft line breaks that are currently set in a given
664
* Typically you use the function ATSUGetSoftLineBreaks by calling
665
* it twice, as follows: (1) Pass valid values for the iTextLayout,
666
* iRangeStart, iRangeLength, and oBreakCount parameters. Pass NULL
667
* for the oBreaks parameter and 0 for the iMaximumBreaks parameter.
668
* ATSUGetSoftLineBreaks returns the size of the font array in the
669
* oBreakCount parameter. (2) Allocate enough space for an array of
670
* the returned size, then call the function again, passing a valid
671
* pointer in the oBreaks parameter. On return, the pointer refers
672
* to an array containing the text range's soft line breaks. If you
673
* have just called ATSUBatchBreakLines, the oBreakCount parameter
674
* will give you the value you would normally obtain from step 1,
675
* allowing you to skip this step in such cases.
680
* A text layout to obtain a list of soft breaks from.
683
* The beginning of the range of text for which to obtain a list
684
* of softbreaks. To indicate that the specified text range starts
685
* at the beginning of the text buffer, you can pass the constant
686
* kATSUFromTextBeginning, To specify the entire text buffer, pass
687
* kATSUFromTextBeginning in this parameter and kATSUToTextEnd in
688
* the iRangeLength parameter.
691
* The end of the range of text for which to obtain a list of
692
* softbreaks. If you want the range of text to extend to the end
693
* of the text buffer, you can pass the constant kATSUToTextEnd.
696
* The maximum number of soft line breaks to obtain. Typically,
697
* this is equivalent to the number of UniCharArrayOffset values
698
* for which you have allocated memory in the oBreaks array. To
699
* determine this value, see the Discussion.
702
* On return, the array contains offsets from the beginning of the
703
* text buffer to each of the soft line breaks in the text range.
704
* If you are uncertain of how much memory to allocate for this
705
* array, see the Discussion. can be NULL
708
* On return, the number of soft breaks set in iTextLayout. Note
709
* that this value may be greater than what you pass in for
710
* iMaximumBreaks. can be NULL
713
* On success, noErr is returned. See MacErrors.h for possible error
717
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
718
* CarbonLib: in CarbonLib 1.0 and later
719
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
721
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
722
function ATSUGetSoftLineBreaks( iTextLayout: ATSUTextLayout; iRangeStart: UniCharArrayOffset; iRangeLength: UniCharCount; iMaximumBreaks: ItemCount; oBreaks: UniCharArrayOffsetPtr; oBreakCount: ItemCountPtr ): OSStatus; external name '_ATSUGetSoftLineBreaks';
726
* ATSUClearSoftLineBreaks()
729
* Unsets any currently set soft breaks in a range of text.
732
* This function clears all previously set soft line breaks for the
733
* specified text range and clears any associated layout caches as
739
* The text layout object for which to remove line breaks.
742
* The beginning of the text range over which to clear soft line
743
* breaks. To indicate that the specified text range starts at the
744
* beginning of the text buffer, you can pass the constant
745
* kATSUFromTextBeginning . To specify the entire text buffer,
746
* pass kATSUFromTextBeginning in this parameter and
747
* kATSUToTextEnd in the iRangeLength parameter.
750
* The length of the text range over which to clear soft line
751
* breaks. If you want the range of text to extend to the end of
752
* the text buffer, you can pass the constant kATSUToTextEnd.
755
* On success, noErr is returned. See MacErrors.h for possible error
759
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
760
* CarbonLib: in CarbonLib 1.0 and later
761
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
763
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
764
function ATSUClearSoftLineBreaks( iTextLayout: ATSUTextLayout; iRangeStart: UniCharArrayOffset; iRangeLength: UniCharCount ): OSStatus; external name '_ATSUClearSoftLineBreaks';
767
{ ---------------------------------------------------------------------------- }
768
{ ATSUI highlighting }
769
{ ---------------------------------------------------------------------------- }
771
* ATSUSetHighlightingMethod()
774
* Specifies the methods ATSUI will use for highlighting and
775
* unhighlighting text in a given layout.
778
* By default, ATSUI highlights text by "inverting" the region
779
* containing the text, that is, its background color. Although
780
* inversion provides satisfactory highlighting in most cases, it
781
* does not always provide the best result for grayscale text. (Mac
782
* OS X sets a lower threshold for antialiasing, while in Mac OS 9
783
* grayscale text can be turned off by the user.) In Mac OS X, when
784
* using a Quartz graphics context, you can instruct ATSUI to use
785
* the redraw method of highlighting, rather than simple inversion.
786
* (Note that Cocoa applications always use the redraw method of
787
* highlighting.) The redraw method allows for accurate highlighting
788
* of more complex backgrounds, such as those containing multiple
789
* colors, patterns, or pictures. To set redrawing on, call the
790
* ATSUSetHighlightingMethod function and specify that the redraw
791
* method be used (by passing kRedrawHighlighting in the iMethod
792
* parameter). If you specify the redraw method of highlighting when
793
* you call ATSUSetHighlightingMethod, then you must also specify
794
* how the background is to be redrawn when the function
795
* ATSUUnhighlightText is called. ATSUI can restore the desired
796
* background in one of two ways, depending on the background's
797
* complexity: (1) When the background is a single color (such as
798
* white), ATSUI can readily unhighlight the background. In such a
799
* case, you specify the background color that ATSUI uses by calling
800
* ATSUSetHighlightingMethod and setting iUnhighlightData.dataType
801
* to kATSUBackgroundColor and providing the background color in
802
* iUnhighlightData.unhighlightData. With these settings defined,
803
* when you call ATSUUnhighlightText, ATSUI simply calculates the
804
* previously highlighted area, repaints it with the specified
805
* background color, and then redraws the text. (2) When the
806
* background is more complex (containing, for example, multiple
807
* colors, patterns, or pictures), you must provide a redraw
808
* background callback function when you call
809
* ATSUSetHighlightingMethod. You do this by setting
810
* iUnhighlightData.dataType to kATSUBackgroundCallback and
811
* providing a RedrawBackgroundUPP in
812
* iUnhighlightData.unhighlightData . Then when you call
813
* ATSUUnhighlightText and ATSUI calls your callback, you are
814
* responsible for redrawing the background of the unhighlighted
815
* area. If you choose to also redraw the text, then your callback
816
* should return false as a function result. If your callback
817
* returns true ATSUI redraws any text that needs to be redrawn. See
818
* RedrawBackgroundProcPtr for additional information.
823
* The layout to which this highlight method should be applied.
826
* The type of highlighting to use; inversion
827
* (kInvertHighlighting) or redrawing (kRedrawHighlighting). The
828
* default is inversion. If you are happy with that technique
829
* there is no reason to call this function.
832
* Data needed to redraw the background or NULL if inversion is
833
* being chosen. See the definition of ATSUUnhighlightData for
834
* more information about the possible contents of this structure.
835
* Also see the Discussion for this function. can be NULL
838
* On success, noErr is returned. See MacErrors.h for possible error
842
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
843
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later
844
* Non-Carbon CFM: not available
846
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
847
function ATSUSetHighlightingMethod( iTextLayout: ATSUTextLayout; iMethod: ATSUHighlightMethod; iUnhighlightData: ATSUUnhighlightDataPtr ): OSStatus; external name '_ATSUSetHighlightingMethod';
851
* ATSUHighlightText()
854
* Renders a highlighted range of text at a specified location in a
855
* QuickDraw graphics port or Quartz graphics context.
858
* When the user selects a series of glyphs, the characters in
859
* memory corresponding to the glyphs make up the selection range
860
* and should be highlighted to indicate where the next editing
861
* operation is to occur. The characters in a selection range are
862
* always contiguous in memory, but their corresponding glyphs are
863
* not necessarily so onscreen. If the selection range crosses a
864
* direction boundary, it is appropriate to display discontinuous
865
* highlighting. The ATSUHighlightText function renders a
866
* highlighted range of text at a specified location in a QuickDraw
867
* graphics port or Quartz graphics context, using the highlight
868
* information in the graphics port or context. ATSUHighlightText
869
* automatically produces discontinuous highlighting, if needed. You
870
* typically call the ATSUHighlightText function every time you need
871
* to draw or redraw highlighted text.
876
* A layout containing text to be highlighted.
879
* The x-coordinate of the origin (in either the current graphics
880
* port or in a Quartz graphics context) of the line containing
881
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
882
* draw relative to the current pen location in the current
886
* The y-coordinate of the origin (in either the current graphics
887
* port or in a Quartz graphics context) of the line containing
888
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
889
* draw relative to the current pen location in the current
893
* The first character of the text range to be highlighted. If the
894
* text range spans multiple lines, you should call
895
* ATSUHighlightText for each line, passing the offset
896
* corresponding to the beginning of the new line to draw with
897
* each call. To indicate that the specified text range starts at
898
* the beginning of the text buffer, you can pass the constant
899
* kATSUFromTextBeginning. To specify the entire text buffer, pass
900
* kATSUFromTextBeginning in this parameter and kATSUToTextEnd in
901
* the iHighlightLength parameter.
904
* The length of the text range to be highlighted. To indicate
905
* that the text range extends to the end of the text buffer, pass
906
* the constant kATSUToTextEnd.
909
* On success, noErr is returned. See MacErrors.h for possible error
913
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
914
* CarbonLib: in CarbonLib 1.0 and later
915
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
917
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
918
function ATSUHighlightText( iTextLayout: ATSUTextLayout; iTextBasePointX: ATSUTextMeasurement; iTextBasePointY: ATSUTextMeasurement; iHighlightStart: UniCharArrayOffset; iHighlightLength: UniCharCount ): OSStatus; external name '_ATSUHighlightText';
922
* ATSUUnhighlightText()
925
* Renders a previously highlighted range of text in an
926
* unhighlighted state.
929
* This function renders a previously highlighted range of text in
930
* an unhighlighted state. You should always call
931
* ATSUUnhighlightText after calling the function ATSUHighlightText
932
* to properly redraw the unhighlighted text and background. If the
933
* inversion method of highlighting was used, when you call
934
* ATSUUnhighlightText, it merely undoes the inversion and renders
935
* the text. If the redraw method of highlighting was used,
936
* ATSUUnhighlightText turns off the highlighting and restores the
937
* desired background. Depending on the complexity of the
938
* background, ATSUI restores the background in one of two ways:
939
* filling in a solid color, or repainting the background using a
940
* callback. See the function ATSUSetHighlightingMethod and the
941
* definition ATSUUnhighlightData for more information.
946
* A layout containing text to be unhighlighted.
949
* The x-coordinate of the origin (in either the current graphics
950
* port or in a Quartz graphics context) of the line containing
951
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
952
* draw relative to the current pen location in the current
956
* The y-coordinate of the origin (in either the current graphics
957
* port or in a Quartz graphics context) of the line containing
958
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
959
* draw relative to the current pen location in the current
963
* The first character of the text range to be unhighlighted. If
964
* the text range spans multiple lines, you should call
965
* ATSUUnhighlightText for each line, passing the offset
966
* corresponding to the beginning of the new line to draw with
967
* each call. To indicate that the specified text range starts at
968
* the beginning of the text buffer, you can pass the constant
969
* kATSUFromTextBeginning. To specify the entire text buffer, pass
970
* kATSUFromTextBeginning in this parameter and kATSUToTextEnd in
971
* the iHighlightLength parameter.
974
* The length of the text range to be unhighlighted. To indicate
975
* that the text range extends to the end of the text buffer, pass
976
* the constant kATSUToTextEnd.
979
* On success, noErr is returned. See MacErrors.h for possible error
983
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
984
* CarbonLib: in CarbonLib 1.0 and later
985
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
987
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
988
function ATSUUnhighlightText( iTextLayout: ATSUTextLayout; iTextBasePointX: ATSUTextMeasurement; iTextBasePointY: ATSUTextMeasurement; iHighlightStart: UniCharArrayOffset; iHighlightLength: UniCharCount ): OSStatus; external name '_ATSUUnhighlightText';
992
* ATSUGetTextHighlight()
995
* Obtains the highlight region for a range of text.
998
* Use this function to obtain the screen region that ATSUI would
999
* normally highlight automatically when ATSUHighlightText is
1000
* called. This is useful if you wish to perform your own
1006
* A layout containing text to be highlighted.
1009
* The x-coordinate of the origin (in either the current graphics
1010
* port or in a Quartz graphics context) of the line containing
1011
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
1012
* draw relative to the current pen location in the current
1016
* The y-coordinate of the origin (in either the current graphics
1017
* port or in a Quartz graphics context) of the line containing
1018
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
1019
* draw relative to the current pen location in the current
1023
* The first character of the text range to be highlighted. If the
1024
* text range spans multiple lines, you should call
1025
* ATSUGetTextHighlight for each line, passing the offset
1026
* corresponding to the beginning of the new line to draw with
1027
* each call. To indicate that the specified text range starts at
1028
* the beginning of the text buffer, you can pass the constant
1029
* kATSUFromTextBeginning. To specify the entire text buffer, pass
1030
* kATSUFromTextBeginning in this parameter and kATSUToTextEnd in
1031
* the iHighlightLength parameter.
1034
* The length of the text range to be highlighted. To indicate
1035
* that the text range extends to the end of the text buffer, pass
1036
* the constant kATSUToTextEnd.
1039
* On return, ATSUGetTextHighlight produces a MacRegion structure
1040
* containing the highlight region for the specified range of
1041
* text. In the case of discontinuous highlighting, the region
1042
* consists of multiple components, with MacRegion.rgnBBox
1043
* specifying the bounding box around the entire area of
1044
* discontinuous highlighting.
1047
* On success, noErr is returned. See MacErrors.h for possible error
1051
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1052
* CarbonLib: in CarbonLib 1.0 and later
1053
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1055
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1056
function ATSUGetTextHighlight( iTextLayout: ATSUTextLayout; iTextBasePointX: ATSUTextMeasurement; iTextBasePointY: ATSUTextMeasurement; iHighlightStart: UniCharArrayOffset; iHighlightLength: UniCharCount; oHighlightRegion: RgnHandle ): OSStatus; external name '_ATSUGetTextHighlight';
1060
* ATSUHighlightInactiveText()
1063
* Highlights text using the standard Mac OS X UI convention for an
1064
* inactive window or UI pane.
1067
* Use this function to redraw text when a window or UI pane
1068
* containing highlighted text becomes inactive. Once the window or
1069
* UI pane becomes active again, call ATSUHighlightText to
1070
* rehighlight the text in active mode.
1075
* A layout containing text to be highlighted.
1078
* The x-coordinate of the origin (in either the current graphics
1079
* port or in a Quartz graphics context) of the line containing
1080
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
1081
* draw relative to the current pen location in the current
1085
* The y-coordinate of the origin (in either the current graphics
1086
* port or in a Quartz graphics context) of the line containing
1087
* the text range. Pass the constant kATSUUseGrafPortPenLoc to
1088
* draw relative to the current pen location in the current
1092
* The first character of the text range to be highlighted. If the
1093
* text range spans multiple lines, you should call
1094
* ATSUHighlightInactiveText for each line, passing the offset
1095
* corresponding to the beginning of the new line to draw with
1096
* each call. To indicate that the specified text range starts at
1097
* the beginning of the text buffer, you can pass the constant
1098
* kATSUFromTextBeginning. To specify the entire text buffer, pass
1099
* kATSUFromTextBeginning in this parameter and kATSUToTextEnd in
1100
* the iHighlightLength parameter.
1103
* The length of the text range to be highlighted. To indicate
1104
* that the text range extends to the end of the text buffer, pass
1105
* the constant kATSUToTextEnd.
1108
* On success, noErr is returned. See MacErrors.h for possible error
1112
* Mac OS X: in version 10.2 and later in ApplicationServices.framework
1113
* CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later
1114
* Non-Carbon CFM: not available
1116
// AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER
1117
function ATSUHighlightInactiveText( iTextLayout: ATSUTextLayout; iTextBasePointX: ATSUTextMeasurement; iTextBasePointY: ATSUTextMeasurement; iHighlightStart: UniCharArrayOffset; iHighlightLength: UniCharCount ): OSStatus; external name '_ATSUHighlightInactiveText';
1120
{ ---------------------------------------------------------------------------- }
1121
{ ATSUI hit-testing }
1122
{ ---------------------------------------------------------------------------- }
1124
* ATSUPositionToOffset()
1127
* Obtains the memory offset for the glyph edge nearest a mouse-down
1131
* The process of hit-testing text obtains the location of a
1132
* mouse-down event relative both to the position of onscreen glyphs
1133
* and to the corresponding offset between character codes in
1134
* memory. You can then use the location information obtained by
1135
* hit-testing to set the insertion point (that is, the caret) or
1136
* selection range (for highlighting). Hit-testing text is
1137
* complicated by the fact that a given line of text may be
1138
* bidirectional. Therefore, the onscreen order of glyphs may not
1139
* readily correspond to the storage order of the corresponding
1140
* character codes. And the concept of which glyph comes "first" in
1141
* a line of text cannot always be limited to the visual terms
1142
* "left" and "right." Because of these complexities, it is more
1143
* accurate to speak in terms of "leading" and "trailing" edges to
1144
* glyphs. A "leading edge" is defined as the edge of a glyph that
1145
* you first encounter when you read the text that includes that
1146
* glyph. For example, when reading Roman text, you first encounter
1147
* the left edge of a Roman glyph. Similarly, the "trailing edge" is
1148
* defined as the edge of the glyph encountered last. This function
1149
* produces the memory offset corresponding to the glyph edge
1150
* nearest the event. If the mouse-down event occurs at a line
1151
* direction boundary or within a glyph cluster,
1152
* ATSUPositionToOffset produces two offsets. You can then provide
1153
* the offset(s) to the ATSUOffsetToPosition function to obtain the
1154
* actual caret position(s) for the event. When you call the
1155
* ATSUPositionToOffset function, ATSUI examines the Unicode
1156
* directionality of the character corresponding to the event
1157
* location. The ATSUPositionToOffset function produces a value of
1158
* true in the oIsLeading parameter if the offset is leading (that
1159
* is, more closely associated with the subsequent character in
1160
* memory and therefore indicative of a left-to-right line
1161
* direction). It produces a value of false if the offset is
1162
* trailing (that is, more closely associated with the preceding
1163
* character in memory and indicative of a right-to-left line
1164
* direction). Finally, note that when the event occurs beyond the
1165
* leftmost or rightmost caret positions of the line (not taking
1166
* into account line rotation), such that no glyph corresponds to
1167
* the location of the hit, the ATSUPositionToOffset function
1168
* produces the primary offset of the closest edge of the line to
1169
* the input location. The oIsLeading flag depends on the
1170
* directionality of the closest glyph and the side of the line to
1171
* which the input location is closest. In this case, the secondary
1172
* offset is equal to the primary offset, since no glyph was hit.
1177
* The layout object in which the mouse-down event occurred.
1180
* The x-coordinate of the event, in local coordinates, relative
1181
* to the origin of the line where the event occurred. That is, to
1182
* specify the x-coordinate value, you should subtract the
1183
* x-coordinate of the line origin from the x-coordinate of the
1184
* hit point (in local coordinates). You can pass the constant
1185
* kATSUUseGrafPortPenLoc for the location of the mouse-down event
1186
* relative to the current pen location in the current graphics
1190
* The y-coordinate of the event, in local coordinates, relative
1191
* to the origin of the line where the event occurred. That is, to
1192
* specify the y-coordinate value, you should subtract the
1193
* y-coordinate of the line origin from the y-coordinate of the
1194
* hit point (in local coordinates). You can pass the constant
1195
* kATSUUseGrafPortPenLoc for the location of the mouse-down event
1196
* relative to the current pen location in the current graphics
1200
* On input, a pointer to a UniCharArrayOffset value specifying
1201
* the offset corresponding to the beginning of the line where the
1202
* event occurred. On return, the value specifies the offset
1203
* corresponding to the glyph edge that is visually closest to the
1204
* event. To determine whether this offset indicates the leading
1205
* or trailing edge of the glyph, you can examine the value
1206
* produced in the oIsLeading parameter.
1209
* On return, the value indicates whether the offset produced in
1210
* the ioPrimaryOffset parameter is leading or trailing. The
1211
* function ATSUPositionToOffset produces a value of true if the
1212
* offset is leading (that is, more closely associated with the
1213
* subsequent character in memory). It produces a value of false
1214
* if the offset is trailing (that is, more closely associated
1215
* with the preceding character in memory).
1218
* On return, the value typically specifies the same offset as
1219
* that produced in the ioPrimaryOffset parameter, unless the
1220
* event occurred within a glyph cluster or at a line direction
1221
* boundary. If so, the value specifies a secondary offset. The
1222
* secondary offset is associated with the glyph that has a
1223
* different direction from the primary line direction.
1226
* On success, noErr is returned. See MacErrors.h for possible error
1230
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1231
* CarbonLib: in CarbonLib 1.0 and later
1232
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1234
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1235
function ATSUPositionToOffset( iTextLayout: ATSUTextLayout; iLocationX: ATSUTextMeasurement; iLocationY: ATSUTextMeasurement; var ioPrimaryOffset: UniCharArrayOffset; var oIsLeading: Boolean; var oSecondaryOffset: UniCharArrayOffset ): OSStatus; external name '_ATSUPositionToOffset';
1239
* ATSUOffsetToPosition()
1242
* Obtains the caret position(s) corresponding to a memory offset.
1245
* This function produces two structures of type ATSUCaret. These
1246
* structures contain the pen positioning information needed to draw
1247
* the caret(s) for the event, specified relative to the origin of
1248
* the line in the current graphics port or graphics context.
1249
* Specifically, the ATSUCaret structures contain x-y coordinates
1250
* for both the caret's starting and ending pen positions (the
1251
* latter taking into account line rotation, caret slanting, and
1252
* split-caret appearances). If the offset you pass to
1253
* ATSUOffsetToPosition is at a line boundary, the structure
1254
* produced in the oMainCaret parameter contains the starting and
1255
* ending pen locations for the high caret, while the oSecondCaret
1256
* parameter contains the corresponding values for the low caret. If
1257
* the offset is not at a line boundary, both parameters contain the
1258
* starting and ending pen locations of the main caret. Because you
1259
* provide the ATSUOffsetToPosition function an offset relative to
1260
* the origin of the line where the hit occurred,
1261
* ATSUOffsetToPosition produces positioning information that is
1262
* also relative. Therefore, you must transform the positions
1263
* produced by the ATSUOffsetToPosition function before drawing the
1264
* caret(s). To transform the caret location(s), add the starting
1265
* and ending caret coordinates to the coordinates of the origin of
1266
* the line in which the hit occurred. For example, if
1267
* ATSUOffsetToPosition produces starting and ending pen locations
1268
* of (25,0), (25,25) in the oMainCaret parameter (and the
1269
* oSecondCaret parameter contains the same coordinates, meaning
1270
* that the caret was not split), you would add these to the
1271
* position of the origin of the line in the graphics port or
1272
* context. If the position of the line origin was at (50,50), then
1273
* the starting and ending pen locations of the caret would be
1279
* The layout containing the offset.
1282
* The offset into the text buffer for which you wish to obtain a
1283
* caret position. To respond to a mouse-down event, pass the
1284
* offset returned in the ioPrimaryOffset parameter from the
1285
* function ATSUPositionToOffset. That is, the offset
1286
* corresponding to the glyph edge closest to the event.
1289
* A Boolean value indicating whether the offset corresponds to
1290
* the leading or trailing edge of the glyph. You can obtain this
1291
* information from the function ATSUPositionToOffset. This value
1292
* is relevant if the offset occurs at a line direction boundary
1293
* or within a glyph cluster.
1296
* On return, contains the starting and ending pen locations of
1297
* the high caret if the value produced in oCaretIsSplit is true.
1298
* If the value is false, the structure contains the starting and
1299
* ending pen locations of the main caret.
1302
* On return, contains the starting and ending pen locations of
1303
* the low caret if the value passed back in the oCaretIsSplit
1304
* parameter is true. If the value is false, the structure
1305
* contains the starting and ending pen locations of the main
1306
* caret (that is, the same values as the oMainCaret parameter).
1309
* On return, indicates whether the offset specified in the
1310
* iOffset parameter occurs at a line direction boundary. If true,
1311
* the offset occurs at a line direction boundary; otherwise,
1315
* On success, noErr is returned. See MacErrors.h for possible error
1319
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1320
* CarbonLib: in CarbonLib 1.0 and later
1321
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1323
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1324
function ATSUOffsetToPosition( iTextLayout: ATSUTextLayout; iOffset: UniCharArrayOffset; iIsLeading: Boolean; var oMainCaret: ATSUCaret; var oSecondCaret: ATSUCaret; var oCaretIsSplit: Boolean ): OSStatus; external name '_ATSUOffsetToPosition';
1328
* ATSUPositionToCursorOffset()
1331
* Obtains the memory offset for the glyph edge nearest a mouse-down
1332
* event, after a move of the specified length.
1335
* This function produces the memory offset for the glyph edge
1336
* nearest a mouse-down event, after a move of the specified length.
1337
* This offset corresponds to where an insertion point would be
1338
* placed after the move.
1343
* The layout in which the mouse down event occured.
1346
* The x-coordinate of the event, in local coordinates, relative
1347
* to the origin of the line where the event occurred. That is, to
1348
* specify the x-coordinate value, you should subtract the
1349
* x-coordinate of the line origin from the x-coordinate of the
1350
* hit point (in local coordinates). You can pass the constant
1351
* kATSUUseGrafPortPenLoc for the location of the mouse-down event
1352
* relative to the current pen location in the current graphics
1356
* The y-coordinate of the event, in local coordinates, relative
1357
* to the origin of the line where the event occurred. That is, to
1358
* specify the y-coordinate value, you should subtract the
1359
* y-coordinate of the line origin from the y-coordinate of the
1360
* hit point (in local coordinates). You can pass the constant
1361
* kATSUUseGrafPortPenLoc for the location of the mouse-down event
1362
* relative to the current pen location in the current graphics
1366
* A constant specifying the type of cursor movement to use. See
1367
* the definition of ATSUCursorMovementType for possible values to
1368
* pass for this parameter.
1371
* On input, the offset corresponding to the beginning of the line
1372
* where the event occurred. On return, the offset corresponding
1373
* to the glyph edge nearest the event, after a movement of the
1374
* specified type. This offset corresponds to where the insertion
1375
* point would be placed after the move. To determine whether this
1376
* offset indicates the leading or trailing edge of the glyph, you
1377
* can examine the value produced in the oIsLeading parameter.
1380
* On return, the value indicates whether the offset produced in
1381
* the ioPrimaryOffset parameter is leading or trailing. The
1382
* ATSUPositionToOffset function produces a value of true if the
1383
* offset is leading (that is, more closely associated with the
1384
* subsequent character in memory). It produces a value of false
1385
* if the offset is trailing (that is, more closely associated
1386
* with the preceding character in memory).
1389
* On return, the value typically specifies the same offset as
1390
* that produced in the ioPrimaryOffset parameter, unless the
1391
* event occurred within a glyph cluster or at a line direction
1392
* boundary. If so, the value specifies the secondary offset, for
1393
* the glyph edge furthest from the event.
1396
* On success, noErr is returned. See MacErrors.h for possible error
1400
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1401
* CarbonLib: in CarbonLib 1.5 and later
1402
* Non-Carbon CFM: in ATSUnicodeLib 9.2.2 and later
1404
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1405
function ATSUPositionToCursorOffset( iTextLayout: ATSUTextLayout; iLocationX: ATSUTextMeasurement; iLocationY: ATSUTextMeasurement; iMovementType: ATSUCursorMovementType; var ioPrimaryOffset: UniCharArrayOffset; var oIsLeading: Boolean; var oSecondaryOffset: UniCharArrayOffset ): OSStatus; external name '_ATSUPositionToCursorOffset';
1409
* ATSUOffsetToCursorPosition()
1412
* Obtains the caret position(s) corresponding to a memory offset,
1413
* after a move of the specified length.
1416
* Use this function in conjunction with ATSUPositionToCursorOffset
1417
* to determine where to draw the caret after a mouse-down event.
1418
* The movement type parameter allows you to have the cursor "snap"
1419
* to different parts of the text depending on the type of movement
1420
* selected (i.e., words or characters). See the definition of
1421
* ATSUCursorMovementType for more information on possible values.
1426
* The text layout object in which the mouse-down event occurred.
1429
* The offset corresponding to the glyph edge nearest the event,
1430
* after a movement of the specified type. You can obtain this
1431
* value by examining the offset produced in the ioPrimaryOffset
1432
* parameter of the function ATSUPositionToCursorOffset.
1435
* A Boolean value indicating whether the specified offset
1436
* corresponds to the leading or trailing edge of the glyph. You
1437
* can obtain this information from the function
1438
* ATSUPositionToCursorOffset . This value is relevant if the
1439
* offset occurs at a line direction boundary or within a glyph
1443
* A constant specifying the unit of cursor movement. See the
1444
* definition of ATSUCursorMovementType for possible values to
1445
* pass for this parameter.
1448
* On return, the structure contains the starting and ending pen
1449
* locations of the high caret if the value produced in the
1450
* oCaretIsSplit parameter is true. If the value is false, the
1451
* structure contains the starting and ending pen locations of the
1455
* On return, the structure contains the starting and ending pen
1456
* locations of the low caret if the value passed back in the
1457
* oCaretIsSplit parameter is true. If the value is false, the
1458
* structure contains the starting and ending pen locations of the
1459
* main caret (that is, the same values as the oMainCaret
1463
* On return, the value indicates whether the offset specified in
1464
* the iOffset parameter occurs at a line direction boundary. If
1465
* true, the offset occurs at a line direction boundary;
1469
* On success, noErr is returned. See MacErrors.h for possible error
1473
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1474
* CarbonLib: in CarbonLib 1.5 and later
1475
* Non-Carbon CFM: in ATSUnicodeLib 9.2.2 and later
1477
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1478
function ATSUOffsetToCursorPosition( iTextLayout: ATSUTextLayout; iOffset: UniCharArrayOffset; iIsLeading: Boolean; iMovementType: ATSUCursorMovementType; var oMainCaret: ATSUCaret; var oSecondCaret: ATSUCaret; var oCaretIsSplit: Boolean ): OSStatus; external name '_ATSUOffsetToCursorPosition';
1481
{ ---------------------------------------------------------------------------- }
1482
{ ATSUI cursor movement }
1483
{ ---------------------------------------------------------------------------- }
1485
* ATSUNextCursorPosition()
1488
* Obtains the memory offset for the insertion point that follows
1489
* the current insertion point in storage order, as determined by a
1490
* move of the specified length and type.
1493
* Together with ATSUPreviousCursorPosition, this function allows an
1494
* application to "walk" the text buffer in storage order, moving
1495
* the cursor by a specified amount and movement type at each step.
1496
* To move through the text buffer in screen order, use the
1497
* functions ATSURightwardCursorPosition and
1498
* ATSULeftwardCursorPosition.
1503
* The layout in which to perform the cursor movement.
1506
* The previous cursor position.
1509
* A constant specifying the unit of cursor movement. See the
1510
* definition of ATSUCursorMovementType for possible values to
1511
* pass for this parameter.
1514
* On return, the new cursor position.
1517
* On success, noErr is returned. See MacErrors.h for possible error
1521
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1522
* CarbonLib: in CarbonLib 1.0 and later
1523
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1525
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1526
function ATSUNextCursorPosition( iTextLayout: ATSUTextLayout; iOldOffset: UniCharArrayOffset; iMovementType: ATSUCursorMovementType; var oNewOffset: UniCharArrayOffset ): OSStatus; external name '_ATSUNextCursorPosition';
1530
* ATSUPreviousCursorPosition()
1533
* Obtains the memory offset for the insertion point that preceeds
1534
* the current insertion point in storage order, as determined by a
1535
* move of the specified length and type.
1538
* Together with ATSUNextCursorPosition, this function allows an
1539
* application to "walk" the text buffer in storage order, moving
1540
* the cursor by a specified amount and movement type at each step.
1541
* To move through the text buffer in screen order, use the
1542
* functions ATSURightwardCursorPosition and
1543
* ATSULeftwardCursorPosition.
1548
* The layout in which to perform the cursor movement.
1551
* The previous cursor position.
1554
* A constant specifying the unit of cursor movement. See the
1555
* definition of ATSUCursorMovementType for possible values to
1556
* pass for this parameter.
1559
* On return, the new cursor position.
1562
* On success, noErr is returned. See MacErrors.h for possible error
1566
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1567
* CarbonLib: in CarbonLib 1.0 and later
1568
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1570
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1571
function ATSUPreviousCursorPosition( iTextLayout: ATSUTextLayout; iOldOffset: UniCharArrayOffset; iMovementType: ATSUCursorMovementType; var oNewOffset: UniCharArrayOffset ): OSStatus; external name '_ATSUPreviousCursorPosition';
1575
* ATSURightwardCursorPosition()
1578
* Obtains the memory offset for the insertion point that is to the
1579
* right of the current insertion point, as determined by a move of
1580
* the specified length and type.
1583
* Together with ATSULeftwardCursorPosition, this function allows an
1584
* application to "walk" the text buffer in screen order, moving the
1585
* cursor by a specified amount and movement type at each step. To
1586
* move through the text buffer in storage order, use the functions
1587
* ATSUNextCursorPosition and ATSUPreviousCursorPosition. Note that
1588
* if you are drawing the cursor after a cursor move, you should use
1589
* ATSUOffsetToPosition to obtain an ATSUCaret that determines the
1590
* on screen location of the new cursor position. Always store the
1591
* ATSUCaret from the previous cursor position as well, as this can
1592
* help determine which caret to use in the case of a split caret.
1593
* When performing leftward and rightward cursor movement, always
1594
* use the caret closest to the previous caret. This maintains
1595
* visual order when moving the cursor on screen.
1600
* The layout in which to perform the cursor movement.
1603
* The previous cursor position.
1606
* A constant specifying the unit of cursor movement. See the
1607
* definition of ATSUCursorMovementType for possible values to
1608
* pass for this parameter.
1611
* On return, the new cursor position.
1614
* On success, noErr is returned. See MacErrors.h for possible error
1618
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1619
* CarbonLib: in CarbonLib 1.0 and later
1620
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1622
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1623
function ATSURightwardCursorPosition( iTextLayout: ATSUTextLayout; iOldOffset: UniCharArrayOffset; iMovementType: ATSUCursorMovementType; var oNewOffset: UniCharArrayOffset ): OSStatus; external name '_ATSURightwardCursorPosition';
1627
* ATSULeftwardCursorPosition()
1630
* Obtains the memory offset for the insertion point that is to the
1631
* left of the current insertion point, as determined by a move of
1632
* the specified length and type.
1635
* Together with ATSURightwardCursorPosition, this function allows
1636
* an application to "walk" the text buffer in screen order, moving
1637
* the cursor by a specified amount and movement type at each step.
1638
* To move through the text buffer in storage order, use the
1639
* functions ATSUNextCursorPosition and ATSUPreviousCursorPosition.
1640
* Note that if you are drawing the cursor after a cursor move, you
1641
* should use ATSUOffsetToPosition to obtain an ATSUCaret that
1642
* determines the on screen location of the new cursor position.
1643
* Always store the ATSUCaret from the previous cursor position as
1644
* well, as this can help determine which caret to use in the case
1645
* of a split caret. When performing leftward and rightward cursor
1646
* movement, always use the caret closest to the previous caret.
1647
* This maintains visual order when moving the cursor on screen.
1652
* The layout in which to perform the cursor movement.
1655
* The previous cursor position.
1658
* A constant specifying the unit of cursor movement. See the
1659
* definition of ATSUCursorMovementType for possible values to
1660
* pass for this parameter.
1663
* On return, the new cursor position.
1666
* On success, noErr is returned. See MacErrors.h for possible error
1670
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1671
* CarbonLib: in CarbonLib 1.0 and later
1672
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1674
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1675
function ATSULeftwardCursorPosition( iTextLayout: ATSUTextLayout; iOldOffset: UniCharArrayOffset; iMovementType: ATSUCursorMovementType; var oNewOffset: UniCharArrayOffset ): OSStatus; external name '_ATSULeftwardCursorPosition';
1678
{ Functions listed beyond this point are either deprecated or not recommended }
1684
* This function is no longer recommended. Please use
1685
* ATSUGetUnjustifiedBounds instead.
1688
* Mac OS X: in version 10.0 and later in ApplicationServices.framework
1689
* CarbonLib: in CarbonLib 1.0 and later
1690
* Non-Carbon CFM: in ATSUnicodeLib 8.5 and later
1692
// AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER
1693
function ATSUMeasureText( iTextLayout: ATSUTextLayout; iLineStart: UniCharArrayOffset; iLineLength: UniCharCount; var oTextBefore: ATSUTextMeasurement; var oTextAfter: ATSUTextMeasurement; var oAscent: ATSUTextMeasurement; var oDescent: ATSUTextMeasurement ): OSStatus; external name '_ATSUMeasureText';
added
removed
fpcsrc/packages/univint/src/ATSUnicodeDrawing.pas
