Previous: Sorting of agenda items, Up: Presentation and Sorting [Contents][Index]
Agenda built-in or customized commands are statically defined. Agenda filters and limits provide two ways of dynamically narrowing down the list of agenda entries: filters and limits. Filters only act on the display of the items, while limits take effect before the list of agenda entries is built. Filters are more often used interactively, while limits are mostly useful when defined as local variables within custom agenda commands.
org-agenda-filter-by-tag
)Filter the agenda view with respect to a tag and/or effort estimates. The difference between this and a custom agenda command is that filtering is very fast, so that you can switch quickly between different filters without having to recreate the agenda.98
You are prompted for a tag selection letter; SPC means any tag at all. Pressing TAB at that prompt offers completion to select a tag, including any tags that do not have a selection character. The command then hides all entries that do not contain or inherit this tag. When called with prefix argument, remove the entries that do have the tag. A second / at the prompt turns off the filter and shows any hidden entries. Pressing + or - switches between filtering and excluding the next tag.
Org also supports automatic, context-aware tag filtering. If the
variable org-agenda-auto-exclude-function
is set to
a user-defined function, that function can decide which tags
should be excluded from the agenda automatically. Once this is
set, the / command then accepts RET as
a sub-option key and runs the auto exclusion logic. For example,
let’s say you use a ‘Net’ tag to identify tasks which need
network access, an ‘Errand’ tag for errands in town, and a ‘Call’
tag for making phone calls. You could auto-exclude these tags
based on the availability of the Internet, and outside of
business hours, with something like this:
(defun org-my-auto-exclude-function (tag) (and (cond ((string= tag "Net") (/= 0 (call-process "/sbin/ping" nil nil nil "-c1" "-q" "-t1" "mail.gnu.org"))) ((or (string= tag "Errand") (string= tag "Call")) (let ((hour (nth 2 (decode-time)))) (or (< hour 8) (> hour 21))))) (concat "-" tag))) (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
org-agenda-filter-by-category
)Filter the current agenda view with respect to the category of the item at point. Pressing < another time removes this filter. When called with a prefix argument exclude the category of the item at point from the agenda.
You can add a filter preset in custom agenda commands through the
option org-agenda-category-filter-preset
. See Setting options.
org-agenda-filter-by-top-headline
)Filter the current agenda view and only display the siblings and the parent headline of the one at point.
org-agenda-filter-by-regexp
)Filter the agenda view by a regular expression: only show agenda entries matching the regular expression the user entered. When called with a prefix argument, it filters out entries matching the regexp. Called in a regexp-filtered agenda view, remove the filter, unless there are two universal prefix arguments, in which case filters are cumulated.
You can add a filter preset in custom agenda commands through the
option org-agenda-regexp-filter-preset
. See Setting options.
org-agenda-filter-by-effort
)Filter the agenda view with respect to effort estimates. You first need to set up allowed efforts globally, for example
(setq org-global-properties '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
You can then filter for an effort by first typing an operator,
one of <, > and =, and then the
one-digit index of an effort estimate in your array of allowed
values, where 0 means the 10th value. The filter then
restricts to entries with effort smaller-or-equal, equal, or
larger-or-equal than the selected value. For application of the
operator, entries without a defined effort are treated according
to the value of org-sort-agenda-noeffort-is-high
.
When called with a prefix argument, it removes entries matching the condition. With two universal prefix arguments, it clears effort filters, which can be accumulated.
You can add a filter preset in custom agenda commands through the
option org-agenda-effort-filter-preset
. See Setting options.
org-agenda-filter-remove-all
)Remove all filters in the current agenda view.
Here is a list of options that you can set, either globally, or locally in your custom agenda views (see Custom Agenda Views).
org-agenda-max-entries
Limit the number of entries.
org-agenda-max-effort
Limit the duration of accumulated efforts (as minutes).
org-agenda-max-todos
Limit the number of entries with TODO keywords.
org-agenda-max-tags
Limit the number of tagged entries.
When set to a positive integer, each option excludes entries from
other categories: for example, ‘(setq org-agenda-max-effort 100)’
limits the agenda to 100 minutes of effort and exclude any entry that
has no effort property. If you want to include entries with no effort
property, use a negative value for org-agenda-max-effort
. One
useful setup is to use org-agenda-max-entries
locally in a custom
command. For example, this custom command displays the next five
entries with a ‘NEXT’ TODO keyword.
(setq org-agenda-custom-commands '(("n" todo "NEXT" ((org-agenda-max-entries 5)))))
Once you mark one of these five entry as DONE, rebuilding the agenda will again the next five entries again, including the first entry that was excluded so far.
You can also dynamically set temporary limits, which are lost when rebuilding the agenda:
org-agenda-limit-interactively
)This prompts for the type of limit to apply and its value.
Custom commands can preset a filter by binding the variable
org-agenda-tag-filter-preset
as an option. This filter is then
applied to the view and persists as a basic filter through refreshes
and more secondary filtering. The filter is a global property of the
entire agenda view—in a block agenda, you should only set this in
the global options section, not in the section of an individual block.
Previous: Sorting of agenda items, Up: Presentation and Sorting [Contents][Index]