Extensions
- You may also want to look at Writing Extensions
Table of Contents
Purpose is bundled with several extensions, which are contained in the window-purpose-x.el file.
In order to use them, you need to add this line to your init file:
(require 'window-purpose-x)Below is a list of those extensions. Note that some of these extensions have a prototype quality, and are there mostly do demonstrate what you can do with Purpose.
Code1 provides a window layout for writing code. It's quite simple and has a prototype nature, and works best with Emacs 24.4 and newer. Set it up with M-x purpose-x-code1-setup:
- Main window: code
-
Top left: directory of current file. Uses Dired with
dired-hide-details-mode. Updated only when Purpose selects a buffer (this could be improved) -
Bottom left: currently opened files. Uses IBuffer with
ibuffer-auto-modeand a custom filter. - Right: list of Imenu entries of current file. Uses imenu-list.
To close Code1, use M-x purpose-x-code1-unset - this cleans everything relevant, but doesn't change the layout.
Magit extension provides Purpose configurations for Magit:
-
M-x purpose-x-magit-single-on: All Magit buffers have the same purpose -
'magit -
M-x purpose-x-magit-multi-on: Each Magit major mode has its own purpose -
'magit-status,'magit-diffand so on - M-x purpose-x-magit-off: Remove Magit configuration
The Magit configurations are pretty straight-forward. Suggestions for improvement are welcome.
Golden Ratio adds some hooks that make golden-ratio.el work with Purpose. Activate with M-x purpose-x-golden-ratio-setup, deactivate with M-x purpose-x-golden-ratio-unset.
Command M-x purpose-x-psw-switch-buffer-with-purpose uses popup-switcher interface to switch to a buffer with the same purpose as the current buffer.
Command purpose-x-popwin-setup enables an extension that gives certain buffers a popup behavior, similar to Popwin package. To disable this extension, use command purpose-x-popwin-unset.
Popup buffers are all the buffers that the 'popup purpose. The best way to give a buffer the 'popup purpose is to add a suitable entry to any of the variables purpose-x-popwin-major-modes, purpose-x-popwin-buffer-names and purpose-x-popwin-buffer-name-regexps, and call the function purpose-x-popwin-update-conf.
The location of the popup window is controlled by the variable purpose-x-popwin-position. The values 'left, 'right, 'top and 'bottom will cause the popup window to be displayed in the left, right, top or bottom side of the current frame. purpose-x-popwin-position can also be set to a display function - in this case, that function decides how to create the popup window.
When purpose-x-popwin-position is either 'left or 'right, the width of the popup window is determined by variable purpose-x-popwin-width. When purpose-x-popwin-position is either 'top or 'bottom, the height of the popup window is determined by purpose-x-popwin-height.
Currenty, the popup window doesn't close itself automatically, as is done in Popwin. It has to be closed manually with the command purpose-x-popwin-close-windows. If you use purpose-x-popwin-setup, it is suggested that you bind purpose-x-popwin-close-windows to a convenient key.
It is possible to set buffers of any purpose as popup buffers, with the function purpose-x-popupify-purpose. For example, the following code causes Purpose to treat buffers with 'terminal or 'general purpose as popup buffers:
(purpose-x-popupify-purpose 'terminal #'purpose-display-at-bottom)
(purpose-x-popupify-purpose 'general #'purpose-display-at-right)Note that 'terminal buffers and 'general buffers will not use the same window! The 'terminal buffers will open at the bottom, while the 'general buffers will open at the right.
Also note that these windows will not be closed by the command purpose-xpopwin-close-windows, although the command winner-undo can have the same effect in some circumstances.
To remove the popup behavior, use the function purpose-x-unpopupify-purpose.
Perspective extension provides a way to associate purpose configurations with perspectives (see perspective.el). To activate this extension, use M-x purpose-x-persp-setup.
Each time the perspective is changed, the purpose configuration is changed according to the variable purpose-x-persp-confs. This variable maps between perspective names to purpose-conf objects.
Internally, this extension calls (purpose-set-extension-configuration :perspective <purpose-conf>).
For example, you may define a perspective called "python" where you want python files to have a distinct purpose:
(require 'window-purpose-x)
(puthash "python" (purpose-conf "python" :mode-purposes '((python-mode . py))) purpose-x-persp-confs)
(purpose-x-persp-setup)The perspective extension also provides three commands for switching buffers: purpose-x-persp-switch-buffer, purpose-x-persp-switch-buffer-other-window
and purpose-x-persp-switch-buffer-other-frame. These commands let you switch to a buffer in the current perspective that has the same purpose as the
current buffer.
When killing a visible buffer, Emacs needs to decide which buffer should replace the killed buffer in the now vacant window (or windows).
The Kill extension makes that decision purpose-aware. The extension works by overriding replace-buffer-in-windows with
purpose-x-replace-buffer-in-windows-1.
The new rules for handling the vacant window are as follows:
- If the window is buffer-dedicated, delete the window.
- If the window is purpose-dedicated, and there is another buffer with the same purpose, display that buffer in the window.
- If the window is purpose-dedicated, but there are no other buffers with the same purpose, delete the window.
- Otherwise, display any buffer in the window.
However, the decision is also affected by the window and frame layout:
- If the window can't be deleted (i.e. it's the only window in the only frame), display any buffer in the window.
- If the window can be deleted, and it is the only window in its frame, delete the frame as well.
To enable the Kill extension:
(require 'window-purpose-x)
(purpose-x-kill-setup)