git.sur5r.net Git - i3/i3/blob - docs/wsbar

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