Travailler avec la sélection utilisateur
########################################

Objectif : lire et analyser les éléments permettant d'obtenir la sélection utilisateur.

1 – récupérer le .jsx de travail
********************************

Télécharger `exemple-selection-utilisateur.jsx <../../_static/scriptUI/exemple-selection-utilisateur.jsx>`_ (à placer dans le dossier ``Scripts`` ou ``Scripts/ScriptUI``)

2 – construction de l'interface
*******************************

.. code-block:: javascript

   // on récupère la référence à la palette (ou on en créé une)
   var fenetre = (this instanceof Panel) ? this : new Window( 'palette', 'script', undefined, { resizeable: true });

   // limites = [ ← gauche, ↑ haut, → droite, ↓ bas ]
   var limites_bouton = [ 5, 5, 105, 25 ];

   // texte à afficher sur le bouton
   var texte_bouton = 'cliquez-moi !';

   // création du bouton et ajout à notre fenêtre
   var bouton_valider = fenetre.add( 'button', limites_bouton, texte_bouton );

.. note::

   À ce stade, cette partie ne doit plus nécéssiter de commentaire

3 – interaction
***************

.. code-block:: javascript

   // on prend notre bouton, on associe à sa propriété onClick une fonction
   // lorsque le bouton sera cliqué,
   // la fonction associée à la propriété onClick sera exécutée
   bouton_valider.onClick = function () {

   /* code à exécuter */

   }

.. note::

   À ce stade, cette partie ne doit plus nécéssiter de commentaire

4 – obtenir la référence de la composition active
*************************************************

.. code-block:: javascript

   // on récupère la composition active
   var composition_active = app.project.activeItem;

   // si on a aucune composition sélectionnée
   if ( !composition_active || !(composition_active instanceof CompItem) ) {
     // à noter que le mot clé return va mettre fin à la fonction actuelle
     return alert("Aucune composition sélectionnée.");
   }

.. note::

   ``app.project.activeItem`` est une référence à la composition active.

   En vérifiant que que cet élément est une instance de la classe ``CompItem`` et non un élément null ou non défini, on peut vérifier qu'une composition est active.

   Si l'élément n'est pas une composition, on utilise le mot clé ``return`` pour terminer la fonction courante sans la poursuivre, et en affichant un message d'erreur.

5 – obtenir la référence des calques sélectionnés
*************************************************

.. code-block:: javascript

   // sinon, on récupère les calques sélectionnés
   var calques_selectionnes = composition_active.selectedLayers;

   // si on a aucun calque sélectionné
   if ( calques_selectionnes.length == 0 ) {
     return alert("Aucun calque sélectionné.");
   }

.. note::

   Ce code est très similaire au code précédent. Ici on obtient la propriété ``selectedLayers`` de la composition active, correspondant aux calques sélectionnés.

   Si le nombre de calque sélectionnés est de 0, on affiche un message et on met fin à la fonction.