0
# Core Foundation Framework
1
2
Low-level C API framework providing fundamental data types, collections, memory management, and system services. CoreFoundation forms the foundation layer for all higher-level Cocoa frameworks on macOS.
3
4
## Capabilities
5
6
### Object Creation Functions
7
8
Static functions for creating Core Foundation collection objects from Python data structures, providing efficient bridging between Python and Objective-C collections.
9
10
```python { .api }
11
def CFArrayCreate(allocator, values, numvalues, callbacks):
12
"""
13
Creates an immutable NSArray from Python sequence.
14
15
Args:
16
allocator: Memory allocator (typically None)
17
values: Sequence of objects to include in array
18
numvalues (int): Number of values to include from sequence
19
callbacks: Callback structure (must be None)
20
21
Returns:
22
NSArray: Immutable array containing the specified values
23
"""
24
25
def CFArrayCreateMutable(allocator, capacity, callbacks):
26
"""
27
Creates a mutable NSMutableArray.
28
29
Args:
30
allocator: Memory allocator (typically None)
31
capacity (int): Initial capacity hint (ignored)
32
callbacks: Callback structure (must be None)
33
34
Returns:
35
NSMutableArray: Empty mutable array
36
"""
37
38
def CFDictionaryCreate(allocator, keys, values, numValues, keyCallbacks, valueCallbacks):
39
"""
40
Creates an immutable NSDictionary from key-value pairs.
41
42
Args:
43
allocator: Memory allocator (typically None)
44
keys: Sequence of dictionary keys
45
values: Sequence of dictionary values
46
numValues (int): Number of key-value pairs to include
47
keyCallbacks: Key callback structure (must be None)
48
valueCallbacks: Value callback structure (must be None)
49
50
Returns:
51
NSDictionary: Immutable dictionary with key-value pairs
52
"""
53
54
def CFDictionaryCreateMutable(allocator, capacity, keyCallbacks, valueCallbacks):
55
"""
56
Creates a mutable NSMutableDictionary.
57
58
Args:
59
allocator: Memory allocator (typically None)
60
capacity (int): Initial capacity hint (ignored)
61
keyCallbacks: Key callback structure (must be None)
62
valueCallbacks: Value callback structure (must be None)
63
64
Returns:
65
NSMutableDictionary: Empty mutable dictionary
66
"""
67
68
def CFSetCreate(allocator, values, numvalues, callbacks):
69
"""
70
Creates an immutable NSSet from Python sequence.
71
72
Args:
73
allocator: Memory allocator (typically None)
74
values: Sequence of objects to include in set
75
numvalues (int): Number of values to include from sequence
76
callbacks: Callback structure (must be None)
77
78
Returns:
79
NSSet: Immutable set containing unique values
80
"""
81
82
def CFSetCreateMutable(allocator, capacity, callbacks):
83
"""
84
Creates a mutable NSMutableSet.
85
86
Args:
87
allocator: Memory allocator (typically None)
88
capacity (int): Initial capacity hint (ignored)
89
callbacks: Callback structure (must be None)
90
91
Returns:
92
NSMutableSet: Empty mutable set
93
"""
94
```
95
96
### String Creation
97
98
Functions for creating Core Foundation string objects with proper encoding and memory management.
99
100
```python { .api }
101
def CFSTR(string):
102
"""
103
Creates an NSString from Python string.
104
105
Args:
106
string (str): Python string to convert
107
108
Returns:
109
NSString: Core Foundation string object
110
"""
111
```
112
113
### Localization Functions
114
115
Functions for retrieving localized strings from application bundles, supporting internationalization and localization workflows.
116
117
```python { .api }
118
def CFCopyLocalizedString(key, comment):
119
"""
120
Gets localized string from main application bundle.
121
122
Args:
123
key (str): Localization key
124
comment (str): Developer comment for translators
125
126
Returns:
127
str: Localized string or key if not found
128
"""
129
130
def CFCopyLocalizedStringFromTable(key, table, comment):
131
"""
132
Gets localized string from specific localization table.
133
134
Args:
135
key (str): Localization key
136
table (str): Name of localization table (.strings file)
137
comment (str): Developer comment for translators
138
139
Returns:
140
str: Localized string or key if not found
141
"""
142
143
def CFCopyLocalizedStringFromTableInBundle(key, table, bundle, comment):
144
"""
145
Gets localized string from table in specific bundle.
146
147
Args:
148
key (str): Localization key
149
table (str): Name of localization table
150
bundle: NSBundle object containing localization
151
comment (str): Developer comment for translators
152
153
Returns:
154
str: Localized string or key if not found
155
"""
156
157
def CFCopyLocalizedStringWithDefaultValue(key, table, bundle, value, comment):
158
"""
159
Gets localized string with fallback default value.
160
161
Args:
162
key (str): Localization key
163
table (str): Name of localization table
164
bundle: NSBundle object containing localization
165
value (str): Default value if localization not found
166
comment (str): Developer comment for translators
167
168
Returns:
169
str: Localized string, default value, or key
170
"""
171
```
172
173
### Collection Callback Constants
174
175
Constants defining callback structures for Core Foundation collections, typically set to None for standard object behavior.
176
177
```python { .api }
178
kCFTypeArrayCallBacks: None
179
kCFTypeDictionaryKeyCallBacks: None
180
kCFTypeDictionaryValueCallBacks: None
181
kCFTypeSetCallBacks: None
182
```
183
184
## Usage Examples
185
186
### Creating Collections
187
188
```python
189
import CoreFoundation
190
191
# Create an immutable array
192
python_list = ["apple", "banana", "cherry"]
193
cf_array = CoreFoundation.CFArrayCreate(python_list)
194
195
# Create a mutable dictionary
196
cf_dict = CoreFoundation.CFDictionaryCreateMutable()
197
# Dictionary can be manipulated using NSMutableDictionary methods
198
199
# Create a set from unique values
200
python_items = [1, 2, 2, 3, 3, 3]
201
cf_set = CoreFoundation.CFSetCreate(python_items) # Contains {1, 2, 3}
202
```
203
204
### Working with Strings
205
206
```python
207
import CoreFoundation
208
209
# Create Core Foundation strings
210
title = CoreFoundation.CFSTR("Application Title")
211
message = CoreFoundation.CFSTR("Hello, World!")
212
213
# Use in Core Foundation APIs that require CFStringRef
214
```
215
216
### Localization
217
218
```python
219
import CoreFoundation
220
221
# Get localized strings
222
title = CoreFoundation.CFCopyLocalizedString("APP_TITLE", "Main window title")
223
error_msg = CoreFoundation.CFCopyLocalizedStringFromTable(
224
"NETWORK_ERROR",
225
"Errors",
226
"Network connection failed"
227
)
228
229
# Use with default fallback
230
welcome = CoreFoundation.CFCopyLocalizedStringWithDefaultValue(
231
"WELCOME_MESSAGE",
232
"Main",
233
None, # main bundle
234
"Welcome!", # default value
235
"Welcome message for new users"
236
)
237
```
238
239
## Framework Integration
240
241
The CoreFoundation module provides the foundation layer that all other Cocoa frameworks build upon. Collections created with these functions are fully compatible with Foundation and AppKit frameworks:
242
243
```python
244
import CoreFoundation
245
import Foundation
246
247
# Create array using Core Foundation
248
cf_array = CoreFoundation.CFArrayCreate(["item1", "item2", "item3"])
249
250
# Use with Foundation methods
251
count = cf_array.count() # NSArray method
252
first_item = cf_array.objectAtIndex_(0) # NSArray method
253
254
# Core Foundation and Foundation objects are toll-free bridged
255
foundation_array = Foundation.NSArray.arrayWithObjects_("a", "b", "c", None)
256
# Can be used interchangeably with CF functions
257
```
258
259
## Types
260
261
All Core Foundation objects are bridged to their corresponding Foundation types:
262
263
```python { .api }
264
# Core Foundation types map to Foundation classes
265
CFArrayRef = NSArray
266
CFMutableArrayRef = NSMutableArray
267
CFDictionaryRef = NSDictionary
268
CFMutableDictionaryRef = NSMutableDictionary
269
CFSetRef = NSSet
270
CFMutableSetRef = NSMutableSet
271
CFStringRef = NSString
272
```