doTUI (C++)

A lightweight, highly responsive Terminal User Interface (TUI) application written in modern C++ for managing categorized tasks, assignments, and activities. Built on top of ncurses, this application is optimized for performance, snappiness, and zero screen flickering.

---

🚀 Features

📋 Core Task Management

• Categorized Tasks: Organize tasks into different lists/categories (e.g., Inbox, Work, Personal).
• Task Types:
  • Activity: Tasks with a designated start date/time.
  • Assignment: Tasks with a designated deadline date/time.
• Completed Tasks Visual Group: Completed tasks automatically move to a distinct visual section at the bottom of the list.
• Sorting & Reordering:
  • Sort categories alphabetically or shift their positions manually.
  • Sort tasks alphabetically, by date/time (earliest/latest), or shift task priorities up/down manually.

⚡ Advanced Actions & Automation

• Task Snooze/Postponement (p): Postpone a task's start/due date by +1 Hour, +1 Day, or +1 Week instantly through a fast selection picker.
• Task Transfer/Movement (m): Move a task out of its current category list and directly into any other user-selected category.
• Direct Calendar Picker: Prompts for date/time by directly opening an interactive visual calendar grid with keyboard navigation (hjkl / arrows), month switching (</>), date clearing (n), and time input (HH:MM).
• Color Theme Selector (t / :theme): Switch between visual color schemes (default, dracula, nord, gruvbox, monokai, tokyo-night) directly from an interactive dialog or command bar.

🎨 Advanced Terminal UX & Polish

• Double-Buffered Rendering: Utilizes wnoutrefresh() and doupdate() to update the terminal window in a single frame update, preventing any screen flickering.
• Zero ESC Delay: Configured with a 25ms ESC timeout for instant dialog cancellation responsiveness.
• Vim-Style Navigation: Support for standard vim keys (j/k to navigate list items, h/l to switch pane focus).
• Interactive Real-Time Filter/Search (/): Drops input focus into a bottom border text search field. As you type, the task pane filters titles in real-time.
• Relative Countdown Display: Displays a dynamic, relative countdown (e.g. (In 2 days, 3 hours) or (Overdue by 5 hours)) underneath the static timestamp in the Task Details Pane.

💾 Storage & Portability

• XDG Base Directory Compliance: Saves configuration dynamically to $XDG_CONFIG_HOME/dotui/tasks.txt. Falls back to $HOME/.config/dotui/tasks.txt if $XDG_CONFIG_HOME is unset. Parent directories are created automatically on startup.
• Extended Serialization: Employs a clean, flat-file serialization piping layout to save and load task states efficiently.

---

🛠️ Technology Stack

• Language: C++17 (compiled using g++)
• UI Library: ncurses (terminal display and keyboard event processing library)
• Build System: GNU Make

---

📂 Project Structure

Task-Management-TUI/
├── src/
│   ├── main.cpp        # Application entry point & main event/drawing loop
│   ├── app/            # Application state management & command execution loop
│   ├── ui/             # Ncurses drawing, modals, calendar picker & themes
│   ├── input/          # Keybindings & mode handling
│   ├── persistence/    # Serialization & theme configuration parser
│   └── core/           # Data structures (Task, List, ThemeColors)
├── Makefile            # Build instructions
├── TODO.md             # Project roadmap and completed tracker
└── README.md           # Documentation (This file)

---

🎮 Keybindings & Controls

The interface is divided into pane columns: Categories Pane on the left and Tasks Pane + Task Details Pane on the right.

General Navigation

• Tab : Switch focus between the Categories pane and the Tasks pane.
• h / l : Vim-style pane switching (pressing h in Tasks pane switches to Categories, pressing l in Categories pane switches to Tasks).
• / : Drop focus to the bottom search bar (type query and press Enter to scroll matches, press Esc to clear search).
• t : Open the interactive Theme Selection dialog.
• ? : Open the full-screen live keybindings overlay.
• : : Open command bar (:new <title>, :sort, :theme <name>, :quit).
• q : Save progress and exit.

Pane Controls (Varies by focus)

Key	Categories Focused	Tasks Focused
Up / Down or k / j	Navigate through categories	Navigate through tasks
Space	N/A	Toggle selected task completion
n or a	Create a new Category	Create a new Task (opens Calendar Picker & time input)
e	Rename selected Category	Edit selected Task (Title, Description, Date/Time)
d or x	Delete selected Category	Delete selected Task
s	Open Sort/Shift menu for Categories	Open Sort/Shift menu for Tasks
t	Select Color Theme	Select Color Theme
p	N/A	Snooze task (postpone date/time by +1 hour, +1 day, or +1 week)
m	N/A	Move task to a different Category list

---

🏁 Getting Started

Prerequisites

Make sure you have a C++ compiler supporting C++17 and the ncurses development library installed.

On Fedora / RHEL / CentOS:

sudo dnf install gcc-c++ ncurses-devel make

On Debian / Ubuntu:

sudo apt-get install g++ libncurses5-dev libncursesw5-dev make

On macOS (using Homebrew):

brew install ncurses

Installation & Build

1. Clone this repository:

   git clone https://github.com/your-username/Task-Management-TUI.git
   cd Task-Management-TUI

2. Build the binary target:

   make

3. Install the application:

   • System-wide installation (installs to /usr/local/bin):

     sudo make install

   • User-only installation (installs to your home directory, e.g. ~/.local/bin):

     make install PREFIX=$HOME/.local

4. Run the application from anywhere:

   dotui

---

💾 Storage Format

Data is serialized to the XDG config folder ($HOME/.config/dotui/tasks.txt). The serialization format uses plain piping:

• Category format: L|<Category Name>
• Task format: T|<Completed (0/1)>|<Type (ACT/ASM)>|<Title>|<Description>|<DateTime>

Example contents of tasks.txt:

L|Inbox
T|0|ACT|Prepare meeting|Prepare presentation slides|2026-07-15 10:00
T|1|ASM|Write essay|Submit via portal|2026-07-17 17:00
L|Work
T|0|ACT|Team Sync|Discuss sprint goals|2026-07-13 09:00