git.sur5r.net Git - i3/i3.github.io/blob - _docs/wsbar

   1 External workspace bars
   2 =======================
   3 Michael Stapelberg <michael+i3@stapelberg.de>
   4 May 2010
   5
   6 This document describes why the internal workspace bar is minimal and how an
   7 external workspace bar can be used. It explains the concepts using +i3-wsbar+
   8 as the reference implementation.
   9
  10 == Internal and external bars
  11
  12 The internal workspace bar of i3 is meant to be a reasonable default so that
  13 you can use i3 without having too much hassle when setting it up. It is quite
  14 simple and intended to stay this way. So, there is no way to display your own
  15 information in this bar (unlike dwm, wmii, awesome, …).
  16
  17 We chose not to implement such a mechanism because that would be duplicating
  18 already existing functionality of tools such as dzen2, xmobar and similar.
  19 Instead, you should disable the internal bar and use an external workspace bar
  20 (which communicates with i3 through its IPC interface).
  21
  22 == dock mode
  23
  24 You typically want to see the same workspace bar on every workspace on a
  25 specific screen. Also, you don’t want to place the workspace bar somewhere
  26 in your layout by hand. This is where dock mode comes in: When a program sets
  27 the appropriate hint (_NET_WM_WINDOW_TYPE_DOCK), it will be managed in dock
  28 mode by i3. That means it will be placed at the bottom of the screen (while
  29 other edges of the screen are possible in the NetWM standard, this is not yet
  30 implemented in i3), it will not overlap any other window and it will be on
  31 every workspace for the specific screen it was placed on initially.
  32
  33 == The IPC interface
  34
  35 In the context of using an external workspace bar, the IPC interface needs to
  36 provide the bar program with the current workspaces and output (as in VGA-1,
  37 LVDS-1, …) configuration. In the other direction, the program has to be able
  38 to switch to specific workspaces.
  39
  40 By default, the IPC interface is enabled and places its UNIX socket in
  41 +~/.i3/ipc.sock+.
  42
  43 To learn more about the protocol which is used for IPC, see +docs/ipc+.
  44
  45 == Output changes (on-the-fly)
  46
  47 i3 implements the RandR API and can handle changing outputs quite well. So, an
  48 external workspace bar implementation needs to make sure that when you change
  49 the resolution of any of your screens (or enable/disable an output), the bars
  50 will be adjusted properly.
  51
  52 == i3-wsbar, the reference implementation
  53
  54 Please keep in mind that +i3-wsbar+ is just a reference implementation. It is
  55 shipped with i3 to have a reasonable default. Thus, +i3-wsbar+ is designed to
  56 work well with dzen2 and there are no plans to make it more generic.
  57
  58 === The big picture
  59
  60 The most common reason to use an external workspace bar is to integrate system
  61 information such as what +i3status+ provides into the workspace bar (to save
  62 screen space). So, we have +i3status+ or a similar program, which only provides
  63 text output (formatted in some way). To display this text nicely on the screen,
  64 there are programs such as dzen2, xmobar and similar. We will stick to dzen2
  65 from here on. So, we have the output of i3status, which needs to go into dzen2
  66 somehow. But we also want to display the list of workspaces. +i3-wsbar+ takes
  67 input on stdin, combines it with a formatted workspace list and pipes it to
  68 dzen2.
  69
  70 Please note that +i3-wsbar+ does not print its output to stdout. Instead, it
  71 launches the dzen2 instances on its own. This is necessary to handle changes
  72 in the available outputs (to place a new dzen2 on a new screen for example).
  73
  74 image:wsbar.png["Overview",link="wsbar.png"]
  75
  76 === Running i3-wsbar
  77
  78 The most simple usage of i3-wsbar looks like this:
  79 -------------------------------
  80 i3-wsbar -c "dzen2 -x %x -dock"
  81 -------------------------------
  82
  83 The +%x+ in the command name will be replaced by the X position of the output
  84 for which this workspace bar is running. i3 will automatically place the
  85 workspace bar on the correct output when dzen2 is started in dock mode. The
  86 bar which you will see should look exactly like the internal bar of i3.
  87
  88 To actually get a benefit, you want to give +i3-wsbar+ some input:
  89 ------------------------------------------
  90 i3status | i3-wsbar -c "dzen2 -x %x -dock"
  91 ------------------------------------------
  92
  93 It is recommended to place the above command in your i3 configuration file
  94 to start it automatically with i3.