Clock: More control about what time is shown in mode line while clocking

This commit changes which time is shown in the mode line while
clocking.  Normally this will now be the total time ever clocked on
this task and its children.

However, when the task is a repeating one, only the time since the
last reset of the task will be shown.  The time of the last reset is
now recorded in a LAST_REPEAT property.

You can also set the CLOCK_MODELINE_TOTAL property to the value
"current" to only show the current clocking instance.  Or it may be
the value "today", to only add up the time spent today on this task.
Other possible values are "repeat", "all", or "auto".

Finally, you can set your default for this property with
`org-clock-modeline-total'.

doc/ChangeLog

@@ -1,3 +1,7 @@
+2009-06-02  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Clocking work time): Document the clock time display.
+
 2009-05-27  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Structure editing, TODO basics): Document new

doc/org.texi

@@ -5252,12 +5252,27 @@ can arrange for the clock information to persisst accress Emacs sessions with
 Start the clock on the current item (clock-in).  This inserts the CLOCK
 keyword together with a timestamp.  If this is not the first clocking of
 this item, the multiple CLOCK lines will be wrapped into a
-@code{:CLOCK:} drawer (see also the variable
+@code{:LOGBOOK:} drawer (see also the variable
 @code{org-clock-into-drawer}).  When called with a @kbd{C-u} prefix argument,
 select the task from a list of recently clocked tasks.  With two @kbd{C-u
 C-u} prefixes, clock into the task at point and mark it as the default task.
 The default task will always be available when selecting a clocking task,
-with letter @kbd{d}.
+with letter @kbd{d}.@*
+@cindex property: CLOCK_MODELINE_TOTAL
+@cindex property: LAST_REPEAT
+@vindex org-clock-modeline-total
+While the clock is running, the current clocking time is shown in the mode
+line, along with the title of the task.  The clock time shown will be all
+time ever clocked for this task and its children.  If the task is a repeating
+one (@pxref{Repeated tasks}), only the time since the last reset of the task
+@footnote{as recorded by the @code{LAST_REPEAT} property} will be shown.
+More control over what time is shown can be exercised with the
+@code{CLOCK_MODELINE_TOTAL} property.  It may have the values @code{current}
+to show only the current clocking instance, @code{today} to show all time
+clocked on this tasks today (see also the variable
+@code{org-extend-today-until}), @code{all} to include all time, or
+@code{auto} which is the default@footnote{See also the variable
+@code{org-clock-modeline-total}.}.
 @kindex C-c C-x C-o
 @item C-c C-x C-o
 @vindex org-log-note-clock-out

lisp/ChangeLog

@@ -1,5 +1,14 @@
 2009-06-02  Carsten Dominik  <carsten.dominik@gmail.com>
 
+	* org.el (org-global-properties-fixed): Add default for
+	CLOCK_MODELINE_TOTAL.
+
+	* org-clock.el (org-clock-sum): Accept lists and strigs as tstart
+	andd tend.
+	(org-clock-sum-current-item): Optional argument TSTART, pass it to
+	org-clock-sum.
+	(org-clock-get-sum-start): New function.
+
 	* org.el (org-startup-options): New keywords blockhide and
 	blockshow.
 	(org-mode): Add new invisibility spec.

lisp/org-clock.el

@@ -161,6 +161,24 @@ file name  play this sound file.  If not possible, fall back to beep"
 	  (const :tag "Standard beep" t)
 	  (file :tag "Play sound file")))
 
+(defcustom org-clock-modeline-total 'auto
+  "Default setting for the time included for the modeline clock.
+This can be overruled locally using the CLOCK_MODELINE_TOTAL property.
+Allowed values are:
+
+current  Only the time in the current instance of the clock
+today    All time clocked inot this task today
+repeat   All time clocked into this task since last repeat
+all      All time ever recorded for this task
+auto     Automtically, either `all', or `repeat' for repeating tasks"
+  :group 'org-clock
+  :type '(choice
+	  (const :tag "Current clock" current)
+	  (const :tag "Today's task time" today)
+	  (const :tag "Since last repeat" repeat)
+	  (const :tag "All task time" all)
+	  (const :tag "Automatically, `all' or since `repeat'" auto)))
+
 ;;; The clock for measuring work time.
 
 (defvar org-mode-line-string "")
@@ -287,12 +305,12 @@ pointing to it."
 	(cons i marker)))))
 
 
-(defun org-clock-sum-current-item ()
+(defun org-clock-sum-current-item (&optional tstart)
   "Returns time, clocked on current item in total"
   (save-excursion
     (save-restriction
       (org-narrow-to-subtree)
-      (org-clock-sum)
+      (org-clock-sum tstart)
       org-clock-file-total-minutes)))
 
 (defun org-clock-get-clock-string ()
@@ -399,7 +417,7 @@ the clocking selection, associated with the letter `d'."
   (interactive "P")
   (catch 'abort
     (let ((interrupting (marker-buffer org-clock-marker))
-	  ts selected-task target-pos)
+	  ts selected-task target-pos (msg-extra ""))
       (when (equal select '(4))
 	(setq selected-task (org-clock-select-task "Clock-in on task: "))
 	(if selected-task
@@ -472,7 +490,8 @@ the clocking selection, associated with the letter `d'."
 		    (apply 'encode-time
 			   (org-parse-time-string (match-string 1))))
 	      (setq org-clock-effort (org-get-effort))
-	      (setq org-clock-total-time (org-clock-sum-current-item)))
+	      (setq org-clock-total-time (org-clock-sum-current-item
+					  (org-clock-get-sum-start))))
 	     ((eq org-clock-in-resume 'auto-restart)
 	      ;; called from org-clock-load during startup,
 	      ;; do not interrupt, but warn!
@@ -491,7 +510,8 @@ the clocking selection, associated with the letter `d'."
 		(org-indent-line-to (- (org-get-indentation) 2)))
 	      (insert org-clock-string " ")
 	      (setq org-clock-effort (org-get-effort))
-	      (setq org-clock-total-time (org-clock-sum-current-item))
+	      (setq org-clock-total-time (org-clock-sum-current-item
+					  (org-clock-get-sum-start)))
 	      (setq org-clock-start-time (current-time))
 	      (setq ts (org-insert-time-stamp org-clock-start-time
 					      'with-hm 'inactive))))
@@ -503,7 +523,37 @@ the clocking selection, associated with the letter `d'."
 	    (org-clock-update-mode-line)
 	    (setq org-clock-mode-line-timer
 		  (run-with-timer 60 60 'org-clock-update-mode-line))
-	    (message "Clock started at %s" ts)))))))
+	    (message "Clock started at %s. %s" ts msg-extra)))))))
+
+(defvar msg-extra)
+(defun org-clock-get-sum-start ()
+  (let ((cmt (or (org-entry-get nil "CLOCK_MODELINE_TOTAL")
+		 (symbol-name 'org-clock-modeline-total)))
+	(lr (org-entry-get nil "LAST_REPEAT")))
+    (cond
+     ((equal cmt "current")
+      (setq msg-extra "Showing instance task time.")
+      (current-time))
+     ((equal cmt "today")
+      (setq msg-extra "Showing today's task time.")
+      (let* ((dt (decode-time (current-time))))
+	(setq dt (append (list 0 0 0) (nthcdr 3 dt)))
+	(if org-extend-today-until
+	    (setf (nth 2 dt) org-extend-today-until))
+	(apply 'encode-time dt)))
+     ((or (equal cmt "all")
+	  (and (or (not cmt) (equal cmt "auto"))
+	       (not lr)))
+      (setq msg-extra "Showing all task time.")
+      nil)
+     ((or (equal cmt "repeat")
+	  (and (or (not cmt) (equal cmt "auto"))
+	       lr))
+      (setq msg-extra "Showing task time since last repeat.")
+      (if (not lr)
+	  nil
+	(org-time-string-to-time lr)))
+     (t nil))))
 
 (defun org-clock-find-position (find-unclosed)
   "Find the location where the next clock line should be inserted.
@@ -684,7 +734,8 @@ With prefix arg SELECT, offer recently clocked tasks for selection."
 
 (defun org-clock-sum (&optional tstart tend)
   "Sum the times for each subtree.
-Puts the resulting times in minutes as a text property on each headline."
+Puts the resulting times in minutes as a text property on each headline.
+TSTART and TEND can mark a time range to be considered."
   (interactive)
   (let* ((bmp (buffer-modified-p))
 	 (re (concat "^\\(\\*+\\)[ \t]\\|^[ \t]*"
@@ -696,6 +747,10 @@ Puts the resulting times in minutes as a text property on each headline."
 	 (level 0)
 	 ts te dt
 	 time)
+    (if (stringp tstart) (setq tstart (org-time-string-to-seconds tstart)))
+    (if (stringp tend) (setq tend (org-time-string-to-seconds tend)))
+    (if (consp tstart) (setq tstart (time-to-seconds tstart)))
+    (if (consp tend) (setq tend (time-to-seconds tend)))
     (remove-text-properties (point-min) (point-max) '(:org-clock-minutes t))
     (save-excursion
       (goto-char (point-max))

lisp/org.el

@@ -2468,7 +2468,8 @@ Effort estimates given in this property need to have the format H:MM."
   :type '(string :tag "Property"))
 
 (defconst org-global-properties-fixed
-  '(("VISIBILITY_ALL" . "folded children content all"))
+  '(("VISIBILITY_ALL" . "folded children content all")
+    ("CLOCK_MODELINE_TOTAL_ALL" . "current today repeat all auto"))
   "List of property/value pairs that can be inherited by any entry.
 
 These are fixed values, for the preset properties.  The user variable
@@ -11637,7 +11638,8 @@ but in some other way.")
     "LOCATION" "LOGGING" "COLUMNS" "VISIBILITY"
     "TABLE_EXPORT_FORMAT" "TABLE_EXPORT_FILE"
     "EXPORT_FILE_NAME" "EXPORT_TITLE" "EXPORT_AUTHOR" "EXPORT_DATE"
-    "ORDERED" "NOBLOCKING" "COOKIE_DATA" "LOG_INTO_DRAWER")
+    "ORDERED" "NOBLOCKING" "COOKIE_DATA" "LOG_INTO_DRAWER"
+    "CLOCK_MODELINE_TOTAL")
   "Some properties that are used by Org-mode for various purposes.
 Being in this list makes sure that they are offered for completion.")