From: Michael Stapelberg Date: Thu, 27 May 2010 18:21:17 +0000 (+0200) Subject: Add documentation for external workspace bars X-Git-Tag: tree-pr2~76 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=086d1563cb521c3d6e93899af5fdfe35d45103bb;p=i3%2Fi3 Add documentation for external workspace bars --- diff --git a/docs/Makefile b/docs/Makefile index b17413ca..79e5019a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,5 +1,5 @@ -all: hacking-howto.html debugging.html userguide.html ipc.html multi-monitor.html +all: hacking-howto.html debugging.html userguide.html ipc.html multi-monitor.html wsbar.html hacking-howto.html: hacking-howto asciidoc -a toc -n $< @@ -16,6 +16,9 @@ ipc.html: ipc multi-monitor.html: multi-monitor asciidoc -a toc -n $< +wsbar.html: wsbar + asciidoc -a toc -n $< + clean: rm -f */*.{aux,log,toc,bm,pdf,dvi} rm -f *.log *.html diff --git a/docs/wsbar b/docs/wsbar new file mode 100644 index 00000000..9e379dd9 --- /dev/null +++ b/docs/wsbar @@ -0,0 +1,94 @@ +External workspace bars +======================= +Michael Stapelberg +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. diff --git a/docs/wsbar.dia b/docs/wsbar.dia new file mode 100644 index 00000000..d117ce07 Binary files /dev/null and b/docs/wsbar.dia differ diff --git a/docs/wsbar.png b/docs/wsbar.png new file mode 100644 index 00000000..0789dec5 Binary files /dev/null and b/docs/wsbar.png differ