Manuel d'utilisation de Debugger.swf

Table des matières

  1. Installation et inclusion
  2. Connexion
  3. Surveillance de variable
  4. Barre d'exécution
  5. Explorateur d'arborescence
  6. Commandes Dièse
  7. Clavier

1.Installation et inclusion

Inclusion de Debbuger.as

Pour que votre animation puisse se connecter à Debugger.swf, il faut que le fichier Debugger.as y soit inclus. Celui-ci contient tout le code de communication qui permettra à votre animation de communiquer les valeurs des variables, envoyer des messages et recevoir des instructions de Debugger.swf. Notez que pour le moment, Debugger.as n'est disponible qu'en AS2. La version minimum de Flash nécessaire est Flash 7, qui introduisit l'objet LocalConnection.
Vous pouvez placer le fichier Debugger.as dans n'importe quel dossier mais il vous faudra adapter le chemin de fichier communiqué à l'animation en conséquence.
Si vous placez votre animation dans le même répertoire que Debugger.as, voici ce qu'il vous faudra ajouter dans votre code ActionScript :

#include "Debugger.as"

Vous pouvez changer le chemin de fichier pour refléter votre cas de figure.

#include "as_files/Debugger.as"     // Debugger.as est placé dans un sous-dossier “as_files”
#include "../as_files/Debugger.as"  // “../” vous permet de remonter d'un niveau

Activation de l'écoute

Une fois le code de communication inclus, vous devez faire en sorte que votre animation accepte les connexions, en exécutant la fonction d_enable. Pour que le déboguage soit possible à n'importe quel moment, placez cette ligne directement en dessous de l'#include.
Debugger.swf conserve des données relatives aux animations auxquelles il s'est précédemment connecté. Pour correctement restituer ces données par la suite, il doit pouvoir identifier l'animation à laquelle il se connecte. Pour cela, vous devez fournir un nom à la fonction d_enable, comme premier argument. Ce nom ne peut contenir que les caractères de l'alphabet, minuscule ou majuscule, et des chiffres ; en outre, il ne peut pas commencer par un chiffre.
Si vous décidez d'utiliser “physicsTest” comme nom pour votre animation, la commande d'activation ressemblera à cela :

d_enable("physicsTest");

Protection par mot de passe

Pour ne pas que votre animation soit accessible par n'importe qui en déboguage, vous pouvez demander à ce qu'un mot de passe soit fourni dans Debugger.swf. Pour cela, il vous suffit simplement de passer ce mot de passe en deuxième argument dans la fonction d_enable. À la connexion à l'animation Flash, il vous faudra taper le mot de passe dans la barre d'exécution puis valider.
Debugger.swf se souviendra des mots de passes entrés et les soumettra automatiquement aux animations correspondantes lors des connexions suivantes. Vous pouvez cependant effacer l'historique des mots de passe grâce à #passwordsreset.

d_enable("physicsTest", "myPassword");

Envoi de message

Vous pouvez utiliser la fonction d_log() comme substitut à la fonction trace(). La différence entre les deux est que d_log() affichera les messages dans le journal (la partie basse de la fenêtre de déboguage). Vous pourrez donc les voir même en déboguant hors de Flash ; vous pouvez cependant passer la variable d_useTrace à true pour que les messages soit affichés de manière conventionnelle quand Debugger.swf n'est pas connecté.

2.Connexion

Pour déboguer une animation, il vous suffit de lancer Debugger.swf et cette animation. L'ordre n'importe pas : le deuxième lancé avertira automatiquement l'autre de sa présence.
Si Debugger.swf est déjà connecté à une animation lorsqu'une autre est lancée, il se connecte automatiquement à la celle venant d'être lancée. Vous pouvez cependant modifier ce comportement grâce à une Commande Dièse.
À la connexion, Debugger.swf chargera les options enregistrées lors de la précédente session (variables surveillées, historique des fonctions, verrouillage de focus). Les options sont sauvegardées sur votre disque dur à chaque modification pour limiter toute perte.

3.Surveillance de variable

Ajout et paramétrage

Pour ajouter une entrée, pressez Shift-Entrée. Vous pouvez pressez Entrée seule si aucun texte n'est présent dans la barre d'exécution.
Le mode d'édition d'entrée est alors automatiquement activé.

Modification des options de l'entrée

Sitôt entré en mode d'édition, vous pouvez taper le chemin de la variable à afficher. Cela peut être le nom d'une variable globale tout comme un chemin d'une propriété d'un clip.
Vous pouvez modifier les options d'affichage dans la partie droite du panneau d'édition.
Le premier bouton, numéroté, vous permet de choisir un des trois modes :

  1. Texte : la valeur de la variable est affichée sans mise en forme
  2. Barre : une barre horizontale représente la variable numérique
  3. Frise : une frise chronologique représente l'évolution de la valeur numérique dans le temps

Pour les deux modes graphiques, vous pouvez choisir deux extremums et deux couleurs.
Le minimum et le maximum seront utilisés s'ils sont entrés, et devinés autrement. Vous pouvez entrer l'un, sans préciser l'autre. Les extremums sont affichés en superposition avec l'affichage, et pour le mode Barre le zéro sera représenté par une séparation verticale. Les extremums automatiques sont réinitialisés à chaque connexion.
Les couleurs seront celle de la barre, ou de la frise. Dans le cas de la barre, cette dernière sera remplie d'un dégradé des deux couleurs choisies. Pour la frise, les couleurs seront utilisées en alternance pour permettre la différenciation des deux couches temporelles.
Si vous faites un Shift-clic sur une couleur, une deuxième couleur complémentaire sera automatiquement choisie.

Réorganisation et suppression

Vous pouvez déplacer une entrée en cliquant-glissant sa poignée verticalement.
Pour supprimer une entrée, maintenez Shift enfoncé et double-cliquez sur l'entrée.
Attention, toutes ces modifications sont immédiatement enregistrées !

Navigation

Vous pouvez faire défiler la liste des entrées en cliquant-glissant l'une d'entre elle.
Notez que vous pouvez activer le défilement rapide en pressant Shift pendant que vous cliquez-glissez : la liste se déplacera alors plus vite que votre curseur, de manière à ce que quand celui-ci atteigne le bas ou le haut de la fenêtre, la liste soit respectivement entièrement scrollée vers le haut, ou le bas. Cette fonctionnalité peut vous faire gagner beaucoup de temps si vous manipulez beaucoup d'entrées.
Pour redimensionner les deux colonnes, cliquez-glissez horizontalement une poignée. Les noms de variable manquant de quelques pixels pour s'afficher s'écraseront horizontalement, au lieu d'être tronqués.
Pour modifier les paramètres d'une entrée, double-cliquez sur le nom de la variable surveillée.
Pour modifier rapidement la valeur d'une variable, double-cliquez celle-ci ; le contenu de la barre d'exécution changera en conséquence.

4.Barre d'exécution

Évaluation d'expression et exécution de fonction

Vous pouvez rapidement obtenir la valeur d'une variable ou d'une propriété d'un clip en tapant son chemin dans la barre d'exécution et en validant avec Entrée. La valeur s'affiche alors dans le journal, situé dans la partie basse de la fenêtre.

Vous pouvez également exécuter une fonction et obtiendrez de la même manière la valeur qu'elle retourne ; vous devez simplement apposer une parenthèse ouvrante à la fin du nom de la fonction.
Si votre fonction prend des arguments, vous pouvez les entrer, séparés par des virgules. Vous pouvez ou non utiliser des guillemets pour vos arguments ; ceux-ci vous permettront d'utiliser des virgules ou de forcer un nombre à être interprété comme string. Voici quelques exemples et leurs équivalents en ActionScript :

resetNotices(                               =>  resetNotices()
resetNotices(Welcome                        =>  resetNotices("Welcome")
resetNotices(Welcome, See you               =>  resetNotices("Welcome", "See you")
resetNotices("Welcome, anonymous", See you  =>  resetNotices("Welcome, anonymous", "See you")

Changement de la valeur d'une variable

Modifier la valeur d'une variable est très simple. Tapez son chemin, un espace, puis sa nouvelle valeur. La variable changera de valeur dès que vous presserez entrée.
Notez que si la variable est actuellement surveillée, vous pouvez double-cliquer la partie droite de l'entrée, et vous n'aurez plus qu'à taper la valeur souhaitée et valider.

Historique et auto-complétion

Au fur et à mesure que vous tapez une commande dans la barre d'exécution, celle-ci recherche dans son historique des commandes concordantes. Si elle en trouve, la fin de la commande suggérée s'affiche en gris. Vous pouvez ignorer cette proposition si elle ne correspond pas à ce que vous tapez ; pour l'accepter, vous pouvez taper Flèche Haut ou Flèche Bas. Flèche Bas complétera votre commande, vous permettant de modifier celle proposée, alors que Flèche Haut l'exécutera aussitôt.
La pertinence des propositions est calculée en fonction de leur nombre d'utilisation, et de leur date de dernière utilisation. Vous pouvez réinitialiser l'historique grâce à #historyreset.

5.Explorateur d'arborescence

Debugger.swf vous permet de visualiser les données et clips de votre animation sous forme d'arbre. Pour entrer dans l'explorateur d'arborescence, pressez Page Down.
L'arbre apparaît sous forme de liste, que vous pouvez faire défiler d'un cliquer-glisser (le défilement rapide fonctionnant comme pour les entrées). Vous voyez, à son ouverture, le contenu du plus haut niveau de votre animation: _root. La valeur de chaque élément est mise à jour en temps réel. Les objets présentent un symbole plus à droite de leur ligne ; double-cliquez-en un pour révéler ses enfants.
Si vous double-cliquez une variable sans enfant, le contenu de la barre d'exécution change afin que vous puissiez choisir une nouvelle valeur pour la variable.
Vous pouvez faire se rafraîchir l'arbre en pressant la touche Home.

Notez que si votre animation contient un nombre important d'éléments, l'envoi de la structure de l'arbre peut échouer.

Propriétés supplémentaires des clips

Afin de générer la vue d'arborescence, Debugger.swf itère au travers de toute la structure de votre animation au moyen de for…in. Une décision d'Adobe a été de masquer les propriétés standard des clips à cette boucle — c'est à dire _x, _y, _totalframes, etc. Debugger.swf peut cependant chercher de lui-même ces propriétés lorsqu'il rencontre un clip, les affichant donc quand même.
Pour activer ce comportement, passez la variable d_useMovieclipProperties à true. Vous pouvez ajouter une ligne juste après l'#include, ou modifier directement la valeur dans Debugger.as (cette modification sera cependant à refaire à chaque mise à jour si effectuée directement dans le .as).
Vous pouvez de plus modifier la liste des propriétés à afficher, appelée d_movieclipProperties. Par défaut, c'est une liste réduite des propriétés les plus essentielles. Mais vous pouvez ajuster ce comportement comme vous le souhaitez : dans Debugger.as se trouve un tableau contenant l'ensemble des propriétés définies. Vous pouvez dé-commenter ce tableau directement, ou le copier coller dans votre animation Flash et conserver uniquement les propriétés vous intéressant.

Attention ! Les objets LocalConnection — utilisées pour la communication entre Debugger.swf et l'animation — ne peuvent pas transmettre un tableau s'il est trop gros. Ce qui veut dire qu'une animation comportant beaucoup d'éléments risque de ne pas pouvoir être parcourue à l'aide de l'Explorateur d'arborescence. Ajouter les propriétés des clips rend ce risque encore plus important.

6.Commandes Dièse

La barre d'exécution vous permet également d'effectuer certaines tâches et certains réglages au moyen des Commandes Dièse. Celles-ci sont connues par le moteur d'auto-complétion, aussi vous n'aurez généralement qu'à taper une ou deux lettres.

Verrouillage

#focus
Vous permet de verrouiller Debugger.swf de manière à ce qu'il ne soit autorisé à déboguer qu'une certaine animation, jusqu'à son prochain lancement.
Quand utilisé sans argument, #focus forcera le débuggeur à ignorer les animations n'ayant pas le même nom que l'animation actuellement connectée.
Si vous ajoutez un argument (par exemple, #focus physicsTest), le débuggeur se verrouillera sur le nom demandé. Si l'animation actuellement en déboguage ne remplit pas la condition, Debugger.swf se déconnecte et cherche une animation ayant le bon identifiant.
#lockfocus
Cette commande doit être utilisée après avoir verrouillé le débbugage au moyen de focus. Elle rendra persistant le verrouillage — ainsi, même après être relancé, Debugger.swf n'acceptera de se connecter qu'à des animations ayant le bon identifiant. Utilisez de nouveau cette commande pour désactiver la persistance.

Mise à zéro

#extremumsreset
Réinitialise les extremums calculés automatiquement pour les affichages graphiques.
#historyreset
Supprime l'historique des fonctions tapées.
#passwordsreset
Efface la liste des mots de passe automatiquement enregistrés.
#conferase
Supprime toute la configuration de Debugger.swf de manière irréversible.

Autres

#timelinejump
Nécessite un argument numérique. Vous permet de spécifier combien de mises à jour doivent ignorer les affichages graphiques de type frise chronologique. En effet, la fréquence de mise à jour des variables étant par défaut de 12 fois par seconde, les graphes ne sont pas systématiquement mis à jour. Ce paramètre est persistant ; la valeur par défaut est de 1.
#grapheffects
Active ou désactive les effets bitmap appliqués sur les graphes. Ceux-ci, en théorie, ne consomment quasiment aucune ressource, mais vous pouvez toujours gagner un peu de puissance en les désactivant. Ce paramètre est persistant.
#refreshtree
Rafraîchit l'arborescence en mode Arbre. Les éléments dépliés le restent, et la position de défilement est conservée. À utiliser si de nouveaux éléments ont été créés depuis le dernier rafraîchissement (ou la dernière entrée en mode Arbre). La touche Home a le même effet.

7.Clavier

Afin de vous permettre d'être efficace, Debugger.swf propose un grand nombre de raccourcis clavier. La plupart ne sont pas la seule façon d'accéder à une fonctionnalité donnée, mais généralement ils sont la façon la plus rapide.

Général

Page Up
Gèle l'animation. Pour cela, Debugger.swf parcoure l'animation à la recherche d'événements (onEnterFrame, onMouseMove, …) et les supprime. Lorsque vous enfoncez de nouveau Page Up, les événements sont remis en place.
Les timer et les interval ne sont pas affectés.
Page Down
Affiche et masque l'Explorateur d'Arborescence.
Home
Rafraîchit la structure de l'arbre.

Barre

Entrée
Valide la commande entrée dans la barre d'exécution.
Si aucune commande n'est présente, crée une entrée.
Entrée + Shift
Ajoute une entrée.
Flèche bas
Complète la barre d'exécution avec la suggestion actuelle.
Flèche haut
Complète la barre d'exécution avec la suggestion actuelle et l'exécute immédiatement.

Combinaisons avec Shift

Shift +
clic sur un bouton de type d'affichage
Décrémente le type d'affichage au lieu de l'incrémenter. Le gain de temps est ici très, très minime.
Shift +
clic sur une couleur
En plus de sélectionner la couleur, définit automatiquement la deuxième couleur en fonction de celle choisie.
Shift +
double clic sur une entrée
Supprime l'entrée double-cliquée.
Shift +
cliquer-glisser d'une liste
Fait défiler la liste avec le défilement rapide.