[elpa] externals/logos 6c8f8ee5e6 1/2: Implement logos-focus-mode-extra-functions

[ELPA Syncer]

branch: externals/logos
commit 6c8f8ee5e6bc55d70e2e62c85eef1b00f62c25f1
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Implement logos-focus-mode-extra-functions
    
    This is inspired by issue 1 over at the GitHub mirror:
    <https://github.com/protesilaos/logos/issues/1>.
---
 README.org | 21 +++++++++++++++++++++
 logos.el   | 16 +++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index 95cb754980..6381daf4a5 100644
--- a/README.org
+++ b/README.org
@@ -227,6 +227,9 @@ changes out-of-the-box 
([[#h:2bb57369-352a-43bf-afe3-0bed2fcc7359][Extra tweaks]
               logos-scroll-lock nil
               logos-olivetti nil)
 
+;; Also check this manual for `logos-focus-mode-extra-functions'.  It is
+;; a hook that lets you extend `logos-focus-mode'.
+
 (let ((map global-map))
   (define-key map [remap narrow-to-region] #'logos-narrow-dwim)
   (define-key map [remap forward-page] #'logos-forward-page-dwim)
@@ -419,6 +422,24 @@ result can look like this:
         (t . ,(or outline-regexp logos--page-delimiter))))
 #+end_src
 
+** Leverage logos-focus-mode-extra-functions
+:PROPERTIES:
+:CUSTOM_ID: h:a2540f2f-1159-4e5c-a486-e1f2cb63fee8
+:END:
+#+cindex: User-level extensions to logos-focus-mode
+
+#+vindex: logos-focus-mode-extra-functions
+The ~logos-focus-mode-extra-functions~ is a normal hook that runs when
+~logos-focus-mode~ is enabled.  It gives users the power to write their
+own extensions that change how the buffer works when that mode is
+toggled on/off.
+
+The hook is designed to call functions without an argument.  An example
+function that sets a variable is ~logos--buffer-read-only~; one that
+sets a mode is ~logos--scroll-lock~; another that sets the mode of an
+external package is ~logos--olivetti~; while ~logos--hide-fringe~
+provides yet another useful sample.
+
 * Acknowledgements
 :PROPERTIES:
 :CUSTOM_ID: h:300c12cb-853e-4e06-9627-e1d6fd3a3a38
diff --git a/logos.el b/logos.el
index b6c251c56b..536aadfc2c 100644
--- a/logos.el
+++ b/logos.el
@@ -155,6 +155,19 @@ This is only relevant when `logos-focus-mode' is enabled."
   :group 'logos
   :local t)
 
+(defcustom logos-focus-mode-extra-functions nil
+  "List of functions to execute when `logos-focus-mode' is toggled.
+
+Each function is run without an argument.  An example that sets a
+variable is `logos--buffer-read-only'; one that sets a mode is
+`logos--scroll-lock'; another that sets the mode of an external
+package is `logos--olivetti'; while `logos--hide-fringe' provides
+yet another useful sample.
+
+Consult the Logos manual for concrete do-it-yourself examples."
+  :type 'hook
+  :group 'logos)
+
 ;;;; General utilities
 
 (defun logos--focus-p ()
@@ -356,7 +369,8 @@ options: `logos-scroll-lock', `logos-variable-pitch',
   (logos--remove-fringe-remap)
   (setq logos--restore nil)
   (when logos-focus-mode
-    (logos--setup)))
+    (logos--setup)
+    (run-hooks 'logos-focus-mode-extra-functions)))
 
 (defun logos--setup ()
   "Set up aesthetics for presentation."