Release: v0.6

Author: alphapapa

README.org

@@ -2,11 +2,13 @@
 
 [[https://elpa.gnu.org/packages/activities.html][file:https://elpa.gnu.org/packages/activities.svg]]
 
-Inspired by Genera's and KDE's concepts of "activities", this library allows the user to select an "activity", the loading of which restores a window configuration into a ~tab-bar~ tab or frame, along with the buffers shown in each window.  Saving an activity saves the state for later restoration.  Switching away from an activity saves the last-used state for later switching back to, while still allowing the activity's initial or default state to be restored on demand.  Resuming an activity loads the last-used state, or the initial/default state when a universal argument is provided.
+Inspired by Genera's and KDE's concepts of "activities", this Emacs library allows the user to manage frames/tabs, windows, and buffers according to their purpose.  An "activity" comprises a frame or tab, its window configuration, and the buffers displayed in them--its "state"; this state would be related to a certain task the user performs at various times, such as developing a certain software project, reading and writing email, working with one's Org mode system, etc.
 
-The implementation uses the bookmark system to save buffers' states--that is, any major mode that supports the bookmark system is compatible.  A buffer whose major mode does not support the bookmark system (or does not support it well enough to restore useful state) is not compatible and can't be fully restored, or perhaps not at all; but solving that is as simple as implementing bookmark support for the mode, which is usually trivial.
+"Suspending" an activity saves the activity's state and closes its frame/tab; the user would do this when finished with the activity's task for the time being.  "Resuming" the activity restores its buffers and windows to its frame/tab; the user would do this when ready to resume the task at a later time.  This saves the user from having to manually arrange the same windows and buffers each time the task is to be done.
 
-Integration with Emacs's ~tab-bar-mode~ is provided: a window configuration or can be restored to a ~tab-bar~ tab or to a frame.
+Each activity saves two states: the default state, set when the activity is defined by the user, and the last-used state, which was how the user left it when the activity was suspended (or when Emacs exited, etc).  This allows the user to resume the activity where the task was left off, while also allowing it to be reverted to the default state, providing a consistent entry point into the activity.
+
+Internally, the Emacs ~bookmark~ library is used to save and restore buffers' states--that is, any major mode that supports the bookmark system is compatible.  A buffer whose major mode does not support the bookmark system (or does not support it well enough to restore useful state) is not compatible and can't be fully restored, or perhaps not at all; but solving that is as simple as implementing bookmark support for the mode, which is often trivial.
 
 Various hooks are (or will be--feedback is welcome) provided, both globally and per-activity, so that the user can define functions to be called when an activity is saved, restored, or switched from/to.  For example, this could be used to limit the set of buffers offered for switching to within an activity, or to track the time spent in an activity.
 
@@ -64,6 +66,7 @@ This is the recommended configuration, in terms of a ~use-package~ form to be pl
      ("C-x C-a C-k" . activities-kill)
      ;; This binding mirrors, e.g. "C-x t RET".
      ("C-x C-a RET" . activities-switch)
+     ("C-x C-a b" . activities-switch-buffer)
      ("C-x C-a g" . activities-revert)
      ("C-x C-a l" . activities-list)))
 #+END_SRC
@@ -115,6 +118,8 @@ Key bindings are, as always, ultimately up to the user.  However, in [[Configura
 + ~activities-resume~ (~C-x C-a C-a~) :: Resume an activity, switching to a new frame or tab for its window configuration, and restoring its buffers.  With prefix argument, restore its default state rather than its last.
 + ~activities-revert~ (~C-x C-a g~) :: Revert an activity to its default state.
 + ~activities-switch~ (~C-x C-a RET~) :: Switch to an already-active activity.
++ ~activities-switch-buffer~ (~C-x C-a b~) :: Switch to a buffer associated with the current activity (or, with prefix argument, another activity).
++ ~activities-rename~ :: Rename an activity.
 + ~activities-discard~ :: Discard an activity permanently.
 + ~activities-save-all~ :: Save all active activities' states.  (~activities-mode~ does this automatically, so this command should rarely be needed.)
 
@@ -126,7 +131,7 @@ When option ~activities-bookmark-store~ is enabled, an Emacs bookmark is stored
 
 + How is this different from [[https://github.com/alphapapa/burly.el][Burly.el]] or [[https://github.com/alphapapa/bufler.el/][Bufler.el]]? :: Burly is a well-polished tool for restoring window and frame configurations, which could be considered an incubator for some of the ideas furthered here.  Bufler's ~bufler-workspace~ library uses Burly to provide some similar functionality, which is at an exploratory stage.  ~activities~ hopes to provide a longer-term solution more suitable for integration into Emacs.
 
-+ How does this differ from "workspace" packages? :: Yes, there are many Emacs packages that provide "workspace"-like features in one way or another.  To date, only Burly and Bufler seem to offer the ability to restore one across Emacs sessions.  As mentioned, ~activities~ is intended to be more refined and easier to use (e.g. automatically saving activities' states when ~activities-mode~ is enabled).  Comparisons to other packages are left to the reader; suffice to say that ~activities~ is intended to provide what other tools haven't, in an idiomatic, intuitive way.  (Feedback is welcome.)
++ How does this differ from "workspace" packages? :: Yes, there are many Emacs packages that provide "workspace"-like features in one way or another.  To date, only Burly and Bufler seem to offer the ability to restore one across Emacs sessions, including non-file-backed buffers.  As mentioned, ~activities~ is intended to be more refined and easier to use (e.g. automatically saving activities' states when ~activities-mode~ is enabled).  Comparisons to other packages are left to the reader; suffice to say that ~activities~ is intended to provide what other tools haven't, in an idiomatic, intuitive way.  (Feedback is welcome.)
 
 + How does this differ from the built-in ~desktop-mode~? :: As best this author can tell, ~desktop-mode~ saves and restores one set of buffers, with various options to control its behavior.  It does not use ~bookmark~ internally, which prevents it from restoring non-file-backed buffers.  As well, it is not intended to be used on-demand to switch between sets of buffers, windows, or frames (i.e. "activities").
 
@@ -138,6 +143,19 @@ When option ~activities-bookmark-store~ is enabled, an Emacs bookmark is stored
 
 * Changelog
 
+** v0.6
+
+*Additions*
++ Command ~activities-switch-buffer~ switches to a buffer associated with the current activity (or, with prefix argument, another activity).  (A buffer is considered to be associated with an activity if it has been displayed in its tab.  Note that this feature currently requires ~activities-tabs-mode~.)
++ Command ~activities-rename~ renames an activity.
++ Option ~activities-after-switch-functions~, a hook called after switching to an activity.
++ Option ~activities-set-frame-name~ sets the frame name after switching to an activity.  ([[https://github.com/alphapapa/activities.el/issues/33][#33]].  Thanks to [[https://github.com/jdtsmith][JD Smith]].)
++ Option ~activities-kill-buffers~, when suspending an activity, kills buffers that were only shown in that activity.
+
+*Changes*
++ Default time format in activities list.
++ When saving all activities, don't persist to disk for each activity.  ([[https://github.com/alphapapa/activities.el/issues/34][#34]].  Thanks to [[https://github.com/yrns][Al M.]] for reporting.)
+
 ** v0.5.1
 
 *Fixes*

activities-list.el

@@ -32,7 +32,7 @@
   "Activities list buffer."
   :group 'activities)
 
-(defcustom activities-list-time-format "%c"
+(defcustom activities-list-time-format "%Y-%m-%d %H:%M:%S"
   "Time format for `activities-list' buffer."
   :type 'string)
 

activities-tabs.el

@@ -35,6 +35,8 @@
   "Records the original value of `tab-bar-tab-face-function'.
 When `activities-tabs-mode' is enabled.")
 
+(defvar activities-kill-buffers)
+
 ;;;; Customization
 
 (defgroup activities-tabs nil
@@ -67,10 +69,12 @@ accordingly."
                         (activities--set . activities-tabs-activity--set)
                         (activities--switch . activities-tabs--switch)
                         (activities-current . activities-tabs-current)
-                        (activities-close . activities-tabs-close))))
+                        (activities-close . activities-tabs-close)
+                        (activities-switch-buffer . activities-tabs--switch-buffer))))
     (if activities-tabs-mode
         (progn
           (tab-bar-mode 1)
+          (add-hook 'window-configuration-change-hook #'activities-tabs--window-configuration-change)
           (advice-add #'activities-resume :before #'activities-tabs-before-resume)
           (pcase-dolist (`(,symbol . ,function) override-map)
             (advice-add symbol :override function))
@@ -83,22 +87,87 @@ accordingly."
           (unless activities-tabs-tab-bar-tab-face-function-original
             (setf activities-tabs-tab-bar-tab-face-function-original tab-bar-tab-face-function
                   tab-bar-tab-face-function #'activities-tabs--tab-bar-tab-face-function)))
+      (remove-hook 'window-configuration-change-hook #'activities-tabs--window-configuration-change)
       (advice-remove #'activities-resume #'activities-tabs-before-resume)
       (pcase-dolist (`(,symbol . ,function) override-map)
         (advice-remove symbol function))
       (when activities-tabs-tab-bar-tab-face-function-original
         (setf tab-bar-tab-face-function activities-tabs-tab-bar-tab-face-function-original
               activities-tabs-tab-bar-tab-face-function-original nil)))))
 
+;;;; Commands
+
+(defun activities-tabs--switch-buffer (activity)
+  "Switch to a buffer associated with ACTIVITY.
+Interactively, select from buffers associated with ACTIVITY; or,
+with prefix argument, choose another activity."
+  (interactive
+   (list (if current-prefix-arg
+             (activities-completing-read)
+           (or (activities-current) (activities-completing-read)))))
+  ;; Much code borrowed from `read-buffer-to-switch', which see.
+  (let* ((tab (activities-tabs--tab activity))
+         (activity-buffers (activities-tabs--tab-parameter 'activities-buffer-list tab))
+         (current-buffer-name (buffer-name (current-buffer)))
+         (rbts-completion-table
+          (apply-partially
+           #'completion-table-with-predicate
+	   #'internal-complete-buffer
+	   (lambda (buffer-name)
+             (let ((buffer-name (if (consp buffer-name) (car buffer-name) buffer-name)))
+               (and (not (equal buffer-name current-buffer-name))
+                    (cl-member buffer-name activity-buffers :key #'buffer-name))))
+	   nil))
+         (selected-buffer
+          (minibuffer-with-setup-hook
+              (lambda ()
+                (setq-local minibuffer-completion-table rbts-completion-table)
+                (if (and (boundp 'icomplete-with-completion-tables)
+                         (listp icomplete-with-completion-tables))
+                    (setq-local icomplete-with-completion-tables
+                                (cons rbts-completion-table
+                                      icomplete-with-completion-tables))))
+            (read-buffer "Switch to activity buffer:" (other-buffer (current-buffer))
+                         (confirm-nonexistent-file-or-buffer)))))
+    (switch-to-buffer selected-buffer)))
+
 ;;;; Functions
 
 (cl-defun activities-tabs-close (activity)
   "Close ACTIVITY.
 Its state is not saved, and its frames, windows, and tabs are
 closed."
   (activities--switch activity)
+  (activities-tabs--kill-buffers)
   (tab-bar-close-tab))
 
+(defun activities-tabs--window-configuration-change ()
+  "Add frame's windows' buffers to the current tab's `buffer-list' parameter."
+  (cl-assert tab-bar-mode)
+  (let ((tab (tab-bar--current-tab-find)))
+    (walk-windows (lambda (window)
+                    (cl-pushnew (window-buffer window)
+                                (alist-get 'activities-buffer-list (cdr tab)))))))
+
+(defun activities-tabs--kill-buffers ()
+  ;; TODO: Frame parameter name should be prefixed with `activities'.
+  "Kill buffers that are only in the current tab's buffer list.
+Only does so when `activities-kill-buffers' is non-nil."
+  (when activities-kill-buffers
+    (let* ((all-tabs (funcall tab-bar-tabs-function))
+           (current-tab (tab-bar--current-tab-find))
+           (tab-buffers
+            (cl-reduce
+             (lambda (acc tab)
+               (seq-difference acc (activities-tabs--tab-parameter 'activities-buffer-list tab)))
+             (remove current-tab all-tabs)
+             :initial-value (activities-tabs--tab-parameter 'activities-buffer-list current-tab)))
+           (target-buffers (cl-remove-if (lambda (buffer)
+                                           (run-hook-with-args-until-success
+                                            'activities-anti-kill-predicates buffer))
+                                         tab-buffers)))
+      (mapc #'kill-buffer target-buffers))))
+
 (defun activities-tabs--switch (activity)
   "Switch to ACTIVITY.
 Selects its tab, making one if needed.  Its state is not changed."