Skip to content

digitalillusion/timepp

 
 

Repository files navigation

Time ++

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

preview

Warning

  1. This extension is in low maintenance mode. Don't make feature requests.
  2. Mild to severe operating system instability can be caused in case of a bug.
  3. Alarms, timers, and similar will not work when the screen is locked because all extensions are disabled then.

Installation

  1. Download the extension:
  2. Extract and rename the downloaded folder to timepp@zagortenay333 and move it into /home/YOUR_USER_NAME/.local/share/gnome-shell/extensions/.
  3. Log in and out or restart gnome shell by typing Alt F2, then r, then Enter.
  4. Enable the extension via the gnome extensions app.

Sections

This is a modular extension consisting of several sections: timer, stopwatch, alarms, etc.

The sections can be individually disabled if you don't use them.

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.

Right-clicking on the panel icons will open a context section with some useful links.

Fullscreen

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 via a keyboard shortcut.

Text Markup

Simple text markup is available in places like todo.txt tasks, timer messages, etc...

  • Parts of text can be highlighted:

    `     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 in various forms are highlighted (and can be clicked):

    https://www.google.com
    www.google.com
    /home/user/Documents
    ~/Documents
    ~/Documents/img.png
    ~/Documents/file\ with\ spaces.png
    
  • There is multiline support in todo.txt tasks with the use of \n:

    Line 1.\nLine 2.\nLine 3.
    

Todo.txt

The todo.txt format is specified here: https://github.com/todotxt/todo.txt

Some of the features of the todo.txt section 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.
  • Auto-updating 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 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, this 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.

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.

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

DBus API

There is a decent 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.

Translations

If you want to help out with translations, check out the instructions in the po_files dir.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 95.2%
  • CSS 3.5%
  • Shell 1.3%