chickadee » i3

i3

Extends the i3 window manager via its IPC interface.

i3

[module] i3

Note that there are more examples than what is documented here at http://code.stapelberg.de/git/i3-egg/tree/examples. That repository is also the canonical location for this egg’s source code.

connect

connectprocedure

Connects to i3 running on the display specified by the environment variable DISPLAY.

(define (connect)
  (let ((cmd-fd (socket af/unix sock/stream))
        (event-fd (socket af/unix sock/stream)))
    (socket-connect cmd-fd (unix-address (i3-socket-path)))
    (socket-connect event-fd (unix-address (i3-socket-path)))
    (let ((conn (make-i3-conn cmd-fd event-fd (make-mutex) #f '())))
      (i3-conn-event-thread-set!
        conn
        (thread-start! (lambda () (read-events conn))))
      conn)))

cmd

cmd conn msg #!optional (type 0)procedure

Sends the given MSG to i3, by default as command.

conn
A connection to i3, created with (connect).
msg
The payload of the message, e.g. a command when type is 0.
type
The numeric message type, “COMMAND” (0) by default. See also http://i3wm.org/docs/ipc.html#_sending_messages_to_i3 for message types.
(define (cmd conn msg #!optional (type 0))
  (let ((sock (i3-conn-cmd-fd conn)))
    (socket-send-all sock (i3-format-ipc-message msg type))
    (i3-read-one-message sock)))

Examples

Change focus to the window to the right:

(cmd (connect) "focus right")

subscribe

subscribe conn event thunkprocedure

Subscribes to the specified EVENT (e.g. "workspace") and calls THUNK when an event arrives.

(define (subscribe conn event thunk)
  (i3-conn-callbacks-set!
    conn
    (alist-update!
      (alist-ref event i3-event-name-to-type string=?)
      thunk
      (i3-conn-callbacks conn)))
  (let ((sock (i3-conn-event-fd conn)) (mutex (i3-conn-evmutex conn)))
    (mutex-lock! mutex)
    (socket-send-all
      sock
      (i3-format-ipc-message (json->string (vector event)) 2))
    (i3-read-one-message sock)
    (mutex-unlock! mutex)))

tree

tree connprocedure

Convenience function to get the layout tree from i3.

See http://i3wm.org/docs/ipc.html#_tree_reply for the reply format.

conn
A connection to i3, created with (connect).
(define (tree conn) (cmd conn "" 4))

Examples

Return a list of all Chrome windows:

(filter-containers
 (lambda (con) (string-suffix? " - Google Chrome" (alist-ref 'name con)))
 (tree (connect)))

workspaces

workspaces connprocedure

Convenience function to get the workspaces from i3.

See http://i3wm.org/docs/ipc.html#_workspaces_reply for the reply format.

conn
A connection to i3, created with (connect)
(define (workspaces conn) (cmd conn "" 1))

filter-containers

filter-containers predicate treeprocedure

Returns a list containing all containers for which the given predicate returns #t.

predicate
Predicate which is evaluated for each i3 container. Only containers for which the predicate returns #t are included in the return list
tree
(Part of) a list of containers as returned by (tree).
(define (filter-containers predicate tree)
  (if (null? tree)
    '()
    (append
      (if (predicate tree) (list tree) (list))
      (apply append
             (filter-map
               (lambda (node) (filter-containers predicate node))
               (cdr (assoc 'nodes tree)))))))

Examples

Return a list of all Chrome windows:

(filter-containers
 (lambda (con) (string-suffix? " - Google Chrome" (alist-ref 'name con)))
 (tree (connect)))

descend-focused

descend-focused stop-predicate treeprocedure

Descends the focused containers of the given TREE, stopping at the first container which satisfies STOP-PREDICATE.

stop-predicate
Processing stops when this predicate first returns true. The return value is the container with which this predicate was evaluated.
tree
(Part of) a list of containers as returned by (tree).
(define (descend-focused stop-predicate tree)
  (if (stop-predicate tree)
    tree
    (if (null? (alist-ref 'focus tree))
      tree
      (descend-focused
        stop-predicate
        (let ((focused-id (first (alist-ref 'focus tree))))
          (find (lambda (con) (= (alist-ref 'id con) focused-id))
                (append
                  (alist-ref 'nodes tree)
                  (alist-ref 'floating_nodes tree))))))))

focused-con

focused-con treeprocedure

Returns the currently focused container.

tree
(Part of) a list of containers as returned by (tree).
(define (focused-con tree)
  (descend-focused (lambda (con) (null? (alist-ref 'nodes con))) tree))

Examples

Print the name of the currently focused window:

(format #t "~A~N" (alist-ref 'name (focused-con (tree (connect)))))

Print the name of the focused window of workspace 1:

(let ((ws-1
       (first
        (filter-containers
         (lambda (con)
           (and (= (alist-ref 'type con) 4)
                (string= (alist-ref 'name con) "1")))
         (tree (connect))))))
  (format #t "~A~N" (focused-con ws-1)))

About this egg

Author

Michael Stapelberg

Colophon

Documented by cock.

Contents »