/packages/univint/src/CTFrame.pas

  1{
  2 *	CTFrame.h
  3 *	CoreText
  4 *
  5 *	Copyright (c) 2003-2012 Apple Inc. All rights reserved.
  6 *
  7 }
  8{  Initial Pascal Translation:  Jonas Maebe, <jonas@freepascal.org>, October 2009 }
  9{  Pascal Translation Updated:  Jonas Maebe, <jonas@freepascal.org>, October 2012 }
 10{
 11    Modified for use with Free Pascal
 12    Version 308
 13    Please report any bugs to <gpc@microbizz.nl>
 14}
 15
 16{$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
 17{$mode macpas}
 18{$packenum 1}
 19{$macro on}
 20{$inline on}
 21{$calling mwpascal}
 22
 23unit CTFrame;
 24interface
 25{$setc UNIVERSAL_INTERFACES_VERSION := $0400}
 26{$setc GAP_INTERFACES_VERSION := $0308}
 27
 28{$ifc not defined USE_CFSTR_CONSTANT_MACROS}
 29    {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
 30{$endc}
 31
 32{$ifc defined CPUPOWERPC and defined CPUI386}
 33	{$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
 34{$endc}
 35{$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
 36	{$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
 37{$endc}
 38
 39{$ifc not defined __ppc__ and defined CPUPOWERPC32}
 40	{$setc __ppc__ := 1}
 41{$elsec}
 42	{$setc __ppc__ := 0}
 43{$endc}
 44{$ifc not defined __ppc64__ and defined CPUPOWERPC64}
 45	{$setc __ppc64__ := 1}
 46{$elsec}
 47	{$setc __ppc64__ := 0}
 48{$endc}
 49{$ifc not defined __i386__ and defined CPUI386}
 50	{$setc __i386__ := 1}
 51{$elsec}
 52	{$setc __i386__ := 0}
 53{$endc}
 54{$ifc not defined __x86_64__ and defined CPUX86_64}
 55	{$setc __x86_64__ := 1}
 56{$elsec}
 57	{$setc __x86_64__ := 0}
 58{$endc}
 59{$ifc not defined __arm__ and defined CPUARM}
 60	{$setc __arm__ := 1}
 61{$elsec}
 62	{$setc __arm__ := 0}
 63{$endc}
 64
 65{$ifc defined cpu64}
 66  {$setc __LP64__ := 1}
 67{$elsec}
 68  {$setc __LP64__ := 0}
 69{$endc}
 70
 71
 72{$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
 73	{$error Conflicting definitions for __ppc__ and __i386__}
 74{$endc}
 75
 76{$ifc defined __ppc__ and __ppc__}
 77	{$setc TARGET_CPU_PPC := TRUE}
 78	{$setc TARGET_CPU_PPC64 := FALSE}
 79	{$setc TARGET_CPU_X86 := FALSE}
 80	{$setc TARGET_CPU_X86_64 := FALSE}
 81	{$setc TARGET_CPU_ARM := FALSE}
 82	{$setc TARGET_OS_MAC := TRUE}
 83	{$setc TARGET_OS_IPHONE := FALSE}
 84	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
 85	{$setc TARGET_OS_EMBEDDED := FALSE}
 86{$elifc defined __ppc64__ and __ppc64__}
 87	{$setc TARGET_CPU_PPC := FALSE}
 88	{$setc TARGET_CPU_PPC64 := TRUE}
 89	{$setc TARGET_CPU_X86 := FALSE}
 90	{$setc TARGET_CPU_X86_64 := FALSE}
 91	{$setc TARGET_CPU_ARM := FALSE}
 92	{$setc TARGET_OS_MAC := TRUE}
 93	{$setc TARGET_OS_IPHONE := FALSE}
 94	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
 95	{$setc TARGET_OS_EMBEDDED := FALSE}
 96{$elifc defined __i386__ and __i386__}
 97	{$setc TARGET_CPU_PPC := FALSE}
 98	{$setc TARGET_CPU_PPC64 := FALSE}
 99	{$setc TARGET_CPU_X86 := TRUE}
100	{$setc TARGET_CPU_X86_64 := FALSE}
101	{$setc TARGET_CPU_ARM := FALSE}
102{$ifc defined(iphonesim)}
103 	{$setc TARGET_OS_MAC := FALSE}
104	{$setc TARGET_OS_IPHONE := TRUE}
105	{$setc TARGET_IPHONE_SIMULATOR := TRUE}
106{$elsec}
107	{$setc TARGET_OS_MAC := TRUE}
108	{$setc TARGET_OS_IPHONE := FALSE}
109	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
110{$endc}
111	{$setc TARGET_OS_EMBEDDED := FALSE}
112{$elifc defined __x86_64__ and __x86_64__}
113	{$setc TARGET_CPU_PPC := FALSE}
114	{$setc TARGET_CPU_PPC64 := FALSE}
115	{$setc TARGET_CPU_X86 := FALSE}
116	{$setc TARGET_CPU_X86_64 := TRUE}
117	{$setc TARGET_CPU_ARM := FALSE}
118	{$setc TARGET_OS_MAC := TRUE}
119	{$setc TARGET_OS_IPHONE := FALSE}
120	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
121	{$setc TARGET_OS_EMBEDDED := FALSE}
122{$elifc defined __arm__ and __arm__}
123	{$setc TARGET_CPU_PPC := FALSE}
124	{$setc TARGET_CPU_PPC64 := FALSE}
125	{$setc TARGET_CPU_X86 := FALSE}
126	{$setc TARGET_CPU_X86_64 := FALSE}
127	{$setc TARGET_CPU_ARM := TRUE}
128	{ will require compiler define when/if other Apple devices with ARM cpus ship }
129	{$setc TARGET_OS_MAC := FALSE}
130	{$setc TARGET_OS_IPHONE := TRUE}
131	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
132	{$setc TARGET_OS_EMBEDDED := TRUE}
133{$elsec}
134	{$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ is defined.}
135{$endc}
136
137{$ifc defined __LP64__ and __LP64__ }
138  {$setc TARGET_CPU_64 := TRUE}
139{$elsec}
140  {$setc TARGET_CPU_64 := FALSE}
141{$endc}
142
143{$ifc defined FPC_BIG_ENDIAN}
144	{$setc TARGET_RT_BIG_ENDIAN := TRUE}
145	{$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
146{$elifc defined FPC_LITTLE_ENDIAN}
147	{$setc TARGET_RT_BIG_ENDIAN := FALSE}
148	{$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
149{$elsec}
150	{$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
151{$endc}
152{$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
153{$setc CALL_NOT_IN_CARBON := FALSE}
154{$setc OLDROUTINENAMES := FALSE}
155{$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
156{$setc OPAQUE_UPP_TYPES := TRUE}
157{$setc OTCARBONAPPLICATION := TRUE}
158{$setc OTKERNEL := FALSE}
159{$setc PM_USE_SESSION_APIS := TRUE}
160{$setc TARGET_API_MAC_CARBON := TRUE}
161{$setc TARGET_API_MAC_OS8 := FALSE}
162{$setc TARGET_API_MAC_OSX := TRUE}
163{$setc TARGET_CARBON := TRUE}
164{$setc TARGET_CPU_68K := FALSE}
165{$setc TARGET_CPU_MIPS := FALSE}
166{$setc TARGET_CPU_SPARC := FALSE}
167{$setc TARGET_OS_UNIX := FALSE}
168{$setc TARGET_OS_WIN32 := FALSE}
169{$setc TARGET_RT_MAC_68881 := FALSE}
170{$setc TARGET_RT_MAC_CFM := FALSE}
171{$setc TARGET_RT_MAC_MACHO := TRUE}
172{$setc TYPED_FUNCTION_POINTERS := TRUE}
173{$setc TYPE_BOOL := FALSE}
174{$setc TYPE_EXTENDED := FALSE}
175{$setc TYPE_LONGLONG := TRUE}
176uses MacTypes,CFArray,CFDictionary,CFBase,CFNumber,CFString,CGContext,CGGeometry,CGPath;
177{$endc} {not MACOSALLINCLUDE}
178
179
180{$ALIGN POWER}
181
182 
183{!
184    @header
185
186    Thread Safety Information
187
188    All functions in this header are thread safe unless otherwise specified.
189}
190
191
192{ --------------------------------------------------------------------------- }
193{ Frame Types }
194{ --------------------------------------------------------------------------- }
195
196type
197	CTFrameRef = ^__CTFrame; { an opaque type }
198	__CTFrame = record end;
199
200
201{!
202	@function	CTFrameGetTypeID
203	@abstract	Returns the CFType of the frame object
204}
205
206function CTFrameGetTypeID: CFTypeID; external name '_CTFrameGetTypeID';
207(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
208
209
210{ --------------------------------------------------------------------------- }
211{ Frame Values }
212{ --------------------------------------------------------------------------- }
213
214{!
215	@enum		CTFrameProgression
216	@abstract	These constants specify frame progression types.
217	
218	@discussion The lines of text within a frame may be stacked for either
219				horizontal or vertical text. Values are enumerated for each
220				stacking type supported by CTFrame. Frames created with a
221				progression type specifying vertical text will rotate lines
222				90 degrees counterclockwise when drawing.
223	
224	@constant	kCTFrameProgressionTopToBottom
225				Lines are stacked top to bottom for horizontal text.
226	
227	@constant	kCTFrameProgressionRightToLeft
228				Lines are stacked right to left for vertical text.
229}
230
231const
232	kCTFrameProgressionTopToBottom = 0;
233	kCTFrameProgressionRightToLeft = 1;
234type
235	CTFrameProgression = UInt32;
236
237
238{!
239	@const		kCTFrameProgressionAttributeName
240	@abstract	Specifies progression for a frame.
241	
242	@discussion Value must be a CFNumberRef containing a CTFrameProgression.
243				Default is kCTFrameProgressionTopToBottom. This value determines
244				the line stacking behavior for a frame and does not affect the
245				appearance of the glyphs within that frame.
246
247	@seealso	CTFramesetterCreateFrame
248}
249
250var kCTFrameProgressionAttributeName: CFStringRef; external name '_kCTFrameProgressionAttributeName'; (* attribute const *)
251(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
252
253{!
254	@enum		CTFramePathFillRule
255	@abstract	These constants specify fill rule used by the frame.
256 
257	@discussion When a path intersects with itself, the client should specify which rule to use for deciding the 
258				area of the path.
259 
260	@constant	kCTFramePathFillEvenOdd
261				Text is filled in the area that would be painted if the path were given to CGContextEOFillPath.
262
263	@constant	kCTFramePathFillWindingNumber
264				Text is fill in the area that would be painted if the path were given to CGContextFillPath.
265 
266 
267 }
268
269const
270	kCTFramePathFillEvenOdd = 0;
271	kCTFramePathFillWindingNumber = 1;
272type
273	CTFramePathFillRule = UInt32;
274
275
276{!
277	@const		kCTFramePathFillRuleAttributeName
278	@abstract	Specifies fill rule for a frame if this attribute is used at top level of frameAttributes dictionary, or specify
279				fill rule for a clipping path if used in a dictionary contained in an array specified by kCTFrameClippingPathsAttributeName.
280				
281	@discussion Value must be a CFNumberRef containing kCTFramePathFillEvenOdd or kCTFramePathFillWindingNumber.
282				Default is kCTFramePathFillEvenOdd.
283
284	@seealso	CTFramesetterCreateFrame
285 }
286
287var kCTFramePathFillRuleAttributeName: CFStringRef; external name '_kCTFramePathFillRuleAttributeName'; (* attribute const *)
288(* CT_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_4_2) *)
289
290{!
291	@const		kCTFramePathWidthAttributeName
292	@abstract	Specifies frame width if this attribute is used at top level of frameAttributes dictionary, or specify
293				clipping path width if used in a dictionary contained in an array specified by kCTFrameClippingPathsAttributeName.
294
295	@discussion Value must be a CFNumberRef specifying frame width.
296				Default is zero.
297
298	@seealso	CTFramesetterCreateFrame
299 }
300
301var kCTFramePathWidthAttributeName: CFStringRef; external name '_kCTFramePathWidthAttributeName'; (* attribute const *)
302(* CT_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_4_2) *)
303
304	
305{!
306	@const		kCTFrameClippingPathsAttributeName
307	@abstract	Specifies array of paths to clip frame.
308	
309	@discussion Value must be a CFArrayRef containing CFDictionaryRefs or CGPathRef.  (CGPathRef is allowed on 10.8 or later.)
310				Each dictionary should have a kCTFramePathClippingPathAttributeName key-value pair, and can have a kCTFramePathFillRuleAttributeName key-value pair 
311				and kCTFramePathFillRuleAttributeName key-value pair as optional parameters.  In case of CGPathRef, default fill rule (kCTFramePathFillEvenOdd) and width (0.0) are used.
312
313	@seealso	CTFramesetterCreateFrame
314}
315
316var kCTFrameClippingPathsAttributeName: CFStringRef; external name '_kCTFrameClippingPathsAttributeName'; (* attribute const *)
317(* CT_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_4_3) *)
318
319{!
320	@const		kCTFramePathClippingPathAttributeName
321	@abstract	Specifies clipping path.  This attribute is valid in a dictionary contained in an array specified by kCTFrameClippingPathsAttributeName.
322				On 10.8 or later, This attribute is also valid in frameAttributes dictionary passed to CTFramesetterCreateFrame.
323
324	@discussion Value must be a CGPathRef specifying a clipping pat.
325
326	@seealso	kCTFrameClippingPathsAttributeName
327 }
328
329var kCTFramePathClippingPathAttributeName: CFStringRef; external name '_kCTFramePathClippingPathAttributeName'; (* attribute const *)
330(* CT_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_4_3) *)
331
332{ --------------------------------------------------------------------------- }
333{ Frame Accessors }
334{ --------------------------------------------------------------------------- }
335
336{!
337	@function	CTFrameGetStringRange
338	@abstract	Returns the range of characters that were originally requested
339				to fill the frame.
340
341	@param		frame
342				The frame that you want to get the character range from.
343
344	@result		This function will return a CFRange containing the backing
345				store range of characters that were originally requested
346				to fill the frame. If the function call is not successful,
347				then an empty range will be returned.
348}
349
350function CTFrameGetStringRange( frame: CTFrameRef ): CFRange; external name '_CTFrameGetStringRange';
351(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
352
353
354{!
355	@function	CTFrameGetVisibleStringRange
356	@abstract	Returns the range of characters that actually fit in the
357				frame.
358
359	@discussion This can be used to cascade frames, as it returns the range of
360				characters that can be seen in the frame. The next frame would
361				start where this frame ends.
362
363	@param		frame
364				The frame that you want to get the visible character range
365				from.
366
367	@result		This function will return a CFRange containing the backing
368				store range of characters that fit into the frame. If the
369				function call is not successful, or if no characters fit
370				in the frame, then an empty range will be returned.
371}
372
373function CTFrameGetVisibleStringRange( frame: CTFrameRef ): CFRange; external name '_CTFrameGetVisibleStringRange';
374(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
375
376
377{!
378	@function	CTFrameGetPath
379	@abstract	Returns the path used to create the frame.
380
381	@param		frame
382				The frame that you want to obtain the path from.
383}
384
385function CTFrameGetPath( frame: CTFrameRef ): CGPathRef; external name '_CTFrameGetPath';
386(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
387
388
389{!
390	@function	CTFrameGetFrameAttributes
391	@abstract	Returns the frame attributes used to create the frame.
392
393	@discussion It is possible to create a frame with an attributes dictionary
394				in order to control various aspects of the framing process.
395				These attributes are different from the ones that are used to
396				create an attributed string.
397
398	@param		frame
399				The frame that you want to obtain the frame attributes from.
400
401	@result		This function will return a CFDictionary containing the
402				frame attributes that were used to create the frame. If the
403				frame was created without any frame attributes, this function
404				will return NULL.
405}
406
407function CTFrameGetFrameAttributes( frame: CTFrameRef ): CFDictionaryRef; external name '_CTFrameGetFrameAttributes';
408(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
409
410
411{!
412	@function	CTFrameGetLines
413	@abstract	Returns an array of lines that make up the frame.
414
415	@discussion This function will return an array of CTLine objects that are
416				stored in the frame. These line objects can be accessed and
417				manipulated in any way that normal line objects can be. It is
418				possible that an empty frame exists. That is, a frame in which
419				no lines exist. In this case, the returned array will have 0
420				entries.
421
422	@param		frame
423				The frame that you want to obtain the line array from.
424
425	@result		This function will return a CFArray object containing the
426				CTLine objects that make up the frame.
427}
428
429function CTFrameGetLines( frame: CTFrameRef ): CFArrayRef; external name '_CTFrameGetLines';
430(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
431
432
433{!
434	@function	CTFrameGetLineOrigins
435	@abstract	Copies a range of line origins for a frame.
436
437	@discussion	This function will copy a range of CGPoint structures. Each
438				CGPoint is the origin of the corresponding line in the array of
439				lines returned by CTFrameGetLines, relative to the origin of the
440				frame's path. The maximum number of line origins returned by
441				this function is the count of the array of lines.
442
443	@param		frame
444				The frame that you want to obtain the line origin array from.
445
446	@param		range
447				The range of line origins you wish to copy. If the length of the
448				range is set to 0, then the copy operation will continue from
449				the range's start index to the last line origin.
450
451	@param		origins
452				The buffer to which the origins will be copied. The buffer must
453				have at least as many elements as specified by range's length.
454				When using the origins to calculate measurements for a frame's
455				contents, remember that line origins do not always correspond to
456				line metrics; paragraph style settings can affect line origins,
457				for one. The overall typographic bounds of a frame may generally
458				be calculated as the difference between the top of the frame and
459				the descent of the last line. This will obviously exclude any
460				spacing following the last line, but such spacing has no effect
461				on framesetting in the first place.
462}
463
464procedure CTFrameGetLineOrigins( frame: CTFrameRef; range: CFRange; origins: {variable-size-array} CGPointPtr ); external name '_CTFrameGetLineOrigins';
465(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
466
467
468{!
469	@function	CTFrameDraw
470	@abstract	Draws an entire frame to a context.
471
472	@discussion This function will draw an entire frame to the context. Note
473				that this call may leave the context in any state and does not
474				flush it after the draw operation.
475
476	@param		frame
477				The frame that you want to draw.
478
479	@param		context
480				The context to draw the frame to.
481
482	@result		If both the frame and the context are valid, the frame will be
483				drawn in the context.
484}
485
486procedure CTFrameDraw( frame: CTFrameRef; context: CGContextRef ); external name '_CTFrameDraw';
487(* CT_AVAILABLE_STARTING( __MAC_10_5, __IPHONE_3_2) *)
488
489{$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
490
491end.
492{$endc} {not MACOSALLINCLUDE}