Function: org-agenda
org-agenda is an autoloaded, interactive and byte-compiled function
defined in org-agenda.el.gz.
Signature
(org-agenda &optional ARG KEYS RESTRICTION)
Documentation
Dispatch agenda commands to collect entries to the agenda buffer.
Prompts for a command to execute. Any prefix arg will be passed on to the selected command. The default selections are:
a Call org-agenda-list to display the agenda for current day or week.
t Call org-todo-list to display the global todo list.
T Call org-todo-list to display the global todo list, select only
entries with a specific TODO keyword (the user gets a prompt).
m Call org-tags-view to display headlines with tags matching
a condition (the user is prompted for the condition).
M Like m, but select only TODO entries, no ordinary headlines.
e Export views to associated files.
s Search entries for keywords.
S Search entries for keywords, only with TODO keywords.
/ Multi occur across all agenda files and also files listed
in org-agenda-text-search-extra-files.
< Restrict agenda commands to buffer, subtree, or region.
Press several times to get the desired effect.
> Remove a previous restriction.
# List "stuck" projects.
! Configure what "stuck" means.
C Configure custom agenda commands.
More commands can be added by configuring the variable
org-agenda-custom-commands. In particular, specific tags and TODO keyword
searches can be pre-defined in this way.
If the current buffer is in Org mode and visiting a file, you can also
first press < once to indicate that the agenda should be temporarily
(until the next use of M-x org-agenda (org-agenda)) restricted to the current file.
Pressing < twice means to restrict to the current subtree or region
(if active).
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/org/org-agenda.el.gz
;;;###autoload
(defun org-agenda (&optional arg keys restriction)
"Dispatch agenda commands to collect entries to the agenda buffer.
Prompts for a command to execute. Any prefix arg will be passed
on to the selected command. The default selections are:
a Call `org-agenda-list' to display the agenda for current day or week.
t Call `org-todo-list' to display the global todo list.
T Call `org-todo-list' to display the global todo list, select only
entries with a specific TODO keyword (the user gets a prompt).
m Call `org-tags-view' to display headlines with tags matching
a condition (the user is prompted for the condition).
M Like `m', but select only TODO entries, no ordinary headlines.
e Export views to associated files.
s Search entries for keywords.
S Search entries for keywords, only with TODO keywords.
/ Multi occur across all agenda files and also files listed
in `org-agenda-text-search-extra-files'.
< Restrict agenda commands to buffer, subtree, or region.
Press several times to get the desired effect.
> Remove a previous restriction.
# List \"stuck\" projects.
! Configure what \"stuck\" means.
C Configure custom agenda commands.
More commands can be added by configuring the variable
`org-agenda-custom-commands'. In particular, specific tags and TODO keyword
searches can be pre-defined in this way.
If the current buffer is in Org mode and visiting a file, you can also
first press `<' once to indicate that the agenda should be temporarily
\(until the next use of `\\[org-agenda]') restricted to the current file.
Pressing `<' twice means to restrict to the current subtree or region
\(if active)."
(interactive "P")
(catch 'exit
(let* ((org-keys keys)
(prefix-descriptions nil)
(org-agenda-buffer-name org-agenda-buffer-name)
(org-agenda-window-setup (if (equal (buffer-name)
org-agenda-buffer-name)
'current-window
org-agenda-window-setup))
(org-agenda-custom-commands-orig org-agenda-custom-commands)
(org-agenda-custom-commands
;; normalize different versions
(delq nil
(mapcar
(lambda (x)
(cond ((stringp (cdr x))
(push x prefix-descriptions)
nil)
((stringp (nth 1 x)) x)
((not (nth 1 x)) (cons (car x) (cons "" (cddr x))))
(t (cons (car x) (cons "" (cdr x))))))
org-agenda-custom-commands)))
(org-agenda-custom-commands
(org-contextualize-keys
org-agenda-custom-commands org-agenda-custom-commands-contexts))
;; (buf (current-buffer))
(bfn (buffer-file-name (buffer-base-buffer)))
entry type org-match lprops ans) ;; key
;; Turn off restriction unless there is an overriding one,
(unless org-agenda-overriding-restriction
(unless org-agenda-keep-restricted-file-list
;; There is a request to keep the file list in place
(put 'org-agenda-files 'org-restrict nil))
(setq org-agenda-restrict nil)
(move-marker org-agenda-restrict-begin nil)
(move-marker org-agenda-restrict-end nil))
(unless org-keys
(setq ans (org-agenda-get-restriction-and-command prefix-descriptions)
org-keys (car ans)
restriction (cdr ans)))
;; If we have sticky agenda buffers, set a name for the buffer,
;; depending on the invoking keys. The user may still set this
;; as a command option, which will overwrite what we do here.
(when org-agenda-sticky
(setq org-agenda-buffer-name
(format "*Org Agenda(%s)*" org-keys)))
;; Establish the restriction, if any
(when (and (not org-agenda-overriding-restriction) restriction)
(put 'org-agenda-files 'org-restrict (list bfn))
(cond
((eq restriction 'region)
(setq org-agenda-restrict (current-buffer))
(move-marker org-agenda-restrict-begin (region-beginning))
(move-marker org-agenda-restrict-end (region-end)))
((eq restriction 'subtree)
(save-excursion
(setq org-agenda-restrict (current-buffer))
(org-back-to-heading t)
(move-marker org-agenda-restrict-begin (point))
(move-marker org-agenda-restrict-end
(progn (org-end-of-subtree t)))))
((eq restriction 'buffer)
(if (not (buffer-narrowed-p))
(setq org-agenda-restrict t)
(setq org-agenda-restrict (current-buffer))
(move-marker org-agenda-restrict-begin (point-min))
(move-marker org-agenda-restrict-end (point-max))))))
;; For example the todo list should not need it (but does...)
(cond
((setq entry (assoc org-keys org-agenda-custom-commands))
(if (or (symbolp (nth 2 entry)) (functionp (nth 2 entry)))
(progn
;; FIXME: Is (nth 3 entry) supposed to have access (via dynvars)
;; to some of the local variables? There's no doc about
;; that for `org-agenda-custom-commands'.
(setq type (nth 2 entry) org-match (eval (nth 3 entry) t)
lprops (nth 4 entry))
(when org-agenda-sticky
(setq org-agenda-buffer-name
(or (and (stringp org-match) (format "*Org Agenda(%s:%s)*" org-keys org-match))
(format "*Org Agenda(%s)*" org-keys))))
(cl-progv
(mapcar #'car lprops)
(mapcar (lambda (binding) (eval (cadr binding) t)) lprops)
(pcase type
(`agenda
(org-agenda-list arg))
(`agenda*
(org-agenda-list arg nil nil t))
(`alltodo
(org-todo-list arg))
(`search
(org-search-view arg org-match nil))
(`stuck
(org-agenda-list-stuck-projects arg))
(`tags
(org-tags-view arg org-match))
(`tags-todo
(org-tags-view '(4) org-match))
(`todo
(org-todo-list org-match))
(`tags-tree
(org-check-for-org-mode)
(org-match-sparse-tree arg org-match))
(`todo-tree
(org-check-for-org-mode)
(org-occur (concat "^" org-outline-regexp "[ \t]*"
(regexp-quote org-match) "\\>")))
(`occur-tree
(org-check-for-org-mode)
(org-occur org-match))
((pred functionp)
(funcall type org-match))
;; FIXME: Will signal an error since it's not `functionp'!
((pred fboundp) (funcall type org-match))
(_ (user-error "Invalid custom agenda command type %s" type))))
(let ((inhibit-read-only t))
(add-text-properties (point-min) (point-max)
`(org-lprops ,lprops))))
(org-agenda-run-series (nth 1 entry) (cddr entry))))
((equal org-keys "C")
(setq org-agenda-custom-commands org-agenda-custom-commands-orig)
(customize-variable 'org-agenda-custom-commands))
((equal org-keys "a") (call-interactively 'org-agenda-list))
((equal org-keys "s") (call-interactively 'org-search-view))
((equal org-keys "S") (org-call-with-arg 'org-search-view (or arg '(4))))
((equal org-keys "t") (call-interactively 'org-todo-list))
((equal org-keys "T") (org-call-with-arg 'org-todo-list (or arg '(4))))
((equal org-keys "m") (call-interactively 'org-tags-view))
((equal org-keys "M") (org-call-with-arg 'org-tags-view (or arg '(4))))
((equal org-keys "e") (call-interactively 'org-store-agenda-views))
((equal org-keys "?") (org-tags-view nil "+FLAGGED")
(add-hook
'post-command-hook
(lambda ()
(unless (current-message)
(let* ((m (org-agenda-get-any-marker))
(note (and m (org-entry-get m "THEFLAGGINGNOTE"))))
(when note
(message "FLAGGING-NOTE ([?] for more info): %s"
(org-add-props
(replace-regexp-in-string
"\\\\n" "//"
(copy-sequence note))
nil 'face 'org-warning))))))
t t))
((equal org-keys "#") (call-interactively 'org-agenda-list-stuck-projects))
((equal org-keys "/") (call-interactively 'org-occur-in-agenda-files))
((equal org-keys "!") (customize-variable 'org-stuck-projects))
(t (user-error "Invalid agenda key"))))))