Skip to content
You are looking at the legacy documentation of AGS v1. Go to aylur.github.io/ags for AGS v2.

Utils

Running external commands

Synchronously

function exec(cmd: string): string

This is synchronous, meaning it will block the eventloop

const echo = Utils.exec('echo "Hi Mom"') // returns string
console.log(echo) // logs "Hi Mom"
const uptime = Utils.exec(`bash -c "uptime | awk '{print $3}' | tr ',' ' '"`)
console.log(uptime)

Asynchronously

function execAsync(cmd: string | string[]): Promise<string>;

This won’t block,

Utils.execAsync(['echo', 'Hi Mom'])
.then(out => print(out))
.catch(err => print(err));

Running external scripts

function subprocess(
cmd: string | string[],
callback: (out: string) => void,
onError = logError,
bind?: Gtk.Widget,
): Gio.Subprocess

Takes two to four arguments, returns Gio.Subprocess

const proc = Utils.subprocess(
// command to run, in an array just like execAsync
['bash', '-c', 'path-to-bash-script'],
// callback when the program outputs something to stdout
(output) => print(output),
// callback on error
(err) => logError(err),
// optional widget parameter
// if the widget is destroyed the subprocess is forced to quit
widget,
)

Killing the process

proc.force_exit()

Writing and reading files

function readFile(file: string | Gio.File): string
function readFileAsync(file: string | Gio.File): Promise<string>
function writeFileSync(string: string, path: string): Gio.File
function writeFile(string: string, path: string): Promise<Gio.File>

Synchronously

const contents = Utils.readFile('/path/to/file')
Utils.writeFileSync('some content', '/path/to/file')

Asynchronously

Utils.readFileAsync('path-to-file')
.then(content => print('contents of the file: ' + content))
.catch(logError)
Utils.writeFile('Contents: Hi Mom', 'path-to-file')
.then(file => print('file is the Gio.File'))
.catch(err => print(err))

Monitoring files and directories

function monitorFile(
path: string,
callback?: (file: Gio.File, event: Gio.FileMonitorEvent) => void,
flags = Gio.FileMonitorFlags.NONE,
): Gio.FileMonitor | null
const monitor = Utils.monitorFile('/path/to/file', (file, event) => {
print(Utils.readFile(file), event)
})

Canceling the monitor

monitor.cancel()

Timeout and Interval

You can use native JS setTimeout and setInterval, they return a GLib.Source

Timeout

const source = setTimeout(() => { /* callback */ }, 1000)

Interval

const source = setInterval(() => { /* callback */ }, 1000)

To cancel them use GLib.Source.destroy

source.destroy()

You can use the ones from Utils

function interval(
interval: number,
callback: () => void,
bind?: Gtk.Widget,
): number
function timeout(
ms: number,
callback: () => void,
): number
const id = Utils.timeout(1000, () => {
// runs with a second delay
})

The widget parameter is optional

const id = Utils.interval(1000, () => {
// runs immediately and once every second
})

If you pass a widget to Utils.interval, it will automatically be canceled, when the widget is destroyed

const widget = Widget.Label()
const id = Utils.interval(1000, () => {}, widget)
widget.destroy()

To cancel them use GLib.source_remove

import GLib from 'gi://GLib'
GLib.source_remove(id)

Lookup an Icon name

const icon = Utils.lookUpIcon('dialog-information-symbolic')
if (icon) {
// icon is the corresponding Gtk.IconInfo
}
else {
// null if it wasn't found in the current Icon Theme
}

Fetch

should be pretty close to the web api

Utils.fetch('http://wttr.in/?format=3')
.then(res => res.text())
.then(print)
.catch(console.error)

Authentication

authenticate a user using pam

Utils.authenticate('password')
.then(() => print('authentication successful'))
.catch(err => logError(err, 'unsuccessful'))
Utils.authenticateUser("username", "password")
.then(() => print("authentication successful"))
.catch(err => logError(err, 'unsuccessful'))

Send Notifications

Utils.notify('summary', 'body', 'icon-name')
const id = await Utils.notify({
summary: 'Title',
body: 'Description',
iconName: 'icon-name',
actions: {
'Click Me': () => print('clicked')
}
})
const notifications = await Service.import('notifications')
const n = notifications.getNotification(id)