Skip to content

pages

This directory establishes a standardized voice-control interface for applications that use page-based navigation, such as PDF viewers, e-readers, document editors, and presentation software.

By defining a reusable Talon tag (user.pages) and a set of abstract page-navigation actions, this module decouples the voice commands from the application-specific implementations. This allows users to use the same voice commands across different applications while letting developers implement the underlying keystrokes or APIs required for each specific app.

How It Works

The page navigation capability is split into two components: 1. The Declaration/Interface (pages.py): Defines the user.pages tag and specifies the actions that any compatible application should implement. 2. The Voice Commands (pages.talon): Maps natural spoken phrases to the actions defined in the Python file, which are active only when the user.pages tag is enabled for the active application.

Core Components

pages.py

This file defines the programming interface (API) for page navigation.

  • Tag Definition: Registers the user.pages tag with Talon. Application-specific contexts (e.g., for Acrobat Reader or Okular) will activate this tag when they are in focus.
  • Abstract Actions: Establishes several actions that act as placeholders. These must be overridden in application-specific scripts to perform the actual keystrokes or API calls:
    • page_current(): Returns the current page number as an integer.
    • page_jump(number): Jumps directly to a specified page.
    • page_final(): Jumps to the end of the document.
    • page_rotate_right() / page_rotate_left(): Rotates the document 90 degrees.
  • Helper Implementations: Provides default logic for sequential navigation by leveraging the abstract actions:
    • page_next(): Automatically calculates and jumps to the next page (page_current() + 1) using page_jump().
    • page_previous(): Calculates and jumps to the previous page (page_current() - 1) using page_jump().

pages.talon

This file defines the voice command grammar. It activates only when a context assigns the user.pages tag.

  • Dependencies: It automatically activates the user.navigation tag to ensure general navigation commands (like scrolling) are also available alongside page-specific controls.

  • Voice Bindings: Maps spoken commands directly to the actions defined in pages.py:

    • "page next" $\rightarrow$ user.page_next()
    • "page last" $\rightarrow$ user.page_previous()
    • "go page <number>" $\rightarrow$ user.page_jump(number)
    • "go page final" $\rightarrow$ user.page_final()
    • "rotate right" $\rightarrow$ user.page_rotate_right()
    • "rotate left" $\rightarrow$ user.page_rotate_left()

Implementing Page Navigation for an Application

To enable these commands in a specific PDF reader or application, a developer would write an application-specific context file that:

  1. Activates the user.pages tag when the application is active.
  2. Overrides the abstract actions (like page_jump or page_rotate_right) with the keyboard shortcuts specific to that application. For example, in a PDF viewer where Ctrl+G opens the page jump dialog, page_jump(number) would be implemented to press Ctrl+G, type the number, and press enter.