desktop_kit v1.0.0
desktop_kit
Native application runtime for Crystal programs on Linux: GTK 4 and libadwaita windows, tabs, splits and surfaces driven by typed actions, with desktop notifications, global shortcuts, DBus IPC and systemd integration.
This release holds the application lifecycle with command line and file arguments, windows with tabs and splits of surfaces, menus, file, color, font and about dialogs, an OpenGL drawing canvas (optionally on its own thread) with keyboard, input method and pointer input, the clipboard, actions with local and global key bindings, desktop notifications, opening URLs, IPC, configuration reload and the GLib layer the runtime builds on.
examples/ holds runnable programs; make examples builds them into bin/:
| Example | Shows |
|---|---|
hello.cr |
windows, tabs and splits of text entries, bindings, a global binding, notifications, reload |
canvas.cr |
an OpenGL canvas following pointer, buttons, scrolling and typed text |
ipc.cr |
opens a window in a running hello.cr |
workspace.cr |
the card window style, pane icons, header bar content, the command palette with custom commands, key sequences, a key table |
snake.cr |
a game on OpenGL canvases in split cards, steered with physical keys |
dialogs.cr |
header bar buttons for confirm and prompt dialogs, toasts, notifications, opening a URL, drops |
panel.cr |
a hidden drop-down panel toggled by a global binding, Escape or panel toggle over IPC |
Requirements
- Crystal ≥ 1.22.3
- GTK ≥ 4.18, libadwaita ≥ 1.7, gtk4-layer-shell ≥ 1.0 and wayland-client (development packages, found with
pkg-config)
Installation
Add the dependency to your shard.yml:
dependencies:
desktop_kit:
github: shpeckman/desktop_kit
version: "~> 1.0"
Run shards install, then:
require "desktop_kit"
API
Applications
Subclass DesktopKit::App, return the content of new surfaces from #new_surface, override the hooks it needs and call #run:
class Hello < DesktopKit::App
protected def new_surface(context : DesktopKit::SurfaceContext) : DesktopKit::Content
# A widget from the application's own GTK bindings.
DesktopKit::WidgetContent.new(DesktopKit::Widget.new(LibGtk.gtk_label_new("Hello")))
end
protected def on_startup
self.css = "window { background: #202020; }"
end
protected def on_activate
new_window
end
protected def on_color_scheme(scheme : DesktopKit::ColorScheme)
puts "now #{scheme}"
end
end
exit Hello.new("org.example.Hello").run(ARGV)
#run drives GTK on a thread of its own and blocks the calling fiber until #quit is called or the last application window closes (see #quit_delay=); it returns the exit status. One application runs at a time. The application id must be a valid reverse-DNS name (ArgumentError otherwise). With single_instance: true, the default, launching the program again hands its arguments to the running instance and exits with the status that instance returns.
With App#restore_session = true the application saves its windows, tabs, splits, their ratios and title overrides when it quits or its last window closes, to $XDG_STATE_HOME/<app id>/session.json, and reopens them on its first activation instead of calling #on_activate. Each surface saves what its content's Content#session_state returns, and #new_surface receives it back as SurfaceContext#session_state. Panels are not saved; a missing or unreadable session activates as usual.
Hooks, all called on the GTK thread:
| Hook | Called |
|---|---|
on_startup |
once GTK is initialized |
on_command_line(command_line) |
on each launch, with the arguments given to #run; returns the exit status |
on_open(files) |
with files to open, from on_command_line or the desktop |
on_activate |
at a launch without files, and on each such relaunch of a single instance |
on_color_scheme(scheme) |
after on_startup, then whenever light/dark changes |
on_reload |
on #reload and SIGUSR2 |
on_binding_failed(binding, message) |
when the desktop does not bind a global binding |
on_window(window) |
with each new window, before it is shown |
on_window_suspended(window, suspended) |
when the desktop stops or resumes showing a window (another workspace, minimized) |
on_user_idle(idle) |
when the user turns idle after #idle_timeout, and when they return |
on_shutdown |
when quitting, while the windows still exist |
on_command_line receives an DesktopKit::CommandLine: #arguments (without the program name), #directory (the launching process's working directory) and #remote? (launched by another process). #path(argument) resolves a file argument against #directory, or from a file:// URI. By default the hook calls on_open with the arguments as files, or on_activate when there are none, and returns 0; on_open calls on_activate. Override on_command_line to parse options:
protected def on_command_line(command_line : DesktopKit::CommandLine) : Int32
if command_line.arguments.first? == "--version"
puts "1.0"
return 0
end
super
end
These methods are callable from any thread:
#post { ... }runs the block on the GTK thread at the next main loop iteration, in posting order. Blocks posted before#runrun once the application is active; blocks still queued when it quits are dropped.#quitcloses the application windows and quits at the next main loop iteration, so the windows outlive the hook or handler that calls it.#reloadcallson_reload, thenContent#on_reloadof every surface's content. Both do nothing unless#running?.#css=sets the application style sheet, applied above the theme; parse errors are logged as warnings.#window_style=sets the look of all windows (see Window style).#undo_timeout=sets how longUndocan reopen closed surfaces, tabs and windows; 5 seconds by default, zero turns undo off.#quit_delay=sets how long the application keeps running after its last window closes: zero, the default, quits right away; a window that opens in time keeps it running;nilruns until#quit.#config_errors=shows a list of configuration errors in a dialog that offers to reload or to ignore them; an empty list closes it. Errors set before#runshow once the application is active.#bell=,#bell_sound=and#bell_volume=set what a ringing bell does (see Bell).#appearance=requestsDesktopKit::Appearance::System(follow the desktop, the default),LightorDark.#idle_timeout=sets how long the user may leave the keyboard and pointer alone beforeon_user_idle(true);nil, the default, reports nothing. The desktop decides (and may never tell);#user_idle?holds the last report.
On the GTK thread, two methods hook into its main loop and return an DesktopKit::Source, which #cancel stops; quitting cancels every source:
#after(delay) { ... }runs the block once delay passed.#watch(fd, conditions = :read) { |condition| ... }calls the block whenever the file descriptor (anInt32or anIO::FileDescriptor) meets one ofSource::ConditionRead,PriorityorWrite.Error,HangUpandInvalidare reported regardless;Invalid(a closed descriptor) ends the watch. Read and write the descriptor without blocking: the GTK thread runs the whole application.
blink = app.after(500.milliseconds) { toggle_cursor }
reader = app.watch(pty) { |condition| drain(pty) if condition.read? }
# later
reader.cancel
While #run runs, SIGINT and SIGTERM quit the application and SIGUSR2 reloads it; the signals return to their default action afterwards.
Windows, tabs and surfaces
A window holds tabs; a tab holds one or more surfaces laid out in splits. A surface shows a DesktopKit::Content, which #new_surface creates: return an DesktopKit::WidgetContent to show a widget, or a subclass of Content. Each call must return a new content; Content#surface is the surface showing it. The DesktopKit::SurfaceContext tells where the surface opens: kind is Window, Tab, Split or Restore (a saved session reopens), parent is the surface it opens from, if any, and session_state is what the saved surface's content returned from Content#session_state. Content#on_close runs once the surface closed for good (past the reach of undo), so the content can free what it holds, such as a child process.
The window, tab and surface methods run on the GTK thread only: in hooks, in perform, or in #post blocks. App#new_window raises RuntimeError elsewhere.
| Method | Does |
|---|---|
App#new_window(parent = nil) |
opens and presents a window with one tab and returns it |
App#windows |
the open windows, oldest first |
App#active_window |
the window focused last |
App#active_surface |
the focused surface of #active_window |
App#surface(id) |
the open surface with Surface#id |
Window#new_tab |
opens a tab after the selected one and selects it |
Window#tabs, #active_tab |
the tabs in tab bar order, the selected tab |
Window#active_surface |
the focused surface of the selected tab |
Window#present, #close |
brings the window to the front, closes it |
Tab#surfaces |
the splits from left or top to right or bottom, then the floats from the bottom one up |
Tab#floats |
the floating surfaces, from the bottom one to the top one |
Tab#active_surface, #zoomed? |
the focused surface, whether one surface fills the tab |
Tab#window, #close |
the window showing the tab, closes it |
Surface#split(direction, share) |
opens a surface beside it, in an DesktopKit::Direction, and focuses it; the new one takes share of their room (default a half) |
Surface#focus, #close |
focuses the surface and selects its tab, closes it |
Surface#present |
focuses the surface and raises its window (PresentSurface) |
Surface#tab, #window, #id |
where it is shown, its identifier, unique in the process |
Surface#focused? |
whether it holds its window's keyboard focus |
Surface#cursor= |
sets the pointer by CSS name ("text", "pointer"); nil resets |
Surface#mouse_visible= |
shows or hides the pointer over it (MouseVisibility) |
Surface#ring_bell |
rings its bell (RingBell, see Bell) |
Surface#show_banner(message, button) { } |
shows a bar with message over the bottom of its pane, and a button running the block; #hide_banner removes it |
Surface#confirm_clipboard(request, text) { |allowed| } |
asks the user to allow a clipboard Paste, Read or Write of text |
Surface#show_on_screen_keyboard |
asks the input method to show the on-screen keyboard of a Canvas (ShowOnScreenKeyboard); returns whether it did |
Window#toast(message, timeout) |
shows a message at the bottom of the window, 3 seconds by default |
Window#decoration= |
DesktopKit::Decoration: Auto, Client, Server or None |
Window#background_blur= |
blurs what lies behind the window's transparent parts |
Window#urgent=, #active? |
asks for the user's attention while inactive, whether it is active |
Window#confirm(heading, body) |
asks a yes/no question in a dialog and yields the answer |
Window#prompt(heading, body) |
asks for a line of text in a dialog and yields it |
Window#open_file, #open_files, #save_file, #choose_folder |
asks for files or a folder in a file dialog and yields the paths (see Dialogs) |
Window#choose_color, #choose_font |
asks for a color or a font and yields it |
Window#show_about(about) |
shows the application's about dialog |
Window#subtitle= |
sets a second line under the window title; nil removes it |
Window#fullscreen=, #fullscreen?, #maximized=, #maximized? |
asks the desktop to (un)fullscreen or (un)maximize it, and its state |
Window#resizable= |
whether the user can resize it; a fixed window keeps its content's size |
Window#app_id= |
the application id the desktop groups it under (icon, window rules); nil uses the application's |
Window#idle_inhibited=, #set_idle_inhibited(on, reason) |
keeps the desktop from blanking or locking while it is open |
Window#shortcuts_inhibited= |
lets the desktop's own shortcuts reach it while focused; the desktop may ask or refuse |
Window#activate(token) |
raises and focuses it with an activation token from another application |
Window#monitor_size |
the logical size of its monitor, nil while not shown |
Window#suspended? |
whether the desktop stopped showing it (on_window_suspended) |
Window#snapshot(path) |
writes what it shows to a PNG at the output's scale; false while not shown or when the file cannot be written |
Window#pick_surface(except:) { |surface| } |
labels the active tab's surfaces with a key each and yields the one whose key is typed next; other keys cancel. #picking?, #cancel_pick |
Window#add_overlay(content, x, y, width, height, modal:) |
shows content over its tabs at a rectangle of the tab area, above earlier overlays, and returns a Window::Overlay (#place, #modal=, #raise, #close, #on_outside_press); input outside the rectangle reaches the splits unless modal, when `#on_outside_press { |
Window#pack_start, #pack_end |
adds a widget, or a button with an DesktopKit::Icon performing an action, to the header bar |
Surface#swap_with(other) |
trades places with another surface of its tab; the focus stays |
Surface#float(bounds = nil), #tile |
lifts it out of the splits to float over its tab (ToggleFloat), moves a float to bounds, splits a float back in |
Surface#floating?, #float_bounds |
whether it floats, and where as a DesktopKit::Bounds; nil for a split |
Surface#stack_into(direction), #stack_with(other), #unstack(layout = :auto) |
moves it into the stack of a neighbouring split (StackInto) or of other, or splits it out beside its stack (Unstack) |
Surface#stacked?, #stack |
whether it shares its split with other surfaces, and the surfaces of its stack in order |
Surface#icon= |
sets an DesktopKit::Icon for its pane header and, while active, its tab; nil removes it |
Surface#read_only= |
marks it read-only with a lock badge (ToggleReadOnly); the content reads #read_only? and decides what to refuse |
Window#key_tables |
the names of its active key tables, innermost last |
Surface#progress= |
shows an DesktopKit::Progress on its pane, tab and the taskbar; nil hides it |
Surface#hover_text= |
shows text, such as a hovered link's target, at the bottom of its pane; nil hides it |
Surface#show_size(text) |
shows text, such as the new size after a resize, in the middle of its pane for a moment |
Surface#start_search(needle), #end_search, #search_active? |
opens and closes its search bar (StartSearch, Search(needle), EndSearch) |
Surface#search_total=, #search_selected= |
the match count and the current match (from 0) the search bar shows |
A window has a header bar with a new tab button, a tab overview button and a menu, App#window_menu (see Menus); the tab bar shows while there is more than one tab. Closing the last surface of a tab closes the tab, and closing the last tab closes the window. Once closed, #closed? is true, Window#new_tab and Surface#split raise RuntimeError, and the objects leave the registries.
A surface can float over its tab instead of taking a split: Surface#float places it at a DesktopKit::Bounds, its x, y, width and height in fractions of the tab area, or cascades it near the middle at 60% of the tab. A tab's only split does not float. The focused float rises above the others, and a float stays inside the tab: dragging its pane header moves it, the grip at its bottom-right corner resizes it down to its content's minimum size, and MoveFloat and ResizeSplit do the same from the keyboard. Surface#tile splits a float back in beside the split under its centre, as dropping it on a split does; surfaces dropped on a float are refused. GotoSplit Previous and Next go through the splits, then the floats; a float has no neighbours in a direction, and does not swap or zoom. While a split is zoomed the floats hide; focusing one ends the zoom. Closing the last split of a tab that has floats turns the top float into the split; moving a float to another tab or window makes it a split there. Saved sessions and Undo keep floats where they were.
A stack is several surfaces in one split, one shown at a time; the pane header of each shows its place, such as 2/3. Surface#stack_into and StackInto move a surface into the stack of the split next to it, the split becoming a stack if it is none; Surface#stack_with moves a split or a float into the stack of another split. The surface moved in shows after the one shown before and takes the focus. GotoStacked shows another surface of the focused one's stack, and focusing a hidden surface shows it; neither rebuilds the splits. Unstack splits the focused surface out beside its stack, along the stack's longer side for Auto. Closing or moving the shown surface shows the next one, and a stack left with one surface is a plain split again. A stack moves, swaps, resizes and zooms as one split; GotoSplit and Window#pick_surface see only its shown surface. Saved sessions and Undo keep stacks with their order and shown surface.
Undo reopens the latest closed surface, tab or window within App#undo_timeout: a surface returns to its place in the split tree when the tab has not changed since, and next to the active surface otherwise; a tab returns to its position, a window with all its tabs. The content is the same object, so its state survives; it is released, and #closed? becomes true, only once the timeout passes. Redo closes what Undo reopened last.
DesktopKit::Progress.new(value, state) describes a long task: value from 0 to 1, or nil for an indeterminate bar, and state Normal, Error or Paused. Surface#progress= shows it as a bar at the top of the pane and a loading indicator on the tab, and sends the mean of all surfaces' progress to the taskbar through com.canonical.Unity.LauncherEntry, which KDE Plasma and Ubuntu's dock read for the desktop file named after the application id.
Dialogs
The file, color and font dialogs show over the window; inside a sandbox the desktop portal shows them. Each yields its result to the block on the GTK thread, nil (or no paths) when the user cancels, and never when the window closed first. Keyword arguments, all optional:
| Method | Arguments | Yields |
|---|---|---|
#open_file |
title, folder, filters |
Path? |
#open_files |
title, folder, filters |
Array(Path) |
#save_file |
title, folder, name, filters |
Path? |
#choose_folder |
title, folder |
Path? |
#choose_color |
title, color, alpha (default true) |
DesktopKit::Color? |
#choose_font |
title, font |
String? |
DesktopKit::FileFilter.new(name, patterns, mime_types) lists files matching any glob or MIME type under name. DesktopKit::Color holds red, green, blue and alpha from 0.0 to 1.0. Fonts are Pango descriptions such as "Monospace Bold 12". The save dialog asks before replacing a file.
window.open_file(filters: [DesktopKit::FileFilter.new("Images", mime_types: ["image/*"])]) do |path|
viewer.load(path) if path
end
window.show_about(DesktopKit::About.new("Viewer", version: "1.0",
developers: ["Ann <ann@example.org>"], website: "https://example.org", license: :gpl30))
DesktopKit::About takes the application name and optionally version, icon (an icon name), developer, developers, comments, website, issue_url, copyright and license (About::License).
Menus
An DesktopKit::Menu holds sections of items; each item has a label and either an action to perform or a submenu. Menu.build fills one; #section starts a new section below a separator:
app.window_menu = DesktopKit::Menu.build do |menu|
menu.item "New Window", DesktopKit::Action::NewWindow.new
menu.section
menu.submenu "Split" do |split|
split.item "Right", DesktopKit::Action::NewSplit.new(:right)
split.item "Down", DesktopKit::Action::NewSplit.new(:down)
end
menu.item "Settings", OpenSettings.new
end
App#window_menu= replaces the header menu of every window, open ones too; Menu.window, the default, holds the window, tab, split, title and close actions and the keyboard shortcuts. A content's context menu comes from its Content#context_menu(x, y) hook, called on a right click at x, y (logical pixels from its top left): return a menu to show it there, or nil, the default, to pass the click on. The surface is focused first, so tab and split actions act on it.
Window style
App#window_style= takes an DesktopKit::WindowStyle; the defaults give GTK's plain look, with the header bar on and the other options off:
| Option | Effect |
|---|---|
pane_headers |
a header over each surface: its icon, its title and buttons to split right, split down, zoom and close it |
cards |
surfaces as rounded cards with gaps between them |
gap |
space around each card, in pixels (4) |
radius |
corner radius of the cards, in pixels (12); windows that draw their own frame round their corners to match |
tabs_in_header |
the tab bar in the header bar, beside the window title, always shown |
header_bar |
the header bar with the title, the tabs and their buttons; false leaves windows without a title bar of their own and passes libadwaita's tab keys (Ctrl+Tab, Ctrl+Page Up, Alt+1 …) to the content |
pill_tabs |
tabs as pills, the selected one outlined, each with its icon on a badge |
tint |
a #rrggbb color that washes over the window background, fading from its top left corner |
opacity |
opacity of the window background, 0 to 1; pair it with Window#background_blur= |
unfocused_opacity |
opacity of the surfaces of a split other than the tab's active one, 0 to 1 |
The style applies to open windows at once. on_window adds header bar content to each new window:
class Hello < DesktopKit::App
protected def on_startup : Nil
self.window_style = DesktopKit::WindowStyle.new(
pane_headers: true, cards: true, tabs_in_header: true,
opacity: 0.85, unfocused_opacity: 0.7)
end
protected def on_window(window : DesktopKit::Window) : Nil
window.subtitle = System.hostname
window.pack_end(DesktopKit::Action::ToggleCommandPalette.new, "system-search-symbolic", "Commands")
window.background_blur = true
end
end
The surface widget carries the CSS class surface, plus active on each tab's active surface; the pane header is .surface-header. A float carries floating too and, whatever the style, shows its pane header and a framed card with a shadow. Windows carry desktop-kit-window. App#css= can restyle them.
Closing asks the user first when a surface it closes has Surface#confirm_close = true: a split, a tab, a window, all windows or the application. App#quit never asks. While any surface asks, the application also asks the desktop not to log out; App#logout_inhibited? tells whether it does.
Window#confirm and Window#prompt ask the user something in a dialog over the window. Their block runs once, after the answer; #prompt skips it when the user cancels, and neither runs it when the window closes first. Both take confirm: and cancel: button labels; destructive: true shows the confirm button in red and makes cancel the default; text: is the prompt's initial text.
window.confirm("Discard Changes?", "The draft will be lost.", confirm: "Discard", destructive: true) do |discard|
draft.clear if discard
end
window.prompt("Rename Session", text: session.name) { |name| session.name = name }
An DesktopKit::Icon is a themed icon name (String, such as "utilities-terminal") or the Path of an image file:
surface.icon = Path["/usr/share/pixmaps/editor.png"]
window.pack_start(OpenSettings.new, "emblem-system-symbolic", "Settings")
Panels
App#new_panel opens a window that the desktop docks to a screen edge, shows as the wallpaper or floats above other windows, like kitty's panel kitten: a quick terminal, a status bar, a desktop widget. Panels have tabs and splits like other windows, but no header bar or decorations. They need a Wayland compositor with the wlr layer shell protocol, such as sway, KDE Plasma, Hyprland or niri; GNOME has none, and App#panels? is then false.
quick = DesktopKit::Panel.new(edge: :top, height: 400, layer: :overlay,
focus: :on_demand, hide_on_focus_loss: true, name: "quick")
app.new_panel(quick, shown: false)
app.bindings = [DesktopKit::Binding.new("super+grave", DesktopKit::Action::TogglePanel.new("quick"), global: true)]
DesktopKit::IPC.send(app_id, DesktopKit::Action::TogglePanel.new("quick")) toggles it from another process. Window#panel= moves and resizes an open panel; Window#panel is nil for ordinary windows. App#outputs lists the monitors' names for output.
Panel field |
default | meaning |
|---|---|---|
edge |
:top |
where it sits; see below |
layer |
:bottom |
:background, :bottom, :top or :overlay, from the bottom up; edge: :background forces :background |
width, height |
0 |
logical pixels; 0 takes the content's natural size, which is also the minimum |
margin_top, margin_right, margin_bottom, margin_left |
0 |
logical pixels, on the edges the panel touches only |
output |
nil |
monitor name, such as "DP-1"; nil lets the compositor choose |
focus |
:not_allowed |
keyboard focus: :not_allowed, :exclusive (always, as the desktop permits) or :on_demand (on click) |
exclusive_zone |
nil |
pixels other windows and panels keep clear of; see below |
hide_on_focus_loss |
false |
hides the panel when it loses the focus; implies focus: :on_demand |
name |
"desktop-kit-panel" |
layer namespace, for TogglePanel and compositor rules |
edge |
placement | size from |
|---|---|---|
:top, :bottom |
along the edge, full width | height |
:left, :right |
along the edge, full height | width |
:background |
whole monitor, below every window | — |
:center |
whole monitor less the margins | — |
:center_sized |
centered; margins have no effect | width, height |
:none |
top left corner, offset by the top and left margins | width, height |
An edge panel reserves its own thickness by default, so maximized windows and other panels stay clear of it; other panels take -1 by default and cover what others reserve. An explicit exclusive_zone overrides both (not for :background): 0 reserves nothing but stays clear of others' zones, -1 covers them. Window#shortcuts_inhibited= lets a focused panel take the desktop's own shortcuts, like kitty's --grab-keyboard.
Preferences
DesktopKit::Preferences builds a preferences dialog from pages of groups of rows. Each row edits one value and passes every change to its block:
| Row | Value | Edits it with |
|---|---|---|
switch(title, subtitle:, value:) |
Bool |
a switch |
entry(title, value:) |
String |
a text entry |
spin(title, subtitle:, value:, range:, step:, digits:) |
Float64 |
a spin button, step 1 and digits 0 by default |
choice(title, options, subtitle:, selected:) |
Int32 |
a drop-down of options, the index of the chosen one |
Preferences#page(title, icon:) and Page#group(title, description:) yield the page or group to fill. #present(window) shows the dialog over window (on the GTK thread), closing an earlier one; the rows keep their values, so the dialog shows the latest ones when presented again. #close closes it and #open? tells whether it is shown. choice raises ArgumentError without options and IndexError when selected lies outside them.
prefs = DesktopKit::Preferences.new("Preferences")
prefs.page("General", icon: "preferences-system-symbolic") do |page|
page.group("Appearance", description: "How windows look") do |group|
group.switch("Pane headers", value: true) { |on| app.window_style = DesktopKit::WindowStyle.new(pane_headers: on) }
group.spin("Opacity", value: 1.0, range: 0.2..1.0, step: 0.05, digits: 2) { |value| settings.opacity = value }
group.choice("Colours", ["System", "Light", "Dark"]) { |index| settings.scheme = index }
end
page.group("Session") do |group|
group.entry("Name", value: settings.name) { |name| settings.name = name }
end
end
prefs.present(window)
ToggleCommandPalette opens a search over the application's commands, App#commands, with the shortcut of each; Enter or a click performs the selected one on the window, Up and Down move the selection and Escape closes it. An DesktopKit::Command has a title, an action and an optional description that the search also matches. DesktopKit::Command.defaults lists the built-in actions that need no input, and is the set until App#commands= replaces it:
app.commands = DesktopKit::Command.defaults + [
DesktopKit::Command.new("Open Settings", OpenSettings.new, "preferences"),
]
Titles: a surface has a #title, set by the application, and a #title_override, set by the user through PromptTitle. A tab shows its #title_override, else the title of its focused surface, else the application name, marked with 🔍 while zoomed and with 🔔 while one of its surfaces rings. A window shows its #title_override, else the title of its selected tab. Assigning nil to an override restores the default.
Window extras work on Wayland and do nothing elsewhere. Decoration::Auto uses the compositor's preference where it tells one (KDE's server decoration protocol), else client-side decorations; Server falls back to Client without that protocol, and None hides them: the window then has square corners, no outline and no shadow. ToggleWindowDecorations switches between None and the previous choice. Blur needs a compositor with ext-background-effect-v1; the region follows the window's rounded corners. Urgency uses xdg-activation-v1: a ringing bell in an inactive window makes it urgent, and activating the window clears it.
Drag and drop: hovering a split shows a handle at its top; dragging it, or the pane header, onto another surface, in any tab or window, moves it there, beside the edge nearest to the pointer. Files and text dropped on a surface go to Content#on_drop:
class Editor < DesktopKit::WidgetContent
protected def on_drop(files : Array(Path)) : Bool
files.each { |file| open_file(file) }
true
end
protected def on_drop(text : String) : Bool
insert(text)
true
end
end
Search: the search bar sits in a corner of the pane (top right at first; dragging it moves it to the nearest corner) with an entry, the match count, previous and next buttons and a close button. Return selects the next match, Shift+Return the previous one, Escape closes it. The content does the searching:
class Editor < DesktopKit::WidgetContent
protected def on_search(needle : String) : Nil
@matches = find_all(needle)
surface.search_total = needle.empty? ? nil : @matches.size
surface.search_selected = @matches.empty? ? nil : 0
end
protected def on_search_navigate(forward : Bool) : Nil
select_match(forward ? 1 : -1)
end
protected def on_search_end : Nil
clear_highlights
end
end
Bell
Surface#ring_bell does what the DesktopKit::Bell flags in App#bell say; the default is System | Attention | Title:
| Flag | Effect |
|---|---|
System |
beeps through the display server |
Audio |
plays App#bell_sound at App#bell_volume (0 to 1, 0.5 by default) |
Attention |
the tab needs attention while not selected; an inactive window turns urgent |
Title |
marks the tab title with 🔔 |
Border |
draws a border around the surface |
Ringing an unfocused surface sets Surface#bell_ringing? and its marks until it gets the focus; a focused surface only beeps and plays the sound. A sound file that cannot play is logged as a warning.
Canvas
DesktopKit::Canvas is a Content that draws with OpenGL. Subclass it, implement #on_render and override the input hooks you need; each #new_surface call returns a new canvas.
class Scene < DesktopKit::Canvas
def initialize
super(api: :gl, version: {3, 3})
end
protected def on_render : Nil
# draw into the bound framebuffer: width × height pixels
end
protected def on_key(event : DesktopKit::KeyEvent) : Bool
return false unless event.pressed?
puts event.text || event.keyval
queue_render
true
end
end
.new(*, api, version, depth_buffer, stencil_buffer, input_purpose, offload, threaded) sets the GL context and framebuffer: api is Canvas::API::GL, GLES or both (the default), version the least {major, minor}, and the framebuffer gets a 24-bit depth and 8-bit stencil buffer when either is asked for. input_purpose (Canvas::InputPurpose, FreeForm by default; Terminal for keys that go to a program) tells input methods and on-screen keyboards what text the canvas takes. The GL context is current in #on_realize, #on_render, #on_resize and #on_unrealize; #api is the flavour GTK made, and #error the reason when it made none. Moving a canvas, such as into a split, unrealizes and realizes it again, so #on_realize must recreate GL objects. The canvas draws a frame when it is shown, resized or rescaled, and after #queue_render; call that after a change.
offload: true hands frames to GTK as DMA-BUFs where the GL driver can export them (EGL with EGL_MESA_image_dma_buf_export, as on Mesa), and puts the frame in a GtkGraphicsOffload, so the compositor may show it on a subsurface without GTK copying it. Elsewhere, or when GTK refuses the buffer's format, frames go as GL textures, as without the option. #dmabuf? tells whether the last frame went as a DMA-BUF.
threaded: true draws on a thread of the canvas's own, so a slow frame never stalls the GTK thread: #on_realize, #on_resize, #on_render and #on_unrealize run there and must not call GTK; #queue_render may be called from either thread, and #threaded? tells the mode. The thread draws one frame at a time; GTK keeps showing the previous frame until it finishes. Share state between the hooks and the input hooks (still on the GTK thread) under a lock, or hand it over with App#post and a Channel.
threaded: thread, a RenderThread, draws several canvases on one thread with one GL context, so programs, textures and caches made in one canvas's hooks serve every canvas of the thread. The canvases draw one after another; GL state one hook leaves is what the next finds. The thread starts with the first realized canvas and ends with the last one unrealized. RenderThread.new(*, api, version, name) picks the context as Canvas.new does; the canvases' own api and version are not used. Canvas#render_thread returns the thread of a threaded canvas.
thread = DesktopKit::RenderThread.new(version: {4, 3}, name: "terminal")
left = MyCanvas.new(threaded: thread)
right = MyCanvas.new(threaded: thread)
Each frame goes to a framebuffer of exactly the canvas's size at the output's scale, fractional scales included (#scale is a Float64 such as 1.5), with the GL origin at the bottom left. The canvas keeps several framebuffers: #buffer_age tells, during #on_render, how many frames ago the bound one was last drawn, or 0 when its contents are undefined, so a canvas can redraw only what changed since then. #frame numbers the frame drawn last, and #on_presented(timing) reports when the display showed a frame: an DesktopKit::FrameTiming with frame, presented (a Time::Span on CLOCK_MONOTONIC) and refresh_interval, both nil when the compositor does not tell.
DesktopKit::GLContext.new(api:, version:) makes a context for drawing off screen, for example into textures, with no canvas; it shares objects with every canvas of the display. #make_current, #current?, #api and GLContext.clear_current manage it; Canvas#gl_context is a canvas's own, nil while it is unrealized. Make contexts on the GTK thread; a context is current on one thread at a time.
| Hook | Called |
|---|---|
on_realize, on_unrealize |
after the GL context is made, before it goes |
on_render |
to draw a frame |
on_resize(width, height) |
when the framebuffer size changes |
on_presented(timing) |
when the display showed a frame |
on_key(event) : Bool |
for a key press or release; true when used, else GTK passes the key on |
on_preedit(text), on_commit(text) |
input method composition text (nil ends it), finished text |
on_focus(focused) |
when the canvas gains or loses the keyboard focus |
on_mouse_button(event) |
for a button press or release; a press focuses the canvas |
on_mouse_enter(event), on_mouse_motion(event), on_mouse_leave |
when the pointer enters the canvas, while it moves over it, when it leaves |
on_scroll(event) |
for a wheel step or a touchpad scroll |
Sizes and positions are framebuffer pixels: #width, #height, event coordinates and precise scroll deltas are logical units times #scale. Call #ime_cursor(x, y, width, height) with the text cursor's rectangle in framebuffer pixels so the input method places its popup there.
DesktopKit::KeyEvent holds pressed?, repeat? (a press of a key already down, as keyboard repeat sends), keyval (a GDK keysym), keycode, key (the physical key, an DesktopKit::Key), layout (the index of the keyboard layout in use), mods (the modifiers held, counting a modifier key in its own press but not in its release), consumed_mods (the modifiers the layout used to make the key), text (what a press types, nil for a release or a non-text key), unshifted and shifted (the characters of the key without modifiers and with Shift alone), base (its character without modifiers in the first layout, for bindings across layouts), caps_lock?, num_lock?, modifier? and composing? (the input method is composing). A key the input method uses for a composition reaches #on_key with composing? = true; text it finishes comes through #on_commit, or as the event's text when one key finishes it. Using a key while composing ends the composition. DesktopKit::MouseButtonEvent holds pressed?, button (Left, Middle, Right, Back, Forward; other buttons keep their number), x, y, mods and time (milliseconds of the display's clock, for double clicks); DesktopKit::MouseMotionEvent holds x, y, mods and time; DesktopKit::ScrollEvent holds dx, dy, precise? (pixel deltas from a touchpad rather than wheel steps) and mods.
Canvas drag and drop
A canvas can take drags by MIME type and start its own. These hooks come on top of Content#on_drop, which still gets the drags the canvas refuses:
| Hook | Called |
|---|---|
on_drop_accept(drop) : Bool |
when a drag enters; true takes part in it (default false) |
on_drop_motion(drop, x, y) : DragAction |
as it enters and moves; the action a drop there would perform (default Copy when allowed) |
on_drop_leave(drop) |
when it leaves without dropping |
on_drop(drop, x, y) : Bool |
when it drops; true takes the drop (default false) |
on_drag_end(drag, action) |
when a drag from #drag ends; None when cancelled |
An DesktopKit::Drop offers mime_types, actions (the DesktopKit::DragAction flags Copy, Move, Link its source allows) and local? (a drag from this application). Once on_drop returned true, read(mime_type) { |bytes| } fetches the data (nil when it is not offered) and finish(action) ends the drop, DragAction::None reporting a failure.
#drag(mime_types, actions = :copy, icon = nil) { |request| } starts a drag with the pointer; call it while a button is held. It returns the DesktopKit::Drag (its mime_types and the action the target under the pointer would perform), or nil while the canvas is not on screen. The data is produced on demand: the block gets an DesktopKit::Drag::Request for each MIME type a target asks for and answers it once with reply(bytes) or fail, now or later. An DesktopKit::Drag::Icon holds straight RGBA pixels and the pointer's spot on them; icon= on the drag changes it while the drag runs. #cancel_drag cancels the running drag.
protected def on_drop_accept(drop : DesktopKit::Drop) : Bool
drop.mime_types.includes?("text/uri-list")
end
protected def on_drop(drop : DesktopKit::Drop, x : Float64, y : Float64) : Bool
drop.read("text/uri-list") do |bytes|
open_uris(String.new(bytes)) if bytes
drop.finish(bytes ? DesktopKit::DragAction::Copy : DesktopKit::DragAction::None)
end
true
end
protected def on_mouse_motion(event : DesktopKit::MouseMotionEvent) : Nil
return unless @pressed_on_link
drag(["text/uri-list", "text/plain;charset=utf-8"]) { |request| request.reply(@link.to_slice) }
@pressed_on_link = false
end
DesktopKit::Key names a key by its position on a US keyboard, whatever the layout, with the W3C UI Events code names: KeyA is the key right of Caps Lock even where it types q. Use it for bindings that follow the keyboard's shape, such as WASD movement; keyval and text follow the layout. Keys the table does not know are Unidentified.
protected def on_key(event : DesktopKit::KeyEvent) : Bool
case event.key
when .key_w? then move(:up)
when .key_s? then move(:down)
else return false
end
true
end
Clipboard
DesktopKit::Clipboard.write(text, kind = :standard) puts text on a clipboard; .read(kind = :standard) { |text| } yields its text later, or nil when it holds none. kind is Standard (copy and paste) or Primary (the selection, pasted by middle-click). Use them on the GTK thread only.
Other data travels by MIME type:
.write(items, kind = :standard)puts{mime_type, bytes}pairs on a clipboard; each reader picks the type it wants. Empty items clear it..offered(kind = :standard)returns the MIME types a clipboard offers..read(mime_type, kind = :standard) { |bytes| }yields the data of one type later, ornilwhen the clipboard does not offer it..items(kind = :standard)returns the items this application last wrote, while it still owns the clipboard;nilotherwise.
DesktopKit::Clipboard.write([{"text/html", html.to_slice}, {"text/plain;charset=utf-8", text.to_slice}])
if DesktopKit::Clipboard.offered.includes?("text/html")
DesktopKit::Clipboard.read("text/html") { |bytes| paste(bytes) if bytes }
end
Surface#confirm_clipboard(request, text) { |allowed| } asks before a clipboard access: Clipboard::Request::Paste warns about pasting text, Read and Write ask to let the content read or write the clipboard, and show text. The block gets true when the user allows it, and false right away for a closed surface.
Notifications
Surface#notify(title, body) shows a desktop notification; clicking it presents the surface. App#notify(title, body) shows one from the application, which clicking does not act on. An empty title shows the application name. Sending the same title and body again replaces the notification instead of adding one. A surface withdraws its notifications once it gets the focus or closes, and one sent while it is focused after a few seconds. Use them on the GTK thread only; GIO hands them to the desktop's notification service.
Actions
Everything the runtime does on request is an action: a typed value that menus, buttons, key bindings and other processes trigger through GTK's action system. DesktopKit::App#perform carries actions out, with one overload per action type. Its target is the DesktopKit::App for app actions, the DesktopKit::Window for window actions, the DesktopKit::Tab for tab actions and the DesktopKit::Surface for split actions; a window triggers its tab and split actions on its selected tab and that tab's focused surface.
Declare an action with DesktopKit.action; the payload becomes the struct's constructor arguments and getters:
DesktopKit.action Refresh, "refresh", payload: {force: Bool}
DesktopKit.action Zoom, "zoom", scope: :split, payload: {step: Step} do
enum Step
In
Out
end
end
class Viewer < DesktopKit::App
protected def perform(target : DesktopKit::App, action : Refresh) : Bool
puts "refreshing, force: #{action.force}"
true
end
end
| Option | Meaning |
|---|---|
| name | the struct, here Refresh |
| gname | the action name: letters, digits, - and ., unique per scope |
scope: |
:app (default), :window, :tab or :split |
payload: |
named fields of types DesktopKit::Variant carries; flags enums are not |
ipc: |
whether DesktopKit::IPC.send may send it; :app actions only |
| block | definitions added to the struct, such as its payload enums |
perform returns whether it handled the action; actions nobody handles are logged as warnings. Redefine a built-in overload, such as perform(target : DesktopKit::App, action : DesktopKit::Action::Quit), to change what it does, and call super to keep the default.
Each action has a detailed name, #detailed_name, in the GTK format <prefix>.<name>[::<string> or (<parameter>)]. The prefix is app, win, tab or split by scope, so DesktopKit::Action::NewSplit.new(:right) is split.new-split::right. Buttons and menus trigger an action through its detailed name.
Built-in actions, all nested in DesktopKit::Action:
| Scope | Actions (payload) |
|---|---|
app |
Quit, NewWindow (ipc), CloseAllWindows, ReloadConfig, PresentSurface(surface_id : UInt64) (ipc), DesktopNotification(title, body : String), OpenUrl(url : String), ToggleVisibility, TogglePanel(panel : String) (ipc), ShowGtkInspector, Undo, Redo |
window |
CloseWindow, ToggleMaximize, ToggleFullscreen, ToggleWindowDecorations, ToggleTabOverview, ToggleCommandPalette, ShowShortcuts, GotoWindow(direction : Previous/Next), SetWindowTitle(title), InitialSize(width, height), SizeLimit(min_width, min_height, max_width, max_height), ResizeWindow(width, height), SetWindowTheme(appearance), NewTab, GotoTab(index), ResetWindowSize, ToggleBackgroundOpacity, ActivateKeyTable(table : String), ActivateKeyTableOnce(table : String), DeactivateKeyTable, DeactivateAllKeyTables |
tab |
CloseTab(mode : This/Other/Right), MoveTab(amount : Int32), MoveTabToNewWindow, SetTabTitle(title) |
split |
NewSplit(direction), GotoSplit(direction : Previous/Next/Left/Right/Up/Down), SwapSplit(direction : Previous/Next/Left/Right/Up/Down/First), MoveSurfaceToNewWindow, MoveSurfaceToPreviousWindow, ResizeSplit(direction, amount : UInt32), EqualizeSplits, ToggleSplitZoom, ToggleFloat, MoveFloat(direction, amount : UInt32), StackInto(direction), Unstack(layout : Auto/Horizontal/Vertical), GotoStacked(index), CloseSurface, SetTitle(title), PromptTitle(kind : Surface/Tab/Window), RingBell, MouseVisibility(visible : Bool), CopyTitleToClipboard, ToggleReadOnly, ShowOnScreenKeyboard, StartSearch, EndSearch, Search(needle), NavigateSearch(direction : Previous/Next) |
Sizes are UInt32 pixels. SizeLimit sets the smallest window size and treats 0 as no limit; GTK 4 windows have no largest size, so its maximum is ignored. ResizeWindow sizes the window so that its surface gets the size, only while the window shows one surface and is neither maximized nor fullscreen. A window that is not on screen yet opens at that size. SetWindowTheme sets the appearance of the whole application. ToggleFloat floats the focused split over its tab, or splits a float back in; MoveFloat moves a float by amount pixels, stopping at the tab's edges. ResizeSplit moves the divider of the nearest split along direction's axis; on a float it grows it to the right or down and shrinks it to the left or up, its top-left corner kept. Surface#grows?(direction) tells whether that makes the surface larger. GotoTab counts from 0 and also takes GotoTab::PREVIOUS, NEXT and LAST; previous and next wrap around, as MoveTab does. GotoStacked counts the same way within the focused surface's stack. ResetWindowSize returns a window that is neither maximized nor fullscreen to its InitialSize, 800x600 by default. ToggleBackgroundOpacity makes a window opaque and back while the WindowStyle opacity is below 1. ToggleVisibility hides every window when any is shown and shows them all otherwise; TogglePanel does the same for the panels whose Panel#name it names. ShowGtkInspector opens GTK's interactive debugger. CopyTitleToClipboard copies the surface's shown title. PresentSurface presents the surface with that Surface#id and ignores an unknown one; DesktopNotification is App#notify. OpenUrl opens the URL with the desktop's default handler through the OpenURI portal, and with xdg-open when no portal answers or the request fails; file paths and file:// URLs always go to xdg-open. A request the user cancels opens nothing. direction is an DesktopKit::Direction (Left, Right, Up, Down) unless the action lists its own values.
Key bindings
DesktopKit::App#bindings= sets the key bindings, callable from any thread and replacing the previous set:
app.bindings = [
DesktopKit::Binding.new("ctrl+q", DesktopKit::Action::Quit.new),
DesktopKit::Binding.new("ctrl+shift+e", DesktopKit::Action::NewSplit.new(:right)),
DesktopKit::Binding.new("ctrl+a>n", DesktopKit::Action::NewTab.new),
DesktopKit::Binding.new("super+grave", DesktopKit::Action::NewWindow.new, global: true),
]
Bindings become GTK accelerators: app actions work in every window, the others act on the focused window, tab or split. A trigger bound twice keeps its first binding.
A sequence joins triggers with >: "ctrl+a>n" performs its action when n follows ctrl+a. After each trigger of a sequence the window takes the next key; modifier keys alone do not count, and a key that continues no sequence ends it and is dropped. A single trigger that starts a sequence is ignored with a warning. > stays a key at the start of a trigger or after +, as in "ctrl+>" or "a>>". Binding#triggers lists the triggers, #sequence? tells whether there are several, #label joins their labels with spaces ("Ctrl+A N") and #to_s gives back the text. Sequences cannot be global. A pending sequence waits for its next key until App#sequence_timeout passes; nil, the default, waits indefinitely.
App#key_tables= sets named key tables, modes that lay their own bindings over the window's while active:
app.key_tables = {
"resize" => [
DesktopKit::Binding.new("h", DesktopKit::Action::ResizeSplit.new(:left, 20)),
DesktopKit::Binding.new("l", DesktopKit::Action::ResizeSplit.new(:right, 20)),
DesktopKit::Binding.new("esc", DesktopKit::Action::DeactivateKeyTable.new),
],
}
app.bindings = [DesktopKit::Binding.new("ctrl+r", DesktopKit::Action::ActivateKeyTable.new("resize"))]
ActivateKeyTable pushes a table onto the window's stack, up to eight deep; an unknown table or the one already innermost is ignored. ActivateKeyTableOnce pops it again after its first binding performs. DeactivateKeyTable pops the innermost table and DeactivateAllKeyTables all of them. A pending sequence comes first, then the tables from the innermost out, then the bindings; keys no table binds pass through to the content. Tables take single keys and sequences but no global bindings, which raise ArgumentError. While a table or a sequence is active the window shows them in its bottom corner (resize › Ctrl+A).
global: true marks a binding that works while the application is not focused. Global bindings go to the desktop's global shortcuts portal (org.freedesktop.portal.GlobalShortcuts), which may ask the user to confirm them; the action then acts on the active window, tab or split, like a key binding. The portal identifies the application by its id, which must match the basename of an installed .desktop file, or by the systemd scope the desktop launched it in. The on_binding_failed hook receives each global binding the desktop does not bind and the reason; by default it logs a warning. Desktops without the portal fail every global binding.
DesktopKit::Trigger.parse reads a trigger: modifiers and a key joined by +.
| Part | Accepted |
|---|---|
| modifiers | shift, ctrl (control), alt (opt, option), super (cmd, command), any case, once each |
| key | a single character (t, €, + as in ctrl++) |
enter (return), esc, tab, space, backspace, delete (del), insert, home, end, page_up (pageup), page_down (pagedown), up, down, left, right (arrow_*), f1 to f24, any case |
|
a GDK key name, exact case, such as KP_Enter or grave |
Triggers that cannot be shortcuts, such as a modifier key alone or a character without a key symbol, raise ArgumentError. A trigger converts to its GTK accelerator (#to_gtk_accel, "<Shift><Control>t"), its XDG shortcut (#to_xdg, "SHIFT+CTRL+t", as global shortcut portals expect), a label for the user (#label, "Shift+Ctrl+T") and back to text (#to_s, "shift+ctrl+t").
ShowShortcuts opens a dialog over the window listing every binding, grouped by the scope of its action, then each key table. A binding's title is that of the command in App#commands with the same action, else the action name in words; the dialog's search matches the titles.
Translation
DesktopKit.translator= sets the function that translates desktop_kit's own texts: labels, tooltips, dialog texts and the titles of Command.defaults and Menu.window. It receives the English text and returns the one to show; the default returns it unchanged, and a translator that raises keeps the English text. Set it before creating the application, as the default commands and window menu are built then:
GERMAN = {"Quit" => "Beenden", "New Tab" => "Neuer Tab"}
DesktopKit.translator = ->(text : String) { GERMAN[text]? || text }
Texts the application passes, such as its own command titles or the title: of Window#open_file, are shown as given. The texts desktop_kit translates:
| Text |
|---|
| Allow |
| An application is attempting to read from the clipboard. The current clipboard contents are shown below. |
| An application is attempting to write to the clipboard. The text it would copy is shown below. |
| Application |
| Authorize Clipboard Access |
| Cancel |
| Change Surface Title |
| Change Tab Title |
| Change Tab Title… |
| Change Title |
| Change Title… |
| Change Window Title |
| Change Window Title… |
| Close |
| Close All Windows |
| Close All Windows? |
| Close Other Tabs |
| Close Split |
| Close Split? |
| Close Tab |
| Close Tab? |
| Close Tabs to the Right |
| Close Window |
| Close Window? |
| Command Palette |
| Configuration Errors |
| Copy Title |
| Deny |
| End Search |
| Equalize Splits |
| Find… |
| Focus Next Split |
| Focus Previous Split |
| GTK Inspector |
| Global shortcut |
| Hide All Windows |
| Ignore |
| Key table |
| Keyboard Shortcuts |
| Leave blank to restore the default title. |
| Main Menu |
| Move Split to New Window |
| Move Split to Previous Window |
| Move Tab to New Window |
| New Tab |
| New Window |
| Next Match |
| Next Tab |
| OK |
| One or more configuration errors were found. Please review the errors below, and either reload your configuration or ignore these errors. |
| Open File |
| Open Files |
| Pasting this text may be dangerous as it looks like some commands may be executed. |
| Preferences |
| Previous Match |
| Previous Tab |
| Quit |
| Quit? |
| Read-only |
| Redo Close |
| Reload Configuration |
| Reset Window Size |
| Save File |
| Select Color |
| Select Folder |
| Select Font |
| Show Next Stacked Split |
| Show On-Screen Keyboard |
| Show Previous Stacked Split |
| Some windows ask before closing |
| Split |
| Split Down |
| Split Left |
| Split Right |
| Split Up |
| Stack With Left Split |
| Stack With Right Split |
| Stack With Split Above |
| Stack With Split Below |
| Swap With Next Split |
| Swap With Previous Split |
| Tab |
| Tab Overview |
| Toggle Background Opacity |
| Toggle Floating Split |
| Toggle Fullscreen |
| Toggle Maximize |
| Toggle Read-Only |
| Toggle Split Zoom |
| Toggle Window Decorations |
| Undo Close |
| Unsaved work in this split will be lost. |
| Unsaved work in this tab will be lost. |
| Unsaved work in this window will be lost. |
| Unsaved work will be lost. |
| Unstack Split |
| View Open Tabs |
| Warning: Potentially Unsafe Paste |
| Window |
| Zoom Split |
IPC
DesktopKit::IPC.send(app_id, action) triggers an ipc: true action in the running single instance of the application app_id, such as DesktopKit::Action::NewWindow; other actions fail to compile. It blocks until the application answers and raises DesktopKit::GLibError when none runs, and ArgumentError for an invalid id. Call it from another process, or from a thread other than the target application's GTK thread:
DesktopKit::IPC.send("org.example.Hello", DesktopKit::Action::NewWindow.new)
Only ipc: true actions are exported on the session bus; other processes calling any other action get an error. Inside the application every action works as usual.
Tray icon
App#tray= shows an DesktopKit::Tray in the desktop's system tray while the application runs; nil removes it. Assigning a new one updates the shown icon, title, tooltip and menu. Callable from any thread.
| Field | Type | Meaning |
|---|---|---|
icon |
String |
icon name from the icon theme |
title |
String |
name of the item, shown in its tooltip |
tooltip |
String? |
tooltip text below the title |
menu |
Menu? |
menu shown on click; a Menu like the header menu's |
activate |
Action? |
performed on a primary click; without it a primary click shows the menu |
Actions run as if performed in the active window. The tray shows through a StatusNotifierItem host, such as KDE Plasma's or GNOME's AppIndicator extension; without a host nothing shows. With quit_delay = nil the application keeps running with only its tray icon.
app.tray = DesktopKit::Tray.new(icon: "mail-unread-symbolic", title: "Mail", tooltip: "3 new",
menu: DesktopKit::Menu.build { |menu|
menu.item "New Window", DesktopKit::Action::NewWindow.new
menu.section
menu.item "Quit", DesktopKit::Action::Quit.new
},
activate: DesktopKit::Action::NewWindow.new)
D-Bus
DesktopKit::DBus is a message bus connection: DBus.session, DBus.system or App#dbus (the running application's own, nil before it registers). Arguments and replies are tuple Variants.
| Method | Does |
|---|---|
#call(destination, path, interface, method, args = nil, reply_type:, timeout:, auto_start:) { |reply, error| } |
calls a method; the block gets the reply tuple or a GLibError, on the calling thread's main loop |
#call_sync(...) |
the same, waiting; returns the reply, raises GLibError |
#emit(path, interface, member, args = nil, destination:) |
emits a signal |
#subscribe(sender:, interface:, member:, path:, arg0:) { |signal| } |
yields each matching DBus::Signal (sender, path, interface, member, args) until Subscription#cancel |
#unique_name |
the connection's unique name (":1.42") |
Use #call and #subscribe on the GTK thread; #call_sync and #emit work anywhere. Arguments that are not a tuple raise ArgumentError.
bus = app.dbus.not_nil!
bus.subscribe(interface: "org.freedesktop.Notifications", member: "ActionInvoked") do |signal|
puts "#{signal.args[0].get(UInt32)}: #{signal.args[1].get(String)}"
end
Configuration reload
App#reload, SIGUSR2 and the ReloadConfig action call on_reload, where the application rereads its configuration and applies what lives on the app, such as #css=, #appearance= and #bindings=. Then each surface's content gets Content#on_reload; an exception there is logged and the other contents still reload. Under systemd the reload runs between RELOADING=1 and READY=1.
systemd
Under systemd (Type=notify or Type=notify-reload), the application reports READY=1 after its first activation, RELOADING=1 around each reload and STOPPING=1 when it quits. DesktopKit::Systemd.notify(state) sends other states, such as "STATUS=Indexing", and returns false outside systemd.
DesktopKit::Systemd.start_scope moves a child process into its own transient scope of the user's service manager, so that systemd accounts, limits and kills it apart from the application:
process = Process.new("make")
unit = "app-#{app.id}-transient-#{process.pid}.scope"
DesktopKit::Systemd.start_scope(process.pid, unit, memory_high: 4_u64 << 30, tasks_max: 512_u64, oom_kill: true)
It returns once the process is in the scope, or false after timeout (250 ms), and raises DesktopKit::GLibError when the session bus or the service manager refuses.
Variants
DesktopKit::Variant is an immutable GLib GVariant, the value type of action parameters, DBus messages and portal options. Values convert by their Crystal type:
| Crystal | GVariant |
|---|---|
Bool |
b |
Int32, UInt32 |
i, u |
Int64, UInt64 |
x, t |
Float64 |
d |
String |
s |
DesktopKit::Variant::ObjectPath |
o |
enum (not @[Flags]) |
s, the member name in snake case |
DesktopKit::Variant |
v |
T? |
mT |
Array(T) |
aT |
Hash(K, V) |
a{KV} |
Tuple(T, U, ...) |
(TU...) |
options = DesktopKit::Variant.new({"modal" => DesktopKit::Variant.new(true)})
options.type_string # => "a{sv}"
options["modal"]?.try(&.get(Bool)) # => true
DesktopKit::Variant.parse("(1, 'a')").get(Tuple(Int32, String)) # => {1, "a"}
DesktopKit::Variant.signature(Array(String)) # => "as"
#get raises TypeCastError when the variant holds another type; .parse raises DesktopKit::GLibError on bad input.
Widgets
DesktopKit::Widget is a borrowed handle to a GTK widget: size, scale, visibility, focus, cursor, tooltip and CSS classes. It holds no reference; GTK's widget tree owns the widget. Use it on the GTK thread only.
Errors
DesktopKit::GLibError carries the GLib error domain (#domain, a string such as "g-io-error-quark") and #code.
Exceptions raised inside callbacks that GTK runs are logged to the "desktop_kit" Log source instead of crossing into C.
License
MIT; see LICENSE, which also holds the notices of third-party code included here.
desktop_kit
- 0
- 0
- 0
- 0
- 0
- 10 minutes ago
- November 12, 2026
Other
Sat, 21 Nov 2026 09:05:40 GMT