radialmenu — u_pbt_radialmenu #

← Référence des composants · Sommaire du guide

Menu contextuel radial : les commandes en couronne autour du curseur, choisies par leur direction plutôt qu'en parcourant une liste.

▶ Le voir en vrai — Application de démonstration, tuile Radial menu : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

// Une roue montée pour ce qui est sous le curseur
uo_wheel.of_add_item(/*keys*/ "cut",    /*text*/ "Cut")
uo_wheel.of_add_item(/*keys*/ "copy",   /*text*/ "Copy")
uo_wheel.of_add_item(/*keys*/ "paste",  /*text*/ "Paste")
uo_wheel.of_add_item(/*keys*/ "delete", /*text*/ "Delete")

// Elle s'ouvre au relâchement du bouton droit : voir ue_rclicked

Ouvrir, puis choisir #

La roue s'ouvre au relâchement du bouton droit, et il faut un second clic pour choisir. Ce n'est pas un détail d'implémentation : si elle s'ouvrait sur l'appui, le relâchement de ce même clic sélectionnerait aussitôt le secteur tombé sous le curseur, et l'utilisateur déclencherait une commande sans l'avoir vue.

C'est pourquoi of_show() s'appelle depuis l'événement clic droit du contrôle sur lequel l'utilisateur fait le geste (un statictext, un button, une grille…) : à cet instant le bouton est déjà relâché, et le clic suivant est bien celui qui choisit. Le menu radial, lui, n'a aucune surface — donc aucun événement de souris à lui.

Le composant lui-même est invisible : il n'occupe aucune place dans la fenêtre. Posez-le n'importe où, donnez-lui une largeur et une hauteur nulles, il n'existe que le temps où la roue est ouverte.

La branche pointée — à la souris ou au clavier — montre son libellé entier, au-dessus de ses voisines : un secteur garde deux lignes au plus (une seule au-delà de huit branches), et c'est ce qui lui permet de porter un libellé court sans mentir sur ce qu'il fait. Le moyeu au centre est la sortie : le cliquer referme la roue ; dans une sous-roue, il fait remonter d'un niveau. Tant que la roue est ouverte, l'application continue de tourner : une branche retirée, grisée ou masquée entre-temps ne se choisit plus (ue_dismissed à la place), et of_clear, of_remove_item ou of_reset ferment la roue ouverte.

// Elle s'ouvre au relâchement du bouton droit : voir ue_rclicked
uo_wheel.of_show()

Au clavier, les flèches parcourent les branches en sautant les grisées, Entrée ou Espace choisit, ← et Retour arrière remontent d'un cran, et Échap remonte d'un cran dans une sous-roue — il ne ferme la roue qu'à la racine. Aucune de ces touches ne file dans l'application tant que la roue est ouverte. En lecture de droite à gauche, la couronne tourne dans l'autre sens et ← et → s'échangent : → remonte d'un cran.

Les sous-roues #

Une adresse accroche des branches sous une autre : export/pdf. Choisir la branche parente ne choisit rien : la roue est remplacée par celle de ses enfants, et le moyeu devient le retour.

Pourquoi remplacer plutôt qu'ajouter une seconde couronne ? Parce qu'un anneau extérieur diviserait les secteurs par deux à chaque niveau. Huit branches est déjà le maximum lisible ; on n'a pas les moyens d'en afficher deux niveaux à la fois.

L'événement ue_item_selected rapporte l'adresse complète (export/pdf), pas la clé de la feuille seule. Deux sous-roues peuvent donc nommer leurs branches pareil sans ambiguïté.

// A branch, then two entries at its address
uo_wheel.of_add_item(/*keys*/ "export", /*text*/ "Export")
uo_wheel.of_add_item(/*keys*/ "export/pdf", /*text*/ "PDF")
uo_wheel.of_add_item(/*keys*/ "export/csv", /*text*/ "CSV")

Pour retirer une branche — sa sous-roue avec elle — sans reconstruire toute la roue : of_remove_item("export/csv"). Les autres branches restent en place.

Quand il y a trop de branches #

Une roue se lit par direction, et au-delà de huit secteurs les tranches cessent d'être distinguables. ii_max_sectors fixe ce plafond (de 3 à 12, 8 par défaut).

Les branches en trop ne sont pas perdues : la dernière place de la couronne devient une branche qui les contient toutes, et qui s'ouvre comme une sous-roue. Un menu qui laisserait tomber sa queue serait un menu qui ment sur ce qu'il propose.

Resserrer la couronne est souvent un gain : quatre branches larges se visent plus vite que huit étroites.

Propriétés #

Méthodes #

Événements #

Un clic dans un coin de la fenêtre, hors du disque, compte comme un clic dehors : la roue se referme (ue_dismissed) et le clic passe à l'application qui se trouve derrière, au lieu d'être avalé par un carré invisible.

Propriétés d'item #

Une branche n'affiche aucune info-bulle : la fenêtre ronde n'a pas de place hors du disque. Le is_tooltip hérité par la poignée est gardé et se relit, mais il n'est jamais montré — c'est la branche pointée qui montre son libellé entier.

Exemples #

Une roue par contexte #

// Une roue montée pour ce qui est sous le curseur
uo_wheel.of_clear()
uo_wheel.of_add_item(/*keys*/ "bold", /*text*/ "Bold", /*image*/ "mono:img\packimages.dll:svg/samples/bold", /*checked*/ true)
uo_wheel.of_add_item(/*keys*/ "find", /*text*/ "Find", /*image*/ "mono:img\packimages.dll:svg/samples/find", /*checked*/ false)

Réagir au chemin choisi #

// Événement ue_item_selected du menu radial
// as_keys porte le chemin complet, ex. "export/pdf"
choose case as_keys
	case "export/pdf"
		of_export_pdf()
	case "delete"
		of_delete_selection()
end choose

Marquer, griser, resserrer #

// Marquer une branche comme active
uo_wheel.of_item(/*keys*/ "bold").ib_checked = true

// Griser celle qui n'a pas de sens ici
uo_wheel.of_item(/*keys*/ "paste").ib_enabled = false

// Quatre branches au plus sur une couronne
uo_wheel.ii_max_sectors = 4

Bonnes pratiques #

• Ouvrez au clic droit RELÂCHÉ du contrôle, jamais sur l'appui. C'est ce qui sépare « ouvrir » de « choisir », et l'utilisateur a besoin des deux.
• Des libellés courts. Un ou deux mots. Le secteur est là pour la direction ; le texte entier ne se lit qu'en pointant la branche.
• Quatre à six branches valent mieux que huit. Une roue se retient par la position ; moins il y a de positions, plus vite elles s'apprennent.
• Mettez les commandes les plus fréquentes en haut et en bas. Ce sont les deux directions que la main atteint sans réfléchir.
• Gardez l'ordre stable d'une ouverture à l'autre : tout l'intérêt d'une roue est que le geste finisse par précéder la lecture.
• Un menu radial ne remplace pas un menu en liste. Vingt commandes rares se lisent mieux dans une liste ; réservez la roue à la poignée qu'on utilise sans cesse.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide