tde-i18n/tde-i18n-fr/docs/tdeedu/kstars/dcop.docbook

<chapter id="dcop">
<title
>Utilisation de KStars avec des scripts : l'interface DCOP</title>
<para
>Un des buts de &kstars; est de fournir la possibilité de jouer des comportements compliqués à partir d'un script. Ceci vous permet de créer des <quote
>tours virtuels</quote
> du ciel et vous permettra d'enseigner comment construire une démonstration à une salle de classe pour illustrer certains concepts astronomiques. Il est déjà possible d'écrire de tels scripts pour &kstars;, bien que toutes les fonctions désirées ne soient pas encore incluses. De plus, bien que nous aurons plus tard un constructeur de scripts basé sur une interface graphique, les scripts doivent pour le moment être écrits à la main. Ce chapitre expliquera comment écrire des scripts pour &kstars;. </para>
<para
>L'architecture &kde; fournit le cadre nécessaire pour les applications scriptables via l'interface <abbrev
>DCOP</abbrev
>. <abbrev
>DCOP</abbrev
> veut dire <quote
>Desktop Communication Protocole</quote
> (Protocole de communication pour le bureau) ; à travers <abbrev
>DCOP</abbrev
>, les applications &kde; peuvent être contrôlées par d'autres applications, depuis une ligne de commande de terminal ou par un texte de script. </para>

<sect1 id="dcop-interface">
<title
>Les fonctions DCOP</title>
<para
>L'interface <abbrev
>DCOP</abbrev
> de &kstars; inclut les fonctions suivantes : <itemizedlist>
<listitem
><para
><function
> lookTowards( const QString direction )</function
> : pointer le focus d'affichage dans une direction spécifiée par l'argument. Ceci peut être le nom de n'importe quel objet dans le ciel, ou une des directions suivantes : zenith (ou z), north (n), northeast (ne), east (e), southeast (se), south (s), southwest(sw), west(w), northwest (nw). </para
></listitem>

<listitem
><para
><function
> setRaDec( double ad, double déc )</function
> : pointer le focus d'affichage aux coordonnées équatoriales spécifiées. </para
></listitem>

<listitem
><para
><function
> setAltAz(double alt, double az)</function
> : pointer le focus d'affichage aux coordonnées horizontales spécifiées. </para
></listitem>

<listitem
><para
><function
> zoomIn()</function
> : augmenter le niveau de grossissement de l'affichage. </para
></listitem>

<listitem
><para
><function
> zoomOut()</function
> : diminuer le niveau de grossissement de l'affichage. </para
></listitem>

<listitem
><para
><function
> defaultZoom()</function
> : réinitialise le niveau de grossissement de l'affichage à 3 (la valeur par défaut). </para
></listitem>

<listitem
><para
><function
> setLocalTime(int an, int mois, int jour, int hr, int min, int sec)</function
> : déterminer l'horloge de simulation aux date et heure spécifiées. </para
></listitem>

<listitem
><para
><function
> waitFor( double t )</function
> : pause pendant t secondes avant de continuer avec les commandes suivantes du script. </para
></listitem>

<listitem
><para
><function
> waitForKey( const QString k )</function
> : arrêter l'exécution du script jusqu'à ce que l'utilisateur enfonce la touche spécifiée. À cet endroit, vous ne pouvez pas spécifier de combinaisons de touches (comme <keycombo action="simul"
>&Ctrl;<keycap
>C</keycap
></keycombo
>) ; utilisez de simples touches. Vous pouvez écrire <quote
>space</quote
> pour indiquer la barre d'espacement. </para
></listitem>

<listitem
><para
><function
> setTracking( bool track )</function
> : inverser l'utilisation du mode de suivi ou non. </para
></listitem>

<listitem
><para
><function
> changeViewOption( const QString option, const QString valeur )</function
> : ajuster une option d'affichage. Il y a des douzaines et des douzaines d'options disponibles ; en gros, tout ce que vous pouvez changer dans la fenêtre <guilabel
>Configuration de &kstars;</guilabel
>, vous pouvez le changer ici. Le premier argument est le nom de l'option (les noms sont pris dans le fichier de configuration <filename
>kstarsrc</filename
>), et le second argument est la valeur désirée. L'analyseur d'arguments est conçu pour être robuste. Ainsi, si vous envoyez accidentellement une mauvaise donnée, il devrait échouer sans heurt. </para
></listitem>

<listitem
><para
><function
> setGeoLocation( const QString ville, const QString province, const QString pays )</function
> : changer l'emplacement d'observation pour la ville spécifiée. Si aucune ville correspondant à l'argument n'est trouvée, rien ne se passe. </para
></listitem>

<listitem
><para
><function
> stop()</function
> [clock] : arrêter l'horloge de simulation. </para
></listitem>

<listitem
><para
><function
> start()</function
> [clock] : démarrer l'horloge de simulation </para
></listitem>

<listitem
><para
><function
> setScale(float s)</function
> [clock] : déterminer le taux de l'horloge de simulation. s=1,0 correspond au temps réel, 2,0 est deux fois plus rapide, etc. </para
></listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="dcop-test">
<title
>Tester les fonctions DCOP</title>
<para
>Vous pouvez essayer les fonctions DCOP très facilement en utilisant le programme <application
>kdcop</application
>. Lorsque vous lancez <application
>kdcop</application
>, vous verrez une arborescence de tous les programmes en fonctionnement ; si &kstars; est en fonctionnement, il sera listé. La plupart des fonctions <abbrev
>DCOP</abbrev
> sont listées sous l'en-tête <quote
>KStarsInterface</quote
>, sauf les fonctions d'horloge, qui sont listées sous <quote
>clock</quote
>. Double cliquez sur n'importe quelle fonction pour l'exécuter. Si la fonction nécessite des arguments, une fenêtre s'ouvrira, dans laquelle vous pourrez donner les valeurs. </para>
</sect1>

<sect1 id="dcop-script">
<title
>Écrire un script DCOP</title>
<para
>Les fonctions <abbrev
>DCOP</abbrev
> peuvent aussi être appelées depuis la ligne de commande UNIX, et elles peuvent être encapsulées dans un script. Nous créerons un script d'exemple qui passe en coordonnées équatoriales, pointe l'affichage vers la Lune, zoome un peu et accélère l'horloge à une heure par seconde. Après avoir suivi la Lune pendant 20 secondes, l'horloge est mise en pause et l'affichage zoome en arrière. Vous pouvez utiliser ce script comme un modèle pour faire de nouveaux scripts. Je listerai le script entier d'abord, puis expliquerai ses différentes parties. </para>
<para>
<programlisting
>#!/bin/bash
#KStars script: Track the Moon!
#
KSTARS=`dcopfind -a 'kstars*'`
MAIN=KStarsInterface
CLOCK=clock#1
dcop $KSTARS $MAIN  changeViewOption UseAltAz false
dcop $KSTARS $MAIN  lookTowards Moon
dcop $KSTARS $MAIN  defaultZoom
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $MAIN  zoomIn
dcop $KSTARS $CLOCK setScale 3600.
dcop $KSTARS $CLOCK start
dcop $KSTARS $MAIN  waitFor  20.
dcop $KSTARS $CLOCK stop
dcop $KSTARS $MAIN  defaultZoom
##
</programlisting>
</para>
<para
>Enregistrez ce script dans un fichier. Le nom de fichier peut être ce que vous voulez ; je suggère quelque chose de descriptif comme <filename
>suivrelune.kstars</filename
>. Puis, écrivez la commande suivante pour rendre le script exécutable : <userinput
><command
>chmod</command
> <option
>a+x</option
> <parameter
>suivrelune.kstars</parameter
></userinput
>. Le script peut être exécuté à n'importe quel moment en écrivant <userinput
><command
>./suivrelune.kstars</command
></userinput
> dans le dossier qui contient le script. Notez que le script ne fonctionnera que si une instance de &ktars; est déjà en fonctionnement. Vous pouvez utiliser la commande <command
>dcopstart</command
> dans un script pour lancer une nouvelle instance de &kstars;. </para>
<para
>Expliquons maintenant le script. La ligne du haut identifie le fichier comme un script shell <command
>BASH</command
>. Les deux lignes suivantes sont des <firstterm
>commentaires</firstterm
> (n'importe quelle ligne commençant par un <quote
>#</quote
> est un commentaire et est ignorée par le shell). Les trois lignes suivantes définissent des variables pratiques qui seront utilisées plus tard. La variable <varname
>KSTARS</varname
> identifie le processus de &kstars; en fonctionnement, grâce à la commande <command
>dcopfind</command
>. <varname
>MAIN</varname
> et <varname
>CLOCK</varname
> identifient les deux interfaces <abbrev
>DCOP</abbrev
> associées à &kstars;. </para>
<para
>Le reste du script est la vraie liste des appels <abbrev
>DCOP</abbrev
>. La première commande paramètre l'affichage pour utiliser les coordonnées équatoriales en positionnant l'option <quote
>UseAltAz</quote
> sur <quote
>false</quote
> (vous pouvez voir une liste de toutes les options que <quote
>changeViewOption</quote
> peut utiliser en examinant votre fichier de configuration <filename
>kstarsrc</filename
>). La commande suivante centre l'affichage sur la Lune, et engage automatiquement le suivi. Nous positionnons alors le niveau de zoom par défaut, puis zoomons de 5 niveaux. Puis, l'échelle de temps est mise à 1 heure par seconde (3 600 secondes font 1 heure), et l'horloge est lancée (au cas où elle ne fonctionnerait pas déjà). La ligne suivante suspend le script pendant 20 secondes pendant que nous suivons la Lune durant son mouvement à travers le ciel. Enfin, nous arrêtons l'horloge et réinitialisons le niveau de zoom à sa valeur par défaut. </para>
<para
>Nous espérons que vous aimez les possibilités de scriptage de KStars. Si vous créez un script intéressant, veuillez l'envoyer par courrier électronique à <email
>kstars@30doradus.org</email
> ; nous aimerions voir ce que vous avez fait, et peut-être mettre des scripts sur notre page web. De plus, si vous avez des idées sur la manière d'améliorer le scriptage (ou toute partie de &kstars;), faites-le nous savoir à <email
>kstars-devel@lists.sourceforge.net</email
> ou soumettez un souhait sur bugzilla. </para>
</sect1>
</chapter>