pane:get_progress()

Since: Nightly Builds Only

The functionality described in this section requires a nightly build of wakterm. You can obtain a nightly build by following the instructions from the Download section.

Returns the progress state associated with the pane.

By default, when the terminal is reset, the progress state will be "None" to indicate that no progress has been reported.

An application can use the ConEmu style progress report OSC sequence to alter the progress state, which has the following form:

ESC ] 9 ; 4 ; st ; pr ST

When st is:

• 0: set progress to "None"
• 1: set progress value to pr (number, 0-100). Reported as {Percentage = pr}
• 2: set error state in progress, pr is optional and will be assumed 0 if omitted. Reported as {Error = pr}
• 3: set indeterminate state. Reported as "Indeterminate"
• 4: set paused state, pr is optional. Not supported by wakterm

When the progress OSC is processed, the state is captured, and if it has changed, wakterm will trigger an update of the tab bar, which will in turn cause events such as format-tab-title to trigger.

The progress information is not directly used by wakterm, but you can access it from lua to style tabs differently according to progress. For example, the following will prefix the tab with the progress percentage expressed using Nerd Fonts circle symbols and adjust its color based on whether it is success or error progress:

local wakterm = require 'wakterm'

local function tab_title(tab_info)
  return tab_info.effective_title
end

local PCT_GLYPHS = {
  wakterm.nerdfonts.md_circle_slice_1,
  wakterm.nerdfonts.md_circle_slice_2,
  wakterm.nerdfonts.md_circle_slice_3,
  wakterm.nerdfonts.md_circle_slice_4,
  wakterm.nerdfonts.md_circle_slice_5,
  wakterm.nerdfonts.md_circle_slice_6,
  wakterm.nerdfonts.md_circle_slice_7,
  wakterm.nerdfonts.md_circle_slice_8,
}
local function pct_glyph(pct)
  local slot = math.floor(pct / 12)
  return PCT_GLYPHS[slot + 1]
end

wakterm.on(
  'format-tab-title',
  function(tab, tabs, panes, config, hover, max_width)
    local pane = tab.active_pane
    local progress = pane and pane.progress or 'None'
    local title = tab_title(tab)
    local elements = {
      { Text = string.format('%d: ', tab.tab_index + 1) },
    }

    if progress ~= 'None' then
      local color = 'green'
      local status
      if progress.Percentage ~= nil then
        -- status = string.format("%d%%", progress.Percentage)
        status = pct_glyph(progress.Percentage)
      elseif progress.Error ~= nil then
        -- status = string.format("%d%%", progress.Error)
        status = pct_glyph(progress.Error)
        color = 'red'
      elseif progress == 'Indeterminate' then
        status = '~'
      else
        status = wakterm.serde.json_encode(progress)
      end

      table.insert(elements, { Foreground = { Color = color } })
      table.insert(elements, { Text = status })
      table.insert(elements, { Foreground = 'Default' })
    end

    table.insert(elements, { Text = ' ' .. title .. ' ' })

    return elements
  end
)

return wakterm.config_builder()