Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Docs for rustcast-cross

Warning

These docs are probably incomplete and wonky. The most up to date docs are in the doc comments, which is kinda suboptimal, but it is what it is

Where should I start?

I recommend looking at the configuration guide to get a better idea of how to configure rustcast.

Welcome to the RustCast contributing guide!

Thank you for wanting to contribute to RustCast!

Some areas you can help work on are

  1. Bug fixes
  2. New Features
  3. Help people in solving their github issues

For bug fixes, and helping people to solve their github issues: see [https://github.com/rustcast-cross/rustcast-cross/issues] For features, see the planned features in the README or the existing feature list

Code Guidelines

  1. All code must be formatted with cargo fmt
  2. Code must not be malicious or be intended to harm someones device
  3. All features added must work as intended
  4. Code must compile…
  5. A video recording / screenshot would be an added bonus in getting your pull request merged faster.
  6. Being warning-free with pedantic lints (clippy -- "-Wclippy::pedantic") is nice, but not necessary
  7. Please follow conventional commits
  8. Please add to the changelog

Codebase

.
├── assets
│   ├── icon              # The icon
|   │   ├── icon_opt.svg  # Same stuff as icon.svg, minus the inkscape metadata
|   │   ├── icon.svg      # The icon SVG (with inkscape metadata)
|   │   ├── icon64.png    # The icon bitmap in various sizes
|   │   ├── icon128.png   # |
|   │   ├── icon256.png   # |
|   │   └── icon512.png   # |
|   |
│   └── macos         # MacOS stuff, you can look deeper if it's relevant to what you're doing
├── bundling          # MacOS stuff
│   ├── entitlements.plist
│   ├── icon.icns
│   └── Info.plist
├── debian            # Debian stuff
├── docs              # Website and documentation related stuff. If something new is added to config,
│                     # then modify this as well before PR-ing
├── Cargo.lock 
├── Cargo.toml
├── CONTRIBUTING.md   # Contributing guidelines and codebase structure
├── EXTENSIONS.md     # Discussions about extensions implementation
├── LICENSE.md        # License file
├── README.md         # Readme file
├── FEATURES.md       # List of features currently implemented that should be updated when new 
├── scripts           # Fancy scripts for building on macos (presumably)
└── src
    ├── app
    │   ├── apps.rs             # Logic for the "apps" / commands that rustcast can perform
    │   ├── menubar.rs          # All the code related to the tray icon / menu bar icon
    │   ├── pages.rs            # TODO: convert to pages/mod.rs for consistency
    │   ├── pages               # Definitions for "pages" of the app
    │   │   ├── clipboard.rs
    │   │   ├── common.rs
    │   │   ├── emoji.rs
    │   │   ├── prelude.rs      # Prelude for individual pages
    │   │   └── settings.rs
    │   └── tile                # Logic for the tile (rustcast window)
    │       ├── mod.rs
    │       ├── search_query.rs
    │       ├── elm.rs          # Logic for the elm architecture of the rustcast window (New and View)
    │       └── update.rs       # Logic for the updating (elm architecture update) of the rustcast window
    ├── app_finding             # All the logic for app discovery
    |   ├── mod.rs
    │   ├── linux.rs            # Platform specific code
    │   ├── macos.rs            # |
    │   └── windows.rs          # |
    ├── config                  # Where configs are defined
    |   ├── mod.rs
    |   ├── include_patterns.rs # Custom serde parsers
    |   └── patterns.rs         # | 
    ├── cross_platform          # Stuff that's platform specific
    │   ├── mod.rs
    │   ├── linux.rs
    │   ├── macos
    │   |   ├── mod.rs
    |   |   └── haptics.rs      # Haptics stuff, ask secretised if you don't understand this stuff
    │   └── windows
    │       ├── mod.rs
    │       ├── appicon.rs      # Some code for extracting app icons (slightly wonky)
    │       └── app_finding.rs  # TODO: move this to the right place
    ├── unit_conversion         # Stuff for converting between units         
    │   ├── mod.rs
    │   └── defs.rs
    ├── app.rs                  # All code related to the app
    ├── calculator.rs           # Calculator logic 
    ├── commands.rs             # Logic for different commands
    ├── clipboard.rs            # Logic for the clipboard history feature of rustcast
    ├── icon.rs                 # Bundles icons into the binary
    ├── styles.rs               # Styles for the app
    ├── main.rs                 # Start app
    └── utils.rs                # Common functions that are used across files

0.6.0

  • All sorts of random stuff, nobody really kept track of any of it

< 0.6.0

See upstream

Configuring rustcast

Rustcast is designed to be reasonably configurable in general. Because of this, there’s a config file you can edit to change how it does things™.

If rustcast can’t find the config file at

  • ~/.config/rustcast/config.toml on linux/macos
  • %LOCALAPPDATA%/rustcast/config.toml on windows

it creates a new one at the location, with the data in the default config

“Root” configs

toggle_hotkey = "ALT+Space"
placeholder = "Time to be productive!"
search_url = "https://google.com/search?q=%s"
haptic_feedback = false
show_trayicon = false
shells = []
index_dirs = [] # Not actually empty, it's just far too user specific
index_exclude_patterns = []
index_include_patterns = []

  • toggle_hotkey, clipboard_hotkey
    These hide and show the rustcast window, just opening to different pages. toggle_hotkey opens to the main search page, clipboard hotkey opens to the clipboard history page.

    You MUST Provide a Key, but a modifier is optional. The “letter” keys are in the format Key<LETTER> where the letter is always captials, e.g. KeyG, KeyR

    Some of the common valid modifiers (and the respective MacOS Key it maps to):

    • SUPER (Command)
    • ALT (Option)
    • CTRL (Control)
    • SHIFT (Shift)

    see the full list here

    +s are used as separators between them, e.g. CTRL+SHIFT+KeyA, which is parsed as the modifiers CTRL and SHIFT, with the key A.

    There are too many keys to list exhaustively, the full list is in the enum definition here

  • placeholder
    This is a string that contains the search input placeholder text, e.g.

    Displayed search input where placeholder is set to “Time!”

    (yeah, I was feeling a bit goofy when setting this)

  • search_url
    This is the search engines URL thats used when doing web searches (using the ? suffix)

    A simple way to think about this is that for your search engine of choice, you have to put: %s where the query will go. If you want to switch to duckduckgo, or bing (why?) you simply need to set it to https://duckduckgo.com/search?q=%s or https://bing.com/search?q=%s respectively. For google, you can refer to the default config, and rustcast also uses google by default.

    Google was chosen as the default because it’s the most popular one.

  • haptic_feedback (macos only)

    Note

    All secretised’s words, I don’t actually understand what this does myself

    A random feature I added, you can have the macos haptic feedback be triggered when you type in rustcast. I added this for fun, but if you want to add this you can. This is a boolean value (AKA true or false), where true means it will enable haptic feedback.

  • show_trayicon This is if you don’t want the menubar icon, you can choose to disable the RustCast menu bar icon.

  • shells See the associated file on the format

  • index_dirs

    Important

    Only really known to work on windows

    The dirs to index. This can be in the format <path> or the format <path>:<maximum depth>. If the maximum depth is set, doesn’t index any files deeper than that depth.

  • index_exclude_dirs and index_include_dirs

    index_exclude_dirs is a list of any directories to exclude from the search. index_include_dirs is a list of directories to index anyway, ignoring index_exclude_dirs.

Buffer rules

[buffer_rules]
clear_on_hide = true
clear_on_enter = true

clear_on_hide and clear_on_enter mean whether the “buffer” (aka the text box’s content), should be cleared when the app is hidden / entered

Modes

Warning

This hasn’t been implemented in the fork yet, this is just kept for when i get around to porting it over

Modes are similar to macos focus modes.

You can run a shell script to disable / enable your WM, turn on / off your notifications, or do pretty much anything.

Modes are still a relatively trial feature, so don’t expect a lot from it just yet (It is v0.5.9 at the time of writing this) They lack a bunch of features, but they will be improved over time.

Modes are fairly simple to add, but much more annoying to make. The different between modes and shell scripts is that modes are meant to be shown in the menu bar icon and in the rustcast footer.

[modes]
default = "~/.config/rustcast/hello_modes.sh" # overrides the "do nothing" default mode
presentation = "~/.config/rustcast/presentation.sh"

This creates 1 new mode and overrides the default mode.

Now, when u switch to the presentation mode, the presentation.sh file (which should be stored inside the rustcast config directory) is run. And when you switch back to the default mode, it will run the “hello_modes.sh” (in the place we defined)

Shell Commands

A shell command can do as much as modes can, but they can have custom icons + different display names / search names

A shell command is configured slightly differently:

[[shells]] # note that its encased in double square brackets

command = "osascript -e 'tell application \"Spotify\" to play next track'"
icon_path = "/Applications/Spotify.app/Contents/Resources/AppIcon.icns"
alias = "Next Spotify Song" 
alias_lc = "next"
  • command is the shell command to run (can be a shell script as well, which is useful for longer scripts)
  • icon_path can point to a png, jpg, or icns
  • alias is the text displayed
  • alias_lc is the text used to search

As seen in the below image:

  • The spotify icon is loaded from icon_path
  • The yellow rectangle is whats used to search, aka alias_lc (Ideally should be fully lowercased)
  • The alias is the one in the dark red rectangle image

Buffer Rules and Theme Config:

Default config

[theme]
text_color = [0.95, 0.95, 0.96]
background_color = [0.09, 0.09, 0.09]
blur = false
show_icons = true
show_scroll_bar = true

  • text_color
    This is the text color that rustcast should use inside the app with the format text_color = [R, G, B].

  • background_color
    This is the background color that rustcast should use inside the app with the same format as text_color but different name.

  • show_icons Sets whether rustcast displays app icons or not.

  • show_scroll_bar If false, stops rustcast from displaying a scrollbar in the app list.

Logger configuration

Default

This is the only logger added by default

[log.stdout]
type = "stdout"
level = "INFO"
use_ansi = true

This prints all logs at the INFO level or above to stdout, with ansi colouring

Format

The log key is a table of each logger. The keys are mostly irrelevant, it’s really only used for logging. The properties are

  • type (stdout or file)
    The logger type. stdout logs to stdout, while file logs to a provided location

  • level (ERROR, WARN, INFO, DEBUG, TRACE case insensitively) The minimum level to log. The levels are (in order)

    1. ERROR Critical errors
    2. WARN General warnings
    3. INFO Relatively unimportant but nice info
    4. DEBUG Slightly noisier logs that are mostly useful for debugging
    5. TRACE Really noisy logs. You probably shouldn’t ever print these to stdout.

    e.g. if you set it to INFO, it’ll print logs with the levels INFO, WARN, and ERROR.

  • use_ansi (true / false) If true, prints out logs with ANSI colours. You probably shouldn’t use this when logging to files.

  • env_filter (optional string) An envfilter to apply to the data. For more info, see tracing_subscriber’s docs

  • path (only when type is file) The path to output the logs to

Default configuration

This is automatically generated by rustcast the first time you run it.

toggle_hotkey = "ALT+Space"
placeholder = "Time to be productive!"
search_url = "https://google.com/search?q=%s"
haptic_feedback = false
show_trayicon = false
shells = []
index_dirs = [] # Not actually empty, it's just far too user specific
index_exclude_patterns = []
index_include_patterns = []

[buffer_rules]
clear_on_hide = true
clear_on_enter = true

[theme]
text_color = [0.95, 0.95, 0.96]
background_color = [0.09, 0.09, 0.09]
blur = false
show_icons = true
show_scroll_bar = true

[log.stdout]
type = "stdout"
level = "info"
use_ansi = true