Configuring stackline

The stackline config file is a plain lua file. The default configuration is loaded from stackline/conf.lua.

conf.lua has 3 sections:

Paths

Specify paths to binaries & scripts without mucking around in the stackline source.

Appearance

Customize indicator sizing, coloring, positioning, roundness, animation durations, form factor, etc

Features

Enable/disable fuzzy frame detection, click-to-focus, or the hacky workaround for a troublesome Hammerspoon bug. The ability to enable/disable features will be especially useful for upcoming features such as displaying window titles during switching.

The main benefit is that you won't have to put up with bugs in a feature that you don't even use (see #41).

---

Initialize Stackline with custom config

Let's assume that you think the icon indicators use up too much valuable screen real estate. This is an easy issue to fix!

Create a local variable in your init.lua to hold your customizations. I'll call mine myStackline, but you may name yours whatever you wish.

stackline = require "stackline.stackline.stackline"

local myStackline = {
    appearance = { 
      showIcons = false,       -- default is true
    },
    features = {
        clickToFocus = false,  -- default is true
        fzyFrameDetect = {
            fuzzFactor = 25    -- default is 30
        },
    },
}

stackline:init(myStackline)

Values that you set in this table will override Stackline's default config. Note that this table must adhere to the config schema (which can be found in stackline/configmanager.lua). If invalid config options are passed, Stackline a macOS notification will let you know, and the details will be printed to the Hammerspoon console:

2020-10-10 12:19:14: 12:19:14 ERROR:sline.conf: Invalid stackline config:
 {
  appearance = {
    myCoolSetting = "is not allowed."
  }
}

---

Config validation & live-tweaking

All config values can be edited while stackline is running (similarly to yabai).

Values can be set using the hs cli tool:

hs -c "stackline.config:set('appearance.radius', 3)"

All config fields support get(key), set(key, val), and getOrSet(key, [val]).

In addition, boolean fields support toggle()

# Toggle boolean values with the hs cli
hs -c "stackline.config:toggle('appearance.showIcons')"

You can get and set nested config fields by passing a dot-separated string path, like this: features.fzyFrameDetection.enabled

Config fields validated when stackline initializes and when config values are set live.

If a provided settings path does not exist, stackline will find the most similar setting that does exist and notify you:

---

The default config

c = {}
c.paths = {}
c.appearance = {}
c.features = {}
c.advanced = {}

-- Paths
c.paths.getStackIdxs                  = hs.configdir .. '/stackline/bin/yabai-get-stack-idx'
c.paths.jq                            = '/usr/local/bin/jq'
c.paths.yabai                         = '/usr/local/bin/yabai'

-- Appearance
c.appearance.color                    = { white = 0.90 }    -- Indicator background color, e.g., {red = 0.5, blue = 0 }
c.appearance.alpha                    = 1                   -- Opacity of active indicators
c.appearance.dimmer                   = 2.5                 -- Higher numbers increase contrast b/n focused & unfocused state
c.appearance.iconDimmer               = 1.1                 -- Higher numbers dim inactive icons *less* than the non-icon indicators
c.appearance.showIcons                = true                -- Window indicator style ('lozenge'-shaped when false)
c.appearance.size                     = 32                  -- Size of window indicators (height when icons off)
c.appearance.radius                   = 3                   -- Indicator roundness. Higher numbers → *less* roundness… I'm sorry
c.appearance.iconPadding              = 4                   -- Space between icon & indicator edge. Higher numbers → smaller, more inset icons
c.appearance.pillThinness             = 6                   -- Aspect ratio of pill-style icons (width = size / pillThinness)

c.appearance.vertSpacing              = 1.2                 -- Amount of vertical space between indicators

c.appearance.offset                   = {}                  -- Offset controls position of stack indicators relative to the window
c.appearance.offset.y                 = 2                   -- Distance from top of the window to render indicators
c.appearance.offset.x                 = 4                   -- Distance away from the edge of the window to render indicators

c.appearance.shouldFade               = true                -- Enable/disable fade animations
c.appearance.fadeDuration             = 0.2                 -- Duration of fade animations (seconds) 

-- Features
c.features.clickToFocus               = true                -- Click indicator to focus window. Mouse clicks are tracked when enabled
c.features.hsBugWorkaround            = true                -- Workaround for https://github.com/Hammerspoon/hammerspoon/issues/2400

c.features.fzyFrameDetect             = {}                  -- Round window frame dimensions by fuzzFactor before identifying stacked windows
c.features.fzyFrameDetect.enabled     = true                -- Enable/disable fuzzy frame detection
c.features.fzyFrameDetect.fuzzFactor  = 30                  -- Window frame dimensions will be rounded to nearest fuzzFactor

c.features.winTitles                 = 'not_implemented'    -- Valid options: false, true, 'when_switching', 'not_implemented'
c.features.dynamicLuminosity         = 'not_implemented'    -- Valid options: false, true, 'not_implemented'

c.advanced.maxRefreshRate             = 0.3                 -- How aggressively to refresh Stackline. Higher = slower response time + less battery drain

return c

Next: Keybindings →