Bibliotheca/docs/booktile.md

BookTile Module Overview

BookTile is the compact widget that displays a single book inside the shelf grid. Each tile shows the cover art (if available) and a wrapped title label, and emits a signal when the user clicks it.

Responsibilities

• Render a thumbnail using Gtk::Picture, loading a Gdk::Texture from the Book when needed.
• Display a short title (falling back to the file name if the book has no title).
• Provide a click gesture (Gtk::GestureClick) that triggers signalActivated() for the parent view to handle.
• Respect layout hints (size request, alignment) so BookShelf can pack multiple tiles per row seamlessly.

Structure

BookTile : Gtk::Box (vertical)
 ├── Gtk::Picture m_cover
 └── Gtk::Label   m_title

Gestures and styling are applied to the box itself so the grid behind it can control selection appearance.

Key methods

• BookTile::setBook(const Book&): updates internal state, refreshes the cover texture and title.
• BookTile::rebuild(): helper that (re)loads the cover if missing and updates the label text.
• signalActivated(): forward this signal to react when the tile is clicked.

Styling expectations

BookShelf adds CSS classes (book-tile) and wraps each tile inside a GridView child. To keep a consistent grid:

• The constructor calls set_size_request(m_coverSize + 16, -1) so each tile has a predictable width for column calculations.
• Margins and spacing are kept small; the grid’s CSS handles selection borders.

Extension points

• Add badges/metadata: append extra widgets (e.g., author label, progress bar) to the box.
• Context menus: attach a Gtk::GestureClick with button 3 or a Gtk::Popover.
• Custom selection visuals: override the CSS class or expose a property that the grid can toggle.

Expected usage

BookShelf creates BookTile instances inside onFactorySetup(), binds them to BookObject data during onFactoryBind(), and listens to signalActivated() to emit its own signalBookActivated().

If other modules need to render books (e.g., a details sidebar), they can reuse BookTile directly or subclass it with additional controls.