pip-frame/README.org

4.8 KiB
Raw Permalink Blame History

pip-frame.el

pip-frame.el allows displaying a floating Emacs frame with Emacs buffers in EXWM (and possibly other) environments.

Why?

EXWM, an Emacs window manager, supports floating windows, placed above the tiled windows. But this doesnt apply to Emacs buffers, there is no way known to me to display an Emacs buffer in a floating window.

Having floating Emacs buffers looking like Picture-In-Picture is still useful. Imagine you start a long compilation and do other work in the meantime. You must poll the compilation status regularly. Maybe the compilation fails early and you dont notice it until the next polling interval. Or you run an upgrade and forget about it, only to discover a couple of hours later that the upgrade has hung on an interactive question. With a PIP frame displaying the compilation and upgrade buffers, you always know whats happening.

People often use secondary monitors for such overviews. But this is often overkill. Its often hard to use all the space on contemporary wide or even very wide monitors. I typically run Emacs with two windows side by side, focusing mostly on the left one. The area close to the right bottom screen corner is the least one used and its a good place to place a PIP frame there. And its often better than connecting a secondary monitor.

In theory, its possible to create such a window in a standard Emacs frame. But having a corner window is impractical, considering applications changing window layouts (e.g. Gnus). And if workspaces are used, e.g. Emacs tabs, the window is still hidden when working in a different workspace. Similar problems are experienced when using tiling window managers other than EXWM.

Screenshot

This is an example of an Emacs buffer displayed in a PIP frame using this utility:

An Emacs frame with a PIP frame

How?

Installation

You can install pip-frame.el from MELPA. If you use straight.el and prefer using source repos directly, you can install pip-frame.el as follows:

(straight-use-package
'(pip-frame :type git
          :repo "https://git.zamazal.org/pdm/pip-frame"
          :local-repo "pip-frame"))

For manual installation, simply put pip-frame.el file to your site-lisp directory and add the following to your Emacs configuration:

(require pip-frame)

Commands

The PIP frame is created using M-x pip-frame-add-buffer command. You can use the command repeatedly to add more buffers to the PIP frame.

A buffer can be removed from the PIP frame using M-x pip-frame-remove-buffer command. If the last buffer is removed from the PIP frame, the frame is deleted. The frame can also be deleted any time using M-x pip-frame-delete-frame.

If the frame obscures anything important, you can move it elsewhere with M-x pip-frame-move.

There are no key bindings. Feel free to add them to your configuration if needed. But these commands are not very frequent and tools such as Icomplete mode or smex are likely to serve better than tons of key shortcuts.

Customization

Use M-x customize-group RET pip-frame RET to customize pip-frame.el.

Some customization examples:

  • To place the PIP frame to right top rather than to right bottom:

      (setq pip-frame-parameters '((left . 0.9) (top . 0.1)))
  • To better distinguish the PIP frame from the rest of the screen (the frame is intentionally kept out of EXWM hands and no window manager borders are displayed), you can show it in inverse colors:

      (setq pip-frame-face-attributes '((:inverse-video . t)))

    Or with a different background:

      (setq pip-frame-face-attributes '((:background . "light gray")))
  • To add internal borders to the PIP frame and make it resizable with a mouse:

      (setq pip-frame-parameters (append pip-frame-parameters
                                         '((drag-internal-border . t)
                                           (internal-border-width . 20))))

Contact

pip-frame.el is available at git.zamazal.org. You can file issues there.

If you dont want to discuss things publicly or to bother registering at yet another web site, you can reach me at pdm@zamazal.org.