tkinter.ttk --- Tk themed widgets

Code source : Lib/tkinter/ttk.py


Le module tkinter.ttk donne accès à l'ensemble de widgets sur le thème Tk, introduit dans Tk 8.5. Il offre des avantages supplémentaires, notamment le rendu des polices avec anticrénelage sous X11 et la transparence des fenêtres (nécessitant un gestionnaire de fenêtres de composition sur X11).

L'idée de base de tkinter.ttk est de séparer, dans la mesure du possible, le code implémentant le comportement d'un widget du code implémentant son apparence.

Voir aussi

Tk Widget Styling Support

Document présentant la prise en charge des thèmes pour Tk

Utilisation de Ttk

Pour commencer à utiliser Ttk, importez son module :

from tkinter import ttk

Pour remplacer les widgets Tk de base, l'importation doit suivre l'importation Tk :

from tkinter import *
from tkinter.ttk import *

Ce code implique que plusieurs widgets tkinter.ttk (Button, Checkbutton, Entry, Frame, Label, LabelFrame, Menubutton, PanedWindow, Radiobutton, Scale et Scrollbar) remplacent automatiquement les widgets Tk.

L'avantage immédiat est d'utiliser les nouveaux widgets qui donnent une meilleure apparence sur toutes les plateformes ; cependant, les widgets de remplacement ne sont pas complètement compatibles. La principale différence est que les options de widget telles que "fg", "bg" et d'autres liées au style des widgets ne sont plus présentes dans les widgets Ttk. Utilisez plutôt la classe ttk.Style pour des effets de style améliorés.

Voir aussi

Converting existing applications to use Tile widgets

Monographie (utilisant la terminologie Tcl) sur les différences généralement rencontrées lors de la modification d'applications pour utiliser les nouveaux widgets.

Widgets Ttk

Ttk est livré avec 18 widgets, dont douze existaient déjà dans tkinter : Button, Checkbutton, Entry, Frame, Label, LabelFrame, Menubutton, PanedWindow, Radiobutton, Scale, Scrollbar et Spinbox. Les six autres sont nouveaux : Combobox, Notebook, Progressbar, Separator, Sizegrip et Treeview. Et tous sont des sous-classes de Widget.

L'utilisation des widgets Ttk donne à l'application une apparence et une convivialité améliorées. Comme indiqué ci-dessus, il existe des différences dans la façon dont le style est codé.

Code Tk :

l1 = tkinter.Label(text="Test", fg="black", bg="white")
l2 = tkinter.Label(text="Test", fg="black", bg="white")

Code Ttk :

style = ttk.Style()
style.configure("BW.TLabel", foreground="black", background="white")

l1 = ttk.Label(text="Test", style="BW.TLabel")
l2 = ttk.Label(text="Test", style="BW.TLabel")

Pour plus d'informations sur TtkStyling, consultez la documentation de la classe Style.

Widget

ttk.Widget définit les options et méthodes standard prises en charge par les widgets à thème Tk et n'est pas censé être directement instancié.

Options standards

All the ttk Widgets accept the following options:

Option

Description

class

Spécifie la classe de fenêtre. La classe est utilisée lors de l'interrogation de la base de données d'options pour les autres options de la fenêtre, pour déterminer les balises de liaison par défaut pour la fenêtre et pour sélectionner la disposition et le style par défaut du widget. Cette option est en lecture seule et ne peut être spécifiée qu'à la création de la fenêtre.

cursor

Spécifie le curseur de la souris à utiliser pour le widget. S'il est défini sur la chaîne vide (valeur par défaut), le curseur est hérité du widget parent.

takefocus

Détermine si la fenêtre accepte le focus pendant le parcours du clavier. 0, 1 ou une chaîne vide est renvoyée. Si 0 est renvoyé, cela signifie que la fenêtre doit être entièrement ignorée lors du parcours au clavier. Si 1, cela signifie que la fenêtre doit recevoir le focus d'entrée tant qu'elle est visible. Et une chaîne vide signifie que les scripts de parcours prennent la décision de donner ou non le focus à la fenêtre.

style

Peut être utilisé pour spécifier un style de widget personnalisé.

Options de widget avec barre de défilement

Les options suivantes sont prises en charge par les widgets contrôlés par une barre de défilement.

Option

Description

xscrollcommand

Utilisé pour communiquer avec les barres de défilement horizontal.

Lorsque la vue dans la fenêtre du widget change, le widget génère une commande Tcl basée sur scrollcommand.

Habituellement, cette option consiste en la méthode Scrollbar.set() d'une barre de défilement. Cela entraîne la mise à jour de la barre de défilement chaque fois que la vue dans la fenêtre change.

yscrollcommand

Utilisé pour communiquer avec les barres de défilement vertical. Pour plus d'informations, voir ci-dessus.

Options d'étiquette (label)

Les options suivantes sont prises en charge par les étiquettes (labels), les boutons et autres widgets de type bouton.

Option

Description

text

Spécifie une chaîne de texte à afficher dans le widget.

textvariable

Spécifie un nom dont la valeur est utilisée à la place de la ressource d'option de texte.

underline

S'il est défini, spécifie l'indice (commençant à 0) d'un caractère à souligner dans la chaîne de texte. Le caractère de soulignement est utilisé pour l'activation mnémonique.

image

Spécifie une image à afficher. C'est une liste de un ou plusieurs éléments. Le premier élément est le nom de l'image par défaut. Le reste de la liste est une séquence de paires statespec-valeur telles que définies par Style.map(), spécifiant différentes images à utiliser lorsque le widget est dans un état particulier ou une combinaison d'états. Toutes les images de la liste doivent avoir la même taille.

compound

Spécifie comment afficher l'image par rapport au texte, dans le cas où les options de texte et d'images sont présentes. Les valeurs valides sont :

  • text : afficher uniquement le texte

  • image : afficher uniquement l'image

  • top, bottom, left, right : afficher l'image au-dessus, en dessous, à gauche ou à droite du texte, respectivement.

  • none : la valeur par défaut. Afficher l'image si présente, sinon le texte.

width

Si supérieur à zéro, spécifie la quantité d'espace, en largeurs de caractères, à allouer à l'étiquette de texte, si inférieur à zéro, spécifie une largeur minimale. Si zéro ou non spécifié, la largeur naturelle de l'étiquette de texte est utilisée.

Options de compatibilité

Option

Description

state

Peut être défini sur "normal" ou "disabled" pour contrôler le bit d'état d'activation. Il s'agit d'une option en écriture seule : sa définition modifie l'état du widget, mais la méthode Widget.state() n'affecte pas cette option.

États des widgets

L'état du widget est une combinaison d'indicateurs d'état indépendants.

Option

Description

active

Le curseur de la souris est sur le widget et appuyer sur un bouton de la souris provoquera une action

disabled

Le widget est désactivé sous le contrôle du programme

focus

Le widget a le focus du clavier

pressed

Le widget est en train d'être pressé

selected

"On", "true" ou "current" pour des choses comme les boutons de contrôle et les boutons radio

background

Windows et Mac ont une notion de fenêtre « active » ou de premier plan. L'état background est défini pour les widgets dans une fenêtre en arrière-plan et effacé pour ceux de la fenêtre au premier plan

readonly

Le widget ne doit pas permettre la modification par l'utilisateur

alternate

Un format d'affichage alternatif spécifique au widget

invalid

La valeur du widget est invalide

Une spécification d'état est une séquence de noms d'état, éventuellement précédée d'un point d'exclamation indiquant que le bit est désactivé.

ttk.Widget

Outre les méthodes décrites ci-dessous, la ttk.Widget prend en charge les méthodes tkinter.Widget.cget() et tkinter.Widget.configure().

class tkinter.ttk.Widget
identify(x, y)

Renvoie le nom de l'élément à la position x y, ou la chaîne vide si le point ne se trouve dans aucun élément.

x et y sont des coordonnées en pixels relatives au widget.

instate(statespec, callback=None, *args, **kw)

Teste l'état du widget. Si un rappel n'est pas spécifié, renvoie True si l'état du widget correspond à statespec et False sinon. Si le rappel est spécifié, il est appelé avec des arguments si l'état du widget correspond à statespec.

state(statespec=None)

Modifie ou demande l'état du widget. Si statespec est spécifié, définit l'état du widget en fonction de celui-ci et renvoie un nouveau statespec indiquant quels drapeaux ont été modifiés. Si statespec n'est pas spécifié, renvoie les indicateurs d'état actuellement activés.

statespec est généralement une liste ou un n-uplet.

Combobox

Le widget ttk.Combobox combine un champ de texte avec une liste déroulante de valeurs. Ce widget est une sous-classe de Entry.

En plus des méthodes héritées de Widget : Widget.cget(), Widget.configure(), Widget.identify(), Widget.instate() et Widget.state(), et les suivants hérités de Entry : Entry.bbox(), Entry.delete(), Entry.icursor(), Entry.index(), Entry.insert(), Entry.selection(), Entry.xview(), il a quelques autres méthodes, décrites dans ttk.Combobox.

Options

Ce widget accepte les options spécifiques suivantes :

Option

Description

exportationsselection

Valeur booléenne. Si elle est définie, la sélection du widget est liée à la sélection du gestionnaire de fenêtres (qui peut être renvoyée en appelant Misc.selection_get, par exemple).

justify

Spécifie comment le texte est aligné dans le widget. Les valeurs possibles sont "left", "center" ou "right".

height

Spécifie la hauteur de la liste déroulante, en lignes.

postcommand

Script (éventuellement enregistré avec Misc.register) qui est appelé immédiatement avant d'afficher les valeurs. Il peut spécifier les valeurs à afficher.

state

Les valeurs sont "normal", "readonly" ou "disabled". Dans l'état readonly, la valeur ne peut pas être modifiée directement et l'utilisateur ne peut que sélectionner les valeurs dans la liste déroulante. Dans l'état normal, le champ texte est directement éditable. Dans l'état disabled, aucune interaction n'est possible.

textvariable

Spécifie un nom dont la valeur est liée à la valeur du widget. Chaque fois que la valeur associée à ce nom change, la valeur du widget est mise à jour, et vice versa. Voir tkinter.StringVar.

values

Spécifie la liste de valeurs à afficher dans la liste déroulante.

width

Spécifie une valeur entière indiquant la largeur souhaitée de la fenêtre d'entrée, en caractères de taille moyenne de la police du widget.

Événements virtuels

Les widgets combobox génèrent un événement virtuel <<ComboboxSelected>> lorsque l'utilisateur sélectionne un élément dans la liste de valeurs.

ttk.Combobox

class tkinter.ttk.Combobox
current(newindex=None)

Si newindex est spécifié, définit la valeur de la combobox à la position de l'élément newindex. Sinon, renvoie l'indice de la valeur courante ou −1 si la valeur courante n'est pas dans la liste des valeurs.

get()

Renvoie la valeur actuelle de la combobox.

set(value)

Définit la valeur de la combobox sur value.

Spinbox

Le widget ttk.Spinbox est un ttk.Entry amélioré avec des flèches d'incrémentation et de décrémentation. Il peut être utilisé pour des nombres ou des listes de valeurs de chaîne. Ce widget est une sous-classe de Entry.

En plus des méthodes héritées de Widget : Widget.cget(), Widget.configure(), Widget.identify(), Widget.instate() et Widget.state(), et les suivantes héritées de Entry : Entry.bbox(), Entry.delete(), Entry.icursor(), Entry.index(), Entry.insert(), Entry.xview(), il a quelques autres méthodes, décrites dans ttk.Spinbox.

Options

Ce widget accepte les options spécifiques suivantes :

Option

Description

from

Valeur flottante. Si elle est définie, il s'agit de la valeur minimale à laquelle le bouton de décrémentation décrémentera. Doit être orthographié comme from_ lorsqu'il est utilisé comme argument, car from est un mot-clé Python.

to

Valeur flottante. Si elle est définie, il s'agit de la valeur maximale du bouton d'incrémentation.

increment

Valeur flottante. Spécifie la quantité dont les boutons d'incrémentation/décrémentation modifient la valeur. La valeur par défaut est 1.0.

values

Séquence de valeurs de chaîne ou flottantes. S'ils sont spécifiés, les boutons d'incrémentation/décrémentation font défiler les éléments dans cette séquence plutôt que d'incrémenter ou de décrémenter les nombres.

wrap

Valeur booléenne. Si True, les boutons d'incrémentation et de décrémentation passent de la valeur to à la valeur from ou de la valeur from à la valeur to, respectivement.

format

Valeur sous forme de chaîne. Cela spécifie le format des nombres définis par les boutons d'incrémentation/décrémentation. Il doit être sous la forme "%W.Pf", où W est la largeur de la valeur, P est la précision et '%' et 'f' sont littéraux.

command

appelable Python. Est appelé sans argument chaque fois que l'un des boutons d'incrémentation ou de décrémentation est enfoncé.

Événements virtuels

Le widget spinbox génère un événement virtuel <<Increment>> lorsque l'utilisateur appuie sur <Up>, et un événement virtuel <<Decrement>> lorsque l'utilisateur appuie sur <Down>.

ttk.Spinbox

class tkinter.ttk.Spinbox
get()

Renvoie la valeur actuelle du spinbox.

set(value)

Définit la valeur du spinbox sur value.

Carnet de notes (notebook)

Le widget Ttk Notebook gère une collection de fenêtres et n'en affiche qu'une seule à la fois. Chaque fenêtre enfant est associée à un onglet, que l'utilisateur peut sélectionner pour changer la fenêtre actuellement affichée.

Options

Ce widget accepte les options spécifiques suivantes :

Option

Description

height

S'il est présent et supérieur à zéro, spécifie la hauteur souhaitée de la zone du volet (sans compter l'ajustement interne ni les onglets). Sinon, la hauteur maximale de tous les volets est utilisée.

padding

Spécifie la quantité d'espace supplémentaire à ajouter autour de l'extérieur du bloc-notes. L'ajustement est défini par une liste jusqu'à quatre spécifications de longueur à gauche en haut à droite en bas. Si moins de quatre éléments sont spécifiés, bottom vaut par défaut top, right vaut par défaut left et top vaut par défaut left.

width

S'il est présent et supérieur à zéro, spécifiez la largeur souhaitée de la zone du volet (hors ajustement interne). Sinon, la largeur maximale de tous les volets est utilisée.

Options d'onglet

Il existe également des options spécifiques pour les onglets :

Option

Description

state

Soit "normal", "disabled" ou "hidden". Si disabled, l'onglet n'est pas sélectionnable. S'il est hidden, l'onglet n'est pas affiché.

sticky

Spécifie comment la fenêtre enfant est positionnée dans la zone du volet. La valeur est une chaîne contenant zéro ou plusieurs des caractères "n", "s", "e" ou "w". Chaque lettre fait référence à un côté (nord, sud, est ou ouest) auquel la fenêtre enfant colle, selon le gestionnaire de géométrie grid().

padding

Spécifie la quantité d'espace supplémentaire à ajouter entre le bloc-notes et ce volet. La syntaxe est la même que pour l'option d'ajustement utilisée par ce widget.

text

Spécifie un texte à afficher dans l'onglet.

image

Spécifie une image à afficher dans l'onglet. Voir l'option image décrite dans Widget.

compound

Spécifie comment afficher l'image par rapport au texte, dans le cas où les deux options texte et image sont présentes. Voir Label Options pour les valeurs autorisées.

underline

Spécifie l'indice (en commençant à 0) d'un caractère à souligner dans la chaîne de texte. Le caractère souligné est utilisé pour l'activation mnémonique si Notebook.enable_traversal() est appelé.

Identifiants d'onglet

Le tab_id présent dans plusieurs méthodes de ttk.Notebook peut prendre l'une des formes suivantes :

  • Un entier compris entre zéro et le nombre d'onglets

  • Le nom d'une fenêtre fille

  • Une spécification de position de la forme "@x,y", qui identifie l'onglet

  • La chaîne littérale "current", qui identifie l'onglet actuellement sélectionné

  • La chaîne littérale "end", qui renvoie le nombre d'onglets (valable uniquement pour Notebook.index())

Événements virtuels

Ce widget génère un événement virtuel <<NotebookTabChanged>> après la sélection d'un nouvel onglet.

ttk.Notebook

class tkinter.ttk.Notebook
add(child, **kw)

Ajoute un nouvel onglet au bloc-notes.

Si la fenêtre est actuellement gérée par le notebook mais masquée, elle est restaurée à sa position précédente.

Voir Options d'onglet pour la liste des options disponibles.

forget(tab_id)

Supprime l'onglet spécifié par tab_id, et ne gère plus la fenêtre associée.

hide(tab_id)

Masque l'onglet spécifié par tab_id.

L'onglet ne s'affiche pas, mais la fenêtre associée reste gérée par le notebook et sa configuration mémorisée. Les onglets cachés peuvent être restaurés avec la commande add().

identify(x, y)

Renvoie le nom de l'élément tab à la position x, y, ou la chaîne vide s'il n'y en a pas.

index(tab_id)

Renvoie l'indice de l'onglet spécifié par tab_id, ou le nombre total d'onglets si tab_id est la chaîne "end".

insert(pos, child, **kw)

Insère un volet à la position spécifiée.

pos est soit la chaîne "end", un indice entier ou le nom d'un enfant géré. Si child est déjà géré par le notebook, le déplace vers la position spécifiée.

Voir Options d'onglet pour la liste des options disponibles.

select(tab_id=None)

Sélectionne le tab_id spécifié.

La fenêtre enfant associée est affichée, et la fenêtre précédemment sélectionnée (si différente) est masquée. Si tab_id est omis, renvoie le nom du widget du volet actuellement sélectionné.

tab(tab_id, option=None, **kw)

Interroge ou modifie les options du tab_id spécifique.

Si kw n'est pas donné, renvoie un dictionnaire des valeurs des options de l'onglet. Si option est spécifié, renvoie la valeur de cette option. Sinon, définit les options sur les valeurs correspondantes.

tabs()

Renvoie une liste des fenêtres gérées par le notebook.

enable_traversal()

Active la traversée du clavier pour une fenêtre de niveau supérieur contenant ce bloc-notes.

Cela étend les liaisons pour la fenêtre de niveau supérieur contenant le bloc-notes comme suit :

  • Control-Tab : sélectionne l'onglet suivant celui actuellement sélectionné.

  • Shift-Control-Tab : sélectionne l'onglet précédant celui actuellement sélectionné.

  • Alt-K : où K est le caractère mnémonique (souligné) de n'importe quel onglet, sélectionne cet onglet.

Plusieurs blocs-notes dans un seul niveau supérieur peuvent être activés pour la traversée, y compris les blocs-notes imbriqués. Cependant, la traversée du bloc-notes ne fonctionne correctement que si tous les volets ont le bloc-notes dans lequel ils se trouvent en tant que maître.

Barre de progression

Le widget ttk.Progressbar affiche l'état d'une opération de longue durée. Il peut fonctionner en deux modes : 1) le mode déterminé qui indique la quantité achevée par rapport à la quantité totale de travail à effectuer et 2) le mode indéterminé qui fournit un affichage animé pour informer l'utilisateur que le travail progresse.

Options

Ce widget accepte les options spécifiques suivantes :

Option

Description

orient

"horizontal" ou "vertical". Spécifie l'orientation de la barre de progression.

length

Spécifie la longueur de l'axe long de la barre de progression (largeur si horizontale, hauteur si verticale).

mode

"determinate" ou "indeterminate".

maximum

Nombre spécifiant la valeur maximale. La valeur par défaut est 100.

value

La valeur actuelle de la barre de progression. En mode determinate, cela représente la quantité de travail accompli. En mode indeterminate, il est interprété comme modulo maximum ; c'est-à-dire que la barre de progression effectue un « cycle » lorsque sa valeur augmente de maximum.

variable

Nom lié à la valeur de l'option. Si spécifié, la valeur de la barre de progression est automatiquement fixée à la valeur de ce nom à chaque modification de ce dernier.

phase

Option en lecture seule. Le widget incrémente périodiquement la valeur de cette option chaque fois que sa valeur est supérieure à 0 et, en mode déterminate, inférieure au maximum. Cette option peut être utilisée par le thème actuel pour fournir des effets d'animation supplémentaires.

ttk.Progressbar

class tkinter.ttk.Progressbar
start(interval=None)

Commence le mode d'auto-incrémentation : planifie un événement de minuterie récurrent qui appelle Progressbar.step() toutes les interval millisecondes. S'il est omis, interval est par défaut de 50 millisecondes.

step(amount=None)

Incrémente la valeur de la barre de progression de amount.

amount est par défaut égal à 1.0 s'il est omis.

stop()

Arrête le mode d'auto-incrémentation : annule tout événement de minuterie récurrent initié par Progressbar.start() pour cette barre de progression.

Séparateur

Le widget ttk.Separator affiche une barre de séparation horizontale ou verticale.

Il n'a pas d'autres méthodes que celles héritées de ttk.Widget.

Options

Ce widget accepte l'option spécifique suivante :

Option

Description

orient

"horizontal" ou "vertical". Spécifie l'orientation du séparateur.

Poignée de redimensionnement

Le widget ttk.Sizegrip (également connu sous le nom de grow box) permet à l'utilisateur de redimensionner la fenêtre de niveau supérieur en appuyant et en faisant glisser la poignée.

Ce widget n'a ni options spécifiques ni méthodes spécifiques, à part celles héritées de ttk.Widget.

Notes spécifiques à une plateforme

  • Sur macOS, les fenêtres de niveau supérieur incluent automatiquement une poignée de redimensionnement intégrée par défaut. L'ajout d'un Sizegrip est sans danger, car la poignée intégrée masquera simplement le widget.

Bogues

  • Si la position du contenant de niveau supérieur a été spécifiée par rapport à la droite ou au bas de l'écran (par exemple…), le widget Sizegrip ne redimensionne pas la fenêtre.

  • Ce widget ne prend en charge que le redimensionnement "southeast".

Arborescence

Le widget ttk.Treeview affiche une collection hiérarchique d'éléments. Chaque élément possède une étiquette textuelle, une image facultative et une liste facultative de valeurs de données. Les valeurs des données sont affichées dans des colonnes successives après l'étiquette de l'arbre.

L'ordre dans lequel les valeurs de données sont affichées peut être contrôlé en définissant l'option de widget displaycolumns. Le widget d'arborescence peut également afficher les en-têtes de colonne. Les colonnes sont accessibles par des numéros ou des noms symboliques indiqués dans l'option columns du widget. Voir Identifiants de colonnes.

Chaque élément est identifié par un nom unique. Le widget génère des identifiants d'éléments s'ils ne sont pas fournis par l'appelant. Il existe un élément racine distinct, nommé {}. L'élément racine lui-même n'est pas affiché ; ses enfants apparaissent au niveau supérieur de la hiérarchie.

Chaque élément possède également une liste de balises, qui peuvent être utilisées pour associer des liaisons d'événements à des éléments individuels et contrôler l'apparence de l'élément.

Le widget Treeview prend en charge le défilement horizontal et vertical, selon les options décrites dans Scrollable Widget Options et les méthodes Treeview.xview() et Treeview.yview().

Options

Ce widget accepte les options spécifiques suivantes :

Option

Description

columns

Une liste d'identificateurs de colonne, spécifiant le nombre de colonnes et leurs noms.

displaycolumns

Une liste d'identificateurs de colonne (indices symboliques ou entiers) spécifiant quelles colonnes de données sont affichées et l'ordre dans lequel elles apparaissent, ou la chaîne "#all".

height

Spécifie le nombre de lignes qui doivent être visibles. Remarque : la largeur demandée est déterminée à partir de la somme des largeurs de colonne.

padding

Spécifie le remplissage interne du widget. L'ajustement est décrit par une liste jusqu'à quatre spécifications de longueur.

selectmode

Contrôle la façon dont les liaisons de classe intégrées gèrent la sélection. Les valeurs possibles sont "extended", "browse" ou "none". S'il est défini sur extended (valeur par défaut), plusieurs éléments peuvent être sélectionnés. Si c'est browse un seul élément ne peut être sélectionné à la fois. Si c'est none, la sélection ne peut pas être modifiée.

Notez que le code d'application et les liaisons de balises peuvent définir la sélection comme ils le souhaitent, quelle que soit la valeur de cette option.

show

Une liste contenant zéro ou plusieurs des valeurs suivantes, spécifiant les éléments de l'arborescence à afficher.

  • tree : affiche les étiquettes de l'arbre dans la colonne 0.

  • headings : affiche la ligne d'en-tête.

La valeur par défaut est "tree headings", c'est-à-dire afficher tous les éléments.

Remarque : la colonne 0 fait toujours référence à la colonne de l'arborescence, même si show="tree" n'est pas spécifié.

Options d'éléments

Les options d'éléments suivantes peuvent être spécifiées pour les éléments dans les commandes insert et les widgets de type élément.

Option

Description

text

Libellé textuel à afficher pour l'élément.

image

Image Tk, affichée à gauche de l'étiquette.

values

Liste des valeurs associées à l'élément.

Chaque élément doit avoir le même nombre de valeurs que les colonnes d'options du widget. S'il y a moins de valeurs que de colonnes, les valeurs restantes sont supposées vides. S'il y a plus de valeurs que de colonnes, les valeurs supplémentaires sont ignorées.

open

Valeur True ou False indiquant si les enfants de l'élément doivent être affichés ou masqués.

tags

Liste de balises associées à cet élément.

Options de balise

Les options suivantes peuvent être spécifiées sur les balises :

Option

Description

foreground

Spécifie la couleur de premier plan du texte.

background

Spécifie la couleur d'arrière-plan de la cellule ou de l'élément.

font

Spécifie la police à utiliser lors du dessin du texte.

image

Spécifie l'image de l'élément, au cas où l'option d'image de l'élément est vide.

Identifiants de colonnes

Les identifiants de colonnes prennent l'une des formes suivantes :

  • Un nom symbolique de l'option de liste de colonnes.

  • Un entier n, spécifiant la nième colonne de données.

  • Une chaîne de la forme #n, où n est un entier, spécifiant la nième colonne d'affichage.

Notes :

  • Les valeurs d'option de l'élément peuvent être affichées dans un ordre différent de celui dans lequel elles sont stockées.

  • La colonne #0 fait toujours référence à la colonne de l'arborescence, même si show="tree" n'est pas spécifié.

Un numéro de colonne de données est un indice dans la liste des valeurs d'option d'un élément ; un numéro de colonne d'affichage est le numéro de colonne dans l'arborescence où les valeurs sont affichées. Les étiquettes d'arbre sont affichées dans la colonne #0. Si l'option displaycolumns n'est pas définie, la colonne de données n s'affiche dans la colonne #n+1. Encore une fois, la colonne #0 fait toujours référence à la colonne de l'arborescence.

Événements virtuels

Le widget Treeview génère les événements virtuels suivants.

Événement

Description

<<TreeviewSelect>>

Généré chaque fois que la sélection change.

<<TreeviewOpen>>

Généré juste avant de définir l'élément de focus sur open=True.

<<TreeviewClose>>

Généré juste après avoir défini l'élément de focus sur open=False.

Les méthodes Treeview.focus() et Treeview.selection() peuvent être utilisées pour déterminer le ou les éléments concernés.

ttk.Treeview

class tkinter.ttk.Treeview
bbox(item, column=None)

Renvoie la boîte englobante (relative à la fenêtre du widget treeview) de l'item spécifié sous la forme (x, y, largeur, hauteur).

Si column est spécifié, renvoie la boîte englobante de cette cellule. Si item n'est pas visible (c'est-à-dire s'il est un descendant d'un élément fermé ou se trouve hors écran en raison du défilement), renvoie une chaîne vide.

get_children(item=None)

Renvoie la liste des enfants appartenant à item.

Si item n'est pas spécifié, renvoie les enfants racine.

set_children(item, *newchildren)

Remplace l'enfant de item par newchildren.

Les enfants présents dans item qui ne sont pas présents dans newchildren sont détachés de l'arbre. Aucun élément de newchildren ne peut être un ancêtre de item. Notez que ne pas spécifier newchildren entraîne le détachement des enfants de item.

column(column, option=None, **kw)

Interroge ou modifie les options pour la column spécifiée.

Si kw n'est pas donné, renvoie un dictionnaire des valeurs d'option de colonne. Si option est spécifié, la valeur de cette option est renvoyée. Sinon, définit les options sur les valeurs correspondantes.

Les options/valeurs valides sont :

id

Renvoie le nom de la colonne. Il s'agit d'une option en lecture seule.

anchor: One of the standard Tk anchor values.

Spécifie comment le texte de cette colonne doit être aligné par rapport à la cellule.

minwidth: width

La largeur minimale de la colonne en pixels. Le widget Treeview ne rend pas la colonne plus petite que celle spécifiée par cette option lorsque le widget est redimensionné ou que l'utilisateur fait glisser une colonne.

stretch: True/False

Spécifie si la largeur de la colonne doit être ajustée lorsque le widget est redimensionné.

width: width

La largeur de la colonne en pixels.

Pour configurer la colonne d'arborescence, appelez-la avec column = "#0"

delete(*items)

Supprime tous les items spécifiés et tous leurs descendants.

L'élément racine ne peut pas être supprimé.

detach(*items)

Dissocie tous les items spécifiés de l'arborescence.

Les éléments et tous leurs descendants sont toujours présents et peuvent être réinsérés à un autre point de l'arborescence, mais ne seront pas affichés.

L'élément racine ne peut pas être détaché.

exists(item)

Renvoie True si l'item spécifié est présent dans l'arborescence.

focus(item=None)

Si item est spécifié, définit l'élément de focus sur item. Sinon, renvoie l'élément de focus actuel, ou '' s'il n'y en a pas.

heading(column, option=None, **kw)

Interroge ou modifie les options d'en-tête pour la column spécifiée.

Si kw n'est pas donné, renvoie un dictionnaire des valeurs d'option d'en-tête. Si option est spécifié, la valeur de cette option est renvoyée. Sinon, définit les options sur les valeurs correspondantes.

Les options/valeurs valides sont :

text: text

Texte à afficher dans l'en-tête de colonne.

image: imageName

Spécifie une image à afficher à droite de l'en-tête de colonne.

anchor: anchor

Spécifie comment le texte du titre doit être aligné. Une des valeurs d'ancrage Tk standard.

command: callback

Un rappel à invoquer lorsque l'étiquette d'en-tête est pressée.

Pour configurer l'en-tête de colonne de l'arborescence, appelez-la avec column = "#0".

identify(component, x, y)

Renvoie une description du component spécifié sous le point donné par x et y, ou la chaîne vide si aucun component de ce type n'est présent à cette position.

identify_row(y)

Renvoie l'ID d'élément de l'élément à la position y.

identify_column(x)

Renvoie l'identificateur de colonne de données de la cellule à la position x.

La colonne arborescence possède l'ID #0.

identify_region(x, y)

Renvoie l'un des éléments suivants :

region

signification

heading

Zone d'en-tête de l'arbre.

separator

Espace entre deux en-têtes de colonnes.

tree (arbre)

Une zone de l'arbre.

cell

Une cellule de données.

Disponibilité : Tk 8.6.

identify_element(x, y)

Renvoie l'élément à la position x, y.

Disponibilité : Tk 8.6.

index(item)

Renvoie l'indice (entier) de item dans la liste des enfants de son parent.

insert(parent, index, iid=None, **kw)

Crée un nouvel élément et renvoie l'identifiant de l'élément nouvellement créé.

parent est l'ID d'élément de l'élément parent ou la chaîne vide pour créer un nouvel élément de niveau supérieur. index est un entier, ou la valeur "end", spécifiant où dans la liste des enfants du parent insérer le nouvel élément. Si index est inférieur ou égal à zéro, le nouveau nœud est inséré au début ; si index est supérieur ou égal au nombre actuel d'enfants, il est inséré à la fin. Si iid est spécifié, il est utilisé comme identifiant d'élément ; iid ne doit pas déjà exister dans l'arborescence. Sinon, un nouvel identifiant unique est généré.

See Item Options for the list of available options.

item(item, option=None, **kw)

Interroge ou modifie les options pour l'item spécifié.

Si aucune option n'est donnée, un dictionnaire avec des options/valeurs pour l'élément est renvoyé. Si option est spécifié, la valeur de cette option est renvoyée. Sinon, définit les options sur les valeurs correspondantes données par kw.

move(item, parent, index)

Déplace item vers la position index dans la liste des enfants de parent.

Il est interdit de déplacer un élément sous l'un de ses descendants. Si index est inférieur ou égal à zéro, item est déplacé au début ; s'il est supérieur ou égal au nombre d'enfants, il est déplacé à la fin. Si item a été détaché, il est rattaché.

next(item)

Renvoie l'identifiant du frère suivant de item, ou '' si item est le dernier enfant de son parent.

parent(item)

Renvoie l'identifiant du parent de item, ou '' si item est au niveau supérieur de la hiérarchie.

prev(item)

Renvoie l'identifiant du frère précédent de item, ou '' si item est le premier enfant de son parent.

reattach(item, parent, index)

Alias pour Treeview.move().

see(item)

Fait en sorte que item soit visible.

Définit l'option d'ouverture de tous les ancêtres de item sur True, et fait défiler le widget si nécessaire afin que item soit dans la partie visible de l'arborescence.

selection()

Renvoie un n-uplet d'éléments sélectionnés.

Modifié dans la version 3.8: selection() ne prend plus d'arguments. Pour modifier l'état de sélection, utilisez les méthodes de sélection suivantes.

selection_set(*items)

items devient la nouvelle sélection.

Modifié dans la version 3.6: items peut être passé en tant qu'arguments séparés, pas seulement en tant que n-uplet.

selection_add(*items)

Ajoute des items à la sélection.

Modifié dans la version 3.6: items peut être passé en tant qu'arguments séparés, pas seulement en tant que n-uplet.

selection_remove(*items)

Supprime les items de la sélection.

Modifié dans la version 3.6: items peut être passé en tant qu'arguments séparés, pas seulement en tant que n-uplet.

selection_toggle(*items)

Bascule l'état de sélection de chaque élément de items.

Modifié dans la version 3.6: items peut être passé en tant qu'arguments séparés, pas seulement en tant que n-uplet.

set(item, column=None, value=None)

Avec un argument, renvoie un dictionnaire de paires colonne/valeur pour l'item spécifié. Avec deux arguments, renvoie la valeur actuelle de la column spécifiée. Avec trois arguments, définit la valeur de la column donnée dans l'item donné à la value spécifiée.

tag_bind(tagname, sequence=None, callback=None)

Lie le rappel callback à l'événement donné sequence pour la balise tagname. Lorsqu'un événement est envoyé à un élément, les rappels pour chacune des options de balises de l'élément sont appelés.

tag_configure(tagname, option=None, **kw)

Interroge ou modifie les options pour le tagname spécifié.

Si kw n'est pas donné, renvoie un dictionnaire des paramètres d'option pour tagname. Si option est spécifié, renvoie la valeur de cette option pour le tagname spécifié. Sinon, définit les options sur les valeurs correspondantes pour le tagname donné.

tag_has(tagname, item=None)

Si item est spécifié, renvoie 1 ou 0 selon que item spécifié a le tagname donné. Sinon, renvoie une liste de tous les éléments qui ont la balise spécifiée.

Disponibilité : Tk 8.6

xview(*args)

Interroge ou modifie la position horizontale de l'arborescence.

yview(*args)

Interroge ou modifie la position verticale de l'arborescence.

Style Ttk

Chaque widget dans ttk se voit attribuer un style, qui spécifie l'ensemble d'éléments composant le widget et la façon dont ils sont disposés, ainsi que les paramètres dynamiques et par défaut pour les options d'élément. Par défaut, le nom du style est le même que le nom de la classe du widget, mais il peut être remplacé par l'option de style du widget. Si vous ne connaissez pas le nom de classe d'un widget, utilisez la méthode Misc.winfo_class() (somewidget.winfo_class()).

Voir aussi

Tcl'2004 conference presentation

Ce document explique le fonctionnement du moteur de thème

class tkinter.ttk.Style

Cette classe est utilisée pour manipuler la base de données de style.

configure(style, query_opt=None, **kw)

Interroge ou définit la valeur par défaut des options spécifiées dans style.

Chaque clé dans kw est une option et chaque valeur est une chaîne identifiant la valeur de cette option.

Par exemple, pour changer chaque bouton par défaut en un bouton plat avec un ajustement et une couleur d'arrière-plan différente :

from tkinter import ttk
import tkinter

root = tkinter.Tk()

ttk.Style().configure("TButton", padding=6, relief="flat",
   background="#ccc")

btn = ttk.Button(text="Sample")
btn.pack()

root.mainloop()
map(style, query_opt=None, **kw)

Interroge ou définit les valeurs dynamiques des options spécifiées dans style.

Chaque clé dans kw est une option et chaque valeur doit être une liste ou un n-uplet (généralement) contenant des spécifications d'état regroupées dans des n-uplets, des listes ou une autre préférence. Un statespec est un composé d'un ou plusieurs états, puis d'une valeur.

Un exemple peut le rendre plus compréhensible :

import tkinter
from tkinter import ttk

root = tkinter.Tk()

style = ttk.Style()
style.map("C.TButton",
    foreground=[('pressed', 'red'), ('active', 'blue')],
    background=[('pressed', '!disabled', 'black'), ('active', 'white')]
    )

colored_btn = ttk.Button(text="Test", style="C.TButton").pack()

root.mainloop()

Notez que l'ordre des séquences (états, valeur) pour une option est important, si l'ordre est changé en [('active', 'blue'), ('pressed', 'red')] dans l'option de premier plan, par exemple, le résultat est un premier plan bleu lorsque le widget est dans les états actif ou pressé.

lookup(style, option, state=None, default=None)

Renvoie la valeur spécifiée pour option dans style.

Si state est spécifié, on s'attend à ce qu'il s'agisse d'une séquence d'un ou plusieurs états. Si l'argument default est défini, il est utilisé comme valeur de secours au cas où aucune spécification d'option n'est trouvée.

Pour vérifier quelle police un bouton utilise par défaut :

from tkinter import ttk

print(ttk.Style().lookup("TButton", "font"))
layout(style, layoutspec=None)

Définit la disposition du widget pour un style donné. Si layoutspec est omis, renvoie la spécification de mise en page pour le style donné.

layoutspec, si spécifié, doit être une liste ou un autre type de séquence (à l'exception des chaînes), où chaque élément doit être un n-uplet et le premier élément est le nom de la mise en page et le deuxième élément doit avoir le format décrit dans Layouts.

Pour comprendre le format, consultez l'exemple suivant (il n'est pas destiné à faire quoi que ce soit d'utile) :

from tkinter import ttk
import tkinter

root = tkinter.Tk()

style = ttk.Style()
style.layout("TMenubutton", [
   ("Menubutton.background", None),
   ("Menubutton.button", {"children":
       [("Menubutton.focus", {"children":
           [("Menubutton.padding", {"children":
               [("Menubutton.label", {"side": "left", "expand": 1})]
           })]
       })]
   }),
])

mbtn = ttk.Menubutton(text='Text')
mbtn.pack()
root.mainloop()
element_create(elementname, etype, *args, **kw)

Create a new element in the current theme, of the given etype which is expected to be either "image", "from" or "vsapi". The latter is only available in Tk 8.6 on Windows.

Si image est utilisé, args doit contenir le nom de l'image par défaut suivi de paires statespec / value (il s'agit de l'imagespec), et kw peut avoir les options suivantes :

border=remplissage

padding est une liste de quatre entiers maximum, spécifiant respectivement les bordures gauche, supérieure, droite et inférieure.

height=hauteur

Spécifie une hauteur minimale pour l'élément. Si elle est inférieure à zéro, la hauteur de l'image de base est utilisée par défaut.

padding= ajustement

Spécifie l'ajustement intérieur de l'élément. La valeur par défaut est la valeur de border si elle n'est pas spécifiée.

sticky= spec

Spécifie comment l'image est placée dans la partie de l'espace attribué finale. spec contient zéro ou plusieurs caractères "n", "s", "w" ou "e".

width=largeur

Spécifie une largeur minimale pour l'élément. Si inférieur à zéro, la largeur de l'image de base est utilisée par défaut.

Example:

img1 = tkinter.PhotoImage(master=root, file='button.png')
img1 = tkinter.PhotoImage(master=root, file='button-pressed.png')
img1 = tkinter.PhotoImage(master=root, file='button-active.png')
style = ttk.Style(root)
style.element_create('Button.button', 'image',
                     img1, ('pressed', img2), ('active', img3),
                     border=(2, 4), sticky='we')

Si from est utilisé comme valeur de etype, element_create() clone un élément existant. args doit contenir un nom de thème, à partir duquel l'élément est cloné, et éventuellement un élément à cloner. Si cet élément qu'il faut cloner n'est pas spécifié, un élément vide est utilisé. kw est ignoré.

Example:

style = ttk.Style(root)
style.element_create('plain.background', 'from', 'default')

If "vsapi" is used as the value of etype, element_create() will create a new element in the current theme whose visual appearance is drawn using the Microsoft Visual Styles API which is responsible for the themed styles on Windows XP and Vista. args is expected to contain the Visual Styles class and part as given in the Microsoft documentation followed by an optional sequence of tuples of ttk states and the corresponding Visual Styles API state value. kw may have the following options:

padding= ajustement

Specify the element's interior padding. padding is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. If fewer than four elements are specified, bottom defaults to top, right defaults to left, and top defaults to left. In other words, a list of three numbers specify the left, vertical, and right padding; a list of two numbers specify the horizontal and the vertical padding; a single number specifies the same padding all the way around the widget. This option may not be mixed with any other options.

margins=padding

Specifies the elements exterior padding. padding is a list of up to four integers specifying the left, top, right and bottom padding quantities respectively. This option may not be mixed with any other options.

width=largeur

Specifies the width for the element. If this option is set then the Visual Styles API will not be queried for the recommended size or the part. If this option is set then height should also be set. The width and height options cannot be mixed with the padding or margins options.

height=hauteur

Specifies the height of the element. See the comments for width.

Example:

style = ttk.Style(root)
style.element_create('pin', 'vsapi', 'EXPLORERBAR', 3, [
                     ('pressed', '!selected', 3),
                     ('active', '!selected', 2),
                     ('pressed', 'selected', 6),
                     ('active', 'selected', 5),
                     ('selected', 4),
                     ('', 1)])
style.layout('Explorer.Pin',
             [('Explorer.Pin.pin', {'sticky': 'news'})])
pin = ttk.Checkbutton(style='Explorer.Pin')
pin.pack(expand=True, fill='both')

Modifié dans la version 3.13: Added support of the "vsapi" element factory.

element_names()

Renvoie la liste des éléments définis dans le thème courant.

element_options(elementname)

Renvoie la liste des options de elementname.

theme_create(themename, parent=None, settings=None)

Crée un nouveau thème.

C'est une erreur si themename existe déjà. Si parent est spécifié, le nouveau thème hérite des styles, des éléments et des mises en page du thème parent. Si settings est présent, il doit avoir la même syntaxe que celle utilisée pour theme_settings().

theme_settings(themename, settings)

Définit temporairement le thème actuel sur themename, applique les settings spécifiés, puis restaure le thème précédent.

Chaque clé dans settings est un style et chaque valeur peut contenir les clés 'configure', 'map', 'layout' et 'element create' et elles doivent avoir le même format que celui spécifié par les méthodes Style.configure(), Style.map(), Style.layout() et Style.element_create() respectivement.

À titre d'exemple, changeons un peu la Combobox pour le thème par défaut :

from tkinter import ttk
import tkinter

root = tkinter.Tk()

style = ttk.Style()
style.theme_settings("default", {
   "TCombobox": {
       "configure": {"padding": 5},
       "map": {
           "background": [("active", "green2"),
                          ("!disabled", "green4")],
           "fieldbackground": [("!disabled", "green3")],
           "foreground": [("focus", "OliveDrab1"),
                          ("!disabled", "OliveDrab2")]
       }
   }
})

combo = ttk.Combobox().pack()

root.mainloop()
theme_names()

Renvoie une liste de tous les thèmes connus.

theme_use(themename=None)

Si themename n'est pas donné, renvoie le thème utilisé. Sinon, définit le thème actuel sur themename, actualise tous les widgets et lève un événement <<ThemeChanged>>.

Dispositions de mise en page

A layout can be just None, if it takes no options, or a dict of options specifying how to arrange the element. The layout mechanism uses a simplified version of the pack geometry manager: given an initial cavity, each element is allocated a parcel.

Les options/valeurs valides sont :

side: whichside

Spécifie de quel côté de l'espace vide placer l'élément ; top (en haut), right (à droite), bottom (en bas) ou left (à gauche). S'il est omis, l'élément occupe toute l'espace.

sticky: nswe

Spécifie où l'élément est placé à l'intérieur de sa partie d'espace alloué.

unit: 0 or 1

Si défini sur 1, l'élément et tous ses descendants sont traités comme un seul élément aux fins de Widget.identify() et consœurs. Il est utilisé pour des choses comme la barre de défilement ou les agrandissements.

children: [sublayout... ]

Spécifie une liste d'éléments à placer à l'intérieur de l'élément. Chaque élément est un n-uplet (ou un autre type de séquence) où le premier élément est le nom de la mise en page et l'autre est un Layout.