Généralités

Un spinner est un objet graphique constitué d'une zone de saisie (texte contenant un nombre) associée à 2 boutons : flèche vers le haut et flèche vers le bas .

Son fonctionnement interactif est le suivant :
  • Le clic avec la souris sur la flèche incrémente la valeur du nombre dans la zone de saisie.
  • Le clic avec la souris sur la flèche décrémente la valeur du nombre dans la zone de saisie.
  • L'utilisateur peut modifier directement le nombre par modification dans la zone de saisie (avec contrôle de la valeur saisie).
    • Voici un exemple de spinner dont la valeur peut varier de 0 à 20 :
    De nombreuses options permettent de personnaliser son fonctionnement :
  • Taille de la zone de saisie
  • Valeur initiale
  • Valeur d'incrément
  • Nombre de chiffres affichés après la virgule
  • Bornes minimale et maximale
  • Circularité : après avoir atteint la borne maximum, on repasse directement au minimum (et inversement) ou le compteur reste bloqué à la borne
  • Position des boutons : à droite ou à gauche de la zone de saisie
  • Période de répétition si un des boutons reste enfoncé
  • Fonction appelée lorsque la valeur est modifiée
    • Attention de consulter les restrictions d'utilisation avant d'utiliser cet objet.

     

    Utilisation dans une page HTML

    Pour utiliser ce module dans une page HTML , procéder comme suit :

    Dans l'entête de la page (entre les balises <head> et </head>) inclure ce module et l'initialiser :
    Par exemple, si le module est dans le répertoire "tools/spinner" :

    <script src="tools/spinner/spinner.js"></script>
    <script language="JavaScript" type="text/javascript">
    initSpinner("tools/spinner");
    </script>
    Dans le corps de la page (entre les balises <body> et </body>) les opérations suivantes sont possibles :

    Déclaration d'un nouveau spinner : fonction addSpinner

    <script language="JavaScript" type="text/javascript">
    addSpinner (
      "callback" , code exécuté lorsque la valeur change (pas de code exécuté par défaut),
      "default" , valeur d'origine (0 par défaut),
      "max" , valeur max (= min si pas de max),
      "min" , valeur min (quelconque si pas de min),
      "name" , nom du spinner,
      "position" , position des flèches ('left' ou 'right' (par défaut)),
      "precision" , nombre de chiffres après la virgule (0 par défaut = nombre entier , -1 = pas de limite),
      "roll" , indicateur de circularité si min != max (0 ou "no" (défaut) = pas circulaire , 1 ou "yes" = circulaire)
      "step" , valeur d'incrément (1 par défaut),
      "timeout" , temps de modif si le bouton reste enfoncé (200 ms par défaut)
      "width" , taille de la zone de saisie (3 par défaut),
    );
    </script>

    Les arguments vont toujours par paire : le nom de l'argument est séparé de sa valeur par une virgule.

    Ils peuvent être fournis dans n'importe quel ordre.

    Seul, l'argument name est obligatoire.

    Exemple
    Le spinner utilisé comme exemple plus haut sur cette page est déclaré comme suit :
    addSpinner(
    "name", "example",
    "width", 3,
    "default", 12,
    "min", 0,
    "max", 20,
    "roll", "yes"
    );
    Les autres paramètres utilisent les valeurs par défaut.

    Lecture de la valeur d'un spinner : fonction getSpinner

    <script language="JavaScript" type="text/javascript">
    var valeur = getSpinner (
      "name" , nom du spinner,
    );
    </script>

    Exemple
    Pour lire la valeur du spinner déclaré ci-dessus :
    var val = getSpinner(
    "name", "example",
    );

    Modification d'un spinner : fonction setSpinner

    Cette fonction permet de modifier par programme la valeur du spinner (avec contrôle de validité de la nouvelle valeur) et/ou ses bornes minimales et maximales.

    var ancienne_valeur = setSpinner (
      "name" , nom du spinner,
      "max" , nouvelle borne maximale,
      "min" , nouvelle borne minimale,
      "value" , nouvelle valeur,
    );
    Seul, l'argument name est obligatoire.

    Les paramètres qui ne sont pas fournis lors de l'appel ne sont pas modifiés.

    En cas de modification des bornes, la valeur est éventuellement ajustée en conséquence.

    Si une nouvelle valeur et des nouvelles bornes sont fournies, les bornes sont d'abord modifiées puis la valeur est appliquée.

    Exemple
    Pour positionner à 17 la valeur du spinner déclaré ci-dessus :
    setSpinner(
    "name", "example",
    "value", 17,
    );


    Exemple
    Pour modifier à -5 et +5 les bornes minimale et maximale du spinner déclaré ci-dessus :
    setSpinner(
    "name", "example",
    "min", -5,
    "max", 5,
    );

    Dans ce cas, la valeur du spinner (qui était positionnée à 17) est ramenée à la borne maximale (5 dans l'exemple).

    Restrictions d'utilisation

    1. La déclaration d'un spinner ne doit pas être faite à l'intérieur de la déclaration d'un formulaire. En terme de programmation, cela se traduit par le fait que l'appel à la fonction addSpinner ne doit pas se situer entre les balises <form> et </form>.

     

    Droits d'auteur

    Ce code est la propriété de Patrick Renaud ().

    L'auteur vous accorde l'autorisation d'utiliser ce code sans restriction et sans frais à condition que cette utilisation soit faite dans un cadre privé. Pour toute utilisation à des fins commerciales, merci de me contacter.

    Dans tous les cas, l'auteur décline toute responsabilité concernant les dégâts directs ou indirects pouvant résulter de l'utilisation de ce code.