Bibliotheca/docs/bookdetails.md

BookDetails Module Overview

BookDetails is a widget that displays detailed information about a single book and provides tag management functionality. It subscribes to BookList signals to stay synchronized with model changes.

Responsibilities

• Display book metadata: cover image, title, author, file path.
• Render tags as interactive chips in a FlowBox.
• Allow users to add new tags via an entry field.
• Allow users to remove tags by clicking the X button on each chip.
• Provide an "Open" button to launch the book file in the default application.
• Emit signalBookRemoved() when the displayed book is deleted.

Structure

BookDetails (Gtk::Box, vertical)
 ├── Gtk::Image m_cover           // book cover thumbnail
 ├── Gtk::Label m_title           // book title (bold markup)
 ├── Gtk::Label m_author          // book author
 ├── Gtk::Label (file path)       // path to book file
 ├── Gtk::Button m_open_button    // "Open" - launches file
 ├── Gtk::FlowBox m_tags_box      // tag chips with X buttons
 └── Gtk::Box (horizontal)
      ├── Gtk::Entry m_tag_entry  // new tag input
      └── Gtk::Button m_add_tag_button  // "Add Tag"

Data flow

1. Display: set_book(book) stores the book ID and calls refresh_display() to populate all widgets from the book data.

2. Tag management:

   • on_add_tag_button_clicked() calls m_db.add_tag_to_book() then refresh_tags()
   • on_remove_tag_clicked(tag) calls m_db.remove_tag_from_book() then refresh_tags()
   • refresh_tags() queries only the tags for this book (no full list reload)

3. Synchronization:

   • Subscribes to BookList::signalBookRemoved() - if the displayed book is deleted, emits signalBookRemoved() so the window can navigate away
   • Subscribes to BookList::signalBookUpdated() and signalReset() to refresh the display when book data changes

4. Clearing: clear() resets the book ID and all widget contents

Tag chip widget

Each tag is rendered as a horizontal box containing:

• A label with the tag name
• A small button with an X icon to remove the tag

The chips are created by create_tag_chip() and added to the FlowBox.

Signals

Signal	Description
signalBookRemoved	Emitted when the displayed book is deleted

Thread safety

BookDetails operates on the main UI thread. All database operations go through DatabaseManager which handles its own locking. The widget looks up fresh book data via m_book_list.findById() rather than storing a raw pointer.

Expected usage

m_bookDetails = std::make_unique<BookDetails>(db, bookList);
m_bookDetails->signalBookRemoved().connect([this]() {
  // Navigate back to shelf view
});
m_stack.add(*m_bookDetails, "details");

// When a book is activated:
m_bookDetails->set_book(&book);
m_stack.set_visible_child(*m_bookDetails);

Extension points

• Additional metadata: Add labels for format, file size, date added.
• Edit metadata: Add entry fields to modify title/author.
• Tag autocomplete: Suggest existing tags when typing.
• Delete confirmation: Show a dialog before deleting books.