Skip to content

Latest commit

 

History

History
525 lines (441 loc) · 16.4 KB

README.md

File metadata and controls

525 lines (441 loc) · 16.4 KB

Time ++

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

Table of Contents

Installation

  • You can install this extension from the gnome-shell extensions site.

    NOTE:
    Since it takes some time for the extension to be reviewed, the version on this site might be out of date and contain bugs that have already been fixed. Consider using the github version.

  • You can install it manually:

    • Download/clone this repo into your ~/.local/share/gnome-shell/extensions dir and rename the downloaded dir to timepp@zagortenay333.
    • Restart gnome-shell by typing Alt+F2, then r, then Enter.
    • Enable the extension via gnome tweak tool.

Compatibility

The latest version of this extension is on the master branch, and it supports gnome-shell version: 3.32.

For older versions, check the available releases.

Translations

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

Lock Screen

‼️ Note that all gnome-shell extensions get disabled in the lock screen.

Alarms, stopwatch and other timers won't work when the screen is locked.

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