JMRI: Create a Custom DecoderPro Programmer

# JMRI: Guide Utilisateur DecoderPro

## Créer un Programmateur Personnalisé

Comment puis-je créer mon propre programmateur personnalisé?

La réponse commence par la création d'un fichier xml dans le sous-répertoire "programmers" de la distribution JMRI. Le contenu du fichier est décrit ci-dessous.

Après quelques parties initiales ( que vous pouvez copier depuis un fichier existant ), le reste du fichier est une série de "volets" de définitions d'éléments. Chacun d'eux devient un volet dans la fenêtre DecoderPro.

Les volets du fichier programmer apparaissent quand vous sélectionnez ce programmateur dans DecoderPro. Notez que les volets peuvent aussi être définis dans la définition décodeur, au quel cas ces volets apparaissent après ceux qui présents dans les définitions de programmeur.

- Il y a une option pour montrer/masquer les volets depuis le fichier decoder. Si vous écrivez un programmateur très basique, vous pouvez vouloir les cacher pour conserver une interface simple.
- Si un volet est défini dans le fichier decoder et le fichier programmer avec le même nom, celui du fichier décodeur ( le plus spécifique ) apparaît.

Spécifier les éléments à afficher

  L'élément de base d'un volet de programmation est un "affichage". Cela signifie que le programmateur ne présente qu'une seule variable. Les attributs sont:

  - name - ( Nécessaire ) C'est le "nom standard" de la variable qui sera présenté.
  - label - S'il est présent, il va être utilisé pour marquer la variable sur le volet au lieu du nom ou du nom standard de la variable.
  - Layout - Où trouver l'étiquette par rapport au champ modifiable, par exemple, la zône de texte. Les valeurs possibles sont "gauche", "au-dessus", "en dessous", "droit" , par défaut "droit" .
  - format - Comment la variable devra être présentée. Les variables numériques peuvent être présentées comme
    - un champ de texte modifiable, qui est la valeur par défaut si rien n'est spécifié
    - hslider - un curseur horizontal
    - vslider - un curseur vertical
    Les variables Enum peuvent être présentées comme
    - une zône de sélection, qui est la valeur par défaut si rien n'est spécifié
    - radiobuttons - Chaque valeur possible est présentée comme un bouton individuel
    - checkbox - Une liste avec seulement deux états peut également être présentée comme une case à cocher
    - offradiobutton - Un seul bouton qui donne le choix 0 pour la variable lorsqu'il est sélectionné.
    - onradiobutton - Un seul bouton qui donne le choix 1 pour la variable lorsqu'il est sélectionné.
    Ces deux derniers peuvent être utiles pour indiquer quelles parties d'une configuration sont actives, voir le volet "Table de Vitesse" de Comprehensive.xml comme exemple.
  - tooltip - Vous permet de spécifier une info-bulle par défaut qui sera présentée lorsque le curseur survole la variable. Cette info-bulle sera remplacée par toute info-bulle définie dans un fichier de décodeur. (Note: Ce comportement est différent de celui défini pour l'attribut d'étiquette 'label'.)

  Le nom à afficher est commandé par le volet de l'attribut "nameFmt" et l'attribut "label" sur chaque élément d'affichage (variable).

  Les choix sont:

  - Si une étiquette est spécifiée, elle sera utilisée. Utilisez une étiquette si vous souhaitez un contrôle absolu sur comment une variable doit être appelée, quel que soit le fichier décodeur qui l'appelle, et que vous n'aimez pas le nom standard.
  - Le volet attribut nameFmt est "élément ", auquel cas le nom de l'élément sera utilisé indépendamment de ce que le fichier décodeur appelle la variable. Utilisez ceci si vous voulez un aspect uniforme pour le volet pour tous les décodeurs. Mais soyez conscient que certains noms standard sont vraiment tellement générique qu'ils sont inutiles.
  - Si le volet attribut nameFmt est autorisé par défaut, ou contient "mfg", le nom du fichier de définition de décodeur sera utilisé. Il s'agit de la forme normale, car il permet au fabricant d'indiquer en détail ce qu'une variable définit.
Formatage
  Chaque volet du programmateur se compose de lignes et/ou des colonnes ( imbriquées ) . Les colonnes exposent les variables de haut en bas. Les rangées exposent les variables de gauche à droite. Vous pouvez les imbriquer pour obtenir des effets différents; pour un exemple, voir le volet "Table de Vitesse" du dossier Comprehensive.xml. Il a deux colonnes, la gauche de chacune utilise une ligne pour mettre des curseurs de gauche à droite.
Éléments spéciaux
  Il y a un certain nombre d'éléments que vous pouvez utiliser pour obtenir que le programmateur formate exactement comme vous le souhaitez:
  - grid - Créer une grille pour exposer les éléments en rangées et colonnes. Voir la section ci-dessous Disposition de la grille
  - label - Ajouter du texte dans un volet.
  - soundlabel - Ajouter un soundlabel depuis un fichier decoder definition dans un volet. Il a un attribut:
    - dfn - ( Requise ) C'est le nombre de label son à présenter
  - separator - Ajouter une ligne de séparation dans un volet. S'il est inclus dans une colonne, ce sera une ligne de séparation horizontale. S'il est inclus dans une ligne, ce sera une ligne verticale.
  - cvtable - Insérer un tableau des valeurs de CV sur le volet. Pour obtenir le droit d'espacement, vous devriez probablement ne pas combiner cela avec d'autres variables sur le même volet.
  - fnmapping -Afficher une grille fonction Mapping . Cela nécessite des variables avec des noms spécifiques, qui sont décrites sur une page séparée
  - dccaddress - Afficher une variable combinée pour l'adresse DCC. Il s'agit d'une case à cocher qui permet de sélectionner l'utilisation de l'adresse courte par rapport à une longue, et un champ texte simple pour entrer l'adresse. Selon la façon dont la case est activée, le champ de texte permet de configurer l'adresse courte dans CV 1 ou adresse longue dans CV 17/18.
Formatage avec la Disposition de la Grille

  Les éléments "row" et "column" vous permettent d'aligner les éléments dans les rangées ou les colonnes, mais il si vous avez plusieurs colonnes avec un seul élément rangée ( ou vice versa ) il n'est pas possible d'assurer que les rangées dans les colonnes adjacentes ( ou vice versa ) restent alignées.

  La Disposition de la Grille vous permet d'aligner les éléments en rangées et colonnes, en conservant l'alignement même si un élément particulier est absent. Il y a deux éléments:

  - grid - Crée une Disposition de Grille ( avec en son sein un élément colonne et rangée ) :
    - Il peut avoir un ou plusieurs attributs optionnels.
    - Le seul sous-élément autorisé est "griditem" et il doit y avoir au moins un d'eux.
  - griditem - Crée un élément grille au sein d'un élément "grille":
    - Il doit avoir les attributs "gridx" et "gridy".
    - Il peut avoir aussi un ou pusieurs attributs optionnels.
    - Il peut contenir un ou plusieurs éléments, qui peuvent être n'importe quelle combinaison de n'importe quels éléments listés ci-dessus, incluant "row", column", ou même une autre grille.

  Les attributs "gridx" et "gridy" d'un élément d'une grille spécifie l'emplacement de l'élément au sein de la grille. Une valeur de gridx= "0" met l'élément dans la colonne la plus à gauche. Une valeur de gridy= "0" met l'élément dans la rangée la plus haute. D'autres attributs pour commander le format des éléments de la grille sont disponibles et sont documentés dans le Tutoriel Java® GridBagLayout.

  - Les Attributs de "grid" s'appliquent à tous les éléments de la table.
  - Les Attributs de "griditem" s'appliquent à cet élément et remplace tout attribut équivalent de "grid".
  - Les deux valeurs numérique et littérale d'une constante ( comme spécifié par le documentation) peuvent être utilisées.
  - Deux valeurs littérales supplémentaires de constantes sont disponibles pour "gridx" et gridy":
    - "CURRENT" est la valeur du dernier "griditem" ajouté ( exemple la même colonne ou rangée ).
    - "NEXT" est un de plus que la dernière valeur "griditem" ajoutée ( exemple la rangée ou la colonne suivante ).
      ("NEXT" est actuellement synonyme de "RELATIVE". )
  - L'attribut "insets" est spécifié comme insets= "haut,gauche,bas droit" où "haut", etc, sont des entiers.
  - Un "griditem peut avancer de plus d'une cellule de la grille. Les attributs "gridwidth" et "gridheight" commandent ceci.
  - Par défaut les éléments de la grille sont agglutinés au centre d'un container. L'attribut "weightx" peut modifier ceci et justifier gauche/droite.
  - il est possible dans quelques circonstances d'oublier un ou les deux "gridx" et "gridy" d'un "griditem" et spécifier une valeur par défaut dans "grid". Voir xml/decoders/esu/v4fnOutPane.xml pour un exemple de cet utilisation pour générer une simple grille à une colonne alignée à droite. ( Cependant si vous n'êtes pas rigoureux avec l'usage de cette technique et/ou la constante "RELATIVE", les résultats peuvent être bizarres. )
  - Malheureusement "ipadx", "ipady", et "insets" allouent de l'espace même si la variable d'affichage contenue échoue à la condition. Une solution de contournement est de qualifier l'ensemble "GridItem" entourant la variable ( si c'est approprié à la situation ).

  Pour un exemple d'utilisation de la Disposition de la Grille ( avec quelques explications sur les attributs utilisés ), voir xml/decoders/esu/v4soundPane.xml. Les définitons LokSound Select ( et V4 ) utilise ce fichier.

Installation de votre nouveau programmateur

  Tous les fichiers .xml dans le sous-répertoire "programmers" apparaîtront dans la boîte de sélection lorsque vous créerez un nouveau programmateur dans DecoderPro. Pour utiliser votre nouveau fichier, il suffit de mettre dans le sous-répertoire "programmers" du répertoire "prefs" et de le sélectionnez. Vous n'avez pas à redémarrer le programme, la liste est refaite à chaque fois que vous ouvrez une nouvelle fenêtre programmateur.

  Il ya une option pour présenter/masquer les volets depuis le fichier décodeur. Si vous écrivez un programmateur tès basique, vous pouvez les cacher.

### Comment les variables dans un fichier décodeur correspondent avec le fichier programmateur

Chaque fichier décodeur définit les variables qui décrivent des commandes spécifiques dans le décodeur. Le fichier programmateur décrit ensuite comment les placer sur ces volets, de telle sorte que l'utilisateur puisse les trouver et les manipuler

Chaque élément "affichage" dans le fichier programmer définit une chose à montrer. Mais laquelle? C'est contrôlé par l'attribut "name" de l'élément "display" . DecoderPro ne prend que "name" et regarde à travers la définition décodeur pour un élément "variable" qui a soit le même "élément" ou le même attribut "label".

Cela a des effets très intéressants:

1. Le "nom" dans l'élément "display" est effectivement un "nom standard", qui peut être utilisé dans les fichiers de définition décodeur provenant de différents constructeurs. Comme il est distinct du "label" sur la variable décodeur, il est possible d'avoir un fichier programmateur générique qui fonctionne pour de nombreux types de décodeurs différents, tout en affichant les noms des variables spécifiques. Pour en savoir plus, s'il vous plaît voir ci-dessus .
2. Il vous permet d'utiliser des noms très génériques pour commander où vont des choses un peu différentes. Par exemple, différents décodeurs sonores donnent différents commandes. On pourrait avoir "Pompe à air", tandis qu'un autre n'a pas du tout ceci, et a au lieu "Crissement de frein". Nous ne voulons pas avoir les fichiers programmateur contenant des milliards d'éléments "display" à maîtriser avec toutes les options possibles. Au lieu de cela, nous utilisons des éléments avec des noms plus génériques, comme "Option Son 1", pour le nom d'affichage.
   La définition décodeur dispose alors d'un "label" de "Pompe à air" ou que ce soit, et un "élément" de "Option Son 1". Tout correspond correctement, et "Pompe à air" apparaît sur l'écran de l'ordinateur.