Skip to content

3. Lookups & Navigation

Jump to bottom
Jimmy Pautz edited this page Jul 8, 2026 · 3 revisions

Lookups & Navigation

The X-Ray plugin integrates directly into KOReader's reading view, allowing you to lookup entities and navigate mentions without disrupting your reading flow.

Quick In-Text Lookups

You don't have to navigate through the main menu every time you want to check a character's name or a term's definition.

  • Selection Popup: If you long-press a word or name while reading, you'll see a dedicated X-Ray button directly in the dictionary/selection popup.
    • Instant Lookup: Tapping the X-Ray button will immediately search your local data for that character, location, or term.
    • Inline Fetching: If the word isn't in your X-Ray database yet, the plugin will ask if you want to look it up using AI. This is a "Targeted Fetch" that only retrieves info for that specific name, making it much faster than a full book scan.
  • Highlights: If you long-press an existing highlight, the standard KOReader menu will pop up. There's an X-Ray option added in there too.
  • Keyboard Shortcut: If you happen to be using a device with a keyboard, pressing Alt + X will open the quick menu.

Tip

You can disable this feature entirely under Settings → X-Ray Mode.

Footnote-style Popup UI

In addition to the classic full-screen layout, the plugin features a Footnote-style Popup UI. When viewing descriptions, they can appear as an inline popup at the bottom of the screen, similar to KOReader's native footnote previews.

This allows you to quickly view descriptions for a character, location, or term without blocking your book view or closing your page. A Read More button is included to open the full classic entry if needed.

You can customize this layout via two independent toggles under Tools Menu → X-Ray → Settings → Display & UI Settings:

  • Use Footnote Style for In-text Lookups: Toggles the popup layout when tapping a name directly within the book text.
  • Use Footnote Style for Menu Lookups: Toggles the popup layout when selecting an entry from the plugin's menus (like the character list or glossary).

The popup body text automatically matches the font family and size of the book you are currently reading, so the X-Ray description feels like a natural extension of the page rather than a generic system dialog. If the document font is unavailable (e.g., on a PDF document), the popup falls back gracefully to KOReader's standard UI font at the same size.

Footnote Popup UI

Unit Conversion Underlines & Tooltips

When the Unit Converter is enabled, matching measurements in the book are highlighted using customizable underlines.

  • Interactive Tooltips: Tapping an underlined unit displays a small, footnote-style popup tooltip centered above the word.
  • Auto-Dismiss: The tooltip stays visible for a user-specified timeout (e.g., 2, 4, or 8 seconds) or remains open until you tap elsewhere on the screen (the "Never" setting).
  • Seamless Font Integration: Tooltips automatically inherit the font face and font size of the book you are currently reading, rendering within a clean popup bubble that points directly to the measurement.

Unit Converter Tooltip

Customizing the Visuals

Under Tools Menu → X-Ray → Settings → Unit Converter → Style & Underline Settings, you will find an interactive preview panel where you can customize how underlines and tooltips behave:

  • Underline Style: Choose between Solid, Wavy, Dotted, Dashed, or Invisible (if you want tap-to-convert but no visible marks).
  • Underline Thickness: Set the underline weight to 1px, 2px, or 3px.
  • Underline Intensity: Adjust the grey contrast level (Light, Medium, or Dark) so that underlines match your e-ink screen's refresh rate and reading preferences.
  • Tooltip Timeout: Select the display duration (2s, 4s, 8s, or Never).

Underline Styles & Preview

Gestures

You can tie the X-Ray menu to any of KOReader's gestures (like corner taps or edge swipes) for quick access:

  1. Go to Settings Menu → Taps and Gestures → Gesture Manager.
  2. Pick whatever gesture you prefer.
  3. Look for X-Ray Quick Menu under General in the action list and assign it.

Mentions Scanning & Navigation

Mentions scanning allows you to find every occurrence of a character, location, or historical figure throughout the book.

  • How to Use: Tap on any entity in the X-Ray menu and select "Find Mentions".
  • Wait for Scan: The initial scan for an entity's mentions happens in the "foreground" while you have the menu open. You should wait for the progress indicator to finish before closing the menu or attempting to navigate to a mention.
  • Navigation: Once the scan is complete, you will see a list of page numbers and context snippets. Tapping a mention will jump you directly to that page.

Mentions List

  • In-Text Banner: When you jump to a mention, a small navigation banner will appear at the top of the screen. This allows you to quickly cycle through occurrences (Next / Prev) or return to exactly where you were reading before (Back).

Mention Navigation Banner

Tip

You can enable or disable this feature entirely under Tools Menu → X-Ray → Settings → Display & UI Settings → Mentions Settings.

Related Pages

Clone this wiki locally