Function: todo-jump-to-category

todo-jump-to-category is an interactive and byte-compiled function defined in todo-mode.el.gz.

Signature

(todo-jump-to-category &optional FILE WHERE)

Documentation

Prompt for a category in a todo file and jump to it.

With non-nil FILE (interactively a prefix argument), prompt for a specific todo file and choose (with TAB completion) a category in it to jump to; otherwise, choose and jump to any category in either the current todo file or a file in todo-category-completions-files.

Also accept a non-existing category name and ask whether to add a new category by that name; on confirmation, add it and jump to that category, and if option todo-add-item-if-new-category is non-nil (the default), then prompt for the first item.

In noninteractive calls non-nil WHERE specifies either the goal category or its file. If its value is archive, the choice of categories is restricted to the current archive file or the archive you were prompted to choose; this is used by todo-jump-to-archive-category. If its value is the name of a category, jump directly to that category; this is used in Todo Categories mode.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/calendar/todo-mode.el.gz
(defun todo-jump-to-category (&optional file where)
  "Prompt for a category in a todo file and jump to it.

With non-nil FILE (interactively a prefix argument), prompt for a
specific todo file and choose (with TAB completion) a category
in it to jump to; otherwise, choose and jump to any category in
either the current todo file or a file in
`todo-category-completions-files'.

Also accept a non-existing category name and ask whether to add a
new category by that name; on confirmation, add it and jump to
that category, and if option `todo-add-item-if-new-category' is
non-nil (the default), then prompt for the first item.

In noninteractive calls non-nil WHERE specifies either the goal
category or its file.  If its value is `archive', the choice of
categories is restricted to the current archive file or the
archive you were prompted to choose; this is used by
`todo-jump-to-archive-category'.  If its value is the name of a
category, jump directly to that category; this is used in Todo
Categories mode."
  (interactive "P")
  ;; If invoked outside of Todo mode and there is not yet any Todo
  ;; file, initialize one.
  (if (null (funcall todo-files-function))
      (todo-show)
    (let* ((archive (eq where 'archive))
	   (cat (unless archive where))
           (goto-archive (and cat
                              todo-skip-archived-categories
                              (zerop (todo-get-count 'todo cat))
                              (zerop (todo-get-count 'done cat))
                              (not (zerop (todo-get-count 'archived cat)))))
	   (file0 (when cat		; We're in Todo Categories mode.
		    (if goto-archive
			;; If the category has only archived items and
			;; `todo-skip-archived-categories' is non-nil, jump to
			;; the archive category.
			(concat (file-name-sans-extension
				 todo-current-todo-file) ".toda")
		      ;; Otherwise, jump to the category in the todo file.
		      todo-current-todo-file)))
	   (cat+file (unless cat
		       (todo-read-category "Jump to category: "
					    (if archive 'archive) file)))
	   (category (or cat (car cat+file))))
      (unless cat (setq file0 (cdr cat+file)))
      (with-current-buffer (find-file-noselect file0 'nowarn)
        (when goto-archive (todo-archive-mode))
        (set-window-buffer (selected-window)
                           (set-buffer (find-buffer-visiting file0)))
        (if transient-mark-mode (deactivate-mark))
        (unless todo-global-current-todo-file
          (setq todo-global-current-todo-file todo-current-todo-file))
        (todo-category-number category)
        (todo-category-select)
        (goto-char (point-min))
	(if (bound-and-true-p hl-line-mode) (hl-line-highlight))
        (when (and todo-add-item-if-new-category
                   ;; A new category is empty on creation.
                   (seq-every-p #'zerop (cdr (assoc category todo-categories))))
          (todo-insert-item--basic))))))