Protocol Verbs

Workspaces and layout

Workspaces and layout: part of the Protocol Verbs of TUIOS.

This page is one part of docs/protocol-verbs.md of the tuios repository. The Protocol Verbs page lists every part.

layout-template Added in v0.13.1

Save the workspace a session shows as a layout template, load one back, list them, or delete one. Templates are files of this machine (~/.config/tuios/layouts), so every client reads one list. A load reuses the workspace's panes in order, opens the ones it lacks with their folder and name and types their command, minimizes the ones it does not name, and gives a bsp layout its split tree back. Works with no client attached.

ParamTypeRequiredDefaultDescription
actionstringyesWhat to do. One of list, save, load or delete.
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
namestringThe layout. Needed to save, load and delete.
Result fieldTypeDescription
layouts[]objectlist: each layout's name, panes, mode, tiling, created_at and version.
dirstringlist: the folder the layouts are kept in.
namestringThe layout saved, loaded or deleted.
panesintsave and load: how many panes the layout holds, or shows.
modestringsave and load: the layout mode, bsp, master-stack, scrolling or floating.
workspaceintsave and load: the workspace.
pathstringsave: the file written.
focusstringload: the pane that has the focus after the load, a pane of the layout.
openedintload: panes opened for the layout.
reusedintload: panes of the workspace that took a place.
minimizedintload: panes of the workspace the layout does not name, minimized.
deletedbooldelete: the layout was removed.
{"id":1,"verb":"layout-template","params":{"action":"save","session":"work","name":"three-up"}}
{"id":2,"verb":"layout-template","params":{"action":"load","session":"work","name":"three-up"}}
{"id":3,"verb":"layout-template","params":{"action":"list"}}

list-workspaces Added in v0.8.0

List every workspace with its name, how many windows it holds, and which one is showing.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
Result fieldTypeDescription
workspaces[]objectOne row per workspace: workspace, name, window_count, focused_window_id, current, and focus_history, the windows focused there, newest first.
current_workspaceintWorkspace showing.
order[]intDisplay order, empty when the workspaces are in their plain ascending order.
{"id":1,"verb":"list-workspaces","params":{"session":"work"}}

run-command Added in v0.8.0

Run one tape command, or any keybinding action by the name config.toml binds it to. Prefer a verb where one exists: a verb reports what changed, this reports only that the command ran.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
commandstringTape command name, e.g. "ToggleZoom" or "SnapLeft", or a keybinding action name, e.g. "toggle_spotlight" (tuios keybinds list prints them). An action runs on an attached client and takes no args.
args[]stringArguments for the command.
Result fieldTypeDescription
commandstringThe command that ran.
routedboolTrue when an attached client ran it, false when the daemon did.
{"id":1,"verb":"run-command","params":{"session":"work","command":"ToggleZoom"}}

select-workspace Added in v0.8.0

Show a workspace. To rename or reorder workspaces, use set-workspace-name and set-workspace-order.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
workspaceintyesWorkspace number to show.
return_toint0Workspace to show when this workspace loses its last pane, before any other. tuios xpanes sets it to the workspace that ran it.
Result fieldTypeDescription
current_workspaceintWorkspace now showing.
focused_window_idstringWindow focused on it, empty when it holds none.
window_countintHow many windows it holds.
{"id":1,"verb":"select-workspace","params":{"session":"work","workspace":2}}

set-layout Added in v0.8.0

Turn tiling on or off, tidy the splits, and shape the master-stack layout. Needs an attached client.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
tilingboolTile the panes automatically, or let them float.
equalizeboolfalseReset every split ratio so the panes share the space evenly.
rotateboolfalseFlip the axis of the split holding the focused pane.
master_positionstringSide the master panes take on the current workspace: left, right, top, bottom or center.
master_countintHow many panes are master panes on the current workspace, 1 to 9.
Result fieldTypeDescription
tiling_modestring"tiling" or "floating".
layout_modestringWhich tiling layout is in effect: bsp, master-stack, scrolling, or "unknown" on a session no client has reported one for.
master_ratiofloatFraction of the screen the master pane takes.
master_positionstringSide the master panes take on the current workspace, or "default" when the workspace uses the client's configured side.
master_countintHow many panes are master panes on the current workspace, or 0 when the workspace uses the client's configured count.
{"id":1,"verb":"set-layout","params":{"session":"work","tiling":true,"equalize":true}}
{"id":2,"verb":"set-layout","params":{"session":"work","master_position":"center","master_count":1}}

set-workspace-name Added in v0.8.0

Name a workspace. The workspace keeps its number for addressing. An unnamed workspace shows the name its active pane gave with OSC 1, else its number.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
workspaceintyesWorkspace number to name.
namestringLabel for the workspace. Omit or pass an empty string to clear it and fall back to the number.
{"id":1,"verb":"set-workspace-name","params":{"session":"work","workspace":2,"name":"review"}}

set-workspace-order Added in v0.8.0

Put the workspaces in an order, renumbering them: a workspace's number is its position. Each workspace takes its panes, name, focus and layout to its new number.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
order[]intyesWorkspace numbers in their new order. The workspaces named take the numbers they hold between them, smallest first, in this order: [3,1,2] makes 3 workspace 1, 1 workspace 2 and 2 workspace 3. A workspace the list omits keeps its number. Numbers outside the session's range and repeats are dropped.
{"id":1,"verb":"set-workspace-order","params":{"session":"work","order":[3,1,2]}}

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page