notedeck

One damus client to rule them all
git clone git://jb55.com/notedeck
Log | Files | Refs | README | LICENSE

DEVELOPER.md (4113B)

      1 # Developer Guide for Notedeck Chrome
      2 
      3 This guide covers the technical details of the Notedeck Chrome component, which serves as the container and navigation framework for the Notedeck Nostr browser.
      4 
      5 ## Project Structure
      6 
      7 ```
      8 notedeck_chrome
      9 ├── Cargo.toml          - Project manifest and dependencies
     10 ├── android/            - Android-specific code and configuration
     11 │   └── ...
     12 └── src/
     13     ├── notedeck.rs     - Main application entry point
     14     ├── lib.rs          - Library exports
     15     ├── theme.rs        - Theme definitions and customization
     16     ├── preview.rs      - UI component preview system
     17     ├── chrome.rs       - Core Chrome UI implementation
     18     ├── fonts.rs        - Font loading and configuration
     19     ├── app.rs          - Application management
     20     ├── android.rs      - Android-specific code
     21     └── setup.rs        - Application setup and configuration
     22 ```
     23 
     24 ## Key Components
     25 
     26 ### Chrome
     27 
     28 The `Chrome` struct (`src/chrome.rs`) is the main container that:
     29 - Maintains a list of applications
     30 - Renders the sidebar
     31 - Handles application switching
     32 - Processes UI actions
     33 
     34 ### NotedeckApp
     35 
     36 The `NotedeckApp` enum (`src/app.rs`) represents different applications that can be managed by the Chrome:
     37 - `Columns` - The main Damus columns interface
     38 - `Dave` - The Dave application
     39 - `Other` - Generic container for other implementations of the `App` trait
     40 
     41 ### Setup
     42 
     43 The `setup.rs` file handles initialization of:
     44 - Font loading
     45 - Theme setup
     46 - Window configuration
     47 - App icons
     48 
     49 ## Architecture Overview
     50 
     51 Notedeck Chrome follows a container-based architecture:
     52 
     53 1. The `Chrome` struct maintains a vector of applications
     54 2. It controls which application is active via an index
     55 3. The sidebar is rendered with buttons for each application
     56 4. When an application is selected, it's updated within the container
     57 
     58 ## Android Support
     59 
     60 Android integration relies on:
     61 - Native Android UI integration via `GameActivity`
     62 - Custom keyboard height detection for improved mobile UX
     63 - Configuration via external JSON files
     64 
     65 ### Android Keyboard Handling
     66 
     67 The Android integration includes custom Java code to handle keyboard visibility changes:
     68 - `KeyboardHeightProvider` - Detects keyboard height changes
     69 - `KeyboardHeightObserver` - Interface for keyboard events
     70 - `MainActivity` - Main Android activity with JNI integration
     71 
     72 ## Styling and Theming
     73 
     74 The theme system supports:
     75 - Light and dark mode
     76 - OLED-optimized dark mode for mobile
     77 - Customizable text styles
     78 - Font loading with multiple typefaces
     79 
     80 ## Building and Running
     81 
     82 ### Desktop
     83 
     84 ```bash
     85 # Run in debug mode
     86 cargo run -- --debug
     87 
     88 # Run in release mode
     89 cargo run --release
     90 ```
     91 
     92 ## Testing
     93 
     94 The project includes tests for:
     95 - Database path configuration
     96 - Command-line argument parsing
     97 - Column initialization
     98 
     99 Run tests with:
    100 
    101 ```bash
    102 cargo test
    103 ```
    104 
    105 ## Configuration and Data Paths
    106 
    107 - Desktop: Uses the platform-specific data location or current directory
    108 - Android: Uses the Android app's internal storage
    109 - Custom paths can be specified via command-line arguments
    110 
    111 ## Advanced Debugging
    112 
    113 - Enable the `debug-widget-callstack` feature to debug UI hierarchy
    114 - Enable the `debug-interactive-widgets` feature to highlight interactive areas
    115 - Android logging uses `tracing-logcat` for detailed diagnostics
    116 
    117 ## Code Workflow
    118 
    119 1. `notedeck.rs` is the entry point, which initializes `Notedeck`
    120 2. `setup.rs` configures the application environment
    121 3. `Chrome` is created and populated with applications
    122 4. The main UI loop renders the sidebar and active application
    123 
    124 ## Key Files for Modification
    125 
    126 - `chrome.rs` - To modify the sidebar or app container behavior
    127 - `theme.rs` - To update theming and colors
    128 - `setup.rs` - To change startup configuration
    129 - `android.rs` - For Android-specific changes
    130 
    131 ## Adding a New Application
    132 
    133 1. Implement the `notedeck::App` trait for your application
    134 2. Add a new variant to the `NotedeckApp` enum if needed
    135 3. Update the `Chrome::topdown_sidebar` method to add a button for your app
    136 4. Add your app to the `Chrome` instance in `notedeck.rs`