1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
# Subclassing GObject.Object
Astal provides decorator functions that make it easy to subclass gobjects.
## Example Usage
```ts
import GObject, { register, property } from "astal/gobject"
@register()
class MyObj extends GObject.Object {
@property(String)
declare myProp: string
@signal(String, Number)
declare mySignal: (a: string, b: number) => void
}
```
## Property decorator
```ts
type PropertyDeclaration =
| GObject.ParamSpec
| { $gtype: GObject.GType }
function property(declaration: PropertyDeclaration)
```
The `property` decorator can take any class that has a registered GType.
This includes the globally available `String`, `Number`, `Boolean` and `Object`
javascript constructors. They are mapped to their relative `GObject.ParamSpec`.
The property decorator can be applied in the following ways:
1. On a property declaration
```ts {3,4}
@register()
class MyObj extends GObject.Object {
@property(String)
declare myProp: string
}
```
This will create a getter and setter for the property and will also
emit the notify signal when the value is set to a new value.
:::info
The `declare` keyword is required so that the property declaration
is not transpiled into JavaScript, otherwise the initial value of the
property would be `undefined`.
:::
:::warning
The value is checked by reference, this is important if your
property is an object type.
```ts
const dict = obj.prop
dict["key"] = 0
obj.prop = dict // This will not emit notify::prop // [!code error]
obj.prop = { ...dict } // This will emit notify::prop
```
:::
If you want to set a custom default value, do so in the constructor of your class.
```ts {7}
@register()
class MyObj extends GObject.Object {
@property(String)
declare myProp: string
constructor() {
super({ myProp: "default-value" })
}
}
```
2. On a getter
```ts {3,4}
@register()
class MyObj extends GObject.Object {
@property(String)
get myProp () {
return "value"
}
}
```
This will create a read-only property.
3. On a getter and setter
```ts {5,6,10}
@register()
class MyObj extends GObject.Object {
declare private _prop: string
@property(String)
get myProp () {
return "value"
}
set myProp (v: string) {
if (v !== this._prop) {
this._prop = v
this.notify("my-prop")
}
}
}
```
This will create a read-write property.
:::info
When defining getter/setters for the property, notify signal emission has to be done explicitly.
:::
## Signal decorator
```ts
function signal(...params: Array<{ $gtype: GObject.GType })
function signal(declaration?: SignalDeclaration) // Object you would pass to GObject.registerClass
```
You can apply the signal decorator to either a property declaration or a method.
```ts {3,4,6,7}
@register()
class MyObj extends GObject.Object {
@signal(String, String)
declare mySig: (a: String, b: String) => void
@signal(String, String)
mySig(a: string, b: string) {
// default signal handler
}
}
```
You can emit the signal by calling the signal method or using `emit`.
```ts
const obj = new MyObj()
obj.connect("my-sig", (obj, a: string, b: string) => {})
obj.mySig("a", "b")
obj.emit("my-sig", "a", "b")
```
## Register decorator
Every GObject subclass has to be registered. You can pass the same options
to this decorator as you would to `GObject.registerClass`
```ts
@register({ GTypeName: "MyObj" })
class MyObj extends GObject.Object {
}
```
|
