pycocoa.runtime.ObjCSubclass

Package pycocoa :: Module runtime :: Class ObjCSubclass |
[frames] | no frames]

# Class ObjCSubclass

              object --+
                       |
    internals._Objectype --+
                           |
                   _ObjCBase --+
                               |
                              ObjCSubclass

Python class creating an ObjC sub-class of an existing ObjC (super)class.

This class is used only to define the interface and implementation of an ObjC sub-class from Python. It should not be used in any other way. If you want a Python representation of the resulting class, create it with ObjCClass.

It consists primarily of function decorators which you use to add methods to the sub-class.

ObjCSubclass is used to define an ObjC sub-class of an existing class registered with the runtime. When you create an instance of ObjCSubclass, it registers the new sub-class with the ObjC runtime and creates a set of function decorators that you can use to add instance methods or class methods to the sub-class.

Typical usage would be to first create and register the sub-class:

    >>> MySubclass = ObjCSubclass('NSObject', 'MySubclassName')

and then add methods with:

    >>> @MySubclass.method('v')
    >>> def methodThatReturnsVoid(self):
    >>>     pass

    >>> @MySubclass.method('Bi')
    >>> def boolReturningMethodWithInt_(self, x):
    >>>     return True

    >>> @MySubclass.classmethod('@')
    >>> def classMethodThatReturnsId(self):
    >>>     return self

It is probably a good idea to organize the code related to a single sub-class by either (a) putting it in its own module (note that you don't actually need to expose any of the method names or the ObjCSubclass) or (b) bundling it all up inside a Python class definition, perhaps called MySubclassImplementation.

It is also possible to add ObjC ivars to the sub-class, however if you do so, you must call the `.__init__` method with keyword argument register=False, and then call the `.register` method after the ivars have been added.

However, instead of creating the ivars in ObjC land, it is easier to just define Python-based ivars in your sub-class' `.__init__` method.

Instances are created as a pointer to the ObjC object by using:

    >>> myinstance = send_message('MySubclassName', 'alloc')
    >>> myinstance = send_message(myinstance, 'init')

or wrapped inside an ObjCInstance by using:

    >>> myclass = ObjCClass('MySubclassName')
    >>> myinstance = myclass.alloc().init()

Instance Methods
__init__(self, parent, name, register=True, **ivars) New sub-class of the given (super-)class. |
__str__(self) str(x) |
add_ivar(self, name, ctype) Add an instance variable to the sub-class. |
classmethod(self, encoding) Decorator for class methods. |
method(self, encoding) Decorator for instance methods. |
rawmethod(self, encoding) Decorator for instance methods without any fancy shenanigans. |
register(self) Register this new class with the ObjC runtime. |
Inherited from `_ObjCBase`: `__repr__` Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Properties
| isregistered Check whether the (sub)class is registered (`bool`).
| name Get the name of this ObjC sub-class (`str`).
| objc_class Get the ObjC class.
| objc_metaclass Get the ObjC metaclass, or `None` if un-registered.
Inherited from `_ObjCBase`: `description` Inherited from `internals._Objectype`: `typename` Inherited from `object`: `__class__`

Method Details

### __init__(self, parent, name, register=True, **ivars) (Constructor) |
New sub-class of the given (super-)class. Parameters: `parent` - The super-class (`str` or `ObjCClass`). `name` - The sub-class name (`str`). `register` - Register the new sub-class (`bool`). `ivars` - Optionally, specify any number of instance variables to be added before registering the new class, each by a keyword argument `name=ctype` to specify the name and `ctype` of the instance variable. Overrides: object.__init__

### __str__(self) (Informal representation operator) |
str(x) Overrides: object.__str__ (inherited documentation)

### add_ivar(self, name, ctype) |
Add an instance variable to the sub-class. Parameters: `name` - Name of the ivar (`str`). `ctype` - The ivar type (`ctypes`). Raises: `ValueError` - This class is already registered. Note: Instance variables can only be added BEFORE the class is registered.

### classmethod(self, encoding) |
Decorator for class methods. Parameters: `encoding` - Signature of the method (`encoding`) without `Id/self` and `SEL/cmd` encoding. Returns: Decorated class method.

### method(self, encoding) |
Decorator for instance methods. Parameters: `encoding` - Signature of the method (`encoding`), without `Id/self` and `SEL/cmd` encoding. Returns: Decorated instance method.

### rawmethod(self, encoding) |
Decorator for instance methods without any fancy shenanigans. Parameters: `encoding` - Signature of the method (`encoding`) without `Id/self` and `SEL/cmd` encoding. Returns: The instance method. Note: The method must have signature m(self, cmd, *args) where both `Id/self` and `SEL/cmd` are just pointers to ObjC objects of type `Id_t` respectively `SEL_t`.

Property Details

### isregistered Check whether the (sub)class is registered (`bool`). Get Method: isregistered(self) - Check whether the (sub)class is registered (`bool`). Set Method: Read_Only(inst, value) - Throws an `AttributeError`, always.

### name Get the name of this ObjC sub-class (`str`). Get Method: name(self) - Get the name of this ObjC sub-class (`str`). Set Method: Read_Only(inst, value) - Throws an `AttributeError`, always.

### objc_class Get the ObjC class. Get Method: objc_class(self) - Get the ObjC class. Set Method: Read_Only(inst, value) - Throws an `AttributeError`, always.

### objc_metaclass Get the ObjC metaclass, or `None` if un-registered. Get Method: objc_metaclass(self) - Get the ObjC metaclass, or `None` if un-registered. Set Method: Read_Only(inst, value) - Throws an `AttributeError`, always.