developing-gtk-apps（开发 GTK 应用程序）

Developing GTK Apps

Build robust GTK 4/libadwaita applications with correct architecture, lifecycle, and patterns.

Core principle: Get the foundation right before the UI. Application lifecycle, threading model, and resource management are where most GTK apps break.

Relationship to UI skill: This skill handles architecture and plumbing. For widget selection, layout, and HIG compliance, use designing-gnome-ui.

Decision Flow

What's Current (libadwaita 1.7+, GTK 4.18+)

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

Application Boilerplate

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

Lifecycle Signals

def do_startup(self):
    Adw.Application.do_startup(self)  # Chain up FIRST
    self.setup_actions()

Threading - The Critical Rule

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

# 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 (Quick Reference)

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

# 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", ["<Control>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", ["<Control>s"])

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

GSettings (Quick Reference)

Persist user preferences with GSettings. Requires a schema file.

# 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.

Debugging (Quick Reference)

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.

Red Flags - STOP

• 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)

Reference Files

External References

• Blueprint docs
• Libadwaita API
• GTK 4 API