# O Manual do &karm;

Jonathan
Singer

    &Jonathan.Singer.mail;

Mark
Bucciarelli

    mark@hubcapconsulting.com

Sirtaj
Singh
Kang

    &Sirtaj.Singh.Kang.mail;

Lauri
Watts
Revisor

    &Lauri.Watts.mail;

Marcus
Gama

    marcus.gama@gmail.com

Tradução
2000-2004
&Jonathan.Singer;
2004-2005
Mark Bucciarelli
&FDLNotice;
2005-02-02
1.5.0

&karm; registra o tempo dispendido em várias tarefas.

KDE
karm
kdeutils
tempo
registro
projeto

## Introdução

O &karm; registra o tempo dispendido em várias tarefas. É útil para registrar as horas para faturação e poderá apresentar as horas registradas por tarefa e por dia.

Nesta altura, o histórico poderá ser exportado como um arquivo de texto separado por vírgulas para poder ser importado em outras ferramentas de faturação e/ou gerenciamento de projetos.

O &karm; detecta quando o seu teclado e mouse ficam inativos e poderá associar várias tarefas com áreas de trabalho diferentes, ou seja, duas ferramentas que poderão ajudar a manter o relógio em funcionamento na tarefa correta.

O &karm; foi originalmente criado pelo &Sirtaj.Singh.Kang;. A palavra karm significa trabalho ou deveres na língua nativa do autor - o Punjabi -, e é a mesma palavra (mas com uma transliteração melhorada) que karma.

## Usando o &karm;

### Iniciando o &karm;

Digite `ktimetracker` numa linha de comando ou selecione a opção Registro Pessoal do Tempo do menu Utilitários do menu inicial do KDE. As opções normais da linha de comando do &Qt; e do &kde; estão disponíveis e poderão ser listadas ao digitar ``ktimetracker` `--help`` na linha de comando.

O &karm; oferece uma opção adicional da linha de comando que lhe permite indicar o nome do arquivo iCalendar que é usado para guardar o seu histórico de trabalho. Você poderá indicar um arquivo iCalendar remoto se usar o 'http' ou o 'ftp' como parte do nome do arquivo, como por exemplo http://www.exemplo.com/meus_dados/meu_trabalho.ics.

### Tarefas

Problema: Você é um consultor com vários clientes. Alguns dos clientes possuem vários projetos. Ao longo do dia, você alterna entre diferentes projetos. Você precisa registrar o seu tempo para gerar faturas mensais.

Solução: Crie uma tarefa de topo para cada cliente e uma sub-tarefa para cada projeto do cliente. Para os projetos que necessitem de um registro mais detalhado, crie uma lista de sub-tarefas do projeto. Registre o tempo, fazendo duplo-clique na tarefa em que está trabalhando no momento.

O &karm; oferece uma grande flexibilidade ao registrar o seu tempo, permitindo quantidades e profundidades de tarefas ilimitadas. O tempo poderá ser registrado para qualquer tarefa e poderá existir mais de uma tarefa ativa a qualquer momento.

Para criar uma tarefa de topo, selecione &Ctrl;N Tarefa Nova Para criar uma sub-tarefa, selecione a tarefa-mãe e selecione &Ctrl;&Alt;N Tarefa Nova Sub-tarefa

Quando o &karm; sair, a lista de tarefas é salva no arquivo indicado em Configurações Configurar o KArm . Na próxima vez que for iniciado, ele recarrega a lista de tarefas do mesmo arquivo.

O &karm; poderá importar e exportar as tarefas para minimizar o seu trabalho. Veja os Outros Sistemas.

### Cronômetros

Problema: Para se manter rentável, você precisa faturar uma média de cinco horas por dia. Para manter a o controle, você vigia os seus totais diários e semanais.

Solução: Reinicie o temporizador da sessão no início de cada dia de trabalho e reinicie todos os temporizadores no início de cada semana.

O &karm; torna o registro do tempo simples. Para começar a registrar o tempo relacionado com uma tarefa, faça um duplo-clique nela. Para parar o tempo do registro, volte a fazer duplo-clique na tarefa. As tarefas ativas mostram um pequeno relógio na coluna do Tempo de Sessão.

Outra pista visual da atividade de registro é o ícone do &karm; na área de notificação. Quando uma tarefa ficar ativa, o segundo ponteiro do ícone começa a mover-se. Se você deixar ficar o cursor do mouse sobre este ícone, o nome da tarefa ativa irá aparecer numa dica. Se mais de uma tarefa estiver ativa, os nomes das tarefas na dica ficam separados por vírgulas.

O &karm; mantém dois temporizadores para cada tarefa: um para o tempo da sessão e outro para o tempo total. Na configuração padrão, o &karm; mostra duas colunas para cada temporizador, resultando num total de quatro colunas por cada tarefa:

Tempo da Sessão

  O tempo gasto na tarefa desde que a sessão começou.

Tempo Total da Sessão

  O tempo gasto na tarefa, e em todas as suas sub-tarefas, desde que a sessão começou.

Tempo

  O tempo gasto na tarefa desde que os tempos foram reiniciados.

Tempo Acumulado

  O tempo gasto na tarefa, e em todas as suas sub-tarefas, desde que os tempos foram reiniciados.

Para iniciar uma nova sessão, selecione Arquivo Iniciar Nova Sessão

Para reiniciar todos os tempos, selecione Arquivo Reiniciar Todos os Tempos

#### Registro da Área de Trabalho

Problema: Você possui dois projetos principais nos quais alterna em cada dia. Para ajudá-lo a organizar o seu trabalho, você mantém os seus arquivos do projeto 1 na Área de Trabalho 1 e os arquivos do projeto 2 no Área de Trabalho 2.

Solução: Associe a tarefa do projeto 1 com a Área de Trabalho 1 e a tarefa do projeto 2 com a Área de Trabalho 2. Quando você mudar da Área de Trabalho 2 para a1, o &karm; pára automaticamente a tarefa do projeto 2 e começa a tarefa do projeto 1.

Para associar uma tarefa com uma ou mais áreas de trabalho, selecione a opção &Ctrl;E Tarefa Editar . Ative o Registro automático e selecione a área ou áreas de trabalhoo a associar com esta tarefa. Quando qualquer uma das áreas de trabalho selecionadas ficar ativa, o &karm; irá automaticamente começar o registro para esta tarefa.

#### Detecção de Ausência de Atividade

Problema: Você sai do trabalho cedo na Sexta e se esquecede parar o temporizador. Quando você voltar na Segunda-Feira, o relógio ainda está trabalhando.

Solução: Ative a detecção de inatividade.

O &karm; pode ser configurado para detectar quando o mouse e o teclado ficam inativos. Se o mouse e o teclado ficarem inativos durante mais do que o número de minutos indicado, o &karm; mostra a seguinte janela:

Detecção de Inatividade do &karm;
Janela de Detecção de Inatividade do &karm;

Reverter & Parar

  Subtrai a quantidade de tempo inativo de todos os temporizadores ativos e interrompe-os.

  Você não estava trabalhando na tarefa enquanto o seu computador estava inativo e você continua a não estar.

Reverter & Continuar

  Subtrai a quantidade de tempo inativo de todos os temporizadores ativos mas mantêm-os funcionando.

  Você não estava trabalhando na tarefa enquanto o seu computador estava inativo mas agora já está.

Continuar Contagem do Tempo

  Aplicar o tempo de inatividade a todos os temporizadores ativos e mantêm-os rodando.

  Você estava trabalhando nas tarefas enquanto o seu computador estava ativo e ainda continua.

### Relatórios

O &karm; oferece três formas de relatar o tempo que registrou. Você poderá enviar os tempos totais e da sessão para a impressora, copiá-los para a área de transferência ou copiar o histórico do tempo também para a área de transferência.

#### Imprimir os Totais

Para gerar o relatório dos totais para a impressora, selecione a opção &Ctrl;P Arquivo Imprimir . Isto gera um relatório de três colunas com a lista completa das tarefas. A primeira coluna é o nome da tarefa, a segunda é o Tempo Total da Sessão e a terceira é o Tempo Total.

#### Totais na Área de Transferência

Para gerar o relatório dos totais para a área de transferência, selecione a opção &Ctrl;C Arquivo Copiar os Totais para a Área de Transferência .

Este relatório é gerado para a tarefa atualmente selecionada e para todas as suas sub-tarefas. Se a tarefa for de topo, o &karm; pergunta se deseja gerar o relatório para a tarefa atual e para as suas sub-tarefas ou para toda a lista de tarefas.

&karm; Copiar esta Tarefa
Janela do &karm; para Copiar esta Tarefa

Logo que o relatório seja gerado, abra o &kedit; ou outro editor de texto e cole os dados do relatório.

    Totais das Tarefas
    2004-07-10 02:26

      Tempo    Tarefa
    ----------------------------------------------
      9:14    kde
       9:14    karm
        1:08    erros
        0:00    enviar alterações
       0:00    promoção
       0:00    coisas da Web
    ----------------------------------------------
      9:14 Total

A primeira coluna é o Tempo Total e está indentado (como os nomes das tarefas) para indicar as relações de tarefas/sub-tarefas. Os tempos indicados incluem os tempos das sub-tarefas.

#### Histórico na Área de Transferência

Para gerar os relatórios dos totais para a área de transferência, selecione a opção &Ctrl;&Alt;C Arquivo Copiar o Histórico para a Área de Transferência .

Você precisa ativar a opção Registro histórico em Configurações Configurar o KArm . Caso contrário, o &karm; só mantém um registro dos totais e não um histórico de tarefas detalhado.

Este relatório é gerado para a tarefa atualmente selecionada e para todas as suas sub-tarefas. Você possui também a opção de gerá-lo para todas as tarefas.

Quando você selecionar o relatório do histórico, o &karm; solicitará primeiro para indicar o intervalo de datas do relatório:

&karm; Inserção do Intervalo de Datas
&karm; Inserção do Intervalo de Datas

Após indicar um intervalo de datas, abra o &kedit; ou outro editor de texto e cole os dados dos relatórios.

    Histórico de Tarefas
    De Quinta 01 de Julho de 2004 até Segunda 12 de Julho de 2004
    Impresso em: 2004-07-12 17:18

                                   Semana de Segunda 05 de Julho de 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   plano de funcionalidades do 3.2
                  1:08                           1:08   erros
                                                 0:00   enviar alterações
                                                 0:00  promoção
                                                 0:00  coisas da Web
    -------------------------------------------------------------------------
                  2:30  1:46  3:14  1:44         9:14 Total

O histórico de tarefas é totalizado para cada dia e tarefa e agrupado por semanas. As primeiras sete colunas vão de Segunda até Domingo. A oitava coluna é o total da semana e a nona coluna é o nome da tarefa. Os nomes das tarefas estão indentados para indicar as relações de tarefas/sub-tarefas.

### Outros Sistemas

#### &korganizer;

O &karm;, como o &korganizer; e o iCal da Apple, usa o padrão da indústria iCalendar para os seus dados. O &karm; pode ler e gravar as listas de pendências criadas por estes dois aplicativos.

Se tanto o &karm; como o &korganizer; tiverem o mesmo arquivo aberto, ao editar o arquivo com o &korganizer;, você poderá arriscar-se a perder dados. Para estar seguro, edite apenas o arquivo com um aplicativo de cada vez.

#### Planner

Como caso de uso típico,você poderá querer planejar um projeto com a ferramenta de gerenciamento de projetos Imendio Planner (from planner.imendio.org) e importar as suas tarefas para o &karm;, de modo a tê-las no formato padrão da indústria iCalendar. Depois de fazer isso, você poderá então agendar as tarefas no &korganizer; e contabilizar o seu tempo para elas no &karm;. Esta é uma forma de controlar se o seu projeto se mantém no seu orçamento e nos seus limites de tempo.

#### &DBus;

O &DBus; é o mecanismo que os programas do &kde; usam para comunicarem-se uns com os outros. Um programa do &kde; oferece uma lista de funções que os outros programas (um programa do Bash, por exemplo) poderão usar.

##### Um programa do Bash que mostra a versão do &karm;

    qdbus org.kde.ktimetracker /KTimeTracker version 2
    >/dev/null || echo "o ktimetracker não está rodando"

A interface atual de &DBus; do &karm; é usada principalmente para testes automatizados, sendo assim bastante limitada. Para a definição completa da interface, veja o Apêndice da Interface de &DBus;.

Para ver a interface completa de &DBus; da versão do &karm; instalada no seu sistema, execute o seguinte programa em Bash:

##### Listar a interface de &DBus; do &karm; no console

    qdbus org.kde.ktimetracker /KTimeTracker 2
    >/dev/null || echo "o ktimetracker não está em execução"

#### Exportar os Totais para CSV

O &karm; pode exportar tanto os totais como o histórico para um formato de arquivo separado por vírgulas. Para exportar os totais, selecione a opção Arquivo Importar/Exportar Exportar para um arquivo CSV... para que o &karm; mostre a seguinte janela de exportação:

Janela de Exportação para CSV do &karm;
Janela de Exportação para CSV do &karm;

Indique o arquivo para o qual desejaria exportar os dados e modifique as outras opções da janela, se necessário. Repare que o intervalo de datas está desativado, uma vez que você vai exportar os tempos totais, não os dados históricos. Clique em Exportar, para o &karm; exportar os totais de todas as tarefas para o arquivo que selecionou.

Aqui está um exemplo do formato do resultado:

    "kde",,,,,0.00,0.00,6.88,9.83
    ,"karm",,,,6.88,8.70,6.88,9.83
    ,,"plano de funcionalidades do 3.2",,,0.00,0.00,0.00,0.00
    ,,"erros",,,0.00,1.13,0.00,1.13
    ,,"enviar alterações - textos de traduções",,,0.00,0.00,0.00,0.00
    ,,"relatório da fatura de tempo",,,0.00,0.00,0.00,0.00
    ,"kopete",,,,0.00,0.00,0.00,0.00
    ,"promoção",,,,0.00,0.00,0.00,0.00
    ,"coisas na Web",,,,0.00,0.00,0.00,0.00

As tarefas de topo são colocadas na primeira coluna, as sub-tarefas na segunda e assim por diante. Os dados dos tempos são apresentados a seguir à profundidade de tarefas máxima (cinco, neste exemplo). A coluna do primeiro tempo é o Tempo de Sessão, a segunda é o Tempo, a terceira é o Tempo Total da Sessão e a quarta é o Tempo Total.

#### Exportar o Histórico para CSV

Para exportar o histórico de tarefas, selecione Arquivo Importar/Exportar Exportar o Histórico para um arquivo CSV... para o &karm; mostrar a mesma janela de exportação que foi apresentada acima.

Insira o nome do arquivo para o qual deseja exportar os dados e selecione o intervalo de datas para o qual deseja o histórico de tarefas. Modifique as outras opções da janela, se necessário e clique em Exportar, para o &karm; exportar o histórico de todas as tarefas para o arquivo que selecionou.

Aqui está um exemplo do formato do resultado:

    Histórico de Tarefas
    De Terça 06 de Julho de 2004 até Terça 13 de Julho de 2004
    Impresso a: 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,,,"plano de funcionalidades do 3.2"
    ,1.13,,,,,,,1.13,,,"erros"
    ,,,,,,,,0.00,,,"enviar alterações - textos de traduções"
    ,,,,,,,,0.00,,,"relatório da fatura de tempo"
    ,,,,,,,,0.00,,"kopete"
    ,,,,,,,,0.00,,"promoção"
    ,,,,,,,,0.00,,"coisas na Web"

As três linhas identificam quando o relatório foi gerado e para que intervalo de datas. A quarta linha é uma lista separada por vírgulas das datas no intervalo definido, no formato ISO 8601 (AAAA-MM-DD). Todas as linhas subsequentes indicam o tempo registrado para cada tarefa. A última coluna numérica é o total da linha ao longo de todos os dias. O nome da tarefa aparece logo após à coluna dos totais e está indentado para indicar a relação de tarefas/sub-tarefas. Os nomes das tarefas de topo aparecem na primeira coluna após o total.

## A interface do &karm;

A janela principal do &karm; possui os seguintes componentes: o menu, a barra de ferramentas, a janela de tarefas/tempos e a barra de estado.

Tela do &karm;
Tela do &karm;

### A janela das Tarefas/Tempos

As várias tarefas são apresentadas nesta janela, juntamente com o tempo acumulado para cada uma na sessão atual e no total. As tarefas que estiverem para ser temporizadas possuem um pequeno ícone de relógio ao lado do tempo de sessão.

Podem ser criadas sub-tarefas para cada tarefa. Clicar no sinal de mais/menos ao lado da tarefa principal, ativa ou desativa a visualização das suas sub-tarefas associadas. O tempo total atingido para uma determinada tarefa inclui os tempos das suas sub-tarefas, assim como o seu tempo acumulado.

### A Barra de Ferramentas

A barra de ferramentas contém ícones para os seguintes comandos:

(Todos se comportam de forma idêntica ao respectivo comando no menu.)

- Iniciar

- Parar

- Novo

- Nova Sub-Tarefa

- Apagar

- Editar

### A Barra de Estado

Reporta o tempo total que já passou na sessão.

## Créditos e Licença

&karm;

Copyright do programa:

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

- 2001-2002 Tomas Pospisek tpo_deb@sourcepole.ch

- 2003-2004 Mark Bucciarellimark@hubcapconsulting.com

Contribuidores (em ordem alfabética)

- 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

O &karm; foi inspirado pelo utilitário criado por Harald Tveit Alvestrand que era o titrax, sendo o único problema dele o fato de ser baseado na plataforma do Xt.

Documentação com 'copyright' 2000-2004 de &Jonathan.Singer; &Jonathan.Singer.mail; e &Sirtaj.Singh.Kang; &Sirtaj.Singh.Kang.mail;.

Tradução de Marcus Gamamarcus.gama@gmail.com

&underFDL; &underGPL;
tarefa ativa

  Uma tarefa com um cronômetro rodando.

&DBus;

  O protocolo de comunicação entre processos usado no &kde;. É uma abreviatura para Desktop COmmunication Protocol.

área de trabalho

  O &GNU;/&Linux;, o FreeBSD e os outros sistemas que rodam o X-Windows possuem várias áreas de trabalho virtuais. Você possui, tipicamente, quatro áreas de trabalho diferentes instalados por padrão. Cada área poderá mostrar o seu conjunto próprio de programas e arquivos. Quando o &kde; inicializa pela primeira vez, a área de trabalho que você vê é a de número 1. Clicando em &Ctrl;F2, você verá a Área de Trabalho 2. Clicar em &Ctrl;F1 irá voltar à Área de Trabalho 1.

histórico

  Se o &karm; estiver configurado para registrar o histórico, ele irá guardar todos os eventos de inicalização/parada dos temporizadores. Este histórico nunca é limpo quando os tempos são reiniciados e continua no arquivo até que a tarefa seja removida.

sessão

  Um ponto de referência definido pelo usuário para os temporizadores de sessão. É iniciada uma nova sessão quando você selecionar a opção Arquivo Iniciar Nova Sessão . Os dados da sessão não são salvos quando você cria uma nova.

Tempo da Sessão

  O tempo gasto na tarefa desde que a sessão começou.

área de notificação

  A área de notificação é a barra que aparece (por padrão) na base do tela. Nesta área de notificação , o ícone do &karm; está mais à direita.

tarefa de topo

  Uma tarefa sem tarefa-mãe.

Tempo Total da Sessão

  O tempo gasto na tarefa, e em todas as suas sub-tarefas, desde que a sessão começou.

Tempo

  O tempo gasto na tarefa desde que os tempos foram reiniciados.

Tempo Acumulado

  O tempo gasto na tarefa, e em todas as suas sub-tarefas, desde que os tempos foram reiniciados.

## Instalação

### Como obter o &karm;

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

## A Interface &DBus;

version

### version

Retorna a versão do &karm;.

    QString version()

#### Descrição

O `version()` é uma chamada de &DBus; que devolve o número de versão do &karm;, como por exemplo 1.5.0. O número de versão é devolvido como um texto no formato típico da &GNU; maior.menor.correção.

quit

### quit

Sai do &karm;.

    QString quit()

#### Descrição

O `quit()` é uma chamada de &DBus; que oferece a possibilidade a um programa externo fazer com que o &karm; termine em segurança.

hastodo

### hastodo

Verifica se o item por-fazer de topo existe.

    QString hastodo(QString nomeTarefa)

#### Parâmetros

`nomeTarefa`

  O nome do item por-fazer a procurar.

#### Descrição

O `hastodo(QString nomeTarefa)` é uma chamada de &DBus; que procura por um item por-fazer com o nome indicado. Se for encontrado, devolve o UID do iCalendar que identifica este item. Se não for encontrado, devolve um texto vazio.

O arquivo iCalendar que o &karm; possui atualmente aberto é o arquivo que será pesquisado. Todas as árvores de itens por-fazer serão pesquisadas, não apenas os de topo. Se mais de um item por-fazer corresponder a esse nome, será devolvido o primeiro.

addtodo

### addtodo

Adiciona um novo item por-fazer.

    QString addtodo(QString nomeItem)

#### Parâmetros

`nomeItem`

  O nome do novo item por-fazer.

#### Descrição

O `addtodo(QString nomeItem)` é uma chamada de &DBus; que adiciona um novo item por-fazer de topo ao arquivo atual. É devolvido o UID do novo item por-fazer.

&documentation.index;