|
|
## GObjects
|
|
|
## GObject Construction, Subclassing, Templates and GType
|
|
|
|
|
|
### Constructors
|
|
|
### Constructing GObjects
|
|
|
|
|
|
Object constructors look like JavaScript constructors, and can take a map of properties.
|
|
|
Object constructors look like JavaScript constructors, and can take a map of properties. The object that you pass to `new` (e.g. `Gtk.Label` in `let label = new Gtk.Label()`) is the **constructor object**, which differs from the **class declaration** and the **object instance**.
|
|
|
|
|
|
This object can contain convenient constructor methods and static methods such as `Gio.File.new_for_path()`, however vanilla constructor functions like `GObject.Object.new()` are generally not useful.
|
|
|
|
|
|
```js
|
|
|
let label = new Gtk.Label({
|
... | ... | @@ -12,16 +14,23 @@ let label = new Gtk.Label({ |
|
|
use_markup: true,
|
|
|
visible: true
|
|
|
});
|
|
|
|
|
|
let file = Gio.File.new_for_path('/proc/cpuinfo');
|
|
|
log(file); // [object instance proxy GType:GLocalFile jsobj@0x7f843439eee0 native@0x5639e83b1360]
|
|
|
```
|
|
|
|
|
|
Subclassing GObjects is done like so:
|
|
|
### Subclassing GObjects
|
|
|
|
|
|
GObjects have facilities for defining properties, signals and implemented interfaces. Additionally, Gtk objects support defining a CSS name and composite template.
|
|
|
|
|
|
The **constructor object** is also passed to the `extends` keyword in **class declarations** when subclassing GObjects.
|
|
|
|
|
|
```js
|
|
|
var MyLabel = GObject.registerClass({
|
|
|
// GObject
|
|
|
Implements: [ Gtk.Orientable ], // Interfaces the subclass implements
|
|
|
Properties: {}, // Custom properties
|
|
|
Signals: {}, // Custom signals
|
|
|
Properties: {}, // Custom properties (see [Properties](#properties))
|
|
|
Signals: {}, // Custom signals (see [Signals](#signals))
|
|
|
// Gtk
|
|
|
CssName: '', // CSS name
|
|
|
Template: 'resource:///path/example.ui', // Builder template
|
... | ... | @@ -36,9 +45,48 @@ var MyLabel = GObject.registerClass({ |
|
|
});
|
|
|
```
|
|
|
|
|
|
### Properties
|
|
|
### GType Objects
|
|
|
|
|
|
This is the object that represents a type in the GObject type system. Internally a GType is an integer, but you can't access that integer in GJS.
|
|
|
|
|
|
The `$gtype` property gives the GType object for the given type. This is the proper way to find the GType given an object or a class.
|
|
|
|
|
|
For a class, `GObject.type_from_name('GtkLabel')` would work too if you know the GType name, but only if you had previously constructed a Gtk.Label object.
|
|
|
|
|
|
```js
|
|
|
// These would both print: [object GType for 'GtkLabel']
|
|
|
log(Gtk.Label.$gtype);
|
|
|
log(labelInstance.constructor.$gtype);
|
|
|
```
|
|
|
|
|
|
The `name` property of GType objects gives the GType name as a string ('GtkLabel'). This is the proper way to find the type name given an object or a class.
|
|
|
|
|
|
```js
|
|
|
log(Gtk.Label.$gtype.name);
|
|
|
// expected output: GtkLabel
|
|
|
|
|
|
log(labelInstance.constructor.$gtype.name);
|
|
|
// expected output: GtkLabel
|
|
|
```
|
|
|
|
|
|
### Comparing GObjects
|
|
|
|
|
|
While [`typeof`][mdn-typeof] will return `object` for GObjects, [`instanceof`][mdn-instanceof] can be used to compare an object instance to a constructor object.
|
|
|
|
|
|
```js
|
|
|
log(typeof labelInstance === 'object');
|
|
|
// expected output: true
|
|
|
|
|
|
log(labelInstance instanceof Gtk.Label);
|
|
|
// expected output: true
|
|
|
```
|
|
|
|
|
|
[mdn-typeof]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/typeof
|
|
|
[mdn-instanceof]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/instanceof
|
|
|
|
|
|
## Properties
|
|
|
|
|
|
GObject properties may be retrieved and set using native property style access or standard get/set methods. Note that variables in JavaScript can't contain hyphens (-) so when a property name is *unquoted* use an underscore (_).
|
|
|
GObject properties may be retrieved and set using native property style access or GObject get/set methods. Note that variables in JavaScript can't contain hyphens (-) so when a property name is *unquoted* use an underscore (_).
|
|
|
|
|
|
```js
|
|
|
if (!label.use_markup) {
|
... | ... | @@ -50,7 +98,7 @@ if (!label.use_markup) { |
|
|
|
|
|
GObject subclasses can define their own properties, which is necessary if you want to use `GObject.notify()` or `GObject.bind_property()`.
|
|
|
|
|
|
**NOTE:** Never use underscores in property names in the param spec, because of the conversion between underscores and dashes mentioned above.
|
|
|
**NOTE:** Never use underscores in property names in the ParamSpec, because of the conversion between underscores and dashes mentioned above.
|
|
|
|
|
|
```js
|
|
|
var MyLabel = GObject.registerClass({
|
... | ... | @@ -83,7 +131,7 @@ var MyLabel = GObject.registerClass({ |
|
|
});
|
|
|
```
|
|
|
|
|
|
### Signals
|
|
|
## Signals
|
|
|
|
|
|
Every object inherited from GObject has `connect()`, `connect_after()`, `disconnect()` and `emit()` methods.
|
|
|
|
... | ... | |