Platforms: MacOS X
The module objc is the core of PyObjC and provides the automatic bridging between Python and Objective-C. It also provides a number of utility functions and types that make it easier to integrate Python and Objective-C code.
The module objc defines a number of functions whose names start with an underscore. Those functions are private and should not be used, they can be removed from release without warning.
NOTE: This document is currently mostly an exhaustive list of stuff and needs to be reorganised once I’ve filled in the technical details.
When the argument is True the bridge will log more information.
This currently results in output on the standard error stream whenever an exception is translated from Python to Objective-C.
When the argument is True protected methods of an Objective-C class will not be included in the output of dir(). Protected methods are those whose selector starts with an underscore.
This option is on by default.
TODO
This function is not available in Python 3.x
TODO
This function is not available in Python 3.x
Parameter: | classname (string) – the name of an Objective-C class |
---|---|
Returns: | the named Objective-C class |
Raise: | objc.nosuchclass_error when the class does not exist |
Returns: | a list of a classes known to the Objective-C runtime |
---|
Returns: | a list of properties from the Objective-C runtime |
---|
The return value is a list with information about properties on this class or protocol from the Objective-C runtime. This does not include properties superclasses.
Every entry in the list is dictionary with the following keys:
Key | Description |
---|---|
name | Name of the property (a string) |
raw_attr | Raw value of the attribute string (a byte string) |
typestr | The type string for this attribute (a byte string) |
classname | When the type string is objc._C_ID this is the name of the Objective-C class (a string). |
readonly | True iff the property is read-only (bool) |
copy | True iff the property is copying the value (bool) |
retain | True iff the property is retaining the value (bool) |
nonatomic | True iff the property is not atomic (bool) |
dynamic | True iff the property is dynamic (bool) |
weak | True iff the property is weak (bool) |
collectable | True iff the property is collectable (bool) |
getter | Non-standard selector for the getter method (a byte string) |
setter | Non-standard selector for the setter method (a byte string) |
All values but name and raw_attr are optional. The other attributes contain a decoded version of the raw_attr value. The boolean attributes should be interpreted as False when the aren’t present.
The documentation for the Objective-C runtime contains more information about property definitions.
This function only returns information about properties as they are defined in the Objective-C runtime, that is using @property definitions in an Objective-C interface. Not all properties as they are commonly used in Objective-C are defined using that syntax, especially properties in classes that were introduced before MacOSX 10.5.
This function always returns an empty list on MacOS X 10.4.
New in version 2.3.
PyObjC automaticly manages Cocoa reference counts for you, the functions in this section help in finetuning this behaviour.
The functions in this section are present as support code for PyObjC’s unittests and are not part of the stable API. Please let us know if you use these functions in your code.
Split an encoded Objective-C signature string into the encoding strings for seperate types.
Parameter: | typestring (byte string) – an encoded method signature |
---|---|
Returns: | list of type signatures |
Return type: | list of byte strings |
This is a private hook that is called during the creation of a subclass.
WARNING: This hook is not part of the stable API.
New in version 2.3.
This is a private hook that’s called during the creation of the proxy for an Objective-C class.
WARNING: This hook is not part of the stable API.
New in version 2.2.
Changed in version 2.3: TODO: In version 2.2 the hook gets called any time the bridge rescans a class, in 2.3 the hook only gets called during initial construction and has less oportunity to change things.
This is a subclass of super that works properly for Objective-C classes as well as regular Python classes.
The statement from Framework import * will replace the regular super by this class.
The Objective-C runtime and the PyObjC bridge represent the types of instance variables and methods arguments and return values as a string with a compact representation. The Python representation of that string is a byte string (that is type bytes in Python 3.x and str in Python 2.x).
The representation for basic types is a single character, the table below lists symbolic constants in the for those constants.
Name | Objective-C type |
---|---|
_C_ID | id (an Objective-C instance) |
_C_CLASS | an Objective-C class |
_C_SEL | a method selector |
_C_CHR | char |
_C_UCHR | unsigned char |
_C_SHT | short |
_C_USHT | unsigned short |
_C_BOOL | bool (or _Bool) |
_C_INT | int |
_C_UINT | unsigned int |
_C_LNG | long |
_C_ULNG | unsigned long |
_C_LNG_LNG | long long |
_C_ULNG_LNG | unsigned long long |
_C_FLT | float |
_C_DBL | double |
_C_VOID | void |
_C_UNDEF | “other” (such a function) |
_C_CHARPTR | C string (char*) |
_C_NSBOOL | BOOL |
_C_UNICHAR | UniChar |
_C_CHAR_AS_TEXT | char when uses as text or a byte array |
_C_CHAR_AS_INT | int8_t (or char when |
used | as a number) |
The values _C_NSBOOL, _C_UNICHAR, _C_CHAR_AS_TEXT and _C_CHAR_AS_INT are inventions of PyObjC and are not used in the Objective-C runtime.
More complex types can be represented using longer type strings:
a pointer to some type is _C_PTR followed by the type string of the pointed-to type.
a bitfield in a structure is represented as _C_BFLD followed by an integer with the number of bits.
Note that PyObjC cannot convert bitfields at this time.
a C structure is represented as _C_STRUCT_B followed by the struct name, followed by '=', followed by the encoded types of all fields followed by _C_STRUCT_E. The field name (including the closing equals sign) is optional.
a C union is represented as _C_UNION_B followed by the struct name, followed by '=', followed by the encoded types of all fields followed by _C_UNION_E. The field name (including the closing equals sign) is optional.
Note that PyObjC cannot convert C unions at this time.
a C array is represented as _C_ARY_B followed by an integer representing the number of items followed by the encoded element type, followed by _C_ARY_E.
The C construct ‘const’ is mapped to _C_CONST, that is a const char* is represented as _C_CONST + _C_CHARPTR.
Method arguments can have prefixes that closer describe their functionality. Those prefixes are inheritted from Distributed Objects are not used by the Objective-C runtime, but are used by PyObjC.
When a pointer argument to a function prefixed by _C_IN, _C_OUT or _C_INOUT the brige assumes that it is a pass by reference argument (that is, a pointer to a single value), unless other information is provided to the bridge.
TODO: Write how to write Objective-C code to ensure that the right prefixes are added by the compiler.
The table below shows constants for a number of C types that are used in Cocoa but are not basic C types.
Constant Objective-C type _C_CFTYPEID CFTypeID _C_NSInteger NSInteger :const`:_C_NSUInteger` NSUInteger _C_CFIndex CFIndex _C_CGFloat CGFloat _sockaddr_type struct sockaddr
A number of Objective-C APIs have one argument that is a context pointer, which is a void*. In Objective-C your can pass a pointer to an arbitrary value, in Python this must be an integer.
PyObjC provides a context object that can be used to allocate unique integers and map those to objects.
(NOTE: The markup below here is probably incorrect)
Add a value to the context registry.
Parameter: | value – An arbitrary object |
---|---|
Returns: | A unique integer that’s suitable to be used as a context pointer |
Remove an object from the context registery, this object must be have been added to the registry before.
Parameter: | value – An object in the context registry |
---|
Creates an instance variable that can be used as an outlet in Interface Builder. When the name is not specified the bridge will use the name from the class dictionary.
The code block below defines an instance variable named “button” and makes that available as an outlet in Interface Builder.
class SomeObject (NSObject):
button = IBOutlet()
Mark an method as an action for use in Interface Builder.
Usage:
class SomeObject (NSObject):
@IBAction
def saveDocument_(self, sender):
pass
Explicitly mark a method as an instance method. Use this when PyObjC incorrectly deduced that a method should be a class method.
Usage:
class SomeObject (NSObject):
@instancemethod
def alloc(self):
pass
Use this decorator on the definition of accessor methods to ensure that it gets the right method signature in the Objective-C runtime.
The valueType is the encoded string for a single value.
Use this decorator to explicitly set the type signature for a method.
An example:
@typedSelector(b'I@:d')
def makeUnsignedIntegerOfDouble_(self, d):
return d
Use this decorator to tell that this function is the callback for an (Objective-C) API.
TODO: further describe
Decorator to tell that this is the “callback” selector for another API.
TODO: further describe
Use this to synthesize a property with getter and setter methods.
TODO: futher describe
PyObjC provides an API that implements locking in the same way as the @synchronized statement in Objective-C.
with object_lock(anNSObject):
pass
Python and Objective-C each provide a native object serialization method, the pickle module in Python and the NSCoding protocol in Objective-C.
It is possible to use an NSKeyedArchiver to store any Python object that can be pickled in an Objective-C serialized data object.
Due to technical details it is not possible to pickle an Objective-C object, unless someone explicitly implements the pickle protocol for such an object.
Both Python and Objective-C have support for properties, which are object attributes that are accessed using attribute access syntax but which result in a method call.
The Python built-in property is used to define new properties in plain Python code. These properties don’t full interoperate with Objective-C code though because they do not necessarily implement the Objective-C methods that mechanisms like Key-Value Coding use to interact with a class.
PyObjC therefore has a number of property classes that allow you to define new properties that do interact fully with the Key-Value Coding and Observation frameworks.
TODO: Implement method for enabling properties on existing classes and tell why that is off by default and when it will be turned on by default.
TODO: The description is way to minimal, even the design document contained more information.
Parameters: |
|
---|
but will rely on some external process to create them. :param ivar: Name of the instance variable that’s used to store the value. When this value is None the name will be calculated from the property name. If it is NULL there will be no instance variable. :param typestr: The Objective-C type for this property, defaults to an arbitrary object. :param depends_on: A sequence of names of properties the value of this property depends on.
During the class definition you can add accessor methods by using the property as a decorator
Decorator for defining the getter method for a property. The name of the method should be the same as the property:
class MyObject (NSObject):
prop = objc.object_property()
@prop.getter
def prop(self):
return 42
It is possible to override property accessor in a subclass:
class MySubclass (MyObject):
@MyObject.prop.getter
def getter(self):
return "the world"
This can also be used to convert a read-only property to a read-write one by adding a setter accessor.