A Cocoa Bridge for OpenMCL Randall D. Beer beer@eecs.cwru.edu http://vorlon.cwru.edu/~beer INTRODUCTION The purpose of CocoaBridge is to make Cocoa as easy as possible to use from OpenMCL, in order to support GUI application and development environment activities. It builds on the capabilities provided in the APPLE-OBJC example. The eventual goal is complete integration of Cocoa into CLOS. The current release provides Lisp-like syntax and naming conventions for ObjC object creation and message sending, with automatic type processing and compile-time checking of message sends. It also provides some convenience facilities for working with Cocoa. A small sample Cocoa program can be invoked by evaluating (REQUIRE 'TINY) and then (CCL::TINY-SETUP). This program provides a simple example of using several of the bridge's capabilities BASICS The main things you need to know are: 1) You create and initialize ObjC objects using MAKE-OBJC-INSTANCE. This should be replaced by MAKE-INSTANCE as CLOS integration improves Example: [[NSNumber alloc] initWithFloat: 2.7] in ObjC becomes (MAKE-OBJC-INSTANCE 'NS-NUMBER :INIT-WITH-FLOAT 2.7) in Lisp Note that class names and init keywords are translated from ObjC to Lisp in pretty much the obvious way 2) You send messages to ObjC objects using SEND Examples: [w alphaValue] becomes (SEND W 'ALPHA-VALUE) [w setAlphaValue: 0.5] becomes (SEND W :SET-ALPHA-VALUE 0.5) [v mouse: p inRect: r] becomes (SEND V :MOUSE P :IN-RECT R) Note that message keywords are translated to Lisp in pretty much the obvious way. From within a method, you can also use SEND-SUPER. 3) The @CLASS macro from APPLE-OBJC is currently used to refer to named ObjC classes, which can also be sent messages via SEND. This should be replaced by FIND-CLASS as CLOS integration improves. Example: [NSColor whiteColor] becomes (SEND (@CLASS NS-COLOR) 'WHITE-COLOR) 4) New ObjC classes and methods are currently defined using DEF-OBJC-CLASS and DEFINE-OBJC-METHOD from APPLE-OBJC. This should be replaced by DEFCLASS and DEFMETHOD as CLOS integration improves. NAME TRANSLATION There are a standard set of naming conventions for Cocoa classes, messages, etc. As long as these are followed, the bridge is fairly good at automaticallly translating between ObjC and Lisp names. Examples: "NSURLHandleClient" <==> NS-URL-HANDLE-CLIENT "NSOpenGLView" <==> NS-OPENGL-VIEW "nextEventMatchingMask:untilDate:inMode:dequeue:" <==> (:NEXT-EVENT-MATCHING-MASK :UNTIL-DATE :IN-MODE :DEQUEUE) To see how a given ObjC or Lisp name will be translated by the bridge, you can use the following functions: OBJC-TO-LISP-CLASSNAME string LISP-TO-OBJC-CLASSNAME symbol OBJC-TO-LISP-MESSAGE string LISP-TO-OBJC-MESSAGE keyword-list OBJC-TO-LISP-INIT string LISP-TO-OBJC-INIT keyword-list Of course, there will always be exceptions to any naming convention. Please let me know if you come across any name translation problems that seem to be bugs. Otherwise, the bridge provides two ways of dealing with exceptions: 1) You can pass a string as the class name of MAKE-OBJC-INSTANCE and as the message to SEND. These strings will be directly interpreted as ObjC names, with no translation. This is useful for a one-time exception. Examples: (MAKE-OBJC-INSTANCE "WiErDclass") (SEND o "WiErDmEsSaGe:WithARG:" x y) 2) You can define a special translation rule for your exception. This is useful for an exceptional name that you need to use throughout your code. Examples: (DEFINE-CLASSNAME-TRANSLATION "WiErDclass" WEIRD-CLASS) (DEFINE-MESSAGE-TRANSLATION "WiErDmEsSaGe:WithARG:" (:WEIRD-MESSAGE :WITH-ARG)) (DEFINE-INIT-TRANSLATION "WiErDiNiT:WITHOPTION:" (:WEIRD-INIT :OPTION) The normal rule in ObjC names is that each word begins with a capital letter (except possibly the first). Using this rule literally, "NSWindow" would be translated as N-S-WINDOW, which seems wrong. "NS" is a special word in ObjC that should not be broken at each capital letter. Likewise "URL", "PDF", "OpenGL", etc. Most common special words used in Cocoa are already defined in the bridge, but you can define new ones as follows: (DEFINE-SPECIAL-OBJC-WORD "QuickDraw") Note that message keywords in a SEND such as (SEND V :MOUSE P :IN-RECT R) may look like Lisp keyword args, but they really aren't. All keywords must be present and the order is significant. Neither (:IN-RECT :MOUSE) nor (:MOUSE) translate to "mouse:inRect:" Note that an "init" prefix is optional in the initializer keywords, so (MAKE-OBJC-INSTANCE 'NS-NUMBER :INIT-WITH-FLOAT 2.7) can also be expressed as (MAKE-OBJC-INSTANCE 'NS-NUMBER :WITH-FLOAT 2.7) STRETS Some Cocoa methods return small structures (such as those used to represent points, rects, sizes and ranges). Although this is normally hidden by the ObjC compiler, such messages are sent in a special way, with the storage for the STructure RETurn (STRET) passed as an extra argument. This STRET and special SEND must normally be made explicit in Lisp. Thus NSRect r = [v1 bounds]; [v2 setBounds r]; in ObjC becomes (RLET ((R :<NSR>ect)) (SEND/STRET R V1 'BOUNDS) (SEND V2 :SET-BOUNDS R)) In order to make STRETs easier to use, the bridge provides two conveniences: 1) The SLET and SLET* macros may be used to define local variables that are initialized to STRETs using a normal SEND syntax. Thus, the following is equivalent to the above RLET: (SLET ((R (SEND V 'BOUNDS))) (SEND V2 :SET-BOUNDS R)) 2) The arguments to a SEND are evaluated inside an implicit SLET, so instead of the above, one could in fact just write: (SEND V1 :SET-BOUNDS (SEND V2 'BOUNDS)) There are also several psuedo-functions provided for convenience by the ObjC compiler. The following are currently supported by the bridge: NS-MAKE-POINT, NS-MAKE-RANGE, NS-MAKE-RECT, and NS-MAKE-SIZE. These can be used within a SLET initform or within a message send: (SLET ((P (NS-MAKE-POINT 100.0 200.0))) (SEND W :SET-FRAME-ORIGIN P)) or (SEND W :SET-ORIGIN (NS-MAKE-POINT 100.0 200.0)) However, since these aren't real functions, a call like the following won't work: (SETQ P (NS-MAKE-POINT 100.0 200.0)) The following convenience macros are also provided: NS-MAX-RANGE, NS-MIN-X, NS-MIN-Y, NS-MAX-X, NS-MAX-Y, NS-MID-X, NS-MID-Y, NS-HEIGHT, and NS-WIDTH. Note that there is also a SEND-SUPER/STRET for use within methods. OPTIMIZATION The bridge works fairly hard to optimize message sends under two conditions. In both of these cases, a message send should be nearly as efficient as in ObjC: 1) When both the message and the receiver's class are known at compile-time. In general, the only way the receiver's class is known is if you declare it, which you can do either via a DECLARE or THE form. For example: (SEND (THE NS-WINDOW W) 'CENTER) Note that there is no way in ObjC to name the class of a class. Thus the bridge provides a @METACLASS declaration. The type of an instance of "NSColor" is NS-COLOR. The type of the *class* "NSColor" is (@METACLASS NS-COLOR): (LET ((C (@CLASS NS-COLOR))) (DECLARE ((@METACLASS NS-COLOR) C)) (SEND C 'WHITE-COLOR)) 2) When only the message is known at compile-time, but its type signature is unique. Of the over 6000 messages currently provided by Cocoa, only about 50 of them have nonunique type signatures. An example of a message whose type signature is not unique is SET. It returns VOID for NSColor, but ID for NSSet. In order to optimize sends of messages with nonunique type signatures, the class of the receiver must be declared at compile-time. If the type signature is nonunique or the message is unknown at compile-time, then a slower runtime call must be used. The ability of the bridge to optimize most constant message sends even when the receiver's class is unknown crucially depends on a type signature table that the bridge maintains. When the bridge is first loaded, it initializes this table by scanning all methods of all ObjC classes defined in the environment. If new methods are later defined, this table must be updated. After a major change (such as loading a new framework with many classes), you should evaluate (UPDATE-TYPE-SIGNATURES) to rebuild the type signature table. Because SEND, SEND-SUPER, SEND/STRET and SEND-SUPER/STRET are macros, they cannot be FUNCALLed, APPLYed or passed as functional arguments. The functions %SEND and %SEND/STRET are provided for this purpose. There are also %SEND-SUPER and %SEND-SUPER/STRET functions for use within methods. However, these functions should be used only when necessary since they perform general (nonoptimized) message sends. VARIABLE ARITY MESSAGES There are a few messages in Cocoa that take variable numbers of arguments. Perhaps the most common examples involve formatted strings: [NSClass stringWithFormat: "%f %f" x y] In the bridge, this would be written as follows: (SEND (@CLASS NS-STRING) :STRING-WITH-FORMAT #@"%f %f" (:DOUBLE-FLOAT X :DOUBLE-FLOAT Y)) Note that the types of the variable arguments must be given, since the compiler has no way of knowing these types in general. Variable arity messages can also be sent with the %SEND function: (%SEND (@CLASS NS-STRING) :STRING-WITH-FORMAT #@"%f %f" (LIST :DOUBLE-FLOAT X :DOUBLE-FLOAT Y)) Because the ObjC runtime system does not provide any information on which messages are variable arity, they must be explicitly defined. The standard variable arity messages in Cocoa are predefined. If you need to define a new variable arity message, use (DEFINE-VARIABLE-ARITY-MESSAGE "myVariableArityMessage:") TYPE COERCION OpenMCL's FFI handles many common conversions between Lisp and foreign data, such as unboxing floating-point args and boxing floating-point results. The bridge adds a few more automatic conversions: 1) N...
stec007