### Create and Open Documents (C++)

Source: https://context7.com/lewhfree/bookr/llms.txt

This C++ snippet demonstrates the factory method for creating document instances based on file type. It initializes the PSP screen and user settings, then opens a specified document file. The code retrieves document metadata such as title, type, and filename, and checks document capabilities like pagination, zoom, rotation, and bookmarking.

```cpp
#include "bkdocument.h"
#include "fzscreen.h"

int main() {
    // Initialize PSP screen and user settings
    FZScreen::open(argc, argv);
    FZScreen::setupCtrl();
    BKUser::init();

    // Open a document by file path
    string filePath = "ms0:/PSP/GAME/bookrpsp/mydocument.pdf";
    BKDocument* doc = BKDocument::create(filePath);

    if (doc == nullptr) {
        // File format not supported or file not found
        return -1;
    }

    // Get document metadata
    string title, type, filename;
    doc->getTitle(title);      // "My Document"
    doc->getType(type);        // "PDF" or "Plain Text"
    doc->getFileName(filename); // Full path

    // Check document capabilities
    bool paginated = doc->isPaginated();     // true for PDF
    bool zoomable = doc->isZoomable();       // true for PDF
    bool rotatable = doc->isRotable();       // true
    bool bookmarkable = doc->isBookmarkable(); // true

    // Clean up
    doc->release();
    FZScreen::close();
    return 0;
}
```

--------------------------------

### Configure User Settings in C++

Source: https://context7.com/lewhfree/bookr/llms.txt

Initializes and configures user preferences, including control mappings, CPU speeds, PDF options, text rendering settings, and color schemes. Loads settings from 'user.xml' and saves them back. Dependencies include 'bkuser.h'.

```cpp
#include "bkuser.h"

void configureUserSettings() {
    // Initialize user preferences (loads from user.xml)
    BKUser::init();

    // Configure control mappings
    BKUser::Controls& controls = BKUser::controls;
    controls.nextPage = FZ_CTRL_DOWN;        // D-pad down
    controls.previousPage = FZ_CTRL_UP;       // D-pad up
    controls.next10Pages = FZ_CTRL_RTRIGGER;  // Right trigger
    controls.previous10Pages = FZ_CTRL_LTRIGGER; // Left trigger
    controls.zoomIn = FZ_CTRL_TRIANGLE;       // Triangle button
    controls.zoomOut = FZ_CTRL_SQUARE;        // Square button
    controls.showToolbar = FZ_CTRL_START;     // Start button
    controls.showMainMenu = FZ_CTRL_SELECT;   // Select button
    controls.select = FZ_CTRL_CIRCLE;         // Circle (or Cross)
    controls.cancel = FZ_CTRL_CROSS;          // Cross (or Circle)

    // Configure application options
    BKUser::Options& options = BKUser::options;

    // PSP CPU speed settings (higher = faster but more battery drain)
    options.pspSpeed = 266;      // CPU speed during reading (MHz)
    options.pspMenuSpeed = 133;  // CPU speed in menus (MHz)

    // PDF options
    options.pdfFastScroll = true;     // Fast scroll mode for PDFs
    options.pdfInvertColors = false;  // Invert PDF colors (white-on-black)

    // Text rendering options
    options.txtFont = "ms0:/fonts/vera.ttf";
    options.txtSize = 10;
    options.txtRotation = 0;
    options.txtJustify = true;
    options.txtHeightPct = 110;
    options.txtWrapCR = 1;

    // Color schemes (can have multiple)
    BKUser::ColorScheme blackOnWhite;
    blackOnWhite.txtFGColor = 0xFF000000; // Black
    blackOnWhite.txtBGColor = 0xFFFFFFFF; // White

    BKUser::ColorScheme whiteOnBlack;
    whiteOnBlack.txtFGColor = 0xFFFFFFFF; // White
    whiteOnBlack.txtBGColor = 0xFF000000; // Black

    options.colorSchemes.push_back(blackOnWhite);
    options.colorSchemes.push_back(whiteOnBlack);
    options.currentScheme = 0; // Use first scheme

    // Display options
    options.displayLabels = true;     // Show page numbers and status
    options.loadLastFile = true;      // Auto-load last opened file
    options.lastFolder = "ms0:/PSP/GAME/documents/";
    options.lastFontFolder = "ms0:/PSP/GAME/fonts/";

    // Save preferences to user.xml
    BKUser::save();
}

```

--------------------------------

### Document API - Creating and Opening Documents

Source: https://context7.com/lewhfree/bookr/llms.txt

This API section describes how to create and open documents in Bookr. It utilizes a factory method to detect file types and instantiate the appropriate document viewer (PDF or plain text). It also covers retrieving document metadata and checking supported capabilities.

```APIDOC
## POST /document/create

### Description
Factory method that detects file type and creates appropriate document viewer instance (PDF or plain text).

### Method
POST

### Endpoint
/document/create

#### Request Body
- **filePath** (string) - Required - The path to the document file to be opened.

### Request Example
```json
{
  "filePath": "ms0:/PSP/GAME/bookrpsp/mydocument.pdf"
}
```

### Response
#### Success Response (200)
- **document_id** (string) - A unique identifier for the created document.
- **title** (string) - The title of the document.
- **type** (string) - The type of the document (e.g., "PDF", "Plain Text").
- **filename** (string) - The full path of the document file.
- **capabilities** (object) - An object containing boolean flags for document capabilities.
  - **paginated** (boolean) - Indicates if the document is paginated.
  - **zoomable** (boolean) - Indicates if the document supports zoom.
  - **rotatable** (boolean) - Indicates if the document supports rotation.
  - **bookmarkable** (boolean) - Indicates if the document supports bookmarking.

#### Response Example
```json
{
  "document_id": "doc123",
  "title": "My Document",
  "type": "PDF",
  "filename": "ms0:/PSP/GAME/bookrpsp/mydocument.pdf",
  "capabilities": {
    "paginated": true,
    "zoomable": true,
    "rotatable": true,
    "bookmarkable": true
  }
}
```

#### Error Response (400)
- **error** (string) - "File format not supported or file not found."
```

--------------------------------

### Render Document Loop in C++

Source: https://context7.com/lewhfree/bookr/llms.txt

Manages the main rendering loop for displaying documents and UI elements using the PSP graphics library. It handles user input, updates the document state, and performs screen rendering including buffer swapping and waiting for vertical blank. Dependencies include 'fzscreen.h' and 'BKDocument'.

```cpp
#include "fzscreen.h"

void renderDocumentLoop(BKDocument* doc) {
    // Initialize screen
    FZScreen::open(argc, argv);
    FZScreen::setupCtrl();

    // Set CPU speed for optimal performance
    FZScreen::setSpeed(266); // 266 MHz

    bool exitLoop = false;
    bool needsRedraw = true;

    while (!exitLoop) {
        // Read PSP button input
        int buttons = FZScreen::readCtrl();

        // FZ_CTRL_UP, FZ_CTRL_DOWN, FZ_CTRL_LEFT, FZ_CTRL_RIGHT
        // FZ_CTRL_CIRCLE, FZ_CTRL_CROSS, FZ_CTRL_TRIANGLE, FZ_CTRL_SQUARE
        // FZ_CTRL_LTRIGGER, FZ_CTRL_RTRIGGER
        // FZ_CTRL_START, FZ_CTRL_SELECT

        if (buttons != 0) {
            needsRedraw = true;

            // Update document based on input
            int command = doc->update(buttons);

            if (command == BK_CMD_EXIT) {
                exitLoop = true;
            }
        }

        if (needsRedraw) {
            // Begin rendering
            FZScreen::startDirectList();

            // Render document content
            doc->render();

            // End rendering and display
            FZScreen::endAndDisplayList();

            // Wait for vertical blank (60 Hz)
            FZScreen::waitVblankStart();

            // Swap framebuffers
            FZScreen::swapBuffers();

            needsRedraw = false;
        }

        // Process system events
        FZScreen::checkEvents();
    }

    // Cleanup
    FZScreen::close();
    FZScreen::exit();
}

```

--------------------------------

### Load and Display Plain Text Documents (C++)

Source: https://context7.com/lewhfree/bookr/llms.txt

Loads and displays plain text files with configurable fonts, sizes, and color schemes. It requires 'bkplaintext.h' and 'bkuser.h' for text handling and user settings. The function takes a file path as input and outputs rendered text to the screen.

```cpp
#include "bkplaintext.h"
#include "bkuser.h"

void loadTextDocument(string& txtPath) {
    // Create plain text document
    BKPlainText* txt = BKPlainText::create(txtPath);
    if (!txt) return;

    // Configure text rendering options via BKUser settings
    BKUser::options.txtFont = "ms0:/PSP/GAME/bookrpsp/fonts/vera.ttf";
    BKUser::options.txtSize = 12; // Font size in points
    BKUser::options.txtRotation = 0; // 0=portrait, 1=90°, 2=180°, 3=270°
    BKUser::options.txtJustify = true; // Text justification
    BKUser::options.txtHeightPct = 100; // Line height percentage
    BKUser::options.txtWrapCR = 1; // Wrap on carriage return

    // Set color scheme (foreground and background)
    BKUser::ColorScheme scheme;
    scheme.txtFGColor = 0xFF000000; // Black text (ARGB format)
    scheme.txtBGColor = 0xFFFFFFFF; // White background
    BKUser::options.colorSchemes.push_back(scheme);
    BKUser::options.currentScheme = 0;

    // Save user preferences
    BKUser::save();

    // Navigation (plain text is paginated based on screen size)
    int totalPages = txt->getTotalPages();
    int currentPage = txt->getCurrentPage();
    txt->setCurrentPage(10);

    // Render text content
    FZScreen::startDirectList();
    txt->renderContent();
    FZScreen::endAndDisplayList();

    txt->release();
}

```

--------------------------------

### PDF Document Navigation and Zoom (C++)

Source: https://context7.com/lewhfree/bookr/llms.txt

This C++ snippet illustrates PDF document navigation and zoom functionalities. It creates a PDF document instance, retrieves total and current page numbers, and allows jumping to specific pages. The code also handles screen-based scrolling for zoomed documents, manages zoom levels (including fit-to-screen options), and adjusts document rotation. Finally, it renders the current view of the PDF document.

```cpp
#include "bkpdf.h"

void handlePDFDocument(string& pdfPath) {
    // Create PDF document
    BKPDF* pdf = BKPDF::create(pdfPath);
    if (!pdf) return;

    // Page navigation
    int totalPages = pdf->getTotalPages();  // e.g., 150
    int currentPage = pdf->getCurrentPage(); // e.g., 1

    // Jump to specific page
    pdf->setCurrentPage(25);

    // Navigate by screen movements (for zoomed documents)
    pdf->screenDown();  // Scroll down one screen
    pdf->screenUp();    // Scroll up one screen
    pdf->screenLeft();  // Scroll left
    pdf->screenRight(); // Scroll right

    // Get available zoom levels
    vector<BKDocument::ZoomLevel> zoomLevels;
    pdf->getZoomLevels(zoomLevels);
    // zoomLevels contains: "Fit Width", "Fit Height", "50%", "100%", "150%", etc.

    int currentZoom = pdf->getCurrentZoomLevel(); // e.g., 3 (100%)
    pdf->setZoomLevel(4); // Set to 150%

    // Fit-to-screen zoom modes
    if (pdf->hasZoomToFit()) {
        pdf->setZoomToFitWidth();  // Fit page width to screen
        pdf->setZoomToFitHeight(); // Fit page height to screen
    }

    // Analog stick panning (x, y deltas)
    pdf->pan(10, -5); // Pan 10 pixels right, 5 pixels up

    // Rotation (0=0°, 1=90°, 2=180°, 3=270°)
    int rotation = pdf->getRotation(); // Current rotation
    pdf->setRotation(1); // Rotate 90 degrees

    // Render the current view
    FZScreen::startDirectList();
    pdf->renderContent();
    FZScreen::endAndDisplayList();

    pdf->release();
}
```

--------------------------------

### Manage Bookmarks for Documents (C++)

Source: https://context7.com/lewhfree/bookr/llms.txt

Manages bookmarks for documents, allowing creation, saving, and restoration of reading positions. It utilizes 'bkbookmark.h' and 'bkbookmarksmanager.h'. The function takes a document object and filename as input. It can restore the last viewed position or add new user-created bookmarks.

```cpp
#include "bkbookmark.h"

void manageBookmarks(BKDocument* doc, string& filename) {
    // Check if document supports bookmarks
    if (!doc->isBookmarkable()) return;

    // Get last viewed position for a file
    BKBookmark lastView;
    bool hasLastView = BKBookmarksManager::getLastView(filename, lastView);

    if (hasLastView) {
        // Restore last reading position
        doc->setBookmarkPosition(lastView.viewData);
        // lastView.page contains the page number
        // lastView.viewData contains view-specific data (zoom, pan, etc.)
    }

    // Create a new bookmark at current position
    BKBookmark newBookmark;
    newBookmark.title = "Chapter 5 - Important Section";
    newBookmark.page = doc->getCurrentPage();
    newBookmark.createdOn = "2006-08-16 14:30";
    newBookmark.lastView = false; // Not the last view, user-created bookmark

    // Get current view position data (zoom, pan, rotation)
    doc->getBookmarkPosition(newBookmark.viewData);

    // Save bookmark
    BKBookmarksManager::addBookmark(filename, newBookmark);

    // Load all bookmarks for a file
    BKBookmarkList bookmarks;
    BKBookmarksManager::getBookmarks(filename, bookmarks);

    // Iterate through bookmarks (max 20 per file)
    for (BKBookmarkListIt it = bookmarks.begin(); it != bookmarks.end(); ++it) {
        string title = it->title;
        int page = it->page;
        bool isLastView = it->lastView;
    }

    // Update last file opened
    BKBookmarksManager::setLastFile(filename);

    // Clear all bookmarks (use with caution)
    // BKBookmarksManager::clear();
}

```

--------------------------------

### Plain Text Document Loading

Source: https://context7.com/lewhfree/bookr/llms.txt

API for loading and displaying plain text files with configurable font, size, and color settings.

```APIDOC
## Plain Text Document Loading API

### Description
This API allows for the loading and rendering of plain text files. It provides extensive customization options for text appearance, including font selection, size, color schemes, and text justification.

### Method
N/A (This describes a library function, not a network API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **txtPath** (string) - Required - The file path to the plain text document.

#### Query Parameters
None

#### Request Body
None

### Request Example
```cpp
void loadTextDocument(string& txtPath);
```

### Response
#### Success Response (200)
N/A (Function returns void, success indicated by lack of errors)

#### Response Example
N/A
```

--------------------------------

### File Chooser UI for Document and Font Selection (C++)

Source: https://context7.com/lewhfree/bookr/llms.txt

Provides an interactive file browser for selecting documents and fonts from the PSP memory stick. It uses 'bkfilechooser.h'. The function 'openFileChooser' creates and manages the file chooser dialog, handling user input and rendering. It outputs the selected file path or command.

```cpp
#include "bkfilechooser.h"

void openFileChooser() {
    // Create file chooser dialog
    string title("Select document to open");
    BKFileChooser* chooser = BKFileChooser::create(title, BK_CMD_OPEN_FILE);

    // Alternative: font file chooser
    // string title("Select font file");
    // BKFileChooser* chooser = BKFileChooser::create(title, BK_CMD_SET_FONT);

    // File chooser is a layer that handles its own input
    // Add to layer stack for display
    // layers.push_back(chooser);

    // In the update loop, process button input
    int buttons = FZScreen::readCtrl();
    int command = chooser->update(buttons);

    // Render file chooser
    FZScreen::startDirectList();
    chooser->render();
    FZScreen::endAndDisplayList();

    if (command == BK_CMD_OPEN_FILE) {
        // User selected a file
        string selectedPath;
        chooser->getFullPath(selectedPath);
        // selectedPath = "ms0:/PSP/GAME/documents/mybook.pdf"

        FZDirent dirent;
        chooser->getCurrentDirent(dirent);
        // dirent contains file metadata (name, size, type)

        // Create document from selected file
        BKDocument* doc = BKDocument::create(selectedPath);
    }

    chooser->release();
}

```

--------------------------------

### Bookmark Management API

Source: https://context7.com/lewhfree/bookr/llms.txt

API for creating, saving, and restoring bookmarks within documents, including position and view-specific data.

```APIDOC
## Bookmark Management API

### Description
This API provides functionality to manage bookmarks for documents. It enables users to save their current reading position, restore previous reading sessions, and organize bookmarks with titles and timestamps.

### Method
N/A (This describes a library function, not a network API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **doc** (BKDocument*) - Required - Pointer to the document object.
- **filename** (string) - Required - The identifier for the document.

#### Query Parameters
None

#### Request Body
None

### Request Example
```cpp
void manageBookmarks(BKDocument* doc, string& filename);
```

### Response
#### Success Response (200)
N/A (Function returns void, success indicated by lack of errors)

#### Response Example
N/A
```

--------------------------------

### File Chooser UI API

Source: https://context7.com/lewhfree/bookr/llms.txt

API for an interactive file browser UI, allowing users to select documents and font files from the memory stick.

```APIDOC
## File Chooser UI API

### Description
This API exposes an interactive file chooser interface, enabling users to browse and select files (documents, fonts) stored on the PSP's memory stick. It handles user input for navigation and selection.

### Method
N/A (This describes a library function, not a network API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```cpp
void openFileChooser();
```

### Response
#### Success Response (200)
N/A (Function returns void, success indicated by lack of errors)

#### Response Example
N/A
```

--------------------------------

### PDF Document Navigation and Zoom API

Source: https://context7.com/lewhfree/bookr/llms.txt

This API section details how to navigate and manipulate PDF documents within Bookr. It covers page navigation, adjusting zoom levels, panning the viewport, and rotating the document view.

```APIDOC
## PDF Document Navigation and Zoom API

### Description
Navigate PDF pages, adjust zoom levels, and pan the viewport.

### Method
POST

### Endpoint
/document/pdf/navigate

#### Request Body
- **document_id** (string) - Required - The ID of the PDF document to interact with.
- **action** (string) - Required - The navigation action to perform. Possible values: "setCurrentPage", "screenDown", "screenUp", "screenLeft", "screenRight", "setZoomLevel", "setZoomToFitWidth", "setZoomToFitHeight", "pan", "setRotation".
- **params** (object) - Optional - Parameters for the action.
  - **pageNumber** (integer) - Required for "setCurrentPage". The target page number.
  - **zoomLevelIndex** (integer) - Required for "setZoomLevel". The index of the desired zoom level.
  - **deltaX** (integer) - Required for "pan". Horizontal pan delta.
  - **deltaY** (integer) - Required for "pan". Vertical pan delta.
  - **rotationDegrees** (integer) - Required for "setRotation". The desired rotation in degrees (0, 90, 180, 270).

### Request Example
```json
{
  "document_id": "doc123",
  "action": "setCurrentPage",
  "params": {
    "pageNumber": 25
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - "success"
- **message** (string) - A confirmation message (e.g., "Page set to 25", "Zoom level updated").
- **currentPage** (integer) - The current page number after the action.
- **totalPages** (integer) - The total number of pages in the document.
- **currentZoomLevel** (integer) - The index of the current zoom level.
- **rotation** (integer) - The current rotation in degrees.

#### Response Example
```json
{
  "status": "success",
  "message": "Page set to 25",
  "currentPage": 25,
  "totalPages": 150,
  "currentZoomLevel": 3,
  "rotation": 0
}
```

#### Error Response (400)
- **error** (string) - "Invalid action or parameters."
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.