gtk4-rs

The gtk4-rs repository provides complete Rust bindings for GTK 4. It is organized into several core crates that handle different layers of the GTK stack:

• GTK (gtk4): The main high-level widget toolkit.
• GDK (gdk4): An intermediate layer that isolates GTK from windowing system details. It includes backend-specific crates:
  • gdk4-macos: macOS backend.
  • gdk4-wayland: Wayland backend.
  • gdk4-win32: Windows backend.
  • gdk4-x11: X11 backend.
• GSK (gsk4): An intermediate layer that isolates GTK from OpenGL or Vulkan implementations.

Note that these crates depend on core libraries like glib, gio, graphene, cairo, and pango, which are maintained in the gtk-rs-core repository.

Libadwaita is a library that augments GTK 4 to help applications follow the GNOME Human Interface Guidelines (HIG).

Key features include:

• HIG-compliant widgets: Provides widgets designed specifically for the GNOME ecosystem.
• Adaptive Layouts: Widgets that allow applications to change their layout based on available space.
• Adwaita Stylesheet: Integrated support for the Adwaita look and feel.
• Runtime Recoloring: Support for changing colors at runtime using CSS variables.
• Dark Mode Support: API to handle cross-desktop dark style preferences.

When two GObjects hold strong references to each other (e.g., two buttons that modify each other's properties), a reference cycle is created. This prevents the objects from ever being deallocated.

To break these cycles, use weak references. In gtk-rs, you can use the glib::clone! macro with the @weak specifier. When the closure runs, the macro attempts to 'upgrade' the weak reference to a strong one. If the object has already been destroyed, the closure will return early (defaulting to () return value).

Properties provide a public API for accessing the state of GObjects. In gtk-rs, properties are typically accessed via generated getter and setter methods (e.g., is_active() and set_active() for a Switch's active property).

Properties can also be bound to one another using bind_property. This allows the state of one object to automatically synchronize with another. You can create a bidirectional binding using the bidirectional() method on the BindingBuilder, ensuring that changes to either object update the other.

GTK is an object-oriented framework built on top of the GObject library. Because GTK is written in C, gtk-rs provides a mapping of GObject's object-oriented features to idiomatic Rust constructs.

To use gtk-rs effectively, you should understand how the following concepts are implemented:

• Inheritance and Interfaces: Mapped to Rust traits.
• Memory Management: How GObject lifecycles interact with Rust's ownership model.
• Subclassing: How to create your own custom GObjects.
• Generic Values: How to handle GValue-based data.
• Properties: How to interact with GObject properties.
• Signals: How to emit and connect to signals for event handling.

The main event loop is a single-threaded mechanism that manages all events, such as mouse clicks, keyboard presses, and file events. It iterates rapidly between tasks to create the illusion of parallelism (e.g., allowing a window to be moved while a progress bar updates).

Warning: If a single task takes too long to execute on the main thread, the entire GUI will become unresponsive and frozen.

To keep the UI responsive, choose your execution strategy based on the nature of the task:

CPU-bound tasks

If the task involves heavy calculations, run it in a separate thread and communicate results back to the main thread via a channel.

IO-bound tasks

• Light I/O: If the library uses glib, smol, async-std, or only the futures trait family, you can use glib::spawn_future_local to run it directly on the main loop. This often avoids the need for complex synchronization.
• Heavy I/O: If the work is intensive, run it in a separate thread or an async executor to avoid saturating the main loop.
• Tokio-dependent libraries: If the library requires tokio (e.g., reqwest), you must spawn the task using a tokio::runtime::Runtime and communicate back to the main thread via a channel.

GTK's Default stylesheet provides pre-defined, named colors for common UI scenarios (e.g., success, error, warning).

To use these exported colors in your custom CSS, prefix the color name with an @ symbol. For example, to use the standard success color, use @success_color in your CSS rule.

Actions are organized into groups. To trigger an action, you use a name in the format group.action_name.

GTK provides two predefined, widely used groups:

• app: For actions that are global to the entire application.
• win: For actions tied specifically to an application window.

You can create custom groups by using the insert_action_group method on a widget. When using a custom group, the callback for the action's activate signal will receive the SimpleActionGroup as its first parameter instead of the parent widget (e.g., ApplicationWindow).