Welcome to xatk’s documentation¶
xatk is a keyboard-driven window switcher for X11. It dynamically binds windows to keyboard shortcuts, so it is possible to reach any window with one or a few keystrokes.
Installation¶
xatk is a single python file program that you can put in any directory defined in the PATH environment variable. To run xatk you should have python 2 (>= 2.7) and python-xlib installed.
Alternatively you can install xatk with pip (python2 version):
$ pip install xatk
Running¶
Before running xatk you may want to change some configuration options. First, create the default configuration file:
$ mkdir -p ~/.xatk
$ xatk --print-defaults > ~/.xatk/xatkrc
Then open ~/.xatk/xatkrc and make changes. The most interesting
option is prefix which is set to Super (Windows) by default. This
means that all keyboard shortcuts will start with Super modifier. You
can define any modifier you like or even combination of modifiers and
keys. Look at the comment blocks in the default configuration file for
more customization options.
When you get ready with configuration, you can start xatk by running it with no arguments:
$ xatk
If no error occurr you will be able to notice shortcuts in window
titles. To activate a specific window press prefix + shortcut.
If you want to exit the program run:
$ xatk --kill
It’s the same as kill xatk with SIGTERM. It’s safe.
Autostart¶
If you use GDM or KDM, you can add xatk to ~/.xprofile. If you
use startx or xinit you can add xatk to ~/.xinitirc
before line exec window-manager. Also GNOME, KDE and Xfce have
dedicated GUI tools to add programs to startup.
More Info¶
For more information on configuration options look at the comment blocks in ~/.xatk/xatkrc. For other information look at the links below.
How it works¶
Motivation¶
Most of window switchers are interactive. They provide attributes associated with windows (e.g. titles, icons, previews) which we scan first and than choose one of them. That works well enough when we deal with a set of applications for the first time. However, we regularly use the same applications. So, in most cases our wish to switch a window can be expressed like “Show me <my favourite text editor>”. One possible solution to switch between windows efficiently is to bind regularly used windows to keyboard shortcuts with such tools as wmctrl and xbindkeys. However, this approach has a few drawbacks:
- switching to the particular window of the program which has more than one window is hard if not impossible;
- only limited number of windows are covered;
- manual composition of keyboard shortcuts which becomes even more boring when you stop using one program and start using another one;
- it is not easy to keep in mind all defined keyboard shortcuts.
xatk was created to resolve these issues.
How it works¶
When a new window appears xatk determines its special name called abstract window name (awn). This name is used for 2 purposes:
- windows which have the same awn fall into one group;
- characters of awn are preferable keys to compose a shortcut from for the corresponding window.
By default, window class property is assigned to awn. However, user may define own rules based on window class and window name (title) to form awns.
When awn of the window is determined, xatk looks it up in the history, holding awn — shortcut pairs. If the history contains the appropriate entry, xatk will bind the window to the previously used shortcut. Otherwise the shortcut is generated from the awn. This technique results in next xatk’s features:
- new shortcuts are usually not hard to remember as they are derived from the application names (more precisely, from the awns);
- regularly used windows have the same shortcuts all the time;
- shortcuts of applications that are not used anymore for some time get freed.
Windows which belong to the same group have the same base key which is the first key of the shortcut.
Keybindings¶
xatk tries to compose keybindings which would be easy to press and predict. If a window is alone in the group, then to activate it you have to press a one-key shortcut while holding a prefix key. If the group contains more than one window, than a keybinding of the first window will remain the same (but window activation will be triggered by key release instead of key press). Other windows of the group will have keybindings with prefix+base key+suffix key scheme. Such notation means that you should press base key while holding prefix key and then press suffix key while holding base key. xatk takes into consideration the keyboard layout when it produces suffix keys. So, a distance between base key and suffix key is one, two, and three keys for the second, third, and fourth window of the group respectively. Another way to reach deeper windows of the group is cycling through them by pressing a base key repeatedly.
Finally, if you don’t like pressing key sequences, you can configure xatk not to group windows.
Frequently Asked Questions¶
Is xatk compatible with my window manager?¶
xatk uses some hints specified in EWMH. So xatk should work fine with window managers that support such hints. Metacity/Mutter, KWin, Compiz, Openbox, Awesome have been reported to work with xatk. Share your experience with us via issue tracking system.
Customization¶
All customizations are done by modifying xatk’s configuration file
~/.xatk/xatkrc. Before making any changes ensure that xatk is not
running.
How to assign keybindings to the certain windows permanently?¶
Create a rule and prefix awn with !. For example,
class.emacs = !e
How to forbid xatk to assign keybindings to the certain windows?¶
Crate a rule and specify empty awn. For example,
class.emacs =
How to make xatk ignore all windows except a few ones?¶
Specify rules for windows which should not be ignored and the following rule at the end of RULES:
class..* =
How to forbid xatk to modify all window titles?¶
Set title_format to None.
How to disable multi-key shortcuts?¶
Change group_windows_by option value to None.
Shortcuts for my windows change all the time.¶
Try to increase the value of history_length option or specify premanent keys for some windows.
How to make two windows belong to the same group?¶
Windows belong to the same group if they have identical awn attributes. You can specify identical awns for those windows in the RULES section.
I want shortcuts to be in certain order (e.g. q,w,e,r...) without considering programs they belong to.¶
You can set history_length to 0, group_windows_by to None and define the rule like this:
title..*=qwertyuiopasdfghjklzxcvbnm
Miscellaneous¶
How can I get a window class or instance?¶
First stop xatk if it is running. Run xatk with the following options:
xatk --no-daemon --filter=windows --verbose
You will see information messages starting with
new window attributes. These lines contain klass, instance and name
attributes. They correspond to window class, instance and title
respectively.
Run 'xprop WM_CLASS' and select a window. The first string after ‘=’
is a window instance and the second one is a window class.
wmctrl -xl prints a window list on the standard output. The second
column is in instance.class format.
Contributing¶
How can I help the project?¶
Report bugs and request features via issue tracking system.
Make a screencast.
Spread the word. Write about xatk on your site or blog.
Help with code, see Roadmap. A preliminary discussion with developers is encouraged.
Troubleshooting¶
xatk doesn’t start or doesn’t work¶
Run xatk in the terminal and look at the output. Probably it is something wrong with your configuration. If there is no complains, and you have still no idea what is going on, run xatk in foreground:
$ xatk --no-daemon -vv
If it is still not clear, where the problem is, please create a bug report.
I have Python 2 installed but xatk doesn’t start¶
If your shell prints something similar to
/usr/bin/env: python2: No such file or directory
then probably your OS distribution doesn’t provide python2 symlink. The real fix is to convince maintainers of your distribution to provide python2 symlink as described in PEP 394. The temporary fix is obvious: you can either edit xatk file replacing python2 with your real python 2 executable name, or you can specify xatk path as command line argument to python 2 interpreter.
Ideas for future versions of xatk¶
- add keybindings to quit xatk, reload config and update history in the config;
- generate dump files on unhandled exceptions;
- alt-tab-like behaviour for cycling shortcuts for grouped windows (more recently used windows are raised first);
- revert states of the windows while cycling (e.g. iconify them if they were iconified before);
- user-defined keyboard layouts;
- provide current list of windows and corresponding shortcuts (via pipe or a regular file?);
- make program’s name as another source to form awns;
- prevent updating window names too often.