source: project/wiki/objc @ 7035

Last change on this file since 7035 was 7035, checked in by Jim Ursetto, 13 years ago

fix typo in objc doc

File size: 28.5 KB
Line 
1[[tags:eggs]]
2
3This is version 0.4 of the '''objc''' extension library for Chicken Scheme.
4
5[[toc:]]
6
7== Description
8
9
10Scheme to Objective C bridge
11
12== Documentation
13
14
15This 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.
16
17This egg [[#Requirements|requires Mac OS X and libffi]].
18
19=== Method invocation
20
21
22 '''macro:''' (objc:send RECEIVER KEYWORD1 ARGUMENT1 ...)
23
24Sends 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)}}.
25
26
27
28 '''macro:''' (objc:send/safe RECEIVER KEYWORD1 ARGUMENT1 ...)
29
30Identical 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.
31
32
33
34 '''macro:''' (objc:send/maybe-safe RECEIVER KEYWORD1 ARGUMENT1 ...)
35 '''parameter:''' (objc:optimize-callbacks) [default: #t]
36
37Identical 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.
38
39If 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.
40
41
42 '''macro:''' (@ RECEIVER KEYWORD ARGUMENT ...)
43
44An abbreviation for {{(objc:send/maybe-safe RECEIVER KEYWORD ARGUMENT ...)}}.  The author prefers this form over the older {{@[...]}} form, described next.
45
46
47
48 '''read-syntax:''' @[RECEIVER KEYWORD ARGUMENT ...]
49
50Same 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.
51
52
53
54For 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:
55  (@ NSDictionary dictionary-with-contents-of-file: name)
56  (@ NSDictionary dictionaryWithContentsOfFile: name)
57
58=== Instances
59
60
61 '''record:''' objc:instance
62
63A wrapper for an instance of an Objective C class.  The object's {{description}} method determines how this record is displayed.
64
65
66
67 '''procedure:''' (objc:class-of ID)
68
69Return 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.
70
71
72
73 '''procedure:''' (objc:instance->pointer OBJ)
74
75Return the raw pointer associated with objc:instance OBJ.
76
77
78
79 '''procedure:''' (objc:pointer->instance ptr)
80
81Create an objc:instance from a raw instance pointer (an {{id}}).  Implicitly retains the object, releasing it when the objc:instance is finalized.
82
83
84
85=== Strings
86
87
88 '''procedure:''' (objc:nsstring STRING)
89
90Constructs a new NSString from STRING.  Currently assumes UTF8 encoding.
91
92
93
94 '''read-syntax:''' @"..."
95
96Equivalent to {{(objc:nsstring "...")}}.
97
98
99
100 '''procedure:''' (objc:nsstring->string STRING)
101
102Converts an NSString into a Scheme string.
103
104
105
106=== Instance variables
107
108
109 '''procedure:''' (objc:ivar-ref OBJECT NAME)
110
111Returns the value of OBJECT's instance variable NAME (which should be a string).
112
113[[#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.
114
115
116
117 '''procedure:''' (objc:ivar-set! OBJECT NAME VALUE)
118 '''procedure:''' (set! (objc:ivar-ref OBJECT NAME) VALUE)
119
120Sets the value of OBJECT's instance variable NAME to VALUE.
121
122Type 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.
123
124[[#memory-management|Reference counts are automatically managed]] for {{id}} types.
125
126
127
128 '''macro:''' (ivar-ref OBJECT NAME)
129
130Shorthand for {{(objc:ivar-ref OBJECT (symbol->string NAME))}}.
131
132
133
134 '''macro:''' (ivar-set! OBJECT NAME VALUE)
135
136Shorthand for {{(objc:ivar-set! OBJECT (symbol->string NAME) VALUE)}}.
137
138
139
140 '''read-syntax:''' @VAR
141
142Intended for use within methods, this expands to {{(objc:ivar-ref self "VAR")}}.
143
144Use {{(set! @var value)}} to set an instance variable.
145
146
147 Examples: 
148 (objc:ivar-set! p "x" 3) 
149 (objc:ivar-ref p "x")     ; => 3 
150 (ivar-ref p x)            ; => 3   
151 (set! @x (vector 1 2 3))  ; when @x is a slot: 
152 @x                        ; => #(1 2 3)
153
154=== Classes
155
156
157 '''macro:''' (define-objc-classes NAME ...)
158
159Locates 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
160 (begin
161   (define NSTextView (objc:string->class "NSTextView"))
162   (define NSTask (objc:string->class "NSTask")))
163
164
165
166 '''record:''' objc:class
167
168A record representing an Objective C class.
169
170<table class="symbol-table"><tr><td>name</td><td>Class name as a string.</td></tr>
171<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>
172<tr><td>class-method-list</td><td>List of class methods.</td></tr>
173<tr><td>super-class</td><td>Superclass of this class (as an objc:class).</td></tr>
174<tr><td>meta-class</td><td>Metaclass of this class (as an objc:class).</td></tr>
175<tr><td>ivar-list</td><td>List of all instance variables in this class (as objc:raw-ivar records).</td></tr>
176<tr><td>ivars</td><td>List of ivars in this class defined in Scheme (as objc:ivar records).</td></tr>
177<tr><td>all-ivars</td><td>Aggregate list of objc:ivar records from the class hierarchy.</td></tr>
178</table>
179
180A 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.
181
182
183
184 '''procedure:''' (objc:class->pointer CLASS)
185
186Return the raw pointer associated with objc:class CLASS.
187
188
189
190 '''procedure:''' (objc:pointer->class ptr)
191
192Create a class from a raw class pointer (a {{Class}}).
193
194
195
196 '''procedure:''' (objc:string->class STRING)
197
198Look up and return the Objective C class named STRING.
199
200
201
202 '''macro:''' (objc:define-method CLASS RT ARGS . BODY)
203 '''macro:''' (objc:define-class-method CLASS RT ARGS . BODY)
204
205Define an instance or class method in CLASS.
206
207<table class="symbol-table"><tr><td>CLASS</td><td>An objc:class object representing the destination class.</td></tr>
208<tr><td>RT</td><td>The return type of the method.</td></tr>
209<tr><td>ARGS</td><td>{{((KEYWORD TYPE VAR-NAME) ...)}} or {{SYMBOL}}</td></tr>
210<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>
211</table>
212
213Each 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.
214
215TYPE should be a [[#types|short typename]], a symbol such as {{INT}}.
216
217Within 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.
218
219Example:
220 
221  (objc:define-method Rect VOID ((set-width: DBL my-w)
222                                 (height:    DBL my-h))
223    (ivar-set! self w my-w)
224    (ivar-set! self h my-h))
225
226Method removal is not yet implemented, but redefining a method will override the old definition.
227
228
229
230 '''macro:''' (define-objc-class CLASS SUPERCLASS IVARS . METHODS)
231
232Defines CLASS (a symbol) with superclass SUPERCLASS (a symbol), instance variables IVARS, and methods METHODS.  The new classname is imported with {{define-objc-classes}}.
233
234SUPERCLASS is looked up for you in the runtime, so it need not be imported.
235
236IVARS 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.
237
238METHODS 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.
239
240You can also use '''+''' as an alias for {{define-class-method}} and '''-''' for {{define-method}}.  These correspond to Objective C method definition syntax.
241 Example:
242 
243  (define-objc-class MyPoint NSObject ((DBL x)
244                                       (DBL y) 
245                                       (slot: closure))
246    (define-method ID init
247      (print "MyPoint init")
248      (@ super init))
249    (- DBL getX @x)
250    (- DBL getY @y)
251    (- ID description
252       (sprintf "<MyPoint: (~a, ~a)>" @x @y))
253 
254    (- VOID ((move-by-x: DBL a) (y: DBL b))
255      (set! @x (+ a @x))
256      (ivar-set! self y (+ b (ivar-ref self y))))  ;; more wordy
257 
258    (- ID ((init-with-x: DBL a) (y: DBL b))
259       (let ((p (@ self init)))
260         (@ p move-by-x: a y: b)
261         (set! @closure (lambda (msg)
262                          (cond ((eq? msg 'initial-x) 
263                                 (print "MyPoint: initial x was " a))
264                                ((eq? msg 'initial-y) 
265                                 (print "MyPoint: initial y was " b)))))
266         p)))
267 
268  #;1> (define p (@ (@ MyPoint alloc) init-with-x: 3.4 y: 4.5))
269  MyPoint init
270  #;2> (@ p move-by-x: 2 y: 3)
271  #<objc-instance <MyPoint: (5.4, 7.5)>>
272  #;3> ((ivar-ref p closure) 'initial-x)
273  MyPoint: initial x was 3.4
274
275
276
277 '''parameter:''' (objc:allow-class-redefinition) [default: #t]
278
279If #f, an error will occur when attempting to redefine an existing class with define-objc-class.
280
281If #t, redefinition is allowed and a warning will be printed.
282
283
284
285=== Types
286
287
288Objective 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.
289
290{{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!}}.
291
292<table class="symbol-table"><tr><td>objc:ID</td><td>id</td></tr>
293<tr><td>objc:CLASS</td><td>Class</td></tr>
294<tr><td>objc:SEL</td><td>SEL</td></tr>
295<tr><td>objc:INT</td><td>int</td></tr>
296<tr><td>objc:DBL</td><td>double</td></tr>
297<tr><td>objc:FLT</td><td>float</td></tr>
298<tr><td>objc:CHR</td><td>char</td></tr>
299<tr><td>objc:SHT</td><td>short</td></tr>
300<tr><td>objc:LNG</td><td>long</td></tr>
301<tr><td>objc:USHT</td><td>unsigned short</td></tr>
302<tr><td>objc:UINT</td><td>unsigned int</td></tr>
303<tr><td>objc:UCHR</td><td>unsigned char</td></tr>
304<tr><td>objc:ULNG</td><td>unsigned long</td></tr>
305<tr><td>objc:BOOL</td><td>BOOL</td></tr>
306<tr><td>objc:PTR</td><td>void *</td></tr>
307<tr><td>objc:CHARPTR</td><td>char *</td></tr>
308<tr><td>objc:NSRECT</td><td>NSRect</td></tr>
309<tr><td>objc:NSSIZE</td><td>NSSize</td></tr>
310<tr><td>objc:NSPOINT</td><td>NSPoint</td></tr>
311<tr><td>objc:NSRANGE</td><td>NSRange</td></tr>
312<tr><td>objc:VOID</td><td>void</td></tr>
313</table>
314
315Instance variables defined in {{define-objc-class}} use the type qualifiers in the following table.
316
317<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>
318<tr><td>ID</td><td>An Objective C instance (objc:ID) with automatic [[#memory-management|memory management]].</td></tr>
319<tr><td>#:outlet</td><td>An Interface Builder outlet (objc:ID).  Memory management is not performed.</td></tr>
320<tr><td>#:slot</td><td>Holds a scheme object, such as a vector or closure.</td></tr>
321<tr><td>#:wrapper</td><td>Holds a scheme object like #:slot, but is less efficient.</td></tr>
322</table>
323
324=== Type conversions
325
326
327Numeric types (such as double and int) are converted to and from Scheme numbers just as in Chicken's C FFI.
328
329Class types are wrapped in unique objc:class records when passed to Scheme---see [[#class-proxies|Class Proxies]] for more details.
330
331An {{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.
332
333There 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]].
334
335Objective 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.
336
337Selectors 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.
338
339CHARPTR (char *) types are converted to Scheme strings, but conversion to CHARPTR is disabled.
340
341NSRect, NSPoint, NSSize and NSRange structures can be sent to and received from Objective C.  Each is represented by a record on the Scheme side.
342
343 '''record:''' ns:rect
344
345{{ns:make-rect}} is provided as an alias for the default constructor {{make-ns:rect}}.  The same is true for the other records.
346
347<table class="symbol-table"><tr><td>x</td><td>X coordinate of origin (NSRect.origin.x)</td></tr>
348<tr><td>y</td><td>Y coordinate of origin (NSRect.origin.y)</td></tr>
349<tr><td>width</td><td>Width of rectangle (NSRect.size.width)</td></tr>
350<tr><td>height</td><td>Height of rectangle (NSRect.size.height)</td></tr>
351</table>
352
353
354
355 '''record:''' ns:size
356
357<table class="symbol-table"><tr><td>width</td><td>Width</td></tr>
358<tr><td>height</td><td>Height</td></tr>
359</table>
360
361
362
363 '''record:''' ns:point
364
365<table class="symbol-table"><tr><td>x</td><td>X coordinate</td></tr>
366<tr><td>y</td><td>Y coordinate</td></tr>
367</table>
368
369
370
371 '''record:''' ns:range
372
373<table class="symbol-table"><tr><td>location</td><td>Start index, 0-based</td></tr>
374<tr><td>length</td><td>Length of range</td></tr>
375</table>
376
377
378
379Other than the four exceptions above, struct, union, and array types cannot be sent to or received from Objective C.
380
381=== Memory management
382
383
384The 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.)
385
386In 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.
387
388Instance 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).
389
390There 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.
391
392=== Class proxies
393
394
395In 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.
396
397For 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.
398
399For 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.
400
401Instance 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.
402
403=== Lowlevel
404
405
406 '''procedure:''' (objc:register-class CLASSNAME SUPERCLASS)
407
408Registers CLASSNAME (a string) having superclass SUPERCLASS (an objc:class) with the Objective C runtime.  An error is raised if CLASSNAME already exists.
409
410
411
412 '''procedure:''' (objc:set-ivars! CLASS IVARS)
413
414Defines 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.
415
416Warning: 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.
417 Example: 
418 (objc:set-ivars! MyClass (list (make-objc:raw-ivar "jimmy" objc:INT 0) 
419                                (make-objc:raw-ivar "cammy" objc:DBL 0)
420
421
422
423 '''procedure:''' (objc:add-method CLASS METHOD TYPES PROC)
424 '''procedure:''' (objc:add-class-method CLASS METHOD TYPES PROC)
425
426Adds a class or instance method to CLASS.
427
428<table class="symbol-table"><tr><td>METHOD</td><td>Method name as a string (e.g. {{"setWidth:height:"}})</td></tr>
429<tr><td>TYPES</td><td>List of encoded argument type strings (such as {{objc:INT}} or "@").</td></tr>
430<tr><td>PROC</td><td>Scheme procedure representing the method.</td></tr>
431</table>
432
433The structure of the TYPES list is {{(RETURN-TYPE SELF SELECTOR METHOD-ARGS...)}}.
434
435You 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.
436
437 Transformation: 
438 (objc:define-method MyClass DBL ((sel1: INT i) (sel2: DBL d)) 
439                                 (print i) (+ i d)) 
440 => 
441 (objc:add-method MyClass "sel1:sel2:"
442                  (list objc:DBL objc:ID objc:SEL objc:INT objc:DBL) 
443                  (lambda (self sel i d) (print i) (+ i d))) 
444 
445
446
447
448 '''procedure:''' (objc:wrap X)
449 '''procedure:''' (objc:unwrap X)
450
451Wrap 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.
452
453These functions are also used to implement the {{#:wrapper}} type qualifier for instance variables.
454
455
456
457 '''record:''' objc:raw-ivar
458
459A 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!}}.
460
461<table class="symbol-table"><tr><td>name</td><td>Name as a string.</td></tr>
462<tr><td>type</td><td>Type as an encoded type string.</td></tr>
463<tr><td>offset</td><td>Offset within class -- for debugging only.</td></tr>
464</table>
465
466
467
468 '''record:''' objc:ivar
469
470A 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:
471
472<table class="symbol-table"><tr><td>function</td><td>Keyword #:slot, #:wrapper, #:outlet, or #:ivar.</td></tr>
473</table>
474
475
476
477 '''procedure:''' (with-autorelease-pool THUNK)
478
479Creates an autorelease pool that lasts for the duration of the thunk.
480
481A 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.
482
483
484
485 '''procedure:''' (objc:import-classes-at-toplevel!)
486
487Import 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.
488
489
490
491 '''procedure:''' (objc:get-class-list)
492
493Looks up and returns a list of all available classes.  At startup, the result of this call is stored in the variable {{objc:classes}}.
494
495
496
497== Cocoa
498
499
500{{(require-extension cocoa)}}
501
502It 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.
503
504Also, 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.
505
506 '''procedure:''' (ns:application-main)
507
508Starts the main event loop of a Cocoa-based application.  If any arguments are present on the command line, they will be passed to NSApplicationMain.
509
510
511
512 '''procedure:''' (ns:beep)
513
514Plays the default system sound using NSBeep.
515
516
517
518 '''procedure:''' (ns:log FORMAT-STR ARGS...)
519
520Logs a message using NSLog.  The optional {{ARGS}} are interpolated into {{FORMAT-STR}} as in {{printf}}.
521
522
523
524 '''procedure:''' (ns:rect-fill RECT)
525
526Fills the passed RECT (an {{ns:rect}}) with the current color, using NSRectFill.
527
528
529
530 '''procedure:''' (cocoa:run)
531
532Send 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.
533
534
535
536Some [[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.
537
538== About this egg
539
540=== Requirements
541
542'''Mac OS X Intel or PPC'''.  This egg does not run on GNUStep.
543
544[[http://www.call-with-current-continuation.org/tarballs/libffi-3.tgz|libffi]].  Chicken itself need not be compiled with libffi support; libffi just needs to be installed on your system.  If the previous link does not work, the [[http://sourceware.org/libffi|last public release of libffi]] is still available, but it's very old.
545
546=== Author
547
548[[http://3e8.org/zb|Zbigniew]], [[mailto:felix@call-with-current-continuation.org|Felix]]
549=== Version history
550
551; 0.4.3 : Callback-safe context for {{release}}; {{add-method}} taints pure ObjC classes.  Verify egg on x86.
552; 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.]]
553; 0.3 : Enable struct support; change to ns: prefix.
554; 0.2 : Add objc:class-of and rename extension
555; 0.1 : Initial release
556
557=== License
558
559 Copyright (c) 2005, 2006, 2007 Jim Ursetto.  All rights reserved.
560 
561 Redistribution and use in source and binary forms, with or without
562 modification, are permitted provided that the following conditions are met:
563 
564   Redistributions of source code must retain the above copyright notice,
565   this list of conditions and the following disclaimer. Redistributions in
566   binary form must reproduce the above copyright notice, this list of
567   conditions and the following disclaimer in the documentation and/or
568   other materials provided with the distribution. Neither the name of the
569   author nor the names of its contributors may be used to endorse or
570   promote products derived from this software without specific prior
571   written permission.
572 
573 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
574 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
575 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
576 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
577 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
578 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
579 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
580 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
581 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
582 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
583 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.