define-objc-method

define-objc-method Macro

Summary

Defines an Objective-C instance method for a specified class.

Package

objc

Signature

define-objc-method (name result-type &optional result-style)(object-argspec {argspec}*) {form}*

object-argspec ::= (object-var class-name [pointer-var])

argspec ::= (arg-var arg-type [arg-style])

Arguments

`name`⇩	A string naming the method to define.
`result-type`⇩	An Objective-C FLI type.
`result-style`⇩	An optional keyword specifying the result conversion style, either `:lisp` or `:foreign`, or a symbol naming a variable.
`form`⇩	A form.
`object-var`⇩	A symbol naming a variable.
`class-name`⇩	A symbol naming a class defined with define-objc-class.
`pointer-var`⇩	An optional symbol naming a variable.
`arg-var`⇩	A symbol naming a variable.
`arg-type`⇩	An Objective-C FLI type.
`arg-style`⇩	An optional symbol or list specifying the argument conversion style.

Description

The macro define-objc-method defines the Objective-C instance method name for the Objective-C classes associated with class-name. name should be a concatenation of the message name and its argument names, including the colons, for example "setWidth:height:".

If the define-objc-class definition of class-name specifies the (:objc-class-name objc-class-name) option, then the method is added to the Objective-C class objc-class-name. Otherwise, the method is added to the Objective-C class of every subclass of class-name that specifies the :objc-class-name option, allowing a mixin class to define methods that become part of the implementation of its subclasses (see 1.4.6 Abstract classes).

When the method is invoked, each form is evaluated in sequence with object-var bound to the object of type class-name associated with the receiver, pointer-var (if specified) bound to the receiver foreign pointer and each arg-var bound to the corresponding method argument.

Each argument has an arg-type (its Objective-C FLI type) and an optional arg-style, which specifies how the FLI value is converted to a Lisp value. If arg-style is :foreign, then arg-var is bound to the FLI value of the argument (typically an integer or foreign pointer). Otherwise, arg-var is bound to a value converted according to arg-type:

cocoa:ns-rect	If `arg-style` is omitted or `:lisp` then the rectangle is converted to a vector of four elements of the form `#(x y width height)`. Otherwise the argument is a foreign pointer to a cocoa:ns-rect object.
cocoa:ns-size	If `arg-style` is omitted or `:lisp` then the size is converted to a vector of two elements of the form `#(width height)`. Otherwise the argument is a foreign pointer to a cocoa:ns-size object.
cocoa:ns-point	If `arg-style` is omitted or `:lisp` then the point is converted to a vector of two elements of the form `#(x y)`. Otherwise the argument is a foreign pointer to a cocoa:ns-point object.
cocoa:ns-range	If `arg-style` is omitted or `:lisp` then the range is converted to a cons of the form `(location . length)`. Otherwise the argument is a foreign pointer to a cocoa:ns-range object.
objc-object-pointer	If `arg-style` is the symbol string then the argument is assumed to be a pointer to an Objective-C `NSString` object and is converted to a Lisp string or `nil` for a null pointer. If `arg-style` is the symbol array then the argument is assumed to be a pointer to an Objective-C `NSArray` object and is converted to a Lisp vector or `nil` for a null pointer. If `arg-style` is the a list of the form `(array elt-arg-style)` then the argument is assumed to be a pointer to an Objective-C `NSArray` object and is recursively converted to a Lisp vector using `elt-arg-style` for the elements or `nil` for a null pointer. Otherwise, the argument remains as a foreign pointer to the Objective-C object.
objc-c-string	If `arg-style` is the symbol string then the argument is assumed to be a pointer to a foreign string and is converted to a Lisp string or `nil` for a null pointer.

After the last form has been evaluated, its value is converted to result-type according to result-style and becomes the result of the method.

If result-style is a non-keyword symbol and result-type is a foreign structure type defined with define-objc-struct then the variable named by result-style is bound to a pointer to a foreign object of type result-type while forms are evaluated. forms must set the slots in this foreign object to specify the result.

If result-style is :foreign then the value is assumed to be suitable for conversion to result-type using the normal FLI rules.

If result-style is :lisp then additional conversions are performed for specific values of result-type:

cocoa:ns-rect	If the value is a vector of four elements of the form `#(x y width height)`, the `x`, `y`, `width` and `height` are used to form the returned rectangle. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-rect and is copied.
cocoa:ns-size	If the value is a vector of two elements of the form `#(width height)`, the `width` and `height` are used to form the returned size. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-size and is copied.
cocoa:ns-point	If the value is a vector of two elements of the form `#(x y)`, the `x` and `y` are used to form the returned point. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-point and is copied.
cocoa:ns-range	If the value is a cons of the form `(location . length)`, the `location` and `length` are used to form the returned range. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-range object and is copied.
`(:signed :char)` or `(:unsigned :char)`
	If the value is `nil` then `NO` is returned.If the value is `t` then `YES` is returned. Otherwise the value must be an appropriate integer for `result-type`.
objc-object-pointer	If the value is a string then it is converted to a newly allocated Objective-C `NSString` object which the caller is expected to release. If the value is a vector then it is recursively converted to a newly allocated Objective-C `NSArray` object which the caller is expected to release. If the value is `nil` then a null pointer is returned. Otherwise the value should be a foreign pointer to an Objective-C object of the appropriate class.
objc-class	The value is coerced to a Objective-C class pointer as if by coerce-to-objc-class. In particular, this allows strings to be returned.

forms can use functions such as invoke to invoke other methods on pointer-var. The macro current-super can be used to obtain an object that allows methods in the superclass to be invoked (like super in Objective-C).

Examples

See 1.4.3 Defining Objective-C methods.
See 1.4.5 Invoking methods in the superclass.
See 1.4.6 Abstract classes.