storm/I38

Files

T

Storm Dragon 2b338e44c6 Help page refactored. the example page received only positive feedback, so I guess it's good to go.

2026-07-20 00:22:07 -04:00

20 KiB

Raw Permalink Blame History

Welcome to I38

Note: This help guide has been tailored to your specific configuration. You've chosen @WEBBROWSER@ as your web browser, @MODKEY@ as your mod key, and your screen reader setting is @SCREENREADER@.

I38 is a desktop-like environment for blind and low-vision people based on the i3 window manager. All I38 desktop functionality can be accessed and controlled from the keyboard.

Quick Start

Use this section when you want the shortest path to moving around I38. You can return to this guide whenever you need it by pressing @MODKEY@ + Shift + F1.

Alt + Tab: Move focus to the next window in the current workspace.
Alt + Shift + Tab: Move focus to the previous window in the current workspace.
@MODKEY@ + Return: Open a terminal.
@MODKEY@ + F1: Open the applications menu.
@MODKEY@ + F2: Open the run dialog.
@MODKEY@ + F4: Close the focused window.
@MODKEY@ + BackSpace: Toggle fullscreen for the focused window.
Control + F1 through F10: Switch to workspace 1 through 10.
Control + Shift + F1 through F10: Move the focused window to workspace 1 through 10.
@RATPOISONKEY@: Enter Ratpoison Mode.
@PERSONALMODEKEY@ @RATPOISONKEY@ followed by apostrophe: List windows in the current workspace.
Control + Alt + Tab: Enter Panel Mode.
F1 in Ratpoison Mode or Panel Mode: Show the keybindings for that mode.
Escape or Control + g: Exit Ratpoison Mode, Panel Mode, or Personal Mode without taking action.

Navigating This Document

This guide is organized by heading level so screen reader users can move through it quickly.

Heading level 1 is the document title.
Heading level 2 marks major topics such as Quick Start, Modes, Panel Mode, Accessibility Features, and Updating I38.
Heading level 3 marks subsections inside a topic.
Heading level 4 is used only for deeper reference material.

With common screen-reader browse commands, press 1 to jump to the heading level 1 title near the beginning of the document. Press 2 to move between major topics. Press 3 to move through subsections inside a topic. Press 4 to move through deeper reference sections when they are present. The exact command may vary by screen reader and browser, but heading navigation is the fastest way to learn this document's layout.

Basic Concepts

Workspaces

Workspaces are separate work areas for organizing applications. I38 provides 10 workspaces.

Control + F1 through F10: Switch to workspace 1 through 10.
Control + Shift + F1 through F10: Move the focused window to workspace 1 through 10.

Window Management

I38 uses a tabbed layout by default. In this layout, the focused window takes the screen, and you switch between windows much like switching between tabs.

Alt + Tab: Move focus to the next window.
Alt + Shift + Tab: Move focus to the previous window.
@MODKEY@ + Return: Launch a terminal.
@MODKEY@ + F4: Close the focused window.
@MODKEY@ + BackSpace: Toggle fullscreen.
@RATPOISONKEY@ followed by apostrophe: List windows in the current workspace.
@MODKEY@ + Shift + dash: Move the focused window to the scratchpad.
@MODKEY@ + Shift + equals sign: Bind the focused window to the scratchpad so it opens there in the future.
@MODKEY@ + dash: Show or cycle scratchpad windows.

Modes in I38

I38 uses modes to provide many keyboard shortcuts without taking over every key all the time. A mode is entered with a specific shortcut, then the next key chooses an action.

Default Mode

Default Mode is the normal mode for working with applications. Most commands in Default Mode start with your mod key, @MODKEY@.

TOPLEVELKEYBINDINGS

Ratpoison Mode

Ratpoison Mode provides quick access to common actions with short key sequences. To enter Ratpoison Mode, press @RATPOISONKEY@. After pressing that key, press one of the mode commands below.

c: Launch a terminal.
e: Open the text editor, @TEXTEDITOR@.
@MODKEY@ + e: Open the email client.
f: Open the file manager, if one was configured.
i: Launch the IRC client, if one was configured.
w: Launch the web browser, @WEBBROWSER@.
s: Launch Steam Big Picture, if Steam is installed.
k: Close the focused window.
m: Launch Mumble, if it is installed.
p: Launch Pidgin, if it is installed.
Print: Perform OCR and save to the clipboard, if OCR desktop support is installed.
@MODKEY@ + r: Perform OCR and save to the clipboard, if OCR desktop support is installed.
@MODKEY@ + s: Adjust screen brightness or enable the screen curtain, if xrandr is available.
F1: Show Ratpoison Mode keybindings.
Escape or Control + g: Exit Ratpoison Mode without taking action.
Shift + c: Restart the Cthulhu screen reader, if installed.
Shift + o: Restart the Orca screen reader, if installed.
Shift + t: Toggle the configured screen reader, if one was configured.
Control + semicolon: Reload the I38 configuration.
Control + Shift + semicolon: Restart i3 in place.
@MODKEY@ + q: Exit i3 and end the X session, after confirmation.
Control + @MODKEY@ + q: Exit i3 and end the X session, after confirmation.
exclamation mark: Open the run dialog.
Alt + b: Check battery status.
g: Check game controller status.
a: Open the AI assistant.
Alt + Shift + r: Toggle desktop audio recording and slideshow video conversion.

Bypass Mode

Bypass Mode passes keys directly to the focused application. This is useful for applications that need many keyboard shortcuts of their own.

@MODKEY@ + Shift + BackSpace: Enter Bypass Mode.
@MODKEY@ + Shift + BackSpace: Exit Bypass Mode and return to Default Mode.

Personal Mode

Personal Mode is a user-defined mode for your own keybindings. I38 will not overwrite the personal mode customizations when you regenerate your I38 configuration.

Entering Personal Mode

When you first run I38, you are prompted to choose a Personal Mode key. If you selected one, press that key to enter Personal Mode. If you are using Stormux with the default layout, the key for Personal Mode is Control + Escape.

Adding Custom Bindings

To add your own shortcuts, edit ~/.config/i3/customizations. This file is not overwritten by I38.

Inside the mode "personal" { ... } block, you can add i3 bindsym commands. End each binding with , mode "default" when you want Personal Mode to exit after the action.

Example:


mode "personal" {
    bindsym f exec firefox, mode "default"
    bindsym Shift+f exec firefox --private-window, mode "default"
    bindsym Escape mode "default"
    bindsym Control+g mode "default"
}

In this example, pressing your Personal Mode key followed by f launches Firefox, and Shift + f launches a private Firefox window.

Default Personal Mode Bindings

F1: Show Personal Mode keybindings.
Escape or Control + g: Exit Personal Mode without taking action.

Panel Mode

Panel Mode provides quick access to information displays and utility panels. To enter Panel Mode, press Control + Alt + Tab. A distinctive sound plays when Panel Mode is active.

Panel Mode automatically returns you to Default Mode after a selection is made or when you cancel with Escape or Control + g.

Panel Mode Commands

F1: Show Panel Mode keybindings.
w: Display weather information.
Shift + w: Open the Magic Wormhole file transfer GUI.
t: Open the system tray, if waytray was installed when the i3 config was generated.
s: Show system information.
r: Open the reminder panel, if remind is installed.
n: Launch the notes application.
b: Open Bluetooth, if blueman was installed when the i3 config was generated.
@MODKEY@ + b: Speak a quick battery status.
Shift + b: Show detailed battery information.
m: Launch the password manager.
p: Show power options.
Control + @MODKEY@ + l: Lock the screen, if a screen lock method is configured.
Escape or Control + g: Exit Panel Mode without taking action.

System Information Panel

The system information panel, s in Panel Mode, displays system statistics such as CPU usage, memory usage, disk space, and network status.

Battery Information

The battery report has two modes. Press @MODKEY@ + b in Panel Mode for a concise spoken announcement of charge level and charging state. Press Shift + b in Panel Mode for the detailed report. The detailed report is shown in a reviewable text dialog instead of spoken aloud, so the full details can be navigated with the arrow keys.

The detailed report can include charge, status, health, chemistry, voltage, current, power draw, and cycle count when the hardware exposes them. The quick report is also available with Alt + b in Ratpoison Mode. If acpi is installed, it is used for the report. Otherwise, I38 reads /sys/class/power_supply directly. In the detailed dialog, press Control + Home to jump back to the top of the text.

Weather Panel

The weather panel, w in Panel Mode, provides current weather conditions and forecast information for your configured location.

File Transfer With Magic Wormhole

The Magic Wormhole panel, Shift + w in Panel Mode, provides a graphical interface to the Magic Wormhole command-line application so you can securely share files with others.

Notes Application

The notes panel, n in Panel Mode, provides a simple application for creating single-line notes with automatic expiration.

Create text notes quickly.
Set notes to automatically delete after a specified time period.
Lock important notes to prevent automatic deletion.
Let temporary notes expire after their set time limit.

Reminder Panel

The reminder panel, r in Panel Mode, offers the reminder functionality described in the Reminders and Notifications section. It was previously in Ratpoison Mode but has been moved to Panel Mode because it is a better fit.

System Tray

If waytray is installed, I38 provides keyboard-accessible system tray functionality through the StatusNotifierItem protocol. This lets you interact with applications that use the system tray for status indicators or background controls.

Features:

Access minimized applications.
View and interact with status indicators such as network, volume, and VPN items.
Control background services through their tray context menus.
Use keyboard navigation without a mouse.

Usage:

Press Control + Alt + Tab to enter Panel Mode.
Press t to open the system tray window.
Use the arrow keys to navigate between tray items.
Press Enter or Space to activate the selected item.
Press Menu or Shift + F10 to open context menus.
Press Escape to close the tray window.

Installation:

waytray is an optional dependency. If installed, I38 configures it to provide only system tray functionality. Battery, weather, and system information are disabled in waytray to avoid duplicating I38's panel utilities.

Without waytray installed, applications that require a system tray may not work with I38. Many applications also provide ways to run without a tray.

Accessibility Features

If you configured a screen reader, I38 uses @SCREENREADER@. The screen reader provides spoken feedback about what is happening on screen as long as there is a window. If no window is open and you need to change something screen-reader related, press @MODKEY@ + Control + d to bring up the desktop, then use your screen reader keys.

@RATPOISONKEY@ then Shift + t: Toggle the configured screen reader.
@RATPOISONKEY@ then Shift + o: Restart Orca, if installed.
@RATPOISONKEY@ then Shift + c: Restart Cthulhu, if installed.
@MODKEY@ + Shift + F5: Interrupt speech.

Braille Display Support

If you enabled braille display support during setup, I38 starts XBrlAPI automatically to provide braille output from your screen reader.

Low-Vision Support

During setup, I38 asks for the window title font size used by i3. The default is larger than standard i3 so window titles and tab labels are easier to see.

@MODKEY@ + Control + m: Move the mouse pointer to the center of the focused window.
@MODKEY@ + Control + z: Start xzoom magnifier, if it was installed when your i3 config was generated.
Ratpoison Mode, then @MODKEY@ + s: Adjust screen brightness or enable the screen curtain, if xrandr is available.

I38 keeps windows in a tabbed layout by default. This gives the focused app most of the screen and reduces visual clutter, but it also means switching windows is usually done with Alt + Tab, the window list, or workspace keys rather than by clicking overlapping windows.

OCR

If the required dependencies are installed, you can use OCR to read text from images or inaccessible applications.

@MODKEY@ + F5: Perform OCR on the entire screen and speak the content.
Ratpoison Mode, then Print: Perform OCR and save to the clipboard.
Ratpoison Mode, then @MODKEY@ + r: Perform OCR and save to the clipboard.

Screen Lock

If you enabled a screen lock during setup, press Control + Alt + Tab to enter Panel Mode, then press Control + @MODKEY@ + l to lock the screen.

I38 can configure either the legacy I38 PIN lock or I38Lock. The PIN lock is a privacy screen only, not a secure system lock. I38Lock is a true PAM-backed locker and unlocks with your account password. On Stormux, install I38Lock from the repository. The I38Lock repository is https://git.stormux.org/storm/i38lock. I38Lock requires Cthulhu or Orca 50 or newer for screen-reader feedback.

I38 enables only one lock method at a time. When a screen lock method is configured, I38 can also autolock after an idle timeout. The default is never. Autolock is X11/i3-only and requires xprintidle; if playerctl is installed, I38 avoids autolocking during likely video playback.

If you chose to lock the screen when I38 starts, I38 launches the configured lock shortly after i3 startup. With the PIN lock, startup lock is meant to prevent casual snooping, not to secure the system against a determined user.

Sound Effects

I38 provides audio feedback for many actions.

Window open and close sounds confirm window changes.
Mode sounds confirm when you enter or leave a mode.
Workspace sounds confirm workspace changes.
Fullscreen sounds confirm fullscreen changes.

I38 provides several ways to open applications.

@MODKEY@ + F1: Open the applications menu.
@MODKEY@ + F2: Open the run dialog.
Ratpoison Mode, then exclamation mark: Open the run dialog.
Ratpoison Mode, then one of the application keys listed in the Ratpoison Mode section: Open a common application directly.

The applications menu is organized by category. The run dialog suggests previous entries, installed applications, and commands from your PATH as you type. Enter a path such as ~/Downloads/ to browse its files and subdirectories. Use the up and down arrows to select a suggestion, Tab to insert it into the entry, and Enter to open or run it.

Reminders and Notifications

I38 includes integration with the remind program for managing reminders.

Control + Alt + Tab, then r: Open the reminder tool.

The reminder tool can create one-time, daily, weekly, monthly, and custom reminders. I38 can also provide notification alerts for your reminders.

Volume and Media Controls

System Volume

@MODKEY@ + XF86AudioRaiseVolume: Increase system volume.
@MODKEY@ + XF86AudioLowerVolume: Decrease system volume.
@MODKEY@ + XF86AudioMute: Mute or unmute system volume.
In Ratpoison Mode, Alt + Shift + 0: Increase system volume.
In Ratpoison Mode, Alt + Shift + 9: Decrease system volume.

Media Player Controls

XF86AudioPlay: Play music.
XF86AudioNext: Move to the next track.
XF86AudioPrev: Move to the previous track.
XF86AudioStop: Stop playback.
@MODKEY@ + XF86AudioPlay: Speak media player information.

In Ratpoison Mode, these media controls are also available:

Alt + Shift + equals sign: Increase music volume.
Alt + Shift + dash: Decrease music volume.
Alt + Shift + z: Previous track.
Alt + Shift + c: Pause.
Alt + Shift + x: Play.
Alt + Shift + v: Stop.
Alt + Shift + b: Next track.
Alt + Shift + u: Speak media player information.

File Management

@FILEBROWSERHELP@

System Operations

Ratpoison Mode, then Control + semicolon: Reload the I38 configuration.
Ratpoison Mode, then Control + Shift + semicolon: Restart i3 in place while preserving your layout and session.
Ratpoison Mode, then @MODKEY@ + q: Exit i3 and end the X session, after confirmation.
Ratpoison Mode, then Control + @MODKEY@ + q: Exit i3 and end the X session, after confirmation.
Ratpoison Mode, then Alt + b: Check battery status.
Ratpoison Mode, then g: Check game controller status.
Ratpoison Mode, then @MODKEY@ + s: Adjust screen brightness, if xrandr is available.
@MODKEY@ + Control + m: Move the mouse pointer to the center of the focused window.
@MODKEY@ + Control + z: Start xzoom magnifier, if it was installed when your i3 config was generated.

Keyboard Layouts

Super + Space: Switch between keyboard layouts.

This is only available if you chose multiple keyboard layouts during setup.

Desktop and Window Decorations

I38 uses minimal window decorations. Windows do not use the usual title bars with minimize and maximize buttons. Instead, windows fill their available space automatically, and most interactions are performed through keyboard shortcuts.

@MODKEY@ + Control + d: Show desktop icons.

Clipboard Management

@MODKEY@ + Control + c: Open clipboard history.

Bookmark Management

@MODKEY@ + Control + b: Open bookmarks.

Tips for New Users

Use the window list when you are unsure where focus is. Press @RATPOISONKEY@, then apostrophe, to show all windows in the current workspace.
Start with Alt + Tab, Alt + Shift + Tab, and the workspace keys. Those are the fastest way to get oriented.
Remember the help shortcuts. @MODKEY@ + Shift + F1 opens this guide. F1 in Ratpoison Mode or Panel Mode opens quick keybinding help for that mode.
Let sound effects confirm mode changes, workspace changes, and fullscreen changes.
Try OCR when an application or image is not accessible.

Customization

You can customize I38 by editing ~/.config/i3/customizations. This file is not overwritten when you update I38.

Example customizations:


# Change background color
exec_always --no-startup-id xsetroot -solid "#2E3440"

# Add custom keybinding
bindsym $mod+F12 exec --no-startup-id pactl set-sink-volume @DEFAULT_SINK@ 100%

To reconfigure I38 completely, run the i38.sh script again.

Updating I38

I38 checks for updates in the background during your desktop session. If a newer version is found, I38 sends one notification and then stops checking for the rest of that session. If the server is unavailable or your network is down, I38 stays quiet and tries again later.

To update I38 on this system:

Open a terminal with @MODKEY@ + Return.
Type cd "@I38CHECKOUTPATH@" and press Enter.
Type git pull and press Enter.
Type ./i38.sh and press Enter.

Running ./i38.sh regenerates your I38 configuration and refreshes the installed scripts. Your personal shortcuts in ~/.config/i3/customizations are preserved.

To generate the default configuration without prompts, use ./i38.sh -d. To also generate ~/.xinitrc and ~/.xprofile without prompts, use ./i38.sh -D.

Default configuration mode uses I38Lock when it is installed and supported by the screen-reader setup. In that case, I38 locks on startup and autolocks after 5 minutes when xprintidle is available.

If you only need to copy the latest scripts and do not want to regenerate the full i3 configuration, use ./i38.sh -u.

Getting Help

If you need assistance with I38:

Press @MODKEY@ + Shift + F1 to view this guide.
Visit the Stormux website at stormux.org.
Join the Stormux IRC channels at irc.stormux.org, #stormux or #a11y.
Check the i3 documentation at i3wm.org/docs/userguide.html.

I38 - Making i3 accessible. A Stormux project. License: GPL v3

20 KiB Raw Permalink Blame History