pim/ktimetracker/CONTRIBUTING.md

0001 # Contributing to KTimeTracker
0002
0003 The source code for KTimeTracker can be found at https://invent.kde.org/pim/ktimetracker
0004 and the project uses QtWidgets + KDE Frameworks.
0005
0006 Issues should be reported to the [KDE Bugzilla](https://bugs.kde.org/enter_bug.cgi?product=ktimetracker&component=general).
0007
0008 ## Project Structure
0009
0010 The KTimeTracker source code is modular and easy to understand.
0011
0012 The main structure is: main loads mainwindow, which loads timetrackerwidget, which loads taskview and searchline.
0013
0014 The basics for understanding tasks is: taskmodelitem -> task.
0015 A task can have a representation as an event for iCalendar management.
0016 The projectmodel manages both tasks and events.
0017
0018 The rest consists of minor dialogs or actions.
0019
0020 ---
0021
0022 * **desktoplist**: a single typedef for DesktopList used in model/task, dialogs/taskpropertiesdialog, desktoptracker, plannerparser, taskview, timetrackerstorage, timetrackerwidget and main
0023 * **desktoptracker**: X11-only feature where tasks only run in certain virtual desktops
0024 * **focusdetector**: X11-only detection for which window is currently active, used in taskview
0025 * **idletimedetector**: uses KIdleTime to store the time spent idling, includes KGuiItem dialog
0026 * **ktimetrackerutility**: generic collection of utilities to manage locale, time format, errors (used in ktimetrackerwidget)
0027 * **mainwindow**: KXmlGuiWindow with a central widget TimeTrackerWidget, manages X11 window tracking, TrayIcon, and with KActionCollection shortcuts
0028 * **reportcriteria**: collection of enums and values for exporting backup copies (work reports)
0029 * **taskview**: main area where tasks will be listed, initialized by ktimetrackerwidget which is initialized in mainwindow which is initialized in main
0030 * **timetrackerstorage**: base to save and load **local** iCalendar files
0031 * **timetrackerwidget**: very large, the container for the taskview, searchline and definitions for KActionCollection actions, as well as most actions from the first screen and menu
0032 * **tray**: simple KStatusNotifierItem and its actions
0033 * **treeviewheadercontextmenu**: used for context menus in taskview, including when clicking the column titles
0034
0035 ---
0036
0037 * **dialogs/taskpropertiesdialog**: small dialog for creating/editing new tasks
0038 * **dialogs/edittimedialog**: small dialog that appears only with context menu
0039 * **dialogs/historydialog**: small dialog that appears only in the Edit Time dialog
0040 * **dialogs/exportdialog**: small dialog to export to file or clipboard
0041
0042 ---
0043
0044 * **export/**: the logic for exporting backup copies in multiple formats
0045
0046 ---
0047
0048 * **file/filecalendar**: the main KTimeTracker iCalendar file format
0049 * **file/icalformatkio**: the load/save procedure for the filecalendar (**both local and remote**)
0050
0051 ---
0052
0053 * **import/plannerparser**: generates an object representing a GNOME Planner XML import file
0054
0055 ---
0056
0057 * **model/event**: object for date/time events
0058 * **model/eventsmodel**: operations to manage date/time events
0059 * **model/taskmodelitem**: base class for tasks
0060 * **model/task**: main object for tasks
0061 * **model/taskmodel**: operations to manage tasks
0062 * **model/projectmodel**: high-level manager of events and tasks
0063
0064 ---
0065
0066 * **settings/ktimetrackerconfigdialog**: the main Settings dialog
0067 * **settings/cfgbehavior**: Behavior tab in the settings
0068 * **settings/cfgdisplay**: Appearance tab in the settings
0069 * **settings/cfgstorage**: Storage tab in the settings
0070
0071 ---
0072
0073 * **tests/**: small collection of tests for various tasks like file load/save, time formatting, task creation/deletion, needs -DBUILD_TESTING
0074
0075 ---
0076
0077 * **widgets/searchline**: main search bar
0078 * **widgets/taskswidget**: Percent Complete progress bar, Percent Complete context menu, Priority context menu
0079
0080 ## Available tasks (TODO)
0081
0082 * See if Planner import is still working, if it isn't, remove it
0083 * Remove the desktop tracking feature OR make it run on Wayland
0084 * Remove mention to karm.ics files
0085 * Check why openFile() and saveFile() are commented out
0086 * Find out the practical differente between timetrackerstorage and file/icalformatkio