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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
# libastal
> [!WARNING]
> WIP: everything is subject to change
The main goal of this project is to further abstract gtk bindings in higher level
languages with custom state management mechanisms namely in javascript (gjs, node),
lua (lua-lgi) and python (pygobject)
libastal, which is the library written in Vala, comes with
a few widgets built on top of gtk3 and
tools to execute external binaries and store their output
it also comes with a builtin cli client
## Developing
first install libastal or enter nix shell
```bash
bash meson-install.sh # non nix
nix develop .#astal # nix
```
python and lua should be stright forward, have a look at sample.py and sample.lua
for javascript do
```bash
cd js
npm i
npm run types
npm run build -- --watch
```
## Gtk abstractions
`Variable` and `Binding` objects and a function that turns widget constructors
into ones that can take `Binding` objects as parameters are added ontop of gtk bindings
this mechanism takes care of all state management one would need
This works the same in js/lua/python, its just demonstrated in js
```javascript
// this example will work with Variable<string>
// but it can take any type of value
const v = Variable("value")
.poll(1000, "some-executable on $PATH")
.poll(1000, ["some-executable", "with", "args"])
.poll(1000, () => "some-function")
.watch("some-executable")
.watch(["some-executable", "with", "args"])
.observe(someGObject, "signal", (...args) => "some output")
.observe([[gobj1, "signal"], [gobj2, "signal"]], (...args) => "some output")
.onError(console.error) // when the script fails
.onDropped(() => "clean-up") // cleanup resources if needed on drop() or GC
Button({
label: bind(v),
label: bind(v).as(v => "transformed"),
label: v(t => "transformed"), // shorthand for the above
// in ags we have Service.bind("prop")
// here we will do this, since gobject implementations
// will come from Vala code and not js
label: bind(anyGObject, "one-of-its-prop").as(prop => "transformed"),
// event handlers
on_signalname(self, ...args) { print(self, args) },
// setup prop is still here, but should be rarely needed
setup(self) {
self.hook(v, (self) => print(self))
self.hook(gobject, "signal", (self) => print(self))
}
})
// some additional Variable and Binding methods
v.stop_poll()
v.start_poll()
v.stop_watch()
v.start_watch()
v.get()
v.set("new-value")
const unsub = v.subscribe(value => console.log(value))
unsub() // to unsubscribe
const b = bind(v)
b.get()
// note that its value cannot be set through a Binding
// if you want to, you are doing something wrong
// same subscribe mechanism
const unsub = b.subscribe(value => console.log(value))
unsub()
const derived = Variable.derive([v, b], (vval, bval) => {
return "can take a list of Variable | Binding"
})
v.drop() // dispose when no longer needed
// handle cli client
App.start({
instanceName: "my-instance",
responseHandler(msg, response) {
console.log("message from cli", msg)
response("hi")
}
})
```
after `App.start` is called, it will open a socket, which can be used
with the cli client that comes with libastal
```bash
astal --instance-name my-instance "message was sent from cli"
```
## Lower level languages
As said before, the main goal is to make js/lua/python dx better, but libastal
can be used in **any** language that has bindings for glib/gtk.
`Binding` is not implemented in Vala, but in each language, because
they are language specific, and it doesn't make much sense for lower
level languages as they usually don't have a way to declaratively build
layouts. Subclassed widgets and `Variable` can still be used, but they will
need to be hooked **imperatively**. For languages like rust/go/c++
you will mostly benefit from the other libraries (called `Service` in ags).
I can also recommend using [blueprint](https://jwestman.pages.gitlab.gnome.org/blueprint-compiler/)
which lets you define layouts declaratively and hook functionality in your
preferred language.
I am open to add support for any other language if it makes sense,
but if using blueprint makes more sense, I would rather maintain
templates and examples instead to get started with development.
## Goals
- libastal
- Variables
- [x] poll (interval, string)
- [x] pollv (interval, string[])
- [x] pollfn (interval, closure)
- [x] watch (string)
- [x] watchv (string[])
- [ ] ?observe (object, signal, closure)
- Time
- [x] interval
- [x] timeout
- [x] idle
- [x] now signal
- Process
- [x] exec: string, error as Error
- [x] execAsync: proc, stdout, stderr signal
- [x] subprocess: proc, stdout, stderr signal
- app instance with a socket: Application
- [x] gtk settings as props
- [x] window getters
- [x] include cli client
- few additional widgets
- [x] window widget with gtk-layer-shell
- [x] box with children prop
- [ ] button with abstract signals for button-event
- [ ] ?custom calendar like gtk4
- [x] centerbox
- [ ] circularprogress
- [ ] eventbox
- [ ] icon
- [ ] overlay
- [ ] scrollable/viewport
- [ ] slider
- [ ] stack, shown, children setter
- widgets with no additional behaviour only for the sake of it
- [ ] ?drawingarea
- [ ] ?entry
- [ ] ?fixed
- [ ] ?flowbox
- [ ] ?label
- [ ] ?levelbar
- [ ] ?revealer
- [ ] ?switch
- widget prop setters
- [x] css
- [x] class-names
- [x] cursor
- [ ] click-through
- language bindings
- Binding for Variable and any GObject `bind(gobject, property).as(transform)`
- .hook() for widgets
- setup prop for widgets
- constructor overrides to take bindings
- override default `visible` for widgets to true
- wrap Variable in native object to make sure no GValue crashes
- Variable.observe for signals
- Variable.derive that takes either Variables or Bindings
## Help needed
- packaging
- I am not familiar with python or lua ecosystem at all how should they be distributed?
- node-gtk promise issue
- python types
- I don't know much python, and quite honestly I hate python
## TODO
- docs
- consider moving each language into separate repo
- I want to keep these at one place until I'm sure all of them works as expected
- support jsx
- make sure conventions like the casing of names are followed for each language
- I constantly switched between 4 languages they might be off
- port services from ags into Vala
- and add more
|
