listbox

 

listbox - Crée et manipule les widgets de type listbox


SYNTAXE

 listbox pathName ?options?

OPTIONS STANDARDS


  -background
  -borderwidth
  -cursor
  -disabledforeground
  -exportselection
  -font
  -foreground
  -height
  -highlightbackground
  -highlightcolor
  -highlightthickness
  -relief
  -selectbackground
  -selectborderwidth
  -selectforeground
  -setgrid
  -state
  -takefocus
  -width
  -xscrollcommand
  -yscrollcommand

OPTIONS SPÉCIFIQUES


Command-Line Name: -height

Database Name: height

Database Class: Height

Spécifie la hauteur souhaitée de la fenêtre, en nombre de lignes. Si la valeur est inférieure ou égale à zero, le widget prend une taille suffisante pour contenir tous les éléments de la liste.

Command-Line Name: -listvariable

Database Name: listVariable

Database Class: variable

Spécifie le nom d'une variable. La valeur de la variable correspond à la liste à afficher dans le widget; si la valeur de la variable est modifiée, le widget est automatiquement mis à jour pour refléter cette nouvelle valeur. Une tentative d'assignation d'une variable contenant une liste invalide à -listvariable entraînera une erreur. Une tentative de suppression (unset) d'une variable utilisée par -listvariable échouera, mais n’entraînera pas d'erreur.

Command-Line Name: -selectmode

Database Name: selectMode

Database Class: SelectMode

Spécifie un des différents styles de manipulation de sélection. La valeur de cette option peut être arbitraire, mais le bindings par défaut n'accepte que single, browse, multiple, et extended; la valeur par défaut est browse.

Command-Line Name: -state

Database Name: state

Database Class: State

Spécifie un des deux états de la listbox: normal or disabled. Si la listbox est désactivée, aucune entrée ne peut être rajoutée ou supprimée, les entrées sont affichées avec la couleur -disabledforeground, et la sélection ne peut être modifiée ou visualisée (bien que les informations sur la sélection soient conservées).

Command-Line Name: -width

Database Name: width

Database Class: Width

Spécifie la hauteur désirée de la fenetre, en nombre de caractères. Si la police de caractère utilisée est à taille variable, la largeur du caractère ``0'' est utilisée pour convertir la largeur spécifiée en unités d'écran. Si la valeur est inférieure ou égale à zero, le widget prend une taille suffisante pour contenir tous les éléments de la liste.


DESCRIPTION


La commande listbox crée une nouvelle fenêtre (spécifiée par l'argument pathName) et y intègre un widget de type listbox. Des arguments supplémentaires, décrits ci-dessus, peuvent être spécifiés sur la ligne de commande ou dans la base de données des options pour configurer l'aspect de la listbox, comme ses couleurs, sa police de caractères et son relief. La commande listbox retourne son argument pathName. A l'instant où cette commande est appelée, il ne doit pas exister de fenêtre nommée pathName, mais son parent doit exister.

Une listbox est un widget qui affiche une liste de chaînes de caractères, une chaîne étant affichée par ligne. A sa création, la nouvelle listbox n'a aucun élément. Les éléments peuvent être ajoutés ou supprimés en utilisant des commandes du widget décrites ci-dessous. De plus, un ou plusieurs éléments peuvent être sélectionnés comme décrit ci-dessous. Si la listbox exporte sa sélection (voir l’option exportSelection), elle observe le standard du protocole X11 en ce qui concerne la gestion de la sélection. Les sélection d'une Listbox sont disponibles en tant que type string; la valeur de la sélection correspond au texte des éléments sélectionnés, chaque élément étant séparé par the valeur le caractère de saut de ligne.

Il n'est pas nécessaire que tous les éléments soient affichés en même temps dans la fenêtre de la listbox; des commandes décrites ci-dessous peuvent être utilisées pour changer la vue de la fenêtre. Les listbox autorisent le défilement de leur contenu dans les deux direction, en utilisant les options standards xScrollCommand et yScrollCommand. Elles supportent également le balayage (scanning), comme décrit ci-dessous.


INDICES


Certaines des commandes du widget listbox prennent un ou plusieurs indices comme argument. Un index permet de spécifier de plusieurs façon différent un élément particulier de la listbox :

number Spécifie l'élément avec son index numérique, où 0 correspond au premier élément de la listbox.

active Indique l'élément qui est sous le curseur de position. Cet élément est souligné lorsque la listbox possède le focus clavier, et est spécifié avec la commande activate du widget.

anchor Indique le point d'ancrage de la sélection, qui est défini avec la commande selection du widget.

end Indique la fin de la liste. Pour la plupart des commandes, cela fait référence au dernier élément de la liste, mais pour certaines commandes comme index and insert, cela fait référence à l'élément juste après le dernier.

@x,y Indique l'élément qui couvre le point de la fenêtre de la listbox spécifié par x et y (en coordonnées pixel). Si aucun élément ne couvre ce point, c'est élément le plus proche qui est utilisé..

Dans les commandes du widget décrites ci-dessous, les arguments nommés index, first, et last contiennent toujours un indice respectant l'une des formes décrites ci-dessus.


COMMANDES DE WIDGET


La commande listbox crée une nouvelle commande Tcl dont le nom est pathName. cette commande peut être utilisée pour appeler diverses opérations sur le widget. Elle a la forme générale suivante :

 ''pathName option ''?''arg arg ...''?

Option et les args déterminent le comportement exact de la commande. Les commandes suivantes sont disponibles pour les widgets de type listbox :

pathName activate index Sets the active element to the one indicated by index. If index is outside the range of elements in the listbox then the closest element is activated. The active element is drawn with an underline when the widget has the input focus, and its index may be retrieved with the index active.

pathName bbox index Retourne une liste de quatre chiffres décrivant les limites (bounding box) de l’élément désigné par index. Les deux premiers éléments de lune liste donnent les coordonnées x et y du coin supérieur gauche de l'aire d'écran occupée par le texte de l'élément (en pixels relatifs au widget) et les deux derniers éléments indiquent les largeur et hauteur de la zone, en pixels. Si aucune partie de l'élément spécifié par index n'est visible sur l'écran, ou si index fait référence à un élément inexistant, le résultat de cette commande est une chaîne vide; si l'élément est partiellement visible, le résultat correspond à la surface complète de cet élément, y compris les parties non visibles.

pathName cget option Retourne la valeur courante de l'option de configuration donnée par option. Option peut prendre n'importe quelle des valeurs acceptées par la commande listbox.

pathName configure ?option? ?valeur option valeur ...? Interroge ou modifie les options de configuration du widget. Si aucune option n'est spécifiée, retourne une liste décrivant toutes les options disponibles pour pathName (voir ConfigWidg pour une information sur le format de cette liste). Si option est spécifiée sans valeur, alors la commande retourne une liste décrivant cette option (cette liste sera identique à la sous-liste des valeurs correspondante retournée si aucune option n'est spécifiée). Si une ou plusieurs paires option-valeur sont spécifiées, alors la commande modifie l'option(s) donnée(s); dans ce cas la commande retourne une chaîne vide. Option peut prendre n'importe quelle des valeurs acceptées par la commande listbox.

pathName curselection Retourne une liste contenant la liste des indices numériques de tous les éléments de la listbox qui sont actuellement sélectionnés. Si aucun élément n'est sélectionné, une chaîne vide est retournée.

pathName delete first ?last? Supprime un ou plusieurs éléments de la listbox. First et last sont les indices spécifiant le premier et le dernier élément de l’intervalle à supprimer. Si last n'est pas précisé, sa valeur par défaut est celle de first, c.a.d. un seul élément est supprimé.

pathName get first ?last? Si last est omis, retourne le contenu de l'élément de la listbox spécifié par first, ou une chaine vide si first fait référence à un élément inexistant. Si last est spécifié, la commande retourne une liste dont les éléments sont tous ceux compris entre first and last, bornes comprises. First et last peuvent avoir chacune des formes standards des indices.

pathName index index Retourne une valeur entière de l'index correspondant à l'index index. Si index est end, la valeur retournée est le nombre d'éléments dans la listbox (et non pas l'index du dernier élément).

pathName insert index ?element element ...? Insère zero ou plusieurs nouveaux éléments dans la liste, juste avant l'élément indiqué par index. Si index est end, les nouveaux éléments sont ajoutés à la fin de la liste. Retourne une chaine vide.

pathName itemcget index option Retourne la valeur courante de l'option de configuration d'éléments donnée pas option. Option peut prendre n'importe quelle des valeurs acceptées par la commande listbox itemconfigure.

pathName itemconfigure index ?option? ?valeur? ?option valeur ...? Interroge ou modifie les options de configuration d'un élément de la listbix. Si aucune option n'est spécifiée, retourne une liste décrivant toutes les options disponibles pour un élément' (voir ConfigWid]' pour une information sur le format de cette liste). Si option est spécifiée sans valeur, alors la commande retourne une liste décrivant cette option (cette liste sera identique à la sous-liste des valeurs correspondante retournée si aucune option'' n'est spécifiée). Si une ou plusieurs paires option-valeur sont spécifiées, alors la commande modifie l'option(s) donnée(s); dans ce cas la commande retourne une chaîne vide. Les options suivantes sont actuellement supportées pour les éléments :

-background couleur Couleur spécifie la couleur d'arrière-plan à utiliser quand un élément est affiché. Elle peut prendre n'importe quelle des formes acceptées par GetColor.

-foreground couleur Couleur spécifie la couleur de premier-plan à utiliser quand un élément est affiché. Elle peut prendre n'importe quelle des formes acceptées par GetColor.

-selectbackground couleur Couleur spécifie la couleur d'arrière-plan à utiliser quand un élément est affiché alors qu'il est sélectionné. Elle peut prendre n'importe quelle des formes acceptées par GetColor.

-selectforeground couleur Couleur spécifie la couleur de premier-plan à utiliser quand un élément est affiché alors qu'il est sélectionné. Elle peut prendre n'importe quelle des formes acceptées par GetColor.

pathName nearest y En lui donnant une coordonnée y, cette commande retourne l'index de l'élément (visible) de la listbox le plus proche de cette coordonnée y.

pathName scan option args Cette commande est utilisée pour pouvoir implémenter un balayage (scanning) des éléments de la liste. Elle a deux forme, selon la valeur de option :

pathName scan mark x y Enregistre x et y, ainsi que la vue courante dans la fenêtre de la listebix; utilisé en conjonction avec des commandes scan dragto futures. Cette commande est généralement associée au clic de souris dans le widget. Elle retourne une chaîne vide.

pathName scan dragto x y. Cette commande calcule la différence entre ses arguments x et y, et les arguments x et y de la dernière commande scan mark de ce widget. Elle corrige alors la vue de 10 fois la différence des coordonnées. cette commande est généralement associée aux événements déplacement de souris dans le widget, pour produire un effet de dragging de la listbox à grande vitesse au travers de la fenêtre. La valeur de retour est une chaîne vide.

pathName see index Ajuste la vue de la listbox afin que l'élément index soit visible. Si l'élément est déjà visible, cette commande n'a aucun effet; si l'élément est proche d'une limite de la fenêtre, la listbox défile afin que cette élément soit dans la vue, près de cette limite; sinon, la listbox défile pour centrer cet élément.

pathName selection option arg Cette commande est utilisée pour ajuster la sélection dans une listbox. Elle a plusieurs formes, selon la valeur de option :

pathName selection anchor index Positionne l'ancre de sélection sur l'élément index. Si index fait référence à un élément inexistant, c'est l'élément le plus proche qui est utilisé. L'ancre de sélection correspond la fin de la sélection, qui reste fixe lorsque l'on fait glisser la sélection vers l'extérieur avec la souris (drag). L'index anchor peut être utilisé pour faire référence à l'élément possédant sur lequel l'ancre est positionnée.

pathName selection clear first ?last? Si certains des éléments compris entre first et last (bornes comprises) sont sélectionnés, ils sont retirés de la liste des éléments sélectionnés. L'état de sélection n'est pas modifié pour les éléments en dehors de ces limites.

pathName selection includes index Retourne 1 si l'élément indiqué par index est actuellement sélectionné, 0 sinon.

pathName selection set first ?last? Sélectionne tous les éléments compris entre first et last, bornes incluses, sans affecter l'état de sélection des éléments se trouvant en dehors de ces limites.

pathName size Retourne une chaine de caractère décimale, représentant le nombre total d'élément dans la listbox..

pathName xview args Cette commande est utilisée pour consulter et changer la position horizontale du texte affiché dans la fenêtre du widget. Elle peut prendre n'importe quelle des formes suivantes :

pathName xview Retourne une liste contenant deux éléments. Chaque élément est une fraction comprise entre 0 et 1; ensemble ils décrivent la portion horizontale visible dans la fenêtre. Par exemple, si le premier élément est .2 et le second élément est .6, 20% du texte de l'entrée de texte est hors écran à gauche, les 40% intermédiaires sont visibles dans la fenêtre, et 40% du texte est hors écran à droite. Ce sont les même valeurs transmises aux scrollbars via l'option -xscrollcommand.

pathName xview index Ajuste la vue dans la fenêtre pour que le caractère désigné par index soit affiché à l'extrémité gauche de la fenêtre. La position des caractères est définie par la largeur du caractère 0.

pathName xview moveto fraction Ajuste la vue de la fenêtre pour que cette fraction de la largeur totale du texte de la listbox soit hors de l'écran à. fraction doit être compris entre 0 et 1.

pathName xview scroll number what Cette commande décale la vue dans la fenêtre à gauche ou à droite en fonction de number et what. Number doit être un entier. What doit être soit units soit pages ou une abréviation d'un des deux. Si what est units, la vue est ajustée à gauche ou à droite de number fois la largeur du caractère 0; s'il est pages, la vue est ajustée de number fois la largeur de la fenêtre. Si number est négatif alors les caractères les plus à gauche deviennent visibles; si il est positif alors les caractères les plus à droite deviennent visibles.

pathName yview ?args? Cette commande est utilisée pour consulter et changer la position verticale du texte affiché dans la fenêtre du widget. Elle peut prendre n'importe quelle des formes suivantes :

pathName yview Retourne une liste contenant deux éléments. Chaque élément est une fraction comprise entre 0 et 1. Le premier élément donne la position de l'élément de la listbox qui se trouve en haut de la fenêtre par rapport à la liste complète (par exemple, 0.5 veut dire que la liste est parcourue à moitié). Le second élément donne la position de l'élément de la listbox qui se trouve juste après le dernier affiché dans la fenêtre, par rapport à la liste complète. Ce sont les même valeurs transmises aux scrollbars via l'option -yscrollcommand.

pathName yview index Ajuste la vue dans la fenêtre pour que l'élément désigné par index soit affiché en haut de la fenêtre.

pathName yview moveto fraction Ajuste la vue dans la fenêtre pour que l'élément désigné par index apparaisse en haut de la fenêtre. Fraction est une fraction entre 0 et 1; 0 représente le premier élément de la liste, 0.33 représente l'élément situé au premier tiers de la liste, et ainsi de suite..

pathName yview scroll number what Cette commande décale la vue dans la fenêtre vers le haut ou le bas, en fonction de number et what. Number doit être un entier. What doit être soit units soit pages ou une abréviation d'un des deux. Si what est units, la vue est ajustée vers le haut ou le bas de number lignes; s'il est pages, la vue est ajustée de number fois la hauteur de la fenetre. Si number est négatif alors les éléments précédent deviennent visibles; si il est positif alors les éléments suivants deviennent visibles.


BINDINGS PAR DEFAUT


Tk crée automatiquement des bindings de classe pour les widgets listbox, afin de leur donner un comportement semblable à Motif. La plupart des comportements de la listbox sont déterminés par l'option selectMode, qui permet de sélectionner l'une des quatre méthode de gestion de la sélection.

Si le mode de sélection est single ou browse, un seul élément peut être sélectionner à la fois. Dans ces deux modes, le fait de cliquer sur un élément avec le bouton 1 de la souris sélectionne cet élément, et désélectionne tous les autres éléments précédemment sélectionnés. Dans le mode browse, il est aussi possible de faire glisser la sélection avec le bouton 1.

Si le mode de sélection est multiple ou extended, un nombre quelconque d'éléments peuvent être sélectionnés simultanément, non nécessairement consécutifs. Dans le mode multiple, le fait de cliquer sur un élément avec le bouton 1 change l'état de sélection de cet élément, sans affecter les autres éléments. Dans le mode extended, l'appui du bouton 1 sur un élément a pour effet de le sélectionner, de désélectionner tous les autres éléments, et de positionner l'ancre de sélection sur l'élément situé sous la souris; en faisant alors glisser la souris tout en maintenant le bouton 1 appuyé, la sélection est élargie afin d'inclure tous les éléments entre l'ancre de sélection et l'élément présent sous la souris, ces deux bornes étant elles aussi sélectionnées.

La plupart des personnes utilise généralement le mode browse pour les sélections simples, et le mode extended pour les sélections multiples; les autres modes ne sont intéressantes que dans des situations très spéciales.

A chaque fois que la sélection dans la listbox est modifiée, un événement virtuel <<ListboxSelect>> est généré. Il est très facile de se lier à cet événement (bind) lorsque l'on souhaite gérer les changements de sélection de la listbox.

En plus du comportement décrit ci-dessus, les comportements suivants sont aussi définis par le binding par défaut :

[1] Dans le mode extended, l'intervalle de sélection peut être ajusté en pressant sur le bouton 1 pendant que la touche Shift est enfoncée; cela a pour effet de sélectionner les éléments situés entre l'ancre de sélection et l'élément situé sous la souris, bornes incluses. L'extrémité de la nouvelle sélection qui n'est pas l'ancre de sélection peut être glissée en maintenant le bouton 1 appuyé.

[2] Dans le mode extended, l'appui sur le bouton 1 pendant que la touche Control est enfoncée permet de commencer l'opération d'inversion de sélection : l'ancre de sélection est placée sur l'élément situé sous la souris, et son état de sélection est inversé. L'état de sélection es autres élément est conservé. Si la souris est déplacée pendant que le bouton 1 est maintenu appuyé, tous les éléments entre l'ancre de sélection et l'élément situé sous la souris sont mis dans le même état de sélection que l'élément possédant l'ancre; l'état de sélection des autres éléments reste inchangé.

[3] Si la souris sort de la fenetre de la listbox alors que le bouton 1 est maintenu pressé, la fenêtre défile de sorte que les éléments s'éloignent de la souris, rendant visible des éléments qui étaient hors de l'écran du côté où se trouve la souris. Le défilement continue jusqu'à ce que la souris entre à nouveau dans la fenêtre, que le bouton soit relâché, ou que la fin de la liste soit atteinte.

[4] Le bouton 2 peut être utilisé pour parcourir la liste. Si la souris est déplacée sur la liste pendant qu'il est appuyé, le contenu de la liste défile à grande vitesse dans la direction du mouvement de la souris.

[5] Si les touches Haut et Bas sont pressées, le curseur de position (l'élément actif) est déplacé d'un élément vers le haut ou vers le bas. Si le mode de sélection est browse ou extended, le nouvel élément est aussi sélectionné, et tous les autres éléments sont désélectionnés. Dans le mode extended, le nouvel élément actif devient l'ancre de sélection.

[6] Dans le mode extended, Shift-Haut et Shift-Bas permet de déplacer le curseur de position (l'élément actif) d'un élément vers le haut ou vers le bas, et étend aussi la sélection à cet élément, de la même façon que lors du déplacement de la souris avec le bouton 1 appuyé.

[7] Les touches Gauche et Droite font défiler le vue de la listbox à gauche ou à droite de la largeur du caractère 0. Control-Gauche and Control-Droit fait défiler la vue de la listbox à gauche ou à droite de la largeur de la fenêtre. Control-PageHaut et Control-PageBas fait aussi défiler la vue de la largeur de la fenêtre.

[8] Les touches PageHaut et PageBas font défiler la vue de la listbox vers le haut ou vers le bas d'une page (la hauteur de la fenêtre).

[9] Les touches Début (Home) et Fin font défiler la listbox horizontalement jusqu'à la limite gauche ou droite, respectivement.

[10] Control-Début positionne le curseur de position sur le premier élément de la liste, le sélectionne, et désélectionne tous les autres éléments.

[11] Control-Fin positionne le curseur de position sur le dernier élément de la liste, le sélectionne, et dessélectionne tous les autres éléments.

[12] Dans le mode extended, Control-Shift-Début étend la sélection jusqu'au premier élément de la liste, et Control-Shift-fin l'étend jusqu'au dernier élément.

[13] Dans le mode multiple, Control-Shift-Début place le curseur de position sur le premier élément de la liste, et Control-Shift-Fin le place sur le dernier élément.

[14] Les touches Espace et Select permettent de modifier l'état de sélection de l'élément ayant le curseur de position (l'élément actif) exactement comme si le bouton 1 de la souris avait été pressé sur cet élément.

[15] Dans le mode extended, Control-Shift-Espace et Shift-Select étendent la sélection jusqu'à l'élément actif, comme si le bouton 1 avait été pressé avec la touche Shift enfoncée..

[16] Dans le mode extended, la touche Escape annule la dernière sélection effectuée, et restaure la sélection de tous les éléments dans l'état où ils étaient avant cette sélection.

[17] Control-/ permet de sélectionner tous les éléments de la listbox, sauf dans les modes single et browse dans lequel cela sélectionne l'élément actif et dessélectionne tous les autres.

[18] Control-\ permet de dessélectionner tous les éléments de la listbox, sauf dans le mode browse dans lequel cela n'a aucun effet.

[19] Les touches F16 (portant généralement le nom Copy sur les stations de travail Sun) et Meta-w copient le texte de la sélection dans le blocnote, s'il y a une sélection.

Le comportement des widgets de type listbox peut être modifié en redéfinissant de nouveaux bindings pour certains widget, ou en redéfinissant les bindings de la classe.


Traduit par Michel Salvagniac 2002-2003

Copyright © 2003 - Le Wiki Tcl/Tk Francophone.


Voir aussi


Catégorie Manuel Tcl/Tk