/timepp__gnome

A todo.txt manager, time tracker, timer, stopwatch, pomodoro, and alarms gnome-shell extension.

Primary LanguageJavaScriptOtherNOASSERTION

Time ++

A todo.txt manager, time tracker, timer, stopwatch, pomodoro, and alarms gnome-shell extension.

Table of Contents

Installation

  1. Download this repository into your /home/YOUR_USER_NAME/.local/share/gnome-shell/extensions folder.
  2. Extract and rename the downloaded folder to timepp@zagortenay333.
  3. Restart your desktop shell by typing Alt+F2, then r, then Enter.
  4. Enable the extension via the gnome tweak tool program.

Warnings ‼️

  1. This extension is in very low-maintenance mode.
  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 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.

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 some markdown stuff:

    • A simple version of markdown is supported:

      `     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 are supported:

      https://www.google.com
www.google.com

/home/user/Documents
~/Documents
~/Documents/img.png
~/Documents/file\ with\ spaces.png

    • Newline chars in the todo.txt file can be used to have multiline support:

      (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

The time tracker is built into the todo.txt manager.

  • When the play button is pressed, the task as well as all projects in that task will be tracked.

  • 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.

  • The directory structure of the tracker and the csv specification can be found here.

  • This extension features a fullscreen stats view for browsing/searching your time-tracker data.

    • The stats uses vbar graphs to display total time and/or work intervals.
    • It supports viewing time spent on tasks/projects on any recorded day.
    • You can see a detailed view for a particular task/project.
    • You can fuzzy search your history.
    • You can view the most worked on tasks/projects in a particular time interval.

DBus API

There is a pretty comprehensive dbus api. Check out the dbus dir for info on what you can do.

There are also some example scripts that might come in handy. 😄

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, Wallpaper

preview