Ouverture et fermeture de popups
Les popups et menus peuvent être ouverts et fermés depuis un script.
Ouverture d'un menu
Les menus s'afficheront d'eux-mêmes automatiquement dès que nécessaire sans aucun travail supplémentaire. Par exemple, le popup d'un menu s'ouvrira lors d'un clic sur le label de menu, et un sous-menu s'ouvrira lors du passage de la souris sur l'élément du menu parent.
Cependant, vous pourrez vouloir ouvrir un menu manuellement dans certaines situations. L'élement menu a une propriété open qui peut être définie à true pour ouvrir le menu, ou false pour le fermer. Un exemple simple :
un_menu.open = true;
Cette unique ligne de code ouvrira un menu référencé par la variable « un_menu ». Notez que la propriété open s'applique au menu ou au bouton, pas à l'élément menupopup. Voici un exemple complet utilisant un bouton pour ouvrir un menu :
<button label="Ouvrir un menu"
oncommand="document.getElementById('editMenu').open = true;"/>
<menu id="editMenu" label="Édition">
<menupopup>
<menuitem label="Couper"/>
<menuitem label="Copier"/>
<menuitem label="Coller"/>
</menupopup>
</menu>
Cette technique peut être utilisée pour les menupopups qui utilisent la balise menu tant que pour ceux qui utilisent les balises button et toolbarbutton. Pour les menupopups attachés à d'autres éléments à l'aide des attributs popup ou context, consultez
Ouverture d'un popup plus bas.
Comme avec les autres manières d'ouvrir un menu, l'évènement popupshowing sera déclenché pour permettre de personnaliser les commandes apparaissant dans le menu.
Dans certaines situations, il n'est pas permis d'ouvrir un menu :
- si le menu est déjà ouvert, ou en cours d'ouverture. Naturellement, essayer d'ouvrir un menu qui est déjà ouvert n'aura aucun effet.
- si le menu est l'enfant d'un autre menu et que ce menu parent n'est pas ouvert. Dans ce cas, le menu parent doit d'abord être ouvert. Si vous voulez ouvrir un sous-menu, ouvrez d'abord le menu parent, puis le sous-menu dans un gestionnaire d'évènement
popupshown. Consultez L'évènement popupshown pour un exemple de réalisation. - un menu dans une fenêtre de contenu sans privilèges (comme une page Web) ne peut ouvrir un popup que si sa fenêtre a le focus, et qu'il est dans l'onglet actif. Cela signifie qu'un document dans un onglet d'arrière-plan ne peut ouvrir de menu ou de popup.
Fermeture d'un menu
Un menu se fermera automatiquement une fois que l'utilisateur a fait une sélection depuis celui-ci. Lorsqu'un élément de menu est sélectionné, il déclenche un évènement de commande afin que du code puisse être utilisé pour effectuer une action. L'utilisateur peut annuler la sélection d'une commande en appuyant sur la touche Échap. Ceci fermera un menu simple, mais s'il avait un menu parent, celui-ci restera ouvert. Un utilisateur peut également annuler la sélection en cliquant end ehors du menu. Dans ce cas, non seulement le menu sera fermé, mais tous les menus parents le seront également.
Un menu peut être fermé par un script en définissant la propriété open à false, le contraire de ce qu'on ferait pour ouvrir le menu. La propriété open s'applique au menu ou au bouton, mais pas au menupopup.
un_menu.open = false;
Cette commande fermera uniquement un seul niveau de menus, de sorte que tout menu parent devra être fermé avec une commande semblable si nécessaire. Cependant, les éventuels menus enfants de « un_menu » dans cet exemple seront fermé puisque celui-ci ne sera plus ouvert. Par exemple, disons qu'un menu Fichier a un sous-menu contenant une liste de fichiers récemment utilisés. Si les deux menus sont ouverts et que l'on met la propriété open du sous-menu à false, celui-ci sera fermé mais le menu Fichier parent restera ouvert. D'un autre côté, si c'est la propriété open du menu Fichier qui est mise à false, les deux menus se fermeront.
Cette technique peut être utilisée tant pour les menupopups qui utilisent les balises menu et button que toolbarbutton. Pour les menupopups attachés à d'autres éléments à l'aide des attributs popup ou context, consultez
Fermeture d'un popup plus bas.
Lorsqu'un menu est fermé, l'évènement popuphiding est déclenché sur celui-ci. On peut donc attacher un écouteur sur cet évènement pour retirer toute commande qui avait été ajoutée au cours de l'évènement popupshowing.
Les menus et popups seront également fermés lorsque le document ou la fenêtre dans lesquels ils sont contenus seront fermés, ou si l'élément menupopup est retiré du document. Ce sont des situations dans lesquelles les évènements popuphiding et popuphidden peuvent ne pas se déclencher étant donné que les éléments concernés ne sont plus disponibles. Si des actions spécifiques doivent être effectués à ce moment-là, il vaut mieux utiliser un évènement unload.
Test de l'état d'ouverture d'un menu
Pour vérifier si un menu est ouvert, vérifiez l'état de sa propriété open. Si celle-ci vaut true, le menu est ouvert, sinon il est fermé.
var open = un_menu.open;
Ouverture d'un popup
Pour ouvrir des popups de menu utilisant les balises menu, button et toolbarbutton, consultez Ouverture d'un menu plus haut.
Les popups attachés à l'aide de l'attribut popup sont ouverts lors d'un clic gauche de la souris par l'utilisateur. Il n'y a pas moyen d'effectuer la même action à partir du clavier, vous devrez donc toujours fournir une manière alternative d'accéder aux fonctionnalités du menu. Cela peut se faire soit en plaçant des commandes alternatives ailleurs dans l'interface, ou en fournissant un raccourci clavier permettant d'ouvrir le menu. Une fois que celui-ci est ouvert, le clavier peut être utilisé pour y naviguer et sélectionner des éléments de la manière habituelle.
Les popups attachés à l'aide de l'attribut context sont ouvert lorsque l'utilisateur effectue une action essayant d'ouvrir un menu contextuel. Cette action diffère selon la plateforme, mais en général il s'agit de cliquer sur l'élément avec le bouton de droite de la souris. Sur les systèmes Macintosh avec un seul bouton, un menu contextuel peut être ouvert soit en maintenant le bouton de la souris enfoncé, soit en appuyant sur la touche Control lors du clic sur le bouton. Sous Windows, le menu contextuel peut également être ouvert à l'aide de la touche menu sur le clavier (Il s'agit de la touche figurant sur de nombreux claviers à côté de la touche Ctrl de droite avec une image de menu) ou en appuyant sur Shift+F10. Pour cette raison, il ne faut pas supposer que l'utilisateur a forcément utilisé la souris pour ouvrir le menu contextuel.
La méthode openPopup
Quel que soit le type de popup, il peut être nécessaire de l'ouvrir programmatiquement. Pour ce faire, utilisez la méthode openPopup du popup. Cette méthode peut être utilisée pour tout type de popup, qu'il s'agisse d'un menupopup, d'un panel ou un tooltip, même ceux qui peuvent être ouverts par d'autres moyens, par exemple un popup attaché par l'attribut context.
La méthode openPopup peut recevoir six paramètres qui sont utilisés pour indiquer comment et où le popup doit être positionné. Ils seront décrits plus loin. La méthode openPopup est définie comme suit :
void openPopup(in DOMElement anchorElement,
in String position,
in long x,
in long y,
in boolean estMenuContextuel,
in boolean ecraserAttributs);
Tout d'abord, un exemple :
un_popup.openPopup(ancre, "after_start", 0, 0, false, false);
Cet exemple ouvrira un popup situé juste sous un autre élément référencé par « ancre ». Ceci émula la façon dont s'ouvre un menu, où « ancre » serait l'élément menu. Il est possible d'utiliser la méthode openPopup avec un menu, cependant il est plus facile de définir simplement l'attribut open du menu à true, ce qui gèrera le positionnement du menu à votre place. Notez que si l'attribut open s'applique au menu ou bouton parent, la méthode openPopup s'applique à l'élément menupopup.
L'ancre d'un popup est le nœud élément à côté duquel le popup sera affiché. Par exemple, pour qu'un popup apparaisse à côté d'un bouton, passez une référence au bouton comme premier paramètre de la méthode openPopup. Dans cet exemple, le popup sera ouvert relativement à l'élément du document.
un_popup.openPopup(document.documentElement, "end_before", 0, 0, false, false);
Le second paramètre d'openPopup est la position par rapport à l'ancre, qui indique de quel côté de celle-ci le popup sera positionné. Par exemple, la valeur « end_before » utilisée dans l'exemple précédent indique de placer le côté gauche du popup le long du bord droit de l'élément d'ancrage, avec les deux bords supérieurs alignés. Cela peut être compliqué à comprendre, consultez alors Positionnement d'un popup qui décrit ce processus plus en détail et fournit des images montrant les valeurs possibles et la façon dont serait aligné un popup pour chacune des valeurs.
Les troisième et quatrième paramètres d'openPopup sont des décalages x et y. Après le positionnement initial du popup, il est possible de l'ajuster en spécifiant des valeurs non nulles pour ces décalages. Ceci permet de contrôler précisément le popup tout en étant toujours ancré à un élément particulier. Des valeurs positives peuvent être utilisées pour ajuster le popup vers la droite ou vers le bas et des valeurs négatives pour l'ajuster vers la gauche ou le haut.
Dans l'exemple qui suit, le popup est ancré sous un élément, tout en étant décalé de 10 pixels vers la droite et de 2 pixels vers le haut.
un_popup.openPopup(ancre, "after_start", 10, -2, false, false);
Notez que l'ancre et les décalages spécifient uniquement la position lors de l'ouverture du popup. Si l'ancre est déplacée ou supprimée tandis que le popup est ouvert, le popup ne suivra pas. Cependant, il est possible de déplacer un popup pendant qu'il est ouvert, consultez Déplacement et redimensionnement d'un popup.
Le cinquième paramètre d'openPopup, isContextMenu, indique si le popup est ouvert comme un menu contextuel. Passez true si c'est le cas et false dans le cas contraire. Le valeur à passer devrait être évidente selon l'endroit dont vous appelez openPopup. Notez que le même menu peut être ouvert des deux manières, ce paramètre n'influe donc pas sur la manière dont le popup apparaît. Ce qu'il modifie est la manière dont le focus et la sélection du menu sont gérés. Tant que vous passez la bonne valeur par rapport à la situation, il n'est pas très important de connaître les différences particulières entre les deux cas.
Cependant, vous pouvez voir l'effet de ce paramètre en utilisant les marque-pages de Firefox. Essayez d'ouvrir un sous-menu des marque-pages et notez comme la sélection change toujours lorsque la souris est déplacé vers d'autres menus, et la manière dont le sous-menu est fermé lorsque la souris le quitte. Ouvrez à présent un menu contextuel sur le même marque-page et remarquez que les autres menus ne sont pas affectés par le mouvement de la souris. C'est cette différence qui est gérée par le paramètre isContextMenu.
Enfin, le dernier paramètre de la méthode openPopup, ecraserAttributs indique si les attributs placés sur l'élément popup écrasent les paramètres fournis. Ceci permet à un popup d'utiliser un comportement particulier de positionnement avec les attributs position, left et top à la place. Plus de détails sur ces attributs peuvent être trouvés dans la section Positionnement d'un popup.
Popups non ancrés avec openPopup
Si le premier paramètre de la méthode openPopup vaut null, un popup non ancré est créé. Dans ce cas, le deuxième argument de positionnement n'est pas utilisé et une chaîne vide peut être utilisée. Voici un exemple :
un_popup.openPopup(null, "", 60, 50, false, false);
Un popup non ancré utilise les décalages x et y, dans ce cas 60 et 50 sont des décalages depuis le coin de la fenêtre ou du cadre. De cette manière, un popup peut être positionné relativement à la fenêtre plutôt qu'à un nœud spécifique. Par exemple, il peut être intéressant d'ouvrir un popup à la position courante de la souris au moment du clic. Voici un exemple de gestionnaire d'évènement de clic de souris :
function mouseClicked(event)
{
var panel = document.getElementById("un-panel");
panel.openPopup(null, "", event.clientX, event.clientY, false, false);
}
La méthode openPopupAtScreen
Une seconde méthode, openPopupAtScreen, peut être utilisée pour ouvrir un popup et le placer à des coordonnées précise sur l'écran. Dans ce cas, le popup n'est pas ancré à un élément et apparaît simplement à l'emplacement spécifié par les paramètres x et y passés à cette méthode.
void openPopupAtScreen(in long x, in long y, in boolean estMenuContextuel);
Le paramètre ecraserAttributs indique qu'un menu contextuel est ouvert et fonctionne de la même façon que pour la méthode openPopup. Dans l'exemple qui suit, le popup est ouvert à la position horizontale 100 et à la position verticale 200 :
popup.openPopupAtScreen(100, 200, false);
Notez que si les coordonnées fournies auraient conduit à un popup situé partiellement ou totalement hors de l'écran, celui-ci sera déplacé de manière à être totalement visible, et pourra être redimensionné si nécessaire.
Fermeture d'un popup avec la méthode hidePopup
Un menu popup est fermé par l'utilisateur en appuyant sur la touche Échap ou en cliquant quelque part en dehors du popup.
Pour fermer des menupopups utilisant les balises menu, button et toolbarbutton, consultez Fermeture d'un menu plus haut.
Pour fermer un menu depuis un script utilisez sa méthode hidePopup. Elle ne prend aucun paramètre.
popup.hidePopup();
Déterminer si un popup est ouvert
Pour les menus, il est possible de vérifier la propriété open de l'élément menu, button ou toolbarbutton. Si celle-ci vaut true, le menu est ouvert.
Pour les autres types de popups, la propriété state peut être examinée à cette fin. Elle est disponible pour tous les types de popups, qu'il s'agisse de menus, panels ou de tooltips. Lorsqu'un menu est fermé, la propriété state aura la valeur closed, tandis que pour un popup visible, elle aura la valeur open. Cette propriété est en lecture seule et s'applique aux éléments menupopup, panel ou tooltip.
La propriété state peut également avoir deux autres valeurs, utilisées lorsqu'un popup est en train de passer de l'état ouvert à l'état fermé et vice versa. Lorsqu'un popup est en train de s'ouvrir, la propriété state a une valeur de showing tandis qu'elle aura une valeur hiding au cours de de sa fermeture. La première se rencontrera au cours de l'évènement popupshowing, tandis que la seconde se rencontrera au cours de l'évènement popuphiding.
Par exemple, la propriété state pourrait être utilisée pour déterminer si un panel est déjà ouvert. Si c'est le cas, vous pouvez vouloir éviter de manipuler l'interface utilisateur de la fenêtre principale, étant donné que l'utilisateur ne sera plus directement en train d'interagir avec elle.