Talon

https://github.com/talonvoice/docs
Admin
Talon docs.
Tokens:2,190
Snippets:16
Trust Score:7.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Python Example: Interact with System Clipboard using talon.clip

Source: https://github.com/talonvoice/docs/blob/master/source/modules/clip.rst

This Python snippet demonstrates how to use the `talon.clip` module to retrieve current clipboard content, wait for changes, and set new content.

```python
from talon import clip

s = clip.get()
print(s)
s = clip.await_change()
print(s)
clip.set(s.upper() + ' clipboard test')
```

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

### Build Talon Documentation with Plain Virtualenv

Source: https://github.com/talonvoice/docs/blob/master/README.md

This snippet describes how to set up a plain Python virtual environment, install necessary dependencies like Sphinx, and build the Talon documentation. It produces both standard and single-page HTML documentation files for local viewing.

```Shell
pip install -r requirements.txt
make html singlehtml
```

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

### Execute AppleScript to Display Notification from Python

Source: https://github.com/talonvoice/docs/blob/master/source/modules/applescript.rst

This Python snippet demonstrates how to use the `talon.applescript` module to execute an AppleScript command. The example runs a simple AppleScript that displays a 'Hello world.' notification using 'System Events'.

```Python
from talon import applescript

applescript.run(r'''
tell application "System Events"
    display notification "Hello world."
end tell
''')
```

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

### Importing and Using talon.ctrl Module in Python

Source: https://github.com/talonvoice/docs/blob/master/source/modules/ctrl.rst

This Python snippet demonstrates how to import the `ctrl` module from the `talon` library and initiate a basic key press action. It serves as a minimal example of interacting with the module's functionalities.

```Python
from talon import ctrl

ctrl.key_press()
```

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

### Python: Display Desktop Notifications with talon.app.notify

Source: https://github.com/talonvoice/docs/blob/master/source/modules/app.rst

This Python snippet demonstrates how to use the `talon.app.notify` function to send desktop notifications. It includes examples for a basic notification with just a body and a more comprehensive notification with title, subtitle, body, and sound.

```python
from talon import app

app.notify(body='Hello world')
app.notify('Hello world',
              'Welcome to Talon',
              'Enjoy your stay.', sound=True)
```

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

### Python Example: Watching File System Changes with talon.fs

Source: https://github.com/talonvoice/docs/blob/master/source/modules/fs.rst

This Python snippet demonstrates how to use the `talon.fs.watch` function to monitor a specified file or directory for changes or deletion. It defines a simple callback function `on_change` that prints messages indicating whether the path was changed or deleted.

```python
from talon import fs

def on_change(path, exists):
    if exists:
        print('changed', path)
    else:
        print('deleted', path)

fs.watch('/path/to/stuff', on_change)
```

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

### talon.ctrl Module API Reference

Source: https://github.com/talonvoice/docs/blob/master/source/modules/ctrl.rst

Comprehensive API documentation for the `talon.ctrl` module, detailing functions for simulating keyboard and mouse interactions and providing a reference for supported key names.

```APIDOC
talon.ctrl Module Functions:

key_press(key: str, cmd: bool = False, shift: bool = False, ctrl: bool = False, alt: bool = False, fn: bool = False, down: bool = False, up: bool = False, hold: int = 0, wait: int = 0)
	Description: Simulate a key press. To press and hold, pass `down=True`. To release, pass `up=True`.
	Parameters:
		key: The key to press. Can be any symbol your keyboard can type, as well as any special key from Key Names.
		cmd, shift, ctrl, alt, fn: Modifier keys to apply.
		down, up: Hold or release the key.
		hold: Duration in microseconds to hold the key down.
		wait: Duration in microseconds to wait between key presses.

mouse(x: int, y: int, dx: int = 0, dy: int = 0)
	Description: Move the mouse.
	Parameters:
		x, y: Absolute mouse position.
		dx, dy: Relative mouse movement.

mouse_pos() -> (x: int, y: int)
	Description: Get the cursor's current position.
	Returns: A tuple (x, y) representing the current mouse coordinates.

mouse_click(x: int = None, y: int = None, button: int = 0, times: int = 1, down: bool = False, up: bool = False, hold: int = 0, wait: int = 0)
	Description: Click the mouse. If `x` and `y` are not None, click at coordinates (x, y). Otherwise, click at the current mouse position.
	Parameters:
		x, y: Absolute mouse position, can be omitted to click in the current position.
		button: `0` is left click, `1` is right, `2` is middle, `3+` are additional mouse buttons.
		times: Number of clicks.
		down, up: Hold or release the button.
		hold: Duration in microseconds to hold the mouse button.
		wait: Duration in microseconds to wait between clicks.

mouse_buttons_down() -> list[int]
	Description: Returns which mouse buttons are currently pressed as a list of numbers starting with `0`.
	Returns: A list of integers representing currently pressed mouse buttons.

mouse_scroll(y: int = 0, x: int = 0)
	Description: Scroll the mouse.
	Parameters:
		y: Vertical distance (positive values move down).
		x: Horizontal distance (positive values move right).

```

```APIDOC
Key Names Reference:
  This table lists special key names recognized by `talon.ctrl.key_press`.
  Name, Alternate
  alt
  backspace, bksp
  capslock
  cmd
  ctrl
  delete, del
  down
  end
  escape, esc
  f1
  f2
  f3
  f4
  f5
  f6
  f7
  f8
  f9
  f10
  f11
  f12
  f13
  f14
  f15
  f16
  f17
  f18
  f19
  f20
  fn
  help
  home
  left
  mute
  pageup, pgup
  pagedown, pgdown
  return
  enter
  right
  ralt
  rctrl
  rshift
  shift
  space
  tab
  up
  voldown
  volup
  keypad_clear
  keypad_enter
  keypad_decimal
  keypad_plus
  keypad_divide
  keypad_minus
  keypad_equals
  keypad_0
  keypad_1
  keypad_2
  keypad_3
  keypad_4
  keypad_5
  keypad_6
  keypad_7
  keypad_8
  keypad_9
```

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

### Connect to Talon REPL

Source: https://github.com/talonvoice/docs/blob/master/source/introduction.rst

This snippet provides the command to connect to the Talon Read-Eval-Print Loop (REPL). The REPL allows users to interact with Talon's embedded Python environment for debugging, testing scripts, and executing commands in real-time while the application is running.

```bash
~/.talon/.venv/bin/repl
```

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

### AppleScript Module API Reference

Source: https://github.com/talonvoice/docs/blob/master/source/modules/applescript.rst

API documentation for the `talon.applescript` module, detailing its functions for interacting with AppleScript. It includes methods for syntax checking and running AppleScript code, along with their parameters, return types, and error handling.

```APIDOC
Module: applescript
  Function: check(source: str)
    Description: Check AppleScript `source` for syntax errors. Raises `applescript.ApplescriptErr`.
  Function: run(source: str) -> str
    Description: Run AppleScript `source`. Raises `applescript.ApplescriptErr` on error. Returns a raw AppleScript encoding of the script's result.
```

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

### Build Talon Documentation with Pipenv

Source: https://github.com/talonvoice/docs/blob/master/README.md

This snippet details the process of cloning the Talon documentation repository and building the HTML documentation using Pipenv. It generates both multi-page and single-page HTML outputs, which can then be accessed locally.

```Shell
git clone https://github.com/talonvoice/docs
cd docs
pipenv run make html singlehtml
```

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

### API Reference for talon.clip Module

Source: https://github.com/talonvoice/docs/blob/master/source/modules/clip.rst

Detailed documentation for the `talon.clip` module, outlining its functions, parameters, and return types for clipboard interaction.

```APIDOC
talon.clip module:
  get() -> str
    Get the contents of the clipboard.
  set(contents: str)
    Set the contents of the clipboard.
    contents: The string to set as clipboard content.
  serial() -> int
    The clipboard serial increments on each clipboard update and can be used to see if the clipboard has changed.
  await_change(timeout=0.5, serial=None) -> str or None
    Wait for the clipboard contents to change and return the new contents.
    timeout (float): If the clipboard hasn't changed after this many seconds, returns None.
    serial (int): If not provided, defaults to serial().
```

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

### Talon Audio Noise Module API Reference

Source: https://github.com/talonvoice/docs/blob/master/source/modules/audio.rst

Detailed API documentation for the `noise` submodule within `talon.audio`, outlining the `register` and `unregister` functions, their parameters, and valid noise topics for event callbacks.

```APIDOC
Module: audio.noise
  Function: register(topic, cb: function)
    Description: Register a noise callback.
    Parameters:
      topic: string - Valid topics include: "" (all noises), "hiss_start", "hiss_end", "pop".
      cb: function - The callback function to register.
  Function: unregister(topic: str, cb: function)
    Description: Unregister a noise callback.
    Parameters:
      topic: str - The specific topic to unregister from.
      cb: function - The callback function to unregister.
```

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

### API Reference: talon.fs.watch Function

Source: https://github.com/talonvoice/docs/blob/master/source/modules/fs.rst

Documents the `watch` function within the `talon.fs` module. This function registers a callback to be invoked when the specified file system path undergoes changes (e.g., creation, modification, deletion).

```APIDOC
talon.fs.watch(path, cb)
  path: The file system path to monitor for changes.
  cb: A callback function with the signature `cb(path: str, exists: bool)`.
    path: The specific path that triggered the event.
    exists: A boolean indicating if the path currently exists (True for changes/creation, False for deletion).
```

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

### Registering a Global Noise Callback in Talon Python

Source: https://github.com/talonvoice/docs/blob/master/source/modules/audio.rst

Demonstrates how to register a Python function to receive all noise events from the Talon audio system. The provided callback simply prints the noise event details to the console when triggered.

```python
from talon import audio

def on_noise(noise):
    print(noise)
audio.noise.register('', on_noise)
```

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

### APIDOC: talon.app.notify Function Reference

Source: https://github.com/talonvoice/docs/blob/master/source/modules/app.rst

Detailed API documentation for the `notify` function within the `talon.app` module. This function is used to display desktop notifications.

```APIDOC
function:: notify(title: str, subtitle: str, body: str, sound: bool)
  Display a desktop notification, optionally playing a sound.
  Parameters:
    title (str): The title of the notification.
    subtitle (str): The subtitle of the notification.
    body (str): The main content of the notification.
    sound (bool): If True, a sound will be played with the notification.
```

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

### API Reference: talon.fs.unwatch Function

Source: https://github.com/talonvoice/docs/blob/master/source/modules/fs.rst

Documents the `unwatch` function within the `talon.fs` module. This function removes a previously registered callback from monitoring a specific file system path, effectively stopping the watch.

```APIDOC
talon.fs.unwatch(path, cb)
  path: The file system path that was being watched.
  cb: The specific callback function to remove from the watch list for the given path.
```
Tokens:
Raw