Document commands and new configuration options in userguide
This commit is contained in:
Michael Stapelberg
parent
4b3ea4d524
commit
c38767603b
271
docs/userguide
271
docs/userguide
@ -1,7 +1,7 @@
|
||||
i3 User’s Guide
|
||||
===============
|
||||
Michael Stapelberg <michael+i3@stapelberg.de>
|
||||
June 2009
|
||||
August 2009
|
||||
|
||||
This document contains all information you need to configuring and using the i3
|
||||
window manager. If it does not, please contact me on IRC, Jabber or E-Mail and
|
||||
@ -174,24 +174,40 @@ font::
|
||||
|
||||
=== Keyboard bindings
|
||||
|
||||
You can use each command (see below) using keyboard bindings. At the moment,
|
||||
keyboard bindings require you to specify the keycode (38) of the key, not its key
|
||||
symbol ("a"). This has some advantages (keybindings make sense regardless of
|
||||
the layout you type) and some disadvantages (hard to remember, you have to look
|
||||
them up every time).
|
||||
A keyboard binding makes i3 execute a command (see below) upon pressing a
|
||||
specific key. i3 allows you to bind either on keycodes or on keysyms (you can
|
||||
also mix your bindings, though i3 will not protect you from overlapping ones).
|
||||
|
||||
* A keysym (key symbol) is a description for a specific symbol, like "a" or "b",
|
||||
but also more strange ones like "underscore" instead of "_". These are the ones
|
||||
you also use in Xmodmap to remap your keys. To get the current mapping of your
|
||||
keys, use +xmodmap -pke+.
|
||||
|
||||
* Keycodes however do not need to have a symbol assigned (handy for some hotkeys
|
||||
on some notebooks) and they will not change their meaning as you switch to a
|
||||
different keyboard layout.
|
||||
|
||||
My recommendation is: If you often switch keyboard layouts because you try to
|
||||
learn a different one, but you want to keep your bindings at the same place,
|
||||
use keycodes. If you don’t switch layouts and like a clean and simple config
|
||||
file, use keysyms.
|
||||
|
||||
*Syntax*:
|
||||
--------------------------------
|
||||
----------------------------------
|
||||
bindsym [Modifiers+]keysym command
|
||||
bind [Modifiers+]keycode command
|
||||
--------------------------------
|
||||
----------------------------------
|
||||
|
||||
*Examples*:
|
||||
--------------------------------
|
||||
# Fullscreen
|
||||
bind Mod1+41 f
|
||||
bind Mod1+f f
|
||||
|
||||
# Restart
|
||||
bind Mod1+Shift+27 restart
|
||||
bind Mod1+Shift+r restart
|
||||
|
||||
# Notebook-specific hotkeys
|
||||
bind 214 exec /home/michael/toggle_beamer.sh
|
||||
--------------------------------
|
||||
|
||||
Available Modifiers:
|
||||
@ -241,7 +257,7 @@ set name value
|
||||
*Examples*:
|
||||
------------------------
|
||||
set $m Mod1
|
||||
bind $m+Shift+27 restart
|
||||
bindsym $m+Shift+r restart
|
||||
------------------------
|
||||
|
||||
Variables are directly replaced in the file when parsing, there is no fancy
|
||||
@ -259,8 +275,8 @@ i3 will get the title as soon as the application maps the window (mapping means
|
||||
actually displaying it on the screen), you’d need to have to match on Firefox
|
||||
in this case.
|
||||
|
||||
You can prefix or suffix workspaces with a +~+ to specify that matching clients
|
||||
should be put into floating mode. If you specify only a +~+, the client will
|
||||
You can prefix or suffix workspaces with a `~` to specify that matching clients
|
||||
should be put into floating mode. If you specify only a `~`, the client will
|
||||
not be put onto any workspace, but will be set floating on the current one.
|
||||
|
||||
*Syntax*:
|
||||
@ -294,6 +310,181 @@ exec command
|
||||
exec sudo i3status | dzen2 -dock
|
||||
--------------------------------
|
||||
|
||||
=== Automatically putting workspaces on specific screens
|
||||
|
||||
If you use the assigning of clients to workspaces and start some clients
|
||||
automatically, it might be handy to put the workspaces on specific screens.
|
||||
Also, the assignment of workspaces to screens will determine the workspace
|
||||
which i3 uses for a new screen when adding screens or when starting (e.g., by
|
||||
default it will use 1 for the first screen, 2 for the second screen and so on).
|
||||
|
||||
*Syntax*:
|
||||
----------------------------------
|
||||
workspace <number> screen <screen>
|
||||
----------------------------------
|
||||
|
||||
Screen can be either a number (starting at 0 for the first screen) or a
|
||||
position. When using numbers, it is not guaranteed that your screens always
|
||||
get the same number. Though, unless you upgrade your X server or drivers, the
|
||||
order usually stays the same. When using positions, you have to specify the
|
||||
exact pixel where the screen *starts*, not a pixel which is contained by the
|
||||
screen. Thus, if your first screen has the dimensions 1280x800, you can match
|
||||
the second screen right of it by specifying 1280. You cannot use 1281.
|
||||
|
||||
*Examples*:
|
||||
---------------------------
|
||||
workspace 1 screen 0
|
||||
workspace 5 screen 1
|
||||
|
||||
workspace 1 screen 1280
|
||||
workspace 2 screen x800
|
||||
workspace 3 screen 1280x800
|
||||
---------------------------
|
||||
|
||||
=== Named workspaces
|
||||
|
||||
If you always have a certain arrangement of workspaces, you might want to give
|
||||
them names (of course UTF-8 is supported):
|
||||
|
||||
*Syntax*:
|
||||
---------------------------------------
|
||||
workspace <number> <name>
|
||||
workspace <number> screen <screen> name
|
||||
---------------------------------------
|
||||
|
||||
For more details about the screen-part of this command, see above.
|
||||
|
||||
*Examples*:
|
||||
--------------------------
|
||||
workspace 1 www
|
||||
workspace 2 work
|
||||
workspace 3 i ♥ workspaces
|
||||
--------------------------
|
||||
|
||||
=== Changing colors
|
||||
|
||||
You can change all colors which i3 uses to draw the window decorations and the
|
||||
bottom bar.
|
||||
|
||||
*Syntax*:
|
||||
--------------------------------------------
|
||||
colorclass border background text
|
||||
--------------------------------------------
|
||||
|
||||
Where colorclass can be one of:
|
||||
|
||||
client.focused::
|
||||
A client which currently has the focus.
|
||||
client.focused_inactive::
|
||||
A client which is the focused one of its container, but it does not have
|
||||
the focus at the moment.
|
||||
client.unfocused::
|
||||
A client which is not the focused one of its container.
|
||||
bar.focused::
|
||||
The current workspace in the bottom bar.
|
||||
bar.unfocused::
|
||||
All other workspaces in the bottom bar.
|
||||
|
||||
Colors are in HTML hex format, see below.
|
||||
|
||||
*Examples*:
|
||||
--------------------------------------
|
||||
# class border backgr. text
|
||||
client.focused #2F343A #900000 #FFFFFF
|
||||
--------------------------------------
|
||||
|
||||
=== Interprocess communication
|
||||
|
||||
i3 uses unix sockets to provide an IPC interface. At the moment, this interface
|
||||
is only useful for sending commands. To enable it, you have to configure a path
|
||||
where the unix socket will be stored. The default path is +/tmp/i3-ipc.sock+.
|
||||
|
||||
*Examples*:
|
||||
----------------------------
|
||||
ipc-socket /tmp/i3-ipc.sock
|
||||
----------------------------
|
||||
|
||||
You can then use the i3-msg command to perform any command listed in the next
|
||||
section.
|
||||
|
||||
== List of commands
|
||||
|
||||
=== Manipulating layout
|
||||
|
||||
To change the layout of the current container to stacking or back to default
|
||||
layout, use +s+ or +d+. To make the current client (!) fullscreen, use +f+, to
|
||||
make it floating (or tiling again) use +t+:
|
||||
|
||||
*Examples*:
|
||||
--------------
|
||||
bind Mod1+s s
|
||||
bind Mod1+l d
|
||||
|
||||
# Toggle fullscreen
|
||||
bind Mod1+f f
|
||||
|
||||
# Toggle floating/tiling
|
||||
bind Mod1+t t
|
||||
--------------
|
||||
|
||||
=== Focussing/Moving/Snapping clients/containers/screens
|
||||
|
||||
To change the focus, use one of the +h+, +j+, +k+ and +l+ commands, meaning
|
||||
respectively left, down, up, right. To focus a container, prefix it with +wc+,
|
||||
to focus a screen, prefix it with +ws+.
|
||||
|
||||
The same principle applies for moving and snapping, just prefix the command
|
||||
with +m+ when moving and with +s+ when snapping:
|
||||
|
||||
*Examples*:
|
||||
----------------------
|
||||
# Focus clients on the left, bottom, top, right:
|
||||
bindsym Mod1+j h
|
||||
bindsym Mod1+k j
|
||||
bindsym Mod1+j k
|
||||
bindsym Mod1+semicolon l
|
||||
|
||||
# Move client to the left, bottom, top, right:
|
||||
bindsym Mod1+j mh
|
||||
bindsym Mod1+k mj
|
||||
bindsym Mod1+j mk
|
||||
bindsym Mod1+semicolon ml
|
||||
|
||||
# Snap client to the left, bottom, top, right:
|
||||
bindsym Mod1+j sh
|
||||
bindsym Mod1+k sj
|
||||
bindsym Mod1+j sk
|
||||
bindsym Mod1+semicolon sl
|
||||
|
||||
# Focus container on the left, bottom, top, right:
|
||||
bindsym Mod3+j wch
|
||||
…
|
||||
----------------------
|
||||
|
||||
=== Changing workspaces/moving clients to workspaces
|
||||
|
||||
To change to a specific workspace, the command is just the number of the
|
||||
workspace, e.g. +1+ or +3+. To move the current client to a specific workspace,
|
||||
prefix the number with an +m+.
|
||||
|
||||
Furthermore, you can switch to the next and previous workspace with the
|
||||
commands +nw+ and +pw+, which is handy for example if you have workspace
|
||||
1, 3, 4 and 9 and you want to cycle through them with a single key combination.
|
||||
|
||||
*Examples*:
|
||||
-------------------------
|
||||
bindsym Mod1+1 1
|
||||
bindsym Mod1+2 2
|
||||
...
|
||||
|
||||
bindsym Mod1+Shift+1 m1
|
||||
bindsym Mod1+Shift+2 m2
|
||||
...
|
||||
|
||||
bindsym Mod1+o nw
|
||||
bindsym Mod1+p pw
|
||||
-------------------------
|
||||
|
||||
=== Jumping to specific windows
|
||||
|
||||
Especially when in a multi-monitor environment, you want to quickly jump to a specific
|
||||
@ -340,34 +531,32 @@ ft::
|
||||
If the current window is floating, the next tiling window will be selected
|
||||
and vice-versa.
|
||||
|
||||
=== Changing colors
|
||||
=== Changing border style
|
||||
|
||||
You can change all colors which i3 uses to draw the window decorations and the
|
||||
bottom bar.
|
||||
|
||||
*Syntax*:
|
||||
--------------------------------------------
|
||||
colorclass border background text
|
||||
--------------------------------------------
|
||||
|
||||
Where colorclass can be one of:
|
||||
|
||||
client.focused::
|
||||
A client which currently has the focus.
|
||||
client.focused_inactive::
|
||||
A client which is the focused one of its container, but it does not have
|
||||
the focus at the moment.
|
||||
client.unfocused::
|
||||
A client which is not the focused one of its container.
|
||||
bar.focused::
|
||||
The current workspace in the bottom bar.
|
||||
bar.unfocused::
|
||||
All other workspaces in the bottom bar.
|
||||
|
||||
Colors are in HTML hex format, see below.
|
||||
To change the border of the current client, you can use +bn+ to use the normal
|
||||
border (including window title), +bp+ to use a 1-pixel border (no window title)
|
||||
and +bb+ to make the client borderless.
|
||||
|
||||
*Examples*:
|
||||
--------------------------------------
|
||||
# class border backgr. text
|
||||
client.focused #2F343A #900000 #FFFFFF
|
||||
--------------------------------------
|
||||
------------------
|
||||
bindsym Mod1+t bn
|
||||
bindsym Mod1+y bp
|
||||
bindsym Mod1+u bb
|
||||
------------------
|
||||
|
||||
=== Reloading/Restarting/Exiting
|
||||
|
||||
You can make i3 reload its configuration file with +reload+. You can also
|
||||
restart i3 inplace with the +restart+ command to get it out of some weird state
|
||||
(if that should ever happen) or to perform an upgrade without having to restart
|
||||
your X session. However, your layout is not preserved at the moment, meaning
|
||||
that all open windows will be in a single container in default layout. To exit
|
||||
i3 properly, you can use the +exit+ command, however you don’t need to (e.g.,
|
||||
simply killing your X session is fine aswell).
|
||||
|
||||
*Examples*:
|
||||
----------------------------
|
||||
bindsym Mod1+Shift+r restart
|
||||
bindsym Mod1+Shift+w reload
|
||||
bindsym Mod1+Shift+e exit
|
||||
----------------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user