Date de mise à jour : 14 mai 2008
Pour éviter tous les problèmes de compatibilité des caractères accentués avec les scripts déjà existant, vous devez configurer votre éditeur selon la norme ISO 8859-15.
AudeLA, et son interface graphique Aud'ACE sont des logiciels ouverts, qui permettent à tout le monde d’ajouter ou de personnaliser toutes les fonctions possibles et imaginables. Mais l’expérience nous a montré que pour une parfaite intégration dans le logiciel, plusieurs règles de programmation sont à respecter. Ce document a pour objet de lister, expliquer et décrire ces règles. Il doit servir aux programmeurs lors de leurs développements. Il est destiné aussi à valider de nouveaux scripts avant leur intégration dans une prochaine révision de AudeLA/Aud'ACE. Si votre application est destinée à faire partie intégrante du logiciel, nous vous invitons à respecter scrupuleusement ces règles. Cette contrainte n’a bien sûr aucun caractère obligatoire si votre développement est limité à un usage personnel. Elle reste néanmoins utile pour éviter les surprises...
On peut décomposer les règles d'intégration en plusieurs catégories :
Ce document est appelé à évoluer en fonction des expériences des uns et des autres : N’hésitez pas à faire des propositions d’amélioration à l’équipe de développement AudeLA/Aud'ACE.
Un script peut prendre principalement deux formes dans Aud'ACE :
Si vous souhaitez faire profiter tous les utilisateurs de votre travail, nous vous invitons alors à faire enregistrer votre travail sur notre site web. Cela évitera à d'autres personnes de partir dans un développement similaire, et de faire converger nos efforts.
Dans le cas d'un script simple, la seule règle à respecter est de mettre votre fichier TCL dans le répertoire "scripts".
Dans le cas d'un outil Aud'ACE, il vous faut définir deux noms : Le premier sera celui du script lui-même, et le second sera celui affiché dans le menu déroulant Outils (ce sera aussi le titre de l'outil). Faisons l'hypothèse que votre fichier s'appelle "mon_fichier_a_moi.tcl", et que le titre de votre application est "Mon outil". Dans ce cas, les différents fichiers utilisés par votre application devront respecter les règles suivantes :
Le fichier "mon_fichier_a_moi.tcl" sera écrit uniquement avec des minuscules, et sera installé dans le répertoire "[...]/gui/audace/plugin/tool/mon_fichier_a_moi".
Si vous avez besoin de fichiers complémentaires (par exemple, un fichier de configuration), vous le placerez dans le même répertoire que votre fichier.
Dans ce répertoire, le cas échéant, le fichier de configuration aura le même nom que votre fichier de script, mais avec l'extension .ini : Dans notre cas, il s'agira de "mon_fichier_a_moi.ini". Il est impératif de ne pas utiliser le nom "config.ini" qui est réservé au fichier de configuration de l'application Aud'ACE.
Dans la mesure du possible, tous les autres fichiers complémentaires dont vous aurez besoin devront respecter cette même règle de nom (nom voisin du fichier de script). Ceci facilitera son identification ultérieure.
Si vous travaillez avec un fichier de log (un fichier généré par votre application, et qui enregistre des résultats sur le disque), son nom commencera par le nom du fichier TCL, et aura cette fois l'extension .log. En général, le nom du fichier contient aussi la date, voire l'heure de sa création, pour éviter l'écrasement quand on lance l'application plusieurs fois. Pour notre exemple, on peut imaginer un fichier de log crée le 22 mai 2002 : Il pourrait alors porter le nom "mon_fichier_a_moi_20020522.log". En général, ce fichier est écrit dans le répertoire images. Ceci n'est qu'un exemple, la seule convention à respecter est que le nom du fichier de script apparaisse clairement dans le nom du fichier de log.
Si vous faites un fichier de documentation (nous vous y invitons fortement), il devra être au format .htm ou .pdf (l'équipe de développement saura vous aider si vous ne savez pas générer ce format), et son nom sera toujours "mon_fichier_a_moi.htm" ou "mon_fichier_a_moi.pdf". En effet, il est important que l'utilisateur trouve le fichier d'aide sous le même nom que l'outil sur lequel il cherche de l'aide... Ce fichier sera installé dans le répertoire "mon_fichier_a_moi/french" pour la version française et "mon_fichier_a_moi/english" pour la version anglaise, pour être accessible depuis le menu Aide de l'outil (bouton du nom de l'outil).
Il y a un dernier fichier important à prendre en compte : Celui des captions (fichier contenant toutes les chaînes de caractères utilisées par votre application, et traduites dans toutes les langues de Aud'ACE). Ce fichier, installé dans le répertoire "[...]gui/audace/plugin/tool/mon_fichier_a_moi" aura pour extension "cap", et commencera par le nom du fichier de script. Avec notre exemple, cela donne "mon_fichier_a_moi.cap". Nous reviendrons sur ce fichier dans la partie "Internationalisation" du présent document.
Plusieurs variables générales sont disponibles pour une bonne intégration de votre script. Il s’agit de variables que vous pouvez lire sans problème, mais en aucun cas, vous ne devez en modifier le contenu sauf en parfaite connaissance de cause : Vous risqueriez des effets inattendus dans le déroulement du reste du programme. Il s’agit des variables suivantes :
Toutes ces variables sont initialisées à l'installation ou au lancement de AudeLA, et permettent de pointer sur les bons répertoires, quelque soit le répertoire d'installation de AudeLA.
Plusieurs formats de fichiers d’images sont supportés par AudeLA, selon qu’ils sont compressés ou non. Si vous avez besoin, dans votre script de générer des noms complets de fichiers, vous devez respecter l’extension par défaut des fichiers images. Elle est accessible par la variable conf(extension,defaut). A la création d’un nouveau buffer, vous devez attribuer cette valeur au buffer :
buf$audace(bufNo) extension
: Pour l'extension .fit
et
[buf$audace(bufNo) extension].gz
: Pour l'extension .fit.gz
Attention, vous devez déclarer dans le script les variables globales "audace", et le cas échéant "conf".
Le numéro des buffers de Aud'ACE est géré par l’application. Pour permettre les évolutions futures, vous ne devez pas mettre dans vos scripts des commandes telles que "buf1", vous devez les remplacer par :
buf$audace(bufNo)
en ayant déclaré "global audace" au préalable.
Dans le même esprit, vous devez proscrire les commandes "cam1", vous devez les remplacer par :
cam$audace(camNo)
en ayant déclaré "global audace" au préalable.
Toujours dans la même veine, vous devez proscrire les commandes "tel1", vous devez les remplacer par :
tel$audace(telNo)
en ayant déclaré "global audace" au préalable.
Enfin, vous devez proscrire les commandes "visu1", vous devez les remplacer par :
visu$audace(visuNo)
en ayant déclaré "global audace" au préalable.
AudeLA a été prévu pour travailler avec plusieurs langues. Pour que cela puisse fonctionner dans tous les cas, il a été défini que toutes les chaînes de caractères gérées par le programme sont écrites dans des variables "caption(mon_fichier_a_moi,xxx)". Ces variables sont rassemblées dans un fichier "mon_fichier_a_moi.cap" (le nom est bien sûr à adapter en fonction de votre fichier), qui est appelé au début du script (voir plus haut la partie "convention sur les noms et les répertoires" pour le nom de ce fichier et son répertoire d'installation). Le fichier "mon_fichier_a_moi.cap" doit être installé dans le répertoire "[...]/gui/audace/plugin/tool/mon_fichier_a_moi".
Le fait de mettre les captions dans un fichier à part simplifie le travail de traduction (comme il est peu probable que vous parliez toutes les langues du logiciel, le fichier "mon_fichier_a_moi.cap" pourra être transmis à plusieurs traducteurs de l’équipe de développement). Le contenu du fichier "mon_fichier_a_moi.cap" aura la structure suivante :
# # Fichier : audela.cap # Mise a jour $Id: script1b.htm,v 1.4 2008-05-14 16:54:36 robertdelmas Exp $ # #========================================================================= # Début de la déclaration des textes localisés (internationalisation) #========================================================================= global caption # *************** Version anglaise **************************** set caption(audela,main_title) "AudeLA: Interface Selection" set caption(audela,language) "Language Selection:" set caption(audela,description) "Choose the interface you want to use:" set caption(audela,soft1) "Tutorial" set caption(audela,soft2) "Aud'ACE" set caption(audela,launch) "Run" set caption(audela,dirtcl) "../gui/test test.tcl" set caption(audela,direct_audace) "Do not display this interface any more." # *************** Version française *************************** if { [ string compare $langage "french" ] == "0" } { set caption(audela,main_title) "AudeLA : Sélection de l'interface utilisateur" set caption(audela,language) "Sélection de la langue :" set caption(audela,description) "Sélectionnez l'interface que vous voulez utiliser :" set caption(audela,soft1) "Tutorial" set caption(audela,soft2) "Aud'ACE" set caption(audela,launch) "Lancer" set caption(audela,dirtcl) "../gui/test test.tcl" set caption(audela,direct_audace) "Ne plus afficher cette interface." # *************** Version italienne *************************** } elseif { [ string compare $langage "italian" ] == "0" } { set caption(audela,main_title) "AudeLA: Scelta dell'interfaccia utente" set caption(audela,language) "Scelta delle lingue:" set caption(audela,description) "Scegliere l'interfaccia d'uso:" set caption(audela,soft1) "Tutorial" set caption(audela,soft2) "Aud'ACE" set caption(audela,launch) "Esegui" set caption(audela,dirtcl) "../gui/test test.tcl" set caption(audela,direct_audace) "Non visualizzare piu` questa interfaccia." # *************** Version espagnole *************************** } elseif { [ string compare $langage "spanish" ] == "0" } { set caption(audela,main_title) "AudeLA: Alternativas de interfaz de usuario" set caption(audela,language) "Selecció de idioma:" set caption(audela,description) "Escoger la interfaz de usuario a utilizar:" set caption(audela,soft1) "Tutorial" set caption(audela,soft2) "Aud'ACE" set caption(audela,launch) "Arrancar" set caption(audela,dirtcl) "../gui/test test.tcl" set caption(audela,direct_audace) "No mostrar esta interfaz más." # *************** Version allemande *************************** } elseif { [ string compare $langage "german" ] == "0" } { set caption(audela,main_title) "### AudeLA : Sélection de l'interface utilisateur" set caption(audela,language) "### Sélection de la langue :" set caption(audela,description) "### Sélectionnez l'interface que vous voulez utiliser :" set caption(audela,soft1) "### Tutorial" set caption(audela,soft2) "Aud'ACE" set caption(audela,launch) "### Lancer" set caption(audela,dirtcl) "../gui/test test.tcl" set caption(audela,direct_audace) "### Ne plus afficher cette interface." # *************** Version portugaise **************************** } elseif { [ string compare $langage "portuguese" ] == "0" } { set caption(audela,main_title) "### AudeLA : Sélection de l'interface utilisateur" set caption(audela,language) "### Sélection de la langue :" set caption(audela,description) "### Sélectionnez l'interface que vous voulez utiliser :" set caption(audela,soft1) "### Tutorial" set caption(audela,soft2) "Aud'ACE" set caption(audela,launch) "### Lancer" set caption(audela,dirtcl) "../gui/test test.tcl" set caption(audela,direct_audace) "### Ne plus afficher cette interface." # *************** Version danoise ***************************** } elseif { [ string compare $langage "danish" ] == "0" } { set caption(audela,main_title) "### AudeLA : Sélection de l'interface utilisateur" set caption(audela,language) "### Sélection de la langue :" set caption(audela,description) "### Sélectionnez l'interface que vous voulez utiliser :" set caption(audela,soft1) "### Tutorial" set caption(audela,soft2) "Aud'ACE" set caption(audela,launch) "### Lancer" set caption(audela,dirtcl) "../gui/test test.tcl" set caption(audela,direct_audace) "### Ne plus afficher cette interface." } #========================================================================= # Fin de la déclaration des textes localisés (internationalisation) #=========================================================================
Si vous ne connaissez pas la traduction de vos messages dans l’une ou l’autre langue, laissez le message dans votre langue natale, en le faisant précéder de ### pour aider leur détection par les traducteurs (à titre d'exemple, vous constaterez ci-dessus que les parties allemande, portugaise et danoise sont en attente de traduction). Bien sûr, dans le corps de votre script, vous devrez lancer au tout début la lecture de ce fichier de captions (commande du type "source [ file join $audace(rep_plugin) toolmon_fichier_a_moi mon_fichier_a_moi.cap ]" ), et vous ne devrez utiliser que les variables contenant les captions (par exemple : Message console $caption(mon_fichier_a_moi,titre) ).
Un plugin est un module complémentaire de AudeLA permettant d'ajouter une nouvelle fonctionnalité à AudeLA. Il est installé dans le répertoire des plugins sans avoir à modifier AudeLA par ailleurs.
Un plugin est constituté au moins de deux fichiers TCL situés dans le même répertoire :
Exemple :
package ifneeded focuserjmi 1.0 [list source [file join $dir focuserjmi.tcl]]
Exemple :
namespace eval ::focuserjmi { package provide focuserjmi 1.0 #--- Je charge le fichier caption pour recuperer le label du titre #--- utilise par la procedure getLabel source "[file join [file dirname [info script]] focuserjmi.cap]" } proc ::focuserjmi::getPluginProperty { propertyName } { switch $propertyName { xxxx { return "aaaa" } yyyy { return "bbbb" } }proc ::focuserjmi::getPluginType { } { return "equipment" }proc ::focuserjmi::getPluginTitle { } { return "$::caption(focuserjmi,label)" }proc ::focuserjmi::initPlugin { tkbase } { variable private global conf #--- Cree les variables dans conf(...) si elles n'existent pas if { ! [ info exists conf(focuserjmi,link) ] } { set conf(focuserjmi,link) "" } if { ! [ info exists conf(focuserjmi,bitStart) ] } { set conf(focuserjmi,bitStart) "4" } .... }
La déclaration du namespace doit contenir la commande "package provide" avec le même numéro de version que celui figurant dans la commande "package ifneeded" du fichier pkgIndex.tcl.
La déclaration du namespace doit pouvoir être chargée dans un interpréteur "safe". Ceci implique :
Les procédures getPluginType et getPluginTitle doivent pouvoir être chargées dans un interpréteur "safe". En conséquence elles ne doivent pas utiliser d'autres variables que celles créées dans la déclaration du namespace.
La procédure initPlugin est optionnelle. Elle peut faire appel à n'importe quelle fonction ou variable globale (pas de contrainte de l'interpréteur "safe").
Pour comprendre comment ces procédures sont utilisées, voir 5.4 Chargement d'un plugin dans Aud'ACE
La procédure getPluginType d'un outil doit retourner "tool".
Exemple :
proc ::autoguider::getPluginType { } { return "tool" }
Un outil doit avoir obligatoirement les procédures suivantes :
proc ::autoguider::startTool { { visuNo 1 }} { #--- creation de l'outil ou de la fenetre }proc ::autoguider::stopTool { { visuNo 1 } } { #--- masquage de l'outil }
La procédure getPluginProperty doit retourner la valeur de la propriété
"display" qui peut être :
Exemple :
proc ::acqFC::getPluginProperty { propertyName} { switch $propertyName { display { return "panel" } yyyy { return "bbbb" } }
... à compléter.
... à compléter.
... à compléter.
... à compléter.
... à compléter.
... à compléter.
Le chargement d'un plugin s'effectue en deux étapes.
Etape 1 : Au démarrage de AudeLA, Aud'ACE recherche les fichiers pkgIndex.tcl et effectue les opérations suivantes pour chacun d'eux :
Etape 2 : Quand le plugin est sélectionné, Aud'ACE effectue les opérations suivantes :
(*) Un interpréteur safe est un interpréteur TCL dans lequel aucune variable globale n'est déclarée.
Les outils de la version 1.4.0-beta2 doivent être modifiés de la façon suivante :
1) Modifier la déclaration du namespace :
namespace eval ::xxxxxxxxx{ package provide autoguider 1.0 #--- Charge le fichier caption source [ file join [file dirname [info script]] xxxxxxxxx.cap ] }
2) Renommer la procédure "Init" en "createPluginInstance" et supprimer return [namespace current] à la fin de la procédure.
3) Ajouter les procédures deletePluginInstance, getPluginProperty, getPluginTitle, getPluginType et initPlugin.
Remarque : Les procédures deletePluginInstance et initPlugin ne font rien pour l'instant (sauf pour spectro par exemple).
#------------------------------------------------------------ # deletePluginInstance # suppprime l'instance du plugin #------------------------------------------------------------ proc deletePluginInstance { visuNo } {}#------------------------------------------------------------ # getPluginProperty # retourne la valeur de la propriete # # parametre : # propertyName : nom de la propriete # return : valeur de la propriete , ou "" si la propriete n'existe pas #------------------------------------------------------------ proc getPluginProperty { propertyName } { switch $propertyName { function { return "acquisition" } display { return "panel" } } }#------------------------------------------------------------ # getPluginTitle # retourne le titre du plugin dans la langue de l'utilisateur #------------------------------------------------------------ proc getPluginTitle { } { global caption return "$caption(xxxxxxx,title)" }#------------------------------------------------------------ # getPluginType # retourne le type de plugin #------------------------------------------------------------ proc getPluginType { } { return "tool" }#------------------------------------------------------------ # initPlugin # initialise le plugin #------------------------------------------------------------ proc initPlugin { } {}
4) Supprimer : set panneau(menu_name,autoguider) ...
5) Supprimer à la fin du fichier :
global audace
::xxxxx::Init $audace(base)
6) Modifier le fichier pkgIndex.tcl :
package ifneeded autoguider 1.0 [list source [file join $dir autoguider.tcl ]]