HyControl

Hyperbole includes the fastest, easiest-to-use Emacs window and frame management system available, HyControl, found under the Hyperbole Screen menu. If you use a lot of Emacs windows or frames (typically, window system windows) then this chapter is for you.

HyControl interactively adjusts the layout of your windows and frames down to the pixel-level if desired. You adjust the location, size and display elements of your windows and frames until they look as you like and then simply quit HyControl and go back to work.

Hyperbole binds the key {C-c \} for quick access to HyControl’s window control menu, if it was not already bound prior to Hyperbole’s initialization; otherwise, the Screen/WindowsControl minibuffer menu item, {C-h h s w}, will do the same thing. To start HyControl with the frames menu instead, use Screen/FramesControl, {C-h h s f}.

Once in HyControl, your minibuffer window at the bottom of the selected frame will display a summary of keys you may use to adjust your windows until you press {q} or {Q} to quit from HyControl. The key, {t}, will always toggle between controlling frames and windows, the submodes of HyControl, with the upper left of the minibuffer prompt showing which type of control is active.

A number of commands take a single numeric argument, e.g. movement and sizing, which you can enter by typing a period to clear the argument, followed by any positive number up to 1000. You may also use the {C-u} universal argument key to apply a multiplier of 4 to the argument, any number of times. Any entry that pushes the argument over 1000, restarts it, so 10005 would produce an argument of 5.

The table below explains what each key does in HyControl mode. If the explanation does not say otherwise, then the key applies in both window and frame submodes.

{?}

Toggle whether HyControl displays key binding help in the minibuffer.

{.}

Clear the prefix argument to a value of 0.

{0-9}

Multiply the prefix argument by 10 and add the digit pressed (or subtract it if prefix argument is negative).

{-}

If HyControl mode was just enabled or the last command was prefix arg-related, invert the value of the prefix argument or if 0, set it to -1. Otherwise, depending on whether in Frames or Windows mode, shrink the frame or window to the minimum size needed to display its text.

{C-u}

Multiply the prefix argument by 4 each time this is pressed.

{@}

Display a grid of windows in the selected frame sized according to the prefix argument or via a prompted input. Left digit of the argument is the number of grid rows and the right digit is the number of grid columns to display. The buffers displayed in the grid are determined by the value of the prefix argument given to the command or by the selected items in the current window if in Buffer Menu, Ibuffer Menu or Dired mode.

With no prefix argument and no items chosen, the selected frame’s buffer list is filtered through hycontrol-display-buffer-predicate-list, a list of predicate/boolean filter functions. The default predicate selects existing buffers with attached files and displays those.

Image 8.1: 2x3 Windows Grid

With a prefix argument of 0, the user is prompted for a major mode name and the windows grid size. Only those buffers with the named major mode are displayed.

With a prefix argument < 0, the user is prompted for a shell glob-type file pattern; matching files are read into buffers and displayed in an auto-sized windows grid.

Otherwise, when the prefix argument is an invalid size, the windows grid command prompts for the grid size.

When done, this resets the persistent prefix argument to 1 to prevent following commands from using the often large grid size argument.

If you ever need to experiment with different sized window grids, use {M-x hycontrol-window-grid-repeatedly RET}. It will repeatedly prompt you for a grid size and then display it. When you are done, simply press {RET} to exit.

Programmatically, there are a number of ways to generate and display a windows grid. hycontrol-windows-grid-by-file-pattern creates a windows grid from a glob file pattern. It is bound to {C--1 C-c @}. hycontrol-windows-grid-by-buffer-list creates a windows grid from a list of buffers or buffer names. hycontrol-windows-grid-by-file-list creates a windows grid from a list of file names.

{a}

Cycle through common width adjustments of a frame, such as 25% and 50%. Widths are given in screen percentages by the list hycontrol-frame-widths and typically go from widest to narrowest.

{A}

Cycle through common height adjustments of a frame, such as 33.3% and 75%. Heights are given in screen percentages by the list hycontrol-frame-heights and typically go from tallest to shortest.

{h}

Increase height by argument lines (line height determined by buffer character height).

{s}

Shorten height by argument lines.

{w}

Widen by argument characters.

{n}

Narrow by argument characters.

{%}

In FRAMES mode, resize frame’s height and width to about argument percent of the screen size.

{H}

In FRAMES mode, resize frame’s height to about argument percent of the screen size.

{I/J/K/M}

In WINDOWS mode, the keys I, J, K, M move directionally (based on QUERTY key layout) between windows in the selected frame. In FRAMES mode, they move directionally through visible frames. These use the windmove and framemove libraries. When any of these keys are pressed, Hyperbole will prompt to install the needed library if not already installed.

{W}

In FRAMES mode, resize frame’s width to about argument percent of the screen size.

{up}

{down}

{left}

{right}

Move frame in the specified direction by argument pixels.

{c}

With each press, cycle the selected frame’s position clockwise through the middle of edges and corners of the screen. With an argument of 0, reset the cycle position to the upper left corner. Respects the pixel edge offsets returned by hycontrol-get-screen-offsets.

{d}

Delete selected window or frame based on mode.

{D}

Prompt for confirmation and then delete non-selected windows or frames based on mode.

{l}

In FRAMES mode, lower the selected frame below all other Emacs session frames.

{o}

Select the next window in the window list, across all visible frames.

{O}

Select the next visible frame.

{keypad number}

In FRAMES mode, move the frame directly to the screen edge position given by the numeric keypad layout. For example, 3 moves the frame to the bottom right corner and 8 moves it to the middle of the top edge. Keypad numeric keys do not adjust the argument. Respects the pixel edge offsets returned by hycontrol-get-screen-offsets.

{p}

Display a virtual numeric keypad for emulating a keypad on keyboards without one. Each digit key operates just as a numeric keypad key would.

{r}

In FRAMES mode, raise the selected frame above all other Emacs session frames.

{[}

Create a new atop window or frame depending on mode. If a frame, it is sized to the same size as the selected window and offset from the selected frame by the pixel amounts given by hycontrol-frame-offset.

{]}

Create a new sideways window or frame depending on mode.

{(}

Save the current window or frame configuration based on mode. Whenever, HyControl is invoked, the current window and frame configurations are saved automatically. So use this command only if you have changed the configuration and wish to save it temporarily.

{)}

After confirmation, restore the last saved window or frame configuration based on mode.

{f}

Clone the selected window to a new similarly sized frame.

{F}

Clone the selected window to a new similarly sized frame. Delete the original window unless there is only one window in the source frame or if hycontrol-keep-window-flag is non-nil.

{I}

{J}

{K}

{M}

Select another window or frame in the given direction depending on the current HyControl mode. I=above, J=left, K=right and M=below.

{i}

{j}

{k}

{m}

Expand the selected frame to the respective screen edge based on U.S. keyboard key layout. i=top, j=left, k=right and m=bottom screen edge. If already at the edge, adjusts the perpendicular dimension to ARG percent of the screen (50% by default if ARG is 1 or nil) but keep it at the screen edge. Respects the pixel edge offsets returned by hycontrol-get-screen-offsets.

{=}

After confirmation, in WINDOWS mode, make the current frame’s windows approximately the same size. In FRAMES mode, make all visible frames the size of the selected frame.

{-}

In WINDOWS mode, shrink window to its smallest possible number of lines to display the entire buffer, if possible. Otherwise or if the window is already displaying all of its lines, shrink it to about one line, if possible.

In FRAMES mode, make the frame as small as possible while still displaying it.

{+}

Make the window or frame (based on mode) as large as possible. In FRAMES mode, a second press of this key restores its size to whatever it was prior to the first use of this command.

{b}

Bury the selected buffer within the buffer list, displaying the next buffer.

{u}

Unbury the bottom buffer in the buffer list and display it in the selected window.

{~}

Swap two buffers between the selected window or frame and one other. In WINDOWS mode, there must be precisely two windows in the selected frame. In FRAMES mode, the second frame must have a single window.

{Z}

Zoom in selected window or frame text based on mode, increasing default face size.

{z}

Zoom out selected window or frame text based on mode, increasing default face size. Zooming supports an argument of between 1 and 9 (any other value sets the argument to 1). The argument determines the number of sizes by which to zoom.

FRAMES mode zooming requires the separately available zoom-frm.el library. WINDOWS zooming works without this library.

{t}

Toggle between WINDOWS and FRAMES submodes.

{Q}

{q}

Press {Q} to globally quit HyControl mode and restore normal key bindings. Typically {q} works as well, unless in a help buffer where {q} is bound to quit-window, then that is run instead of quitting HyControl. A second press of {q} will then quit HyControl.

The rest of this section goes into some technicalities about HyControl settings. You may ignore it if you are not familiar with Emacs variables and functions or with customized Emacs.

HyControl allows placement of frames at screen edges and corners with the frame cycle command, {c}, and direct placement using the layout of the numeric keypad keys, if available, or the p virtual keypad key otherwise. (Note that a screen may span multiple physical monitors).

To prevent widgets and toolbars at the corners of the screen from being obscured, HyControl can offset each frame from each screen edge by a fixed number of pixels. These offsets are specified by the variable,hycontrol-screen-offset-alist and can differ for each type of screen; see its documentation for details. If you change its value, then call hycontrol-set-screen-offsets to set any new offset values. hycontrol-get-screen-offsets returns the list of offsets in clockwise order starting from the top edge. Both functions display a minibuffer message with the current offsets when called interactively.

When HyControl creates a new frame, it automatically sizes it to the same size as the previously selected frame and offsets it from that frame by the (X . Y) number of pixels given in the variable, hycontrol-frame-offset.

The source code for the HyControl system is in hycontrol.el within your Hyperbole source directory, given by hyperb:dir. HyControl uses standard Emacs keymaps, so any keys can be rebound. Remember that Hyperbole typically binds {C-c \} to the windows control menu, but if you would like to bind either of the two HyControl minor mode invocation commands to keys, they are, hycontrol-enable-windows-mode and hycontrol-enable-frames-mode. Generally, you need only one of these bound to a key since when you press that key, the other command can be reached by pressing {t}.