classes: Custom GObject classes

Description

Highly experimental support for constructing new GObject classes entirely from with R.

Usage

gClass(name, parent = "GObject", ..., abstract = FALSE) parentHandler(method, obj = NULL, ...) assignProp(obj, pspec, value) getProp(obj, pspec) registerVirtuals(virtuals)

Arguments

name

The name of the new class

parent

The name of the parent class

abstract

If TRUE, the class should not be instantiable.

method

The name of the method to invoke in the parent

obj

A GObject

...

Additional arguments. For parentHandler(), arguments to pass to the parent method. For gClass(), arguments specifying the class definition (see Details).

pspec

A GParamSpec describing the property

value

The value to set on the property

virtuals

An environment containing lists where each list contains the names of the virtual methods for the class matching the name of the list

Value

For gClass, the GType of the new class. For getProp, the value of the property.

Details

The bulk of the class definition (everything except the name and the parent) is passed through additional arguments to the gClass function. This information includes:

Methods: R functions that override virtuals methods in a GObject class. Functions overriding methods in the same class are grouped together in a list and are named according to the virtual they override. Each list is passed as a separate parameter to the class_def list and bears the name of the corresponding class.
Signals: Signals that are emitted by the class, in addition to those of the superclasses. Each signal definition is a list containing the following elements: signal name, vector of type names of signal arguments, type name of signal return value, and a vector of values from the GSignalFlags enumeration. The list of signal definitions is passed as a parameter named .signals to the gClass.
Properties: Properties defined by the class. This is a list of lists, each corresponding to a GParamSpec, as created by gParamSpec. The list is passed under the name .props to gClass. The property values are stored in a private environment. To override that behavior or to be notified (first) upon property changes, simply override the set_property and get_property virtuals in the GObject class. To override the implementation of properties defined by an ancestor class, specify their names in a separate vector passed as the .prop_overrides parameter. If you override the setting or getting of properties, you can use assignProp or getProp to conveniently directly assign or get the value of a property to or from the low-level data structure, respectively. These functions differ from the normal property accessor mechanism in that they bypass the property system, thus avoiding recursion. They should only be used when overriding property handling.
Initializer: Upon instance creation, the function named .initialize (in the parameters passed to gClass) will be called with the instance as the only argument.
New members: It is possible to define new public, protected, and private fields and methods inside an R class, by passing them to gClass within lists named .public, .protected, or .private, respectively. The encapsulation works much the same as Java. Any protected and public functions may be overriden in a class derived from the defining class. All public fields are immutable. All function bindings are locked except for private ones. This means private functions can be replaced.

The above may seem complicated, and it is. Please see the alphaSliderClass for an example. Also note that the local function is convenient for defining static namespaces on the fly. For calling parent virtuals, use parentHandler. assignProp and getProp are low-level functions; they should not be used in place of the conventional GObject property mechanism, except in the case mentioned above. registerVirtuals and unregisterVirtuals are meant for use by packages that bind C GObject classes to R using the RGtk2 system. An example of such a package is rggobi.