From f8b41bed35a396993ef41bd55f88b864ac075c02 Mon Sep 17 00:00:00 2001 From: Wiktor Wichrowski <77555700+Ethran@users.noreply.github.com> Date: Fri, 7 Nov 2025 16:01:19 +0100 Subject: [PATCH 1/2] Add documentation for editor data flow This document describes the data flow for the editor, detailing the roles of PageDataManager and the data loading process. --- docs/editor-data-flow.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/editor-data-flow.md diff --git a/docs/editor-data-flow.md b/docs/editor-data-flow.md new file mode 100644 index 00000000..5f480d82 --- /dev/null +++ b/docs/editor-data-flow.md @@ -0,0 +1,37 @@ +# Editor Data Flow + +This document describes how page data, particularly strokes, is loaded, cached, and managed within the editor. + +**It was created by AI, and should be checked for correctness. Refer to code for actual implementation.** + +Contents: +- `PageDataManager` +- Data Loading Process + +--- + +## `PageDataManager` + +`PageDataManager` is a singleton (`object`) that acts as the central repository for all page-related content. It abstracts the underlying data sources (like the Room database and file system) from the rest of the application. + +- **Responsibilities**: + - Fetching strokes, images, and other page elements from the database. + - Caching frequently accessed data to improve performance. + - Persisting new or modified data back to the database. +- **Role**: It serves as a single source of truth for page content, ensuring data consistency and providing a clean API for the editor components to request and submit data. + +--- + +## Data Loading Process + +The process of loading a page's data into the editor follows a clear path orchestrated by the `EditorControlTower`. + +1. **Initiation**: When the editor is opened for a specific page, the `EditorControlTower` is created with an `EditorState` that contains the required `pageId`. + +2. **Request**: The `EditorControlTower` uses its `CoroutineScope` to launch an asynchronous request to the `PageDataManager` for the strokes and other content associated with the `pageId`. + +3. **Fetching & Caching**: `PageDataManager` retrieves the data from the database. It may also utilize an in-memory cache to avoid redundant database queries if the data has been recently accessed. + +4. **Delivery**: Once the data is retrieved, it is passed to the `PageView`. + +5. **Rendering**: `PageView` then uses this data to instruct its `DrawCanvas` component on what to render on the screen. This separation ensures that the `PageView` manages the "what" (the data) while the `DrawCanvas` handles the "how" (the actual drawing operations). From 6d92ecc5d332dce7420ad82dfe5db4a89af0f6c8 Mon Sep 17 00:00:00 2001 From: Wiktor Wichrowski <77555700+Ethran@users.noreply.github.com> Date: Fri, 7 Nov 2025 16:02:28 +0100 Subject: [PATCH 2/2] Add documentation for editor state and view management This document explains the editor's state and view management, detailing components like EditorState, EditorControlTower, PageView, and DrawCanvas. --- docs/editor-state-and-view.md | 77 +++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/editor-state-and-view.md diff --git a/docs/editor-state-and-view.md b/docs/editor-state-and-view.md new file mode 100644 index 00000000..14cda2de --- /dev/null +++ b/docs/editor-state-and-view.md @@ -0,0 +1,77 @@ +# Editor State and View Management + +This document explains how the editor identifies which page to display and how the view components are managed. + +**It was created by AI, and should be checked for correctness. Refer to code for actual implementation.** + +Contents: +- `EditorState` +- `EditorControlTower` +- `PageView` +- `DrawCanvas` + +--- + +## `EditorState` + +The `EditorState` class is a simple, immutable data holder that represents the "context" of the editor session. Its primary role is to answer the question: "What are we currently editing?" + +```kotlin +class EditorState( + val bookId: String? = null, + val pageId: String, + val pageView: PageView +) +``` + +- It holds the unique `pageId` which is the key identifier for all data loading and state management operations. +- The presence of a `bookId` provides additional context if the page belongs to a notebook. + +--- + +## `EditorControlTower` + +The `EditorControlTower` is the central coordinator for the editor. It holds the `EditorState` and uses it to manage all other components. + +- **Role**: + - Initializes the editor environment based on the provided `EditorState`. + - Orchestrates the flow of data from `PageDataManager` to the `PageView`. + - Manages editor-wide concerns like the undo/redo `History`. + +--- + +## `PageView` + +`PageView` is the main Android `View` for the editor. It is responsible for setting up the drawing surface and handling user interactions like touch input and gestures (zooming, panning). + +```kotlin +class PageView( + val context: Context, + val coroutineScope: CoroutineScope, + var id: String, // The pageId it is currently displaying + var viewWidth: Int, + var viewHeight: Int, + val snackManager: SnackState +) +``` + +- It owns the `DrawCanvas` and other UI elements. +- It translates raw touch events into drawing commands or navigation gestures, which are then processed by the `EditorControlTower` or `DrawCanvas`. + +--- + +## `DrawCanvas` + +The `DrawCanvas` is a specialized component, likely a custom `View` or a class that operates directly on a `Canvas`, dedicated to the low-level task of rendering. + +```kotlin +// Example structure +class DrawCanvas(context: Context) : View(context) { + // ... +} +``` + +- **Responsibilities**: + - Directly handles `Canvas` drawing operations (e.g., `drawPath`). + - Renders the strokes, images, and background that it receives from the `PageView`. + - It is optimized for high-performance drawing and does not contain business logic. Its only job is to draw what it's told to draw.