docs: for the new status bar feature

refs: https://github.com/wez/wezterm/issues/500

.gitignore

@@ -15,6 +15,7 @@
 /docs/config/lua/wezterm/index.md
 /docs/config/lua/pane/index.md
 /docs/config/lua/window/index.md
+/docs/config/lua/window-events/index.md
 /docs/config/lua/keyassignment/index.md
 **/*.rs.bk
 .*.sw*

docs/changelog.md

@@ -46,6 +46,7 @@ brief notes about them may accumulate here.
 * X11: fix an issue where SHIFT-Enter was not recognized [#516](https://github.com/wez/wezterm/issues/516)
 * X11: improved DPI detection for high-DPI displays. [#515](https://github.com/wez/wezterm/issues/515)
 * X11: we now load the XCursor themes when possible, which means that the mouse cursor is now generally a bit larger and clearer as well as conforming more with the prevailing style of the desktop environment. [#524](https://github.com/wez/wezterm/issues/524)
+* New: [window:set_right_status](config/lua/window/set_right_status.md) allows setting additional status information in the tab bar. [#500](https://github.com/wez/wezterm/issues/500)
 
 ### 20210203-095643-70a364eb
 

docs/config/lua/config/status_update_interval.md

@@ -0,0 +1,7 @@
+# `status_update_interval = 1000`
+
+*Since: nightly builds only*
+
+Specifies the number of milliseconds that need to elapse between triggering the
+[update-right-status](../window-events/update-right-status.md) hook.
+

docs/config/lua/window-events/index.md

@@ -1,9 +0,0 @@
-
-# Events emitted by the `Window` object
-
-The following events can be handled using [wezterm.on](../wezterm/on.md):
-
-
-  - [open-uri](open-uri.md)
-  - [window-config-reloaded](window-config-reloaded.md)
-  - [window-resized](window-resized.md)

docs/config/lua/window-events/update-right-status.md

@@ -0,0 +1,24 @@
+# `update-right-status`
+
+*Since: nightly builds only*
+
+The `update-right-status` event is emitted periodically (based on the
+interval specified by the [status_update_interval](../config/status_update_interval.md)
+configuration value).
+
+There is no defined return value for the event, but its purpose is to allow
+you the chance to carry out some activity and then ultimately call
+[window:set_right_status](../window/set_right_status.md).
+
+The first event parameter is a [`window` object](../window/index.md) that
+represents the gui window.
+
+The second event parameter is a [`pane` object](../pane/index.md) that
+represents the active pane in that window.
+
+`wezterm` will ensure that only a single instance of this event is outstanding;
+if the hook takes longer than the
+[status_update_interval](../config/status_update_interval.md) to complete,
+`wezterm` won't schedule another call until `status_update_interval`
+milliseconds have elapsed since the last call completed.
+

docs/config/lua/window/set_right_status.md

@@ -0,0 +1,126 @@
+# `window:set_right_status(string)`
+
+*Since: nightly builds only*
+
+This method can be used to change the content that is displayed in the tab bar,
+to the right of the tabs and new tab button.  The content is displayed
+right-aligned and will be clipped from the left edge to fit in the available
+space.
+
+The parameter is a string that can contain escape sequences that change presentation.
+
+It is recommended that you use [wezterm.format](../wezterm/format.md) to compose
+the string.
+
+Here's a basic example that displays the time in the status area:
+
+<img width="100%" height="100%" src="../screenshots/wezterm-status-date.png"
+  alt="Demonstrating setting the right status area to the current date and time">
+
+```lua
+local wezterm = require 'wezterm';
+
+wezterm.on("update-right-status", function(window, pane)
+  local date = wezterm.strftime("%Y-%m-%d %H:%M:%S");
+
+  -- Make it italic and underlined
+  window:set_right_status(wezterm.format({
+    {Attribute={Underline="Single"}},
+    {Attribute={Italic=true}},
+    {Text="Hello "..date},
+  }));
+end);
+
+return {}
+```
+
+Here's a rather more elaborate example that employs the popular PowerLine glyphs
+to show a visually appealing status area.  It also extracts the current
+working directory and hostname from the current pane. That way
+it can potentially pick up the remote hostname if your remote shell session is using
+[OSC 7 shell integration](../../../shell-integration.html#osc-7-escape-sequence-to-set-the-working-directory).
+
+<img width="100%" height="100%" src="../screenshots/wezterm-status-powerline.png"
+  alt="Demonstrating setting the right status area with powerline styling">
+
+```lua
+wezterm.on("update-right-status", function(window, pane)
+  -- Each element holds the text for a cell in a "powerline" style << fade
+  local cells = {};
+
+  -- Figure out the cwd and host of the current pane.
+  -- This will pick up the hostname for the remote host if your
+  -- shell is using OSC 7 on the remote host.
+  local cwd_uri = pane:get_current_working_dir()
+  if cwd_uri then
+    cwd_uri = cwd_uri:sub(8);
+    local slash = cwd_uri:find("/")
+    local cwd = ""
+    local hostname = ""
+    if slash then
+      hostname = cwd_uri:sub(1, slash-1)
+      -- Remove the domain name portion of the hostname
+      local dot = hostname:find("[.]")
+      if dot then
+        hostname = hostname:sub(1, dot-1)
+      end
+      -- and extract the cwd from the uri
+      cwd = cwd_uri:sub(slash)
+
+      table.insert(cells, cwd);
+      table.insert(cells, hostname);
+    end
+  end
+
+  -- I like my date/time in this style: "Wed Mar 3 08:14"
+  local date = wezterm.strftime("%a %b %-d %H:%M");
+  table.insert(cells, date);
+
+  -- An entry for each battery (typically 0 or 1 battery)
+  for _, b in ipairs(wezterm.battery_info()) do
+    table.insert(cells, string.format("%.0f%%", b.state_of_charge * 100))
+  end
+
+  -- The powerline < symbol
+  local LEFT_ARROW = utf8.char(0xe0b3);
+  -- The filled in variant of the < symbol
+  local SOLID_LEFT_ARROW = utf8.char(0xe0b2)
+
+  -- Color palette for the backgrounds of each cell
+  local colors = {
+    "#3c1361",
+    "#52307c",
+    "#663a82",
+    "#7c5295",
+    "#b491c8",
+  };
+
+  -- Foreground color for the text across the fade
+  local text_fg = "#c0c0c0";
+
+  -- The elements to be formatted
+  local elements = {};
+  -- How many cells have been formatted
+  local num_cells = 0;
+
+  -- Translate a cell into elements
+  function push(text, is_last)
+    local cell_no = num_cells + 1
+    table.insert(elements, {Foreground={Color=text_fg}})
+    table.insert(elements, {Background={Color=colors[cell_no]}})
+    table.insert(elements, {Text=" "..text.." "})
+    if not is_last then
+      table.insert(elements, {Foreground={Color=colors[cell_no+1]}})
+      table.insert(elements, {Text=SOLID_LEFT_ARROW})
+    end
+    num_cells = num_cells + 1
+  end
+
+  while #cells > 0 do
+    local cell = table.remove(cells, 1)
+    push(cell, #cells == 0)
+  end
+
+  window:set_right_status(wezterm.format(elements));
+end);
+```