invoke

invoke Function

Summary

Invokes an Objective-C method.

Package

objc

Signature

invoke class-or-object-pointer method &rest args => value

Arguments

`class-or-object-pointer`⇩
	A string naming an Objective-C class, a pointer to an Objective-C foreign object or the result of calling current-super.
`method`⇩	A string naming the method to invoke or a list as specified below.
`args`⇩	Arguments to the method.

Values

value

The value returned by the method.

Description

The function invoke is used to call Objective-C instance and class methods.

If class-or-object-pointer is a string, then it must name an Objective-C class and the class method named method in that class is called. If class-or-object-pointer is the result of calling current-super then the instance method named method is invoked for the superclass of the current method. Otherwise class-or-object-pointer should be a foreign pointer to an Objective-C object or class and the appropriate instance or class method named method is invoked.

If method is a string then it should be a concatenation of the message name and its argument names, including the colons, for example "setWidth:height:".

Otherwise method must be a list in one of two forms:

(method-name arg-types)
(method-name arg-types :result-type result-type)

method-name must be a string, as described when method is a string above. arg-types must be a list of FLI argument types, each one matching the corresponding argument to the method. result-type must be the FLI result type of the method, which defaults to :void if omitted. This is primarily intended for invoking methods using vector types, which are not compatible with the Objective-C Runtime type encoding API. See 1.3.8 Invoking a method that uses vector types.

Each argument in args is converted to an appropriate FLI Objective-C value and is passed in order to the method. This conversion is done based on the signature of the method as follows:

`NSRect`	If the argument is a vector of four elements of the form `#(x y width height)`, the `x`, `y`, `width` and `height` are used to form the rectangle. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-rect nd is copied.
`NSSize`	If the argument is a vector of two elements of the form `#(width height)`, the `width` and `height` are used to form the size. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-size and is copied.
`NSPoint`	If the argument is a vector of two elements of the form `#(x y)`, the `x` and `y` are used to form the point. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-point and is copied.
`NSRange`	If the argument is a cons of the form `(location . length)`, the `location` and `length` are used to form the range. Otherwise it is assumed to be a foreign pointer to a cocoa:ns-range object and is copied.
other structures	The argument should be a foreign pointer to the appropriate struct object and is copied.
`BOOL`	If the argument is `nil` then `NO` is passed, if the argument is `t` then `YES` is passed. Otherwise the argument must be an integer (due to a limitation in the Objective-C type system, this case cannot be distinguished from the `signed char` type).
`id`	If the argument is a string then it is converted to a newly allocated Objective-C `NSString` object which is released when the function returns. If the argument is a vector then it is recursively converted to a newly allocated Objective-C `NSArray` object which is released when the function returns. If the argument is `nil` then a null pointer is passed. Otherwise the argument should be a foreign pointer to an Objective-C object of the appropriate class.
`Class`	The argument is coerced to an Objective-C class pointer as if by coerce-to-objc-class. In particular, this allows strings to be passed as class arguments.
`char *`	If the argument is a string then it is converted to a newly allocated foreign string which is freed when the function returns. Otherwise the argument should be a foreign pointer.
struct `structname` *	The argument should be a foreign pointer to a struct whose type is defined by define-objc-struct with `:foreign-name` `structname`.
other integer and pointer types
	All other integer and pointer types are converted using the normal FLI rules.

When the method returns, its value is converted according to its type:

`NSRect`	A vector of four elements of the form `#(x y width height)` is created containing the rectangle.
`NSSize`	A vector of two elements of the form `#(width height)` is created containing the size.
`NSPoint`	A vector of two elements of the form `#(x y)` is created containing the point.
`NSRange`	A cons of the form `(location . length)` is created containing the range.
other structures	Other structures cannot be returned by value using `invoke`. See invoke-into for how to handle these types.
`BOOL`	If the value is `NO` then `0` is returned, otherwise `1` is returned. See also invoke-bool.
`id`	An object of type objc-object-pointer is returned.
`char *`	The value is converted to a string and returned.
other integer and pointer types
	All other integer and pointer types are converted using the normal FLI rules.