developing-gtk-apps

| Task | Use |

|------|-----|

| Which widget for settings? | designing-gnome-ui |

| How to structure preferences window? | designing-gnome-ui |

| App crashes on startup | THIS SKILL |

| UI freezes during operation | THIS SKILL |

| How to save user preferences | THIS SKILL (GSettings) |

| Signal not firing/memory leak | THIS SKILL |

| Setting up new app boilerplate | THIS SKILL |

| Packaging for Flatpak | THIS SKILL |

API deprecations to avoid:

• GtkShortcutsWindow → Use AdwShortcutsDialog (libadwaita 1.8+)
• .dim-label CSS class → Use .dimmed class
• X11/Broadway backends are deprecated in GTK 4 (removal planned for GTK 5)

New patterns (libadwaita 1.6-1.8):

• AdwSpinner - Preferred over GtkSpinner
• AdwToggleGroup - Replaces multiple exclusive GtkToggleButton instances
• AdwBottomSheet - Persistent bottom sheets
• AdwWrapBox - Box that wraps children to new lines
• AdwInlineViewSwitcher - For cards, sidebars, boxed lists

```python

import gi

gi.require_version('Gtk', '4.0')

gi.require_version('Adw', '1')

from gi.repository import Gtk, Adw, Gio

class MyApp(Adw.Application):

def __init__(self):

super().__init__(

application_id="com.example.MyApp",

flags=Gio.ApplicationFlags.DEFAULT_FLAGS

)

def do_activate(self):

win = self.props.active_window

if not win:

win = MyWindow(application=self)

win.present()

class MyWindow(Adw.ApplicationWindow):

def __init__(self, **kwargs):

super().__init__(**kwargs)

self.set_default_size(800, 600)

def main():

app = MyApp()

return app.run(None)

```

Application ID Rules

| Rule | Example |

|------|---------|

| Reverse domain notation | com.example.AppName |

| Only alphanumeric + dots | org.gnome.TextEditor |

| Min 2 segments | com.myapp (not myapp) |

| Match desktop file | com.example.MyApp.desktop |

Lifecycle Signals

| Signal | When | Use For |

|--------|------|---------|

| startup | Once, app launches | Actions, CSS, GSettings |

| activate | Each launch/raise | Create/present window |

| shutdown | App exits | Save state, cleanup |

| open | Files passed to app | Handle file arguments |

```python

def do_startup(self):

Adw.Application.do_startup(self) # Chain up FIRST

self.setup_actions()

```

GTK is single-threaded. All UI calls MUST happen on the main thread.

```python

# WRONG - will crash

def background_task():

result = slow_computation()

self.label.set_text(result) # CRASH

# RIGHT - use GLib.idle_add

def background_task():

result = slow_computation()

GLib.idle_add(self.label.set_text, result) # Safe

threading.Thread(target=background_task).start()

```

For async patterns with Gio.Task and cancellation, see gtk-patterns-reference.md.

Actions connect UI to behavior. Define at app level (app.action) or window level (win.action).

```python

# In do_startup - app-level action

quit_action = Gio.SimpleAction.new("quit", None)

quit_action.connect("activate", lambda a, p: self.quit())

self.add_action(quit_action)

self.set_accels_for_action("app.quit", ["q"])

# In window __init__ - window-level action

save_action = Gio.SimpleAction.new("save", None)

save_action.connect("activate", self.on_save)

self.add_action(save_action)

self.get_application().set_accels_for_action("win.save", ["s"])

```

For stateful actions (toggles), parameterized actions, and menu integration, see gtk-patterns-reference.md.

Persist user preferences with GSettings. Requires a schema file.

```python

# In app __init__

self.settings = Gio.Settings.new("com.example.MyApp")

# Read/write values

dark = self.settings.get_boolean("dark-mode")

self.settings.set_boolean("dark-mode", True)

# Bind to widget property (auto-syncs)

self.settings.bind("window-width", window, "default-width",

Gio.SettingsBindFlags.DEFAULT)

# React to changes

self.settings.connect("changed::dark-mode", self.on_dark_changed)

```

For schema XML format and installation, see gtk-patterns-reference.md.

```bash

GTK_DEBUG=interactive myapp # Open GTK Inspector (Ctrl+Shift+D)

G_MESSAGES_DEBUG=all myapp # Show all debug messages

G_DEBUG=fatal-criticals myapp # Abort on critical warnings

GSETTINGS_BACKEND=memory myapp # Test without persisting settings

```

For full debugging patterns, profiling, and GDB integration, see gtk-debugging-reference.md.

• Calling UI methods from threads (use GLib.idle_add)
• Missing do_startup chain-up
• Signal handlers without disconnect on destroy
• Blocking operations in signal handlers
• Hardcoded paths instead of XDG directories
• Missing application ID or wrong format
• Using time.sleep() in main thread
• Using GtkShortcutsWindow (deprecated - use AdwShortcutsDialog)
• Using GtkSpinner for libadwaita apps (use AdwSpinner)

| Need | File |

|------|------|

| GObject classes, properties, signals, list models, property bindings, factories | gtk-gobject-reference.md |

| Actions, GSettings, Resources, Blueprint, async file ops | gtk-patterns-reference.md |

| Desktop file, AppStream metadata, Meson, Flatpak, icons, Python deps | gtk-packaging-reference.md |

| Testing with pytest, async testing, headless/CI testing | gtk-testing-reference.md |

| Internationalization, gettext, ngettext plurals, .po files, Blueprint i18n, RTL testing | gtk-i18n-reference.md |

| DBus activation, interface export, background services, Flatpak portals | gtk-dbus-reference.md |

| GTK Inspector, env vars, profiling, memory debugging | gtk-debugging-reference.md |

| UI patterns, widgets, HIG | Use designing-gnome-ui skill |

• [Blueprint docs](https://jwestman.pages.gitlab.gnome.org/blueprint-compiler/)
• [Libadwaita API](https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/)
• [GTK 4 API](https://docs.gtk.org/gtk4/)