dot/.local/share/gnome-shell/extensions/timepp@zagortenay333

Time ++

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

---

Table of Contents

• Installation
• Warnings
• Translations
• Sections
• Fullscreen Interface
• Todo.txt Manager
• Todo.txt Syntax
• Todo.txt Extensions
• Time Tracker
• DBus API
• Custom Theme Support
• Keyboard Shortcuts
• Preview

---

Installation

1. Download the extension:
   • The latest version supports gnome-shell 3.34 (master-branch).
   • For older versions go to 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 ‼️

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

---

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}