diff options
Diffstat (limited to 'karm/doc')
| -rw-r--r-- | karm/doc/Mainpage.dox | 214 | ||||
| -rw-r--r-- | karm/doc/design | 143 | ||||
| -rw-r--r-- | karm/doc/updating_parents.html | 39 |
3 files changed, 396 insertions, 0 deletions
diff --git a/karm/doc/Mainpage.dox b/karm/doc/Mainpage.dox new file mode 100644 index 000000000..7c8aee5f5 --- /dev/null +++ b/karm/doc/Mainpage.dox @@ -0,0 +1,214 @@ +/** \mainpage %Karm API Overview + +\section intro Introduction + +%Karm is a simple, easy to use time tracking program. It keeps a hierarchical list of tasks. Each task has a timer +associated with it. The primary user interaction for karm is to start and stop the appropriate timer. + +\section map Road Map to the Classes + +MainWindow is the outermost layer and initializes the menus and actions, sets +up the status bar, and handles many of the signal-to-slot connections. It +holds a pointer to the TaskView and Preferences objects and implements the +%Karm's DCOP interface (defined in KarmDCOPIface). + +TaskView does most of the work in the application. This KListView subclass +sets up the columns in the list, the idle detection timer, the auto save +timer, and the desktop tracker. It starts and stops timers, handles importing +and exporting and displays the edit task dialog in response to user action. +TaskView holds a private pointer to Preferences and KarmStorage objects. + +A Task is a QListViewItem subclass stores state such as the timer totals, if a +timer is currently running for the task. It also defines the list view sort +order and can return a pointer to a KCal::Todo object that holds the same +information. + +Preferences is a singleton that stores configuration options. It raises +signals when options change (for example, the location where the karm data is +stored) so the application can react and adjust. + +KarmStorage is a singleton that creates an interface for storing KArm data. +Currently, it uses KDE Resource framework and stores data in the iCalendar +format. + +*/ + +/** \page sig_slot_index Index of Signals and Slots + +To get an understanding of the flow program, it may be useful to see an overview of all of the signals, slots, and +connections. See \see connections to get an index of what signal is connected to which slot. + +\section overview Summary of what each class provides + +<table> + <tr><td><b><center>Class</center></b></td> <td><b><center>Signal?</center></b></td> <td><b><center>Public Slot?</center></b></td> + <td><b><center>Protected Slot?</center></b></td> <td><b><center>Private Slot?</center></b></td></tr> + + + <tr><td>AddTaskDialog</td> <td> </td> <td> </td> <td> </td> <td>Y </td></tr> + <tr><td>IdleTimer</td> <td>Y </td> <td>Y </td> <td>Y </td> <td> </td></tr> + <tr><td>KAccelMenuWatch</td> <td> </td> <td>Y </td> <td> </td> <td>Y </td></tr> + <tr><td>Karm</td> <td>Y </td> <td>Y </td> <td>Y </td> <td> </td></tr> + <tr><td>KarmTray</td> <td> </td> <td>Y </td> <td>Y </td> <td> </td></tr> + <tr><td>KarmWindow</td> <td> </td> <td> </td> <td>Y </td> <td> </td></tr> + <tr><td>KTimeWidget</td> <td> </td> <td> </td> <td> </td> <td> </td></tr> + <tr><td>ListViewIterator</td> <td> </td> <td> </td> <td> </td> <td> </td></tr> + <tr><td>Loging</td> <td> </td> <td> </td> <td> </td> <td> </td></tr> + <tr><td>MyPrinter</td> <td> </td> <td> </td> <td> </td> <td> </td></tr> + <tr><td>Preferences</td> <td>Y </td> <td>Y </td> <td>Y </td> <td> </td></tr> + <tr><td>SubtreeIterator</td> <td> </td> <td> </td> <td> </td> <td> </td></tr> + <tr><td>Task</td> <td> </td> <td> </td> <td>Y </td> <td> </td></tr> +</table> + +\section signals Listing of all of the signals + +These are the signals: +<ol> + <li>IdleTimer::extractTime(int) + <li>IdleTimer::stopTimer() + <li>Karm::sessionTimeChanged() + <li>Karm::timerActive() + <li>Karm::timerInactive() + <li>Karm::timerTick() + <li>Karm::updateButtons() + <li>Karm::tasksChanged(QPtrList<Task>) + <li>Preferences::autoSave(bool) + <li>Preferences::autoSavePeriod(int) + <li>Preferences::detectIdleness(bool) + <li>Preferences::idlenessTimeout(int) + <li>Preferences::saveFile(QString) + <li>Preferences::setupChanged() + <li>Preferences::timeLog(QString) + <li>Preferences::timeLoging(bool) + <li>Preferences::hideOnClose(bool) +</ol> + +\section slots Listing of the slots + +\subsection public Public Slots + +<ol> + <li>IdleTimer::setMaxIdle(int maxIdle) + <li>IdleTimer::startIdleDetection() + <li>IdleTimer::stopIdleDetection() + <li>IdleTimer::toggleOverAllIdleDetection(bool) + <li>KAccelMenuWatch::updateMenus() + <li>Karm::changeTimer(QListViewItem*) + <li>Karm::deleteTask() + <li>Karm::editTask() + <li>Karm::extractTime(int) + <li>Karm::load() + <li>Karm::newSubTask() + <li>Karm::newTask() + <li>Karm::newTask(QString, QListViewItem*) + <li>Karm::parseLine(QString, long*, QString*, int*) + <li>Karm::resetSessionTimeForAllTasks() + <li>Karm::save() + <li>Karm::startTimer() + <li>Karm::stopAllTimers() + <li>Karm::stopCurrentTimer() + <li>Karm::stopTimer(Task*) + <li>KarmTray::initToolTip() + <li>KarmTray::resetClock() + <li>KarmTray::startClock() + <li>KarmTray::stopClock() + <li>KarmTray::updateToolTip(QPtrList<Task>) + <li>Karm::writeTaskToFile(QTextStream*, QListViewItem*, int) + <li>Preferences::load() + <li>Preferences::save() + <li>Preferences::showDialog() +</ol> + +\subsection protected Protected Slots + +<ol> + <li>IdleTimer::check() + <li>Karm::addTimeToActiveTasks(int) + <li>Karm::autoSaveChanged(bool) + <li>Karm::autoSavePeriodChanged(int) + <li>Karm::minuteUpdate() + <li>Karm::stopChildCounters(Task*) + <li>KarmTray::advanceClock() + <li>KarmWindow::contextMenuRequest(QListViewItem*, const QPoint&, int) + <li>KarmWindow::disableStopAll() + <li>KarmWindow::enableStopAll() + <li>KarmWindow::hideOnClose(bool) + <li>KarmWindow::keyBindings() + <li>KarmWindow::print() + <li>KarmWindow::quit() + <li>KarmWindow::resetSessionTime(); + <li>KarmWindow::save() + <li>KarmWindow::slotSelectionChanged() + <li>KarmWindow::updateStatusBar() + <li>KarmWindow::updateTime() + <li>Preferences::autoSaveCheckBoxChanged() + <li>Preferences::hideOnCloseCheckBoxChanged() + <li>Preferences::idleDetectCheckBoxChanged() + <li>Preferences::slotCancel() + <li>Preferences::slotOk() + <li>Preferences::timeLogingCheckBoxChanged() + <li>Task::updateActiveIcon() +</ol> + +\subsection private Private Slots + +<ol> + <li>AddTaskDialog::enterWhatsThis() + <li>AddTaskDialog::slotAbsolutePressed() + <li>AddTaskDialog::slotRelativePressed() + <li>KAccelMenuWatch::removeDeadMenu() +</ol> + +*/ + +/** \page connections Index of the signal/slot connections + +<table> + <tr><td><center><b>Class</b></center></td> <td><center><b>Sender</b></center></td> <td><center><b>Sending Type</b></center></td> +<td><center><b>Signal</b></center></td> <td><center><b>Receiver</b></center></td> <td><center><b>Slot</b></center></td></tr> + +<tr><td>AddTaskDialog</td> <td>_absoluteRB</td> <td>QRadioButton</td> <td>clicked()</td> <td>this</td> <td>slotAbsolutePressed</td></tr> +<tr><td>AddTaskDialog</td> <td>_relativeRB</td> <td>QRadioButton</td> <td>clicked()</td> <td>this</td> <td>slotRelativePressed</td></tr> +<tr><td>AddTaskDialog</td> <td>whatsThisBU</td> <td>QPushButton</td> <td>clicked()</td> <td>this</td> <td>enterWhatsThis</td></tr> +<tr><td>IdleTimer</td> <td>_timer</td> <td>QTimer</td> <td>timeout()</td> <td>this</td> <td>check</td></tr> +<tr><td>KAccelMenuWatch</td> <td>menu</td> <td>QPopupMenu</td> <td>destroyed()</td> <td>this</td> <td>removeeDeadMenu</td></tr> +<tr><td>Karm</td> <td>this</td> <td>Karm__QListView</td> <td>doubleClicked()</td> <td>this</td> <td>changeTimer</td></tr> +<tr><td>Karm</td> <td>_minuteTimer</td> <td>QTimer</td> <td>timeout()</td> <td>this</td> <td>minuteUpdate</td></tr> +<tr><td>Karm</td> <td>_idleTimer</td> <td>IdleTimer</td> <td>extractTime()</td> <td>this</td> <td>extractTime</td></tr> +<tr><td>Karm</td> <td>_idleTimer</td> <td>IdleTimer</td> <td>stopTimer()</td> <td>this</td> <td>stopAllTimers</td></tr> +<tr><td>Karm</td> <td>_preferences</td> <td>Preferences</td> <td>idlenessTimeout()</td> <td>_idleTimer</td> <td>setMaxIdle</td></tr> +<tr><td>Karm</td> <td>_preferences</td> <td>Preferences</td> <td>detectIdleness()</td> <td>_idleTimer</td> <td>toggleOverAllIdleDetection</td></tr> +<tr><td>Karm</td> <td>_preferences</td> <td>Preferences</td> <td>autoSave()</td> <td>this</td> <td>autoSaveChanged</td></tr> +<tr><td>Karm</td> <td>_preferences</td> <td>Preferences</td> <td>autoSavePeriod()</td> <td>this</td> <td>autoSavePeriodChanged</td></tr> +<tr><td>Karm</td> <td>_autoSaveTimer</td> <td>QTimer</td> <td>timeout()</td> <td>this</td> <td>save</td></tr> +<tr><td>Karm</td> <td>_menu</td> <td>QPopupMenu</td> <td>__()</td> <td>this</td> <td>startTimer</td></tr> +<tr><td>Karm</td> <td>_menu</td> <td>QPopupMenu</td> <td>__()</td> <td>this</td> <td>stopCurrentTimer</td></tr> +<tr><td>Karm</td> <td>this</td> <td>Karm__QListView</td> <td>contextMenuRequested()</td> <td>this</td> <td>slotRMB</td></tr> +<tr><td>Preferences</td> <td>_doAutoSaveW</td> <td>QCheckBox</td> <td>clicked()</td> <td>this</td> <td>autoSaveCheckboxChanged</td></tr> +<tr><td>Preferences</td> <td>_doTimeLogingW</td> <td>QCheckBox</td> <td>clicked()</td> <td>this</td> <td>timeLogingCheckboxChanged</td></tr> +<tr><td>Preferences</td> <td>_doIdleDetectionW</td> <td>QCheckBox</td> <td>clicked()</td> <td>this</td> <td>idleDetectCheckBoxChanged</td></tr> +<tr><td>Preferences</td> <td>__</td> <td>Preferences__KDialogBase</td> <td>__()</td> <td>__</td> <td>slotOk</td></tr> +<tr><td>Preferences</td> <td>__</td> <td>Preferences__KDialogBase</td> <td>__()</td> <td>__</td> <td>slotCancel</td></tr> +<tr><td>KArmWindow</td> <td>_karm</td> <td>Karm</td> <td>sessionTimeChanged()</td> <td>this</td> <td>updateTime</td></tr> +<tr><td>KarmWindow</td> <td>_karm</td> <td>Karm__QListView</td> <td>currentChanged()</td> <td>this</td> <td>slotSelectionChanged</td></tr> +<tr><td>KarmWindow</td> <td>_karm</td> <td>Karm__QListView</td> <td>selectionChanged()</td> <td>this</td> <td>slotSelectionChanged</td></tr> +<tr><td>KarmWindow</td> <td>_karm</td> <td>Karm</td> <td>timerTick()</td> <td>this</td> <td>updateTime</td></tr> +<tr><td>KarmWindow</td> <td>_karm</td> <td>Karm</td> <td>timerActive()</td> <td>this</td> <td>setActiveIcon</td></tr> +<tr><td>KarmWindow</td> <td>_karm</td> <td>Karm</td> <td>timerInactive()</td> <td>this</td> <td>setInactiveIcon</td></tr> +<tr><td>KarmWindow</td> <td>KStdAction__quit</td> <td>KAction</td> <td>__()</td> <td>this</td> <td>quit</td></tr> +<tr><td>KarmWindow</td> <td>KStdAction__print</td> <td>KAction</td> <td>__()</td> <td>this</td> <td>print</td></tr> +<tr><td>KarmWindow</td> <td>KStdAction__keyBindings</td> <td>KAction</td> <td>__()</td> <td>this</td> <td>keyBindings</td></tr> +<tr><td>KarmWindow</td> <td>KStdAction__preferences</td> <td>KAction</td> <td>__()</td> <td>_preferences</td> <td>showDialog</td></tr> +<tr><td>KarmWindow</td> <td>KStdAction__save</td> <td>KAction</td> <td>__()</td> <td>_preferences</td> <td>save</td></tr> +<tr><td>KarmWindow</td> <td>actionResetSession</td> <td>KAction</td> <td>__()</td> <td>this</td> <td>resetSessionTime</td></tr> +<tr><td>KarmWindow</td> <td>actionStart</td> <td>KAction</td> <td>__()</td> <td>_karm</td> <td>startTimer</td></tr> +<tr><td>KarmWindow</td> <td>actionStop</td> <td>KAction</td> <td>__()</td> <td>_karm</td> <td>stopCurrentTimer</td></tr> +<tr><td>KarmWindow</td> <td>actionNew</td> <td>KAction</td> <td>__()</td> <td>_karm</td> <td>newTask</td></tr> +<tr><td>KarmWindow</td> <td>actionNewSub</td> <td>KAction</td> <td>__()</td> <td>_karm</td> <td>newSubTask</td></tr> +<tr><td>KarmWindow</td> <td>actionDelete</td> <td>KAction</td> <td>__()</td> <td>_karm</td> <td>deleteTask</td></tr> +<tr><td>KarmWindow</td> <td>actionEdit</td> <td>KAction</td> <td>__()</td> <td>_karm</td> <td>editTask</td></tr> +<tr><td>Task</td> <td>_timer</td> <td>QTimer</td> <td>timeout()</td> <td>this</td> <td>updateActiveIcon</td></tr> + +</table> + +*/ diff --git a/karm/doc/design b/karm/doc/design new file mode 100644 index 000000000..be9a425fa --- /dev/null +++ b/karm/doc/design @@ -0,0 +1,143 @@ +This document is meant to provide some documentation of rough consens +of where karm should be going and how things should be done. + +It does not represent something set in stone. Things can be discussed +and changed. +--------------------------------------------------------------------- + +* karm should not interfere if the user wants to run multiple tasks at + the same time that add up to more that 100%. + + It'd be nice though to have the possibility to have one task at a time + only (currently through double click). + + Or to let tasks' shares add up to 100%. Maybe through the context menu + ("share time with other task"). + +* tasks should update their own time and pass changes on down to the root. + The root is responsable for updating the status bar. + +Subject: Re: [Kde-pim] karm: how tasks should work +From: Scott Monachello <smonach@cox.net> +Date: 2002-10-26 9:38:23 + +On Thursday 24 October 2002 06:37 pm, tomas pospisek wrote: +> OK guys, I'm moving this into public space. I think we're open source so +> it's here where these things should be discussed. I hope citing your +> proposition in public is fine with you Scott. So here it comes, +> reformatted to fit into a mail: +> +> Scott Monachello propopsed [reformatted by tpo] +> +> > Requirements for Karm Subtask Functions +> > +> > This is how HEAD currently operates. +> > Id Description +> > --------------------------------------------------------------------- +> > 1 Karm shall provide a hierarchical structure of tasks. If a task +> > has at least one subtask it will be referred to as a parent task. +> > If a task has no children it will be referred to as a leaf task. +> > If a task has no parent tasks it will be referred to as a root +> > task. +> > 2 A new task can be created as a child of any existing task. +> > 2.1 If the parent had a timer active, it will continue to be active +> +> It depends on how you start it. If you double click it. Any other timer +> will be stopped and the new task started. If you start it through the +> start button, both tasks will be active. This a bug IMO. See at the bottom +> for my proposal. +> +> > 2.2 The session time for the parent will not be changed by adding +> > the new child task. +> > 2.3 The total time for the parent will not be changed by adding a +> > the new child task. +> > 3 Any task (parent, leaf, or root) may have an independent timer. +> > 4 The time (both session and total) for a parent will be the sum +> > of its independent timer and the sum of all of its child timers. +> > +> > Unstable Development +> > This is my proposal for how Unstable_Development should operate. I +> > changed 2.1 - 4 and added and added 2.2.1 and 1008. +> > +> > Id Description +> > --------------------------------------------------------------------- +> > 1 Karm shall provide a hierarchical structure of tasks. If a task +> > has at least one subtask it will be referred to as a parent task. +> > If a task has no children it will be referred to as a leaf task. +> > If a task has no parent tasks it will be referred to as a root +> > task. +> > 2 A new task can be created as a child of any existing task. +> > 2.1 If the parent had a timer active, it will be deactivated +> > 2.2 The session time for the parent will set to zero +> > 2.2.1 The session time for the child will be initialized to the last +> > session time of the parent. +> > 2.3 The total time for the parent will be set to zero. +> > 2.3.1 The total time for the parent will be initialized to the last +> > total time of the parent. +> > 3 Only a leaf task may have a timer. A parent may not have its own +> > timer. +> > 4 The time (both session and total) for a parent will be the sum +> > only of its child timers. +> +> I see where you want to go, but I think it's not the right direction for +> two reasons: +> +> 1. Let's say I'm working on karm - I have a generic task "karm". Now I +> start working on the docu and add a subtask "docu". Right now I can +> switch between a generic task "working on karm" and more specific +> subtask "docu". Times are added together at the task "karm". That makes +> sense IMO. If I don't want to be specific I can - if I do want to be +> more precise I can as well. With your proposal this is not possible any +> more. +> +> 2. You break current setups. People are (I guess) using karm for real life +> things. When you change the behaveour to what you propose this +> force them to reorganize their trees. As a user, personally I'm not +> looking forward having to do this. +> +> My proposition is: +> +> Id Description +> --------------------------------------------------------------------- +> 2.1 If a new task is double clicked or started with the start +> button the previous task is stopped. + +So, only one task is ever active at one time, right? Tasks should be more like +radio boxes rather than check boxes. + +> 2.1.1 If someone feels like it s/he can add an entry/functionality into +> the context menu of a task to have it share proportionally the +> time being stopped with other tasks currently running. All the +> times always add up to 100%. +> This can be useful when doing >1 task at a time (compiling and +> phoning f.ex.) + +I've been thinking about something along these lines too. I think it's a good +idea but can't quite see how the interface should work. + +> +> The rest stays the same as in HEAD. +> +> Additionaly I propose: +> +> Id Description +> --------------------------------------------------------------------- +> 5 Times can be dragged and dropped, whereby they get transferred and +> added to the destination. +> 6 We move to scheme where times have a beginning and an ending and +> not just an absolute value. +> +> Comments? +> *t +> +> PS: Please follow up to the mailing list. + +Ok. So, I'll undo the changes related to: +* summing only leaf tasks +* disallowing edits on parent tasks +_______________________________________________ +kde-pim mailing list +kde-pim@mail.kde.org +http://mail.kde.org/mailman/listinfo/kde-pim +kde-pim home page at http://pim.kde.org/ + diff --git a/karm/doc/updating_parents.html b/karm/doc/updating_parents.html new file mode 100644 index 000000000..3b55ce30f --- /dev/null +++ b/karm/doc/updating_parents.html @@ -0,0 +1,39 @@ +<p>This is an outline of how times should be updated and added together.</p> + +<p>Start the program, create a task three levels deep and give it some time. +You should get something like this.</p> +<table border=2> + <tr><th>Task</th> <th>Session</th> <th>Total</th></tr> + <tr><td>A</td> <td>5</td> <td>5</td></tr> + <tr><td> a1</td> <td>5</td> <td>5</td></tr> + <tr><td> a11</td> <td>5</td> <td>5</td></tr> + <tr><td> a12</td> <td>0</td> <td>0</td></tr> + + <tr><td> </td> <td>Session: 15</td> <td>Total: 15</td></tr> +</table> + +<p>Now exit out of the program and start it up again. You should see the following.</p> +<table border=2> + <tr><th>Task</th> <th>Session</th> <th>Total</th></tr> + <tr><td>A</td> <td>0</td> <td>5</td></tr> + <tr><td> a1</td> <td>0</td> <td>5</td></tr> + <tr><td> a11</td> <td>0</td> <td>5</td></tr> + <tr><td> a12</td> <td>0</td> <td>0</td></tr> + + <tr><td> </td> <td>Session: 0</td> <td>Total: 15</td></tr> +</table> + +<p>Now start the timer and let it run for a minute, then stop it.</p> +<table border=2> + <tr><th>Task</th> <th>Session</th> <th>Total</th></tr> + <tr><td>A</td> <td>1</td> <td>6</td></tr> + <tr><td> a1</td> <td>1</td> <td>6</td></tr> + <tr><td> a11</td> <td>1</td> <td>6</td></tr> + <tr><td> a12</td> <td>0</td> <td>0</td></tr> + + <tr><td> </td> <td>Session: 3</td> <td>Total: 18</td></tr> +</table> + +<p>Since a parent task can have a timer active on it, it needs to be included in the summary +Session and Total times. So, in this example, the Session time will jump three minutes for every +minute the timer is active.</p> |