Toggle horizons buffer

Close #126

changes-for-3.0.org

@@ -8,6 +8,8 @@
 ** you can customize what the functions do for each GTD action (e.g. incubate, single action, etc.)
 ** you can customize your TODO keywords
 ** areas of focus customizable variable and optional decoration hook
+** horizons file customizable, can be displayed/toggled while clarifying items
+suggest keybinding on keymap in doc
 * required config changes
 ** org-gtd-process-mode is now org-gtd-clarify-mode
 ** org-gtd-process-map is now org-gtd-clarify-map

org-gtd-clarify.el

@@ -25,6 +25,7 @@
 ;;; Code:
 
 (require 'org-gtd-id)
+(require 'org-gtd-horizons)
 
 (defgroup org-gtd-clarify nil
   "Customize the behavior when clarifying an item."
@@ -34,9 +35,10 @@
 (defcustom org-gtd-clarify-show-horizons nil
   "If t, show a side buffer with the higher horizons during item clarification.
 The file shown can be configured in `org-gtd-horizons-file'"
+  :options '('right 'top 'left 'bottom 'nil)
   :package-version '(org-gtd . "3.0")
   :group 'org-gtd-clarify
-  :type 'boolean)
+  :type 'symbol)
 
 (defconst org-gtd-clarify--prefix "Org-GTD WIP")
 
@@ -117,15 +119,29 @@ This function is called through the inbox clarification process."
           (org-gtd-clarify-setup-windows chosen-buf-name))
       (message "There are no Org-GTD WIP buffers."))))
 
+(defun org-gtd-clarify-toggle-horizons-window ()
+  "Toggle the window with the horizons buffer."
+  (interactive)
+  (let* ((buffer (org-gtd--horizons-file))
+         (window (get-buffer-window buffer)))
+    (if window
+        (quit-window nil window)
+      (org-gtd-clarify--display-horizons-window))))
+
+(defun org-gtd-clarify--display-horizons-window ()
+  "Display horizons window."
+  (let ((horizons-side (or org-gtd-clarify-show-horizons 'right)))
+    (display-buffer (org-gtd--horizons-file)
+                    `(display-buffer-in-side-window . ((side . ,horizons-side))))))
+
 (defun org-gtd-clarify-setup-windows (buffer-or-name)
   "Setup clarifying windows around BUFFER-OR-NAME."
   (let ((buffer (get-buffer buffer-or-name)))
     (set-buffer buffer)
     (display-buffer buffer)
     (delete-other-windows (get-buffer-window buffer))
     (if org-gtd-clarify-show-horizons
-        (display-buffer (org-gtd--horizons-file)
-                        '(display-buffer-in-side-window . ((side . right)))))))
+        (org-gtd-clarify--display-horizons-window))))
 
 (defun org-gtd-clarify--buffer-name (id)
   "Retrieve the name of the WIP buffer for this particular ID."

org-gtd-core.el

@@ -46,15 +46,6 @@ your own files if you want multiple refile targets (projects, etc.)."
   :package-version '(org-gtd . "0.1")
   :type 'directory)
 
-(defcustom org-gtd-horizons-file "horizons.org"
-  "File holding your GTD horizons.
-
-This may get displayed during item clarification for context and focus.
-This file must be in the `org-gtd-directory'."
-  :group 'org-gtd
-  :package-version '(org-gtd . "3.0")
-  :type 'file)
-
 (defcustom org-gtd-next "NEXT"
   "The `org-mode' keyword for an action ready to be done.  Just the word."
   :group 'org-gtd

org-gtd-files.el

@@ -36,26 +36,13 @@ This is the inbox. Everything goes in here when you capture it.
 
 (defconst org-gtd-default-file-name "org-gtd-tasks")
 
-(defconst org-gtd-file-horizons-template
-  "* Purpose and principles (why)
-* Vision (what)
-* Goals
-* Areas of focus / accountabilities
-")
-
 ;;;###autoload
 (defun org-gtd-inbox-path ()
   "Return the full path to the inbox file."
   (let ((path (org-gtd--path org-gtd-inbox)))
     (org-gtd--ensure-file-exists path org-gtd-inbox-template)
     path))
 
-(defun org-gtd--horizons-file ()
-  "Create or return the buffer to the file containing the GTD horizons."
-  (let ((path (f-join org-gtd-directory org-gtd-horizons-file)))
-    (org-gtd--ensure-file-exists path org-gtd-file-horizons-template)
-    (find-file-noselect path)))
-
 (defun org-gtd--inbox-file ()
   "Create or return the buffer to the GTD inbox file."
   (find-file-noselect (org-gtd-inbox-path)))

org-gtd-horizons.el

@@ -0,0 +1,54 @@
+;;; org-gtd-horizons.el --- manage the horizons buffer -*- lexical-binding: t; coding: utf-8 -*-
+;;
+;; Copyright © 2019-2023 Aldric Giacomoni
+
+;; Author: Aldric Giacomoni <[email protected]>
+;; This file is not part of GNU Emacs.
+
+;; This file is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3, or (at your option)
+;; any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+;;
+;; The horizons help us ensure our lives are on the right track.
+;; The buffer can show up when clarifying to make sure we don't
+;; get distracted.
+;;
+;;; Code:
+
+(require 'org-gtd-files)
+
+(defcustom org-gtd-horizons-file "horizons.org"
+  "File holding your GTD horizons.
+
+This may get displayed during item clarification for context and focus.
+This file must be in the `org-gtd-directory'."
+  :group 'org-gtd
+  :package-version '(org-gtd . "3.0")
+  :type 'file)
+
+(defconst org-gtd-file-horizons-template
+  "* Purpose and principles (why)
+* Vision (what)
+* Goals
+* Areas of focus / accountabilities
+")
+
+(defun org-gtd--horizons-file ()
+  "Create or return the buffer to the file containing the GTD horizons."
+  (let ((path (f-join org-gtd-directory org-gtd-horizons-file)))
+    (org-gtd--ensure-file-exists path org-gtd-file-horizons-template)
+    (find-file-noselect path)))
+
+(provide 'org-gtd-horizons)
+;;; org-gtd-horizons.el ends here

test/horizons-test.el

@@ -17,7 +17,7 @@
  (describe
   "when org-gtd should show the horizons"
 
-  (before-each (setq org-gtd-clarify-show-horizons t))
+  (before-each (setq org-gtd-clarify-show-horizons 'right))
   (after-each (setq org-gtd-clarify-show-horizons nil))
 
   (describe