Exemple : un réveil -- Flash CS3

L'exemple Alarm Clock correspond à une horloge qui permet à l'utilisateur de déterminer l'heure à laquelle l'alarme doit se déclencher et d'afficher un message en même temps. Il repose sur l'application SimpleClock du Utilisation des dates et heures. et illustre de nombreux aspects de l'utilisation des événements dans ActionScript 3.0, notamment les suivants :

Pour obtenir les fichiers d'application pour cet exemple, voir www.adobe.com/go/learn_programmingAS3samples_flash_fr. Les fichiers d'application Alarm Clock se trouvent dans le dossier Samples/AlarmClock. Il s'agit des fichiers suivants :

Fichier	Description
AlarmClockApp.mxml ou AlarmClockApp.fla	Le fichier d'application principal dans Flash (FLA) ou Flex (MXML).
com/example/programmingas3/clock/AlarmClock.as	Classe permettant d'étendre la classe SimpleClock, qui ajoute la fonctionnalité de réveil.
com/example/programmingas3/clock/AlarmEvent.as	Une classe d'événement personnalisé (sous-classe de flash.events.Event), qui sert d'objet événement à l'événement `alarm` de la classe AlarmClock.
com/example/programmingas3/clock/AnalogClockFace.as	Dessine une horloge ronde et les aiguilles des heures, des minutes et des secondes en fonction de l'heure (décrit dans l'exemple SimpleClock).
com/example/programmingas3/clock/SimpleClock.as	Composant d'interface d'horloge doté d'une fonctionnalité simple de mesure temporelle (décrit dans l'exemple SimpleClock).

Sous-rubriques

Présentation du réveil

Dans cet exemple, la principale fonctionnalité de l'horloge (dont la mesure du temps et l'affichage du cadran) réutilise le code de l'application SimpleClock, décrite dans Exemple : une horloge analogique simple. La classe AlarmClock étend la classe SimpleClock de cet exemple en y ajoutant la fonctionnalité de réveil requise : réglage de l'heure de déclenchement et avertissement une fois l'alarme déclenchée.

Le rôle des événements est de fournir un avertissement lorsque se produit quelque chose. La classe AlarmClock expose l'événement Alarme, à l'écoute duquel d'autres objets peuvent être placés afin d'effectuer les actions voulues. En outre, la classe AlarmClock utilise une instance de la classe Timer pour déterminer à quel moment déclencher l'alarme. Comme la classe AlarmClock, la classe Timer fournit un événement pour avertir d'autres objets (une instance AlarmClock dans ce cas) une fois un certain délai écoulé. Comme dans la plupart des applications ActionScript, les événements constituent une part importante de la fonctionnalité de l'exemple Alarm Clock.

Déclenchement de l'alarme

Comme mentionné plus haut, la seule fonctionnalité de la classe AlarmClock est liée à la définition et au déclenchement de l'alarme. La classe intégrée Timer (flash.utils.Timer) permet au développeur de définir du code qui sera exécuté après un délai spécifique. La classe AlarmClock utilise une instance Timer pour déterminer le moment auquel déclencher l'alarme.

    import flash.events.TimerEvent;
    import flash.utils.Timer;

    /**
     * Timer sera utilisé pour l'alarme.
     */
    public var alarmTimer:Timer;
    ...
    /**
     * Instancie une nouvelle AlarmClock d'une taille donnée.
     */
    public override function initClock(faceSize:Number = 200):void
    {
        super.initClock(faceSize);
        alarmTimer = new Timer(0, 1);
        alarmTimer.addEventListener(TimerEvent.TIMER, onAlarm);
    }

L'instance Timer définie dans la classe AlarmClock est nommée alarmTimer. La méthode initClock(), qui effectue les opérations de configuration nécessaires à l'instance AlarmClock, exploite la variable alarmTimer de deux manières. Tout d'abord, la variable est instanciée avec les paramètres indiquant à l'instance Timer d'attendre 0 millisecondes et de déclencher l'événement timer une seule fois. Après instanciation de alarmTimer, le code appelle la méthode addEventListener() de cette variable pour indiquer qu'il veut écouter l'événement timer de cette variable. Le fonctionnement d'une instance Timer repose sur la distribution de l'événement timer après un certain délai. La classe AlarmClock doit savoir quand l'événement timer est distribué afin de déclencher sa propre alarme. En appelant addEventListener(), le code AlarmClock s'enregistre comme écouteur auprès de alarmTimer. Les deux paramètres indiquent que la classe AlarmClock souhaite écouter l'événement timer (indiqué par la constante TimerEvent.TIMER), et que lorsque l'événement survient, la méthode onAlarm() de la classe AlarmClock doit être appelée en réponse à l'événement.

Pour effectivement définir l'alarme, la méthode setAlarm() de la classe AlarmClock est appelée, comme suit :

    /**
     * Définit l'heure à laquelle l'alarme doit se déclencher.
     * @param hour La partie Heure de l'heure d'alarme.
     * @param hour La partie Minutes de l'heure d'alarme.
     * @param message Le message à afficher lorsque l'alarme se déclenche.
     * @return Définit l'heure à laquelle l'alarme se déclenchera.
     */
    public function setAlarm(hour:Number = 0, minutes:Number = 0, message:String = "Alarm!"):Date
    {
        this.alarmMessage = message;
        var now:Date = new Date();
        // Créer cette heure sur la date du jour.
        alarmTime = new Date(now.fullYear, now.month, now.date, hour, minutes);

        // Déterminer si l'heure spécifiée est déjà passée aujourd'hui.
        if (alarmTime <= now)
        {
            alarmTime.setTime(alarmTime.time + MILLISECONDS_PER_DAY);
        }
    
        // Arrêter le minuteur de l'alarme s'il est déjà défini.
        alarmTimer.reset();
        // Calculer le nombre de millisecondes qui doit s'écouler avant que l'alarme
        // ne se déclenche (différence entre l'heure d'alarme et l'heure actuelle) et définir
        // cette valeur comme délai du minuteur d'alarme.
        alarmTimer.delay = Math.max(1000, alarmTime.time - now.time);
        alarmTimer.start();
    
        return alarmTime;
    }

Cette méthode effectue plusieurs opérations, notamment le stockage du message d'alarme et la création d'un objet Date (alarmTime) représentant le moment réel où l'alarme se déclenchera. Point le plus important de cette étude, le minuteur de la variable alarmTimer, dans les dernières lignes la méthode, est défini et activé. Tout d'abord, la méthode reset() est appelée, qui arrête le minuteur et le remet à zéro s'il est déjà reparti. Ensuite, l'heure actuelle (représentée par la variable now) est soustraite à la valeur de la variable alarmTime afin de déterminer combien de millisecondes doivent s'écouler avant le déclenchement de l'alarme. La classe Timer ne déclenche pas l'événement timer à une heure absolue ; c'est ce décalage relatif qui est attribué à la propriété delay de alarmTimer. Enfin, la méthode start() est appelée pour lancer le minuteur.

Une fois le délai spécifié écoulé, alarmTimer distribue l'événement timer. Comme la classe AlarmClock s'est enregistrée comme écouteur auprès de sa méthode onAlarm() pour l'événement timer, lorsque celui-ci survient, onAlarm() est appelée.

    /**
     * Appelée lorsque l'événement Timer est distribué.
     */
    public function onAlarm(event:TimerEvent):void 
    {
        trace("Alarm!");
        var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage);
        this.dispatchEvent(alarm);
    }

Lorsqu'une méthode est enregistrée comme écouteur d'événements, elle doit être définie avec la signature adaptée (c'est-à-dire le jeu de paramètres et le type de renvoi de la méthode). Pour écouter l'événement timer de la classe Timer, une méthode doit comporter un paramètre dont le type de données est TimerEvent (flash.event.TimerEvent), une sous-classe de la classe Event. Lorsque l'instance Timer appelle ses écouteurs d'événements, elle transmet une instance TimerEvent à l'objet événement.

Notification de l'alarme à d'autres composants

De même que la classe Timer, la classe AlarmClock fournit un événement qui permet de transmettre des notifications à d'autres éléments de code lorsque l'alarme se déclenche. Pour qu'une classe puisse utiliser le système de gestion des événements intégré à ActionScript, elle doit mettre en œuvre l'interface flash.events.IEventDispatcher. La plupart du temps, cela se fait par extension de la classe flash.events.EventDispatcher, qui assure une mise en œuvre standard de IEventDispatcher (ou par extension de l'une des sous-classe de EventDispatcher). Comme décrit précédemment, la classe AlarmClock étend la classe SimpleClock, qui à son tour étend la classe Sprite, elle-même extension de la classe EventDispatcher (par héritage). Ainsi, la classe AlarmClock intègre déjà une fonctionnalité lui permettant de fournir ses propres événements.

D'autres éléments de code peuvent s'enregistrer pour être notifiés de l'événement alarm de la classe AlarmClock en appelant la méthode addEventListener(), héritée de EventDispatcher. Lorsqu'une instance AlarmClock est prête à notifier à d'autres éléments de code le déclenchement de l'événement alarm, elle le fait en appelant la méthode dispatchEvent(), également héritée de EventDispatcher.

        var alarm:AlarmEvent = new AlarmEvent(this.alarmMessage);
        this.dispatchEvent(alarm);

Ces lignes de code sont extraites de la méthode onAlarm() de la classe AlarmClock (présentée plus haut dans son intégralité). La méthode dispatchEvent() de l'instance AlarmClock est appelée, puis elle notifie à tous les écouteurs enregistrés le déclenchement de l'événement alarm de l'instance AlarmClock. Le paramètre transmis à dispatchEvent() est l'objet événement qui sera ensuite passé aux méthodes d'écouteur. Dans ce cas, il s'agit d'une instance de la classe AlarmEvent, une sous-classe de Event créée spécialement pour cet exemple.

Elaboration d'un événement d'alarme personnalisé

Tous les écouteurs d'événements reçoivent un paramètre d'objet événement avec des informations sur l'événement qui a été déclenché. Dans bien des cas, l'objet événement est une instance de la classe Event. Dans d'autres cas néanmoins, il s'avère utile de fournir des informations complémentaires aux écouteurs d'événements. Comme décrit plus haut dans ce chapitre, il suffit pour cela de définir une nouvelle classe, sous-classe de la classe Event, et d'utiliser une instance de cette classe comme objet événement. Dans cet exemple, une instance AlarmEvent est utilisée comme objet événement lorsque l'événement alarm de la classe AlarmClock est distribué. La classe AlarmEvent, présentée ici, fournit des informations complémentaires sur l'événement alarm, à savoir le message d'alarme :

    import flash.events.Event;
    
    /**
     * Cette classe Event personnalisée ajoute une propriété message à un événement classique.
     */
    public class AlarmEvent extends Event 
    {
        /**
         * Le nom du nouveau type AlarmEvent.
         */
        public static const ALARM:String = "alarm";
        
        /**
         * Un message texte qui peut être transmis à un gestionnaire d'événements
         * avec cet objet événement.
         */
        public var message:String;
        
        /**
        /*  Constructeur.
         *  @param message Le texte à afficher lorsque l'alarme se déclenche.
         */
        public function AlarmEvent(message:String = "ALARM!")
        {
            super(ALARM);
            this.message = message;
        }
        ...
    }

Le meilleur moyen de créer une classe d'objet événement personnalisée est de définir une classe qui étend la classEvent, comme illustré dans l'exemple précédent. Pour compléter la fonctionnalité héritée, la classe AlarmEvent définit une propriété message qui contient le texte du message d'alarme associé à l'événement. La valeur message est transmise sous forme de paramètre au constructeur AlarmEvent. La classe AlarmEvent définit également la constante ALARM qui peut servir à référencer l'événement (alarm) lors de l'appel de la méthode addEventListener() de la classe AlarmClock.

Outre l'ajout de fonctionnalité, chaque sous-classe Event doit redéfinir la méthode clone() héritée dans le cadre de la gestion des événements ActionScript. Les sous-classes Event peuvent éventuellement redéfinir la méthode toString() afin d'inclure les propriétés de l'événement personnalisé dans la valeur renvoyée par l'appel de la méthode toString().

    /**
     * Crée et renvoie une copie de l'instance actuelle.
     * @return Copie de l'instance actuelle.
     */
    public override function clone():Event
    {
        return new AlarmEvent(message);
    }
    
    /**
     * Renvoie une chaîne contenant toutes les propriétés de
     * l'instance actuelle.
     * @return Chaîne représentant l'instance actuelle.
     */
    public override function toString():String
    {
        return formatToString("AlarmEvent", "type", "bubbles", "cancelable", "eventPhase", "message");
    }

La méthode clone() redéfinie doit renvoyer une nouvelle instance de la sous-classe Event personnalisée, avec toutes les propriétés personnalisées définies pour correspondre à l'instance actuelle. Dans la méthode toString() redéfinie, la méthode d'utilitaire formatToString() (héritée de Event) sert à fournir une chaîne comportant le nom du type personnalisé, ainsi que les noms et valeurs de toutes ses propriétés.