source: project/wiki/objc @ 8480

Last change on this file since 8480 was 8480, checked in by Jim Ursetto, 12 years ago

index: remove yet more spam

File size: 28.8 KB
Line 
1[[tags:eggs macosx]]
2
3This is version 0.4 of the '''objc''' extension library for Chicken Scheme.
4
5[[toc:]]
6
7== Description
8
9<!-- This is a comment -->
10
11Scheme to Objective C bridge
12
13== Documentation
14
15
16This egg provides a basic interface to Objective C from Scheme.  You can invoke class and instance methods, access instance variables, and define Objective C classes directly in Scheme.
17
18This egg [link #Requirements requires Mac OS X and libffi].
19
20=== Method invocation
21
22<highlight language=scheme>
23 '''macro:''' (objc:send RECEIVER KEYWORD1 ARGUMENT1 ...)
24</highlight>
25
26Sends the message KEYWORD1 ARGUMENT1 ... to RECEIVER, which is an objc:instance or objc:class object.  This follows the normal Objective C syntax, so the call {{(objc:send myRect setWidth: 15.0 height: 20.0)}} invokes the method {{setWidth:height:}} on myRect, with arguments 15.0 and 20.0.  If the method has no arguments, use a symbol instead of a keyword: {{(objc:send NSScanner alloc)}}.
27
28
29
30 '''macro:''' (objc:send/safe RECEIVER KEYWORD1 ARGUMENT1 ...)
31
32Identical to {{(objc:send RECEIVER KEYWORD1 ARGUMENT1 ...)}}, but allows callbacks from Objective C into Scheme.  Safe calls are required when invoking any Objective C method that is either implemented in Scheme, or could itself invoke a method defined in Scheme.
33
34
35
36 '''macro:''' (objc:send/maybe-safe RECEIVER KEYWORD1 ARGUMENT1 ...)
37 '''parameter:''' (objc:optimize-callbacks) [default: #t]
38
39Identical to {{objc:send/safe}} when the object or class (or any superclass) is implemented in Scheme, and to {{objc:send}} otherwise.  In general, this greatly improves invocation time for pure Objective C classes and objects, has a negligible impact on Scheme classes, and incurs a 10% penalty for Scheme instances.  This optimization can be disabled by setting the parameter above to {{#f}}---in which case a safe call will always be used.
40
41If class proxies are disabled (they're enabled by default), the bridge can't track which classes have Scheme implementations, so this always performs a safe call.
42
43
44 '''macro:''' (@ RECEIVER KEYWORD ARGUMENT ...)
45
46An abbreviation for {{(objc:send/maybe-safe RECEIVER KEYWORD ARGUMENT ...)}}.  The author prefers this form over the older {{@[...]}} form, described next.
47
48
49
50 '''read-syntax:''' @[RECEIVER KEYWORD ARGUMENT ...]
51
52Same as {{objc:send/maybe-safe}}.  If the receiver is prefixed with the {{unsafe:}} keyword, then this form expands into a {{(objc:send ...)}} expression instead.  Prefixing with {{safe:}} guarantees an {{objc:send/safe}} call.
53
54
55
56For enhanced readability, the bridge accepts hyphenated selector keywords and translates them into their Objective C counterparts by uppercasing any character after a hyphen, then removing the hyphens.  For example, the following are equivalent:
57  (@ NSDictionary dictionary-with-contents-of-file: name)
58  (@ NSDictionary dictionaryWithContentsOfFile: name)
59
60=== Instances
61
62
63 '''record:''' objc:instance
64
65A wrapper for an instance of an Objective C class.  The object's {{description}} method determines how this record is displayed.
66
67
68
69 '''procedure:''' (objc:class-of ID)
70
71Return the class of objc:instance ID, obtained by sending ID a class message.  This procedure also accepts a class object, but the result will generally be the same object.
72
73
74
75 '''procedure:''' (objc:instance->pointer OBJ)
76
77Return the raw pointer associated with objc:instance OBJ.
78
79
80
81 '''procedure:''' (objc:pointer->instance ptr)
82
83Create an objc:instance from a raw instance pointer (an {{id}}).  Implicitly retains the object, releasing it when the objc:instance is finalized.
84
85
86
87=== Strings
88
89
90 '''procedure:''' (objc:nsstring STRING)
91
92Constructs a new NSString from STRING.  Currently assumes UTF8 encoding.
93
94
95
96 '''read-syntax:''' @"..."
97
98Equivalent to {{(objc:nsstring "...")}}.
99
100
101
102 '''procedure:''' (objc:nsstring->string STRING)
103
104Converts an NSString into a Scheme string.
105
106
107
108=== Instance variables
109
110
111 '''procedure:''' (objc:ivar-ref OBJECT NAME)
112
113Returns the value of OBJECT's instance variable NAME (which should be a string).
114
115[[#type-conversions|Type conversion]] is performed on the result, based on the ivar's type.  When the ivar refers to a Scheme object (i.e., is a [[#type-qualifiers|{{#:slot}} or {{#:wrapper}})]], the object is returned transparently.
116
117
118
119 '''procedure:''' (objc:ivar-set! OBJECT NAME VALUE)
120 '''procedure:''' (set! (objc:ivar-ref OBJECT NAME) VALUE)
121
122Sets the value of OBJECT's instance variable NAME to VALUE.
123
124Type conversion is performed on VALUE, based on the ivar type.  When the ivar is a {{#:slot}} or a {{#:wrapper}},  VALUE can be any Scheme object.
125
126[[#memory-management|Reference counts are automatically managed]] for {{id}} types.
127
128
129
130 '''macro:''' (ivar-ref OBJECT NAME)
131
132Shorthand for {{(objc:ivar-ref OBJECT (symbol->string NAME))}}.
133
134
135
136 '''macro:''' (ivar-set! OBJECT NAME VALUE)
137
138Shorthand for {{(objc:ivar-set! OBJECT (symbol->string NAME) VALUE)}}.
139
140
141
142 '''read-syntax:''' @VAR
143
144Intended for use within methods, this expands to {{(objc:ivar-ref self "VAR")}}.
145
146Use {{(set! @var value)}} to set an instance variable.
147
148
149 Examples: 
150 (objc:ivar-set! p "x" 3) 
151 (objc:ivar-ref p "x")     ; => 3 
152 (ivar-ref p x)            ; => 3   
153 (set! @x (vector 1 2 3))  ; when @x is a slot: 
154 @x                        ; => #(1 2 3)
155
156=== Classes
157
158
159 '''macro:''' (define-objc-classes NAME ...)
160
161Locates the Objective C classes NAME ... and defines variables holding pointers to the class objects. NAME may be a symbol or a list of the form {{(VARIABLE CLASSNAME)}}. For example, {{(define-objc-classes NSTextView NSTask)}} is equivalent to
162 (begin
163   (define NSTextView (objc:string->class "NSTextView"))
164   (define NSTask (objc:string->class "NSTask")))
165
166
167
168 '''record:''' objc:class
169
170A record representing an Objective C class.
171
172<table class="symbol-table"><tr><td>name</td><td>Class name as a string.</td></tr>
173<tr><td>method-list</td><td>List of instance methods.  The format is {{((NAME . SIGNATURE) ...)}}, but may change in the future to a list of objc:method records.</td></tr>
174<tr><td>class-method-list</td><td>List of class methods.</td></tr>
175<tr><td>super-class</td><td>Superclass of this class (as an objc:class).</td></tr>
176<tr><td>meta-class</td><td>Metaclass of this class (as an objc:class).</td></tr>
177<tr><td>ivar-list</td><td>List of all instance variables in this class (as objc:raw-ivar records).</td></tr>
178<tr><td>ivars</td><td>List of ivars in this class defined in Scheme (as objc:ivar records).</td></tr>
179<tr><td>all-ivars</td><td>Aggregate list of objc:ivar records from the class hierarchy.</td></tr>
180</table>
181
182A note on instance variables: the bridge generates {{objc:ivar}} records only for ivars defined in Scheme.  However, {{objc:raw-ivar}} records are available for all instance variables.  This API ({{ivar-list / ivars / all-ivars}}) is new and subject to change.
183
184
185
186 '''procedure:''' (objc:class->pointer CLASS)
187
188Return the raw pointer associated with objc:class CLASS.
189
190
191
192 '''procedure:''' (objc:pointer->class ptr)
193
194Create a class from a raw class pointer (a {{Class}}).
195
196
197
198 '''procedure:''' (objc:string->class STRING)
199
200Look up and return the Objective C class named STRING.
201
202
203
204 '''macro:''' (objc:define-method CLASS RT ARGS . BODY)
205 '''macro:''' (objc:define-class-method CLASS RT ARGS . BODY)
206
207Define an instance or class method in CLASS.
208
209<table class="symbol-table"><tr><td>CLASS</td><td>An objc:class object representing the destination class.</td></tr>
210<tr><td>RT</td><td>The return type of the method.</td></tr>
211<tr><td>ARGS</td><td>{{((KEYWORD TYPE VAR-NAME) ...)}} or {{SYMBOL}}</td></tr>
212<tr><td>BODY</td><td>Body of a lambda comprising the method.  The parameters visible inside the lambda are self (a class or instance object), sel (the method selector), and the arguments given in ARGS.</td></tr>
213</table>
214
215Each list in ARGS adds a method argument of type TYPE, visible to the method body as VAR-NAME.  As in Objective C, each argument is associated with a KEYWORD and each KEYWORD is combined into a method name.  Hyphenated keywords are accepted, just like in method invocations.  A bare SYMBOL can be used as the method name (instead of a list) if no arguments are expected.
216
217TYPE should be a [[#types|short typename]], a symbol such as {{INT}}.
218
219Within a method body, you can use {{(@ super ...)}} to call a class or instance method of the superclass.  Note: {{super}} is a reserved keyword, not a variable.
220
221Example:
222 
223  (objc:define-method Rect VOID ((set-width: DBL my-w)
224                                 (height:    DBL my-h))
225    (ivar-set! self w my-w)
226    (ivar-set! self h my-h))
227
228Method removal is not yet implemented, but redefining a method will override the old definition.
229
230
231
232 '''macro:''' (define-objc-class CLASS SUPERCLASS IVARS . METHODS)
233
234Defines CLASS (a symbol) with superclass SUPERCLASS (a symbol), instance variables IVARS, and methods METHODS.  The new classname is imported with {{define-objc-classes}}.
235
236SUPERCLASS is looked up for you in the runtime, so it need not be imported.
237
238IVARS is a list of the form {{((TYPE NAME) ...)}}, where TYPE is a [[#type-qualifiers|type qualifier]] and NAME is a symbol representing the new variable name.  Each instance of CLASS will have a separate copy of these variables.
239
240METHODS are method definitions of the form {{(define-[class-]method RT ARGS . BODY)}}, which are equivalent to calling {{(objc:define-[class]-method CLASS RT ARGS . BODY)}} using the current CLASS.  These methods are defined in the lexical environment of the surrounding {{define-objc-class}} expression.  As a simple consequence, you can surround the class definition with a {{let}} statement and create "static" variables for the class.
241
242You can also use '''+''' as an alias for {{define-class-method}} and '''-''' for {{define-method}}.  These correspond to Objective C method definition syntax.
243 Example:
244 
245  (define-objc-class MyPoint NSObject ((DBL x)
246                                       (DBL y) 
247                                       (slot: closure))
248    (define-method ID init
249      (print "MyPoint init")
250      (@ super init))
251    (- DBL getX @x)
252    (- DBL getY @y)
253    (- ID description
254       (sprintf "<MyPoint: (~a, ~a)>" @x @y))
255 
256    (- VOID ((move-by-x: DBL a) (y: DBL b))
257      (set! @x (+ a @x))
258      (ivar-set! self y (+ b (ivar-ref self y))))  ;; more wordy
259 
260    (- ID ((init-with-x: DBL a) (y: DBL b))
261       (let ((p (@ self init)))
262         (@ p move-by-x: a y: b)
263         (set! @closure (lambda (msg)
264                          (cond ((eq? msg 'initial-x) 
265                                 (print "MyPoint: initial x was " a))
266                                ((eq? msg 'initial-y) 
267                                 (print "MyPoint: initial y was " b)))))
268         p)))
269 
270  #;1> (define p (@ (@ MyPoint alloc) init-with-x: 3.4 y: 4.5))
271  MyPoint init
272  #;2> (@ p move-by-x: 2 y: 3)
273  #<objc-instance <MyPoint: (5.4, 7.5)>>
274  #;3> ((ivar-ref p closure) 'initial-x)
275  MyPoint: initial x was 3.4
276
277
278
279 '''parameter:''' (objc:allow-class-redefinition) [default: #t]
280
281If #f, an error will occur when attempting to redefine an existing class with define-objc-class.
282
283If #t, redefinition is allowed and a warning will be printed.
284
285
286
287=== Types
288
289
290Objective C is a typed language, and the bridge uses these types to decide how to pass values into and out of Objective C.  Each type is represented by a specific string and the bridge provides a variable containing each type string.  The variable names and their associated Objective C types are listed below.
291
292{{objc:define-method}} uses short versions of the types below, with the {{objc:}} prefix removed.  For example, use {{ID}} instead of {{objc:ID}}. The full names are generally used for lower-level methods such as {{objc:add-method}} and {{objc:set-ivars!}}.
293
294<table class="symbol-table"><tr><td>objc:ID</td><td>id</td></tr>
295<tr><td>objc:CLASS</td><td>Class</td></tr>
296<tr><td>objc:SEL</td><td>SEL</td></tr>
297<tr><td>objc:INT</td><td>int</td></tr>
298<tr><td>objc:DBL</td><td>double</td></tr>
299<tr><td>objc:FLT</td><td>float</td></tr>
300<tr><td>objc:CHR</td><td>char</td></tr>
301<tr><td>objc:SHT</td><td>short</td></tr>
302<tr><td>objc:LNG</td><td>long</td></tr>
303<tr><td>objc:USHT</td><td>unsigned short</td></tr>
304<tr><td>objc:UINT</td><td>unsigned int</td></tr>
305<tr><td>objc:UCHR</td><td>unsigned char</td></tr>
306<tr><td>objc:ULNG</td><td>unsigned long</td></tr>
307<tr><td>objc:BOOL</td><td>BOOL</td></tr>
308<tr><td>objc:PTR</td><td>void *</td></tr>
309<tr><td>objc:CHARPTR</td><td>char *</td></tr>
310<tr><td>objc:NSRECT</td><td>NSRect</td></tr>
311<tr><td>objc:NSSIZE</td><td>NSSize</td></tr>
312<tr><td>objc:NSPOINT</td><td>NSPoint</td></tr>
313<tr><td>objc:NSRANGE</td><td>NSRange</td></tr>
314<tr><td>objc:VOID</td><td>void</td></tr>
315</table>
316
317Instance variables defined in {{define-objc-class}} use the type qualifiers in the following table.
318
319<table class="symbol-table"><tr><td>DBL, INT, etc.</td><td>An {{objc:DBL}}, {{objc:INT}}, etc. type---use short typenames, as in {{objc:define-method}}.</td></tr>
320<tr><td>ID</td><td>An Objective C instance (objc:ID) with automatic [[#memory-management|memory management]].</td></tr>
321<tr><td>#:outlet</td><td>An Interface Builder outlet (objc:ID).  Memory management is not performed.</td></tr>
322<tr><td>#:slot</td><td>Holds a scheme object, such as a vector or closure.</td></tr>
323<tr><td>#:wrapper</td><td>Holds a scheme object like #:slot, but is less efficient.</td></tr>
324</table>
325
326=== Type conversions
327
328
329Numeric types (such as double and int) are converted to and from Scheme numbers just as in Chicken's C FFI.
330
331Class types are wrapped in unique objc:class records when passed to Scheme---see [[#class-proxies|Class Proxies]] for more details.
332
333An {{id}}, or instance, type is almost always represented as an {{objc:instance}} record, which is a thin wrapper around a pointer to the Objective C object.  There is generally no automatic conversion to or from Scheme objects, even when the object has a reasonable direct representation in Scheme.  For example, you may not pass the number "3" to a method expecting an {{id}}, even though "3" could be represented as an {{NSNumber}}.  Conversely, an NSNumber representing "3" remains an {{objc:instance}} when returned to Scheme.
334
335There is one exception to this rule: you may pass a string to any method which expects an {{id}}, and it will become an {{NSString}}.  Of course, you can always perform conversions manually using Objective C methods---continuing the example above, an {{(@ NSNumber number-with-int: 3)}} can indeed be passed as an {{id}} argument.  The author has written convenience functions for NSNumber, NSDictionary, and NSArray which reduce the drudgery of conversion.  These should be available soon; [[http://3e8.org/zb|check here for updates]].
336
337Objective C lacks a boolean type; booleans are char types where zero is false and non-zero is true.  Since (char)0 is rare, we convert it to #f when passed to Scheme, which allows Scheme predicates to work without a special test.  We also transform #t and #f to (char)1 and (char)0 when passed to Objective C.  Other character values are passed through as-is.  Unsigned char values, on the other hand, never represent booleans and aren't transformed.
338
339Selectors are converted to strings when passed to Scheme, and strings converted back to selectors when passed to Objective C.  Note that selectors may be wrapped in objc:selector objects in the future.
340
341CHARPTR (char *) types are converted to Scheme strings, but conversion to CHARPTR is disabled.
342
343NSRect, NSPoint, NSSize and NSRange structures can be sent to and received from Objective C.  Each is represented by a record on the Scheme side.
344
345 '''record:''' ns:rect
346
347{{ns:make-rect}} is provided as an alias for the default constructor {{make-ns:rect}}.  The same is true for the other records.
348
349<table class="symbol-table"><tr><td>x</td><td>X coordinate of origin (NSRect.origin.x)</td></tr>
350<tr><td>y</td><td>Y coordinate of origin (NSRect.origin.y)</td></tr>
351<tr><td>width</td><td>Width of rectangle (NSRect.size.width)</td></tr>
352<tr><td>height</td><td>Height of rectangle (NSRect.size.height)</td></tr>
353</table>
354
355
356
357 '''record:''' ns:size
358
359<table class="symbol-table"><tr><td>width</td><td>Width</td></tr>
360<tr><td>height</td><td>Height</td></tr>
361</table>
362
363
364
365 '''record:''' ns:point
366
367<table class="symbol-table"><tr><td>x</td><td>X coordinate</td></tr>
368<tr><td>y</td><td>Y coordinate</td></tr>
369</table>
370
371
372
373 '''record:''' ns:range
374
375<table class="symbol-table"><tr><td>location</td><td>Start index, 0-based</td></tr>
376<tr><td>length</td><td>Length of range</td></tr>
377</table>
378
379
380
381Other than the four exceptions above, struct, union, and array types cannot be sent to or received from Objective C.
382
383=== Memory management
384
385
386The bridge strives to handle memory management automatically.  In general terms, this is accomplished by implicitly retaining an instance object when it is passed into Scheme, and releasing it when the objc:instance is finalized.  The bridge knows that certain selectors, such as alloc and copy, by convention donate a retain reference to you, and adjusts its retain count accordingly.  Furthermore, passing an objc:instance into Objective C retains and autoreleases that object, which is necessary to ensure that short-lived objects (such as automatically created strings) remain valid until the end of a method invocation.  (Each invocation is wrapped in an autorelease pool, hence the autorelease.)
387
388In general, this means you don't have to worry about releasing, autoreleasing or retaining objects.  The expression {{(let ((m [@ MyPoint alloc])) (void))}}, for example, incurs no memory penalty as {{m}} is garbage collected like any other Scheme object.  This principle extends to NSStrings that are created by the bridge when converted from Scheme strings.  Additionally, you may return newly allocated objects from Scheme classes without autoreleasing them.
389
390Instance variables which hold Objective C objects---'''id''' types---are also managed automatically.  Those defined in a Scheme class are properly retained when using {{objc:ivar-set!}}, and properly released in {{dealloc}}.  You should use the {{#:outlet}} type qualifier for Interface Builder outlets, which will turn off automatic management as IB expects.  Ivars defined in a pure Objective C class are never retained or released automatically, as these classes expect to manage memory themselves.  If you must access such a variable directly, you must manually send it retain and release messages (editor's note: the API for such is not exposed right now).
391
392There are some limitations.  Overriding memory-management selectors such as alloc, release, and dealloc is not supported (although alloc does appear to work fine, caveat emptor).  Sending an autorelease message has no effect due to the current implementation of method invocation.  Finally, although the author has tried to ensure automatic memory management works as advertised, certain cases (especially involving calls from Objective C to Scheme) have not been tested and may be problematic at this point.
393
394=== Class proxies
395
396
397In order to implement ivar memory management and transparent access to Scheme objects stored in ivars, the bridge needs to maintain metadata for each class defined in Scheme.  Enter the class proxy, a unique {{objc:class}} record for each class.  Whenever a class pointer is passed into Scheme, this corresponding proxy is looked up and returned.  This means that Scheme can store information about classes beyond that available in the Objective C runtime.
398
399For pure Objective C classes, this proxy is generic, and springs into being dynamically the first time the class is referenced.  It doesn't contain any extra data; it simply notes the class is pure Objective C.
400
401For classes defined in Scheme, the proxy is created at class definition time, and contains (amongst other things) extended instance variable data, including type qualifiers such as slot: and outlet:.  {{objc:ivar-set!}} will look up the object's class, find the appropriate ivar and notice any type qualifier.  Class proxies also keep track of which classes have Scheme implementations, used for minimizing safe callbacks.
402
403Instance proxies per se are not (yet) implemented.  Although objects are wrapped in objc:instance records, each is merely a non-unique wrapper around a pointer and contains no extra data.  Of course, since instance variables can hold Scheme objects, you can store as many "proxy" objects as you like inside any instance.  On the other hand, you have to manually access this data via ivar-ref or by sending the Objective C object a message, which can be cumbersome.  In practice, it may be useful to do this transparently, having an interchangeable proxy Scheme object and Objective C instance.  This is an active area of research.
404
405=== Lowlevel
406
407
408 '''procedure:''' (objc:register-class CLASSNAME SUPERCLASS)
409
410Registers CLASSNAME (a string) having superclass SUPERCLASS (an objc:class) with the Objective C runtime.  An error is raised if CLASSNAME already exists.
411
412
413
414 '''procedure:''' (objc:set-ivars! CLASS IVARS)
415
416Defines in CLASS (an objc:class) the instance variables in IVARS (a list of objc:instance-var records).  The offset parameter of the instance variable records is ignored.
417
418Warning: all old instance variables in MyClass will be removed first. Also, we don't check for conflicts with superclass instance variables.  This should be remedied in a future release.
419 Example: 
420 (objc:set-ivars! MyClass (list (make-objc:raw-ivar "jimmy" objc:INT 0) 
421                                (make-objc:raw-ivar "cammy" objc:DBL 0)
422
423
424
425 '''procedure:''' (objc:add-method CLASS METHOD TYPES PROC)
426 '''procedure:''' (objc:add-class-method CLASS METHOD TYPES PROC)
427
428Adds a class or instance method to CLASS.
429
430<table class="symbol-table"><tr><td>METHOD</td><td>Method name as a string (e.g. {{"setWidth:height:"}})</td></tr>
431<tr><td>TYPES</td><td>List of encoded argument type strings (such as {{objc:INT}} or "@").</td></tr>
432<tr><td>PROC</td><td>Scheme procedure representing the method.</td></tr>
433</table>
434
435The structure of the TYPES list is {{(RETURN-TYPE SELF SELECTOR METHOD-ARGS...)}}.
436
437You may add Scheme methods to pure Objective C classes; when class proxies are enabled, this will automatically taint the class so that safe calls are used.  Currently, a warning is printed when a class is tainted.
438
439 Transformation: 
440 (objc:define-method MyClass DBL ((sel1: INT i) (sel2: DBL d)) 
441                                 (print i) (+ i d)) 
442 => 
443 (objc:add-method MyClass "sel1:sel2:"
444                  (list objc:DBL objc:ID objc:SEL objc:INT objc:DBL) 
445                  (lambda (self sel i d) (print i) (+ i d))) 
446 
447
448
449
450 '''procedure:''' (objc:wrap X)
451 '''procedure:''' (objc:unwrap X)
452
453Wrap or unwrap the Scheme object X inside an Objective C instance (specifically, a {{Scheme_Object_Wrapper}}) so that it can be passed as an {{id}} type.  Essentially, these functions allow you to tunnel a Scheme object through the Objective C bridge, when both endpoints are written in Scheme.  At the moment, the resulting object cannot be accessed meaningfully from the Objective C side.
454
455These functions are also used to implement the {{#:wrapper}} type qualifier for instance variables.
456
457
458
459 '''record:''' objc:raw-ivar
460
461A record describing an Objective C instance variable as seen from the Objective C (as opposed to Scheme) side.  Returned by {{objc:class-ivar-list}}, and used by {{objc:set-ivars!}}.
462
463<table class="symbol-table"><tr><td>name</td><td>Name as a string.</td></tr>
464<tr><td>type</td><td>Type as an encoded type string.</td></tr>
465<tr><td>offset</td><td>Offset within class -- for debugging only.</td></tr>
466</table>
467
468
469
470 '''record:''' objc:ivar
471
472A record describing Scheme's view of an Objective C instance variable.  At the moment, fields include those of {{objc:raw-ivar}} with the following addition:
473
474<table class="symbol-table"><tr><td>function</td><td>Keyword #:slot, #:wrapper, #:outlet, or #:ivar.</td></tr>
475</table>
476
477
478
479 '''procedure:''' (with-autorelease-pool THUNK)
480
481Creates an autorelease pool that lasts for the duration of the thunk.
482
483A global autorelease pool is created automatically at startup, one is wrapped around the main Application Kit event loop, one is wrapped around every call to Objective C, and memory management is generally otherwise automatic.  It is considered unlikely you will have to use this, unless you send Objective C messages directly inside a foreign-lambda.
484
485
486
487 '''procedure:''' (objc:import-classes-at-toplevel!)
488
489Import every class visible to the runtime, as if define-objc-classes had been run on all available classes.  Useful for debugging.  Note that some (rare) classes are not derived from NSObject, and will not respond to standard NSObject selectors, may throw exceptions, or may crash if used.
490
491
492
493 '''procedure:''' (objc:get-class-list)
494
495Looks up and returns a list of all available classes.  At startup, the result of this call is stored in the variable {{objc:classes}}.
496
497
498
499== Cocoa
500
501
502{{(require-extension cocoa)}}
503
504It is possible to create Cocoa applications using this extension.  See [[http://3e8.org/zb/cocoa/creating-a-cocoa-app.html|Creating a Cocoa Application in Chicken]] for a document which walks you through implementing Apple's famous Currency Converter application.
505
506Also, a working application is included in this egg.  Untar the egg, change to the {{tests/}} directory, and type {{make}}.  An application called Temperature Converter will be built.
507
508 '''procedure:''' (ns:application-main)
509
510Starts the main event loop of a Cocoa-based application.  If any arguments are present on the command line, they will be passed to NSApplicationMain.
511
512
513
514 '''procedure:''' (ns:beep)
515
516Plays the default system sound using NSBeep.
517
518
519
520 '''procedure:''' (ns:log FORMAT-STR ARGS...)
521
522Logs a message using NSLog.  The optional {{ARGS}} are interpolated into {{FORMAT-STR}} as in {{printf}}.
523
524
525
526 '''procedure:''' (ns:rect-fill RECT)
527
528Fills the passed RECT (an {{ns:rect}}) with the current color, using NSRectFill.
529
530
531
532 '''procedure:''' (cocoa:run)
533
534Send the run message to the global NSApplication object.  This is intended to be used during debugging, to restart the main application event loop after an error has returned you to the REPL.
535
536
537
538Some [[http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/Functions/AppKitFunctions.html|global Application Kit functions]], such as NSRectFill, take structures which are passed by value.  However, the Chicken FFI only supports passing structs by pointers.  A workaround is provided in the egg; if you need to wrap such a function, see {{ns:rect-fill}} in {{cocoa.scm}} for an example.
539
540== About this egg
541
542=== Requirements
543
544'''Mac OS X Intel or PPC'''.  This egg does not run on GNUStep.
545
546'''libffi'''.  Chicken itself need not be compiled with libffi support; libffi just needs to be installed on your system.  Install one of these:
547
548* [[http://3e8.org/pub/libffi-20071207.tgz|libffi-20071207]]: Preferred build, from a recent [[http://3e8.org/pub/libffi-20071207-build.txt|SVN snapshot]].
549* [[http://www.call-with-current-continuation.org/tarballs/libffi-3.tgz|libffi-3 (Felix's build)]].  Tried and true, but may not work on Leopard.
550* [[http://sourceware.org/libffi|libffi 2.1]]: last public release of libffi, several years old.  Probably unusable.
551
552=== Author
553
554[[http://3e8.org/zb|Zbigniew]], [[mailto:felix@call-with-current-continuation.org|Felix]]
555=== Version history
556
557; 0.4.3 : Callback-safe context for {{release}}; {{add-method}} taints pure ObjC classes.  Verify egg on x86.
558; 0.4 : Class proxies, ivar refcounting, ivar Scheme objects, objc:wrap/unwrap, (@ ...) syntax, hyphenated selectors, callback optimization. [[http://3e8.org/zb/eggs/objc-04-changes.txt|Detailed changelog.]]
559; 0.3 : Enable struct support; change to ns: prefix.
560; 0.2 : Add objc:class-of and rename extension
561; 0.1 : Initial release
562
563=== License
564
565 Copyright (c) 2005, 2006, 2007 Jim Ursetto.  All rights reserved.
566 
567 Redistribution and use in source and binary forms, with or without
568 modification, are permitted provided that the following conditions are met:
569 
570   Redistributions of source code must retain the above copyright notice,
571   this list of conditions and the following disclaimer. Redistributions in
572   binary form must reproduce the above copyright notice, this list of
573   conditions and the following disclaimer in the documentation and/or
574   other materials provided with the distribution. Neither the name of the
575   author nor the names of its contributors may be used to endorse or
576   promote products derived from this software without specific prior
577   written permission.
578 
579 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
580 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
581 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
582 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
583 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
584 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
585 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
586 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
587 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
588 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
589 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.