446 lines
28 KiB
Markdown
446 lines
28 KiB
Markdown
ThunderPad
|
|
==========
|
|
|
|
**An Accessible Joypad to Keyboard/Mouse Mapper**
|
|
|
|
ThunderPad is an accessibility-focused fork of [QJoyPad](https://github.com/panzi/qjoypad) that provides full screen reader compatibility and keyboard navigation support. Originally developed by Nathan Gaylinn and John Toman, QJoyPad was later maintained by Mathias Panzenböck. This fork, ThunderPad, is developed for the [Stormux](https://stormux.org) project with a focus on making joystick/gamepad configuration fully accessible to users of screen readers like Orca.
|
|
|
|
|
|
|
|
Quick Installation
|
|
------------------
|
|
|
|
git clone https://git.stormux.org/storm/thunderpad
|
|
mkdir thunderpad/build
|
|
cd thunderpad/build
|
|
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release
|
|
make -j`nproc`
|
|
make install
|
|
|
|
For more details see [Installation](#installation).
|
|
|
|
## What's New in ThunderPad
|
|
|
|
### Latest Updates (2025.06.30)
|
|
- **Qt 6 Migration**: Updated from Qt5 to Qt6 for improved performance and future-proofing
|
|
- **Streamlined Interface**: Removed redundant close dialog button - single "Quit" button for clearer UX
|
|
- **Enhanced X11 Integration**: Direct X11 library usage for better compatibility
|
|
- **Modern APIs**: Updated all deprecated Qt functions for Qt6 compatibility
|
|
|
|
### Accessibility Features
|
|
- **Full keyboard navigation**: All interface elements are accessible via Tab/Shift+Tab
|
|
- **Screen reader compatible**: Works seamlessly with Orca and other screen readers
|
|
- **Accessible list widgets**: Axes and buttons are presented in navigable lists with descriptive labels
|
|
- **Clear focus indicators**: Visual and screen reader feedback for current focus position
|
|
- **Logical tab order**: Interface elements follow a predictable navigation sequence
|
|
|
|
### Interface Changes
|
|
- **Tab-based layout**: Replaced clickable interface with keyboard-navigable tabs for each joystick
|
|
- **Configure buttons**: Each axis and button has a dedicated configure button accessible via keyboard
|
|
- **No tray icon by default**: Opens configuration window directly for better accessibility (use `--tray` to enable system tray)
|
|
- **Window mode default**: Runs in window mode by default instead of system tray mode
|
|
|
|
### Compatibility
|
|
- **Runs alongside QJoyPad**: ThunderPad uses `~/.config/thunderpad/` for settings, allowing coexistence
|
|
- **Layout compatibility**: Can manually copy `.lyt` files between QJoyPad and ThunderPad directories
|
|
- **Translation removal**: English-only interface reduces complexity and improves screen reader performance
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
### Introduction
|
|
|
|
#### What is ThunderPad
|
|
|
|
ThunderPad is an accessible joystick/gamepad configuration tool with a Qt interface that converts movement and button presses on a gamepad or joystick into key presses, mouse clicks, and mouse movement in XWindows. It provides the same functionality as QJoyPad but with a completely redesigned interface optimized for screen reader users and keyboard navigation.
|
|
|
|
#### What's it good for?
|
|
|
|
ThunderPad lets you play any XWindows game that uses input from the keyboard and mouse with a joystick device, even if the game doesn't normally have joystick support. It's particularly valuable for users who rely on screen readers, as the interface is fully accessible and can be operated entirely via keyboard navigation.
|
|
|
|
In addition to gaming, ThunderPad is useful for anyone who would find it more comfortable or convenient to control their computer with a joystick or game pad, especially users with mobility impairments who may find traditional keyboard/mouse input challenging.
|
|
|
|
#### Features
|
|
|
|
- **Fully accessible interface** compatible with screen readers like Orca
|
|
- **Complete keyboard navigation** - no mouse required for configuration
|
|
- **Tab-based interface** for easy navigation between joysticks
|
|
- Incorporates your gaming devices into any XWindows program
|
|
- Move and click the mouse with your joystick
|
|
- Auto-detects how many joysticks you have and how many buttons and axes each supports
|
|
- Can detect joystick devices on the fly without restarting
|
|
- Support for devices with more than two axes
|
|
- Save as many layouts as you want and switch between them quickly
|
|
- Swap layouts on the fly from the command line or from a script
|
|
- Share layout files with your friends or even edit them by hand for greater control
|
|
- Set or reset all the keys at once in a flash
|
|
- Adjust the sensitivity of every axis independently
|
|
- **Window mode by default** - no system tray dependency for accessibility
|
|
- Optional system tray mode available with `--tray` flag
|
|
- Make an axis "Gradient" so that a light push does a little and a harder push does more
|
|
- Support for throttle controls
|
|
- Make a button "Sticky" if you don't feel like holding it down all the time
|
|
- Turn on Rapid Fire so you don't wear out your gamepad!
|
|
- If libudev is available, the joypad list will automatically update
|
|
|
|
### Getting Started
|
|
|
|
#### Requirements
|
|
|
|
- A Linux computer and a Linux-compatible gaming device
|
|
- A Linux kernel with joystick support (see the [Linux Kernel](https://www.kernel.org/) and the Linux joystick driver documentation [joystick.txt](https://www.kernel.org/doc/Documentation/input/joystick.txt) and [joystick-parport.txt](https://www.kernel.org/doc/Documentation/input/joystick-parport.txt))
|
|
- [XWindows](http://x.org/) - Required for GUI display
|
|
- [Qt 6](http://qt-project.org/) - Qt6Widgets and Qt6Gui modules
|
|
- [X11 development libraries](https://www.x.org/) - libX11 and libXtst for event generation
|
|
- [libudev](http://www.freedesktop.org/software/systemd/libudev/) (optional)
|
|
- For full accessibility: A screen reader like [Orca](https://wiki.gnome.org/Projects/Orca)
|
|
|
|
#### Installation
|
|
|
|
Installing ThunderPad should be a quick and painless process. The basic procedure is:
|
|
|
|
git clone https://git.stormux.org/storm/thunderpad
|
|
mkdir thunderpad/build
|
|
cd thunderpad/build
|
|
cmake .. -DCMAKE_BUILD_TYPE=Release
|
|
make -j`nproc`
|
|
make install
|
|
|
|
However, there are some settings that might need to be changed.
|
|
|
|
1. Device directory: By default, ThunderPad will look for joystick devices in `/dev/input`, but if your system puts them somewhere else, you'll need to run cmake like this:
|
|
|
|
`cmake .. -DDEVICE_DIR=/dev`
|
|
|
|
Do this if your joystick devices are `/dev/js0`, `/dev/js1` etc.
|
|
|
|
2. Install prefix: The default install prefix is `/usr`. To change this invoke cmake like this:
|
|
|
|
`cmake .. -DCMAKE_INSTALL_PREFIX=/usr`
|
|
|
|
3. Use Plain Keys: Normally, ThunderPad doesn't use standard XWindows key names to describe your keyboard, but instead uses names that look nicer and are easier to recognize. For instance, instead of "KP\_Begin", "Prior", and "Shift\_L", ThunderPad uses "KP 5", "PageDown", and "L Shift". If you would rather like the original X11 key names you can invoke cmake like this:
|
|
|
|
`cmake .. -DPLAIN_KEYS=ON`
|
|
|
|
4. Disable libudev support: If you don't have libudev you can disable libudev support like this:
|
|
|
|
`cmake .. -DWITH_LIBUDEV=OFF`
|
|
|
|
### Using ThunderPad
|
|
|
|
#### Running ThunderPad
|
|
|
|
ThunderPad requires a valid X11 display connection. In most desktop environments, simply run:
|
|
|
|
thunderpad
|
|
|
|
If running from a terminal or remote session, you may need to specify the display:
|
|
|
|
DISPLAY=:0 thunderpad
|
|
|
|
#### Default Window Mode
|
|
|
|
Unlike QJoyPad, ThunderPad runs in window mode by default for better accessibility. When you start ThunderPad, it will automatically open the configuration window where you can set up your joystick mappings using full keyboard navigation.
|
|
|
|
#### Accessible Interface Navigation
|
|
|
|
ThunderPad's interface is designed for keyboard navigation:
|
|
|
|
- **Tab/Shift+Tab**: Navigate between interface elements
|
|
- **Enter/Space**: Activate buttons and open configuration dialogs
|
|
- **Arrow keys**: Navigate within lists and tabs
|
|
- **Esc**: Close dialogs and return to main interface
|
|
|
|
#### The Configuration Window
|
|
|
|
The main configuration window contains:
|
|
|
|
##### Layout Management Section
|
|
At the top are controls for managing your controller layouts:
|
|
- **Layout dropdown**: Select from saved layouts
|
|
- **Add button**: Create a new layout
|
|
- **Remove button**: Delete the current layout
|
|
- **Rename button**: Rename the current layout
|
|
- **Import/Export buttons**: Share layouts with others
|
|
- **Save/Revert buttons**: Save changes or restore from file
|
|
- **Quit button**: Exit ThunderPad completely (replaces separate close dialog button)
|
|
|
|
##### Joystick Tabs
|
|
Each connected joystick appears as a separate tab. Use Ctrl+Tab or click to switch between joysticks.
|
|
|
|
##### Axes and Buttons Lists
|
|
Within each joystick tab:
|
|
- **Axes list**: Shows all joystick axes with their current assignments
|
|
- **Configure Axis button**: Opens configuration for the selected axis
|
|
- **Buttons list**: Shows all joystick buttons with their current assignments
|
|
- **Configure Button button**: Opens configuration for the selected button
|
|
- **Clear/Quick Set buttons**: Reset all assignments or use quick configuration mode
|
|
|
|
#### System Tray Mode (Optional)
|
|
|
|
If you prefer the traditional tray icon interface, you can use:
|
|
|
|
thunderpad --tray
|
|
|
|
This will minimize ThunderPad to the system tray. Right-click the tray icon to access layouts and settings.
|
|
|
|
#### Quick Set Feature
|
|
|
|
The Quick Set feature provides rapid configuration:
|
|
1. Click the "Quick Set" button
|
|
2. Press any button or move any axis on your controller
|
|
3. ThunderPad will prompt you to assign a keyboard key or mouse action
|
|
4. Repeat for all controls you want to configure
|
|
5. Click "Done" when finished
|
|
|
|
### Command-line use and scripting
|
|
|
|
ThunderPad supports the same command-line interface as QJoyPad for loading layouts:
|
|
|
|
thunderpad "Tetris"
|
|
|
|
If ThunderPad isn't running, it will start and load the "Tetris" layout. If it's already running, it will switch to that layout.
|
|
|
|
You can create shell scripts to automatically load appropriate layouts when starting games:
|
|
|
|
#!/bin/sh
|
|
|
|
thunderpad "XGalaga" &
|
|
xgalaga++
|
|
|
|
## Layout Files and Compatibility
|
|
|
|
### ThunderPad Layout Directory
|
|
|
|
ThunderPad stores its configuration files in `~/.config/thunderpad/`, separate from QJoyPad's `~/.config/qjoypad4/` directory. This allows both programs to coexist without conflicts.
|
|
|
|
### Sharing Layouts with QJoyPad
|
|
|
|
ThunderPad uses the same `.lyt` file format as QJoyPad, so layouts can be shared:
|
|
|
|
1. **From QJoyPad to ThunderPad**: Copy `.lyt` files from `~/.config/qjoypad4/` to `~/.config/thunderpad/`
|
|
2. **From ThunderPad to QJoyPad**: Copy `.lyt` files from `~/.config/thunderpad/` to `~/.config/qjoypad4/`
|
|
|
|
After copying files, restart the application or use the "Update Layout List" option to see the new layouts.
|
|
|
|
### Layout File Format
|
|
|
|
Layout files use standard X11 keycodes and are human-readable. You can edit them manually if needed. The format includes:
|
|
- Joystick definitions with axis and button mappings
|
|
- Key assignments using X11 keycodes
|
|
- Mouse movement and click assignments
|
|
- Special properties like rapid fire and sticky buttons
|
|
|
|
## Differences from QJoyPad
|
|
|
|
### Accessibility Improvements
|
|
- **Complete keyboard navigation**: No mouse required for any configuration task
|
|
- **Screen reader support**: All interface elements have proper labels and descriptions
|
|
- **Focus management**: Clear visual and audio feedback for current focus position
|
|
- **Simplified interface**: Removed complex clickable widgets in favor of accessible lists and buttons
|
|
|
|
### Interface Changes
|
|
- **Tab-based layout**: Replaced Flash widget arrays with standard Qt tab widgets
|
|
- **List-based controls**: Axes and buttons presented in navigable lists rather than clickable grids
|
|
- **Default window mode**: No system tray icon by default (use `--tray` to enable)
|
|
- **Dedicated configure buttons**: Each control has its own configuration button for keyboard access
|
|
|
|
### Behavioral Changes
|
|
- **No translation system**: English-only interface reduces complexity and improves screen reader performance
|
|
- **Separate config directory**: Uses `~/.config/thunderpad/` to avoid conflicts with QJoyPad
|
|
- **Direct window opening**: Shows configuration window immediately instead of hiding in system tray
|
|
|
|
## Command Line Options
|
|
|
|
thunderpad [OPTIONS] [LAYOUT_NAME]
|
|
|
|
**Options:**
|
|
- `-h, --help`: Show help message
|
|
- `-d, --device=PATH`: Specify joystick device directory (default: `/dev/input`)
|
|
- `-t, --tray`: Use system tray icon (instead of default window mode)
|
|
- `-T, --notray`: Use window mode (default behavior)
|
|
- `-u, --update`: Update device list in running instance
|
|
- `-H, --headless=LAYOUT`: Run in headless mode with no GUI, loading the specified layout
|
|
|
|
**Layout Name:** Load the specified layout on startup
|
|
|
|
## Troubleshooting
|
|
|
|
### Accessibility Issues
|
|
|
|
#### Screen reader not announcing interface elements
|
|
- Ensure you're using a recent version of Orca or your preferred screen reader
|
|
- Try restarting your screen reader after launching ThunderPad
|
|
- Check that Qt accessibility is enabled in your desktop environment
|
|
|
|
#### Tab navigation not working as expected
|
|
- Use Tab/Shift+Tab to move between major interface elements
|
|
- Use arrow keys within lists and combo boxes
|
|
- If focus seems stuck, try pressing Escape to return to the main interface
|
|
|
|
### General Issues
|
|
|
|
Most troubleshooting steps from QJoyPad apply to ThunderPad. See the original documentation sections below for:
|
|
- Joystick recognition problems
|
|
- Device detection issues
|
|
- Sensitivity and calibration problems
|
|
|
|
### Running Alongside QJoyPad
|
|
|
|
ThunderPad and QJoyPad can run simultaneously since they use different configuration directories and process names. However, both will attempt to access the same joystick devices, which may cause conflicts. It's recommended to use only one at a time.
|
|
|
|
## Credits
|
|
|
|
ThunderPad is based on [QJoyPad](https://github.com/panzi/qjoypad), originally developed by Nathan Gaylinn <wren42@users.sourceforge.net> and John Toman <virtuoussin13@users.sourceforge.net>, with Qt 5 port and additional features by Mathias Panzenböck <grosser.meister.morti@gmx.net>.
|
|
|
|
Accessibility improvements and ThunderPad fork developed for the [Stormux](https://stormux.org) project.
|
|
|
|
Special thanks to the screen reader and accessibility communities for feedback and testing.
|
|
|
|
## Original QJoyPad Documentation
|
|
|
|
The following sections contain the original QJoyPad documentation, which remains relevant for ThunderPad's core functionality:
|
|
|
|
---
|
|
|
|
### Configuring axes
|
|
|
|
|
|
|
|
In QJoyPad 2, you were allowed one key to be assigned to each of four directions, Up, Down, Left, and Right. In version 3, there is support for many axes and each one can do fancier things than just press a key. Unfortunately, since different controllers do things differently, it's not as easy as Up, Down, Left, and Right. Up-Down is an axis, Left-Right is an axis, and if you have a nicer controller, you might have many more axes on top of that.
|
|
|
|
The first step in configuring axes is to figure out which one you want to set. If you have a joystick, try moving it around and seeing which items are highlighted in the axes list. If you have a gamepad, try pressing different buttons on the Directional-Pad or moving around any mini joystick controls it might have. Once you know which axis you want to set, select it in the list and click the "Configure Axis" button.
|
|
|
|
#### The Axis Position Indicator
|
|
|
|
In the middle of this dialog, you will see a white bar, divided in two, that represents the current position of the axis you're editing. Try moving that axis to see how it works. This is so you know which direction is considered "positive" and which is "negative"; it might not be what you'd expect. If this axis is a D-Pad, then it is either off or on, but most other axes are sensitive to how far they are depressed and a colored bar here will show you how far it is at the moment.
|
|
|
|
Along the white bar, you will also see small blue and red tabs that you can drag. These adjust the "Dead Zone" and the "Extreme Zone" of the axis. When the colored bar representing the axis' position passes one of the blue markers, the bar will turn blue meaning that when the axis is this far QJoyPad will consider it moved, and when the bar passes one of the red markers it will turn red and QJoyPad will consider that axis fully depressed. When the bar is gray, that means that you haven't moved the axis out of its Dead Zone and QJoyPad is ignoring its movement. To adjust where the Dead and Extreme Zones are, just slide the blue and red markers to where you think they should be.
|
|
|
|
You probably won't need to adjust the sensitivity unless you are having trouble getting QJoyPad to generate key presses when you want it to (see [Joystick adjustment](#joystick-adjustment)).
|
|
|
|
#### Set an axis to 0-max, relative (gradient), or absolute movement
|
|
|
|
On the upper half of the dialog, you will see another drop-down set to relative movement. In 0-max mode QJoyPad generates just one key press when the axis is moved. In case of relative and absolute QJoyPad will start flickering that key on and off as soon as the axis is out of the Dead Zone (when the colored bar turns blue). How far the axis is pushed determines what percent of the time the simulated key will be depressed. As soon as the axis enters its Extreme Zone (when the colored bar turns red), the key will be down 100% of the time. Setting an axis to relative is useful if you want to use it as an accelerator in a game so how fast you go is controlled by how far the axis is moved. Also, it's nice to use this when the axis is set to move the mouse because it can give you finer control of the mouse when you push the axis just a little but still let you move quickly when you push it all the way.
|
|
|
|
#### Switching between keyboard and mouse control
|
|
|
|
On the upper half of the dialog, there is a combo box that lets you choose between keyboard control and mouse control. There are four different mouse options that let you choose whether the mouse will move vertically (Up-Down) when the axis moves or horizontally (Left-Right). You can also reverse the direction of the mouse if you want moving the axis up to move the mouse down or visa versa.
|
|
|
|
**Tip**
|
|
|
|
Usually you want an axis to be relative or absolute if it's going to move the mouse. Relative to pass relative mouse movements, and absolute to place the mouse on the screen according to the axis position.
|
|
|
|
#### Adjusting mouse speed
|
|
|
|
When using one of the mouse modes, you can set the speed of the mouse by adjusting the number in the upper right corner.
|
|
|
|
#### Setting keys
|
|
|
|
When using keyboard mode, you can set which key corresponds to which direction of the axis by clicking the buttons immediately below the Axis Position Indicator. The one on the left will be pressed when the axis is moved in the negative direction (when the colored bar is on the left side) and the one on the right when it is in the positive direction (when the colored bar is on the right side).
|
|
|
|
#### Throttle Settings
|
|
|
|
Between these two buttons is another combo box that changes the throttle settings. This is meant for gamepads which have a specific type of throttle control. What it does is instead of having two keys for when the axis is positive or negative, it has just one and treats the way the axis moves differently. In one of the throttle modes, the axis will be considered centered when it is all the way to one direction or the other.
|
|
|
|
### Configuring buttons
|
|
|
|
|
|
|
|
Similarly to the axes, buttons are listed in the buttons list. To configure a button, select it from the list and click "Configure Button". You can also press the physical button on your controller to see which item gets highlighted in the list.
|
|
|
|
#### Choosing a key / mouse button
|
|
|
|
At the top of this dialog is a button that you can click to set which key or mouse button you want to associate with this button on your controller. Just click on it, and the rest should be self-explanatory.
|
|
|
|
#### Making a button "Sticky"
|
|
|
|
Below this and to the left is a little checkbox marked Sticky. When a button is set as Sticky, that means that pressing the button once will make QJoyPad simulate a key press (or mouse button press) and pressing that button again will make QJoyPad release the simulated key. This is useful for racing games where you're almost always pouring on the gas, or for RPGs that have a button used for run, even though it's always better to be running. This way, all you have to do is press the button once and it's like you're holding it down. To let the button back up, just press it a second time.
|
|
|
|
#### Using Rapid Fire
|
|
|
|
Just next to the Sticky checkbox is another one marked Rapid Fire. When this is enabled for a button, holding that button down means that QJoyPad will flicker the associated key very fast. This is great for space shooters where you want to fire quickly but you don't want to break your button (or your thumb!) from pressing over and over again.
|
|
|
|
**Tip**
|
|
|
|
Keep in mind that any button can be set both Sticky AND Rapid Fire. This is even better for space shooters because this way all you need to do is press the button once and from then until you press it again you will be shooting Rapid Fire.
|
|
|
|
## Problems
|
|
|
|
### I can't get my game controller to work in Linux; will ThunderPad help?
|
|
|
|
Well, that depends on why you can't get it to work. For the most part, the answer is "No." ThunderPad can only use joysticks and gamepads that are recognized by your kernel and that have the proper drivers loaded. If you can't get your joysticks to work at all in Linux, then, no, ThunderPad can't help. (you might want to check out [joystick.txt](https://www.kernel.org/doc/Documentation/input/joystick.txt) or [joystick-parport.txt](https://www.kernel.org/doc/Documentation/input/joystick-parport.txt); if you don't know anything about working with the kernel, check out the [Linux Kernel HOWTO](http://www.linuxdocs.org/HOWTOs/Kernel-HOWTO.html), although this document seems to be outdated)
|
|
|
|
If your joystick is detected and somewhat working, but you can't get it to work in specific programs, then ThunderPad just might be what you're looking for. One of the main reasons QJoyPad was originally created was because gamepads simply wouldn't work right with the input plugins for Linux Playstation emulators, so we know for a fact that sometimes ThunderPad can work around specific software issues.
|
|
|
|
Check out [Joystick recognition](#joystick-recognition) for some tips for checking if your joystick is working.
|
|
|
|
### Joystick recognition
|
|
|
|
#### ThunderPad says it can't find any joysticks?
|
|
|
|
#### ThunderPad isn't showing all of my joysticks.
|
|
|
|
#### My joystick has more/fewer buttons/axes than that!
|
|
|
|
ThunderPad automatically recognizes your joysticks using the Linux joystick driver, so all joysticks must be working properly in Linux before they can be used in ThunderPad. If you can't see all of your joysticks or if ThunderPad complains it can't find any, chances are your joystick(s) are not plugged in or are not properly detected by Linux. If that's not it, ThunderPad could also be looking for your joysticks in the wrong directory.
|
|
|
|
First, double check that your joysticks are plugged in. If they aren't, plug them, load any modules you might need, and tell ThunderPad to Update joystick devices with the popup menu (if using tray mode) or restart ThunderPad.
|
|
|
|
If you're still having trouble, ThunderPad might have been compiled with the devdir setting pointing to the wrong place. That option had to be set at compile time, and to change it you must recompile (see [Installation](#installation)); however, if you don't want to bother with that, you can specify the location of your devices as an argument. Using the command `thunderpad --device /dev/input`, for example, will start ThunderPad and tell it to look for joysticks in `/dev/input/js0`, `/dev/input/js1`, etc.
|
|
|
|
If that doesn't work, then you might want to make sure your joysticks are working properly. One way to test this is to do a `cat /dev/input/js0` (or wherever your joystick device is) and press a few buttons on the controller. If you get a bunch of crazy characters, it's working. If not, you'll have to fiddle around with kernel drivers, and should probably look elsewhere for guidance. Or you can install the jstest command line tool and use `jstest /dev/input/js0`, which will give you a much nicer output.
|
|
|
|
If for some reason ThunderPad is reporting the wrong number of buttons or axes for your device, that means the Linux joystick driver is also reporting the wrong number. Unless you can't get to buttons or axes that you need, this shouldn't be a problem, but if you want to get the number right, Try using a different driver or check out the documentation for the one you're using.
|
|
|
|
If your joysticks are working, plugged in, and ThunderPad is looking in the right place, then I'm not sure what to tell you. Unfortunately, we don't have a wealth of different devices and software setups to test on. If you're really stuck and think it's ThunderPad's fault please [write a bug report](https://git.stormux.org/storm/thunderpad/issues).
|
|
|
|
### Joystick adjustment
|
|
|
|
#### Why does it say I'm moving if I'm not?
|
|
|
|
#### I keep going in two directions at once instead of just one!
|
|
|
|
#### I'm pushing up, but nothing's happening!
|
|
|
|
Chances are, this means you're using an overly sensitive or poorly calibrated joystick or your sensitivity settings are all wrong. Try adjusting the Dead Zone of the axes that are giving you trouble (move the blue tab in the Axis Edit dialog), more away from the center if it thinks you're pressing a button when you aren't, more toward the center if it thinks you aren't pressing a button when you are. If that doesn't work, try manually adjusting your joystick (if it has adjustment knobs/sliders), or try calibrating it with jscal or with the KDE system settings "Input Devices" module.
|
|
|
|
### ThunderPad won't start!
|
|
|
|
There are several reasons why ThunderPad might not start:
|
|
|
|
#### Display Connection Issues
|
|
Since ThunderPad is a Qt6 GUI application, it requires a valid X11 display connection. If you get an error on startup, try:
|
|
|
|
DISPLAY=:0 thunderpad
|
|
|
|
Or ensure you're running from within an X11 desktop environment.
|
|
|
|
#### Already Running
|
|
ThunderPad won't start if it's already running! Only one instance is allowed at a time. If you can't see an already open version, look for the icon in the system tray (if using `--tray` mode). If you really can't find it anywhere, try running `killall thunderpad` and then `rm -f /tmp/thunderpad.pid` and then try starting ThunderPad again.
|
|
|
|
#### Help Mode
|
|
ThunderPad won't actually run if one of its arguments is `-h` or `--help`. When it sees one of those arguments, it outputs usage information to the console and then quits. If you're running ThunderPad away from a console or want it to run like normal, don't give one of these arguments.
|
|
|
|
### I have two versions of ThunderPad/QJoyPad open at once and they're getting in each other's way!
|
|
|
|
ThunderPad and QJoyPad use different PID files (`/tmp/thunderpad.pid` vs `/tmp/qjoypad.pid`), so they can run simultaneously. However, both will try to access the same joystick devices, which may cause conflicts. If you experience issues, close one of the applications.
|
|
|
|
If you have multiple instances of the same application, make sure you don't have old versions installed alongside newer ones.
|
|
|
|
### This program only works in XWindows?
|
|
|
|
Yes, ThunderPad, like QJoyPad, only works in X11/XWindows environments. ThunderPad uses direct X11 libraries for event generation and requires an active X11 display connection.
|
|
|
|
For Wayland environments, you may be able to run ThunderPad under XWayland compatibility. For native Wayland or console applications, you'll need to use alternative solutions like [joy2key](https://sourceforge.net/projects/joy2key/) or [AntiMicro](https://github.com/AntiMicro/antimicro).
|
|
|
|
### Why do I have to tell ThunderPad to "update joystick devices"? Why can't it do that on its own?
|
|
|
|
If you compile with `-DWITH_LIBUDEV=ON` (the default) then UDev is used to automatically update the joypad list. If automatically updating of the joypad list still does not work compile with `-DCMAKE_BUILD_TYPE=Debug` and post the output on the [bug tracker](https://git.stormux.org/storm/thunderpad/issues).
|
|
|
|
You can force ThunderPad to rescan your joypads at any time using the menu or by running `thunderpad --update`.
|
|
|
|
## Licensing
|
|
|
|
This software is licensed under the terms of the GNU GPLv2. Please see LICENSE.txt for a full text of the license.
|