- Command mode
---------------------
-This is the grammar for the command mode (your configuration file uses these commands, too).
+This is the grammar for the 'command mode' (your configuration file
+uses these commands, too).
left := <h> | <cursor-left>
right := <l> | <cursor-right>
with := <w> { [ <times> ] <where> }+ <space> <cmd>
jump := [ "<window class>[/<window title>]" | <workspace> [ <column> <row> ] ]
focus := focus [ <times> | floating | tiling | ft ]
-(travels the focus stack backwards the given amount of times (by default 1), so
- it selects the window which had the focus before you focused the current one when
- specifying "focus 1".
- The special values 'floating' (select the next floating window), 'tiling'
- (select the next tiling window), 'ft' (if the current window is floating,
- select the next tiling window and vice-versa) are also valid)
+ (travels the focus stack backwards, <times> number of times (by default 1).
+ So by specifying "focus 1" it selects the window which last had the focus
+ before you focused the current one window.
+ The following 3 special values are also valid:
+ 'floating' (select the next floating window).
+ 'tiling' (select the next tiling window).
+ 'ft' (toggle tiling/floating: if the current window is floating,
+ select the next tiling window and vice-versa)
special := [ exec <path> | kill | exit | restart ]
-input := [ <cmd> | <with> | <jump> | <focus> | <special> ]
+input := [ <cmd> | <with> | <jump> | <focus> | <special> ]
you can cancel command mode by pressing escape anytime.
-You need the following libraries. The version given is to be understand as the minimum
-version. However, if any of these libraries changes the API, i3 may not compile anymore.
-In that case, please try using the versions mentioned below until a fix is provided.
+You need the following libraries. The version given is to be understood as the
+minimum version required. However, if any of these libraries changes the API,
+i3 may not compile anymore. In that case, please try using the versions
+mentioned below until a fix is provided.
* xcb-proto-1.3 (2008-12-10)
* libxcb-1.1.93 (2008-12-11)
Dear package maintainer,
-thanks for packaging i3. By doing so, you are improving your distribution and i3 in general.
+thanks for packaging i3. By doing so, you are improving your distribution
+and i3 in general.
-Please read the file DEPENDS now, so you know which libraries are necessary and where to
-get them from if your distribution does not already have packages for them.
+Please read the file DEPENDS now, so you know which libraries are necessary
+and where to get them from if your distribution does not already have
+packages for them.
+
+Please make sure the manpage for i3 will be properly created and installed
+in your package.
-Please make sure the manpage for i3 will be properly created and installed in your package.
On debian, this looks like this:
# Compilation
mkdir -p $(CURDIR)/debian/i3-wm/usr/share/man/man1
cp man/i3.1 $(CURDIR)/debian/i3-wm/usr/share/man/man1
-If you got any questions, ideas, hints, problems or whatever, please do not
-hesitate to contact me. I will help you out. Just drop me an E-Mail (find the address at
-http://michael.stapelberg.de/Kontakt, scroll down to bottom), contact me using the same
-address in jabber or ask on our IRC channel (#i3 on irc.twice-irc.de).
+If you have any questions, ideas, hints, problems or whatever, please do not
+hesitate to contact me. I will help you out. Just drop me an E-Mail (find the
+address at http://michael.stapelberg.de/Kontakt, scroll down to bottom),
+contact me using the same address in jabber or ask on our IRC channel:
+(#i3 on irc.twice-irc.de).
Thanks again for your efforts,
Michael
Debugging i3: How To
-==================
+====================
Michael Stapelberg <michael+i3@stapelberg.de>
April 2009
== Enabling logging
i3 spits out much information onto stdout. To have a clearly defined place
-where logfiles will be saved, you should redirect stdout and stderr in
-xsession. While you’re at it, putting each run of i3 in a separate logfile with
-date/time in it is a good idea to not get confused about the different logfiles
-later on.
+where log files will be saved, you should redirect stdout and stderr in
+xsession. While you’re at it, putting each run of i3 in a separate log file
+with date/time in it is a good idea to not get confused about the different
+log files later on.
--------------------------------------------------------------------
exec /usr/bin/i3 >/home/michael/i3/i3log-$(date +'%F-%k-%M-%S') 2>&1
--------------------------------------------------------------------
-== Enabling coredumps
+== Enabling core dumps
-When i3 crashes, often you have the chance of getting a coredump (an image of
-the memory of the i3 process which can be loaded into a debugger). To get a
-core-dump, you have to make sure that the user limit for core dump files is set
+When i3 crashes, often you have the chance of getting a 'core dump' (an image
+of the memory of the i3 process which can be loaded into a debugger). To get a
+core dump, you have to make sure that the user limit for core dump files is set
high enough. Many systems ship with a default value which even forbids core
-dumps completely. To disable the limit completely and thus enable coredumps,
+dumps completely. To disable the limit completely and thus enable core dumps,
use the following command (in your .xsession, before starting i3):
-------------------
== Compiling with debug symbols
-To actually get useful coredumps, you should make sure that your version of i3
+To actually get useful core dumps, you should make sure that your version of i3
is compiled with debug symbols, that is, that they are not stripped during the
build process. You can check whether your executable contains symbols by
issuing the following command:
== Generating a backtrace
Once you have made sure that your i3 is compiled with debug symbols and that
-coredumps are enabled, you can start getting some sense out of the coredumps.
+core dumps are enabled, you can start making sense out of the core dumps.
-Because the coredump depends on the original executable (and its debug
+Because the core dump depends on the original executable (and its debug
symbols), please do this as soon as you encounter the problem. If you
-re-compile i3, your coredump might be useless afterwards.
+re-compile i3, your core dump might be useless afterwards.
Please install +gdb+, a debugger for C. No worries, you don’t need to learn it
now. Start gdb using the following command (replacing the actual name of the
-coredump of course):
+core dump of course):
----------------------------
gdb $(which i3) core.i3.3849
backtrace full
--------------
-== Sending bugreports/debugging on IRC
+== Sending bug reports/debugging on IRC
-When sending bugreports, please paste the relevant part of the log (if in
+When sending bug reports, please paste the relevant part of the log (if in
doubt, please send us rather too much information than too less) and the whole
-backtrace (if there was a coredump).
+backtrace (if there was a core dump).
When debugging with us in IRC, be prepared to use a so called nopaste service
-such as http://nopaste.info because pasting large amounts of text in IRC
-sometimes leads to incomplete lines (servers have line length limitations) or
-flood kicks.
+such as http://nopaste.info or http://pastebin.com because pasting large
+amounts of text in IRC sometimes leads to incomplete lines (servers have line
+length limitations) or flood kicks.
In the case of i3, the tasks (and order of them) are the following:
. Grab the key bindings (events will be sent upon keypress/keyrelease)
-. Iterate through all existing windows (if the window manager is not started as the first
- client of X) and manage them (= reparent them, create window decorations)
+. Iterate through all existing windows (if the window manager is not started as
+ the first client of X) and manage them (reparent them, create window
+ decorations, etc.)
. When new windows are created, manage them
. Handle the client’s `_WM_STATE` property, but only the `_WM_STATE_FULLSCREEN`
. Handle the client’s `WM_NAME` property
. Handle button (as in mouse buttons) presses for focus/raise on click
. Handle expose events to re-draw own windows such as decorations
. React to the user’s commands: Change focus, Move windows, Switch workspaces,
-Change the layout mode of a container (default/stacking), Start a new application,
-Restart the window manager
+ Change the layout mode of a container (default/stacking/tabbed), start a new
+ application, restart the window manager
In the following chapters, each of these tasks and their implementation details
will be discussed.
Traditionally, there are two approaches to managing windows: The most common
one nowadays is floating, which means the user can freely move/resize the
windows. The other approach is called tiling, which means that your window
-manager distributing windows to use as much space as possible while not
-overlapping.
+manager distributes windows to use as much space as possible while not
+overlapping each other.
The idea behind tiling is that you should not need to waste your time
moving/resizing windows while you usually want to get some work done. After
|========
You can really think of the layout table like a traditional HTML table, if
-you’ve ever designed one. Especially col- and rowspan work equally. Below you
-see an example of colspan=2 for the first container (which has T1 as window).
+you’ve ever designed one. Especially col- and rowspan work similarly. Below,
+you see an example of colspan=2 for the first container (which has T1 as
+window).
[width="15%",cols="^asciidoc"]
|========
this first.
include/*.h::
-Contains forward definitions for all public functions, aswell as
+Contains forward definitions for all public functions, as well as
doxygen-compatible comments (so if you want to get a bit more of the big
picture, either browse all header files or use doxygen if you prefer that).
fullscreen, see if its class/name matches a pattern, kill it, …).
src/commands.c::
-Parsing commands and actually execute them (focussing, moving, …).
+Parsing commands and actually executing them (focusing, moving, …).
src/config.c::
Parses the configuration file.
Contains functions for floating mode (mostly resizing/dragging).
src/handlers.c::
-Contains all handlers for all kind of X events (new window title, new hints,
+Contains all handlers for all kinds of X events (new window title, new hints,
unmapping, key presses, button presses, …).
src/ipc.c::
=== Workspace
A workspace is identified by its number. Basically, you could think of
-workspaces as different desks in your bureau, if you like the desktop
+workspaces as different desks in your office, if you like the desktop
methaphor. They just contain different sets of windows and are completely
separate of each other. Other window managers also call this ``Virtual
desktops''.
state-property of keypress/keyrelease events properly. The Mode_switch bit is
not set and we need to get it using XkbGetState. This means we cannot pass X
our combination of modifiers containing Mode_switch when grabbing the key and
-therefore need to grab the keycode itself without any modiffiers. This means,
+therefore need to grab the keycode itself without any modifiers. This means,
if you bind Mode_switch + keycode 38 ("a"), i3 will grab keycode 38 ("a") and
check on each press of "a" if the Mode_switch bit is set using XKB. If yes, it
will handle the event, if not, it will replay the event.
is rendered correctly. To move/resize windows, a window is ``configured'' in
X11-speak.
-Some applications, such as MPlayer obivously assume the window manager is
+Some applications, such as MPlayer obviously assume the window manager is
stupid and try to configure their windows by themselves. This generates an
event called configurerequest. i3 handles these events and tells the window the
size it had before the configurerequest (with the exception of not yet mapped
== Size hints
-Size hints specify the minimum/maximum size for a given window aswell as its
+Size hints specify the minimum/maximum size for a given window as well as its
aspect ratio. This is important for clients like mplayer, who only set the
aspect ratio and resize their window to be as small as possible (but only with
some video outputs, for example in Xv, while when using x11, mplayer does the
(+grabwin+)
* Another window, 2px width and as high as your screen (or vice versa for
horizontal resizing) is created. Its background color is the border color and
- it is only there to signalize the user how big the container will be (it
+ it is only there to inform the user how big the container will be (it
creates the impression of dragging the border out of the container).
* The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer
- and enter an own event loop which will pass all events (expose events) but
+ and enter its own event loop which will pass all events (expose events) but
motion notify events. This function then calls the specified callback
(+resize_callback+) which does some boundary checking and moves the helper
window. As soon as the mouse button is released, this loop will be
When you want to send a patch because you fixed a bug or implemented a cool
feature (please talk to us before working on features to see whether they are
-maybe already implemented, not possible because of some reason or don’t fit
+maybe already implemented, not possible for some some reason, or don’t fit
into the concept), please use git to create a patchfile.
First of all, update your working copy to the latest version of the master
git format-patch origin
-----------------------
-Just send us the generated file via mail.
+Just send us the generated file via email.
To send a message to i3, you have to format in the binary message format which
i3 expects. This format specifies a magic string in the beginning to ensure
-the integrity of messages (to prevent follow-up errors). Afterwards follows
-the length of the payload of the message as 32-bit integer and the type of
-the message as 32-bit integer (the integers are not converted, so they are
-in native byte order).
+the integrity of messages (to prevent follow-up errors). Following the magic
+string comes the length of the payload of the message as 32-bit integer, and
+the type of the message as 32-bit integer (the integers are not converted, so
+they are in native byte order).
The magic string currently is "i3-ipc" and will only be changed when a change
in the IPC API is done which breaks compatibility (we hope that we don’t need
}
$sock->write(format_ipc_command("exit"));
-------------------------------------------------------------
+------------------------------------------------------------------------------
== Receiving replies from i3
-Replies of i3 usually consist of a simple string (the length of the string
+Replies from i3 usually consist of a simple string (the length of the string
is the message_length, so you can consider them length-prefixed) which in turn
contain the JSON serialization of a data structure. For example, the
GET_WORKSPACES message returns an array of workspaces (each workspace is a map
situation can happen: You send a GET_WORKSPACES request but you receive a
"workspace" event before receiving the reply to GET_WORKSPACES. If your
program does not want to cope which such kinds of race conditions (an
-event based library may not have a problem here), I advise to create a separate
-connection to receive events.
+event based library may not have a problem here), I suggest you create a
+separate connection to receive events.
=== Subscribing to events
Michael Stapelberg <michael+i3@stapelberg.de>
March 2010
-…or: oh no, I have an nvidia graphics card!
+…or: oh no, I have an nVidia graphics card!
== The quick fix
-If you are using the nvidia binary graphics driver, you need to use the
-+--force-xinerama+ flag when starting i3, like so (in your xsession):
+If you are using the nVidia binary graphics driver (also known as 'blob')
+you need to use the +--force-xinerama+ flag (in your .xsession) when starting
+i3, like so:
.Example:
----------------------------------------------
-exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1
+exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1
----------------------------------------------
== The explanation
Starting with version 3.ε, i3 uses the RandR (Rotate and Resize) API instead
-of Xinerama. This is due to the reason that RandR provides more information
+of Xinerama. The reason for this, is that RandR provides more information
about your outputs and connected screens than Xinerama does. To be specific,
the code which handled on-the-fly screen reconfiguration (meaning without
restarting the X server) was a very messy heuristic and most of the time did
screens or any additional information). Xinerama simply was not designed
for dynamic configuration.
-So, RandR came up as a more powerful alternative (RandR 1.2 to be specific).
+So RandR came along, as a more powerful alternative (RandR 1.2 to be specific).
It offers all of Xinerama’s possibilities and lots more. Using the RandR API
made our code much more robust and clean. Also, you can now reliably assign
workspaces to output names instead of some rather unreliable screen identifier
(position inside the list of screens, which could change, and so on…).
-As RandR is around for about three years, it seemed like a very good idea to
-us and it still is a very good one. What we did not expect, however, was the
-nVidia binary driver. It still does not support RandR (as of March 2010), even
-though nVidia announced that it will support RandR eventually. What does this
-mean for you, if you are stuck with the binary driver for some reason (say
-the free drivers don’t work with your card)? First of all, you are stuck with
-TwinView and cannot use +xrandr+. While this ruins the user experience, the
-more grave problem is that the nVidia driver not only does not support dynamic
-configuration using RandR, it also does not even expose correct multi-monitor
-information via the RandR API. So, in some setups, i3 will not find any
-screens, in others it will find one large screen which actually contains both
-of your physical screens (but it will not know that these are two screens).
+As RandR has been around for about three years as of this writing, it seemed
+like a very good idea to us, and it still is a very good one. What we did not
+expect, however, was the nVidia binary driver. It still does not support RandR
+(as of March 2010), even though nVidia has announced that it will support RandR
+eventually. What does this mean for you, if you are stuck with the binary
+driver for some reason (say the free drivers don’t work with your card)? First
+of all, you are stuck with TwinView and cannot use +xrandr+. While this ruins
+the user experience, the more grave problem is that the nVidia driver not only
+does not support dynamic configuration using RandR, it also does not expose
+correct multi-monitor information via the RandR API. So, in some setups, i3
+will not find any screens; in others, it will find one large screen which
+actually contains both of your physical screens (but it will not know that
+these are two screens).
For this very reason, we decided to implement the following workaround: As
long as the nVidia driver does not support RandR, an option called
+--force-xinerama+ is available in i3. This option gets the list of screens
-*once* when starting and never updates it. As the nVidia driver cannot do
+*once* when starting, and never updates it. As the nVidia driver cannot do
dynamic configuration anyways, this is not a big deal.
== See also
image:keyboard-layer2.png["Keys to use with Shift+Mod1",width=600,link="keyboard-layer2.png"]
As i3 uses keycodes in the default configuration, it does not matter which
-keyboard layout you actually use. The key positions are what matters (of course you can
-also use keysymbols, see below).
+keyboard layout you actually use. The key positions are what matters (of course
+you can also use keysymbols, see below).
The red keys are the modifiers you need to press (by default), the blue keys
are your homerow.
It is important to keep in mind that i3 uses a table to manage your windows. At
the moment, you have exactly one column and one row which leaves you with one
-cell. In this cell there is a container which is where your new terminal is opened.
+cell. In this cell there is a container, which is where your new terminal is
+opened.
If you now open another terminal, you still have only one cell. However, the
container in that cell holds both of your terminals. So, a container is just a
To move the focus between the two terminals, you use the direction keys which
you may know from the editor +vi+. However, in i3, your homerow is used for
these keys (in +vi+, the keys are shifted to the left by one for compatibility
-with most keyboard layouts). Therefore, +Mod1+J+ is left, +Mod1+K+ is down, +Mod1+L+
-is up and `Mod1+;` is right. So, to switch between the terminals, use +Mod1+K+ or
-+Mod1+L+.
+with most keyboard layouts). Therefore, +Mod1+J+ is left, +Mod1+K+ is down,
++Mod1+L+ is up and `Mod1+;` is right. So, to switch between the terminals,
+use +Mod1+K+ or +Mod1+L+.
To create a new row/column (and a new cell), you can simply move a terminal (or
-any other window) to the direction you want to expand your table. So, let’s
+any other window) in the direction you want to expand your table. So, let’s
expand the table to the right by pressing `Mod1+Shift+;`.
image:two_columns.png[Two columns]
you want to use. If the workspace does not exist yet, it will be created.
A common paradigm is to put the web browser on one workspace, communication
-applications (+mutt+, +irssi+, ...) on another one and the ones with which you
-work on the third one. Of course, there is no need to follow this approach.
+applications (+mutt+, +irssi+, ...) on another one, and the ones with which you
+work, on the third one. Of course, there is no need to follow this approach.
If you have multiple screens, a workspace will be created on each screen at
startup. If you open a new workspace, it will be bound to the screen you
=== Resizing columns/rows
-To resize columns or rows just grab the border between the two columns/rows
+To resize columns or rows, just grab the border between the two columns/rows
and move it to the wanted size. Please keep in mind that each cell of the table
holds a +container+ and thus you cannot horizontally resize single windows. If
-you need applications with different horizontal sizes place them in seperate
+you need applications with different horizontal sizes, place them in seperate
cells one above the other.
See <<resizingconfig>> for how to configure i3 to be able to resize
=== Restarting i3 inplace
-To restart i3 inplace (and thus get into a clean state if there is a bug or
+To restart i3 inplace (and thus get into a clean state if there is a bug, or
to upgrade to a newer version of i3) you can use +Mod1+Shift+r+. Be aware,
though, that this kills your current layout and all the windows you have opened
will be put in a default container in only one cell. Saving layouts will be
Floating mode is the opposite of tiling mode. The position and size of a window
are not managed by i3, but by you. Using this mode violates the tiling
paradigm but can be useful for some corner cases like "Save as" dialog
-windows or toolbar windows (GIMP or similar).
+windows, or toolbar windows (GIMP or similar).
You can enable floating mode for a window by pressing +Mod1+Shift+Space+. By
dragging the window’s titlebar with your mouse you can move the window
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 use in Xmodmap to remap your keys. To get the current mapping of your
- keys, use +xmodmap -pke+.
+* 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 use in Xmodmap to remap your keys. To get the current
+ mapping of your keys, use +xmodmap -pke+.
* Keycodes 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 (when using +xmodmap+).
My recommendation is: If you often switch keyboard layouts but you want to keep
-your bindings in the same physical location on the keyboard use keycodes. If you
-don’t switch layouts and want a clean and simple config file, use keysyms.
+your bindings in the same physical location on the keyboard, use keycodes.
+If you don’t switch layouts, and want a clean and simple config file, use
+keysyms.
*Syntax*:
----------------------------------
you can press Mod1, click into a window using your left mouse button, and drag
it to the position you want.
-When holding the floating modifier, you can resize a floating window by pressing
-the right mouse button on it and moving around while holding it. If you hold the
-shift button as well, the resize will be proportional.
+When holding the floating modifier, you can resize a floating window by
+pressing the right mouse button on it and moving around while holding it. If
+you hold the shift button as well, the resize will be proportional.
*Syntax*:
--------------------------------
[[assign_workspace]]
-It is recommended that you match on window classes whereever possible because
-some applications first create their window and then worry about setting the
+It is recommended that you match on window classes wherever possible because
+some applications first create their window, and then worry about setting the
correct title. Firefox with Vimperator comes to mind. The window starts up
-being named Firefox and only when Vimperator is loaded the title changes. As
-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.
+being named Firefox, and only when Vimperator is loaded does the title change.
+As 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
Note that the arrow is not required, it just looks good :-). If you decide to
use it, it has to be a UTF-8 encoded arrow, not "->" or something like that.
-=== Automatically starting applications on startup
+=== Automatically starting applications on i3 startup
By using the +exec+ keyword outside a keybinding, you can configure which
-commands will be performed by i3 on initial startup (not when restarting inplace
-however). These commands will be run in order.
+commands will be performed by i3 on initial startup (not when restarting i3
+in-place however). These commands will be run in order.
*Syntax*:
------------
workspace <number> output <output>
----------------------------------
-The output is the name of the RandR output you attach your screen to. On a
+The 'output' is the name of the RandR output you attach your screen to. On a
laptop, you might have VGA1 and LVDS1 as output names. You can see the
available outputs by running +xrandr --current+.
workspace <number> output <output> name
---------------------------------------
-For more details about the output-part of this command, see above.
+For more details about the 'output' part of this command, see above.
*Examples*:
--------------------------
client.focused #2F343A #900000 #FFFFFF
--------------------------------------
-Note that for the window decorations the color around the child window is the
-background color and the border color is only the two thin lines at the top of
+Note that for the window decorations, the color around the child window is the
+background color, and the border color is only the two thin lines at the top of
the window.
=== Interprocess communication
i3 uses unix sockets to provide an IPC interface. This allows third-party
-programs to get information like the current workspaces to display a workspace
-bar, and to control i3.
+programs to get information from i3, such as the current workspaces
+(to display a workspace bar), and to control i3.
To enable it, you have to configure a path where the unix socket will be
stored. The default path is +/tmp/i3-ipc.sock+.
ipc-socket /tmp/i3-ipc.sock
----------------------------
-You can then use the +i3-msg+ application to perform any command listed in the next
-section.
+You can then use the +i3-msg+ application to perform any command listed in
+the next section.
=== Disable focus follows mouse
If you have a setup where your mouse usually is in your way (like a touchpad
on your laptop which you do not want to disable completely), you might want
-to disable focus follows mouse and control focus only by using your keyboard.
+to disable 'focus follows mouse' and control focus only by using your keyboard.
The mouse will still be useful inside the currently active window (for example
to click on links in your browser window).
bindsym Mod1+t t
--------------
-=== Focussing/Moving/Snapping clients/containers/screens
+=== Focusing/Moving/Snapping clients/containers/screens
To change the focus, use one of the +h+, +j+, +k+ and +l+ commands, meaning
-left, down, up, right (respectively). To focus a container, prefix it with +wc+,
-to focus a screen, prefix it with +ws+.
+left, down, up, right (respectively). 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
+The same principle applies for moving and snapping: just prefix the command
with +m+ when moving and with +s+ when snapping:
*Examples*:
workspace, e.g. +1+ or +3+. To move the current client to a specific workspace,
prefix the number with an +m+.
-You can also 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.
+You can also 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*:
-------------------------
=== Jumping to specific windows
-Often when in a multi-monitor environment, you want to quickly jump to a specific
-window. For example while working on workspace 3 you may want to jump to
-your mailclient to mail your boss that you’ve achieved some important goal. Instead
-of figuring out how to navigate to your mailclient, it would be more convenient to
-have a shortcut.
+Often when in a multi-monitor environment, you want to quickly jump to a
+specific window. For example, while working on workspace 3 you may want to
+jump to your mail client to email your boss that you’ve achieved some
+important goal. Instead of figuring out how to navigate to your mailclient,
+it would be more convenient to have a shortcut.
*Syntax*:
----------------------------------------------------
jump workspace [ column row ]
----------------------------------------------------
-You can either use the same matching algorithm as in the +assign+ command (see above)
-or you can specify the position of the client if you always use the same layout.
+You can either use the same matching algorithm as in the +assign+ command
+(see above) or you can specify the position of the client if you always use
+the same layout.
*Examples*:
--------------------------------------
This feature is like the jump feature: It allows you to directly jump to a
specific window (this means switching to the appropriate workspace and setting
focus to the windows). However, you can directly mark a specific window with
-an arbitrary label and use it afterwards. You do not need to ensure
-that your windows have unique classes or titles, and you do not need to change
-your configuration file.
+an arbitrary label and use it afterwards. You do not need to ensure that your
+windows have unique classes or titles, and you do not need to change your
+configuration file.
As the command needs to include the label with which you want to mark the
window, you cannot simply bind it to a key. +i3-input+ is a tool created
=== Traveling the focus stack
-This mechanism can be thought of as the opposite of the +jump+ command. It travels
-the focus stack and jumps to the window which had focus previously.
+This mechanism can be thought of as the opposite of the +jump+ command.
+It travels the focus stack and jumps to the window which had focus previously.
*Syntax*:
--------------
focus [number] | floating | tiling | ft
--------------
-Where +number+ by default is 1 meaning that the next client in the focus stack will
-be selected.
+Where +number+ by default is 1 meaning that the next client in the focus stack
+will be selected.
The special values have the following meaning:
tiling::
The next tiling window is selected.
ft::
- If the current window is floating, the next tiling window will be selected
- and vice-versa.
+ If the current window is floating, the next tiling window will be
+ selected; and vice-versa.
=== Changing border style
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 as well).
+that all open windows will end up in a single container in default layout
+after the restart. To exit i3 properly, you can use the +exit+ command,
+however you don’t need to (simply killing your X session is fine as well).
*Examples*:
----------------------------
with support for multiple monitors in mind. This section will explain how to
handle multiple monitors.
-When you have only one monitor things are simple. You usually start with
+When you have only one monitor, things are simple. You usually start with
workspace 1 on your monitor and open new ones as you need them.
When you have more than one monitor, each monitor will get an initial
-workspace. The first monitor gets 1, the second gets 2 and a possible third would
-get 3. When you switch to a workspace on a different monitor, i3 will switch
-to that monitor and then switch to the workspace. This way, you don’t need
-shortcuts to switch to a specific monitor, and you don’t need to remember where
-you put which workspace. New workspaces will be opened on the currently active
-monitor. It is not possible to have a monitor without a workspace.
-
-The idea of making workspaces global is based on the observation that most users
-have a very limited set of workspaces on their additional monitors. They are
-often used for a specific task (browser, shell) or for monitoring several
-things (mail, IRC, syslog, …). Thus, using one workspace on one monitor and
-"the rest" on the other monitors often makes sense. However, as you can
-create an unlimited number of workspaces in i3 and tie them to specific screens,
-you can have the "traditional" approach of having X workspaces per screen by
-changing your configuration (using modes, for example).
+workspace. The first monitor gets 1, the second gets 2 and a possible third
+would get 3. When you switch to a workspace on a different monitor, i3 will
+switch to that monitor and then switch to the workspace. This way, you don’t
+need shortcuts to switch to a specific monitor, and you don’t need to remember
+where you put which workspace. New workspaces will be opened on the currently
+active monitor. It is not possible to have a monitor without a workspace.
+
+The idea of making workspaces global is based on the observation that most
+users have a very limited set of workspaces on their additional monitors.
+They are often used for a specific task (browser, shell) or for monitoring
+several things (mail, IRC, syslog, …). Thus, using one workspace on one monitor
+and "the rest" on the other monitors often makes sense. However, as you can
+create an unlimited number of workspaces in i3 and tie them to specific
+screens, you can have the "traditional" approach of having X workspaces per
+screen by changing your configuration (using modes, for example).
=== Configuring your monitors
-To help you get going if you have never used multiple monitors before, here is a
-short overview of the xrandr options which will probably be of interest to you.
-It is always useful to get an overview of the current screen configuration.
+To help you get going if you have never used multiple monitors before, here is
+a short overview of the xrandr options which will probably be of interest to
+you. It is always useful to get an overview of the current screen configuration.
Just run "xrandr" and you will get an output like the following:
---------------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
$ xrandr
Screen 0: minimum 320 x 200, current 1280 x 800, maximum 8192 x 8192
VGA1 disconnected (normal left inverted right x axis y axis)
connected to one of the ports but xrandr still says "disconnected", you should
check your cable, monitor or graphics driver.
-The maximum resolution you can see at the end of the first line
-is the maximum combined resolution of your monitors. By default, it is usually
-too low and has to be increased by editing +/etc/X11/xorg.conf+.
+The maximum resolution you can see at the end of the first line is the maximum
+combined resolution of your monitors. By default, it is usually too low and has
+to be increased by editing +/etc/X11/xorg.conf+.
So, say you connected VGA1 and want to use it as an additional screen:
-------------------------------------------
This command makes xrandr try to find the native resolution of the device
connected to +VGA1+ and configures it to the left of your internal flat panel.
When running "xrandr" again, the output looks like this:
------------------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
$ xrandr
Screen 0: minimum 320 x 200, current 2560 x 1024, maximum 8192 x 8192
VGA1 connected 1280x1024+0+0 (normal left inverted right x axis y axis) 338mm x 270mm
720x400 85.0
640x400 85.1
640x350 85.1
------------------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
Please note that i3 uses exactly the same API as xrandr does, so it will see
only what you can see in xrandr.
bind Mod1+Shift+24 kill
# Mod1+v starts dmenu and launches the selected application
-# for now, we don’t have an own launcher
+# for now, we don’t have a launcher of our own.
bind Mod1+55 exec /usr/bin/dmenu_run
# Mod1+Shift+e exits i3
1.) Welcome to i3!
-This message provides you with an overview of the default keybindings to use i3.
+This message provides an overview of the default keybindings to use i3.
Please also make sure to have a look at the man page and the user's guide:
http://i3.zekjur.net/docs/userguide.html
2.) Configuration Files
/etc/i3/config is the default configuration. It is recommended to copy it and
-afterwards edit it to suit your needs (you can especially disable this message):
+afterwards edit it to suit your needs (in particular, you may want to disable
+this message):
cp /etc/i3/config ~/.i3/config
The following explanation is related to the QWERTY layout, but as the default
configuration uses keycodes instead of keysymbols for binding, you still have
-to press the same keys, regardless of your keyboard layout.
+to press the same physical keys, regardless of your keyboard layout.
The Mod1 key is usually bound to the "Alt" key on your keyboard.
the arrow keys on your keyboard, if you prefer them.
Mod1+<directional key> moves the focus to the window in the given direction
-Mod1+Shift+<directional key> moves the window to the given direction,
+Mod1+Shift+<directional key> moves the window to the given direction
Mod1+<number> opens the corresponding workspace
-Mod1+Shift+<number> moves a window to the wished workspace
+Mod1+Shift+<number> moves a window to the selected workspace
Mod1+h sets the mode of a container to stacking
Mod1+e sets the mode back to default
Mod1+f toggles fullscreen mode for the current window
Mod1+Shift+Space toggles floating mode for the current window
Mod1+Shift+q closes a window
-Mod1+Shift+r restarts i3 in-place (you will lose your layout, though)
+Mod1+Shift+r restarts i3 in-place (at this time, you will lose your layout)
Mod1+Shift+e exits i3
If you have any questions, please don't hesitate to ask!
i3-input(1)
=========
+
Michael Stapelberg <michael+i3@stapelberg.de>
v3.delta, November 2009
== NAME
-i3-input - interactively take a command for i3
+i3-input - interactively take a command for i3 window manager
== SYNOPSIS
== DESCRIPTION
-i3-input is a tool to take commands (or parts of a command) and then send it
-to i3. This is useful for example for the mark/goto command.
+i3-input is a tool to take commands (or parts of a command) composed by
+the user, and send it/them to i3. This is useful, for example, for the
+mark/goto command.
== EXAMPLE
i3-msg(1)
=========
+
Michael Stapelberg <michael+i3@stapelberg.de>
v3.delta, November 2009
== NAME
-i3-msg - send messages to i3
+i3-msg - send messages to i3 window manager
== SYNOPSIS
happens.
Mod1+Shift+r::
-Restarts i3 in place (without losing any windows, but the layout).
+Restarts i3 in place (without losing any windows, but at this time, the layout
+and placement of windows is not retained).
Mod1+Shift+e::
Exits i3.
== TODO
-There is still lot of work to do. Please check our bugtracker for up-to-date information
-about tasks which are still not finished.
+There is still lot of work to do. Please check our bugtracker for up-to-date
+information about tasks which are still not finished.
== SEE ALSO
-You should have a copy of the userguide (featuring nice screenshots/graphics which is why this
-is not integrated into this manpage), the debugging guide and the "how to hack" guide. If you
-are building from source, run +make -C docs+.
+You should have a copy of the userguide (featuring nice screenshots/graphics
+which is why this is not integrated into this manpage), the debugging guide,
+and the "how to hack" guide. If you are building from source, run:
+ +make -C docs+
You can also access these documents online at http://i3.zekjur.net/
projects / i3 / i3 / commitdiff