# Getting a consistent set of keybindings between i3 and Emacs
Freedom is a state of mind
Author: SqrtMinusOne

## Intro

One advantage of EXWM for an Emacs user is that EXWM gives one set of keybindings to manage both Emacs windows and X windows. In every other WM, like my preferred i3wm, two orthogonal keymaps seem to be necessary. But, as both programs are quite customizable, I want to see whether I can replicate at least some part of the EXWM goodness in i3.

But why not just use EXWM? One key reason is that to my taste (and perhaps on my hardware) EXWM didn’t feel snappy enough. Also, I really like i3’s tree-based layout structure; I feel like it fits my workflow much better than anything else I tried, including the master/stack paradigm of XMonad​, for instance.

One common point of criticism of i3 is that it is not extensible enough, especially compared to WMs that are configured in an actual programing language, like the mentioned XMonad, Qtile, Awesome, etc. But I think i3’s extensibility is underappreciated, although the contents of this article may lie closer to the limits of how far one can go there.

Here is a small demo of how it currently works:

## Emacs integration

What I’m trying to do is actually quite simple, so I’m somewhat surprised I didn’t find anything similar on the Internet. But I didn’t look too hard.

The basic idea is to launch a normal i3 command with `i3-msg` in case the current window is not Emacs, otherwise pass that command to Emacs with `emacsclient`. In Emacs, execute the command if possible, otherwise pass the command back to i3.

This may seem like a lot of overhead, but I didn’t feel it even in the worst case (i3 -> Emacs -> i3), so at least in that regard, the interaction feels seamless. The only concern is that this command flow is vulnerable to Emacs getting stuck, but it is still much less of a problem than with EXWM.

One interesting observation here is that Emacs windows and X windows are sort of one-level entities, so I can talk just about “windows”.

At any rate, we need a script to do the i3 -> Emacs part:

    if [[ $(xdotool getactivewindow getwindowname) =~ ^emacs(:.*)?@.* ]]; then
        command="(my/emacs-i3-integration \"$@\")"
        emacsclient -e "$command"
    else
        i3-msg $@
    fi

My Emacs frame title is set to `emacs[:<projectile-project-name>]@<hostname>`, hence the regex. The script is saved to an executable called `emacs-i3-integration`.

For this to work, we need to make sure that Emacs starts a server, so here is an expression to do just that:

    (add-hook 'after-init-hook #'server-start)

The function `my/emacs-i3-integration`, which is an entrypoint for the i3 integration, will be defined a bit later.

And here is a simple macro to do the Emacs -> i3 part:

    (defmacro i3-msg (&rest args)
      `(start-process "emacs-i3-windmove" nil "i3-msg" ,@args))

## Handling i3 commands

Now we have to handle the required set of i3 commands. It is worth noting here that I’m not trying to implement a general mechanism to apply i3 commands to Emacs, rather I’m implementing a small subset that I use in my i3 configuration and that maps reasonably to the Emacs concepts.

Also, I use evil-mode and generally configure the software to have vim-style bindings where possible. So if you don’t use evil-mode you’d have to detangle the given functions from evil, but then, I guess, you do not use super+hjkl to manage windows either.

### `focus`

First, for the `focus` command I want to move to an Emacs window in the given direction if there is one, otherwise move to an X window in the same direction. Fortunately, i3 and `windmove` have the same names for directions, so the function is rather straightforward.

One caveat here is that the minibuffer is always the bottom-most Emacs window, so it is necessary to check for that as well.

    (defun my/emacs-i3-windmove (dir)
      (let ((other-window (windmove-find-other-window dir)))
        (if (or (null other-window) (window-minibuffer-p other-window))
            (i3-msg "focus" (symbol-name dir))
          (windmove-do-window-select dir))))

The relevant section of the i3 config looks like this:

    bindsym $mod+h exec emacs-i3-integration focus left
    bindsym $mod+j exec emacs-i3-integration focus down
    bindsym $mod+k exec emacs-i3-integration focus up
    bindsym $mod+l exec emacs-i3-integration focus right

    bindsym $mod+Left exec emacs-i3-integration focus left
    bindsym $mod+Down exec emacs-i3-integration focus down
    bindsym $mod+Up exec emacs-i3-integration focus up
    bindsym $mod+Right exec emacs-i3-integration focus right

The Emacs function has to be called like that:

    (my/emacs-i3-windmove 'right)

### `move`

For the `move` command I want the following behavior:

- if there is space in the required direction, move the Emacs window there;
- if there is no space in the required direction, but space in the orthogonal directions, move the Emacs window so that there is no more space in the orthogonal directions;
- otherwise, move an X window (which has to be an Emacs frame).

For the first part, `window-swap-states` with `windmove-find-other-window` do well enough.

`evil-move-window` works well for the second part. By itself it doesn’t behave quite like i3, for instance, `(evil-move-window 'right)` in a three-column split would move the window from the far left side to the far right side (bypassing center). Hence the combination as described here.

So here is a simple predicate which checks whether there is space in the given direction.

    (defun my/emacs-i3-direction-exists-p (dir)
      (some (lambda (dir)
              (let ((win (windmove-find-other-window dir)))
                (and win (not (window-minibuffer-p win)))))
            (pcase dir
              ('width '(left right))
              ('height '(up down)))))

And the implementation of the move command.

    (defun my/emacs-i3-move-window (dir)
      (let ((other-window (windmove-find-other-window dir))
            (other-direction (my/emacs-i3-direction-exists-p
                              (pcase dir
                                ('up 'width)
                                ('down 'width)
                                ('left 'height)
                                ('right 'height)))))
        (cond
         ((and other-window (not (window-minibuffer-p other-window)))
          (window-swap-states (selected-window) other-window))
         (other-direction
          (evil-move-window dir))
         (t (i3-msg "move" (symbol-name dir))))))

The relevant section of the i3 config:

    bindsym $mod+Shift+h exec emacs-i3-integration move left
    bindsym $mod+Shift+j exec emacs-i3-integration move down
    bindsym $mod+Shift+k exec emacs-i3-integration move up
    bindsym $mod+Shift+l exec emacs-i3-integration move right

    bindsym $mod+Shift+Left exec emacs-i3-integration move left
    bindsym $mod+Shift+Down exec emacs-i3-integration move down
    bindsym $mod+Shift+Up exec emacs-i3-integration move up
    bindsym $mod+Shift+Right exec emacs-i3-integration move right

### `resize` and balance windows

Next on the line are `resize grow` and `resize shrink`. `evil-window-` functions do nicely for this task.

This function also checks whether there is space to resize in the given direction with the help of the predicate defined above. The command is forwarded back to i3 if there is not.

    (defun my/emacs-i3-resize-window (dir kind value)
      (if (or (one-window-p)
              (not (my/emacs-i3-direction-exists-p dir)))
          (i3-msg "resize" (symbol-name kind) (symbol-name dir)
                  (format "%s px or %s ppt" value value))
        (setq value (/ value 2))
        (pcase kind
          ('shrink
           (pcase dir
             ('width
              (evil-window-decrease-width value))
             ('height
              (evil-window-decrease-height value))))
          ('grow
           (pcase dir
             ('width
              (evil-window-increase-width value))
             ('height
              (evil-window-increase-height value)))))))

Here I’m following the default configuration of i3, which creates a “submode” to resize windows.

    mode "resize" {

        bindsym h exec emacs-i3-integration resize shrink width 10 px or 10 ppt
        bindsym j exec emacs-i3-integration resize grow height 10 px or 10 ppt
        bindsym k exec emacs-i3-integration resize shrink height 10 px or 10 ppt
        bindsym l exec emacs-i3-integration resize grow width 10 px or 10 ppt

        bindsym Shift+h exec emacs-i3-integration resize shrink width 100 px or 100 ppt
        bindsym Shift+j exec emacs-i3-integration resize grow height 100 px or 100 ppt
        bindsym Shift+k exec emacs-i3-integration resize shrink height 100 px or 100 ppt
        bindsym Shift+l exec emacs-i3-integration resize grow width 100 px or 100 ppt

        # same bindings, but for the arrow keys
        bindsym Left  exec emacs-i3-integration resize shrink width 10 px or 10 ppt
        bindsym Down  exec emacs-i3-integration resize grow height 10 px or 10 ppt
        bindsym Up    exec emacs-i3-integration resize shrink height 10 px or 10 ppt
        bindsym Right exec emacs-i3-integration resize grow width 10 px or 10 ppt

        bindsym Shift+Left  exec emacs-i3-integration resize shrink width 100 px or 100 ppt
        bindsym Shift+Down  exec emacs-i3-integration resize grow height 100 px or 100 ppt
        bindsym Shift+Up    exec emacs-i3-integration resize shrink height 100 px or 100 ppt
        bindsym Shift+Right exec emacs-i3-integration resize grow width 100 px or 100 ppt

        bindsym equal exec i3-emacs-balance-windows

        # back to normal: Enter or Escape
        bindsym Return mode "default"
        bindsym Escape mode "default"
    }

Next, Emacs has a built-in function called `balance-windows`, but i3 doesn’t. Fortunately, there is a Python package called i3-balance-workspace, which performs a similar operation with i3’s IPC. If you use Guix as I do, I’ve written a package definition.

So here is a small wrapper which calls `i3_balance_workspace` and `M-x balance-windows` if the current window is Emacs.

    if [[ $(xdotool getactivewindow getwindowname) =~ ^emacs(:.*)?@.* ]]; then
        emacsclient -e "(balance-windows)" &
    fi
    i3_balance_workspace

### `layout toggle split`

transpose-frame is a package to “transpose” the current Emacs windows layout, which behaves somewhat similar to the `layout toggle split` command in i3, so I’ll use it as well.

    (use-package transpose-frame
      :straight t
      :commands (transpose-frame))

The i3 config for this command:

    bindsym $mod+e exec emacs-i3-integration layout toggle split

### The entrypoint

Finally, the entrypoint for the Emacs integration. In addition to the commands defined above, it processes `split` and `kill` commands and passes every other command back to i3.

    (defun my/emacs-i3-integration (command)
      (pcase command
        ((rx bos "focus")
         (my/emacs-i3-windmove
          (intern (elt (split-string command) 1))))
        ((rx bos "move")
         (my/emacs-i3-move-window
          (intern (elt (split-string command) 1))))
        ((rx bos "resize")
         (my/emacs-i3-resize-window
           (intern (elt (split-string command) 2))
           (intern (elt (split-string command) 1))
           (string-to-number (elt (split-string command) 3))))
        ("layout toggle split" (transpose-frame))
        ("split h" (evil-window-split))
        ("split v" (evil-window-vsplit))
        ("kill" (evil-quit))
        (- (i3-msg command))))

The rest of the relevant i3 config to do the splits:

    bindsym $mod+s exec emacs-i3-integration split h
    bindsym $mod+v exec emacs-i3-integration split v

And to kill the window:

    bindsym $mod+Shift+q exec emacs-i3-integration kill

### Switching i3 tabs

As I use i3’s tabbed layout quite extensively, occasionally I want to switch out of the Emacs tab with one button, and that’s where my integration may interfere.

As a workaround, I found a small Rust program called i3-switch-tabs, which also communicates with i3 via its IPC to switch the top-level tab. I’ve written a Guix package definition for that as well.

    bindsym $mod+period exec i3-switch-tabs right
    bindsym $mod+comma exec i3-switch-tabs left

## Conclusion

So, how does all of that feel? Actually, I got used to that setup pretty quickly. Using `<s-Q>` to quit windows and the `<s-r>` submode to resize them is particularly nice. I’ve seen people making hydras in Emacs to do the latter.

All of that would probably be easier to do in a WM which is configured in a programming language rather than in a self-cooked DSL, so I may try to replicate that somewhere else in an unknown time in the future. Meanwhile, it’s pretty good.

Table of Contents
<Expand> <Collapse>