# Podręcznik programu &karm;

Jonathan
Singer

    &Jonathan.Singer.mail;

Mark
Bucciarelli

    mark@hubcapconsulting.com

Sirtaj
Singh
Kang

    &Sirtaj.Singh.Kang.mail;

Lauri
Watts
Recenzent

    &Lauri.Watts.mail;

Krzysztof
Woźniak

    wozniakk@ceti.pl

Polskie tłumaczenie
2000-2004
&Jonathan.Singer;
2004-2005
Mark Bucciarelli
&FDLNotice;
2005-02-02
1.5.0

Program &karm; zlicza czas spędzany przy wykonywaniu różnych zadań.

KDE
karm
kdeutils
czas
zliczanie
projekt

## Wprowadzenie

Program &karm; podlicza czas spędzony przy wykonywaniu różnych zadań. Może się przydać jako rejestrator czasu pracy, za którą należy się wynagrodzenie, jest też użyteczny do raportowania godzin spędzonych codziennie nad jakimś zadaniem.

Historia przeprowadzonego czasu może być wyeksportowana do pliku rozdzielanego przecinkami, w celu zaimportowania do innych systemów rachunkowych i/lub narzędzi zarządzania projektami.

Program &karm; wykrywa sytuacje, w których klawiatura i myszka są bezczynne, można w nim także przypisać różne zadania dla różnych pulpitów. Te dwie funkcje pozwalają na poprawne działanie licznika czasu dla wielu zadań.

Program &karm; został napisany przez &Sirtaj.Singh.Kang;. Słowo karm oznacza pracę lub czyn w języku autora Punjabi, i ma takie samo znaczenie (przy lepszym zapisie) jak słowo karma.

## Instrukcja stosowania &karm;

### Uruchamianie &karm;

Aby uruchomić program należy wpisać `ktimetracker` w wierszu poleceń lub wybrać Osobisty czasomierz z menu Programy Narzędzi w menu startowym KDE. Standardowe parametry &Qt; i &kde; są dostępne, i mogą zostać wyświetlone za pomocą polecenia ``ktimetracker` `--help``.

&karm; udostępnia dodatkową opcję wiersza poleceń, która umożliwia wpisanie nazwy pliku iCalendar do przechowywania historii pracy. Można podać adres pliku na zdalnym serwerze dodają http lub ftp do nazwy pliku, na przykład: http://www.mysite.com/mydata/mylabor.ics.

### Zadania

Problem: Jesteś konsultantem pracującym w branży wolnego oprogramowania. Część twoich klientów zleca ci wiele projektów. W trakcie dnia, pracujesz nad kilkoma projektami jednocześnie. Chcesz śledzić czas spędzony nad każdym z projektów, aby móc wystawić miesięczną fakturę.

Rozwiązanie: Utwórz zadanie najwyższego poziomu dla każdego klienta i podzadanie dla każdego projektu tego klienta. Dla projektów wymagających bardziej szczegółowego śledzenia, utwórz listę podprojektów. Uruchamiaj zliczanie czasu poprzez dwukrotne kliknięcie na zadaniu, nad którym aktualnie pracujesz.

Program &karm; umożliwia dużą elastyczność przy zliczaniu czasu, pozwalając śledzić nieograniczoną listę zadań wraz z ich poziomami. Czas może być zliczany dla dowolnego zadania, może w danym czasie być jednocześnie aktywna większa liczba zadań.

Aby utworzyć zadanie najwyższego poziomu, trzeba wybrać &Ctrl;N Zadanie Nowe zadanie Aby utworzyć podzadanie, należy wybrać odpowiednie zadanie wyższego poziomu i wybrać &Ctrl;&Alt;N Zadanie Nowe podzadanie

Gdy zamykany jest program &karm; lista zadań jest zapisywane w pliku podanym w Ustawienia Konfiguracja KArm . Po ponownym uruchomieniu programu, zadania są odczytywane z tego pliku.

Program &karm; pozwala na importowanie i eksportowanie zadań z innych programów, aby zminimalizować konieczność niepotrzebnej pracy. Więcej na ten temat w części: Inne systemy.

### Zegary

Problem: Żeby być wypłacalnym, musisz wystawić rachunek na przeciętnie pięć godzin pracy dziennie. Aby realizować ten cel, sprawdzasz regularnie dzienne i tygodniowe podsumowania.

Rozwiązanie: Należy wyzerować licznik sesji na początku każdego dnia pracy, a wszystkie liczniki zerować na początku każdego tygodnia.

Program &karm; upraszcza pomiar czasu realizacji zadań. Aby uruchomić pomiar czasu zadania, wystarczy dwukrotnie kliknąć na zadaniu. Aby zatrzymać pomiar, wystarczy kliknąć zadania powtórnie. Aktywne zadania wyświetlają mały zegarek w kolumnie Czas sesji.

Innym wizualnym wskaźnikiem działania &karm; jest ikona na tacce systemowej. Jeżeli zadanie jest aktywne, wskazówka sekundnika na ikonie porusza się. Jeżeli kursor myszki zostanie przesunięty nad ikonę, pojawi się nazwa aktywnego zadania w podpowiedzi. Jeżeli więcej niż jedno zadanie jest aktywne, pojawi się w podpowiedzi ich lista rozdzielana przecinkami.

Program &karm; obsługuje dwa liczniki dla każdego zadania: jeden licznik sesji i jeden licznik całkowitego czasu. W domyślnej konfiguracji, &karm; wyświetla dwie kolumny dla każdego licznika, co daje cztery kolumny dla każdego zadania:

Czas sesji

  Czas spędzony na wykonanie zadania liczony od początku sesji.

Całkowity czas sesji

  Czas spędzony na realizacji zadania i wszystkich jego podzadań liczony od początku sesji.

Czas

  Czas zużyty na to zadanie od momentu wyzerowania wszystkich czasów.

Całkowity czas

  Czas spędzony na realizacji zadania i wszystkich jego podzadań liczony od momentu wyzerowania wszystkich czasów.

Aby uruchomić nową sesję, należy wybrać menu Plik Rozpocznij nową sesję

Aby wyzerować wszystkie zegary należy wybrać opcję Plik Wyzeruj wszystkie zegary

#### Śledzenie pulpitu

Problem: Użytkownik pracuje na dwoma głównymi projektami, pomiędzy którymi przełącza się w ciągu dnia. Aby wspomóc organizację pracy, utrzymuje pliki związane z pierwszym projektem na pulpicie 1, a drugim na pulpicie 2.

Rozwiązanie: Należy przyporządkować zadanie dotyczące projektu 1 do pulpitu 1, i analogicznie projektu 2 do pulpitu 2. Jeżeli pulpity zostaną przełączone z pulpitu 1 na pulpit 2, &karm; automatycznie zatrzymuje licznik dla projektu 1 i uruchamia licznik dla projektu 2.

Aby przyporządkować zadanie z jednym lub większą liczbą pulpitów, należy wybrać &Ctrl;E Zadanie Edycja . Włączyć opcję Śledzenie automatyczne i wybrać pulpit lub pulpity, z którym zadanie ma być związane. Jeżeli jakikolwiek z wskazanych pulpitów stanie się aktywny przez jakiś czas, &karm; rozpocznie zliczanie czasu dla tego zadania.

#### Wykrywanie bezczynności

Problem: Użytkownik wyszedł z pracy wcześniej w piątek, i zapomniał wyłączyć licznika. Kiedy wraca w poniedziałek, licznik ciągle pracuje.

Rozwiązanie: Należy włączyć wykrywanie bezczynności.

Program &karm; może być skonfigurowany tak, aby wykrywał sytuacje, w której myszka i klawiatura są bezczynne. Jeżeli są bezczynne przez określoną liczbę minut, program &karm; wyświetla następujące okno dialogowe:

Wykrywanie bezczynności przez &karm;
Okno dialogowe wykrywania bezczynności &karm;

Przywróć i zatrzymaj

  Odejmuje czas bezczynności od wszystkich aktywnych liczników i zatrzymuje je.

  Użytkownik nie pracował nad zadaniami, gdy komputer był bezczynny i dalej nie pracuje nad nimi.

Przywróć i kontynuuj.

  Odejmuje czas bezczynności od wszystkich aktywnych liczników i kontynuuje odliczanie.

  Użytkownik nie pracował nad zadaniami, gdy komputer był bezczynny lecz teraz już nad nimi pracuje.

Kontynuuj odliczanie

  Dodaje czas bezczynności do wszystkich aktywnych liczników i kontynuuje odliczanie.

  Użytkownik pracował nad zadaniami, gdy komputer był bezczynny i dalej nad nimi pracuje.

### Raportowanie

Program &karm; pozwala na raportowanie zliczone czasu na trzy sposoby. Można wydrukować podsumowania sesji i liczników, skopiować same podsumowania do schowka lub skopiować całą historię do schowka.

#### Drukowanie podsumowań

Aby wydrukować raport z podsumowaniami czasu, należy wybrać &Ctrl;P Plik Drukuj . Spowoduje to wygenerowanie trójkolumnowego raportu z kompletną listą zadań. Pierwsza kolumna zawiera nazwę zadania, druga kolumna to Całkowity czas sesji a trzecia kolumna to Czas zadania.

#### Podsumowania do schowka

Aby wygenerować raport podsumowań i przenieść go do schowka należy wybrać &Ctrl;C Plik Kopiuj podsumowania do schowka .

Ten raport jest generowany dla aktualnie wybranego zadania i wszystkich podzadań. Jeżeli wybrane jest zadanie najwyższego poziomu, &karm; zapyta czy generować raport dla aktualnego zadania i jego podzadań lub dla całej listy zadań.

&karm; Kopiuj to zadanie
Okno dialogowe &karm; Kopiuj to zadanie

Po wygenerowaniu raportu, należy otworzyć &kedit; lub jakiś inny edytor tekstu i wkleić dane raportu ze schowka.

    Task Totals
    2004-07-10 02:26

      Time    Task
    ----------------------------------------------
      9:14    kde
       9:14    karm
        1:08    bugs
        0:00    checkin changes
       0:00    promo
       0:00    web stuff
    ----------------------------------------------
      9:14 Total

Pierwsza kolumna to Total Time całkowity czas, jest wcięta (tak jak nazwy zadań) aby wskazywać relację zadania-podzadanie. Pokazywane na raporcie czasy zawierają czasy podzadań.

#### Historia do schowka

Aby wygenerować raport historii i przenieść go do schowka należy wybrać &Ctrl;&Alt;C Plik Kopiuj historię do schowka .

Wcześniej musi zostać włączona opcja Zapisuj historię w menu Ustawienia Konfiguracja &karm; . W innym przypadku &karm; będzie przechowywał jedynie podsumowania, a nie szczegółową historię zadania.

Raport jest generowany dla aktualnie wybranego zadania i wszystkich podzadań. Można także wygenerować go dla wszystkich zadań.

Jeżeli wybrany zostanie raport historii, &karm; najpierw zapyta o zakres dat dla raportu:

&karm; Wprowadzenie zakresu dat
&karm; Wprowadzanie zakresu dat

Po podaniu zakresu dat, należy otworzyć &kedit; lub jakiś inny edytor tekstu i wkleić dane raportu ze schowka.

    Task History
    From Thursday 01 July 2004 to Monday 12 July 2004
    Printed on: 2004-07-12 17:18

                                   Week of Monday 05 July 2004
         5     6     7     8     9    10    11
    -------------------------------------------------------------------------
                                                 0:00 kde
                                                 0:00  dc
                  !:22  1:46  3:14  1:44         8:06  karm
                                                 0:00   3.2 feature plan
                  1:08                           1:08   bugs
                                                 0:00   checkin changes
                                                 0:00  promo
                                                 0:00  web stuff
    -------------------------------------------------------------------------
                  2:30  1:46  3:14  1:44         9:14 Total

Historia zadania jest podsumowywana dla każdego dnia i zadania, oraz pogrupowana według tygodni. Pierwsze siedem kolumn odpowiada dniom tygodnia od poniedziałku do niedzieli. Ósma kolumna jest podsumowaniem całego tygodnia, a dziewiąta to nazwa zadania. Nazwy zadań są wcięte aby pokazać zależności pomiędzy zadaniami i podzadaniami.

### Współpraca z innymi programami

#### &korganizer;

&karm;, podobnie jak &korganizer; oraz iCal firmy Apple, używa standardowego formatu zapisu danych iCalendar. Program &karm; może czytać i zapisywać pliki zadań do wykonania utworzone przez te dwie aplikacje.

Jeżeli ten sam plik jest otwarty jednocześnie przez &karm; i &korganizer;, to zmiana pliku za pomocą programu &korganizer; może skutkować utratą danych. Aby zapewnić bezpieczeństwo danych, pliki należy zmieniać tylko w jednej aplikacji.

#### Planowanie

Jako typowy przykład zastosowania, użytkownik może chcieć zaplanować przedsięwzięcie w narzędziu zarządzania projektami: Imendio Planner (z planner.imendio.org) i zaimportować z niego zadania do programu &karm;, aby były w standardowym formacie iCalendar. Po zrobieniu tego, będzie on mógł zaplanować zadania w programie &korganizer; i zliczać czas spędzony przy ich realizacji za pomocą &karm;. Jest to jeden ze sposobów zapewniających, żeby projekt nie był opóźniony, zaś jego budżet nie był przekroczony.

#### &DBus;

&DBus; jest to mechanizm, wykorzystywany przez programy środowiska &kde; do wzajemnej komunikacji. Program &kde; udostępnia listę funkcji, które inne programy (jak np. skrypty powłoki) mogą wykorzystywać.

##### Skrypt powłoki, który zwraca wersję programu &karm;

    qdbus org.kde.ktimetracker /KTimeTracker version 2
    >/dev/null || echo "ktimetracker nie jest uruchomiony"

Aktualnie interfejs &DBus; w programie &karm; jest używany głównie do automatycznych testów, i w związku z tym jest bardzo ograniczony. Pełna dokumentacja interfejsu &DBus; znajduje się w dokumencie: &DBus; Interface Appendix.

Aby zobaczyć wszystkie funkcje udostępniane przez interfejs &DBus; zainstalowanej w systemie wersji programu &karm; należy uruchomić następujący skrypt powłoki:

##### Wyświetla funkcje interfejsu &DBus; w konsoli

    qdbus org.kde.ktimetracker /KTimeTracker 2
    >/dev/null || echo "ktimetracker nie jest uruchomiony"

#### Eksportowanie podsumowań do pliku CSV

Program &karm; umożliwia eksport zarówno podsumowań jak i historii do pliku rozdzielanego przecinkami. Aby wyeksportować podsumowania należy wybrać: Plik Importuj/Eksportuj Eksportuj do pliku CSV... co wyświetli następujące okno dialogowe:

&karm; Okno dialogowe eksportu do pliku CSV
&karm; Okno dialogowe eksportu do pliku CSV

Należy tu wprowadzić nazwę pliku, do którego użytkownik chce wyeksportować dane i dostosować inne dane domyślnie wypełnione w oknie w razie potrzeby. Uwaga: kontrolka modyfikacji zakresu dat jest nieaktywna, gdyż eksportowane są podsumowania, a nie historia. Po kliknięciu przycisku Eksportuj &karm; zapisze podsumowania wszystkich zadań do wybranego pliku.

Poniżej przykładowy układ raportu:

    "kde",,,,,0.00,0.00,6.88,9.83
    ,"karm",,,,6.88,8.70,6.88,9.83
    ,,"3.2 feature plan",,,0.00,0.00,0.00,0.00
    ,,"bugs",,,0.00,1.13,0.00,1.13
    ,,"checkin changes - translation strings",,,0.00,0.00,0.00,0.00
    ,,"time card report",,,0.00,0.00,0.00,0.00
    ,"kopete",,,,0.00,0.00,0.00,0.00
    ,"promo",,,,0.00,0.00,0.00,0.00
    ,"web stuff",,,,0.00,0.00,0.00,0.00

Zadania najwyższego poziomu zapisywane są w pierwszej kolumnie, podzadania w drugiej i tak dalej. Dane dotyczące czasu są zapisywane po osiągnięciu maksymalnego poziomu zagnieżdżenia zadań (piątego w powyższym przykładzie). Pierwsza kolumna czasu to: Session Time, druga Time, trzecia Total Session Time i czwarta Total Time.

#### Eksportuj historię do pliku CSV

by wyeksportować historię należy wybrać: Plik Importuj/Eksportuj Eksportuj historię do pliku CSV... co wyświetli takie samo jak wcześniej pokazane okno dzialogowe.

Należy tu wprowadzić nazwę pliku, do którego użytkownik chce wyeksportować historię i dostosować zakres dat do wyeksportowania, oraz inne opcje. Po kliknięciu przycisku Eksportuj &karm; zapisze historię wszystkich wszystkich zadań do wybranego pliku.

Poniżej przykładowy układ raportu:

    Task History
    From Tuesday 06 July 2004 to Tuesday 13 July 2004
    Printed on: 2004-07-13 18:10
    2004-07-06,2004-07-07,2004-07-08,2004-07-09,2004-07-10,2004-07-11,2004-07-12,2004-07-13,
    ,,,,,,,,0.00,"kde"
    ,,1.77,3.23,1.73,,1.37,0.82,8.95,,"karm"
    ,,,,,,,,0.00,,,"3.2 feature plan"
    ,1.13,,,,,,,1.13,,,"bugs"
    ,,,,,,,,0.00,,,"checkin changes - translation strings"
    ,,,,,,,,0.00,,,"time card report"
    ,,,,,,,,0.00,,"kopete"
    ,,,,,,,,0.00,,"promo"
    ,,,,,,,,0.00,,"web stuff"

Pierwsze trzy wiersze zawierają informacje o dacie wygenerowania raportu oraz o zakresie dat objętych raportem. Czwarty wiersz, jest rozdzielaną przecinkami listą dat objętych zakresem w formacie ISO 8601 (YYYY-MM-DD). Następne wiersze zawierają o czasie wszystkich zadań. Ostatnia numeryczna kolumna zawiera podsumowanie czasów dla wszystkich dni. Nazwa zadania podawana jest w ostatniej kolumnie i jest wcinana, aby pokazać zależności zadanie/podzadania. Zadania najwyższego poziomu podawane są w pierwszej kolumnie za podsumowaniem.

## Zawartość okna programu &karm;

Główne okno programu &karm; składa się z następujących elementów: menu, paska narzędzi, okna zadań/czasu oraz paska stanu.

Okno programu &karm;
Okno programu &karm;

### Okno Zadań/Czasu

Różne zadania są wyświetlone w tym oknie, wraz z całkowitym czasem dla każdego zadania w bieżącej sesji oraz ogółem. Zadania, dla których odlicza się czas, mają małą ikonę zegara wyświetloną obok czasu sesji.

Podzadania mogą być tworzone dla każdego zadania. Kliknięcie znaku plus oraz minus z przodu głównego zadania włącza i wyłącza widok powiązanych podzadań. Całkowity czas podliczony dla zadania, zawiera podsumowane czasy wszystkich podzadań jak i czasu głównego zadania.

### Pasek narzędzi

Pasek narzędzi zawiera ikony dla następujących poleceń:

(Wszystkie zachowują się identycznie jako polecenia w menu).

- Uruchom

- Zatrzymaj

- Nowe zadanie

- Nowe podzadanie

- Usuń

- Edycja

### Pasek stanu

Wyświetla podsumowanie całkowitego czasu pracy w sesji.

## Zasługi i licencje

&karm;

Prawa autorskie:

- 1997-2000 &Sirtaj.Singh.Kang; &Sirtaj.Singh.Kang.mail;.

- 2001-2002 Tomas Pospisek tpo_deb@sourcepole.ch

- 2003-2004 Mark Bucciarellimark@hubcapconsulting.com

Współtwórcy (w porządku alfabetycznym)

- Allen Winter winter@kde.org

- &David.Faure; &David.Faure.mail;

- &Espen.Sand; espen@kde.org

- Gioele Barabucci gioele@gioelebarabucci.com

- Jan Schaumann jschauma@netmeister.org

- &Jesper.Pedersen; blackie@ifad.dk

- Kalle Dalheimer &Matthias.Kalle.Dalheimer.mail;

- Klarälvdalens Datakonsult AB

- Mark Bucciarelli mark@hubcapconsulting.com

- Thorsten Stärk dev@staerk.de

- Tomas Pospisek tpo_deb@sourcepole.ch

- Willi Richert w.richert@cox.net

Program &karm; został zainspirowany przez małe narzędzie napisane przez Harald'a Tveit'a Alvestrand'a o nazwietitrax, jego jedyną wadą jest to, że bazujena bibliotece Xt.

Prawa autorskie do dokumentacji 2000-2004 &Jonathan.Singer; &Jonathan.Singer.mail; and &Sirtaj.Singh.Kang; &Sirtaj.Singh.Kang.mail;.

Polskie tłumaczenie: Krzysztof Woźniak wozniakk@ceti.pl

&underFDL; &underGPL;
aktywne zadanie

  Zadanie, dla którego uruchomiony jest zegar.

&DBus;

  Protokół wymiany komunikatów pomiędzy procesami w środowisku &kde;.

pulpit

  Systemy &GNU;/&Linux;, FreeBSD i inne bazujące na X-Windows posiadają wiele pulpitów. Najczęściej domyślna liczba pulpitów to cztery. Każdy pulpit może wyświetlać swój własny zestaw plików i programów. Gdy &kde; zostaje uruchomione po raz pierwszy, użytkownik widzi Pulpit 1. Po naciśnięciu klawiszy &Ctrl;F2, zobaczy Pulpit 2. Naciśnięcie&Ctrl;F1 spowoduje powrót na Pulpit 1.

historia

  Jeżeli program &karm; ma włączoną w konfiguracji opcję zapisywania historii, będzie zapisywał każdą sytuację uruchomienia i zatrzymania licznika. Ta historia nigdy nie jest usuwana przy zerowaniu liczników i pozostaje w pliku do czasu usunięcia zadania.

sesja

  Zdefiniowany przez użytkownika czas uruchomienia liczników sesji. Nowa sesja rozpoczyna się po wybraniu w menu Plik Rozpocznij nową sesję . Dane bieżącej sesji nie są zapisywane po utworzeniu nowej sesji.

Czas sesji

  Czas spędzony na wykonanie zadania liczony od początku sesji.

tacka systemowa

  Tacka systemowa to pasek, który (domyślnie) pokazuje się w dolnej części ekranu. W tej tacce widoczna po prawej stronie, znajduje się ikona programu &karm;: .

zadanie najwyższego poziomu

  Zadanie bez żadnych zadań-rodziców.

Całkowity czas sesji

  Czas spędzony na realizacji zadania i wszystkich jego podzadań liczony od początku sesji.

Czas

  Czas zużyty na to zadanie od momentu wyzerowania wszystkich czasów.

Całkowity czas

  Czas spędzony na realizacji zadania i wszystkich jego podzadań liczony od momentu wyzerowania wszystkich czasów.

## Instalacja

### Jak zdobyć &karm;

&install.intro.documentation; &install.compile.documentation;

## Interfejs &DBus;

version

### version

Zwraca numer wersji programu &karm;.

    QString version()

#### Opis

`version()` jest wywołaniem &DBus;, które zwraca numer wersji programu &karm;, na przykład: 1.5.0. Numer wersji zwracany jest jako napis w typowym formacie &GNU; tzn: major.minor.bugfix.

quit

### quit

Zamyka program &karm;.

    QString quit()

#### Opis

`quit()` jest wywołaniem &DBus; pozwalającym zewnętrznym programom poprawnie zakończyć działanie &karm;.

hastodo

### hastodo

Sprawdza istnienie zadania najwyższego poziomu.

    QString hastodo(QString taskname)

#### Parametry

`taskname`

  Nazwa zadania do wyszukania.

#### Opis

`hastodo(QString taskname)` jest wywołaniem &DBus;, które wyszukuje zadania o podanej nazwie. Jeżeli je znajdzie, to zwraca numer UID w pliku iCalendar, które dotyczy tego zadania. Jeżeli nic nie znajdzie, to zwraca pusty napis.

Przeszukiwany jest plik iCalendar aktualnie używany przez &karm;. Wszystkie zadania i podzadania są przeszukiwane. Jeżeli znalezione zostanie więcej niż jedno zadanie o podanej nazwie, to zwracany jest numer pierwszego znalezionego.

addtodo

### addtodo

Dodaje nowe zadanie

    QString addtodo(QString todoname)

#### Parametry

`todoname`

  Nazwa nowego zadania.

#### Opis

`addtodo(QString todoname)` jest wywołaniem &DBus;, które dodaje nowe zadanie najwyższego poziomu do bieżącego pliku zadań. Zwracany jest numer UID nowo dodanego zadania.

&documentation.index;