Function: todo-show

todo-show is an autoloaded, interactive and byte-compiled function defined in todo-mode.el.gz.

Signature

(todo-show &optional SOLICIT-FILE INTERACTIVE)

Documentation

Visit a todo file and display one of its categories.

When invoked in Todo mode, Todo Archive mode or Todo Filtered Items mode, or when invoked anywhere else with a prefix argument, prompt for which todo file to visit. When invoked outside of a Todo mode buffer without a prefix argument, visit todo-default-todo-file. Subsequent invocations from outside of Todo mode revisit this file or, with option todo-show-current-file(var)/todo-show-current-file(fun) non-nil (the default), whichever todo file was last visited.

If you call this command before you have created any todo file in the current format, and you have a todo file in old format, it will ask you whether to convert that file and show it. Otherwise, calling this command before any todo file exists prompts for a file name and an initial category (defaulting to todo-initial-file and todo-initial-category), creates both of these, visits the file and displays the category, and if option todo-add-item-if-new-category is non-nil (the default), prompts for the first item.

The first invocation of this command on an existing todo file interacts with the option todo-show-first: if its value is first (the default), show the first category in the file; if its value is table, show the table of categories in the file; if its value is one of top, diary or regexp, show the corresponding saved top priorities, diary items, or regexp items file, if any. Subsequent invocations always show the file's current (i.e., last displayed) category.

In Todo mode just the category's unfinished todo items are shown by default. The done items are hidden, but typing M-x todo-toggle-view-done-items (todo-toggle-view-done-items) displays them below the todo items. With non-nil user option todo-show-with-done both todo and done items are always shown on visiting a category.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/calendar/todo-mode.el.gz
;;;###autoload
(defun todo-show (&optional solicit-file interactive)
  "Visit a todo file and display one of its categories.

When invoked in Todo mode, Todo Archive mode or Todo Filtered
Items mode, or when invoked anywhere else with a prefix argument,
prompt for which todo file to visit.  When invoked outside of a
Todo mode buffer without a prefix argument, visit
`todo-default-todo-file'.  Subsequent invocations from outside of
Todo mode revisit this file or, with option
`todo-show-current-file' non-nil (the default), whichever todo
file was last visited.

If you call this command before you have created any todo file in
the current format, and you have a todo file in old format, it
will ask you whether to convert that file and show it.
Otherwise, calling this command before any todo file exists
prompts for a file name and an initial category (defaulting to
`todo-initial-file' and `todo-initial-category'), creates both of
these, visits the file and displays the category, and if option
`todo-add-item-if-new-category' is non-nil (the default), prompts
for the first item.

The first invocation of this command on an existing todo file
interacts with the option `todo-show-first': if its value is
`first' (the default), show the first category in the file; if
its value is `table', show the table of categories in the file;
if its value is one of `top', `diary' or `regexp', show the
corresponding saved top priorities, diary items, or regexp items
file, if any.  Subsequent invocations always show the file's
current (i.e., last displayed) category.

In Todo mode just the category's unfinished todo items are shown
by default.  The done items are hidden, but typing
\\[todo-toggle-view-done-items] displays them below the todo
items.  With non-nil user option `todo-show-with-done' both todo
and done items are always shown on visiting a category."
  (interactive "P\np")
  (when todo-default-todo-file
    (todo-check-file (todo-absolute-file-name todo-default-todo-file)))
  (catch 'shown
    ;; Before initializing the first todo first, check if there is a
    ;; legacy todo file and if so, offer to convert to the current
    ;; format and make it the first new todo file.
    (unless todo-default-todo-file
      (let ((legacy-todo-file (if (boundp 'todo-file-do)
                                  todo-file-do
                                (locate-user-emacs-file "todo-do" ".todo-do"))))
        (when (and (file-exists-p legacy-todo-file)
                   (y-or-n-p (concat "Do you want to convert a copy of your "
                                     "old todo file to the new format? ")))
          (when (todo-convert-legacy-files)
            (throw 'shown nil)))))
    (catch 'end
      (let* ((cat)
	     (show-first todo-show-first)
	     (file (cond ((or solicit-file
			      (and interactive
				   (memq major-mode '(todo-mode
						      todo-archive-mode
						      todo-filtered-items-mode))))
			  (if (funcall todo-files-function)
			      (todo-read-file-name "Choose a todo file to visit: "
						   nil t)
			    (user-error "There are no todo files")))
			 ((and (eq major-mode 'todo-archive-mode)
			       ;; Called noninteractively via todo-quit
			       ;; to jump to corresponding category in
			       ;; todo file.
			       (not interactive))
			  (setq cat (todo-current-category))
			  (concat (file-name-sans-extension
				   todo-current-todo-file) ".todo"))
			 (t
			  (or todo-current-todo-file
			      (and todo-show-current-file
				   todo-global-current-todo-file)
			      (todo-absolute-file-name todo-default-todo-file)
			      (todo-add-file)))))
	     add-item first-file)
	(unless todo-default-todo-file
	  ;; We just initialized the first todo file, so make it the default.
	  (setq todo-default-todo-file (todo-short-file-name file)
		first-file t)
          (put 'todo-default-todo-file 'custom-type
               `(radio ,@(todo--files-type-list))))
	(unless (member file todo-visited)
	  ;; Can't setq t-c-t-f here, otherwise wrong file shown when
	  ;; todo-show is called from todo-show-categories-table.
	  (let ((todo-current-todo-file file))
	    (cond ((eq todo-show-first 'table)
		   (todo-show-categories-table))
		  ((memq todo-show-first '(top diary regexp))
		   (let* ((shortf (todo-short-file-name file))
			  (fi-file (todo-absolute-file-name
				    shortf todo-show-first)))
		     (when (eq todo-show-first 'regexp)
		       (let ((rxfiles (directory-files todo-directory t
						       "\\.todr\\'" t)))
			 (when (and rxfiles (> (length rxfiles) 1))
			   (let ((rxf (mapcar #'todo-short-file-name rxfiles)))
			     (setq fi-file (todo-absolute-file-name
					    (completing-read
					     "Choose a regexp items file: "
					     rxf)
                                            'regexp))))))
		     (if (file-exists-p fi-file)
			 (progn
			   (set-window-buffer
			    (selected-window)
			    (set-buffer (find-file-noselect fi-file 'nowarn)))
			   (unless (derived-mode-p 'todo-filtered-items-mode)
			     (todo-filtered-items-mode)))
		       (message "There is no %s file for %s"
				(cond ((eq todo-show-first 'top)
				       "top priorities")
				      ((eq todo-show-first 'diary)
				       "diary items")
				      ((eq todo-show-first 'regexp)
				       "regexp items"))
				shortf)
		       (setq todo-show-first 'first)))))))
	(when (or (member file todo-visited)
		  (eq todo-show-first 'first))
	  (unless (todo-check-file file) (throw 'end nil))
          ;; If todo-show is called from the minibuffer, don't visit
          ;; the todo file there.
	  (set-window-buffer (if (minibufferp) (minibuffer-selected-window)
			       (selected-window))
			     (set-buffer (find-file-noselect file 'nowarn)))
	  (if (equal (file-name-extension (buffer-file-name)) "toda")
	      (unless (derived-mode-p 'todo-archive-mode) (todo-archive-mode))
	    (unless (derived-mode-p 'todo-mode) (todo-mode)))
	  ;; When quitting an archive file, show the corresponding
	  ;; category in the corresponding todo file, if it exists.
	  (when (assoc cat todo-categories)
	    (setq todo-category-number (todo-category-number cat)))
	  ;; If this is a new todo file, add its first category.
	  (when (zerop (buffer-size))
            ;; Don't confuse an erased buffer with a fresh buffer for
            ;; adding a new todo file -- it might have been erased by
            ;; mistake or due to a bug (e.g. Bug#20832).
            (when (buffer-modified-p)
              (error "Buffer is empty but modified, please report a bug"))
	    (let (cat-added)
	      (unwind-protect
		  (setq todo-category-number
			(todo-add-category todo-current-todo-file "")
			add-item todo-add-item-if-new-category
			cat-added t)
		(if cat-added
		    ;; If the category was added, save the file now, so we
		    ;; don't risk having an empty todo file, which would
		    ;; signal an error if we tried to visit it later,
		    ;; since doing that looks for category boundaries.
		    (save-buffer 0)
		  ;; If user cancels before adding the category, clean up
		  ;; and exit, so we have a fresh slate the next time.
		  (delete-file file)
		  ;; (setq todo-files (funcall todo-files-function))
		  (setq todo-files (delete file todo-files))
		  (when first-file
		    (setq todo-default-todo-file nil
			  todo-current-todo-file nil)
                    (put 'todo-default-todo-file 'custom-type
                         `(radio ,@(todo--files-type-list))))
		  (kill-buffer)
		  (keyboard-quit)))))
	  (save-excursion (todo-category-select))
	  (when add-item (todo-insert-item--basic)))
	(setq todo-show-first show-first)
	(add-to-list 'todo-visited file)))))