swmctl

swmctl.1

# swmctl

CTL_PKGS      = wayland-client

CTL_CPPFLAGS := `$(PKG_CONFIG) --cflags $(CTL_PKGS)`

CTL_LDLIBS   := `$(PKG_CONFIG) --libs $(CTL_PKGS)`

SRC   := swm.c util.c ext-workspace-v1-protocol.c swm-workspace-v1-protocol.c

	swm-workspace-v1-protocol.h \

all: man swm swmctl

man: swm.1 swmctl.1

swmctl.1: swmctl.1.adoc

	@echo "man  $< => $@"

	@asciidoctor -b manpage -o $@ $<

swmctl: swmctl.o swm-workspace-v1-protocol.o

	@echo "ld   $^ => $@"

	@$(CC) $(LDFLAGS) $^ $(CTL_LDLIBS) -o $@

	@echo "ok   $@"

swmctl.o: swmctl.c swm-workspace-v1-client-protocol.h Makefile config.mk

	@echo "cc   $< => $@"

	@$(CC) $(CTL_CPPFLAGS) $(CFLAGS) -c $< -o $@

swm-workspace-v1-protocol.h: protocols/swm-workspace-v1.xml

	@echo "hdr  $@"

	@$(WL_SCANNER) server-header $< $@

swm-workspace-v1-client-protocol.h: protocols/swm-workspace-v1.xml

	@echo "hdr  $@"

	@$(WL_SCANNER) client-header $< $@

swm-workspace-v1-protocol.c: protocols/swm-workspace-v1.xml

	@echo "src  $@"

	@$(WL_SCANNER) private-code $< $@

install: swm swmctl swm.1 swmctl.1

	install -Dm755 swmctl $(DESTDIR)$(PREFIX)/bin/swmctl

	install -Dm644 swmctl.1 $(DESTDIR)$(MANDIR)/man1/swmctl.1

	rm -f $(DESTDIR)$(PREFIX)/bin/swmctl

	rm -f $(DESTDIR)$(MANDIR)/man1/swmctl.1

	rm -f swm swmctl swm.1 swmctl.1 *.o *-protocol.h *-protocol.c

	swm.h util.c util.h $(PROTO) ext-workspace-v1-protocol.c swm-workspace-v1-protocol.c

		ext-workspace-v1-protocol.c swm-workspace-v1-protocol.c $(LDLIBS) -o $@

		ext-workspace-v1-protocol.c swm-workspace-v1-protocol.c $(LDLIBS) -o $@

$(TEST_BIN)/swmctl: swmctl.c swm-workspace-v1-client-protocol.h \

		swm-workspace-v1-protocol.c | $(TEST_BIN)

	@echo "cc   swmctl.c => $@"

	@$(CC) $(CTL_CPPFLAGS) $(TEST_CFLAGS) swmctl.c \

		swm-workspace-v1-protocol.c $(CTL_LDLIBS) -o $@

test-build: $(TEST_BIN)/unit $(TEST_BIN)/swm $(TEST_BIN)/swmctl

test-integration: $(TEST_BIN)/swm $(TEST_BIN)/swmctl

  cp "${startdir}"/{Makefile,config.mk,swm.c,swm.h,swmctl.c,util.c,util.h} \

  cp "${startdir}"/{config.def.h,swm.1.adoc,swmctl.1.adoc,swm.desktop} \

workspaces remain visible. See `swmctl(1)` for workspace metadata and Waybar

integration.

standard input. Workspace metadata uses `workspace N title VALUE` and

`workspace N color #RRGGBBAA` records; empty values mean unset. The active window

title is published atomically to

<?xml version="1.0" encoding="UTF-8"?>

<protocol name="swm_workspace_v1">

  <copyright>

    Copyright (C) 2026 swm contributors

    This program is free software: you can redistribute it and/or modify

    it under the terms of the GNU General Public License as published by

    the Free Software Foundation, either version 3 of the License, or

    (at your option) any later version.

  </copyright>

  <interface name="swm_workspace_manager_v1" version="1">

    <description summary="inspect and change swm workspace metadata">

      This interface exposes ephemeral titles and colors associated with

      swm's fixed workspaces. Metadata exists only for the lifetime of the

      compositor process.

      When a client binds, the compositor sends one metadata event for every

      workspace followed by done. Later changes are sent in the same way.

    </description>

    <enum name="error">

      <entry name="invalid_workspace" value="1" summary="workspace number is out of range"/>

      <entry name="title_too_long" value="2" summary="workspace title is too long"/>

    </enum>

    <enum name="metadata">

      <entry name="title" value="1" summary="the title is non-empty"/>

      <entry name="color" value="2" summary="the color is set"/>

      <entry name="selected" value="4" summary="the workspace is selected by swm"/>

    </enum>

    <event name="metadata">

      <description summary="workspace metadata">

        The workspace number starts at one. Color is encoded as 0xRRGGBBAA;

        zero means unset and omits the color bit from flags. An empty

        title means the additional label is unset. Selected identifies the

        workspace on swm's currently selected output.

      </description>

      <arg name="workspace" type="uint" summary="one-based workspace number"/>

      <arg name="flags" type="uint" enum="metadata"/>

      <arg name="title" type="string"/>

      <arg name="color" type="uint" summary="color encoded as 0xRRGGBBAA"/>

    </event>

    <event name="done">

      <description summary="metadata update is complete"/>

    </event>

    <request name="set_title">

      <description summary="set a workspace title">

        Set the title of a workspace. An empty title clears it.

      </description>

      <arg name="workspace" type="uint" summary="one-based workspace number"/>

      <arg name="title" type="string"/>

    </request>

    <request name="set_color">

      <description summary="set a workspace color">

        Set the color of a workspace. Zero clears it.

      </description>

      <arg name="workspace" type="uint" summary="one-based workspace number"/>

      <arg name="color" type="uint" summary="color encoded as 0xRRGGBBAA"/>

    </request>

    <request name="destroy" type="destructor">

      <description summary="release the manager object"/>

    </request>

  </interface>

</protocol>

*swmctl*(1) can associate additional ephemeral titles and colors with

workspaces. These do not replace the numbered ext-workspace names and are only

shown by explicitly configured consumers. All workspace metadata is discarded

when *swm* exits.

*foot*(1), *swmctl*(1), *wmenu*(1)

#include "swm-workspace-v1-protocol.h"

#define MAX_WORKSPACE_TITLE     256

    char            title[MAX_WORKSPACE_TITLE]; /* Ephemeral human-readable label. */

    uint32_t        color; /* Ephemeral color encoded as 0xRRGGBBAA; zero means unset. */

/* Bound client for swm's ephemeral workspace metadata protocol. */

typedef struct {

    struct wl_resource *resource;

    struct wl_list      link;

} metadata_manager_t;

static void         workspace_metadata_bind(

    struct wl_client *client, void *data, uint32_t version, uint32_t id

);

static void workspace_metadata_broadcast(void);

static void workspace_handle_create(workspace_manager_t *mgr, workspace_t *ws);

static void workspace_manager_bind(

static struct wl_list            ws_managers;       /* workspace_manager_t.link */

static struct wl_list            metadata_managers; /* metadata_manager_t.link */

static struct wl_list            pending_spawns;    /* pending_spawn_t.link */

static struct wl_list            window_states;     /* window_state_t.link */

static struct wl_list            input_popups;      /* input_popup_t.link */

static metadata_manager_t   metadata_manager_items[MAX_WS_MANAGERS];

static bool workspace_handle_used[MAX_WS_HANDLES], metadata_manager_used[MAX_WS_MANAGERS];

static pool_t metadata_manager_pool   = { metadata_manager_items,

                                          metadata_manager_used,

                                          LENGTH(metadata_manager_items),

                                          sizeof *metadata_manager_items,

                                          "metadata_manager" };

    int         i;

    for (i = 0; i < WSCOUNT; i++) {

        status_field(title, sizeof(title), workspaces[i].title);

        printf("workspace %d title %s\n", i + 1, title);

        if (workspaces[i].color)

            printf("workspace %d color #%08" PRIx32 "\n", i + 1, workspaces[i].color);

        else

            printf("workspace %d color \n", i + 1);

    }

/* Send one workspace's ephemeral metadata to a control client. */

static void workspace_metadata_send(struct wl_resource *resource, workspace_t *ws) {

    uint32_t flags = 0;

    if (ws->title[0])

        flags |= SWM_WORKSPACE_MANAGER_V1_METADATA_TITLE;

    if (ws->color)

        flags |= SWM_WORKSPACE_MANAGER_V1_METADATA_COLOR;

    if (selmon && selmon->ws == ws)

        flags |= SWM_WORKSPACE_MANAGER_V1_METADATA_SELECTED;

    swm_workspace_manager_v1_send_metadata(

        resource, (uint32_t)ws->idx + 1, flags, ws->title, ws->color

    );

}

/* Send a complete workspace metadata snapshot to one control client. */

static void workspace_metadata_snapshot(struct wl_resource *resource) {

    int i;

    for (i = 0; i < WSCOUNT; i++)

        workspace_metadata_send(resource, &workspaces[i]);

    swm_workspace_manager_v1_send_done(resource);

}

/* Publish all workspace metadata to every connected control client. */

static void workspace_metadata_broadcast(void) {

    metadata_manager_t *mgr;

    wl_list_for_each(mgr, &metadata_managers, link) workspace_metadata_snapshot(mgr->resource);

}

/* Return a requested workspace or report a protocol error. */

static workspace_t *workspace_metadata_get(struct wl_resource *resource, uint32_t number) {

    if (!number || number > WSCOUNT) {

        wl_resource_post_error(

            resource,

            SWM_WORKSPACE_MANAGER_V1_ERROR_INVALID_WORKSPACE,

            "workspace %" PRIu32 " is outside 1..%d",

            number,

            WSCOUNT

        );

        return nullptr;

    }

    return &workspaces[number - 1];

}

/* Change an ephemeral workspace title. */

static void workspace_metadata_set_title(

    struct wl_client *client, struct wl_resource *resource, uint32_t number, const char *title

) {

    workspace_t *ws = workspace_metadata_get(resource, number);

    if (!ws)

        return;

    if (strlen(title) >= sizeof(ws->title)) {

        wl_resource_post_error(

            resource,

            SWM_WORKSPACE_MANAGER_V1_ERROR_TITLE_TOO_LONG,

            "workspace title exceeds %zu bytes",

            sizeof(ws->title) - 1

        );

        return;

    }

    if (!strcmp(ws->title, title))

        return;

    strcpy(ws->title, title);

    print_status();

}

/* Change an ephemeral workspace color. */

static void workspace_metadata_set_color(

    struct wl_client *client, struct wl_resource *resource, uint32_t number, uint32_t color

) {

    workspace_t *ws = workspace_metadata_get(resource, number);

    if (!ws)

        return;

    if (ws->color == color)

        return;

    ws->color = color;

    print_status();

}

/* Release an ephemeral workspace metadata manager. */

static void workspace_metadata_destroy_request(

    struct wl_client *client, struct wl_resource *resource

) {

    wl_resource_destroy(resource);

}

static const struct swm_workspace_manager_v1_interface workspace_metadata_impl = {

    .set_title = workspace_metadata_set_title,

    .set_color = workspace_metadata_set_color,

    .destroy   = workspace_metadata_destroy_request,

};

/* Stop publishing workspace metadata after a client disconnects. */

static void workspace_metadata_destroy(struct wl_resource *resource) {

    metadata_manager_t *mgr = wl_resource_get_user_data(resource);

    if (!mgr)

        return;

    wl_list_remove(&mgr->link);

    pool_release(&metadata_manager_pool, mgr);

}

/* Publish all ephemeral workspace metadata to a newly connected client. */

static void workspace_metadata_bind(

    struct wl_client *client, void *data, uint32_t version, uint32_t id

) {

    metadata_manager_t *mgr = pool_take(&metadata_manager_pool);

    if (!mgr) {

        wl_client_post_no_memory(client);

        return;

    }

    mgr->resource =

        wl_resource_create(client, &swm_workspace_manager_v1_interface, (int)version, id);

    if (!mgr->resource) {

        pool_release(&metadata_manager_pool, mgr);

        wl_client_post_no_memory(client);

        return;

    }

    wl_resource_set_implementation(

        mgr->resource, &workspace_metadata_impl, mgr, workspace_metadata_destroy

    );

    wl_list_insert(&metadata_managers, &mgr->link);

    workspace_metadata_snapshot(mgr->resource);

}

    if (!wl_list_empty(&ws_managers)) {

        for (i = 0; i < WSCOUNT; i++) {

            state = workspace_state(&workspaces[i]);

            wl_list_for_each(h, &workspaces[i].handles, link)

                ext_workspace_handle_v1_send_state(h->resource, state);

        }

        wl_list_for_each(mgr, &ws_managers, link) ext_workspace_manager_v1_send_done(mgr->resource);

    workspace_metadata_broadcast();

    wl_list_init(&metadata_managers);

    wl_global_create(dpy, &swm_workspace_manager_v1_interface, 1, nullptr, workspace_metadata_bind);

= swmctl(1)

:doctype: manpage

:manmanual: SWM Manual

:mansource: swm 1.0.0

== NAME

swmctl - inspect and change swm workspace metadata

== SYNOPSIS

*swmctl workspace list*

*swmctl workspace get* _N_ (*title*|*color*|*selected*)

*swmctl workspace set* _N_ (*title* _TITLE_|*color* _#RRGGBB[AA]_)

*swmctl workspace clear* _N_ (*title*|*color*)

*swmctl workspace subscribe* [*--format=waybar*]

== DESCRIPTION

*swmctl* connects to the running *swm* Wayland compositor and reads or changes

the title and color associated with a workspace. This metadata is ephemeral: it

is stored only in compositor memory and is discarded when *swm* exits.

An empty title clears the additional label. It does not change the numeric

workspace name. A cleared color tells consumers to use their default color.

Colors use six-digit RGB or eight-digit RGBA notation. RGB implies full

opacity. `#00000000` means unset, while `#000000` represents opaque black.

*set* changes one named field. *clear* clears one named field.

*get* prints one field value. An unset title or color produces an empty line;

*selected* produces `true` or `false`.

*subscribe* writes a JSON array containing the current metadata, then writes a

new array after every change. Each array occupies one line, making the command

suitable for custom bars and other long-running consumers.

With *--format=waybar*, *subscribe* instead writes Waybar custom-module JSON

for the workspace on swm's selected output. Its additional title becomes the

module text and its color becomes the text foreground. An unset title produces

empty text. Configure the module with `return-type` set to `json` and `escape`

set to `false`.

== WAYBAR

The `ext/workspaces` module continues to display the numeric workspace names

`1` through `10`. A custom module can display the additional title and color

independently:

    "modules-center": ["custom/workspace-title"],

    "custom/workspace-title": {

        "exec": "swmctl workspace subscribe --format=waybar",

        "return-type": "json",

        "escape": false,

        "hide-empty-text": true

    }

The custom module follows the workspace on swm's selected output and uses its

color for the title text.

== EXAMPLES

Set both fields for workspace 3:

    swmctl workspace set 3 title "Prototyping new window manager"

    swmctl workspace set 3 color "#81a1c1"

Print its title:

    swmctl workspace get 3 title

Clear only its color:

    swmctl workspace clear 3 color

List every workspace number:

    swmctl workspace list

== SEE ALSO

*swm*(1), *waybar*(5)

/*

 * swmctl.c

 * Control and inspect swm's state.

 */

#include <errno.h>

#include <inttypes.h>

#include <stdbool.h>

#include <stdint.h>

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <wayland-client.h>

#include "swm-workspace-v1-client-protocol.h"

#define MAX_WORKSPACES      32

#define MAX_WORKSPACE_TITLE 256

typedef struct {

    bool     seen;

    uint32_t flags;

    char     title[MAX_WORKSPACE_TITLE];

    uint32_t color;

} workspace_t;

static struct wl_display               *display;

static struct swm_workspace_manager_v1 *manager;

static workspace_t                      workspaces[MAX_WORKSPACES];

static bool                             subscribing;

static bool                             waybar;

[[noreturn]] static void usage(void) {

    fprintf(

        stderr,

        "usage:\n"

        "  swmctl workspace list\n"

        "  swmctl workspace get N (title | color | selected)\n"

        "  swmctl workspace set N (title TITLE | color COLOR)\n"

        "  swmctl workspace clear N (title | color)\n"

        "  swmctl workspace subscribe [--format=waybar]\n"

    );

    exit(EXIT_FAILURE);

}

/* Print a color in its shortest lossless notation. */

static void print_color(uint32_t color) {

    if ((color & 0xff) == 0xff)

        printf("#%06" PRIx32, color >> 8);

    else

        printf("#%08" PRIx32, color);

}

/* Write a string with JSON quoting. */

static void json_string(const char *value) {

    const unsigned char *p;

    putchar('"');

    for (p = (const unsigned char *)value; *p; p++) {

        if (*p == '"' || *p == '\\')

            printf("\\%c", *p);

        else if (*p == '\n')

            fputs("\\n", stdout);

        else if (*p == '\r')

            fputs("\\r", stdout);

        else if (*p == '\t')

            fputs("\\t", stdout);

        else if (*p < 0x20)

            printf("\\u%04x", *p);

        else

            putchar(*p);

    }

    putchar('"');

}

/* Print one workspace as a JSON object. */

static void print_json_workspace(uint32_t number, workspace_t *ws) {

    printf("{\"workspace\":%" PRIu32 ",\"title\":", number);

    if (ws->flags & SWM_WORKSPACE_MANAGER_V1_METADATA_TITLE)

        json_string(ws->title);

    else

        fputs("null", stdout);

    fputs(",\"color\":", stdout);

    if (ws->flags & SWM_WORKSPACE_MANAGER_V1_METADATA_COLOR) {

        putchar('"');

        print_color(ws->color);

        putchar('"');

    } else {

        fputs("null", stdout);

    }

    printf(

        ",\"selected\":%s}",

        ws->flags & SWM_WORKSPACE_MANAGER_V1_METADATA_SELECTED ? "true" : "false"

    );

}

/* Write a JSON string safe for use as Pango markup in Waybar. */

static void json_markup_string(const char *value, bool has_color, uint32_t color) {

    const unsigned char *p;

    putchar('"');

    if (has_color) {

        printf("<span foreground=\\\"#%06" PRIx32 "\\\"", color >> 8);

        if ((color & 0xff) != 0xff)

            printf(" foreground_alpha=\\\"%" PRIu32 "\\\"", (color & 0xff) * 257);

        putchar('>');

    }

    for (p = (const unsigned char *)value; *p; p++) {

        if (*p == '&')

            fputs("&", stdout);

        else if (*p == '<')

            fputs("<", stdout);

        else if (*p == '>')

            fputs(">", stdout);

        else if (*p == '"')

            fputs(""", stdout);

        else if (*p == '\'')

            fputs("'", stdout);

        else if (*p == '\\')

            fputs("\\\\", stdout);

        else if (*p == '\n')

            fputs("\\n", stdout);

        else if (*p == '\r')

            fputs("\\r", stdout);

        else if (*p == '\t')

            fputs("\\t", stdout);

        else if (*p < 0x20)

            printf("\\u%04x", *p);

        else

            putchar(*p);

    }

    if (has_color)

        fputs("</span>", stdout);

    putchar('"');

}

/* Print the selected workspace label as a Waybar custom-module update. */

static void print_waybar(void) {

    workspace_t *selected = nullptr;

    uint32_t     number   = 0;

    bool         has_title;

    for (uint32_t i = 0; i < MAX_WORKSPACES; i++) {

        if (workspaces[i].seen &&

            workspaces[i].flags & SWM_WORKSPACE_MANAGER_V1_METADATA_SELECTED) {

            selected = &workspaces[i];

            number   = i + 1;

            break;

        }

    }

    has_title = selected && selected->flags & SWM_WORKSPACE_MANAGER_V1_METADATA_TITLE;

    fputs("{\"text\":", stdout);

    json_markup_string(

        has_title ? selected->title : "",

        has_title && selected->flags & SWM_WORKSPACE_MANAGER_V1_METADATA_COLOR,

        selected ? selected->color : 0

    );

    printf(",\"tooltip\":\"Workspace %" PRIu32 "\"}\n", number);

    fflush(stdout);

}

/* Print the complete cached workspace metadata as one JSON value. */

static void print_json_workspaces(void) {

    bool first = true;

    putchar('[');

    for (uint32_t i = 0; i < MAX_WORKSPACES; i++) {

        if (!workspaces[i].seen)

            continue;

        if (!first)

            putchar(',');

        print_json_workspace(i + 1, &workspaces[i]);

        first = false;

    }

    puts("]");

    fflush(stdout);

}

/* Cache one workspace metadata event. */

static void metadata(

    void                            *data,

    struct swm_workspace_manager_v1 *object,

    uint32_t                         number,

    uint32_t                         flags,

    const char                      *title,

    uint32_t                         color

) {

    workspace_t *ws;

    if (!number || number > MAX_WORKSPACES)

        return;

    ws        = &workspaces[number - 1];