Lua Reference

Appearance

Class pinnacle.tag ​

Tag management.

This module provides utilities for creating and manipulating tags.

A tag is a sort of marker for each of your windows. It allows you to present windows in ways that traditional workspaces cannot.

More specifically:

  • A window can have multiple tags.
    • This means that you can have one window show up across multiple "workspaces" if you come something like i3.
  • An output can display multiple tags at once.
    • This allows you to toggle a tag and have windows on both tags display at once. This is helpful if you, say, want to reference a browser window while coding; you toggle your browser's tag and temporarily reference it while you work without having to change screens.

If you need to get tags beyond the first with the same name, use the get method and find what you need.

Fields ​

handle ​

handle: pinnacle.tag.TagHandleModule

Functions ​

function get_all ​

function pinnacle.tag.get_all()
    -> pinnacle.tag.TagHandle[]

Gets all tags across all outputs.

Returns ​

  1. pinnacle.tag.TagHandle[]

function get ​

function pinnacle.tag.get(name: string, output?: pinnacle.output.OutputHandle)
    -> pinnacle.tag.TagHandle | nil

Gets the tag with the given name and output.

If output is not specified, this uses the focused output.

If an output has more than one tag with the same name, this returns the first.

Example ​

lua
 -- Get tags on the focused output
local tag = Tag.get("Tag")

 -- Get tags on a specific output
local tag_on_hdmi1 = Tag.get("Tag", Output.get_by_name("HDMI-1"))

Parameters ​

name: string - The name of the tag
output?: pinnacle.output.OutputHandle - The output to get the tag on, or nil for the focused output.

Returns ​

  1. pinnacle.tag.TagHandle | nil

function add ​

function pinnacle.tag.add(output: pinnacle.output.OutputHandle, ...: string)
    -> tags: pinnacle.tag.TagHandle[]

Adds tags with the given names to the specified output.

Returns handles to the created tags.

Example ​

lua
local tags = Tag.add(Output.get_by_name("HDMI-1"), "1", "2", "Buckle", "Shoe")

 -- With a table
local tag_names = { "1", "2", "Buckle", "Shoe" }
local tags = Tag.add(Output.get_by_name("HDMI-1"), tag_names)

Parameters ​

output: pinnacle.output.OutputHandle - The output to add tags to.
...: string - The names of the new tags.

Returns ​

  1. tags: pinnacle.tag.TagHandle[] - Handles to the created tags.

function remove ​

function pinnacle.tag.remove(tags: pinnacle.tag.TagHandle[])

Removes the given tags.

Example ​

lua
local tags = Tag.add(Output.get_by_name("HDMI-1"), "1", "2", "Buckle", "Shoe")

Tag.remove(tags) -- "HDMI-1" no longer has those tags

Parameters ​

tags: pinnacle.tag.TagHandle[] - The tags to remove.

function connect_signal ​

function pinnacle.tag.connect_signal(signals: pinnacle.tag.TagSignal)
    -> signal_handles: pinnacle.signal.SignalHandles

Connects to a tag signal.

signals is a table containing the signal(s) you want to connect to along with a corresponding callback that will be called when the signal is signalled.

This function returns a table of signal handles with each handle stored at the same key used to connect to the signal. See SignalHandles for more information.

Example ​

lua
Tag.connect_signal({
    active = function(tag, active)
        print("Activity for " .. tag:name() .. " was set to", active)
    end
})

Parameters ​

signals: pinnacle.tag.TagSignal - The signal you want to connect to

Returns ​

  1. signal_handles: pinnacle.signal.SignalHandles - Handles to every signal you connected to wrapped in a table, with keys being the same as the connected signal.

See also ​

Last updated: