#+TITLE: org-treescope.el

*** This repo has migrated to GitLab https://gitlab.com/mtekman/org-treescope.el ****** (The copy here is archived. Please see the above link for the latest developments)

#+HTML:

NOTE: HTML for the GitHub renderer, courtesy of alphapapa for the template.

#+HTML:

Many people place the power of org-mode into the reports provided by org-agenda, which filters and summarizes org entries by tags, todo states, priorities and tags.

I don't do that. My mind is simple. I like trees. Trees are easy. You have one org mode file and you filter it for what you need, whether it's a quick glance at what you did last week or a peek at what you're currently working on. This package provides an interactive filter window using the excellent [[https://github.com/alphapapa/org-ql][org-ql]] library as well as the calendar window from =calendar.el= to help with defining the scope of the filtering query.

#+HTML:

** Installation

#+begin_src elisp (use-package org-treescope :custom (org-treescope-cyclestates-todo '(nil ("TODO") ("WAITING" "DONE"))) (org-treescope-cyclestates-priority '(nil ("A" "B" "C") ("D"))) :bind (("C-c M-t" . org-treescope))) #+end_src

** Usage

Once =org-treescope= is run, a minor mode is launched with the following controls which are designed to not interfere with =calendar-mode=.

**** Time Range Shift

 | Binding      | Action                                              |
 |--------------+-----------------------------------------------------|
 | =left/right=   | Shift current range one day backward / forward      |
 | =up/down=      | Shift current range one week backward / forward     |
 | =C-left/right= | Move lowerbound of range one day backward / forward |
 | =M-left/right= | Move upperbound of range one day backward / forward |

**** Time Range Flank

 | Binding        | Action                                  |
 |----------------+-----------------------------------------|
 | =C-M-left/right= | Show all dates before/after centre date |
 | =C-M-down=       | Reset to range in previous section      |

**** Cycling States

 | Binding   | Action                                                          |
 |-----------+-----------------------------------------------------------------|
 | =C-up/down= | Cycle through user-defined groups of =TODO= states                |
 | =M-up/down= | Cycle through user-defined groups of =PRIORITY= ranges            |
 | =t=         | Cycle through time modes =TIMESTAMP=, =SCHEDULED=, =DEADLINE=, =CLOSED= |

** Customisation

The user should check that the below scope types are set to reasonable ranges for that file.

**** Scope Types

 Currently supported types are =TODO= groups, =PRIORITY= ranges, and =TIMESTAMP= types. Currently these are set to:

 | Main Customisable Variables  | Current Setting                     | Info                              |
 |------------------------------+-------------------------------------+-----------------------------------|
 | =org-treescope-cyclestates-todo=     | =DONE=, =TODO= =DOING=, =TODO= =DONE= =WAITING= | Any number of elements in a group |
 | =org-treescope-cyclestates-priority= | =A=, =A= =C=, =D=                           | Any number of elements in a group |
 | =org-treescope-cyclestates-time=     | =ts=, =scheduled=, =deadline=, =closed=     | [[https://github.com/alphapapa/org-ql#datetime-predicates][Other predicates]] can be added     |

 These can be customised to specify different groups/pairs that might be more useful to the user.

**** Faces

 The faces used within the calendar can also be customised, and the user should see the =defface= definitions used in the source.

 | Variable                    | Info                                                                                 |
 |-----------------------------+--------------------------------------------------------------------------------------|
 | =org-treescope-faces-range=  | The face used to specify all dates within the range except the centre midpoint date. |
 | =org-treescope-faces-midday= | The face used only by the centre midpoint date.                                      |