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
|
# CLI and App
`App` is a singleton **instance** of an [Astal.Application](https://aylur.github.io/libastal/astal3/class.Application.html).
Depending on gtk version require paths will differ
<!--TODO: remove gtk4 notice when its available-->
```lua
local App = require("astal.gtk3.app")
local App = require("astal.gtk4.app") -- not yet available
```
## Entry point
`App:start` is a wrapper function for `App:run`
that will only run the application if there is no
instance already running with the specified name.
:::code-group
```lua [init.lua]
App:start({
instance_name = "my-instance", -- defaults to "astal"
main = function()
-- setup anything
-- instantiate widgets
end,
})
```
:::
## Messaging from CLI
If you want to interact with an instance from the CLI,
you can do so by sending a request.
```lua
App:start({
main = function() end,
---@param request string
---@param res fun(response: any): nil
request_handler = function(request, res)
if request == "say hi" then
return res("hi cli")
end
res("unknown command")
end
})
```
```sh
astal say hi
# hi cli
```
## Toggling Windows by their name
In order for Astal to know about your windows, you have to register them.
You can do this by specifying a **unique** `name` and calling `App:add_window`.
```lua
local App = require("astal.gtk3.app")
local function Bar()
return Widget.Window({
name = "Bar",
setup = function(self)
App:add_window(self)
end,
Widget.Box()
})
end
```
You can also invoke `App:add_window` by simply passing the `App` to the `application` prop.
```lua
local App = require("astal.gtk3.app")
local function Bar()
return Widget.Window({
name = "Bar",
application = App,
Widget.Box()
})
end
```
```sh
astal -t Bar
```
:::warning
When assigning the `application` prop make sure `name` comes before.
Props are set sequentially and if name is applied after application it won't work.
:::
## Client instances
The first time `App:start` is invoked the `main` function gets called.
While that instance is running any subsequent execution of the script will call
the `client` function.
:::code-group
```lua [init.lua]
App:start({
-- main instance
main = function(...)
local args = { ... }
print(string.format("{%s}", table.concat(args, ", ")))
end,
-- client instance
client = function(request, ...)
local res = request("you can send a request to the main instance")
print(res)
end,
-- this runs in the main instance
request_handler = function(request, res)
res("response from main instance")
end
})
```
:::
|
