/packages/univint/src/CFAttributedString.pas

  1{	CFAttributedString.h
  2	Copyright (c) 2004-2012, Apple Inc. All rights reserved.
  3}
  4{       Pascal Translation:  Peter N Lewis, <peter@stairways.com.au>, August 2005 }
  5{       Pascal Translation Updated:  Gorazd Krosl, <gorazd_1957@yahoo.ca>, October 2009 }
  6{       Pascal Translation Updated:  Jonas Maebe, <jonas@freepascal.org>, October 2009 }
  7{       Pascal Translation Updated: Jonas Maebe <jonas@freepascal.org>, September 2012 }
  8{
  9    Modified for use with Free Pascal
 10    Version 308
 11    Please report any bugs to <gpc@microbizz.nl>
 12}
 13
 14{$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
 15{$mode macpas}
 16{$packenum 1}
 17{$macro on}
 18{$inline on}
 19{$calling mwpascal}
 20
 21unit CFAttributedString;
 22interface
 23{$setc UNIVERSAL_INTERFACES_VERSION := $0400}
 24{$setc GAP_INTERFACES_VERSION := $0308}
 25
 26{$ifc not defined USE_CFSTR_CONSTANT_MACROS}
 27    {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
 28{$endc}
 29
 30{$ifc defined CPUPOWERPC and defined CPUI386}
 31	{$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
 32{$endc}
 33{$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
 34	{$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
 35{$endc}
 36
 37{$ifc not defined __ppc__ and defined CPUPOWERPC32}
 38	{$setc __ppc__ := 1}
 39{$elsec}
 40	{$setc __ppc__ := 0}
 41{$endc}
 42{$ifc not defined __ppc64__ and defined CPUPOWERPC64}
 43	{$setc __ppc64__ := 1}
 44{$elsec}
 45	{$setc __ppc64__ := 0}
 46{$endc}
 47{$ifc not defined __i386__ and defined CPUI386}
 48	{$setc __i386__ := 1}
 49{$elsec}
 50	{$setc __i386__ := 0}
 51{$endc}
 52{$ifc not defined __x86_64__ and defined CPUX86_64}
 53	{$setc __x86_64__ := 1}
 54{$elsec}
 55	{$setc __x86_64__ := 0}
 56{$endc}
 57{$ifc not defined __arm__ and defined CPUARM}
 58	{$setc __arm__ := 1}
 59{$elsec}
 60	{$setc __arm__ := 0}
 61{$endc}
 62
 63{$ifc defined cpu64}
 64  {$setc __LP64__ := 1}
 65{$elsec}
 66  {$setc __LP64__ := 0}
 67{$endc}
 68
 69
 70{$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
 71	{$error Conflicting definitions for __ppc__ and __i386__}
 72{$endc}
 73
 74{$ifc defined __ppc__ and __ppc__}
 75	{$setc TARGET_CPU_PPC := TRUE}
 76	{$setc TARGET_CPU_PPC64 := FALSE}
 77	{$setc TARGET_CPU_X86 := FALSE}
 78	{$setc TARGET_CPU_X86_64 := FALSE}
 79	{$setc TARGET_CPU_ARM := FALSE}
 80	{$setc TARGET_OS_MAC := TRUE}
 81	{$setc TARGET_OS_IPHONE := FALSE}
 82	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
 83	{$setc TARGET_OS_EMBEDDED := FALSE}
 84{$elifc defined __ppc64__ and __ppc64__}
 85	{$setc TARGET_CPU_PPC := FALSE}
 86	{$setc TARGET_CPU_PPC64 := TRUE}
 87	{$setc TARGET_CPU_X86 := FALSE}
 88	{$setc TARGET_CPU_X86_64 := FALSE}
 89	{$setc TARGET_CPU_ARM := FALSE}
 90	{$setc TARGET_OS_MAC := TRUE}
 91	{$setc TARGET_OS_IPHONE := FALSE}
 92	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
 93	{$setc TARGET_OS_EMBEDDED := FALSE}
 94{$elifc defined __i386__ and __i386__}
 95	{$setc TARGET_CPU_PPC := FALSE}
 96	{$setc TARGET_CPU_PPC64 := FALSE}
 97	{$setc TARGET_CPU_X86 := TRUE}
 98	{$setc TARGET_CPU_X86_64 := FALSE}
 99	{$setc TARGET_CPU_ARM := FALSE}
100{$ifc defined(iphonesim)}
101 	{$setc TARGET_OS_MAC := FALSE}
102	{$setc TARGET_OS_IPHONE := TRUE}
103	{$setc TARGET_IPHONE_SIMULATOR := TRUE}
104{$elsec}
105	{$setc TARGET_OS_MAC := TRUE}
106	{$setc TARGET_OS_IPHONE := FALSE}
107	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
108{$endc}
109	{$setc TARGET_OS_EMBEDDED := FALSE}
110{$elifc defined __x86_64__ and __x86_64__}
111	{$setc TARGET_CPU_PPC := FALSE}
112	{$setc TARGET_CPU_PPC64 := FALSE}
113	{$setc TARGET_CPU_X86 := FALSE}
114	{$setc TARGET_CPU_X86_64 := TRUE}
115	{$setc TARGET_CPU_ARM := FALSE}
116	{$setc TARGET_OS_MAC := TRUE}
117	{$setc TARGET_OS_IPHONE := FALSE}
118	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
119	{$setc TARGET_OS_EMBEDDED := FALSE}
120{$elifc defined __arm__ and __arm__}
121	{$setc TARGET_CPU_PPC := FALSE}
122	{$setc TARGET_CPU_PPC64 := FALSE}
123	{$setc TARGET_CPU_X86 := FALSE}
124	{$setc TARGET_CPU_X86_64 := FALSE}
125	{$setc TARGET_CPU_ARM := TRUE}
126	{ will require compiler define when/if other Apple devices with ARM cpus ship }
127	{$setc TARGET_OS_MAC := FALSE}
128	{$setc TARGET_OS_IPHONE := TRUE}
129	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
130	{$setc TARGET_OS_EMBEDDED := TRUE}
131{$elsec}
132	{$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ is defined.}
133{$endc}
134
135{$ifc defined __LP64__ and __LP64__ }
136  {$setc TARGET_CPU_64 := TRUE}
137{$elsec}
138  {$setc TARGET_CPU_64 := FALSE}
139{$endc}
140
141{$ifc defined FPC_BIG_ENDIAN}
142	{$setc TARGET_RT_BIG_ENDIAN := TRUE}
143	{$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
144{$elifc defined FPC_LITTLE_ENDIAN}
145	{$setc TARGET_RT_BIG_ENDIAN := FALSE}
146	{$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
147{$elsec}
148	{$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
149{$endc}
150{$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
151{$setc CALL_NOT_IN_CARBON := FALSE}
152{$setc OLDROUTINENAMES := FALSE}
153{$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
154{$setc OPAQUE_UPP_TYPES := TRUE}
155{$setc OTCARBONAPPLICATION := TRUE}
156{$setc OTKERNEL := FALSE}
157{$setc PM_USE_SESSION_APIS := TRUE}
158{$setc TARGET_API_MAC_CARBON := TRUE}
159{$setc TARGET_API_MAC_OS8 := FALSE}
160{$setc TARGET_API_MAC_OSX := TRUE}
161{$setc TARGET_CARBON := TRUE}
162{$setc TARGET_CPU_68K := FALSE}
163{$setc TARGET_CPU_MIPS := FALSE}
164{$setc TARGET_CPU_SPARC := FALSE}
165{$setc TARGET_OS_UNIX := FALSE}
166{$setc TARGET_OS_WIN32 := FALSE}
167{$setc TARGET_RT_MAC_68881 := FALSE}
168{$setc TARGET_RT_MAC_CFM := FALSE}
169{$setc TARGET_RT_MAC_MACHO := TRUE}
170{$setc TYPED_FUNCTION_POINTERS := TRUE}
171{$setc TYPE_BOOL := FALSE}
172{$setc TYPE_EXTENDED := FALSE}
173{$setc TYPE_LONGLONG := TRUE}
174uses MacTypes,CFBase,CFString,CFDictionary;
175{$endc} {not MACOSALLINCLUDE}
176
177{$ALIGN POWER}
178
179
180{! @header CFAttributedString
181Instances of CFAttributedString manage character strings and associated sets of attributes (for example, font and kerning) that apply to individual characters or ranges of characters in the string. CFAttributedString as defined in CoreFoundation provides the basic container functionality, while higher levels provide definitions for standard attributes, their values, and additional behaviors involving these. 
182
183CFAttributedString is not a "subclass" of CFString; that is, it does not respond to CFString function calls. CFAttributedString conceptually contains a CFString to which it applies attributes. This protects users of attributed strings from ambiguities caused by the semantic differences between simple and attributed strings.
184
185Attributes are identified by key/value pairs stored in CFDictionaryRefs. Keys must be CFStrings, while the values are arbitrary CFTypeRefs.
186}
187
188
189{ CFAttributedString comes in immutable and mutable flavors.
190}
191type
192	CFAttributedStringRef = ^__CFAttributedString; { an opaque type }
193	__CFAttributedString = record end;
194	CFMutableAttributedStringRef = ^__CFMutableAttributedString; { an opaque type }
195	__CFMutableAttributedString = record end;
196
197{! @function CFAttributedStringGetTypeID
198Returns the type identifier of all CFAttributedString instances.
199}
200function CFAttributedStringGetTypeID: CFTypeID; external name '_CFAttributedStringGetTypeID';
201(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
202
203
204{** CFAttributedString **}
205
206{! @function CFAttributedStringCreate
207Creates an attributed string with the specified string and attributes (both copied).
208}
209function CFAttributedStringCreate( alloc: CFAllocatorRef; str: CFStringRef; attributes: CFDictionaryRef ): CFAttributedStringRef; external name '_CFAttributedStringCreate';
210(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
211
212{! @function CFAttributedStringCreateWithSubstring
213Creates a sub-attributed string from the specified range. It's a programming error for range to specify characters outside the bounds of aStr.
214}
215function CFAttributedStringCreateWithSubstring( alloc: CFAllocatorRef; aStr: CFAttributedStringRef; range: CFRange ): CFAttributedStringRef; external name '_CFAttributedStringCreateWithSubstring';
216(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
217
218{! @function CFAttributedStringCreateCopy
219Creates an immutable attributed string copy.
220}
221function CFAttributedStringCreateCopy( alloc: CFAllocatorRef; aStr: CFAttributedStringRef ): CFAttributedStringRef; external name '_CFAttributedStringCreateCopy';
222(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
223
224{! @function CFAttributedStringGetString
225Returns the string for the attributed string. For performance reasons, this will often point at the backing store of the attributed string, and it might change if the attributed string is edited.  However, this is an implementation detail, and definitely not something that should be counted on.
226}
227function CFAttributedStringGetString( aStr: CFAttributedStringRef ): CFStringRef; external name '_CFAttributedStringGetString';
228(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
229
230{! @function CFAttributedStringGetLength
231Returns the length of the attributed string in characters; same as CFStringGetLength(CFAttributedStringGetString(aStr))
232}
233function CFAttributedStringGetLength( aStr: CFAttributedStringRef ): CFIndex; external name '_CFAttributedStringGetLength';
234(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
235
236{! @function CFAttributedStringGetAttributes
237Returns the attributes at the specified location. If effectiveRange is not NULL, upon return *effectiveRange contains a range over which the exact same set of attributes apply. Note that for performance reasons, the returned effectiveRange is not necessarily the maximal range - for that, use CFAttributedStringGetAttributesAndLongestEffectiveRange().  It's a programming error for loc to specify a location outside the bounds of the attributed string.
238
239Note that the returned attribute dictionary might change in unpredictable ways from under the caller if the attributed string is edited after this call. If you wish to hang on to the dictionary long-term, you should make an actual copy of it rather than just retaining it.  Also, no assumptions should be made about the relationship of the actual CFDictionaryRef returned by this call and the dictionary originally used to set the attributes, other than the fact that the values stored in the dictionary will be identical (that is, ==) to those originally specified.
240}
241function CFAttributedStringGetAttributes( aStr: CFAttributedStringRef; loc: CFIndex; effectiveRange: CFRangePtr ): CFDictionaryRef; external name '_CFAttributedStringGetAttributes';
242(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
243
244{! @function CFAttributedStringGetAttribute
245Returns the value of a single attribute at the specified location. If the specified attribute doesn't exist at the location, returns NULL. If effectiveRange is not NULL, upon return *effectiveRange contains a range over which the exact same attribute value applies. Note that for performance reasons, the returned effectiveRange is not necessarily the maximal range - for that, use CFAttributedStringGetAttributeAndLongestEffectiveRange(). It's a programming error for loc to specify a location outside the bounds of the attributed string.
246}
247function CFAttributedStringGetAttribute( aStr: CFAttributedStringRef; loc: CFIndex; attrName: CFStringRef; effectiveRange: CFRangePtr ): CFTypeRef; external name '_CFAttributedStringGetAttribute';
248(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
249
250{! @function CFAttributedStringGetAttributesAndLongestEffectiveRange
251Returns the attributes at the specified location. If longestEffectiveRange is not NULL, upon return *longestEffectiveRange contains the maximal range within inRange over which the exact same set of attributes apply. The returned range is clipped to inRange. It's a programming error for loc or inRange to specify locations outside the bounds of the attributed string.
252}
253function CFAttributedStringGetAttributesAndLongestEffectiveRange( aStr: CFAttributedStringRef; loc: CFIndex; inRange: CFRange; longestEffectiveRange: CFRangePtr ): CFDictionaryRef; external name '_CFAttributedStringGetAttributesAndLongestEffectiveRange';
254(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
255
256{! @function CFAttributedStringGetAttributeAndLongestEffectiveRange
257Returns the value of a single attribute at the specified location. If longestEffectiveRange is not NULL, upon return *longestEffectiveRange contains the maximal range within inRange over which the exact same attribute value applies. The returned range is clipped to inRange. It's a programming error for loc or inRange to specify locations outside the bounds of the attributed string.
258}
259function CFAttributedStringGetAttributeAndLongestEffectiveRange( aStr: CFAttributedStringRef; loc: CFIndex; attrName: CFStringRef; inRange: CFRange; longestEffectiveRange: CFRangePtr ): CFTypeRef; external name '_CFAttributedStringGetAttributeAndLongestEffectiveRange';
260(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
261
262
263{** CFMutableAttributedString **}
264
265{! @function CFAttributedStringCreateMutableCopy
266Creates a mutable attributed string copy. maxLength, if not 0, is a hard bound on the length of the attributed string; exceeding this size limit during any editing operation is a programming error. If 0, there is no limit on the length.
267}
268function CFAttributedStringCreateMutableCopy( alloc: CFAllocatorRef; maxLength: CFIndex; aStr: CFAttributedStringRef ): CFMutableAttributedStringRef; external name '_CFAttributedStringCreateMutableCopy';
269(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
270
271{! @function CFAttributedStringCreateMutable
272Creates a mutable empty attributed string. maxLength, if not 0, is a hard bound on the length of the attributed string; exceeding this size limit during any editing operation is a programming error. If 0, there is no limit on the length.
273}
274function CFAttributedStringCreateMutable( alloc: CFAllocatorRef; maxLength: CFIndex ): CFMutableAttributedStringRef; external name '_CFAttributedStringCreateMutable';
275(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
276
277{! @function CFAttributedStringReplaceString
278Modifies the string for the attributed string, much like CFStringReplace().  It's an error for range to specify characters outside the bounds of aStr. 
279
280(Note: This function is a convenience on CFAttributedStringGetMutableString(); however, until CFAttributedStringGetMutableString() is implemented, it remains the only way to edit the string of the attributed string.)
281}
282procedure CFAttributedStringReplaceString( aStr: CFMutableAttributedStringRef; range: CFRange; replacement: CFStringRef ); external name '_CFAttributedStringReplaceString';
283(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
284
285{! @function CFAttributedStringGetMutableString
286Gets the string for the attributed string as a mutable string, allowing editing the character contents of the string as if it were an CFMutableString. Attributes corresponding to the edited range are appropriately modified. If, as a result of the edit, new characters are introduced into the string, they inherit the attributes of the first replaced character from range. If no existing characters are replaced by the edit, the new characters inherit the attributes of the character preceding range if it has any, otherwise of the character following range. If the initial string is empty, the attributes for the new characters are also empty.
287
288(Note: This function is not yet implemented and will return NULL except for toll-free bridged instances.)
289}
290function CFAttributedStringGetMutableString( aStr: CFMutableAttributedStringRef ): CFMutableStringRef; external name '_CFAttributedStringGetMutableString';
291(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
292
293{! @function CFAttributedStringSetAttributes
294Sets the value of multiple attributes over the specified range, which should be valid. If clearOtherAttributes is false, existing attributes (which aren't being replaced) are left alone; otherwise they are cleared. The dictionary should be setup for "usual" CF type usage --- CFString keys, and arbitrary CFType values. Note that after this call, further mutations to the replacement dictionary argument by the caller will not affect the contents of the attributed string.
295}
296procedure CFAttributedStringSetAttributes( aStr: CFMutableAttributedStringRef; range: CFRange; replacement: CFDictionaryRef; clearOtherAttributes: Boolean ); external name '_CFAttributedStringSetAttributes';
297(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
298
299{! @function CFAttributedStringSetAttribute
300Sets the value of a single attribute over the specified range, which should be valid. value should not be NULL. 
301}
302procedure CFAttributedStringSetAttribute( aStr: CFMutableAttributedStringRef; range: CFRange; attrName: CFStringRef; value: CFTypeRef ); external name '_CFAttributedStringSetAttribute';
303(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
304
305{! @function CFAttributedStringRemoveAttribute
306Removes the value of a single attribute over the specified range, which should be valid. It's OK for the attribute not the exist over the specified range.
307}
308procedure CFAttributedStringRemoveAttribute( aStr: CFMutableAttributedStringRef; range: CFRange; attrName: CFStringRef ); external name '_CFAttributedStringRemoveAttribute';
309(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
310
311{! @function CFAttributedStringReplaceAttributedString
312Replaces the attributed substring over the specified range with the attributed string specified in replacement. range should be valid. To delete a range of the attributed string, call CFAttributedStringReplaceString() with empty string and specified range. 
313}
314procedure CFAttributedStringReplaceAttributedString( aStr: CFMutableAttributedStringRef; range: CFRange; replacement: CFAttributedStringRef ); external name '_CFAttributedStringReplaceAttributedString';
315(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
316
317{! @function CFAttributedStringBeginEditing
318In cases where attributed string might do a bunch of work to assure self-consistency, CFAttributedStringBeginEditing/CFAttributedStringEndEditing allow disabling that to allow deferring and coalescing any work. It's a good idea to call these around a set of related mutation calls which don't require the string to be in consistent state in between. These calls can be nested. 
319}
320procedure CFAttributedStringBeginEditing( aStr: CFMutableAttributedStringRef ); external name '_CFAttributedStringBeginEditing';
321(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
322
323{! @function CFAttributedStringEndEditing
324In cases where attributed string might do a bunch of work to assure self-consistency, CFAttributedStringBeginEditing/CFAttributedStringEndEditing allow disabling that to allow deferring and coalescing any work. It's a good idea to call these around a set of related mutation calls which don't require the string to be in consistent state in between. These calls can be nested. 
325}
326procedure CFAttributedStringEndEditing( aStr: CFMutableAttributedStringRef ); external name '_CFAttributedStringEndEditing';
327(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)
328
329{$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
330
331end.
332{$endc} {not MACOSALLINCLUDE}