book: add chapter about accessibility (#2237)

* book: add chapter about accessibility

* Some improvements

* Another review round

* Fix ci workflow and format

* Address review comments

Author: Hofer-Julian

.github/workflows/book-listings.yml

@@ -29,6 +29,7 @@ jobs:
 
       - run: cargo xtask install
         name: Install Meson and schemas
+        working-directory: book/listings
 
       - run: cargo fmt --check --all
         name: "Format"

book/listings/Cargo.toml

@@ -7,7 +7,7 @@ adw = { version = "0.8", package = "libadwaita", features = ["v1_8"] }
 anyhow = "1.0"
 async-channel = "2.5"
 gettext-rs = { version = "0.7" }
-gtk = { version = "0.10", package = "gtk4", features = ["v4_12"] }
+gtk = { version = "0.10", package = "gtk4", features = ["v4_14"] }
 reqwest = { version = "0.12", default-features = false, features = [
     "rustls-tls",
 ] }
@@ -306,6 +306,31 @@ path = "todo/9/src/main.rs"
 name = "todo_10"
 path = "todo/10/src/main.rs"
 
+# accessibility
+[[bin]]
+name = "accessibility_1"
+path = "accessibility/1/main.rs"
+
+[[bin]]
+name = "accessibility_2"
+path = "accessibility/2/main.rs"
+
+[[bin]]
+name = "accessibility_3"
+path = "accessibility/3/main.rs"
+
+[[bin]]
+name = "accessibility_4"
+path = "accessibility/4/main.rs"
+
+[[bin]]
+name = "accessibility_5"
+path = "accessibility/5/main.rs"
+
+[[bin]]
+name = "accessibility_6"
+path = "accessibility/6/main.rs"
+
 # xtask
 [[bin]]
 name = "xtask"

book/listings/accessibility/1/main.rs

@@ -0,0 +1,51 @@
+use gtk::prelude::*;
+use gtk::{Application, ApplicationWindow, Button, Orientation, accessible, glib};
+
+const APP_ID: &str = "org.gtk_rs.Accessibility1";
+
+fn main() -> glib::ExitCode {
+    let app = Application::builder().application_id(APP_ID).build();
+    app.connect_activate(build_ui);
+    app.run()
+}
+
+fn build_ui(app: &Application) {
+    let container = gtk::Box::builder()
+        .orientation(Orientation::Horizontal)
+        .spacing(12)
+        .halign(gtk::Align::Center)
+        .valign(gtk::Align::Center)
+        .build();
+
+    // ANCHOR: icon_button
+    // Icon-only button needs an accessible label
+    let search_button = Button::builder()
+        .icon_name("system-search-symbolic")
+        .build();
+    search_button.update_property(&[accessible::Property::Label("Search")]);
+    // ANCHOR_END: icon_button
+
+    // ANCHOR: description
+    // Add additional context with a description
+    let settings_button = Button::builder()
+        .icon_name("emblem-system-symbolic")
+        .build();
+    settings_button.update_property(&[
+        accessible::Property::Label("Settings"),
+        accessible::Property::Description("Open application preferences"),
+    ]);
+    // ANCHOR_END: description
+
+    container.append(&search_button);
+    container.append(&settings_button);
+
+    let window = ApplicationWindow::builder()
+        .application(app)
+        .title("Icon Buttons")
+        .default_width(300)
+        .default_height(200)
+        .child(&container)
+        .build();
+
+    window.present();
+}

book/listings/accessibility/2/main.rs

@@ -0,0 +1,44 @@
+use gtk::prelude::*;
+use gtk::{
+    Application, ApplicationWindow, Entry, Label, Orientation, accessible, glib,
+};
+
+const APP_ID: &str = "org.gtk_rs.Accessibility2";
+
+fn main() -> glib::ExitCode {
+    let app = Application::builder().application_id(APP_ID).build();
+    app.connect_activate(build_ui);
+    app.run()
+}
+
+// ANCHOR: labelled_by
+fn build_ui(app: &Application) {
+    let container = gtk::Box::builder()
+        .orientation(Orientation::Horizontal)
+        .spacing(12)
+        .margin_start(12)
+        .margin_end(12)
+        .margin_top(12)
+        .margin_bottom(12)
+        .build();
+
+    let label = Label::new(Some("Username:"));
+    let entry = Entry::new();
+
+    // Tell assistive technologies that the entry is labelled by this label
+    entry.update_relation(&[accessible::Relation::LabelledBy(&[label.upcast_ref()])]);
+
+    container.append(&label);
+    container.append(&entry);
+
+    let window = ApplicationWindow::builder()
+        .application(app)
+        .title("Form Field")
+        .default_width(300)
+        .default_height(100)
+        .child(&container)
+        .build();
+
+    window.present();
+}
+// ANCHOR_END: labelled_by

book/listings/accessibility/3/custom_button/imp.rs

@@ -0,0 +1,105 @@
+use std::cell::RefCell;
+use std::sync::OnceLock;
+
+use glib::Properties;
+use gtk::gdk;
+use gtk::prelude::*;
+use gtk::subclass::prelude::*;
+use gtk::{AccessibleRole, GestureClick, Label, accessible, glib};
+
+// ANCHOR: subclass
+#[derive(Properties, Default)]
+#[properties(wrapper_type = super::CustomButton)]
+pub struct CustomButton {
+    #[property(get, set)]
+    label: RefCell<String>,
+    child: RefCell<Option<Label>>,
+}
+
+#[glib::object_subclass]
+impl ObjectSubclass for CustomButton {
+    const NAME: &'static str = "CustomButton";
+    type Type = super::CustomButton;
+    type ParentType = gtk::Widget;
+
+    fn class_init(klass: &mut Self::Class) {
+        // Set the accessible role to Button
+        klass.set_accessible_role(AccessibleRole::Button);
+        klass.set_css_name("custom-button");
+        klass.set_layout_manager_type::<gtk::BinLayout>();
+
+        // Bind keyboard shortcuts for activation (Enter and Space)
+        klass.add_binding_signal(
+            gdk::Key::space,
+            gdk::ModifierType::empty(),
+            "activate",
+        );
+        klass.add_binding_signal(
+            gdk::Key::KP_Enter,
+            gdk::ModifierType::empty(),
+            "activate",
+        );
+        klass.add_binding_signal(
+            gdk::Key::Return,
+            gdk::ModifierType::empty(),
+            "activate",
+        );
+    }
+}
+// ANCHOR_END: subclass
+
+// ANCHOR: object_impl
+#[glib::derived_properties]
+impl ObjectImpl for CustomButton {
+    fn signals() -> &'static [glib::subclass::Signal] {
+        static SIGNALS: OnceLock<Vec<glib::subclass::Signal>> = OnceLock::new();
+        SIGNALS.get_or_init(|| {
+            vec![glib::subclass::Signal::builder("activate").action().build()]
+        })
+    }
+
+    fn constructed(&self) {
+        self.parent_constructed();
+
+        let obj = self.obj();
+        // Make the widget focusable so keyboard users can reach it
+        obj.set_focusable(true);
+        // Also allow focusing by clicking
+        obj.set_focus_on_click(true);
+
+        // Create a child label and bind its text to our "label" property
+        let child = Label::new(None);
+        child.set_parent(&*obj);
+        obj.update_relation(&[accessible::Relation::LabelledBy(&[child.upcast_ref()])]);
+        obj.bind_property("label", &child, "label")
+            .sync_create()
+            .build();
+        self.child.replace(Some(child));
+
+        // Handle click events
+        let gesture = GestureClick::new();
+        let button = obj.downgrade();
+        gesture.connect_released(move |_, _, _, _| {
+            if let Some(button) = button.upgrade() {
+                button.emit_by_name::<()>("activate", &[]);
+            }
+        });
+        obj.add_controller(gesture);
+
+        // Add an activation handler
+        obj.connect_local("activate", false, move |values| {
+            let button = values[0].get::<super::CustomButton>().unwrap();
+            println!("Button '{}' activated!", button.label());
+            None
+        });
+    }
+
+    fn dispose(&self) {
+        while let Some(child) = self.obj().first_child() {
+            child.unparent();
+        }
+    }
+}
+
+impl WidgetImpl for CustomButton {}
+// ANCHOR_END: object_impl

book/listings/accessibility/3/custom_button/mod.rs

@@ -0,0 +1,15 @@
+mod imp;
+
+use gtk::glib;
+
+glib::wrapper! {
+    pub struct CustomButton(ObjectSubclass<imp::CustomButton>)
+        @extends gtk::Widget,
+        @implements gtk::Accessible, gtk::Buildable, gtk::ConstraintTarget;
+}
+
+impl CustomButton {
+    pub fn new(label: &str) -> Self {
+        glib::Object::builder().property("label", label).build()
+    }
+}

book/listings/accessibility/3/main.rs

@@ -0,0 +1,48 @@
+mod custom_button;
+
+use gtk::prelude::*;
+use gtk::{Application, ApplicationWindow, CssProvider, Orientation, gdk, gio, glib};
+
+use custom_button::CustomButton;
+
+const APP_ID: &str = "org.gtk_rs.Accessibility3";
+
+// ANCHOR: main
+fn main() -> glib::ExitCode {
+    gio::resources_register_include!("accessibility_3.gresource")
+        .expect("Failed to register resources.");
+
+    let app = Application::builder().application_id(APP_ID).build();
+    app.connect_startup(|_| load_css());
+    app.connect_activate(build_ui);
+    app.run()
+}
+
+fn load_css() {
+    let provider = CssProvider::new();
+    provider.load_from_resource("/org/gtk_rs/Accessibility3/style.css");
+    gtk::style_context_add_provider_for_display(
+        &gdk::Display::default().expect("Could not connect to a display."),
+        &provider,
+        gtk::STYLE_PROVIDER_PRIORITY_APPLICATION,
+    );
+}
+
+fn build_ui(app: &Application) {
+    let button1 = CustomButton::new("Click me");
+    let button2 = CustomButton::new("Or me");
+    let container = gtk::Box::new(Orientation::Vertical, 12);
+    container.append(&button1);
+    container.append(&button2);
+
+    let window = ApplicationWindow::builder()
+        .application(app)
+        .title("Custom Button")
+        .default_width(300)
+        .default_height(200)
+        .child(&container)
+        .build();
+
+    window.present();
+}
+// ANCHOR_END: main

book/listings/accessibility/3/resources/resources.gresource.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<gresources>
+  <gresource prefix="/org/gtk_rs/Accessibility3/">
+    <file compressed="true">style.css</file>
+  </gresource>
+</gresources>

book/listings/accessibility/3/resources/style.css

@@ -0,0 +1,14 @@
+custom-button {
+    padding: 12px;
+    outline: 0 solid transparent;
+    outline-offset: 4px;
+    transition: outline-color 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
+                outline-width 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94),
+                outline-offset 200ms cubic-bezier(0.25, 0.46, 0.45, 0.94);
+}
+
+custom-button:focus:focus-visible {
+    outline-color: rgba(53, 132, 228, 0.5);
+    outline-width: 2px;
+    outline-offset: -2px;
+}