Learn R Programming

RGtk2 (version 2.20.31)

GObject: The GObject system in RGtk2

Description

GObject is the fundamental type providing the common attributes and methods for all object types in GTK+, Pango and other libraries based on GObject. It provides facilities for object construction, properties, and signals.

Usage

gObjectGet(obj, ..., drop = T) "["(obj, value, ...) gObjectSet(obj, ...) "["(obj, propNames) <- value "[["(obj, member, where = parent.frame()) "[["(obj, member) <- value "$"(x, member) "$"(obj, member) <- value gObject(type, ...) gObjectNew(type, ...) gObjectSetData(obj, key, data = NULL) gObjectGetData(obj, key) gObjectGetSignals(obj) gObjectGetPropInfo(obj, parents = TRUE, collapse = TRUE) gTypeGetPropInfo(type) "names"(x) interface(obj) gObjectParentClass(obj)

Arguments

obj
an instance of a GObject
drop
when retrieving the value of a single property, TRUE to return the element from the list, instead of the list with just that element.
member
the name of a member in an R-defined (custom) GObject class
type
the type of GObject
key
the unique identifier under which the data is stored
data
the data to store with the GObject
...
named arguments of properties to set or names of properties to retrieve
propNames
the names properties to set or get
value
a value with which to set a proprety
parents
whether to include the parents when retrieving property info
collapse
whether to collapse the properties over the parents
x
The GObject for which the property names are to be retrieved
where
The environment in which to look for the field accessor function

Value

Properties and data for gObjectGet and gObjectGetData, respectively. gObjectNew returns a new instance of the specified type. gObjectGetPropInfo and gTypeGetPropInfo return a named list (or list of lists if collapse is FALSE) of properties (GParamSpecs) belonging to the GObject type and its parents (unless parents is FALSE). gObjectGetSignals gets a list of signal ids with names for the signals supported by the object. gObjectParentClass returns a pointer to the parent class of the object.

Details

Every GObject has a type, known as a GType. Like all object-oriented paradigms, types may be (in this case singly) inherited. Thus, every GObject has a type that descends from the common GObject type. GObjects may also implement interfaces. The interfaces implemented by a particular object may be found in the interfaces attribute of an R object representing a GObject, for which, as you might expect, inherits("GObject") returns TRUE. To conveniently access this attribute, use interface.

A GObject is usually constructed with the constructor belonging to a particular subtype (for example, gtkWindowNew constructs a GtkWindow). It is also possible to use gObjectNew to construct an instance of GObject with the given type and properties.

The properties of a GObject are name-value pairs that may be retrieved and set using gObjectGet and gObjectSet, respectively. Whenever specifying properties as arguments in RGtk2, name the arguments with the property name and give the desired property value as the actual argument. For example, gObjectSet(window, modal = T) to make a window modal. For convenience, the [.GObject and [<-.GObject functions may be used to get and set properties, respectively. For example, window["modal"] <- T. Properties help describe the state of an object and are convenient for many reasons, including the ability to register handlers that are invoked when a property changes. They are also associated with metadata that describe their purpose and allow runtime checking of constraints, such as the data type or range in the case of a numeric type.

This notification occurs via GObject signals, which are named hooks for which callbacks may be registered. The event driven system of GTK+ depends on signals for coordinating objects in response to both user and programmatic events. You can use gSignalConnect to connect an R function to a signal.

When new GObject classes are defined in R, they may provide additional fields and methods. [[.GObject and [[<-.GObject get and set, respectively, those members, depending on permissions: private members are only available to methods of the defining class, and protected only to subclasses of the defining class. If [[ fails to find an R-defined member, it searches for a C field and then a GObject property. [[<- first tries to set a GObject property before looking for an R member to ensure that properties are set through the proper channel. Note that the bindings of public fields and public and protected methods are locked, so they cannot be changed using [[<-. $<-.GObject serves as a synonym of [[<-.GObject, but $.GObject first checks for a function (see $.RGtkObject) before falling back to the behavior of [[.GObject.

Finally, arbitrary R objects can be stored in a GObject under a specific key for later retrieval. This can be achieved with gObjectSetData and gObjectGetData, respectively. This is similar to attributes in R, with a major difference being that changes occur in the external GObject, transcending the local R object.

GObjects also offer some introspection capabilities. gObjectGetPropInfo and gObjectGetSignals provide a list of supported properties and signals, respectively. names.GObject lists the available properties for an object. It is hoped that in the future methods and fields may also be introspected.

References

http://developer.gnome.org/doc/API/2.0/gobject/gobject-The-Base-Object-Type.html

See Also

GType GSignal