DOCSEARCHbyAlgolia
Submit Docs

Peashot (Ferrishot)

repository·main·Indexed 42 days ago

https://github.com/nik-rev/peashot

A Rust-based screenshot application inspired by Flameshot featuring advanced region selection, keyboard-driven controls, and Vim motions. It includes a customizable CLI for automation and scripting, supporting headless mode via options like --region and --accept-on-select. Configuration is handled via .kdl files, allowing for custom UI, color schemes, and keybindings.

Tokens
13.7K
Snippets
53
Records
67
Agent score
51%

What's inside Peashot

  1. Install Peashot (Ferrishot)

    main

    Peashot (also referred to as ferrishot in commands) can be installed via several package managers depending on your platform:

    Homebrew (macOS/Linux)

    brew install nik-rev/tap/ferrishot

    PowerShell (Windows)

    powershell -ExecutionPolicy Bypass -c "irm https://github.com/nik-rev/ferrishot/releases/latest/download/ferrishot-installer.ps1 | iex"

    Shell Script (Linux/macOS)

    curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nik-rev/ferrishot/releases/latest/download/ferrishot-installer.sh | sh

    Nix

    Add it to your flake.nix inputs:

    inputs.ferrishot.url = "github:nik-rev/ferrishot/main";
# Then use it in home-manager:
inputs.ferrishot.packages.${pkgs.system}.default

    Arch Linux (AUR)

    yay -S ferrishot-bin

    Cargo (Rust)

    cargo install ferrishot

  2. Basic usage and keyboard controls

    main

    Run ferrishot from the command line to start the application.

    Mouse Interaction

    • Select region: Left-click and drag.
    • Resize: Drag any side of the selected region. Hold Shift for granular control.
    • Move: Drag from the center of the region.

    Post-Selection Actions

    Once a region is selected, use the following keybindings:

    • Enter: Copy screenshot to clipboard.
    • Ctrl s: Save screenshot to a file (supports .png, .webp, .jpg, etc.).
    • Ctrl u: Upload screenshot to the internet (provides a link and QR code).

    Keyboard-Only Selection

    You can select a region without a mouse:

    1. Type t to pick the top-left corner.
    2. Type b to pick the bottom-right corner.

    Vim Motions

    Peashot supports Vim motions for navigation. Press ? within the app to view the available cheatsheet.

  3. Get started with Peashot: Hello, world!

    main
    To begin using Peashot, follow the 'Hello, world!' guide to set up your first project and verify your installation. This guide covers the most basic usage patterns to ensure your environment is correctly configured.

  4. Configure Peashot

    main

    Peashot uses a .kdl configuration format. You can customize the UI, color scheme, and keybindings.

    To generate a starting configuration file, run:

    ferrishot --dump-default-config

    This will write the default configuration to your system's config directory (e.g., /home/e/.config/ferrishot.kdl). You can then use the -C or --config-file flag to point to a custom configuration file.

  5. Add a new icon to Peashot

    main

    To register a new icon in the project, follow these two steps:

    1. Place your SVG file in the assets/icons/ directory and name it Icon.svg (or follow the existing naming convention).
    2. Update the load_icons! macro invocation located in src/icons.rs to include your new icon identifier.

    Once registered, the icon can be used within the ferrishot crate.

    // Example of how to use a registered icon in ferrishot
// This expands to an iced::widget::Svg
crate::icon!(Icon)

  6. How the Linux clipboard daemon works

    main

    On Linux, peashot uses a background daemon to provide clipboard access. This is necessary because the main process might not maintain the necessary connection to the clipboard manager.

    Daemon Invocation

    The daemon is triggered by passing a specific ID and command to the program's own executable. The ID used is __ferrishot_clipboard_daemon.

    Command Arguments

    The daemon expects the following argument structure:

    For Text:

    1. CLIPBOARD_DAEMON_ID (__ferrishot_clipboard_daemon)
    2. Copy type: text
    3. The text content string

    For Images:

    1. CLIPBOARD_DAEMON_ID (__ferrishot_clipboard_daemon)
    2. Copy type: image
    3. Width (usize)
    4. Height (usize)
    5. Path to the file containing the image bytes

    Implementation Note

    Developers should use the high-level set_text and set_image functions rather than attempting to invoke the daemon manually, as these functions handle the process spawning and argument serialization correctly.

    // The internal constant used for daemon signaling
pub const CLIPBOARD_DAEMON_ID: &str = "__ferrishot_clipboard_daemon";

  7. Define colors in KDL using CSS strings or Palette references

    main

    When configuring colors in Peashot (via KDL), you can use two types of values for KdlColor:

    1. CSS Color Strings: Standard CSS color strings (e.g., #ff0000, rgb(255, 0, 0), red) are parsed directly into a Color object.
    2. Palette References: By prefixing a string with the @ symbol (e.g., @brand-primary), you define a reference to a PaletteId. These references are resolved later against the project's defined palette.

    Internally, these are represented by the KdlColorValue enum.

    // Example KDL usage patterns
color_config {
    primary_color "#ff0000"      // CSS Color
    secondary_color "@accent"    // Palette Reference
}

  8. Understand the Output of an image action

    main

    When an image action is executed, it returns an Output enum and ImageData. The Output variant tells you the result of the operation:

    • Copied: The image was successfully placed in the clipboard.
    • Saved: The image is queued to be saved to a file (the specific path is resolved at the end of the application lifecycle).
    • Uploaded: The image was successfully uploaded to the internet. This variant contains:
      • data: An ImageUploaded object containing upload details.
      • file_size: The size of the file in bytes.
      • path: The local temporary path where the image was stored before upload.

    ImageData provides the dimensions of the processed image:

    • height: Height in pixels.
    • width: Width in pixels.

  9. Understand the Image Uploaded popup

    main

    When an image is successfully uploaded to the internet, Peashot displays an ImageUploaded popup. This popup provides the user with several ways to interact with the uploaded content:

    • QR Code: A visual representation of the image URL.
    • Copy URL: A button to copy the image link to the clipboard. Clicking this changes the button to a green checkmark (Check icon) for 3 seconds before reverting.
    • Image Metadata: Displays the image dimensions (width $\times$ height), file size (formatted in human-readable bytes), and the link expiration time.
    • Image Preview: A visual preview of the uploaded image.

    This popup is managed via the State and ImageUploadedData structures and is triggered by the Message::ImageUploaded variant.

  10. Define key sequences in configuration

    main

    Peashot uses the KeySequence type to represent a sequence of up to two keys. This allows for single keypresses or rapid double-keypresses (chords) to be used as triggers.

    Key Sequence Syntax

    When defining key sequences in text-based configuration, use the following rules:

    • Single Characters: Use the character directly (e.g., x).
    • Named Keys: Wrap the name of the key in angle brackets (e.g., <space>, <f32>, <enter>).
    • Sequences: Combine keys by placing them adjacent to each other. A sequence can contain at most two keys.
    • Special Characters:
      • To represent the < or > characters as keys, use double brackets (e.g., << for two < keys) or the specific sequence <> for < followed by >.

    Limitations

    • Maximum Length: Only sequences of up to 2 keys are supported. Attempting to define a sequence with 3 or more keys will result in an error.
    • Key Matching: The system searches for the first key in the sequence first. If the first key is not found, it searches for the second key.
    # Examples of valid key sequence strings:
x
gh
<space>x
<f32><f31>
<<
<>

  11. How to implement and add new commands

    main

    In peashot, commands are used to mutate the application state and can be bound to keybindings. To add a new command to the application, follow these three steps:

    1. Define the command: Use the declare_commands! macro in your module to generate the necessary command structures.
    2. Register the command: Add the module containing your new commands to the declare_global_commands! macro invocation to make them part of the global command set.
    3. Implement the handler: Implement the CommandHandler trait for the generated Command type to define its behavior.

    A Command is a subset of a Message that can receive a count. This count allows for repeated execution; for example, if j is bound to move down by 1px, typing 200j will execute the command 200 times.

    impl crate::command::CommandHandler for MyGeneratedCommand {
    fn handle(self, app: &mut crate::App, count: u32) -> iced::Task<crate::Message> {
        // Implement mutation logic here
        // Use `count` for repeated actions
        todo!()
    }
}

  12. Configure theme and colors in KDL

    main

    Peashot uses a KDL-based configuration for themes. You can define a palette of hex colors and then reference them in your theme keys using the @ symbol. Alternatively, you can provide raw hex values directly. Colors can also have an optional opacity property (from 0.0 to 1.0).

    All theme keys are stored in a flat format. When defining a color, you can use either a hex integer or a string referencing a palette name.

    theme {
  palette {
    black 0x00_00_00
  }
  // Reference a palette item
  cheatsheet_bg @black
  
  // Use a raw hex value with opacity
  cheatsheet_fg ffffff opacity=0.5
}