# Manuel de &kalarm;

## Introduction

&kalarm; est un programmateur personnel de messages d'alarme et de commandes. Il vous permet de planifier des messages de réveil-matin ou de pense-bête personnels qui surgissent sur l'écran à l'heure prévue, ou de paramétrer des commandes à exécuter.

S'il est lancé dans son mode graphique par défaut, &kalarm; affiche une liste d'alarmes planifiées, avec leur heure et leurs caractéristiques. Vous pouvez créer de nouvelles alarmes, ou sélectionner des alarmes existantes afin de les modifier ou de les annuler.

Lorsque vous mettez en place ou modifiez une alarme, vous pouvez soit saisir le texte de l'alarme, soit indiquer un fichier de texte à afficher, ou alors indiquer une commande à exécuter. Vous pouvez également choisir la couleur du message d'alarme, indiquer s'il doit se répéter, indiquer s'il doit jouer un son, et indiquer si l'alarme doit être annulée si le message n'a pas pu être déclenché à l'heure prévue.

Les alarmes peuvent également être planifiées depuis la ligne de commande ou par le moyen d'appels &DCOP; depuis d'autres programmes.

Quand un message d'alarme est déclenché, il s'affiche sur chaque bureau virtuel de &kde; afin de s'assurer que vous ne le manquerez pas. La fenêtre de message affiche l'heure à laquelle le message était prévu. Il propose en général une option de remise à plus tard permettant de demander à l'alarme de se réafficher plus tard. Voici un exemple de message d'alarme :

Copie d'écran de la fenêtre de message de &kalarm; Message d'alarme

Quand l'alarme indique une commande à exécuter, &kalarm; n'affiche rien.

&kalarm; peut fonctionner de deux manières différentes : en continu (par défaut), où il fonctionne depuis la boîte à miniatures de &kde;, ou à la demande où il est exécuté quand c'est nécessaire (avec la possibilité d'afficher une icône indépendante dans la boîte à miniatures).

Ce document évoque souvent le démon d'alarme. Il s'agit d'une application qui tourne en arrière-plan, en vérifiant les alarmes en attente et en indiquant à &kalarm; de les afficher quand elles arrivent à échéance.

## Utilisation de &kalarm;

### Mode graphique

Lorsqu'il est lancé sans arguments de ligne de commande, &kalarm; démarre en mode graphique. Il affiche la liste actuelle des alarmes en attente, avec pour chacune l'heure, l'intervalle de répétition, la couleur, ainsi que le texte du message, le nom du fichier à afficher ou de la commande à exécuter. (L'heure affichée pour une alarme à répétition est celle du prochain déclenchement prévu). Une icône à gauche de chaque alarme (texte/fichier/commande) indique le type d'alarme.

Copie d'écran de la fenêtre principale de &kalarm; Fenêtre principale

Pour les alarmes à répétition, la liste affiche la prochaine heure de déclenchement prévue ainsi que le nombre de fois que l'alarme doit se répéter ensuite.

Les alarmes peuvent être triées par date et heure, par intervalle de répétition, par couleur, ou par texte en cliquant dans la barre de titre sur la colonne appropriée. Pour inverser l'ordre de tri, cliquez une seconde fois dans la barre de titre.

Lorsque &kalarm; démarre en mode graphique, il vérifie que le démon d'alarme est en cours d'exécution. Si ce n'est pas le cas, &kalarm; le lance.

#### Comment ajouter une nouvelle alarme

Pour ajouter une nouvelle alarme, choisissez Actions Nouveau.... Cela affiche la boîte de dialogue de paramétrage de l'alarme décrite ci-dessous.

#### Comment modifier une alarme existante

Pour modifier une alarme existante, utilisez une des méthodes ci-dessous :

- Double-cliquez sur sa ligne dans la liste des alarmes.

- Sélectionnez-la en cliquant sur sa ligne dans la liste des alarmes. Choisissez alors Actions Modifier....

- Cliquez avec le &BDS; sur sa ligne dans la liste d'alarmes et choisissez Modifier.. dans le menu contextuel.

Cela affiche la boîte de dialogue de paramétrage de l'alarme :

Copie d'écran de la boîte de dialogue de modification d'une alarme Boîte de dialogue de modification d'une alarme

Dans le groupe d'options Action, choisissez soit Texte pour saisir le texte du message (qui peut comprendre des sauts de lignes) dans la zone de saisie, soit Fichier pour saisir le nom ou l'&URL; d'un fichier de texte dont le contenu s'affichera dans le message d'alarme, soit Commande pour saisir une commande de l'interpréteur à exécuter. Lorsque Fichier est choisi, le bouton à droite de la zone de saisie peut être utilisé pour afficher la boîte de dialogue de sélection de fichier.

Si l'alarme est une alarme à répétition et si elle a été différée après son dernier affichage, le groupe d'options Alarme différée affiche l'heure à laquelle l'alarme différée doit se déclencher. Le bouton Modifier... affiche une boîte de dialogue qui vous permet de modifier l'heure différée ou d'annuler le report à plus tard.

Dans le groupe d'options Heure, choisissez soit

- À la date et l'heure : pour saisir la date et l'heure auxquelles l'alarme doit se déclencher. Cochez la case N'importe quand si vous désirez n'indiquer qu'une date pour l'alarme. Dans ce cas, l'alarme sera affichée à cette date à la première occasion à partir de l'heure de début de la journée telle qu'elle a été configurée. La section Comment configurer les options par défaut indique comment régler l'heure de début de la journée.

- Durée à partir de maintenant : pour indiquer dans combien de temps (en nombre d'heures et de minutes) l'alarme doit se déclencher.

Indiquez si et comment l'alarme doit se répéter dans le groupe d'options Répétition.

- Pour que l'alarme ne se déclenche qu'une fois, choisissez Pas de répétition.

- Choisissez Répéter à la connexion pour déclencher l'alarme à chaque fois que vous vous connectez jusqu'à l'heure prévue. Il convient de remarquer qu'une alarme répétée à la connexion sera également déclenchée chaque fois que vous activez les alarmes, ou que vous redémarrez ou réinitialisez le démon d'alarme.

- Choisissez Répétition pour déclencher l'alarme à intervalles réguliers. Il vous faut alors indiquer les paramètres de répétition dans l'onglet Répétition.

  Dans le groupe d'options Règles de répétition, réglez l'intervalle de répétition en choisissant un des types d'intervalles et en saisissant dans répéter tous / toutes les : combien d'intervalles de temps doivent écouler entre les répétitions. Par exemple, pour répéter chaque quinzaine, vous pouvez choisir Jours et saisir une valeur de 14, ou choisir Semaines et saisir une valeur de 2. Des options additionnelles sont proposées en fonction de l'intervalle de temps :

  - pour une répétition hebdomadaire, cochez chaque jour de la semaine où vous souhaitez que l'alarme se déclenche,

  - pour une répétition mensuelle, vous pouvez choisir soit une date fixe, soit une position dans le mois, comme le second mardi du mois,

  - pour une répétition annuelle, vous pouvez choisir soit une date fixe dans l'année, soit une position dans un mois (&pex; le dernier samedi de mai).

  Dans le groupe d'options Fin de la répétition, réglez la période globale de répétition de la manière suivante :

  - choisissez Pas de fin pour continuer les répétitions indéfiniment,

  - choisissez Arrêter après : pour indiquer le nombre total d'occurrences de l'alarme,

  - choisissez Finir le : pour indiquer jusqu'à quelle date et quelle heure l'alarme se répétera.

La case à cocher Annuler si trop tard détermine ce qui se passe lorsque l'alarme ne peut pas se déclencher à l'heure prévue. Cochez cette case si elle ne peut pas être déclenchée pendant la minute qui suit le moment prévu. Laissez cette case non cochée pour déclencher l'alarme à la première occasion suivant le moment prévu. Les alarmes basées sur la date seulement, &cad; celles pour qui l'option N'importe quand est activée, seront annulées si elles ne peuvent pas s'afficher pendant les 24 heures qui suivent le début de la journée correspondant à la date prévue.

Une alarme ne peut se déclencher que si vous êtes connecté, et que lorsque X et le démon d'alarme sont tous les deux en cours d'exécution.

La case à cocher Demande de confirmation de la réception vous permet de préciser si vous souhaitez vous voir demander une confirmation lorsque vous fermez la fenêtre d'alarme. Cette option peut être utilisée préventivement contre une confirmation accidentelle des alarmes.

Cochez la case Son si vous souhaitez qu'une sonnerie audible accompagne le message d'alarme lorsqu'il s'affiche. Par défaut on entend un bip sonore ; utilisez le bouton de droite pour choisir un fichier audio à jouer. Pour revenir au bip, cliquez une seconde fois sur le bouton. Pour voir quel est le son actuellement choisi, survolez le bouton avec le curseur de la souris jusqu'à ce qu'une bulle d'aide apparaisse.

Choisissez la couleur de fond pour la fenêtre du message d'alarme.

Appuyez sur le bouton OK quand tous les détails sont correctement réglés afin d'ajouter l'alarme à la liste des alarmes prévues.

#### Comment détruire une alarme existante

Pour annuler une alarme existante, choisissez une des méthodes suivantes :

- Choisissez-la en cliquant sur sa ligne dans la liste des alarmes. Choisissez ensuite Actions Supprimer .

- Cliquez avec le &BDS; sur sa ligne dans la liste des alarmes et choisissez Supprimer dans le menu contextuel qui apparaît.

#### Comment confirmer la réception d'une alarme

Reportez-vous à la section sur la fenêtre de message d'alarme pour savoir comment confirmer la réception d'une alarme.

#### Comment afficher &kalarm; dans la boîte à miniatures

Vous devez utiliser le bureau &kde; pour afficher &kalarm; dans la boîte à miniatures. Si &kalarm; fonctionne en mode continu, la miniature est affichée en permanence. Les instructions qui suivent s'appliquent uniquement au mode à la demande. (Reportez-vous à Comment régler les options par défaut pour une description des différents modes d'exécution).

Pour afficher &kalarm; dans la boîte à miniatures de &kde;, choisissez Affichage Afficher la miniature dans la boîte à miniatures .

Pour retirer &kalarm; de la boîte à miniatures &kde;, utilisez l'une des méthodes suivantes :

- choisissez Affichage Retirer la miniature de la boîte à miniatures,

- cliquez avec le &BDS; sur la miniature et choisissez Quitter dans le menu contextuel qui apparaît.

L'utilisation de la miniature est décrite ci-dessous.

#### Comment activer ou désactiver la surveillance des alarmes

##### Comment activer la surveillance des alarmes

Tout d'abord, si &kalarm; fonctionne en mode continu et si vous avez choisi Désactiver les alarmes lorsqu'il ne fonctionne pas dans la boîte de dialogue de configuration, vous devez vous assurer que &kalarm; fonctionne pour que la surveillance des alarmes soit assurée.

Ensuite, si la gestion des alarmes est actuellement désactivée, utilisez une des méthodes suivantes :

- Choisissez Actions Alarmes activées.

- Cliquez avec le &BDS; sur la miniature et choisissez Activer les alarmes dans le menu contextuel qui apparaît.

Le démon d'alarme est lancé quand c'est nécessaire, et les alarmes seront surveillées de façon à se déclencher au moment opportun.

Le lancement du démon d'alarme affectera toutes les autres applications qui utilisent le démon d'alarme.

##### Comment activer la surveillance des alarmes

Il y a plusieurs façons de désactiver la surveillance des alarmes, ce qui empêche &kalarm; d'afficher des alarmes jusqu'à ce que vous les réactiviez, ou, dans le cas où le démon d'alarme est réglé pour se lancer à la connexion, jusqu'à ce que vous vous reconnectiez.

Pour désactiver les alarmes sans arrêter le démon d'alarme (et ainsi sans affecter les autres applications qui utilisent ce démon d'alarme), utilisez une des méthodes suivantes :

- choisissez Actions Alarmes Activées,

- cliquez avec le &BDS; sur la miniature et choisissez Alarmes activées dans le menu contextuel qui apparaît,

- si &kalarm; s'exécute en mode continu et si vous avez coché Désactiver les alarmes lorsqu'il ne fonctionne pas dans la boîte de dialogue de configuration, sortez de &kalarm;.

Pour désactiver les alarmes en arrêtant le démon d'alarme :

- choisissez Configuration Contrôler le démon d'alarme.... Cela affiche la boîte de dialogue du gestionnaire de services, ce qui vous permet d'arrêter le démon d'alarme.

Cela affectera toute autre application qui utiliserait le démon d'alarme.

#### Comment rafraîchir les alarmes

Dans le cas improbable où une alarme n'aurait pas été déclenchée alors qu'elle aurait dû l'être, vous pouvez rafraîchir la liste des alarmes et déclencher les alarmes manquées en choisissant Actions Rafraîchir les alarmes .

&kalarm; redéclenche les alarmes manquées en réinitialisant le démon d'alarme, ceci est décrit dans la section sur le démon d'alarme.

#### Comment contrôler le démon d'alarme

Pour agir sur le démon d'alarme, choisissez Configuration Contrôler le démon d'alarme.... Cela affiche la boîte de dialogue du gestionnaire de services, qui vous permet de démarrer ou d'arrêter le démon d'alarme et de déterminer s'il se lance automatiquement à la connexion. Reportez-vous à Comment contrôler le démon d'alarme avec le gestionnaire de services pour plus de détails.

#### Comment sortir du programme

Quittez &kalarm; en fermant toutes ses fenêtres et l'icône dans la boîte à miniatures, ou s'il fonctionne en mode continu, en fermant toutes les fenêtres de messages et en choissant Quitter dans le menu contextuel de l'icône.

Fichier Quitter ne ferme que la fenêtre concernée. L'effet de l'élément Quitter du menu contextuel de la miniature dépend, lui, du mode d'exécution. En mode à la demande, il cache la miniature, alors qu'en mode continu il sort du programme.

Le fait de sortir de &kalarm; n'a pas d'effet sur le démon d'alarme, qui, s'il est déjà actif, continuera a surveiller les alarmes prévues, et demandera leur affichage quand elles arriveront à échéance (à moins que vous n'ayez choisi Désactiver les alarmes lorsqu'il ne fonctionne pas dans la boîte de dialogue des préférences).

### La fenêtre des messages d'alarme

Lorsqu'un message d'alarme arrive à échéance, il est affiché sur chaque bureau de &kde; et ne peut pas être recouvert par des fenêtres ordinaires, afin d'être sûr que vous le voyez bien. La fenêtre de message affiche l'heure à laquelle l'alarme était programmée, de façon que vous puissiez voir quand elle est apparue si vous étiez parti à ce moment là.

Dans le cas d'une alarme répétitive, si une fenêtre de message reste non validée d'une occurrence prédécente de l'alarme, la fenêtre existante est simplement réaffichée lorsque l'alarme se produit. Cela évite de devoir accuser réception de plusieurs exemplaires du même message, dans le cas où ne voudriez ou ne pourriez pas accuser réception d'un message au moment où il apparaît.

Quand une fenêtre de message d'alarme est affichée, utilisez une des méthodes suivantes :

- Accusez réception en actionnant le bouton Fermer. Cela fermera la fenêtre (après une demande de confirmation, si vous avez choisi Demande de confirmation de la réception).

- Affichez les options pour différer l'alarme en cliquant sur le bouton Différer.... Sélectionnez ensuite Différer à (date / heure) pour saisir la date et l'heure à laquelle le message doit être réaffiché, ou sélectionnez Différer (durée) pour saisir le temps au bout duquel le message doit être réaffiché (en heures et minutes). Cliquez ensuite sur OK pour différer le message d'alarme.

  Si l'alarme se répète régulièrement, l'heure à laquelle elle est reportée doit être plus antérieure que l'heure de la prochaine répétition prévue.

  Le bouton Différer... n'est pas disponible lorsqu'une alarme est affichéee à la reconnexion, suite à l'activation de l'option Répéter à la connexion.

Le bouton affichant l'icône de &kalarm; permet d'appeler &kalarm; aisément. Le fait de cliquer dessus n'a pas d'effet sur la fenêtre de l'alarme.

### L'icône de la boîte à miniatures

&kalarm; peut être exécuté comme icône dans la boîte à miniatures de &kde;. Cette icône permet d'activer &kalarm; en un seul clic, et fournit à la fois le contrôle et des indications d'état de la surveillance des alarmes. Une icône normale de &kalarm; indique que les alarmes sont surveillées, alors qu'une croix rouge sur l'icône indique que les alarmes ne le sont pas.

Cliquez avec le &BGS; sur la miniature pour cacher ou au contraire afficher la fenêtre principale de &kalarm;.

Cliquez avec le &BDS; sur la miniature pour afficher son menu contextuel :

Activer les alarmes

- Active la surveillance des alarmes.

  voir Activer/désactiver la surveillance des alarmes pour plus d'informations.

Alarmes activées

- Désactive la surveillance des alarmes

  voir Activer/désactiver la surveillance des alarmes pour plus d'informations.

Configurer &kalarm;...

- Affiche la boîte de dialogue de configuration de &kalarm;.

  La boîte de dialogue de configuration est décrite dans Configurer les options par défaut. Elle inclut des options relatives à l'icône de la boîte à miniatures de &kalarm;.

Contrôler le démon d'alarme...

- Affiche la boîte de dialogue du gestionnaire de services qui vous permet de contrôler le démon d'alarme.

  Voir Contrôler le démon d'alarme avec le gestionnaire de services pour plus d'informations.

Réduire / restaurer

- Restaure ou minimise la fenêtre principale de &kalarm;.

  Cette option n'est disponible si le mode de fonctionnenent est continu (voir Configurer les options par défaut pour une description des modes de fonctionnement).

Quitter

- Ferme l'icône de &kalarm; dans la boîte à miniatures.

  En mode de fonctionnement continu, ceci ferme également toutes les fenêtres principales de &kalarm;. Ça n'a aucun effet sur la surveillance des alarmes par le démon d'alarmes (à moins que vous n'ayez sélectionné Désactiver les alarmes lorsqu'il ne fonctionne pas dans la boîte de dialogue de configuration).

### Comment configurer les options par défaut

Pour régler les options par défaut de &kalarm;, sélectionnez Configuration Configurer &kalarm;. Ceci affiche la boîte de dialogue de configuration. La section Général vous permet de contrôler le comportement global de &kalarm; :

- Spécifiez le mode de fonctionnement. Vous pouvez choisir soit de fonctionner en continu dans la boîte à miniatures de &kde;, soit de fonctionner uniquement à la demande. Cette sélection n'affecte pas l'affichage des alarmes lorsqu'elles arrivent à échéance, puisque c'est le démon d'alarmes et pas &kalarm; qui surveille la liste des alarmes. Faire fonctionner &kalarm; dans la boîte à miniatures rend l'application plus accessible et affiche une indication sur l'activation ou non des alarmes, mais faire fonctionner une application en continu consomme plus de ressources système. Donc si les performances de votre système sont une priorité, l'option À la demande est préférable.

  Lorsque le fonctionnement est à la demande, l'icône dans la boîte à miniatures peut tout de même être affichée. La différence principale entre les deux modes de fonctionnement est que lorsque vous fermez l'icône en mode à la demande, ceci n'a aucun effet sur les fenêtres de &kalarm;, tandis qu'en mode continu, fermer l'icône ferme également toutes le fenêtres principales de &kalarm;.

- Si vous spécifiez que &kalarm; soit fonctionner en mode continu, vous pouvez désactiver toutes les alarmes à venir alors que &kalarm; ne fonctionne pas.

- Spécifiez si l'icône de &kalarm; dans la boîte à miniatures doit être affichée à la connexion.

- Configurez l'intervalle de rafraîchissement de l'icône de &kalarm; dans la boîte à miniatures pour refléter si les alarmes sont actuellement surveillées ou non. Ceci implique la vérification du fonctionnement du démon d'alarmes.

- Réglez la date de démarrage pour les alarmes ne s'activant qu'avec la date, &cad; celles pour lesquelles l'option n'importe quand a été sélectionnée. À la date d'échéance, de telles alarmes seront déclenchées à la première opportunité durant les 24 heures à partir de la date de démarrage.

- Spécifiez si on doit vous demander confirmation chaque fois que vous supprimez une alarme.

Les sections Options par défaut et Apparence vous permettent de choisir les valeurs par défaut pour les options dans la boîte de dialogue d'édition des alarmes :

- réglez la police par défaut et la couleur de fond à utiliser pour les messages d'alarme,

- réglez l'état par défaut des cases à cocher Annuler si trop tard et Demande la confirmation de la réception,

- réglez le bip par défaut pour l'option son,

- réglez la période de répétition par défaut pour les alarmes répétitives.

### Opération en ligne de commande

Lorsque des paramètres en ligne de commande sont fournis, &kalarm; n'affiche pas la liste des alarmes programmées comme décrit dans le mode graphique ci-dessus. Les options en ligne de commande spécifiques à &kalarm; peuvent être utilisées pour réaliser les opérations suivantes :

- programmer une nouvelle alarme,

- contrôler le démon d'alarmes,

- contrôler les modes d'affichage de &kalarm;,

- obtenir de l'aide.

Des options en ligne de commande supplémentaires sous fournies principalement pour permettre à d'autres programmes d'être interfacés avec &kalarm;. Elles sont décrites dans le chapitre Guide du développeur de &kalarm;.

La ligne de commande ne doit contenir que des options applicables à une des opérations de &kalarm;. Si vous voulez effectuer des opérations multiples, vous devez invoquer &kalarm; plusieurs fois avec une seule option à chaque fois.

#### Programmer une nouvelle alarme

Les options suivantes sont utilisées pour programmer une nouvelle alarme :

Option | Description
`-a`, `--ack-confirm` | Demande une confirmation lorsque le message d'alarme est accusé réception.
`-b`, `--beep` | Émet un bip lorsque le message est affiché. `--sound` ne doit pas être présent su cette option est spécifiée.
`-c`, `--color`, `--colour `couleur`` | Règle la couleur de fond du message à la couleur &Qt; spécifiée ou son code hexadécimal 0xRRGGBB.
`-e`, `--exec `ligne_de_commande`` | Spécifie une ligne de commande shell à exécuter. Si spécifiée, cette option doit être la dernière option de &kalarm; dans la ligne de commande de &kalarm; Tous les autres paramètres de commande et options suivantes sont interprétés comme formant la ligne de commande à exécuter. `--file` ne peut pas être spécifié avec cette option. `--ack-confirm`, `--beep` et `--color` sont ignorées avec cette option.
`-f`, `--file `URL`` | Spécifie le nom, l'&URL; ou le fichier texte dont le contenu doit former le message d'alarme. `message` ne doit pas être présent si cette option est spécifiée.
`-i`, `--interval `period`` | Règle l'intervalle de répétition de l'alarme. Heures/minutes sont spécifiées dans le format `nHnM`, où `n` est un nombre, &pex; 3H30M. Les autres périodes de temps sont spécifiées dans le format `nX`, où `n` est un nombre et `X` est une des lettres suivantes : Y (années), M (mois), W (semaines), D (jours). Obligatoire si `--repeat` ou `--until` est spécifié.
`-l`, `--late-cancel` | Annule l'alarme si elle ne peut pas être déclenchée à l'heure correcte.
`-L`, `--login` | Déclenche l'alarme chaque fois que vous vous connectez. `--interval`, `--repeat` et `--until` ne peuvent pas être spécifiés avec cette option.
`-r`, `--repeat `count`` | Nombre de fois que l'alarme doit être déclenchée. Spécifiez -1 pour répéter l'alarme indéfiniment. `--interval` doit être spécifié avec cette option, et `--until` ne peut pas l'être.
`-s`, `--sound `URL`` | Spécifie le nom, l'&URL; ou le fichier audio à jouer lorsque le message d'alarme est affiché. `--beep` ne doit pas être présent si cette option est spécifiée.
`-t`, `--time `date/time`` | Déclenche l'alarme à la date ou à la date et à l'heure spécifiées. Spécifiez une date sans heure dans le format `yyyy-mm-dd` ; spécifiez une date et une heure avec `[[[yyyy-]mm-]dd-]hh:mm` (dans laquelle les champs de date omis prendront par défaut les valeurs du jour).
`-u`, `--until `date/time`` | Répète l'alarme jusqu'à une date ou une date et heure spécifiée. Spécifiez une date sans heure dans le même format que pour `--time`. `--interval` doit être spécifié avec cette option, et `--repeat` ne doit pas apparaître.
`message` | Texte du message à afficher.

Soit un texte de message, soit `--file` ou `--exec` doivent être spécifiés, sauf comme mentionné ci-dessus, toutes les options sont facultatives.

Deux autres exemples qui affichent un message sur plusieurs lignes avec un fond rouge à 10 heures pm le 27 de ce mois sont :

    % kalarm -c red -t 27-22:00 "Penser à\ns'arrêter"
    % kalarm -c 0xFF0000 -t 27-22:00 "Penser à\ns'arrêter"

#### Autres options

Les options suivantes sont utilisées pour réinitialiser ou arrêter le démon d'alarmes, ou pour contrôler les modes d'affichage de &kalarm;.

Voir la section démon d'alarmes pour une dscussion sur la réinitialisation et l'arrêt du démon d'alarmes.

Option | Description
`--reset` | Réinitialise le démon d'alarmes.
`--stop` | Arrête le démon d'alarmes.
`--tray` | Affiche &kalarm; sour forme d'icône dans la boîte à miniatures de &kde;.

Par exemple, pour réinitialiser le démon d'alarmes :

    % kalarm --reset

#### Options d'aide

Les options d'aide suivantes sont communes à tous les programmes &kde; :

Option | Description
`--help` | Affiche un bref texte d'aide sur les options.
`--help-qt` | Montre plusieurs options spécifiques à &Qt;.
`--help-kde` | Montre plusieurs options spécifiques à &kde;.
`--help-all` | Affiche toutes les options.
`--author` | Affiche les noms et les adresses électroniques des auteurs de &kalarm;.
`-v`, `--version` | Affiche les versions actuelles de la bibliothèque &Qt;, de &kde; et de &kalarm;.
`--license` | Affiche des informations sur la licence.

### Le démon d'alarmes

Le démon d'alarmes, &kalarmd;, surveille le fichier de calendrier de &kalarm; contenant lealarmes. Lorsqu'il détermine qu'une alarme arrive à échéance, il demande à &kalarm; de l'afficher, de l'exécuter ou de l'annuler s'il est trop tard et que l'activation avec retard n'a pas été sélectionnée pour cette alarme.

Sous &kde;3, le démon d'alarme peut être également utilisé par d'autres applications, y-compris KOrganizer.

Le démon d'alarme fonctionne en tache de ond, sanserface utilisateur. Il peut être contrôlé comme décrit ci-dessous :

#### Démarrer réinitialiser et arrêter le démon d'alarmes

Le démon d'alarmes est normalement démarré dès la connexion à &kde; (à moins que vous n'ayez utilisé la boîte de dialogue de gestion des services pour désactiver le démarrage automatique), et fonctionne en continu jusqu'à la déconnexion. Si pour une raison quelconque il ne fonctionne pas, la surveillance des alarmes ne se fera pas et &kalarm; n'affichera ou n'exécutera pas les alarmes.

##### Démarrage du démon de alarmes

Pour démarrer le démon d'alarmes, vous pouvez soit exécuter &kalarm; avec son mode graphique par défaut (&cad; sans paramètres en ligne de commande), activer les alarmes en utilisant le menu de l'icône de &kalarm; dans la boîte à miniatures, réinitialiser le démon comme décrit ci-dessous, le démarrer en utilisant la boîte de dialogue de gestion des services (voir Contrôler le démon d'alarmes avec le gestionnaire de services soit exécuter le démon d'alarmes directement depuis la ligne de commande.

    % kalarmd

##### Réinitialisation du démon d'alarmes

Il est également possible de réinitialiser le démon d'alarmes sans l'arrêter. La réinitialisation implique une relecture de la liste des messages dans le fichier de calendrier par le démon d'alarmes et réinitialise les données relatives à &kalarm;.

Pourquoi vouloir réinitialiser le démon d'alarme ? Ceci n'arrive pas souvent, mais si pour une raison quelconque &kalarm; n'était pas capable de démarrer lorsque le démon d'alarmes lui demande d'activer une alarme, l'alarme ne sera jamais affichée ou exécutée jusqu'à ce que le démon d'alarme soit réinitialisé ou redémarré. La réinitialisation est préférable à l'arrêt et le redémarrage du démon d'alarme, puisqu'une réinitialisation n'affectera pas les autres applications qui utilisent le démon d'alarme.

La réinitialisation démarre le démon d'alarme s'il ne fonctionnait pas.

Pour réinitialiser le démon d'alarme, utilisez soit la commande de menu Actions Rafraîchir les alarmes ou saisissez la commande suivante :

    % kalarm --reset

##### Arrêt du démon d'alarmes

En arrêtant le démon d'alarmes, toutes les alarmes suivantes ne seront plus surveillées jusqu'à ce que le démon soit redémarré.

L'arrêt affectera le fonctionnement de toutes les applications qui utilisent également le démon d'alarme. Préférez plutôt une réinitialisation.

Pour arrêter le démon d'alarmes, utilisez la boîte de dialogue de gestion des services (voir Contrôler le démon d'alarme avec le gestionnaire de services), ou saisissez la commande suivante :

    % kalarm --stop

#### Contrôler le démon d'alarme avec le gestionnaire de services

La boîte de dialogue de gestion des services vous permettent de configurer et de contrôler le démon d'alarmes. Vous pouvez :

- configurer s'il fonctionne automatiquement à la connexion.

  Si ni le démon d'alarmes ni &kalarm; ne sont configurée pour fonctionner à la connexion, la surveillance des alarmes ne se produira pas et &kalarm; n'affichera ou n'exécutera pas les alarmes.

- l'arrêter et le démarrer.

  Le démarrage ou l'arrêt du démon d'alarmes affectera toutes les autres applications qui l'utilisent.

Vous pouvez accéder à la boîte de dialogue de gestion des services via l'option de menu Configuration Contrôler le démon d'alarmes, ou via le centre de configuration de &kde;.

## Guide du développeur de &kalarm;

&kalarm; fournit une interface pour pemettre à d'autres applications de demander les fonctions suivantes :

- programmer une nouvelle alarme,

- déclencher ou annuler une alarme déjà programmée,

- annuler une alarme déjà programmée,

- déclencher une alarme déjà activée.

Chacune des fonctions ci-dessus est implémentée à la fois par un appel &DCOP; et par la ligne de commande. Les appels &DCOP; doivent être préférés si &kalarm; fonctionne déjà.

### Interface &DCOP;

cancelEvent

cancelEvent

cancel an already scheduled alarm.

    void cancelEvent(const QString& calendarFile, const QString& eventID)

##### Paramètres

`calendarFile`

- Spécifie l'&URL; d'un fichier calendrier contenant des événements à annuler.

`eventID`

- Spécifie l'identificateur unique de l'événement devant être annulé, comme enregistré dans `calendarFile`.

##### Description

`cancelEvent()` est un appel &DCOP; pour annuler l'alarme spécifiée. &kalarm; supprime l'alarme dans le fichier de calendrier sans l'afficher ou sans l'exécuter.

Le paramètre `calendarFile` n'est utilisé que pour des test d'intégrité : si l'&URL; ne spécifie pas le fichier de calendrier par défaut actuel de &kalarm;, la requête sera ignorée.

L'ancien nom pour cette fonction, `cancelMessage`, a été conservé pour la compatibilité, mais toutes les nouvelles applications devraient utiliser `cancelEvent`.

triggerEvent

triggerEvent

trigger an already scheduled alarm.

    void triggerEvent(const QString& calendarFile, const QString& eventID)

##### Paramètres

`calendarFile`

- Spécifie l'&URL; ou le fichier de calendrier contenant l'événement à activer.

`eventID`

- Spécifie l'identificateur unique à déclencher, comme stocké dans `calendarFile`.

##### Description

`triggerEvent()` est un appel &DCOP; pour déclencher l'affichage immédiat ou l'exécution d'une alarme spécifiée (en fonction de l'heure à laquelle elle est programmé). &kalarm; retrouve l'alarme dans le fichier de calendrier et ensuite l'affiche ou l'exécute.

Si l'alarme est déjà arrivée à échéance, &kalarm; supprime alors les occurrences de l'alarme jusqu'à l'heure courante, et s'il n'y a pas d'alarmes répétitives, l'alarme est supprimée du fichier de calendrier. Si l'alarme n'est pas encore arrivée à échéance, ses occurrences sont inchangées.

Le paramètre `calendarFile` n'est utilisé que pour des test d'intégrité : si l'&URL; ne spécifie pas le fichier de calendrier par défaut actuel de &kalarm;, la requête sera ignorée.

L'ancien nom pour cette fonction, `displayMessage`, a été conservé pour la compatibilité, mais toutes les nouvelles applications devraient utiliser `triggerEvent`.

handleEvent

handleEvent

trigger or cancel an already scheduled alarm.

    void handleEvent(const QString& calendarFile, const QString& eventID)

##### Paramètres

`calendarFile`

- Spécifie l'&URL; du fichier du fichier de calendrier contenant l'événement à afficher/exécuter ou annuler.

`eventID`

- Spécifie l'identificateur unique de l'événement à afficher/exécuter ou annuler, comme stocké dans `calendarFile`.

##### Description

`handleEvent()` est un appel &DCOP; pour afficher/exécuter ou annuler l'alarme spécifiée. &kalarm; retrouve l'alarme dans le fichier de calendrier et ensuite détermine quelle mesure prendre en fonction de l'échéance de l'alarme.

- Si l'alarme n'est pas encore arrivée à échéance, rien ne se passe.

- Si l'alarme est arrivée à échéance, la chose suivante se produit : si le drapeau late-cancel est positionné et que l'alarme est en retard, &cad; l'heure de déclenchement programmé est dépassée depuis plus d'une minute, &kalarm; n'affiche pas ou n'exécute pas l'alarme. Sinon, &kalarm; affiche ou exécute l'alarme. S'il n'y a plus aucune alarme répétitive programmée, alors il supprime l'alarme du fichier de calendrier.

Le paramètre `calendarFile` n'est utilisé que pour des test d'intégrité : si l'&URL; ne spécifie pas le fichier de calendrier par défaut actuel de &kalarm;, la requête sera ignorée.

scheduleMessage

scheduleMessage

schedule a new alarm message.

    bool scheduleMessage(const QString& message, const QDateTime& dateTime, const QColor& bg, int flags, const QString& audioURL)

    bool scheduleMessage(const QString& message, const QDateTime& dateTime, const QColor& bg, int flags, const QString& audioURL, int simpleRepeatType, int interval, int repeatCount)

    bool scheduleMessage(const QString& message, const QDateTime& dateTime, const QColor& bg, int flags, const QString& audioURL, int simpleRepeatType, int interval, const QDateTime& endTime)

##### Paramètres

`message`

- Spécifie le texte du message à programmer.

`dateTime`

- Spécifie la date et l'heure à laquelle le message devra être affiché.

`bg`

- Spécifie la couleur de fond pour afficher le message.

`drapeaux`

- Spécifie le OU logique des drapeaux du message d'alarme désiré. Les bits du drapeau sont ceux définis dans la classe KAlarmEvent dans `msgevent.h`

`audioURL`

- Spécifie le nom ou l'&URL; d'un fichier audio à jouer lorsque le message est affiché.

`simpleRepeatType`

- Spécifie le type de récurrence de l'alarme. Les valeurs admises sont MINUTELY, DAILY, WEEKLY, MONTHLY_DAY, ANNUAL_DATE. Elles sont définies dans la classe KAlarmEvent dans `msgevent.h`.

`interval`

- Spécifie la période (minutes/jours/semaines/mois/années) entre la répétition d'un message d'alarme.

`repeatCount`

- Spécifie le nombre de fois que le message d'alarme doit être affiché. Spécifiez -1 pour répéter l'alarme indéfiniment.

##### Description

`scheduleMessage()` est un appel &DCOP; pour programmer le message d'alarme à afficher à la date et à l'heure spécifiée. Il a trois formes : une pour l'alarme non répétitive, une pour l'alarme répétitive avec un compteur de répétition, et une pour une alarme répétitive avec une heure de fin.

Si l'heure programmée (y-compris les répétitions) est déjà passée, &kalarm; affiche immédiatement le message ou, si le bit du drapeau LATE_CANCEL est positionné, ignore la requête. Si l'heure programmée (ou une répétition) se trouve dans le future, &kalarm; ajoute le message d'alarme dans le fichier de calendrier pour l'afficher plus tard.

Utilisez une séquence de code similaire à ce qui suit pour configurer les paramètres pour l'appel &DCOP; à `scheduleMessage()` pour une alarme non répétitive :

    QString message, audioFile;
    QDateTime dateTime;
    QColor bgColour;
    Q_UINT32 flags;
    . . .
    QByteArray data;
    QDataStream arg(data, IO_WriteOnly);
    arg << message;
    arg.writeRawBytes((char*)&dateTime, sizeof(QDateTime));
    arg.writeRawBytes((char*)&bgColour, sizeof(QColor));
    arg << flags << audioFile;

Utilisez une séquence de code similaire à ce qui suit pour configurer les paramètres pour l'appel &DCOP; à `scheduleMessage()` pour une alarme répétitive :

    QString message, audioFile;
    QDateTime dateTime;
    QColor bgColour;
    Q_UINT32 flags;
    Q_INT32 repeatType, repeatCount, repeatInterval;
    . . .
    QByteArray data;
    QDataStream arg(data, IO_WriteOnly);
    arg << message;
    arg.writeRawBytes((char*)&dateTime, sizeof(QDateTime));
    arg.writeRawBytes((char*)&bgColour, sizeof(QColor));
    arg << flags << audioFile << repeatType << repeatCount << repeatInterval;

scheduleFile

scheduleFile

schedule a new alarm which displays the contents of a text file.

    bool scheduleFile(const QString& URL, const QDateTime& dateTime, const QColor& bg, int flags, const QString& audioURL)

    bool scheduleFile(const QString& URL, const QDateTime& dateTime, const QColor& bg, int flags, const QString& audioURL, int simpleRepeatType, int interval, int repeatCount)

    bool scheduleFile(const QString& URL, const QDateTime& dateTime, const QColor& bg, int flags, const QString& audioURL, int simpleRepeatType, int interval, const QDateTime& endTime)

##### Paramètres

`URL`

- Spécifie le nom ou l'&URL; d'un fichier texte dont le contenu sera affiché dans le message à programmer.

`dateTime`

- Spécifie la date et l'heure programmée à laquelle le fichier devra être affiché.

`bg`

- Spécifie la couleur de fond pour afficher le fichier.

`drapeaux`

- Spécifie le OU logique du drapeau de l'alarme spécifiée. Les bit du drapeau sont ceux définis dans la classe KAlarmEvent dans `msgevent.h`

`audioURL`

- Spécifie le nom ou l'&URL; d'un fichier audio à jouer lorsque le message est affiché.

`simpleRepeatType`

- Spécifie le type de récurrence de l'alarme. Les valeurs admises sont MINUTELY, DAILY, WEEKLY, MONTHLY_DAY, ANNUAL_DATE. Elles sont définies dans la classe KAlarmEvent dans `msgevent.h`.

`interval`

- Spécifie la période (minutes/jours/semaines/mois/années) entre les répétitions de l'alarme.

`repeatCount`

- Spécifie le nombre de fois que l'alarme devra être affichée. Spécifiez -1 pour répéter l'alarme indéfiniment.

##### Description

`scheduleFile()` est un appel &DCOP; pour programmer l'affichage du fichier texte spécifié à la date et à l'heure spécifiée. À part la spécification d'un nom de fichier ou d'une &URL;, son utilisation est identique à `scheduleMessage` - voir la description de cette fonction pour plus de détails.

scheduleCommand

scheduleCommand

schedule a new alarm which executes a shell command.

    bool scheduleCommand(const QString& commandLine, const QDateTime& dateTime, int flags)

    bool scheduleCommand(const QString& commandLine, const QDateTime& dateTime, int flags, int simpleRepeatType, int interval, int repeatCount)

    bool scheduleCommand(const QString& commandLine, const QDateTime& dateTime, int flags, int simpleRepeatType, int interval, const QDateTime& endTime)

##### Paramètres

`commandLine`

- Spécifie la commande shell dont l'exécution doit être programmée.

`dateTime`

- Spécifie la date et l'heure programmée à laquelle la commande doit être exécutée.

`drapeaux`

- Spécifie le OU logique du drapeau de l'alarme désirée. Les bits du drapeau sont ceux définis dans la classe KAlarmEvent dans `msgevent.h`

`simpleRepeatType`

- Spécifie le type de récurrence de l'alarme. Les valeurs admises sont MINUTELY, DAILY, WEEKLY, MONTHLY_DAY, ANNUAL_DATE. Elles sont définies dans la classe KAlarmEvent dans `msgevent.h`.

`interval`

- Spécifie la période (minutes/jours/semaines/mois/années) entre les répétitions de l'alarme.

`repeatCount`

- Spécifie le nombre de fois que l'alarme doit être répétée. Spécifiez -1 pour répéter l'alarme indéfiniment.

##### Description

`scheduleCommand()` est un appel &DCOP; pour programmer la ligne de commande spécifiée à exécuter à la date et à l'heure spécifiée. À part donner la ligne de commande et ommettre la couleur du message et le paramètre du fichier audio, son utilisation est identique à `scheduleMessage` - voir la desctiption de cette fonction pour plus d'informations.

### Interface en ligne de commande

Les options de la ligne de commande sont fournies pour permettre à d'autres programmes (comme le démon d'alarmes) de démarrer &kalarm;, s'il ne fonctionne pas encore, de façon à déclencher ou annuler les alarmes programmées, ou programmer de nouvelles alarmes. Il est préférable d'utiliser les options de la ligne de commande dans ce but car si &kalarm; était démarré sans aucun paramètre de ligne de commande, et si ensuite vous envoyiez des requêtes &DCOP;, il démarrerait dans son mode graphique par défaut, ce qui est clairement indésirable pour une requête d'un programme extérieur.

Les programmes devraient d'abord vérifier si &kalarm; fonctionne déjà. Si c'est le cas, il devraient utiliser les appels &DCOP; pour faire ces opérations.

Les options en ligne de commande pour programmer une nouvelle alarme sont décrites dans le chapitre Utilisation de &kalarm;. Les options pour déclencher et annuler les alarmes programmées sont les suivantes :

Les utilisateurs peuvent également s'ils le souhaitent utiliser ces options en ligne de commande (en supposant qu'ils peuvent fournir les paramètres nécessaires).

Option | Description
`--calendarURL `url`` | Utilise le fichier de calendrier pour spécifier l'&URL;. Cette option n'est utilisée que pour tester l'intégrité. Si l'&URL; ne spécifie aucun fichier de calendrier par défaut actuel de &kalarm;, la requête sera ignorée.
`--cancelEvent `eventID`` | Annule l'événement avec l'identificateur d'événement spécifié.
`--triggerEvent `eventID`` | Active l'événement avec l'identificateur d'événement spécifié. L'action réalisée est la même que pour l'appel &DCOP; triggerEvent().
`--handleEvent `eventID`` | Active ou annule l'événement avec l'identificateur d'événement ID. &kalarm; détermine quelle action effectuer de la même façon que pour l'appel &DCOP; handleEvent().

`--cancelEvent`, `--triggerEvent` et `--handleEvent` sont mutuellement exclusifs. `--calendarURL` est optionnel, mais ne peut être utilisé qu'avec une des trois autres options.

Voici des exemples :

    % kalarm --triggerEvent &kalarm;-387486299.702 --calendarURL file:/home/zaphod/hydra.ics
    % kalarm --cancelEvent &kalarm;-388886299.793

## Questions et réponses

&reporting.bugs; &updating.documentation;

Quels sont les fichiers de configuration utilisés par &kalarm; ?

Le fichier `$KDEHOME/share/config/kalarmrc` contient vos préférences pour &kalarm;.

Le fichier de calendrier qui stocke vos alarmes programmées est `$KDEHOME/share/apps/kalarm/calendar.ics`, à moins qu'un autre fichier de calendrier n'ait été spécifié dans le fichier de configuration.

Si vous changez le fichier de calendrier dans le fichier de configuration, vous devrez également éditer le fichier de configuration `clients` du démon d'alarmes pour enlever les références de l'ancien fichier de calendrier. Ceci devrait être fait tandis que le démon d'alarmes ne fonctionne pas pour éviter d'écraser vos modifications.

Quels fichiers de configuration le démon d'alarmes utilise-t-il ?

Le fichier `$KDEHOME/share/config/kalarmdrc` contient vos préférences du démon d'alarmes.

Le fichier `$KDEHOME/share/apps/kalarmd/clients` contient les détails sur les applications clientes qui ont précédemment été inscrites avec le démon d'alarmes, et leurs fichiers de calendrier.

Quels sont les noms des applications de &kalarm; et du démon d'alarmes ?

Le nom de l'application &kalarm; est kalarm, et le nom de l'application démon d'alarmes est kalarmd. De plus, dans les version de &kde; antérieures à 3.1, il y a une petite application kalarmautostart dont la fonction est de démarrer l'icône de &kalarm; dans la boîtes à miniatures dès la connexion.

## Remerciements et licence

&kalarm;

Programme copyright 2001, 2002 David Jarvie software@astrojar.org.uk

Auteurs du démon d'alarmes :

- Preston Brown pbrown@kde.org

- David Jarvie software@astrojar.org.uk

- Cornelius Schumacher schumacher@kde.org

Documentation copyright 2001, 2002 David Jarvie software@astrojar.org.uk

Traduction française par &EricBischoff; et &LudovicGrossard;.

Remerciements à l'auteur de l'application KAlarm pour &kde; 1, Stefan Nikolaus stefan.nikolaus@stuco.uni-oldenburg.de, qui a gentiment accepté que le nom &kalarm; soit utilisé par cette application &kde;2/&kde;3.

&underFDL; &underGPL;

## Installation

### Comment obtenir &kalarm;

&install.intro.documentation;

&kalarm; est disponible pour &kde; 2 et comme paquetage indépendant pour &kde; 3 depuis http://www.astrojar.org.uk/linux

### Configuration nécessaire

&kalarm; nécessite que les librairies standards de &kde; soient installées (le paquetage `kdelibs`). Pour compiler à partir des sources, vous avez également besoin de &Qt; et des paquetages de développement de `kdelibs`.

&kalarm; utilise environ 12 Mo et le démon d'alarmes utilise environ 2,5 Mo de mémoire pour fonctionner, mais ceci peut varier en fonction de votre plate-forme et de votre configuration.

Vous pouvez trouver une liste des changements dans le fichier `ChangeLog` ou à http://www.astrojar.org.uk/linux/kalarm.html..

### Compilation et installation

Si vous ne pouvez pas obtenir un paquetage de binaires précompilés adapté, vous devez compiler &kalarm; vous-même à partir des sources. Récupérez le paquetage contenant les sources `kdepim-x.x.tar.bz2` ou `kalarm-x.x.tar.bz2` (ou similaire), suivant que vous voulez installer &package; ou simplement &kalarm;. Décompactez-le dans un nouveau dossier en utilisant une commande similaire à ``tar` `xvfj `package.tar.bz2``` et allez dans le dossier qui a été créé.

&install.compile.documentation;

Si vous avez plusieurs versions de &kde; installées (&pex; &kde;2 et &kde;3), il se peut que &kalarm; soit installé dans le mauvais dossier de &kde;. Si nécessaire, vous pouvez donner le dossier de &kde; comme paramètre de ``./configure``. Par exemple, si votre &kde; est installé dans `/opt/kde2` :

``./configure` --prefix=`/opt/kde2``

### Configuration

Il n'y a pas de contraintes de configuration particulières pour paramétrer &kalarm; pour qu'il s'exécute dans l'environnement de bureau &kde;. Une fois que &kalarm; a été exécuté au moins une fois, le démon d'alarmes sera lancé chaque fois que vous vous connectez afin de surveiller les alarmes planifiées.

Pour exécuter &kalarm; dans un environnement de bureau autre que &kde;, la contrainte principale est de s'assurer que le démon d'alarme se lance automatiquement chaque fois que vous vous connectez. Des instructions plus détaillées sont fournies dans le fichier `INSTALL` qui est distribué avec &kalarm;.

&documentation.index;