Variable: org-agenda-custom-commands

org-agenda-custom-commands is a customizable variable defined in org-agenda.el.gz.

Value

(("n" "Agenda and all TODOs"
  ((agenda "")
   (alltodo ""))))

Documentation

Custom commands for the agenda.

These commands will be offered on the splash screen displayed by the agenda dispatcher M-x org-agenda (org-agenda). Each entry is a list like this:

   (key desc type match settings files)

key The key (one or more characters as a string) to be associated
         with the command.
desc A description of the command. When omitted or nil, a default
         description is built using MATCH.
type The command type, any of the following symbols:
          agenda The daily/weekly agenda.
          agenda* Appointments for current week/day.
          todo Entries with a specific TODO keyword, in all agenda files.
          search Entries containing search words entry or headline.
          tags Tags/Property/TODO match in all agenda files.
          tags-todo Tags/P/T match in all agenda files, TODO entries only.
          todo-tree Sparse tree of specific TODO keyword in *current* file.
          tags-tree Sparse tree with all tags matches in *current* file.
          occur-tree Occur sparse tree for *current* file.
          alltodo The global TODO list.
          stuck Stuck projects.
          ... A user-defined function.
match What to search for:
          - a single keyword for TODO keyword searches
          - a tags/property/todo match expression for searches
          - a word search expression for text searches.
          - a regular expression for occur searches
          For all other commands, this should be the empty string.
settings A list of option settings, similar to that in a let form, so like
          this: ((opt1 val1) (opt2 val2) ...). The values will be
          evaluated at the moment of execution, so quote them when needed.
files A list of files to write the produced agenda buffer to with
          the command org-store-agenda-views.
          If a file name ends in ".html", an HTML version of the buffer
          is written out. If it ends in ".ps", a PostScript version is
          produced. Otherwise, only the plain text is written to the file.

You can also define a set of commands, to create a composite agenda buffer. In this case, an entry looks like this:

  (key desc (cmd1 cmd2 ...) general-settings-for-whole-set files)

where

desc A description string to be displayed in the dispatcher menu.
cmd An agenda command, similar to the above. However, tree commands
       are not allowed. Valid commands for a set are:
       (agenda "" settings)
       (agenda* "" settings)
       (alltodo "" settings)
       (stuck "" settings)
       (todo "match" settings files)
       (search "match" settings files)
       (tags "match" settings files)
       (tags-todo "match" settings files)

Each command can carry a list of options, and another set of options can be given for the whole set of commands. Individual command options take precedence over the general options.

When using several characters as key to a command, the first characters are prefix commands. For the dispatcher to display useful information, you should provide a description for the prefix, like

 (setq org-agenda-custom-commands
   '(("h" . "HOME + Name tag searches") ; describe prefix "h"
     ("hl" tags "+HOME+Lisa")
     ("hp" tags "+HOME+Peter")
     ("hk" tags "+HOME+Kim")))

See also Info node (org) Custom Agenda Views.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-agenda.el.gz
(defcustom org-agenda-custom-commands
  '(("n" "Agenda and all TODOs" ((agenda "") (alltodo ""))))
  "Custom commands for the agenda.
\\<org-mode-map>
These commands will be offered on the splash screen displayed by the
agenda dispatcher `\\[org-agenda]'.  Each entry is a list like this:

   (key desc type match settings files)

key      The key (one or more characters as a string) to be associated
         with the command.
desc     A description of the command.  When omitted or nil, a default
         description is built using MATCH.
type     The command type, any of the following symbols:
          agenda      The daily/weekly agenda.
          agenda*     Appointments for current week/day.
          todo        Entries with a specific TODO keyword, in all agenda files.
          search      Entries containing search words entry or headline.
          tags        Tags/Property/TODO match in all agenda files.
          tags-todo   Tags/P/T match in all agenda files, TODO entries only.
          todo-tree   Sparse tree of specific TODO keyword in *current* file.
          tags-tree   Sparse tree with all tags matches in *current* file.
          occur-tree  Occur sparse tree for *current* file.
          alltodo     The global TODO list.
          stuck       Stuck projects.
          ...         A user-defined function.
match    What to search for:
          - a single keyword for TODO keyword searches
          - a tags/property/todo match expression for searches
          - a word search expression for text searches.
          - a regular expression for occur searches
          For all other commands, this should be the empty string.
settings  A list of option settings, similar to that in a let form, so like
          this: ((opt1 val1) (opt2 val2) ...).   The values will be
          evaluated at the moment of execution, so quote them when needed.
files     A list of files to write the produced agenda buffer to with
          the command `org-store-agenda-views'.
          If a file name ends in \".html\", an HTML version of the buffer
          is written out.  If it ends in \".ps\", a PostScript version is
          produced.  Otherwise, only the plain text is written to the file.

You can also define a set of commands, to create a composite agenda buffer.
In this case, an entry looks like this:

  (key desc (cmd1 cmd2 ...) general-settings-for-whole-set files)

where

desc   A description string to be displayed in the dispatcher menu.
cmd    An agenda command, similar to the above.  However, tree commands
       are not allowed.  Valid commands for a set are:
       (agenda \"\" settings)
       (agenda* \"\" settings)
       (alltodo \"\" settings)
       (stuck \"\" settings)
       (todo \"match\" settings files)
       (search \"match\" settings files)
       (tags \"match\" settings files)
       (tags-todo \"match\" settings files)

Each command can carry a list of options, and another set of options can be
given for the whole set of commands.  Individual command options take
precedence over the general options.

When using several characters as key to a command, the first characters
are prefix commands.  For the dispatcher to display useful information, you
should provide a description for the prefix, like

 (setq org-agenda-custom-commands
   \\='((\"h\" . \"HOME + Name tag searches\") ; describe prefix \"h\"
     (\"hl\" tags \"+HOME+Lisa\")
     (\"hp\" tags \"+HOME+Peter\")
     (\"hk\" tags \"+HOME+Kim\")))

See also Info node `(org) Custom Agenda Views'."
  :group 'org-agenda-custom-commands
  :type `(repeat
	  (choice :value ("x" "Describe command here" tags "" nil)
		  (list :tag "Single command"
			(string :tag "Access Key(s) ")
			(option (string :tag "Description"))
			(choice
			 (const :tag "Agenda" agenda)
			 (const :tag "TODO list" alltodo)
			 (const :tag "Search words" search)
			 (const :tag "Stuck projects" stuck)
			 (const :tag "Tags/Property match (all agenda files)" tags)
			 (const :tag "Tags/Property match of TODO entries (all agenda files)" tags-todo)
			 (const :tag "TODO keyword search (all agenda files)" todo)
			 (const :tag "Tags sparse tree (current buffer)" tags-tree)
			 (const :tag "TODO keyword tree (current buffer)" todo-tree)
			 (const :tag "Occur tree (current buffer)" occur-tree)
			 (sexp :tag "Other, user-defined function"))
			(string :tag "Match (only for some commands)")
			,org-agenda-custom-commands-local-options
			(option (repeat :tag "Export" (file :tag "Export to"))))
		  (list :tag "Command series, all agenda files"
			(string :tag "Access Key(s)")
			(string :tag "Description  ")
			(repeat :tag "Component"
				(choice
				 (list :tag "Agenda"
				       (const :format "" agenda)
				       (const :tag "" :format "" "")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "TODO list (all keywords)"
				       (const :format "" alltodo)
				       (const :tag "" :format "" "")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Search words"
				       (const :format "" search)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Stuck projects"
				       (const :format "" stuck)
				       (const :tag "" :format "" "")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Tags/Property match (all agenda files)"
				       (const :format "" tags)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Tags/Property match of TODO entries (all agenda files)"
				       (const :format "" tags-todo)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "TODO keyword search"
				       (const :format "" todo)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Other, user-defined function"
				       (symbol :tag "function")
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)))

			(repeat :tag "Settings for entire command set"
				(list (variable :tag "Any variable")
				      (sexp :tag "Value")))
			(option (repeat :tag "Export" (file :tag "Export to"))))
		  (cons :tag "Prefix key documentation"
			(string :tag "Access Key(s)")
			(string :tag "Description  ")))))