Focus

[[https://melpa.org/#/focus][file:https://melpa.org/packages/focus-badge.svg]] [[https://stable.melpa.org/#/focus][file:https://stable.melpa.org/packages/focus-badge.svg]]

• Focus

  [[./focus-demo.gif]]

  This is Focus, a package that dims surrounding text. It works with any theme and can be configured to focus in on different regions like sentences, paragraphs or code-blocks.

• Installation

  It's available on [[https://melpa.org/#/focus][MELPA]] and [[https://stable.melpa.org/#/focus][MELPA Stable]]:

  #+BEGIN_EXAMPLE M-x package-install focus #+END_EXAMPLE

• Usage

  Enable ~focus-mode~ with ~M-x focus-mode~.

  A few interactive functions are provided:

  | Function | Description | |----------------------+--------------------------------------------------------------------------| | ~focus-change-thing~ | Adjust the narrowness of the focused section for the current buffer | | ~focus-pin~ | Pin the focused section to its current location or the region, if active | | ~focus-unpin~ | Unpin the focused section | | ~focus-next-thing~ | Move the point to the middle of the Nth next thing | | ~focus-prev-thing~ | Move the point to the middle of the Nth previous thing |

  Focus relies on [[https://www.emacswiki.org/emacs/ThingAtPoint][Thing At Point]], which can retrieve a /thing/ surrounding the point. These /things/ may be a symbol, list, S-expression (sexp), function definition (defun), sentence, line, page and others. Calling ~M-x focus-change-thing~ allows you to interactively change the kind of region which should be in focus.

** Focus read-only mode

Enable ~focus-read-only-mode~ with ~M-x focus-read-only-mode~. It inhibits changes in a buffer, hides the cursor and provides bindings for moving between /things/.

Some bindings for simple navigation and exiting focus-read-only-mode are provided.

| Keybinding | Description | |------------+-----------------------------| | ~n~ | Jump to next /thing/ | | ~SPC~ | Jump to next /thing/ | | ~p~ | Jump to previous /thing/ | | ~S-SPC~ | Jump to previous /thing/ | | ~i~ | Exit ~focus-read-only-mode~ | | ~q~ | Exit ~focus-read-only-mode~ |

• Customization

  The choice of what /thing/ is suitable for a mode may be configured by setting the variable ~focus-mode-to-thing~. The default is

  #+BEGIN_EXAMPLE '((prog-mode . defun) (text-mode . sentence)) #+END_EXAMPLE

  For modes inheriting ~prog-mode~ (which are most programming modes), the default is the function-body, and for modes inheriting ~text-mode~, the default is a sentence.

  For instance, adding the following to your ~.emacs~-file:

  #+BEGIN_SRC emacs-lisp (add-to-list 'focus-mode-to-thing '(python-mode . paragraph)) #+END_SRC

  changes ~python-mode~ to focus in on code-blocks with no blank lines rather than the entire function.

  According to [[https://www.reddit.com/r/emacs/comments/b1vrar/lsp_support_for_focusel_using_lspmode/][this reddit post]], Focus plays nice with ~lsp-mode~.

** Faces

Focus offers two faces, one for the focused- and unfocused area. By default, the ~focus-focused~ is the empty face, meaning there is no change, and ~focus-unfocused~ inherits the comment face (which is usually subtle). The faces can easily be customized via ~M-x list-faces-display~.