tkinter — Interface Python para Tcl/Tk

Código-fonte: Lib/tkinter/__init__.py


The tkinter package (“Tk interface”) is the standard Python interface to the Tcl/Tk GUI toolkit. Both Tk and tkinter are available on most Unix platforms, including macOS, as well as on Windows systems.

Executar python -m tkinter na linha de comando deve abrir uma janela demonstrando uma interface Tk simples, informando que tkinter está apropriadamente instalado em seu sistema, e também mostrando qual versão do Tcl/Tk está instalado, para que você possa ler a documentação do Tcl/Tk específica para essa versão.

Tkinter tem suporte a uma gama de versões Tcl/Tk, compiladas com ou sem suporte a thread. O lançamento oficial do binário Python agrupa Tcl/Tk 8.6 em thread. Veja o código-fonte do módulo _tkinter para mais informações sobre as versões suportadas.

O Tkinter não é um invólucro fino, mas adiciona uma boa quantidade de sua própria lógica para tornar a experiência mais pythônica. Esta documentação se concentrará nessas adições e mudanças, e consulte a documentação oficial do Tcl/Tk para detalhes que não foram alterados.

Nota

Tcl/Tk 8.5 (2007) introduced a modern set of themed user interface components along with a new API to use them. Both old and new APIs are still available. Most documentation you will find online still uses the old API and can be woefully outdated.

Ver também

  • TkDocs

    Extensive tutorial on creating user interfaces with Tkinter. Explains key concepts, and illustrates recommended approaches using the modern API.

  • Referência do Tkinter 8.5: uma GUI para Python

    Reference documentation for Tkinter 8.5 detailing available classes, methods, and options.

Tcl/Tk Resources:

  • Comandos Tk

    Comprehensive reference to each of the underlying Tcl/Tk commands used by Tkinter.

  • Tcl/Tk Home Page

    Additional documentation, and links to Tcl/Tk core development.

Books:

Arquitetura

Tcl/Tk is not a single library but rather consists of a few distinct modules, each with separate functionality and its own official documentation. Python’s binary releases also ship an add-on module together with it.

Tcl

Tcl é uma linguagem de programação interpretada dinâmica, assim como Python. Embora possa ser usado sozinho como uma linguagem de programação de propósito geral, é mais comumente embutido em aplicativos C como um mecanismo de script ou uma interface para o kit de ferramentas Tk. A biblioteca Tcl tem uma interface C para criar e gerenciar uma ou mais instâncias de um interpretador Tcl, executar comandos e scripts Tcl nessas instâncias e adicionar comandos personalizados implementados em Tcl ou C. Cada interpretador tem uma fila de eventos, e há instalações para enviar eventos e processá-los. Ao contrário do Python, o modelo de execução do Tcl é projetado em torno da multitarefa cooperativa, e o Tkinter faz a ponte entre essa diferença (veja Modelo de threading para detalhes).

Tk

Tk é um pacote Tcl implementado em C que adiciona comandos personalizados para criar e manipular widgets GUI. Cada objeto Tk incorpora sua própria instância do interpretador Tcl com o Tk carregado nele. Os widgets do Tk são muito personalizáveis, embora ao custo de uma aparência desatualizada. Tk usa a fila de eventos do Tcl para gerar e processar eventos GUI.

Ttk

Themed Tk (Ttk) é uma família mais recente de widgets Tk que fornecem uma aparência muito melhor em diferentes plataformas do que muitos dos widgets Tk clássicos. O Ttk é distribuído como parte do Tk, começando com o Tk versão 8.5. As ligações Python são fornecidas em um módulo separado, tkinter.ttk.

Internally, Tk and Ttk use facilities of the underlying operating system, i.e., Xlib on Unix/X11, Cocoa on macOS, GDI on Windows.

When your Python application uses a class in Tkinter, e.g., to create a widget, the tkinter module first assembles a Tcl/Tk command string. It passes that Tcl command string to an internal _tkinter binary module, which then calls the Tcl interpreter to evaluate it. The Tcl interpreter will then call into the Tk and/or Ttk packages, which will in turn make calls to Xlib, Cocoa, or GDI.

Módulos Tkinter

Support for Tkinter is spread across several modules. Most applications will need the main tkinter module, as well as the tkinter.ttk module, which provides the modern themed widget set and API:

from tkinter import *
from tkinter import ttk
class tkinter.Tk(screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

Construct a toplevel Tk widget, which is usually the main window of an application, and initialize a Tcl interpreter for this widget. Each instance has its own associated Tcl interpreter.

The Tk class is typically instantiated using all default values. However, the following keyword arguments are currently recognized:

screenName

When given (as a string), sets the DISPLAY environment variable. (X11 only)

baseName

Name of the profile file. By default, baseName is derived from the program name (sys.argv[0]).

className

Name of the widget class. Used as a profile file and also as the name with which Tcl is invoked (argv0 in interp).

useTk

If True, initialize the Tk subsystem. The tkinter.Tcl() function sets this to False.

sync

If True, execute all X server commands synchronously, so that errors are reported immediately. Can be used for debugging. (X11 only)

use

Specifies the id of the window in which to embed the application, instead of it being created as an independent toplevel window. id must be specified in the same way as the value for the -use option for toplevel widgets (that is, it has a form like that returned by winfo_id()).

Note that on some platforms this will only work correctly if id refers to a Tk frame or toplevel that has its -container option enabled.

Tk reads and interprets profile files, named .className.tcl and .baseName.tcl, into the Tcl interpreter and calls exec() on the contents of .className.py and .baseName.py. The path for the profile files is the HOME environment variable or, if that isn’t defined, then os.curdir.

tk

The Tk application object created by instantiating Tk. This provides access to the Tcl interpreter. Each widget that is attached the same instance of Tk has the same value for its tk attribute.

master

The widget object that contains this widget. For Tk, the master is None because it is the main window. The terms master and parent are similar and sometimes used interchangeably as argument names; however, calling winfo_parent() returns a string of the widget name whereas master returns the object. parent/child reflects the tree-like relationship while master/slave reflects the container structure.

children

The immediate descendants of this widget as a dict with the child widget names as the keys and the child instance objects as the values.

tkinter.Tcl(screenName=None, baseName=None, className='Tk', useTk=False)

A função Tcl() é uma função fábrica que cria um objeto assim como o criado pela classe Tk, exceto por não inicializar o subsistema Tk. Isto é útil quando executando o interpretador Tcl em um ambiente onde não se quer criar janelas de alto nível externas, ou quando não se pode (como em sistemas Unix/Linux sem um servidor X). Um objeto criado pelo objeto Tcl() pode ter uma janela de alto nível criada (e o subsistema Tk inicializado) chamando o método loadtk().

The modules that provide Tk support include:

tkinter

Main Tkinter module.

tkinter.colorchooser

Caixa de diálogo para permitir que o usuário escolha uma cor.

tkinter.commondialog

Classe base para os diálogos definidos nos outros módulos listados aqui.

tkinter.filedialog

Diálogos comuns para permitir ao usuário especificar um arquivo para abrir ou salvar.

tkinter.font

Utilitários para ajudar a trabalhar com fontes.

tkinter.messagebox

Acesso às caixas de diálogo padrão do Tk.

tkinter.scrolledtext

Componente de texto com uma barra de rolagem vertical integrada.

tkinter.simpledialog

Diálogos básicos e funções de conveniência.

tkinter.ttk

Themed widget set introduced in Tk 8.5, providing modern alternatives for many of the classic widgets in the main tkinter module.

Additional modules:

_tkinter

A binary module that contains the low-level interface to Tcl/Tk. It is automatically imported by the main tkinter module, and should never be used directly by application programmers. It is usually a shared library (or DLL), but might in some cases be statically linked with the Python interpreter.

idlelib

Python’s Integrated Development and Learning Environment (IDLE). Based on tkinter.

tkinter.constants

Symbolic constants that can be used in place of strings when passing various parameters to Tkinter calls. Automatically imported by the main tkinter module.

tkinter.dnd

(experimental) Drag-and-drop support for tkinter. This will become deprecated when it is replaced with the Tk DND.

tkinter.tix

(deprecated) An older third-party Tcl/Tk package that adds several new widgets. Better alternatives for most can be found in tkinter.ttk.

turtle

Gráficos tartaruga em uma janela Tk.

Preservador de vida Tkinter

This section is not designed to be an exhaustive tutorial on either Tk or Tkinter. For that, refer to one of the external resources noted earlier. Instead, this section provides a very quick orientation to what a Tkinter application looks like, identifies foundational Tk concepts, and explains how the Tkinter wrapper is structured.

The remainder of this section will help you to identify the classes, methods, and options you’ll need in your Tkinter application, and where to find more detailed documentation on them, including in the official Tcl/Tk reference manual.

A Hello World Program

We’ll start by walking through a “Hello World” application in Tkinter. This isn’t the smallest one we could write, but has enough to illustrate some key concepts you’ll need to know.

from tkinter import *
from tkinter import ttk
root = Tk()
frm = ttk.Frame(root, padding=10)
frm.grid()
ttk.Label(frm, text="Hello World!").grid(column=0, row=0)
ttk.Button(frm, text="Quit", command=root.destroy).grid(column=1, row=0)
root.mainloop()

After the imports, the next line creates an instance of the Tk class, which initializes Tk and creates its associated Tcl interpreter. It also creates a toplevel window, known as the root window, which serves as the main window of the application.

The following line creates a frame widget, which in this case will contain a label and a button we’ll create next. The frame is fit inside the root window.

The next line creates a label widget holding a static text string. The grid() method is used to specify the relative layout (position) of the label within its containing frame widget, similar to how tables in HTML work.

A button widget is then created, and placed to the right of the label. When pressed, it will call the destroy() method of the root window.

Finally, the mainloop() method puts everything on the display, and responds to user input until the program terminates.

Important Tk Concepts

Even this simple program illustrates the following key Tk concepts:

widgets

A Tkinter user interface is made up of individual widgets. Each widget is represented as a Python object, instantiated from classes like ttk.Frame, ttk.Label, and ttk.Button.

widget hierarchy

Widgets are arranged in a hierarchy. The label and button were contained within a frame, which in turn was contained within the root window. When creating each child widget, its parent widget is passed as the first argument to the widget constructor.

configuration options

Widgets have configuration options, which modify their appearance and behavior, such as the text to display in a label or button. Different classes of widgets will have different sets of options.

geometry management

Widgets aren’t automatically added to the user interface when they are created. A geometry manager like grid controls where in the user interface they are placed.

event loop

Tkinter reacts to user input, changes from your program, and even refreshes the display only when actively running an event loop. If your program isn’t running the event loop, your user interface won’t update.

Understanding How Tkinter Wraps Tcl/Tk

When your application uses Tkinter’s classes and methods, internally Tkinter is assembling strings representing Tcl/Tk commands, and executing those commands in the Tcl interpreter attached to your applicaton’s Tk instance.

Whether it’s trying to navigate reference documentation, trying to find the right method or option, adapting some existing code, or debugging your Tkinter application, there are times that it will be useful to understand what those underlying Tcl/Tk commands look like.

To illustrate, here is the Tcl/Tk equivalent of the main part of the Tkinter script above.

ttk::frame .frm -padding 10
grid .frm
grid [ttk::label .frm.lbl -text "Hello World!"] -column 0 -row 0
grid [ttk::button .frm.btn -text "Quit" -command "destroy ."] -column 1 -row 0

Tcl’s syntax is similar to many shell languages, where the first word is the command to be executed, with arguments to that command following it, separated by spaces. Without getting into too many details, notice the following:

  • The commands used to create widgets (like ttk::frame) correspond to widget classes in Tkinter.

  • Tcl widget options (like -text) correspond to keyword arguments in Tkinter.

  • Widgets are referred to by a pathname in Tcl (like .frm.btn), whereas Tkinter doesn’t use names but object references.

  • A widget’s place in the widget hierarchy is encoded in its (hierarchical) pathname, which uses a . (dot) as a path separator. The pathname for the root window is just . (dot). In Tkinter, the hierarchy is defined not by pathname but by specifying the parent widget when creating each child widget.

  • Operations which are implemented as separate commands in Tcl (like grid or destroy) are represented as methods on Tkinter widget objects. As you’ll see shortly, at other times Tcl uses what appear to be method calls on widget objects, which more closely mirror what would is used in Tkinter.

How do I…? What option does…?

If you’re not sure how to do something in Tkinter, and you can’t immediately find it in the tutorial or reference documentation you’re using, there are a few strategies that can be helpful.

First, remember that the details of how individual widgets work may vary across different versions of both Tkinter and Tcl/Tk. If you’re searching documentation, make sure it corresponds to the Python and Tcl/Tk versions installed on your system.

When searching for how to use an API, it helps to know the exact name of the class, option, or method that you’re using. Introspection, either in an interactive Python shell or with print(), can help you identify what you need.

To find out what configuration options are available on any widget, call its configure() method, which returns a dictionary containing a variety of information about each object, including its default and current values. Use keys() to get just the names of each option.

btn = ttk.Button(frm, ...)
print(btn.configure().keys())

As most widgets have many configuration options in common, it can be useful to find out which are specific to a particular widget class. Comparing the list of options to that of a simpler widget, like a frame, is one way to do that.

print(set(btn.configure().keys()) - set(frm.configure().keys()))

Similarly, you can find the available methods for a widget object using the standard dir() function. If you try it, you’ll see there are over 200 common widget methods, so again identifying those specific to a widget class is helpful.

print(dir(btn))
print(set(dir(btn)) - set(dir(frm)))

Modelo de threading

Python e Tcl/Tk têm modelos de threading muito diferentes, que tkinter tenta fazer a ponte. Se você usa threads, pode precisar estar ciente disso.

Um interpretador Python pode ter muitas threads associados a ele. Em Tcl, várias threads podem ser criadas, mas cada thread tem uma instância de interpretador Tcl separada associada a ele. Threads também podem criar mais de uma instância do interpretador, embora cada instância do interpretador possa ser usada apenas pela thread que a criou.

Cada objeto Tk criado por tkinter contém um interpretador Tcl. Ele também controla qual thread criou aquele interpretador. Chamadas para tkinter podem ser feitas a partir de qualquer thread do Python. Internamente, se uma chamada vier de um thread diferente daquele que criou o objeto Tk, um evento é postado na fila de eventos do interpretador e, quando executado, o resultado é retornado ao thread de chamada do Python.

As aplicações Tcl/Tk são normalmente orientadas a eventos, o que significa que após a inicialização, o interpretador executa um laço de eventos (ou seja Tk.mainloop()) e responde aos eventos. Por ser de thread única, os tratadores de eventos devem responder rapidamente, caso contrário, bloquearão o processamento de outros eventos. Para evitar isso, quaisquer cálculos de longa execução não devem ser executados em um tratador de eventos, mas são divididos em pedaços menores usando temporizadores ou executados em outra thread. Isso é diferente de muitos kits de ferramentas de GUI em que a GUI é executada em um thread completamente separado de todo o código do aplicação, incluindo tratadores de eventos.

Se o interpretador Tcl não estiver executando o laço de eventos e processando eventos, qualquer chamada tkinter feita de threads diferentes daquela que está executando o interpretador do Tcl irá falhar.

Existem vários casos especiais:

  • Bibliotecas Tcl/Tk podem ser construídas de forma que não reconheçam thread. Neste caso, tkinter chama a biblioteca da thread originadora do Python, mesmo que seja diferente da thread que criou o interpretador Tcl. Um bloqueio global garante que apenas uma chamada ocorra por vez.

  • Enquanto tkinter permite que você crie mais de uma instância de um objeto Tk (com seu próprio interpretador), todos os interpretadores que fazem parte da mesma thread compartilham uma fila de eventos comum, o que fica muito rápido. Na prática, não crie mais de uma instância de Tk por vez. Caso contrário, é melhor criá-los em threads separadas e garantir que você esteja executando uma construção Tcl/Tk com reconhecimento de thread.

  • Bloquear manipuladores de eventos não é a única maneira de evitar que o interpretador Tcl entre novamente no laço de eventos. É ainda possível executar vários laços de eventos aninhados ou abandonar totalmente o laço de eventos. Se você estiver fazendo algo complicado quando se trata de eventos ou threads, esteja ciente dessas possibilidades.

  • Existem algumas funções de seleção do tkinter que atualmente funcionam apenas quando chamadas a partir da thread que criou o interpretador Tcl.

Referência Útil

Opções de Definição

As opções controlam coisas como a cor e a largura da borda de um widget. As opções podem ser definidas de três maneiras:

No momento da criação do objeto, usando argumentos nomeados
fred = Button(self, fg="red", bg="blue")
Após a criação do objeto, tratando o nome da opção como um índice de dicionário
fred["fg"] = "red"
fred["bg"] = "blue"
Use o método config() para atualizar vários attrs posteriores à criação do objeto
fred.config(fg="red", bg="blue")

Para uma explicação completa de uma dada opção e seu comportamento, veja as páginas man do Tk para o widget em questão.

Note que as páginas man listam “OPÇÕES PADRÃO” e “OPÇÕES DE WIDGET ESPECÍFICO” para cada widget. A primeira é uma lista de opções que são comuns a vários widgets, e a segunda são opções que são idiossincráticas ao widget em particular. As Opções Padrão estão documentadas na página man options(3).

Nenhuma distinção entre as opções padrão e específicas de widget são feitas neste documento. Algumas opções não se aplicam a alguns tipos de widgets. A resposta de um dado widget a uma opção particular depende da classe do widget; botões possuem a opção command, etiquetas não.

As opções suportadas por um dado widget estão listadas na página man daquele widget, ou podem ser consultadas no tempo de execução chamando o método config() sem argumentos, ou chamando o método keys() daquele widget. O valor retornado por essas chamadas é um dicionário cujas chaves são os nomes das opções como uma string (por exemplo, 'relief') e cujos valores são tuplas de 5 elementos.

Algumas opções, como bg são sinônimos para opções comuns com nomes mais longos (bg é a abreviação de “background”, ou plano de fundo em inglês). Passando o nome de uma opção abreviada ao método config() irá retornar uma tupla de 2 elementos, e não uma tupla de 5 elementos. A tupla de 2 elementos devolvida irá conter o nome do sinônimo e a opção “verdadeira” (como por exemplo em ('bg', 'background')).

Índice

Significado

Exemplo

0

nome da opção

'relief'

1

nome da opção para buscas de banco de dados

'relief'

2

classe de opção para busca de banco de dados

'Relief'

3

valor padrão

'raised'

4

valor atual

'groove'

Exemplo:

>>> print(fred.config())
{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')}

É claro que o dicionário exibido irá incluir todas as opções disponíveis e seus valores. Isso foi apenas um exemplo.

O Empacotador

O empacotador é um dos mecanismos de gerenciamento de geometria do Tk. Gerenciadores de geometria são utilizados para especificar as posições relativas dos widgets dentro dos seus contêineres - os seus processos pai mútuos. Em contraste ao mais incômodo posicionador (que é usado com menos frequência, e não falaremos dele aqui), o empacotador recebe a especificação de relacionamento qualitativo - acima, à esquerda de, preenchimento, etc. - e determina as coordenadas de posição exatas para você.

O tamanho de qualquer widget mestre é determinado pelo tamanho dos “widgets escravos” internos. O empacotador é usado para controlar onde os widgets escravos aparecem dentro do mestre no qual são empacotados. Você pode empacotar widgets em quadros e quadros em outros quadros, a fim de obter o tipo de layout que deseja. Além disso, o arranjo é ajustado dinamicamente para acomodar alterações incrementais na configuração, uma vez que é empacotado.

Note que os widgets não aparecem até que eles tenham sua geometria especificada pelo gerenciador de geometria. É um erro comum de iniciantes deixar a geometria de fora da especificação, então se surpreender que o widget é criado sendo que nada apareceu. O widget irá aparecer apenas quando tiver, por exemplo, o método método pack() do empacotador aplicado a ele.

O método pack() pode ser chamado com pares de palavra reservada-opção/valor que controlam onde o widget deverá aparecer dentro do seu contêiner, e como deverá se comportar quando a janela da aplicação principal for redimensionada. Aqui estão alguns exemplos:

fred.pack()                     # defaults to side = "top"
fred.pack(side="left")
fred.pack(expand=1)

Opções do Empacotador

Para uma informação mais completa do empacotador e as opções que pode receber, veja as páginas man e a página 183 do livro do John Ousterhout.

anchor

Tipo âncora. Denota onde o packer deverá posicionar cada ajudante em seu pacote.

expand

Booleano, 0 ou 1.

fill

Valores legais: 'x', 'y', 'both', 'none'.

ipadx e ipady

Uma distância - designando o deslocamento interno de cada lado do widget ajudante.

padx and pady

Uma distância - designando o deslocamento externo de cada lado do widget ajudante.

side

Valores legais são: 'left', 'right', 'top', 'bottom'.

Acoplando Variáveis de Widgets

A definição do valor atual de alguns widgets (como widgets de entrada de texto) podem ser conectadas diretamente às variáveis da aplicação utilizando métodos especiais. Estas opções são variable, textvariable, onvalue, offvalue, e value. A conexão funciona por ambos os lados: Se por algum motivo a variável se altera, o widget ao qual ela está conectada irá se atualizar para refletir este novo valor.

Infelizmente, na atual implementação do tkinter não é possível passar uma variável Python arbitrária para um widget por uma opção variable ou textvariable. Os únicos tipos de variáveis para as quais isso funciona são variáveis que são subclasses da classe chamada Variable, definida em tkinter.

Há muitas subclasses de Variable úteis já definidas: StringVar, IntVar, DoubleVar, e BooleanVar. Para ler o atual valor de uma variável, chame o método get() nelas, e para alterar o valor você deve chamar o método set(). Se você seguir este protocolo, o widget irá sempre acompanhar os valores da variável, sem nenhuma intervenção da sua parte.

Por exemplo:

import tkinter as tk

class App(tk.Frame):
    def __init__(self, master):
        super().__init__(master)
        self.pack()

        self.entrythingy = tk.Entry()
        self.entrythingy.pack()

        # Create the application variable.
        self.contents = tk.StringVar()
        # Set it to some value.
        self.contents.set("this is a variable")
        # Tell the entry widget to watch this variable.
        self.entrythingy["textvariable"] = self.contents

        # Define a callback for when the user hits return.
        # It prints the current value of the variable.
        self.entrythingy.bind('<Key-Return>',
                             self.print_contents)

    def print_contents(self, event):
        print("Hi. The current entry content is:",
              self.contents.get())

root = tk.Tk()
myapp = App(root)
myapp.mainloop()

O Gerenciador de Janela

No Tk, existe um comando utilitário, wm, para interagir com o gerenciador de janelas. As opções do comando wm permitem que você controle coisas como títulos, localização, ícones bitmap, entre outros. No tkinter, estes comandos foram implementados como métodos da classe Wm class. Widgets de mais alto nívelsão subclasses da classe Wm e portanto podem chamar os métodos Wm diretamente.

Para chegar à janela de nível superior que contém um determinado widget, geralmente você pode apenas consultar o mestre do widget. Claro, se o widget foi compactado dentro de um quadro, o mestre não representará uma janela de nível superior. Para chegar à janela de nível superior que contém um widget arbitrário, você pode chamar o método _root(). Este método começa com um sublinhado para denotar o fato de que esta função é parte da implementação, e não uma interface para a funcionalidade Tk.

Aqui estão alguns exemplos de uso típico:

import tkinter as tk

class App(tk.Frame):
    def __init__(self, master=None):
        super().__init__(master)
        self.pack()

# create the application
myapp = App()

#
# here are method calls to the window manager class
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)

# start the program
myapp.mainloop()

Opções de Tipos de Dados do Tk

anchor

Valores legais são os pontos cardeais: "n", "ne", "e", "se", "s", "sw", "w", "nw", e também "center".

bitmap

Há 8 bitmaps embutidos nomeados: 'error', 'gray25', 'gray50', 'hourglass', 'info', 'questhead', 'question', 'warning'. Para especificar um nome de arquivo do bitmap X, passe o caminho completo do arquivo, precedido pelo caractere @, como em "@/usr/contrib/bitmap/gumby.bit".

booleano

Você pode passar os inteiros 0 ou 1 ou as strings "yes" ou "no".

função de retorno

Esta é uma função Python que não aceita argumentos. Por exemplo:

def print_it():
    print("hi there")
fred["command"] = print_it
cor

Colors can be given as the names of X colors in the rgb.txt file, or as strings representing RGB values in 4 bit: "#RGB", 8 bit: "#RRGGBB", 12 bit: "#RRRGGGBBB", or 16 bit: "#RRRRGGGGBBBB" ranges, where R,G,B here represent any legal hex digit. See page 160 of Ousterhout’s book for details.

cursor

Os nomes de cursor X padrão de cursorfont.h podem ser usados, sem o prefixo XC_. Por exemplo, para obter um cursor de mão (XC_hand2), use a string "hand2". Você também pode especificar um bitmap e um arquivo de máscara de sua preferência. Veja a página 179 do livro de Ousterhout.

distance

As distâncias da tela podem ser especificadas em pixels ou distâncias absolutas. Pixels são dados como números e distâncias absolutas como strings, com os caracteres finais denotando unidades: c para centímetros, i para polegadas, m para milímetros, p para os pontos da impressora. Por exemplo, 3,5 polegadas é expresso como "3.5i".

font

Tk usa um formato de nome de fonte de lista, como {courier 10 bold}. Tamanhos de fonte com números positivos são medidos em pontos; tamanhos com números negativos são medidos em pixels.

geometria

Esta é uma string no formato widthxheight, onde largura e altura são medidas em pixels para a maioria dos widgets (em caracteres para widgets que exibem texto). Por exemplo: fred["geometry"] = "200x100".

justify

Valores aceitos são as strings: "left", "center", "right" e "fill".

region

Esta é uma string com quatro elementos delimitados por espaço, cada um dos quais a uma distância legal (veja acima). Por exemplo: "2 3 4 5" e "3i 2i 4.5i 2i" e "3c 2c 4c 10.43c" são todas regiões legais.

relief

Determina qual será o estilo da borda de um widget. Os valores legais são: "raised", "sunken", "flat", "groove" e "ridge".

scrollcommand

Este é quase sempre o método set() de algum widget da barra de rolagem, mas pode ser qualquer método de widget que receba um único argumento.

wrap

Deve ser um de: "none", "char" ou "word".

Ligações e Eventos

O método de ligação do comando widget permite que você observe certos eventos e tenha um acionamento de função de retorno de chamada quando esse tipo de evento ocorrer. A forma do método de ligação é:

def bind(self, sequence, func, add=''):

sendo que:

sequence

é uma string que denota o tipo de evento de destino. (Veja a página man do bind e a página 201 do livro de John Ousterhout para obter detalhes).

func

é uma função Python, tendo um argumento, a ser invocada quando o evento ocorre. Uma instância de evento será passada como argumento. (As funções implantadas dessa forma são comumente conhecidas como funções de retorno.)

add

é opcional, tanto '' ou '+'. Passar uma string vazia indica que essa ligação substitui todas as outras ligações às quais esse evento está associado. Passar um '+' significa que esta função deve ser adicionada à lista de funções ligadas a este tipo de evento.

Por exemplo:

def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)

Observe como o campo widget do evento está sendo acessado na função de retorno turn_red(). Este campo contém o widget que capturou o evento X. A tabela a seguir lista os outros campos de evento que você pode acessar e como eles são denotados no Tk, o que pode ser útil ao se referir às páginas man do Tk.

Tk

Campo de Eventos do Tkinter

Tk

Campo de Eventos do Tkinter

%f

focus

%A

char

%h

height

%E

send_event

%k

keycode

%K

keysym

%s

state

%N

keysym_num

%t

time

%T

tipo

%w

width

%W

widget

%x

x

%X

x_root

%y

y

%Y

y_root

O Parâmetro index

Vários widgets requerem que parâmetros de “indx” sejam passados. Eles são usados para apontar para um local específico em um widget Text, ou para caracteres específicos em um widget Entry, ou para itens de menu específicos em um widget Menu.

Entry widget indexes (index, view index, etc.)

Entry widgets have options that refer to character positions in the text being displayed. You can use these tkinter functions to access these special points in text widgets:

Text widget indexes

The index notation for Text widgets is very rich and is best described in the Tk man pages.

Menu indexes (menu.invoke(), menu.entryconfig(), etc.)

Algumas opções e métodos de menus manipulam entradas de menu específicas. Sempre que um índice de menu é necessário para uma opção ou parâmetro, você pode passar:

  • um número inteiro que se refere à posição numérica da entrada no widget, contada do topo, começando com 0;

  • a string "active", que se refere à posição do menu que está atualmente sob o cursor;

  • a string "last" que se refere ao último item do menu;

  • Um inteiro precedido por @, como em @6, onde o inteiro é interpretado como uma coordenada de pixel y no sistema de coordenadas do menu;

  • a string "none", que indica nenhuma entrada de menu, mais frequentemente usada com menu.activate() para desativar todas as entradas e, finalmente,

  • uma string de texto cujo padrão corresponde ao rótulo da entrada do menu, conforme varrido da parte superior do menu para a parte inferior. Observe que este tipo de índice é considerado após todos os outros, o que significa que as correspondências para itens de menu rotulados como last, active ou none podem ser interpretadas como os literais acima, em vez disso.

Imagens

Imagens de diferentes formatos podem ser criadas por meio da subclasse correspondente de tkinter.Image:

  • BitmapImage para imagens no formato XBM.

  • PhotoImage para imagens nos formatos PGM, PPM, GIF e PNG. O suporte ao último foi adicionado a partir do Tk 8.6.

Qualquer tipo de imagem é criado através da opção file ou data (outras opções também estão disponíveis).

O objeto imagem pode então ser usado sempre que uma opção image há suporte em algum widget (por exemplo: rótulos, botões, menus). Nestes casos, o Tk não guardará uma referência à imagem. Quando a última referência Python ao objeto imagem for excluída, os dados da imagem também serão excluídos e o Tk exibirá uma caixa vazia onde quer que a imagem tenha sido usada.

Ver também

O pacote Pillow adiciona suporte para formatos como BMP, JPEG, TIFF e WebP, dentre outros.

Tratadores de arquivos

O Tk permite que você registre e cancele o registro de uma função de retorno que será chamada a partir do laço central do Tk quando uma E/S for possível em um descritor de arquivo. Apenas um tratador pode ser registrado por descritor de arquivo. Código de exemplo:

import tkinter
widget = tkinter.Tk()
mask = tkinter.READABLE | tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)

Este recurso não está disponível no Windows.

Já que você não sabe quantos bytes estão disponíveis para leitura, você pode não querer usar os métodos read() ou readline() de BufferedIOBase ou TextIOBase, já que eles insistirão em ler uma quantidade predefinida de byts. Para sockets, os métodos recv() ou recvfrom() vão servir; para outros arquivos, use dados brutos ou os.read(file.fileno(), maxbytecount).

Widget.tk.createfilehandler(file, mask, func)

Registra a função de retorno do tratador de arquivo func. O argumento file pode ser um objeto com um método fileno() (como um arquivo ou objeto soquete) ou um descritor de arquivo de inteiro. O argumento mask é uma combinação OR de qualquer uma das três constantes abaixo. O retorno de chamada é chamado da seguinte maneira:

callback(file, mask)
Widget.tk.deletefilehandler(file)

Cancela o registro de um tratador de arquivo.

tkinter.READABLE
tkinter.WRITABLE
tkinter.EXCEPTION

Constantes usadas nos argumentos mask.