### Time ++ **A [todo.txt manager](https://github.com/todotxt/todotxt/), time tracker, timer, stopwatch, pomodoro, and alarms [gnome-shell extension](https://extensions.gnome.org/about/).**
---
Table of Contents * [Installation](#installation) * [Warnings](#warnings) * [Translations](#translations) * [Sections](#sections) * [Fullscreen Interface](#fullscreen-interface) * [Todo.txt Manager](#todotxt-manager) * [Todo.txt Syntax](#todotxt-syntax) * [Todo.txt Extensions](#todotxt-extensions) * [Time Tracker](#time-tracker) * [DBus API](#dbus-api) * [Custom Theme Support](#custom-theme-support) * [Keyboard Shortcuts](#keyboard-shortcuts) * [Preview](#preview)
--- ### Installation 1. Download the extension: * [The latest version](https://github.com/zagortenay333/timepp__gnome/archive/master.zip) supports `gnome-shell 3.34` (`master-branch`). * For older versions go to [releases](../../releases). 2. Extract and rename the downloaded folder to `timepp@zagortenay333` and move it into `/home/YOUR_USER_NAME/.local/share/gnome-shell/extensions/`. 3. Restart your desktop shell by typing Alt+F2, then r, then Enter. 4. Enable the extension via the `gnome tweak tool` program. --- ### Warnings :bangbang: 1. This extension is in very low-maintenance mode (don't make feature requests). 2. In case of a bug, this extension can freeze your OS, which could require significant effort on your part to solve. 3. All gnome-shell extensions get disabled in the lock screen. Alarms, timers, etc will not work. --- ### Translations If you want to help out with translations, check out the instructions in the [po_files](data/po_files) dir. --- ### Sections This is a modular extension consisting of several sections (timer, stopwatch, alarms..) Each section can open as a separate menu when it's icon is clicked, or it can appear together with other sections in one menu. Individual sections can be disabled if you don't need them. Right-clicking on the panel icons will open a context section with some useful links. --- ### Fullscreen Interface This extension has a fullscreen interface, which can be used to control a corresponding section as well as replace regular notifications. The interface has multi-monitor support, and it can be opened _(and brought into focus)_ via a keyboard shortcut. --- ### Todo.txt Manager Some of the features of the todo.txt manager are: * Kanban boards. * Fuzzy task searching. * Filtering by context, project, priority, custom fuzzy filters... * Toggling a filter on/off by clicking on a priority, context, or proj in a task. * Support for multiple todo files and corresponding done files and csv dirs. * Compound sorting by priority, due date, completion date, creation date, etc... * Fuzzy autocompletion for contexts and projects when inline editing a task. * Autoupdating when the todo.txt file changes. * Deleting all completed tasks and optionally storing them into a done.txt file. * Switching between different views via keyboard shortcuts. * Browse your todo time tracker data in a fullscreen view. --- ### Todo.txt Syntax * The todo.txt format is specified here: https://github.com/todotxt/todo.txt * In various places throughout this extension (todo.txt, alarms, timer) there is support for a simple markup language: * Simple text formatting: ``` ` escape other markdown `` monospace and escape other markdown * bold ** italic *** bold with a red bg __ italic ___ underscore ~~ strikethrough # xx-large ## x-large ### large For example, *bold*, and ##extra large##, and ``monospaced``, and ***this __one__ is nested***, etc... ``` * File paths and web links: ``` https://www.google.com www.google.com /home/user/Documents ~/Documents ~/Documents/img.png ~/Documents/file\ with\ spaces.png ``` * Multiple lines can be used by adding `\n` to represent a newline: ``` (A) A task with\nmultiline\n@support \n +asdf ``` --- ### Todo.txt Extensions A todo.txt extension is just a `key:val` string you type into your todo.txt file. The following extensions are supported:
kan:kan_string Used to specify kanban boards.
Multiple kan boards can be specified by writing multiple kan extensions into the todo.txt file

The format of the extension is: kan:[*]name|column1[|column2|...]

  • The optional * indicates whether the kanban board is active.
  • Each column is either:
    • a comma separated list of todo.txt priorities, contexts, projects.
    • a string indicating a 'kitchen-sink' column.
    • the char '$' indicating a 'kitchen-sink' column with no title
  • Tasks are split into columns based on whether or not they have one or more properties specified in a column.
  • A 'kitchen-sink' column is one into which any task goes.
  • The string '(_)' can be used to refer to completed tasks and tasks with no priorities.
  • The order of the columns matters.
    If a task can go into multiple columns, it will be added to the leftmost one.
    The position of a 'kitchen-sink' column can affect the sorting a lot.
  • Columns that start with '_' (underscore) are collapsed (visually minimized).
Examples:
  • kan:*main|(A),(B),(C)|(D),(E),(F)|(G)
  • kan:other_project|_(A)|_(B)|(C)|_(D)|(E)|(F)|(G)
  • kan:stuff|(D),@stuf,+my_project|everything\ else
  • kan:a_and_no_prios|(A)|(_)
  • kan:kitchen_sink_with_title|some_title_maybe_with\ spaces
  • kan:no_title|$
  • kan:column_order_matters|$|(A)
tracker_id:string Used to identify a task when starting/stopping the time-tracker via the dbus cli or using pomodoro.
Multiple tasks can have the same tracker_id.
pin:1 Pins a task. A task that is pinned is always visible no matter what filters are on. Also, one can sort pinned tasks (for example, always on top.)
pri:A-Z Used to restore the priority of a completed task when it gets reopend.
h:1 This extension disables all other extensions except the kan extension.

Hides a task.
Among other things, can be used to populate the todo manager
with context/project keywords for autocompletion.
t|defer:yyyy-mm-dd Defers opening a task until specified date.
due|DUE:yyyy-mm-dd Sets a due date on a task.
rec:recurrence_string This extension is incompatible with the due and defer extensions.

Used to automatically reopen a task after a given amount of time.

Each time a task recurs, it's creation date is updated.
If a task is already open on the date of the recursion, it's creation date will be updated anyway.

The recurrence_string can be in one of 3 diff forms:
    (n=natural number, d=days, w=weeks, m=months)

  1. rec:n(d|w)
    This means that the task will recur n days/weeks after the creation date.
    - This rec type requires a creation date.
    Examples:
    • x 2000-01-01 2000-01-01 rec:12d means that the task will reopen
      every 12 days starting from 2000-01-01. After 12 days it will look like
      2000-01-13 rec:12d, and 12 days after that it will look like
      2000-01-25 rec:12d, and so on...

  2. rec:x-n(d|w)
    This means that the task will recur n days/weeks after the completion date.
    - This rec type requires a completion date if the task is complete.
    Examples:
    • x 2000-01-01 rec:x-12d recurs 12 days after 2000-01-01.
    • (A) rec:x-3w recurs 3 weeks after completion date.

  3. rec:nd-nm
    This means that the task will recur on the n-th day of every n-th month starting
    from the month of creation.
    - This rec type requires a creation date.
    - 'Month of creation' here refers to the month written into the todo.txt file.
    - If a month doesn't have the particular n-th day, the last day of that month will be used instead.
    Examples:
    • (A) 2000-01-01 rec:12d-1m recurs on the 12th day of each month.
    • (A) 2000-01-01 rec:1d-1m recurs on the first day of each month.
    • (A) 2000-01-01 rec:31d-1m recurs on the last day of each month.
    • (A) 2000-01-01 rec:64d-1m also recurs on the last day of each month.
    • (A) 2000-01-01 rec:29d-1m recurs on the 29th day of each month, and in
      the case of February, on the 28th if it doesn't have 29 days.
    • (A) 2000-02-02 rec:12d-2m recurs on the 12th day every 2 months starting from February.
      If the actual current date is 2000-02-08, the task recurs on 2000-02-12.
      If the actual current date is 2000-02-16, the task recurs on 2000-04-12.
    • (A) 2000-01-01 rec:1d-12m recurs on the first day of every year.
    • (A) 2000-02-01 rec:29d-24m recurs on the last day of February every 2 years starting from 2000.
--- ### Time Tracker You can start time tracking by pressing the play button on a todo card. When you do that, the task as well as all projects in that task will be tracked. Time tracking data is stored in csv files. The directory structure of the tracker and the csv specification can be found [here](data/tracker_spec.md). When a task that has been tracked is edited, only the corresponding entry in the daily csv file will be updated; the yearly csv file will not be changed. --- ### DBus API There is a pretty comprehensive dbus api. Check out the [dbus dir](dbus) for info on what you can do. There are also some example scripts that might come in handy. :smile: --- ### Custom Theme Support This extension supports custom themes. In order to style it, place a `timepp.css` file into your theme's root directory _(the dir where the `gnome-shell.css` file is)_. You must use the `!important` directive in order to override a property from the extensions' stylesheet. --- ### Keyboard Shortcuts
Any fullscreen view
Tab navigate forward
Ctrl + Tab navigate backward
Esc close fullscreen
Timer (fullscreen)
space stop/start timer
r or Backspace repeat last timer preset
1 ... 9 and 0 start timer at the time specified by a num key.
1=1min, 2=2min, ..., 0=10min
Stopwatch (fullscreen)
space stop/start timer
l or Enter lap
r or Backspace reset
Pomodoro (fullscreen)
space stop/start timer
Stats View
f or / start searching history
Todo Section in popup menu (default view)
/ start searching tasks
f open file switcher
i open task editor to add new task
k open kanban switcher
y open filters editor
s open sort editor
When focus is inside a task item in popup menu
e start editing task
Task editor
ctrl + h resize editor to the left
ctrl + j resize editor down
ctrl + k resize editor up
ctrl + l resize editor to the right
ctrl + f open file selector
ctrl + enter commit the change
--- ### Preview [Gnome-Shell theme](https://github.com/zagortenay333/ciliora-tertia-shell), [Wallpaper](https://i.imgur.com/raHVKVk.jpg) ![preview](./data/img/preview.png)