From 460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: 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 --- karm/doc/Mainpage.dox | 214 +++++++++++++++++++++++++++++++++++++++++ karm/doc/design | 143 +++++++++++++++++++++++++++ karm/doc/updating_parents.html | 39 ++++++++ 3 files changed, 396 insertions(+) create mode 100644 karm/doc/Mainpage.dox create mode 100644 karm/doc/design create mode 100644 karm/doc/updating_parents.html (limited to 'karm/doc') 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 + + + + + + + + + + + + + + + + + + + +
Class
Signal?
Public Slot?
Protected Slot?
Private Slot?
AddTaskDialog       Y
IdleTimer Y Y Y  
KAccelMenuWatch   Y   Y
Karm Y Y Y  
KarmTray   Y Y  
KarmWindow     Y  
KTimeWidget        
ListViewIterator        
Loging        
MyPrinter        
Preferences Y Y Y  
SubtreeIterator        
Task     Y  
+ +\section signals Listing of all of the signals + +These are the signals: +
    +
  1. IdleTimer::extractTime(int) +
  2. IdleTimer::stopTimer() +
  3. Karm::sessionTimeChanged() +
  4. Karm::timerActive() +
  5. Karm::timerInactive() +
  6. Karm::timerTick() +
  7. Karm::updateButtons() +
  8. Karm::tasksChanged(QPtrList) +
  9. Preferences::autoSave(bool) +
  10. Preferences::autoSavePeriod(int) +
  11. Preferences::detectIdleness(bool) +
  12. Preferences::idlenessTimeout(int) +
  13. Preferences::saveFile(QString) +
  14. Preferences::setupChanged() +
  15. Preferences::timeLog(QString) +
  16. Preferences::timeLoging(bool) +
  17. Preferences::hideOnClose(bool) +
+ +\section slots Listing of the slots + +\subsection public Public Slots + +
    +
  1. IdleTimer::setMaxIdle(int maxIdle) +
  2. IdleTimer::startIdleDetection() +
  3. IdleTimer::stopIdleDetection() +
  4. IdleTimer::toggleOverAllIdleDetection(bool) +
  5. KAccelMenuWatch::updateMenus() +
  6. Karm::changeTimer(QListViewItem*) +
  7. Karm::deleteTask() +
  8. Karm::editTask() +
  9. Karm::extractTime(int) +
  10. Karm::load() +
  11. Karm::newSubTask() +
  12. Karm::newTask() +
  13. Karm::newTask(QString, QListViewItem*) +
  14. Karm::parseLine(QString, long*, QString*, int*) +
  15. Karm::resetSessionTimeForAllTasks() +
  16. Karm::save() +
  17. Karm::startTimer() +
  18. Karm::stopAllTimers() +
  19. Karm::stopCurrentTimer() +
  20. Karm::stopTimer(Task*) +
  21. KarmTray::initToolTip() +
  22. KarmTray::resetClock() +
  23. KarmTray::startClock() +
  24. KarmTray::stopClock() +
  25. KarmTray::updateToolTip(QPtrList) +
  26. Karm::writeTaskToFile(QTextStream*, QListViewItem*, int) +
  27. Preferences::load() +
  28. Preferences::save() +
  29. Preferences::showDialog() +
+ +\subsection protected Protected Slots + +
    +
  1. IdleTimer::check() +
  2. Karm::addTimeToActiveTasks(int) +
  3. Karm::autoSaveChanged(bool) +
  4. Karm::autoSavePeriodChanged(int) +
  5. Karm::minuteUpdate() +
  6. Karm::stopChildCounters(Task*) +
  7. KarmTray::advanceClock() +
  8. KarmWindow::contextMenuRequest(QListViewItem*, const QPoint&, int) +
  9. KarmWindow::disableStopAll() +
  10. KarmWindow::enableStopAll() +
  11. KarmWindow::hideOnClose(bool) +
  12. KarmWindow::keyBindings() +
  13. KarmWindow::print() +
  14. KarmWindow::quit() +
  15. KarmWindow::resetSessionTime(); +
  16. KarmWindow::save() +
  17. KarmWindow::slotSelectionChanged() +
  18. KarmWindow::updateStatusBar() +
  19. KarmWindow::updateTime() +
  20. Preferences::autoSaveCheckBoxChanged() +
  21. Preferences::hideOnCloseCheckBoxChanged() +
  22. Preferences::idleDetectCheckBoxChanged() +
  23. Preferences::slotCancel() +
  24. Preferences::slotOk() +
  25. Preferences::timeLogingCheckBoxChanged() +
  26. Task::updateActiveIcon() +
+ +\subsection private Private Slots + +
    +
  1. AddTaskDialog::enterWhatsThis() +
  2. AddTaskDialog::slotAbsolutePressed() +
  3. AddTaskDialog::slotRelativePressed() +
  4. KAccelMenuWatch::removeDeadMenu() +
+ +*/ + +/** \page connections Index of the signal/slot connections + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Class
Sender
Sending Type
Signal
Receiver
Slot
AddTaskDialog _absoluteRB QRadioButton clicked() this slotAbsolutePressed
AddTaskDialog _relativeRB QRadioButton clicked() this slotRelativePressed
AddTaskDialog whatsThisBU QPushButton clicked() this enterWhatsThis
IdleTimer _timer QTimer timeout() this check
KAccelMenuWatch menu QPopupMenu destroyed() this removeeDeadMenu
Karm this Karm__QListView doubleClicked() this changeTimer
Karm _minuteTimer QTimer timeout() this minuteUpdate
Karm _idleTimer IdleTimer extractTime() this extractTime
Karm _idleTimer IdleTimer stopTimer() this stopAllTimers
Karm _preferences Preferences idlenessTimeout() _idleTimer setMaxIdle
Karm _preferences Preferences detectIdleness() _idleTimer toggleOverAllIdleDetection
Karm _preferences Preferences autoSave() this autoSaveChanged
Karm _preferences Preferences autoSavePeriod() this autoSavePeriodChanged
Karm _autoSaveTimer QTimer timeout() this save
Karm _menu QPopupMenu __() this startTimer
Karm _menu QPopupMenu __() this stopCurrentTimer
Karm this Karm__QListView contextMenuRequested() this slotRMB
Preferences _doAutoSaveW QCheckBox clicked() this autoSaveCheckboxChanged
Preferences _doTimeLogingW QCheckBox clicked() this timeLogingCheckboxChanged
Preferences _doIdleDetectionW QCheckBox clicked() this idleDetectCheckBoxChanged
Preferences __ Preferences__KDialogBase __() __ slotOk
Preferences __ Preferences__KDialogBase __() __ slotCancel
KArmWindow _karm Karm sessionTimeChanged() this updateTime
KarmWindow _karm Karm__QListView currentChanged() this slotSelectionChanged
KarmWindow _karm Karm__QListView selectionChanged() this slotSelectionChanged
KarmWindow _karm Karm timerTick() this updateTime
KarmWindow _karm Karm timerActive() this setActiveIcon
KarmWindow _karm Karm timerInactive() this setInactiveIcon
KarmWindow KStdAction__quit KAction __() this quit
KarmWindow KStdAction__print KAction __() this print
KarmWindow KStdAction__keyBindings KAction __() this keyBindings
KarmWindow KStdAction__preferences KAction __() _preferences showDialog
KarmWindow KStdAction__save KAction __() _preferences save
KarmWindow actionResetSession KAction __() this resetSessionTime
KarmWindow actionStart KAction __() _karm startTimer
KarmWindow actionStop KAction __() _karm stopCurrentTimer
KarmWindow actionNew KAction __() _karm newTask
KarmWindow actionNewSub KAction __() _karm newSubTask
KarmWindow actionDelete KAction __() _karm deleteTask
KarmWindow actionEdit KAction __() _karm editTask
Task _timer QTimer timeout() this updateActiveIcon
+ +*/ 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 +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 @@ +

This is an outline of how times should be updated and added together.

+ +

Start the program, create a task three levels deep and give it some time. +You should get something like this.

+ + + + + + + + +
Task Session Total
A 5 5
  a1 5 5
    a11 5 5
    a12 0 0
  Session: 15 Total: 15
+ +

Now exit out of the program and start it up again. You should see the following.

+ + + + + + + + +
Task Session Total
A 0 5
  a1 0 5
    a11 0 5
    a12 0 0
  Session: 0 Total: 15
+ +

Now start the timer and let it run for a minute, then stop it.

+ + + + + + + + +
Task Session Total
A 1 6
  a1 1 6
    a11 1 6
    a12 0 0
  Session: 3 Total: 18
+ +

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.

-- cgit v1.2.1