Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Rust GTK App Framework
This libaray aims to provide a framework for adaptive GTK4 and libadwaita apps written in Rust.
Writing flatpak apps requires several files (.desktop file, appdata.xml, flatpak manifest). gtk-rust-app and its CLI gra
allow to generate these files based on an extended Cargo.toml.
Getting started TLDR
cargo install cargo-generate
cargo generate --git https://gitlab.com/floers/gtk-rust-app-template
cd <your app>
sudo make install-gsettings
cargo run
Getting started
Creating apps with gtk-rust-app requires to
- Add more metadata to the Cargo.toml
- Write some boilerplate code in main.rs
- Define App pages
- Optional: Define a build.rs script
- Install cargo-gra subcommand
- Install app settings locally
Cargo.toml
Define app metadata and the dependency to gtk-rust-app
in your Cargo.toml. Checkout the manifest reference for more info.
# Cargo.toml
[]
...
[]
# Metadata of your app
[]
# global settings
[]
# global GTK actions
[]
# as usual
= { = "https://gitlab.com/floers/gtk-rust-app.git", = [ "ui" ] }
# If you want to automatically update generated files you can add this build dependency
[]
= "0.3"
App boilerplate code
Create the file main.rs:
// src/main.rs
extern crate gtk_rust_app;
extern crate log;
use gettext;
use *;
use LeafletLayout;
use crate Home;
// This module will contain our home page
Define app pages
The home page:
//src/home.rs
use ObjectSubclassIsExt;
use *;
use gettext;
use crate Card;
// Define a page of your app as a new widget
// home.ui
True
True
vertical
Write your custom widgets
The examples above mention a card
module. You can come up with your own idea (it works like the home page) or look into examples/simple/src/card.rs
.
Optional: Build script
Define the build script:
// build.rs
Install cargo-gra
cargo install cargo-gra
Prepare the app build via:
cargo gra gen
and build it as usual:
cargo build --release
You can build a flatpak app via:
cargo gra flatpak
That's it.
Install app settings locally
GTK apps define their settings and need gnome or phosh to have these settings installed globally. When you want to run your app without having these settings installed it will crash with an error.
Add the following Makefile
to your project:
install-gsettings:
install -D target/gra-gen/{{app-id}}.gschema.xml /usr/share/glib-2.0/schemas/{{app-id}}.gschema.xml
glib-compile-schemas /usr/share/glib-2.0/schemas
uninstall-gsettings:
rm /usr/share/glib-2.0/schemas/{{app-id}}.gschema.xml
glib-compile-schemas /usr/share/glib-2.0/schemas
And replace {{app-id}}
with your app id. Then run make install-gsettings
and your app should run fine.
Run with different language
LANGUAGE="de_DE:de" LANG="de_DE.utf8" TEXT_DOMAIN="target"
Requirements
Debian dependencies:
sudo apt install libgraphene-1.0-dev libgtk-4-dev flatpak-builder
Arch dependencies:
TODO
To build a flatpak you need the to install gnome-nightly remote. Download https://nightly.gnome.org/gnome-nightly.flatpakrepo.
Examples
Checkout the example apps in carg-gra.
Writing custom Widgets
The example above already showed a custom GTK widget. The #[widget]
macro makes it easy and fast to create custom widgets but it abstracts and simplifies some aspects. The GTK Rust book is a good source to understand what the #[widget]
macro does and how to create custom widgets with full control.
https://gtk-rs.org/gtk4-rs/stable/latest/book/introduction.html
Domain model and GObjects
Sometimes we need GObjects. Widgets are special GObjects. Similar to the #[widget]
macro gtk-rust-app allows to define GObejcts quickly with the #[gobject]
macro. An Example:
We have a domain struct TodoItem
. Our application state stores these TodoItems
in a vec and we want to select a single one in a GTK combobox (Or more likely in a AdwComboRow
) menu. GTK expects a combobox to have a backing model
which is a list of GObjects
. Writing a GObject for our TodoItem
is a lot of boilerplate code and we might not need the whole objectiveness because we are not writing object oriented code. Nevertheless we want our combobox to show the possible TodoItems
and select one probably knowing the selected Id.
To address this problem gtk-rust-app
provides the attribute macro gobjectify
. The macro allows to define a set of fields for a struct which will be used to generate a GObject definition.
Will generate the GObject TodoItemGObject
with the properties id
and name
and a public method TodoItem.gobjectify() -> TodoItemGObject
.
gstore debugging
You can press Ctrl+Shift+G
to open a debug window for the global state and actions implemented in gstore
.
Note: This keybinding and window are only available dev builds.