95 lines
4.1 KiB
Plaintext
95 lines
4.1 KiB
Plaintext
External workspace bars
|
||
=======================
|
||
Michael Stapelberg <michael+i3@stapelberg.de>
|
||
May 2010
|
||
|
||
This document describes why the internal workspace bar is minimal and how an
|
||
external workspace bar can be used. It explains the concepts using +i3-wsbar+
|
||
as the reference implementation.
|
||
|
||
== Internal and external bars
|
||
|
||
The internal workspace bar of i3 is meant to be a reasonable default so that
|
||
you can use i3 without having too much hassle when setting it up. It is quite
|
||
simple and intended to stay this way. So, there is no way to display your own
|
||
information in this bar (unlike dwm, wmii, awesome, …).
|
||
|
||
We chose not to implement such a mechanism because that would be duplicating
|
||
already existing functionality of tools such as dzen2, xmobar and similar.
|
||
Instead, you should disable the internal bar and use an external workspace bar
|
||
(which communicates with i3 through its IPC interface).
|
||
|
||
== dock mode
|
||
|
||
You typically want to see the same workspace bar on every workspace on a
|
||
specific screen. Also, you don’t want to place the workspace bar somewhere
|
||
in your layout by hand. This is where dock mode comes in: When a program sets
|
||
the appropriate hint (_NET_WM_WINDOW_TYPE_DOCK), it will be managed in dock
|
||
mode by i3. That means it will be placed at the bottom of the screen (while
|
||
other edges of the screen are possible in the NetWM standard, this is not yet
|
||
implemented in i3), it will not overlap any other window and it will be on
|
||
every workspace for the specific screen it was placed on initially.
|
||
|
||
== The IPC interface
|
||
|
||
In the context of using an external workspace bar, the IPC interface needs to
|
||
provide the bar program with the current workspaces and output (as in VGA-1,
|
||
LVDS-1, …) configuration. In the other direction, the program has to be able
|
||
to switch to specific workspaces.
|
||
|
||
By default, the IPC interface is enabled and places its UNIX socket in
|
||
+~/.i3/ipc.sock+.
|
||
|
||
To learn more about the protocol which is used for IPC, see +docs/ipc+.
|
||
|
||
== Output changes (on-the-fly)
|
||
|
||
i3 implements the RandR API and can handle changing outputs quite well. So, an
|
||
external workspace bar implementation needs to make sure that when you change
|
||
the resolution of any of your screens (or enable/disable an output), the bars
|
||
will be adjusted properly.
|
||
|
||
== i3-wsbar, the reference implementation
|
||
|
||
Please keep in mind that +i3-wsbar+ is just a reference implementation. It is
|
||
shipped with i3 to have a reasonable default. Thus, +i3-wsbar+ is designed to
|
||
work well with dzen2 and there are no plans to make it more generic.
|
||
|
||
=== The big picture
|
||
|
||
The most common reason to use an external workspace bar is to integrate system
|
||
information such as what +i3status+ provides into the workspace bar (to save
|
||
screen space). So, we have +i3status+ or a similar program, which only provides
|
||
text output (formatted in some way). To display this text nicely on the screen,
|
||
there are programs such as dzen2, xmobar and similar. We will stick to dzen2
|
||
from here on. So, we have the output of i3status, which needs to go into dzen2
|
||
somehow. But we also want to display the list of workspaces. +i3-wsbar+ takes
|
||
input on stdin, combines it with a formatted workspace list and pipes it to
|
||
dzen2.
|
||
|
||
Please note that +i3-wsbar+ does not print its output to stdout. Instead, it
|
||
launches the dzen2 instances on its own. This is necessary to handle changes
|
||
in the available outputs (to place a new dzen2 on a new screen for example).
|
||
|
||
image:wsbar.png["Overview",link="wsbar.png"]
|
||
|
||
=== Running i3-wsbar
|
||
|
||
The most simple usage of i3-wsbar looks like this:
|
||
-------------------------------
|
||
i3-wsbar -c "dzen2 -x %x -dock"
|
||
-------------------------------
|
||
|
||
The +%x+ in the command name will be replaced by the X position of the output
|
||
for which this workspace bar is running. i3 will automatically place the
|
||
workspace bar on the correct output when dzen2 is started in dock mode. The
|
||
bar which you will see should look exactly like the internal bar of i3.
|
||
|
||
To actually get a benefit, you want to give +i3-wsbar+ some input:
|
||
------------------------------------------
|
||
i3status | i3-wsbar -c "dzen2 -x %x -dock"
|
||
------------------------------------------
|
||
|
||
It is recommended to place the above command in your i3 configuration file
|
||
to start it automatically with i3.
|