Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

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>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>Y     </td></tr>
+    <tr><td>IdleTimer</td>        <td>Y     </td> <td>Y     </td> <td>Y     </td> <td>&nbsp;</td></tr>
+    <tr><td>KAccelMenuWatch</td>  <td>&nbsp;</td> <td>Y     </td> <td>&nbsp;</td> <td>Y     </td></tr>
+    <tr><td>Karm</td>             <td>Y     </td> <td>Y     </td> <td>Y     </td> <td>&nbsp;</td></tr>
+    <tr><td>KarmTray</td>         <td>&nbsp;</td> <td>Y     </td> <td>Y     </td> <td>&nbsp;</td></tr>
+    <tr><td>KarmWindow</td>       <td>&nbsp;</td> <td>&nbsp;</td> <td>Y     </td> <td>&nbsp;</td></tr>
+    <tr><td>KTimeWidget</td>      <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td></tr>
+    <tr><td>ListViewIterator</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td></tr>
+    <tr><td>Loging</td>           <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td></tr>
+    <tr><td>MyPrinter</td>        <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td></tr>
+    <tr><td>Preferences</td>      <td>Y     </td> <td>Y     </td> <td>Y     </td> <td>&nbsp;</td></tr>
+    <tr><td>SubtreeIterator</td>  <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td> <td>&nbsp;</td></tr>
+    <tr><td>Task</td>             <td>&nbsp;</td> <td>&nbsp;</td> <td>Y     </td> <td>&nbsp;</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 <[email protected]>
+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
[email protected]
+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>&nbsp;&nbsp;a1</td>              <td>5</td> <td>5</td></tr>
+	<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;a11</td> <td>5</td> <td>5</td></tr>
+	<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;a12</td> <td>0</td> <td>0</td></tr>
+
+	<tr><td>&nbsp;</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>&nbsp;&nbsp;a1</td>              <td>0</td> <td>5</td></tr>
+	<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;a11</td> <td>0</td> <td>5</td></tr>
+	<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;a12</td> <td>0</td> <td>0</td></tr>
+
+	<tr><td>&nbsp;</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>&nbsp;&nbsp;a1</td>              <td>1</td> <td>6</td></tr>
+	<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;a11</td> <td>1</td> <td>6</td></tr>
+	<tr><td>&nbsp;&nbsp;&nbsp;&nbsp;a12</td> <td>0</td> <td>0</td></tr>
+
+	<tr><td>&nbsp;</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>