You are looking at the legacy documentation of AGS v1. Go to aylur.github.io/ags for AGS v2.
Your First Widget
Start by creating ~/.config/ags/config.js
then run ags in the terminal
You will see nothing happen, just AGS hanging,
this is because you have an empty config.
Running ags will execute the config like a regular script,
it is just a library over GTK, and its on you to program your windows and widgets.
Top Level: Window
The top level container is a Window that will hold widgets.
Reusable Widgets
Both myLabel and myBar constants we declared are a single instance
of a Gtk.Widget. What if you have two monitors and want to have
a bar for each? Make a function that returns a Gtk.Widget instance.
Dynamic Content
Alright, but static text is boring, let’s make it dynamically change by updating the label every second with a date.
Looking great, but that code has too much boilerplate.
Let’s use a fat arrow
instead of the function keyword, and instead of calling interval
let’s use the poll method.
Signals
Usually it is best to avoid polling. Rule of thumb: the less intervals the better.
This is where GObject shines. We can use signals for pretty much everything.
anytime myVariable.value changes it will send a signal
and things can react to it
for example execute a callback
bind its value to a widget’s property
incrementing the value causes the label to update and the callback to execute
For example with pactl it is possible to query information about the volume level,
but we don’t want to have an interval that checks it periodically.
We want a signal that signals every time its changed,
so that we only do operations when its needed, and therefore we don’t waste resources.
pactl subscribe writes to stdout everytime there is a change.
Avoiding external scripts
For most of your system, you don’t have to use external
scripts and binaries to query information.
AGS has builtin Services.
They are just like Variables but instead
of a single value they have more attributes and methods on them.