paulwicking/org-timeblock

#+TITLE: org-timeblock

Schedule your day visually, using [[https://en.wikipedia.org/wiki/Timeblocking][timeblocking technique]] inside Emacs.

• Contents

• [[#screenshots][Screenshots]]
• [[#screencast][Screencast]]
• [[#description][Description]]
• [[#installation][Installation]]
• [[#usage][Usage]]
• [[#customization][Customization]]

• Screenshots
  :PROPERTIES:
  :CUSTOM_ID: screenshots
  :END:

org-timeblock-mode buffer:

[[file:screenshots/org-timeblock-mode.png]]

You can press [t] to toggle the display of org-timeblock-list-mode
buffer. Foreground colors for timeblocks are generated randomly, but
you can assign specific background and foreground colors in
customizable variable org-timeblock-tag-colors:

[[file:screenshots/org-timeblock-with-list-mode.png]]

• Screencast
  :PROPERTIES:
  :CUSTOM_ID: screencast
  :END:

[[https://youtu.be/lVV9gVp5nxU]]

• Description
  :PROPERTIES:
  :CUSTOM_ID: description
  :END:

The builtin orgmode package for viewing tasks or events for a
particular day, org-agenda, does not help you to quickly understand,
where, for example, you have free time in your day or where you have
overlapping tasks. Just a list of tasks is not sufficient. This
package is created to fix this problem and provide some of the
functionality that modern calendars provide.

There are two major modes provided by the package:

• org-timeblock-mode. Displays visual schedule (timeblocks) of org
  tasks that are scheduled or have an active timestamp in their body
  (orgmode events) for selected day (Currently, only day view is available). Available commands:

  • org-timeblock-day-earlier/later [C-/]
  • org-timeblock-set-duration [d]
  • org-timeblock-reschedule [s]
  • org-timeblock-new-task [+]
  • org-timeblock-toggle-timeblock-list [t]
  • org-timeblock-todo [1]
  • org-timeblock-done [5]
  • org-timeblock-switch-view [v]
  • org-timeblock-jump-to-day [j]

• org-timeblock-list-mode. Displays a list of org tasks that are
  scheduled or orgmode events for selected day. It's sort of like a
  light org-agenda. The tasks can be sorted via SCHEDULED org
  property or manually placed by user via commands
  org-timeblock-list-drag-line-forward/backward [M-/]. The
  order can be saved in a cache file via org-timeblock-list-save
  [C-s] command. The sorting algorithm can be changed via
  org-timeblock-list-toggle-sort-function [S] command.

  • org-timeblock-list-schedule [s]
  • org-timeblock-list-set-duration [d]
  • org-timeblock-todo [1]
  • org-timeblock-done [5]
  • org-timeblock-list-drag-line-forward/backward [M-/]
  • org-timeblock-list-toggle-sort-function [S]
  • org-timeblock-list-toggle-timeblock [t]

• Installation
  :PROPERTIES:
  :CUSTOM_ID: installation
  :END:

Requirements:

• Emacs 28.1 (or higher)
• SVG support in your Emacs build
• org 9.0 (or higher)
• org-ql 0.7 (or higher)

** package-vc-install (Emacs 29)

If you use Emacs 29, you can install the package via

M-x package-vc-install RET https://github.com/ichernyshovvv/org-timeblock/ RET

** Guix

If you use Guix, you can install the package from [[https://git.sr.ht/~sokolov/channel][this]] channel.

1. To add the channel, add this to the list of channels in channels.scm:

#+begin_src scheme
(channel
(name 'sklv)
(url "https://git.sr.ht/~sokolov/channel"))
#+end_src

2. Then, run guix pull.

3. Now you can install the package.

** Quelpa

1. Install quelpa-use-package (which can be installed directly from MELPA).
2. Add this form to your init file:

#+begin_src elisp
(use-package org-timeblock
:quelpa (org-timeblock :fetcher github :repo "ichernyshovvv/org-timeblock"))
#+end_src

** Manual

1. Run M-x package-install org-ql
2. git clone https://github.com/ichernyshovvv/org-timeblock
3. Add the path of the downloaded folder to load-path somewhere in your Emacs
   config:

#+begin_src elisp
(add-to-list 'load-path "path/to/org-timeblock/")
#+end_src

• Usage
  :PROPERTIES:
  :CUSTOM_ID: usage
  :END:

To enter org-timeblock-list-mode, run M-x org-timeblock-list. To
enter org-timeblock-mode, run M-x org-timeblock

For both modes, the default date is today. All the tasks and events
are searched in (org-agenda-files). You can change the displayed
date via the following commands:

• org-timeblock-day-later [C-]
• org-timeblock-day-earlier [C-]
• org-timeblock-jump-to-day [j]

To navigate between tasks/blocks, use these commands:

• org-timeblock-list-mode
  • org-timeblock-list-previous-line []
  • org-timeblock-list-next-line []
• org-timeblock-mode
  • org-timeblock-forward-block []
  • org-timeblock-bacward-block []

In both modes, you can navigate via mouse clicks to select an entry or
a block.

To reschedule or change the duration of a task at point, use these
commands:

• org-timeblock-list-mode
  • org-timeblock-list-schedule [s]
  • org-timeblock-list-set-duration [d]
• org-timeblock-mode
  • org-timeblock-schedule [s]
  • org-timeblock-set-duration [d]

• Customization
  :PROPERTIES:
  :CUSTOM_ID: customization
  :END:

M-x customize-group org-timeblock to see available customizable variables.