JSmol: l'interface graphique avec l'utilisateur

Cette page présente les aspects graphiques de l'interface. Tout ce qui permet de contrôler la visualisation de la molécule par des éléments de formulaire (zones de texte, cases à cocher et boutons divers ne sont pas expliqués ici mais dans la page Contrôler JSmol).

Afficher une molécule
Les dimensions du <canvas>
Conserver la visibilité du <canvas>
La console
Personnaliser le menu

qualité d'image

variable JmolInfo=

Le tableau associatif définissant l'objet JSmol est plus développé que celui présenté sur la page d'introduction:

Cliquez pour afficher / masquer le code à placer dans l'en-tête ou le corps du document

Afficher une molécule ↑

script:

script: '' exécute la série de commande située en les guillements (on peut utiliser des guillements simples ou doubles. s'il n'y a rien entre les guillemets, script est vide et c'est sa valeur par défaut. Cette page utilise: 'load adenine.mol; rotate x 90'.
Nous n'étudierons pas ici le langage de commande, ce sera l'objet de la page: Contrôler JSmol; expliquons simplement que la commande load charge le fichier représentant la molécule, la commande est suivie d'un espace puis du chemin relatif ou absolu du fichier par rapport à la page (cette commande peut utiliser une URL mais cela pourrait être refusé par le navigateur pour question de sécurité si on fait appel à un serveur différent de celui qui héberge la page). La gestion des fichiers sera détaillée ici: Gérer les fichiers.

Nous avons ajouté une deuxième commande: rotate x 90. Sur la page précédente, vous avez remarqué que les positions des atomes dans le fichier adénine affichent une molécule vue par la tranche; ceci permet de se rendre compte que la molécule est dans un plan, mais n'est pas très informatif; la commande rotate fait tourner la molécule, le paramètre x indique que l'on tourne autour de l'axe horizontal et 90 donne l'angle de rotation en degrés; les commandes successives d'un script sont séparées par des points-virgules.

Vous pouvez exécuter un script en dehors de la définition du tableau associatif JmolInfo, il suffit d'exécuter la fonction JSmol: Jmol.script();

Cliquez pour afficher / masquer le code à placer dans le corps du document

La fonction s'exécute lors du chargement de la page; si vous souhaitez différer l'exécution, une façon simple est d'appeler la fonction dans un lien: cliquer sur le lien qui suit charge une molécule de Glucagon à la place du fichier initial: <a href="javascript: Jmol.script(instance0, 'load 1gcn.pdb');"></a>

Qualité d'image ↑

plus joli, mais plus lent

L'amélioration de la qualité d'image se paye par un ralentissement plus ou moins important. Cette qualité est modifiée par la commande set: set antiAliasDisplay {on ou off} permettant un lissage des contours et des rubans ou des hélices; set zShade {on ou off} qui estompe les éléments en arrière plan, set CartoonFancy {on ou off} qui crée des effets d'ombrage des rubans et hélices. L'utilisation de majuscules ou de minuscules dans le langage de commande est indifférente, mais cela peu améliorer la lisibilité de ce langage.

Les commandes contrôlant la qualité d'image sont ici regroupées en 3 niveaux; le niveau par défaut est comme son nom l'indique adopté à la base par JSmol et il est réinitialisé par la commande load. Dans la plupart des pages du site nous adoptons le niveau intermédiaire; il faut donc penser à le remettre en place à chaque chargement de nouvelle molécule.

Cliquez pour afficher / masquer le code à placer dans le corps du document


<label for="qualityId"  style="vertical-align: top;">spacefill </label>

<input type="range" id="qualityId" min="0" max="2" value="1" step="1" /><br>
<br>


<script type="text/javascript">
	
var quality = document.getElementById('qualityId');
quality.addEventListener('change', () => {
	setQuality(quality.value);
	});	

setQuality= function(imageQuality) { //  sea https://wiki.jmol.org/index.php/Recycling_Corner#Improved_lighting
	switch (imageQuality) {
		case '2':
		theScript = 'reset lighting; set antialiasDisplay on; set cartoonsFancy on; set zShade on; set zShadePower 2; set ambientPercent 25; set specularPower 100; set specularPercent 22; set specularExponent 4;';
		break;
		case '1':
		theScript = 'reset lighting; set antialiasDisplay on; set cartoonsFancy off; set zShade on; set zShadePower 2;';
		break;
		default:
		theScript = 'reset lighting; set antialiasDisplay off; set cartoonsFancy off; set zShade off;';
		}
	Jmol.script(instance0, theScript);
	}

</script>

Les dimensions du <canvas> ↑

width: et height:

La balise HTML <canvas></canvas> crée dans la page un objet particulier destiné au dessin et aux calculs graphiques; il est logiquement utilisé par JSmol. Cet objet offre des possibilités graphiques étendues, mais possède une contrainte: il n'est pas redimensionnable "automatiquement".

Dans la page précédente comme sur de nombreuses pages web assez anciennes, le <canvas> ne se redimensione pas. Pour éviter qu'il soit en partie caché si la fenêtre du navigateur est trop petite, on lui donne des dimensions très faibles: par défaut JSmol utilise width: 300px et height: 300px. Les machines clientes du web étant aujourdhui aussi bien des ordinateurs associés à de très grands écrans comme des smartphones, il est indispensable de prévoir par défaut de grandes dimensions, mais qui s'adapteront à un écran plus petit si nécessaire

Fixer une dimension comme width: 100% ne résout qu'en partie le problème. Il faut donc en faire un peu plus: envelopper le canvas par une boite <div></div> que l'on redimensionnera explicitement ou implicitement.

Implicitement

On utilise des dimensions relatives au viewport (fenêtre du navigateur). L'unité vmin indique au navigateur que le nombre donné dans la définition du style width de la boite enveloppante, est relative: c'est la dimension la plus petite (entre largeur et hauteur) du viewport: 50vmin utilise 50% de la dimension la plus petite. Comme il est possible de faire tourner la molécule, le plus logique est d'utiliser une boite carrée donc on donne la même valeur à height. Il est possible d'utiliser un canvas rectangulaire, un choix peu fréquent. Lorsque l'utilisateur redimensionne la fenêtre, le navigateur fait les calculs automatiquement. Le code qui suit affiche un canvas flottant à droite dans un cadre calculé à 50% de la largeur ou de la hauteur de la fenêtre du navigateur, la dimension minimale étant retenue.

Cliquez pour afficher / masquer le code à placer dans l'entête du document


<style type="text/css">
div#wrapperId {
	float: right; 
	width: 50vmin; 
	height: 50vmin; 
	margin-left: 8px; 
	}
</style>

Cliquez pour afficher / masquer le code à placer là où vous voulez afficher le canvas de JSmol

La définition du style est de préférence à placer dans l'en-tête (CSS), mais peut se faire dans le bloc en cas de nécessité.


<div id="wrapperId" style="float: right; width: 50vmin; height: 50vmin; margin-left: 8px; "> // définition du style facultative si vous l'avez déjà placé dans l'en-tête (ce qui est préférable)


<script type="text/javascript"> 
Jmol.getApplet(instance0, JmolInfo);  // la fonction Jmol.getApplet(); affiche le canvas (ou est dessinée la molécule) de JSmol
</script>
</div><!-- wrapperId -->

Explicitement

La fonction CSS scale() permet de redimensionner la boite enveloppante. Avec JSmol cette solution donne des résultats moins satifaisants, mais dans d'autres cas d'utilisation de canvas le choix peut être intéressant; vous trouverez un exemple sur cette page: billard.

<length>. sur MDN.
Présente longueurs et unités utilisables pour définir width et height (entre-autres).

La documentation de référence de la variable info est ici: Jmol_JavaScript_Object/Info

Conserver la visibilité du <canvas> ↑

Si la page est longue, le <canvas> aura depuis longtemps disparu quand vous en lirez la partie inférieure. Deux positionnements résolvent le problème: le positionnement sticky et le positionnement fixed. Cliquez sur les liens pour comparer: Coller (sticky) ou Fixer (fixed) le canvas de JSmol. sticky est la modification la plus simle à mettre en œuvre: la seule chose à ajouter (à part la définition du positionnement) est de définir une valeur top représentant l'écart avec le bord supérieur de la fenêtre. Le positionnement fixed demande de définir deux valeurs, l'une pour le positionnement vertical: top ou bottom, l'autre pour le positionnement horizontal: left ou right (sticky conserve le positionnement horizontal du bloc englobant mais fixed non); par défaut top et left sont positionnés à zéro. (ces valeurs sont ignorées en positionnement static). J'ai tendance à préférer sticky, le positionnement horizontal de fixed étant calculé depuis le bord de la fenêtre. Si l'affichage de la page n'utilise pas tout l'espace disponible, cela demande quelques calculs supplémentaires.

Attention, les "blocs collant ou fixé" créent un nouveau contexte d'empilement; ils apparaissent normalement opaques mais si vous créez de nouveaux blocs (comme <div></div> ) avec un positionnement relatif dans le flux suivant du document, ces blocs se superposeront à eux en transparence.

Cliquez pour afficher / masquer le code CSS placer dans l'en tête


<style type="text/css"> 
div#wrapperId {
	position: sticky;
	top: 0;
	float: right; 
	width: 50vmin; 
	height: 50vmin; 
	margin-left: 8px;
	}
// ou
div#wrapperId {
	position: fixed;
	top: 0;
	right: 0;
	width: 50vmin; 
	height: 50vmin; 
	margin-left: 8px;
	}
</style>

Ce code CSS convient pour une page occupant toute la largeur de la fenêtre; avec un peu de code css supplémentaire on peut gérer une page très étroite dans laquelle on place tous les blocs sur le même défilement vertical, ou une page très large avec des marges sur les cotés, ce qui nécessite un peu plus de calculs.

Cliquez pour afficher / masquer le code Javascript qui modifie dynamiquement le positionnement


<script type="text/javascript">
sticky= function () {
var applet= document.getElementById('wrapperId');
var change= document.getElementById('stickyId');
if (applet.style.position== 'sticky') { 
	change.innerHTML= "Coller (sticky)";
	applet.style.position = 'static';
	}
	else {
		applet.style.position = 'sticky';
		change.innerHTML= "Décoller (static)";
		}
	}
// ou
fixed= function () {
var applet= document.getElementById('wrapperId');
var change= document.getElementById('fixedId');
if (applet.style.position== 'fixed') { 
	change.innerHTML= "Fixer (fixed)";
	applet.style.position = 'static';
	}
	else {
		applet.style.position = 'fixed';
		change.innerHTML= "Libérer (static)";
		}
	}
</script>

Ce qui précède se suffit à lui même, mais pour éviter l'effet de masquage, on divise couramment la page en deux moitiés verticales, l'une présentant le <canvas> et éventuellement des éléments annexes, l'autre le texte. Une troisième possibilité apparait alors: positionner le bloc enveloppant le <canvas> de manière absolue. Les proportions attribuées à ces deux parties verticales pourraient être redimensionnées en Javascript, sans que cela apparaisse essentiel; l'utilisation de boites flexibles (flex) pour ces parties serait possible, mais semble occasionner des ralentissements importants dans l'affichage. Après de nombreux tests, ma présentation préférée est mise en œuvre dans les pages Contrôler JSmol et dans la plupart des pages consacrées à un famille de molécules, comme: Les acides nucléiques. Le code à insérer est présenté ci-dessous. Le bloc enveloppant peut contenir deux instances de JSmol superposées, ce qui permet de comparer des molécules (démo à venir), sans atteindre l'ergonomie d'un multi-fenêtrage.

Cliquez pour afficher / masquer le code à placer dans l'en tête (proportions imposées)


<style type="text/css"> 
*{ box-sizing: border-box; }
div#wrapperId { // contient le canvas de JSmol
	position: fixed;  
	top: 24px; // distance au haut de la fenêtre (peut être modifié)
	right: 0; // positionnement à droite
	width: 60vw; // utilise une valeur relative: 60% de la largeur de la fenêtre
	} 
div#wrapper2Id { // contient le contenu défilant de la page
	width: 40vw; // les 40% restants	
	}
</style>

Ce code CSS convient pour une page occupant toute la largeur de la fenêtre; avec un peu de code CSS supplémentaire on peut gérer une page très étroite dans laquelle on place tous les blocs sur le même défilement vertical, ou une page très large avec des marges sur les cotés, ce qui nécessite un peu plus de calculs.

Cliquez pour afficher / masquer le code


<style type="text/css"> 

</style>

↑ La solution devenue la plus aventureuse consiste à gérer plusieurs fenêtres (sur un grand écran). C'est un peu passé de mode mais surtout parce que les navigateurs modernes sont de plus en plus réticents à gérer l'apparition de nouvelles fenêtres qu'ils classent souvent dans les "pop-up windows". Et pourtant l'apport ergonomique est considérable, surtout si on souhaite comparer des molécules; Evidemment ce mode ne convient pas aux smartphones, mais quel est l'intérêt de visualiser des molécules sur un smartphone ? Un exemple présentant les acides aminés.

Angel Herráez. 2018. Dynamically sized JSmol CC by SA.
Des exemples de mise en page du canvas de JSmol (simple ou multiple) dans une page avec une zone de texte défilante. Utilise un positionnement absolu et on un bloc fixe; c'est plus complexe que le code présenté ici, et semble un peu dépassé, mais cela devrait fonctionner avec d'anciens navigateurs.

Console ↑

(en cours d'écriture)

La console par défaut s'affiche dans une fenêtre flottante; si vous souhaitez une console non flottante, il faut insérer dans la page <div id="*_console"></div> (remplacez l'étoile par le nom de l'objet JmolObject concerné par cette console; lorsque cette boite est définie dans la page, la commande console insérera le code HTML nécessaire à cet endroit plutôt que dans une fenêtre flottante. Malheureusement dans un cas comme dans l'autre cette console est très laide, elle n'est pas localisée (les fichiers de langue de JSmol ne concernent que le menu "popup"), et ne supporte pas le redimensionnement.

Il semble possible de corriger une partie de ces défauts en remplaçant le contenu inséré dans cette boite par le vôtre; évidemment ceci doit être fait après l'exécution de la commande console

Activer la console (soyez patient après le clic, car JSmol doit lire de nombreux fichiers lors de cet affichage)

Cliquez pour afficher / masquer le code à placer là ou afficher la console


<div id="instance0_console"></div> <!-- la commande console insère la console ici -->

<div id="showConsoleId" style="display:none;"><a href="javascript:showConsole();">Afficher la console</a></div>

<div id="runConsoleId"><a href="javascript:initConsole();">Activer la console</a> (soyez patient après le clic, car <em>JSmol</em> doit lire de nombreux fichiers lors de cet affichage)</div> 

<div id="maskConsoleId" style="display:none;"><a href="javascript:maskConsole();">Masquer la console</a></div>

Cliquez pour afficher / masquer le code à placer dans le document


<script type="text/javascript">
const consoleTxt='<div><a href="javascript:Jmol.script(instance0,\'help\');">Aide</a> <a href="javascript:maskConsole();">Masquer</a></div><div id="instance0_console_outputdiv" style=""><textarea id="instance0_console_output" style="width:100%;"></textarea></div><input type="button" id="instance0_console_Clear_Output" style="width:100px" value="Vider" onclick="Jmol.Console.click(\'instance0_console_Clear_Output\')"><input type="button" id="instance0_console_History" style="width:100px" value="Historique" onclick="Jmol.Console.click(\'instance0_console_History\')"><input type="button" id="instance0_console_State" style="width:100px" value="Etat" onclick="Jmol.Console.click(\'instance0_console_State\')"><br><br><div id="instance0_console_inputdiv" style=""><textarea id="instance0_console_input" style="width:100%"></textarea></div><div id="instance0_console_buttondiv"><input type="button" id="instance0_console_Run" style="width:100px" value="Exécuter" onclick="Jmol.Console.click(\'instance0_console_Run\')"><input type="button" id="instance0_console_Load" style="width:100px" value="Load" onclick="Jmol.Console.click(\'instance0_console_Load\')"><input type="button" id="instance0_console_Clear_Input" style="width:100px" value="Vider" onclick="Jmol.Console.click(\'instance0_console_Clear_Input\')"></div>'; dans l'en tête (proportions imposées) 

initConsole = function() { 
	Jmol.script(instance0,'console');
	document.getElementById('instance0_console').innerHTML = consoleTxt;
	document.getElementById('runConsoleId').style='display: none';
	isConsoleVisible= true;
	}
maskConsole = function() { 
	document.getElementById('instance0_console').style.opacity=0;
	document.getElementById('maskConsoleId').style='display: none';
	document.getElementById('showConsoleId').style='display: block';
	isConsoleVisible= false;
	}
showConsole = function() { 
	document.getElementById('instance0_console').style.opacity=1;
	document.getElementById('showConsoleId').style='display: none';
	document.getElementById('maskConsoleId').style='display: block';
	isConsoleVisible= true;
	}
</script>

Il serait possible de personnaliser davantage cette console en ajoutant une feuille de style. La console est divisée en deux parties; la partie supérieure est un input text-area dans lequel JSmol affiche l'historique de toutes les commandes ou d'autres résultats de ces commandes; on ne peut y écrire, mais on peut en copier le contenu ; la partie inférieure est est un input text-area ou l'utilisateur peut écire des commandes ou des scripts (il n'y a pas de contrôle de la syntaxe contrairement à Jmol).

Menu ↑

Un clic droit sur le canvas de JSmol affiche un menu popup contenant par défaut l'essentiel des commandes, qu'il s'agisse de la gestion des fichiers ou des modalités d'affichage de la molécule une fois celle-ci chargée.

Ce menu est personnalisable; la commande de script qui suit remplace le menu par défaut par celui défini dans un fichier d'extension .mnu (Consultez en bas de paragraphe la référence Custom Menus pour connaitre la syntaxe à utiliser dans de ce fichier.

Choisir un menu très réduit: load menu "jsmol_custom.mnu"
Revenir au menu par défaut: load menu ""

Si le contenu du menu popup est personnalisable, son apparence ne l'est pas (ou bien cela semble très difficile). Je n'ai pas réussi à utiliser la fonction ci-dessous présente dans l'API:


Jmol.setMenuCss = function(cssClass, text) {
	cssClass != null && (Jmol.controls._menuCssClass = cssClass);
	Jmol.controls._menuCssText = text ? text + " ": cssClass ? "class=\"" + cssClass + "\" " : "";
	}

Pourtant la taille des caractères est ridiculement faible, ce qui rend ce menu très peu utilisable.

Custom_Menus

Remplacer la console (ou le menu) ↑

Reférences ↑

Aide
C'est la page officielle affichée par la commande Help. Trop impressionante mais la plus complète. Les exemples affichés par le menu déroulant du même nom (en haut sur la barre bleue sont complexes mais très intéressants).

exemples
Les pages de démonstration de JSmol (tout ne fonctionne pas, c'est aussi un test de votre système sur la machine cliente (en particulier de l'installation ou non de Java).

La coloration syntaxique du code Javascript et HTML est assurée par Prism.

Adresse de cette page: http://www.didac-tic.fr/pdb/demo_interface.php