[Architecture] Harmonize Board and Document thumbnails

[letsfindaway]

Currently Board mode thumbnails and Document mode thumbnails are separate classes and even separate class hierarchies:

Board thumbnails

classDiagram
    QGraphicsPixmapItem <|-- UBThumbnailPixmapItem
    UBThumbnailPixmapItem <|-- UBDraggableThumbnailItem
    UBDraggableThumbnailItem <|-- UBDraggableLivePixmapItem

Document thumbnails

classDiagram
    QGraphicsPixmapItem <|-- UBThumbnailPixmap
    UBThumbnail <|-- UBThumbnailPixmap
    UBThumbnailPixmap <|-- UBSceneThumbnailPixmap
    UBSceneThumbnailPixmap <|-- UBSceneThumbnailNavigPixmap

But in the end I feel these classes have much in common and we should try to harmonize the class hierarchy as much as possible. If we could even manage to use the same objects for both, then this would further increase loading of a document and reduce memory usage, as we only have to create one kind of thumbnail items.

So the goal of this refactoring is not only to have common code for both kinds of thumbnails, but common instances, even if they have different properties in document mode and board mode. This also avoids that we have to take care about updating both kinds of thumbnails when pages are modified, added or deleted.

[letsfindaway]

Features of the derived classes

What features are added by which derived class? Here a short overview:

UBThumbnailPixmapItem

• reference to the UBDocumentProxy
• scene index (page number)

UBDraggableThumbnailItem

• adds buttons and functions for
  • delete page
  • duplicate page
• shows buttons when mouse is over thumbnail

UBDraggableLivePixmapItem

• adds page number as a UBThumbnailTextItem below item
• adds scene
• adds functions to update pixmap from scene
• knows whether the thumbnail is exposed to the view

UBThumbnail

• show selection via a gray frame
• manage row and column for thumbnail in document mode
• manage page number below thumbnail

UBThumbnailPixmap

Puh, mainly gluing the parent classes together

UBSceneThumbnailPixmap

• reference to the UBDocumentProxy
• scene index (page number)

Very similar to UBThumbnailPixmapItem

UBSceneThumbnailNavigPixmap

Very similar to UBDraggableThumbnailItem

[letsfindaway]

As I said, the aim is to have a common instance of the thumbnail for Document and Board mode. However an item can only be part of one scene. To achieve this we have two choices:

• Move all thumbnail items from the sidebar scene to the document overview scene when switching modes. For me this is some kind of brute force approach.
• Use the same scene for both modes and just re-layout the thumbnails. That seems to be smarter.

I find the second approach very appealing. The differences can be implemented by switching a class implementing the behavior of the thumbnails. The thumbnails delegate these functions to that class. For resizing the views we use the transformation from scene to view and do no longer scale the individual thumbnails. This does not work because we also have the page number below the pixmap, which must not be scaled. But that also does not seem to be a performance bottleneck as there are already holdoff timers avoiding too frequent rescaling.

We would have one such thumbnails scene for each document which we quickly want to switch to. If we have one document open in Board mode and are then searching around in Document mode, then the thumbnails of the Board mode document will still be there, so that we can quickly switch back. We can also think about keeping this scene for all previously opened documents, so that switching between favorites is very fast. Currently this takes some time for very large documents like the IPCC report, because the thumbnails have to be recreated. We should however include the thumbnails in our considerations about caching!

We would finally need

• A class managing the list of all thumbnails for a document. This class has a reference to the UBDocumentProxy. Proposed name: UBDocumentThumbnails.
• A class for the scene containing the thumbnails. This class inherits from QGraphicsScene. Proposed name: UBThumbnailScene.
• A class defining a graphics item grid layout. For the board thumbnails the grid has just one column, but otherwise the same algorithms can be used. Proposed name: UBItemGridLayout.
• A class representing a single thumbnail. This class inherits from QGraphicsItemGroup and combines a QGraphicsPixmapItem and a QGraphicsTextItem for the page number. It holds the page number for that thumbnail. Each thumbnail has also a pointer to the managing class. Proposed name: UBPageThumbnailItem.
• An abstract class defining the interface to behavior and two derived classes for the Document mode and Board mode behavior. The managing class also manages a pointer to an instance of that class and provides it to all thumbnails. Proposed names: UBThumbnailDecorator, UBDocumentThumbnailDecorator, UBBoardThumbnailDecorator.

classDiagram
  direction LR
  class UBThumbnailDecorator
  <<Abstract>> UBThumbnailDecorator
  QGraphicsScene <|-- UBThumbnailScene
  UBThumbnailScene <-- UBDocumentThumbnails
  UBDocumentProxy <-- UBDocumentThumbnails
  UBItemGridLayout <-- UBThumbnailScene
  UBPageThumbnailItem "*" <-- UBDocumentThumbnails
  UBThumbnailScene <-- UBPageThumbnailItem
  QGraphicsItemGroup <|-- UBPageThumbnailItem
  QGraphicsPixmapItem <-- QGraphicsItemGroup
  QGraphicsTextItem <-- QGraphicsItemGroup
  UBThumbnailDecorator <-- UBThumbnailScene
  UBThumbnailDecorator <|-- UBDocumentThumbnailDecorator
  UBThumbnailDecorator <|-- UBBoardThumbnailDecorator

Mermaid class diagrams are not very intuitive, but let me explain it a little bit more.:

• UBDocumentThumbnails at the very right represents the collection of all thumbnails for a document. t therefore has a reference to the UBDocumentProxy to identify the document and a list of UBPageThumbnailItem objects. It also manages the UBThumbnailScene holding the items.
• UBPageThumbnailItem is a QGraphicsItemGroup containing the thumbnail pixmap and the textual page number. It uses a UBThumbnailDecorator to paint things like selection frame and buttons. The decorator is attached to the scene, because one decorator is sufficient for all items.
• The abstract UBThumbnailDecorator has two concrete subclasses for Board mode and Document mode. Besides decorating the thumbnails it is also responsible to handle other mode specific things like selection.