87 lines
3.7 KiB
Plaintext
87 lines
3.7 KiB
Plaintext
External workspace bars
|
||
=======================
|
||
Michael Stapelberg <michael@i3wm.org>
|
||
April 2013
|
||
|
||
i3 comes with i3bar by default, a simple bar that is sufficient for most users.
|
||
In case you are unhappy with it, this document explains how to use a different,
|
||
external workspace bar. Note that we do not provide support for external
|
||
programs.
|
||
|
||
== 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.
|
||
|
||
== 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 or top 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 you can get the path to the socket
|
||
by calling +i3 --get-socketpath+.
|
||
|
||
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, an example implementation
|
||
|
||
+i3-wsbar+ used to be the reference implementation before we had +i3bar+.
|
||
Nowadays, it is not shipped with release tarballs, but you can still get it at
|
||
https://github.com/i3/i3/blob/next/contrib/i3-wsbar
|
||
|
||
=== The big picture
|
||
|
||
The most common reason to use an external workspace bar is to integrate system
|
||
information such as what +i3status+ or +conky+ provide into the workspace bar.
|
||
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"
|
||
------------------------------------------
|