25.1. : mod: *tkinter* --- Interface Python para Tcl / Tk
*********************************************************

**Código Fonte:** Lib/tkinter/__init__.py

======================================================================

O pacote: mod: *tkinter* (" Tk interface ") é a interface padrão do
Python para o kit de ferramentas Tk GUI. Ambos Tk e: mod: *tkinter*
estão disponíveis na maioria das plataformas Unix, assim como em
sistemas Windows. (O próprio Tk não faz parte do Python; ele é mantido
no ActiveState.)

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

Ver também:

  Documentação do Tkinter:

  *Recursos do Python Tkinter <https://wiki.python.org/moin/TkInter>*
  _
     O Python Tkinter Topic Guide fornece uma grande quantidade de
     informações sobre como usar o Tk do Python e links para outras
     fontes de informação no Tk.

  *TKDocs <http://www.tkdocs.com/>* _
     Tutorial extenso e páginas de widgets mais amigáveis para alguns
     dos widgets.

  *Referência Tkinter 8.5: uma GUI para Python <https://web.archive.o
  rg/web/20190524140835/https://infohost.nmt.edu/tcc/help/pubs/tkinte
  r/web/index.html>* _
     Material de referência on-line.

  *Tkinter docs from effbot <http://effbot.org/tkinterbook/>* _
     Referência online para o tkinter suportado pelo effbot.org.

  *Programação Python <http://learning-python.com/about-pp4e.html>* _
     Livro de Mark Lutz, tem excelente cobertura da Tkinter.

  *Tkinter moderno para desenvolvedores Python ocupados
  <https://www.amazon.com/Modern-Tkinter-Python-Developers-
  ebook/dp/B0071QDNLO/>* _
     Livro de Mark Roseman sobre a construção de interfaces gráficas
     de usuário atraentes e modernas com Python e Tkinter.

  *Programação Python e Tkinter <https://www.manning.com/books/python-
  and-tkinter-programming>* _
     Livro de John Grayson (ISBN 1-884777-81-3).

  Documentação Tcl / Tk:

  *Comandos Tk <https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm>* _
     A maioria dos comandos estão disponíveis como classes: mod:
     *tkinter* ou: mod:` tkinter.ttk`. Altere '8.6' para corresponder
     à versão de sua instalação Tcl / Tk.

  *Páginas de manual recentes do Tcl / Tk <https://www.tcl.tk/doc/>* _
     Manuais Tcl / Tk recentes em www.tcl.tk.

  ActiveState Tcl Home Page
     O desenvolvimento do Tk/Tcl acontece em larga medida em
     ActiveState.

  Tcl and the Tk Toolkit
     Livro de John Ousterhout, o inventor do Tcl.

  Practical Programming in Tcl and Tk
     Livro enciclopédico de Brent Welch.


25.1.1. Módulos Tkinter
=======================

Na maioria das vezes, "tkinter" é tudo o que você precisa, mas há
outros módulos adicionais disponíveis. A interface do Tk está
localizada em um módulo binário chamado "_tkinter". Este módulo contém
a interface de baixo nível do Tk, e nunca deve ser utilizada
diretamente por aplicativos de programadores. Geralmente é uma
biblioteca compartilhada (ou DLL), mas pode estar em alguns casos
conectada estaticamente ao interpretador do Python.

Além do módulo de interface do Tk, "tkinter" inclui vários módulos do
Python, "tkinter.constants" sendo o mais importante. Importar
"tkinter"  irá importar "tkinter.constants" automaticamente, então,
geralmente, para utilizar o Tkinter tudo o que você ´recisa é de uma
simples instrução de importação:

   import tkinter

Ou, com mais frequência:

   from tkinter import *

class tkinter.Tk(screenName=None, baseName=None, className='Tk', useTk=1)

   A classe "Tk" é instanciada sem argumentos. Isto cria um widget de
   alto nível de Tk que normalmente é a janela principal da aplicação.
   Cada instância possui seu próprio interpretador Tcl associado.

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

   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 subssistema
   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 subssistema Tk inicializado) chamando o método
   "loadtk()".

Outros módulos que fornecem suporte Tk incluem:

"tkinter.scrolledtext"
   Widget de texto com uma barra de rolagem vertical integrada.

"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.simpledialog"
   Diálogos básicos e funções de conveniência.

"tkinter.dnd"
   Suporte de arrastar e soltar para: mod: *tkinter*. Isso é
   experimental e deve se tornar obsoleto quando for substituído pelo
   Tk DND.

"turtle"
   Gráficos de tartaruga em uma janela Tk.


25.1.2. Preservador de vida Tkinter
===================================

Esta seção não foi projetada para ser um tutorial completo sobre Tk ou
Tkinter. Em vez disso, pretende ser um obstáculo, fornecendo alguma
orientação introdutória sobre o sistema.

Créditos:

* Tk foi escrito por John Ousterhout enquanto estava em Berkeley.

* Tkinter foi escrito por Steen Lumholt e Guido van Rossum.

* This Life Preserver foi escrito por Matt Conway, da Universidade de
  Virgínia.

* A renderização do HTML, com algumas edições livres, foram produzidas
  de uma versão do FrameMaker por Ken Manheimer.

* Fredrik Lundh elaborou e revisou as descrições de interface de
  classe, para que elas fiquem atuais com Tk 4.2

* Mike Clarkson converteu a documentação para LaTeX e compilou o
  capítulo de Interface de Usuário para o manual de referência.


25.1.2.1. Como usar esta seção
------------------------------

Esta seção foi feita em duas partes: a primeira parte (mais ou menos)
cobre os materiais fundamentais, enquanto a segunda parte pode ser
levada para o teclado como uma referência útil.

Ao tentar responder perguntas do tipo "como eu faço x", é melhor
pensar como eu faço "x" direto no Tk, e então converter de volta para
uma chamada correspondente do "tkinter". Programadores Python
normalmente adivinham os comandos corretos em Python apenas olhando a
documentação do Tk. Isso significa que para usar Tkinter, você deverá
aprender um pouco sobre Tk. Este documento não pode preencher esse
papel, então o melhor que podemos fazer é indicar as melhores
documentações que existem. Aqui vão algumas dicas:

* Os autores sugerem fortemente que se consiga uma cópia das páginas
  man do Tk. Especificamente, as páginas man no diretório "manN" são
  as mais úteis. As páginas man "man3" descrevem a interface C com a
  biblioteca Tk e, portanto, não são tão úteis para criadores de
  script.

* Addison-Wesley publica um livro chamado Tcl and the Tk Toolkit de
  John Ousterhout (ISBN 0-201-63337-X), que é uma boa introdução a Tcl
  e Tk para o iniciante. O livro não é exaustivo e, para muitos
  detalhes, ele recorre às páginas de manual.

* "tkinter/__init__.py" é o último recurso para a maioria, mas pode
  ser um bom lugar para ir quando nada mais faz sentido.


25.1.2.2. Um simples programa Olá Mundo
---------------------------------------

   import tkinter as tk

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

       def create_widgets(self):
           self.hi_there = tk.Button(self)
           self.hi_there["text"] = "Hello World\n(click me)"
           self.hi_there["command"] = self.say_hi
           self.hi_there.pack(side="top")

           self.quit = tk.Button(self, text="QUIT", fg="red",
                                 command=self.master.destroy)
           self.quit.pack(side="bottom")

       def say_hi(self):
           print("hi there, everyone!")

   root = tk.Tk()
   app = Application(master=root)
   app.mainloop()


25.1.3. Uma olhada (muito) rápida em Tcl / Tk
=============================================

A hierarquia de classe parece complicada, mas na prática,
programadores de aplicação quase sempre se referem às classes nos
níveis mais baixos da hierarquia.

Notas:

* Essas classes são fornecidas com o objetivo de organizar certas
  funções em um espaço de nomes. Elas não devem ser instanciadas de
  forma independente.

* A classe "Tk" deve ser instanciada apenas uma vez em uma aplicação.
  Os programadores de aplicação não precisam instanciar uma
  explicitamente, o sistema cria uma sempre que qualquer uma das
  outras classes é instanciada.

* A classe "Widget" não foi feita para ser instanciada, é apenas para
  quando subclasses forem criadas para fazer widgets "reais" (em C++,
  isto é chamado de *classe abstrata*).

Para fazer uso deste material de referência, haverá vezes em que você
precisará saber como ler pequenas passagens de Tk e como identificar
as várias partes dos comandos Tk. (Veja a seção Mapeamento de TK
Básico para Tkinter para equivalentes de "tkinter" do que está
mostrado abaixo.)

Scripts Tk são programas Tcl. Como todos os programas Tcl, scripts Tk
são apenas listas de elementos sintáticos (tokens) separados por
espaços. Um widget Tk é apenas sua *classe*, as *opções* que ajudam a
configurá-los, e as *ações* que permitem fazer coisas úteis.

Para fazer um widget em Tk, o comando é sempre da forma:

   classCommand newPathname options

*classCommand*
   denota que tipo de widget fazer (um botão, um rótulo, um menu ...)

*newPathname*
   É o novo nome para este widget. Todos os nomes em Tk devem ser
   únicos. Para ajudar a import isto, os widgets em Tk são renomeados
   com *parêntesis*, assim como arquivos em um sistema de arquivos. O
   widget de nível mais alto, a *raiz*, é chamado de "." (ponto) e os
   filhos são delimitados por demais pontos. Por exemplo,
   ".myApp.controlPanel.okButton" pode ser o nome de um widget.

*options*
   configura a aparência do widget e, em alguns casos, seu
   comportamento. As opções aparecem na forma de listas de flags ou
   valores. Flags são precedidas por um '-', como flags em comandos de
   console em Unix, e os valores são colocados entre aspas se
   consistirem em mais de uma palavra.

Por exemplo:

   button   .fred   -fg red -text "hi there"
      ^       ^     \______________________/
      |       |                |
    class    new            options
   command  widget  (-opt val -opt val ...)

Uma vez criado, o nome do path do widget se torna um novo comando.
Este novo *comando widget* é o manipulador do programador para fazer o
novo widget executar alguma *ação*. Em C, você expressaria isso como
algumaAção(fred, algumasOpções), em C++, você expressaria isso como
fred.algumaAção(algumasOpções), e em Tk, você usaria:

   .fred someAction someOptions

Observe que o nome do objeto, ".fred", começa com um ponto.

Como você deve esperar, os valores legais de *algumaAção* vão depender
da classe do widget: ".fred disable" funciona se fred é um botão (fred
fica cinza), mas não funciona se fred é uma etiqueta (desativar
etiquetas não é suportado por Tk).

Os valores legais para *algumaOpção* é dependente de ação. Algumas
ações, como "disable", requerem nenhum argumento, outras, como o
comando "delete" de uma caixa de entrada de texto, precisaria de
argumentos para especificar o intervalo do texto para apagar.


25.1.4. Mapeamento de TK Básico para Tkinter
============================================

Comandos de classe em Tk correspondem à construtores de classe em
Tkinter.

   button .fred                =====>  fred = Button()

The master of an object is implicit in the new name given to it at
creation time.  In Tkinter, masters are specified explicitly.

   button .panel.fred          =====>  fred = Button(panel)

As opções de configurações em Tk são dadas como listas de etiquetas
com hífen seguidas por valores. Em Tkinter, as opções são
especificadas como argumentos de palavra reservada na instância do
construtor, e args de palavras reservadas para configurar chamadas, ou
como índices de instâncias, na forma de dicionários, para estabelecer
instâncias. Veja a seção See section Opções de configuração sobre
opções de definições.

   button .fred -fg red        =====>  fred = Button(panel, fg="red")
   .fred configure -fg red     =====>  fred["fg"] = red
                               OR ==>  fred.config(fg="red")

Em Tk, para executar uma ação em um widget, utilize o nome do widget
como comando, seguido pelo nome de uma ação, possivelmente com
argumentos (opções). Em Tkinter, você chama métodos na instância da
classe para invocar ações no widget. As ações (métodos) que um
determindo widget pode executar estão listadas em
"tkinter/__init__.py".

   .fred invoke                =====>  fred.invoke()

Para dar o widget ao empacotador (gerenciador de geometria), você
chama pack com argumentos opcionais. Em Tkinter, a classe Pack detém
toda esta funcionalidade, e as várias formas do comando pack estão
implementadas como métodos. Todos os widgets em "tkinter" são
subclasses de Packer, e portanto herdam todos os métodos de
empacotamento. Veja a documentação do módulo "tkinter.tix" para
informações adicionais sobre o gerenciador de geometria.

   pack .fred -side left       =====>  fred.pack(side="left")


25.1.5. Como Tk e Tkinter estão relacionados
============================================

De cima para baixo:

Sua aplicação aqui (Python)
   Ums aplicação Python faz uma chamada "tkinter".

tkinter (pacote Python)
   Esta chamada (por exemplo, criando um widget de botão), é
   implementada no pacote "tkinter", que é escrito em Python. Esta
   função Python irá analisar os comandos e os argumentos e
   convertê-los em uma forma que faça parecer que vieram de um script
   Tk em vez de um script Python.

_tkinter (C)
   Esses comandos e seus argumentos serão passados para uma função C
   no módulo de extensão "_tkinter" - note o sublinhado.

Widgets Tk (C e Tcl)
   Esta função C é capaz de fazer chamadas para outros módulos C,
   incluindo as funções C que compõem a biblioteca Tk. Tk é
   implementado em C e algum Tcl. A parte Tcl dos widgets Tk é usada
   para vincular certos comportamentos padrão aos widgets e é
   executada uma vez no ponto onde o pacote Python "tkinter" é
   importado. (O usuário nunca vê este estágio).

Tk (C)
   A parte Tk dos Widgets Tk implementa o mapeamento final para ...

Xlib (C)
   a biblioteca Xlib para desenhar gráficos na tela.


25.1.6. Referência útil
=======================


25.1.6.1. Opções de configuraçã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')").

+---------+-----------------------------------+----------------+
| Index   | Significado                       | Exemplo        |
|=========|===================================|================|
| 0       | nome da opção                     | "'relief'"     |
+---------+-----------------------------------+----------------+
| 1       | nome da opção para buscas de      | "'relief'"     |
|         | banco de dados                    |                |
+---------+-----------------------------------+----------------+
| 2       | classe de opção para busca de     | "'Relief'"     |
|         | banco de dados                    |                |
+---------+-----------------------------------+----------------+
| 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.


25.1.6.2. O Empacotador
-----------------------

The packer is one of Tk's geometry-management mechanisms.    Geometry
managers are used to specify the relative positioning of the
positioning of widgets within their container - their mutual *master*.
In contrast to the more cumbersome *placer* (which is used less
commonly, and we do not cover here), the packer takes qualitative
relationship specification - *above*, *to the left of*, *filling*, etc
- and works everything out to determine the exact placement
coordinates for you.

The size of any *master* widget is determined by the size of the
"slave widgets" inside.  The packer is used to control where slave
widgets appear inside the master into which they are packed.  You can
pack widgets into frames, and frames into other frames, in order to
achieve the kind of layout you desire. Additionally, the arrangement
is dynamically adjusted to accommodate incremental changes to the
configuration, once it is packed.

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)


25.1.6.3. 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.

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

expandir
   Booleano, "0" ou "1".

preencher
   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'".


25.1.6.4. 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:

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

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

           # here is the application variable
           self.contents = 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

           # and here we get a callback when the user hits return.
           # we will have the program print out the value of the
           # application variable when the user hits return
           self.entrythingy.bind('<Key-Return>',
                                 self.print_contents)

       def print_contents(self, event):
           print("hi. contents of entry is now ---->",
                 self.contents.get())


25.1.6.5. 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.

To get at the toplevel window that contains a given widget, you can
often just refer to the widget's master.  Of course if the widget has
been packed inside of a frame, the master won't represent a toplevel
window.  To get at the toplevel window that contains an arbitrary
widget, you can call the "_root()" method. This method begins with an
underscore to denote the fact that this function is part of the
implementation, and not an interface to Tk functionality.

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()


25.1.6.6. Opções de Tipos de Dados do Tk
----------------------------------------

âncora
   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"".

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

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

color
   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
   The standard X cursor names from "cursorfont.h" can be used,
   without the "XC_" prefix.  For example to get a hand cursor
   ("XC_hand2"), use the string ""hand2"".  You can also specify a
   bitmap and mask file of your own. See page 179 of Ousterhout's
   book.

distance
   Screen distances can be specified in either pixels or absolute
   distances. Pixels are given as numbers and absolute distances as
   strings, with the trailing character denoting units: "c" for
   centimetres, "i" for inches, "m" for millimetres, "p" for printer's
   points.  For example, 3.5 inches is expressed as ""3.5i"".

font
   Tk uses a list font name format, such as "{courier 10 bold}". Font
   sizes with positive numbers are measured in points; sizes with
   negative numbers are measured in pixels.

geometry
   This is a string of the form "widthxheight", where width and height
   are measured in pixels for most widgets (in characters for widgets
   displaying text). For example: "fred["geometry"] = "200x100"".

justify
   Legal values are the strings: ""left"", ""center"", ""right"", and
   ""fill"".

region
   This is a string with four space-delimited elements, each of which
   is a legal distance (see above).  For example: ""2 3 4 5"" and ""3i
   2i 4.5i 2i"" and ""3c 2c 4c 10.43c""  are all legal regions.

relief
   Determines what the border style of a widget will be.  Legal values
   are: ""raised"", ""sunken"", ""flat"", ""groove"", and ""ridge"".

scrollcommand
   This is almost always the "set()" method of some scrollbar widget,
   but can be any widget method that takes a single argument.

wrap:
   Must be one of: ""none"", ""char"", or ""word"".


25.1.6.7. Bindings and Events
-----------------------------

The bind method from the widget command allows you to watch for
certain events and to have a callback function trigger when that event
type occurs.  The form of the bind method is:

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

where:

sequence (sequência)
   is a string that denotes the target kind of event.  (See the bind
   man page and page 201 of John Ousterhout's book for details).

func
   is a Python function, taking one argument, to be invoked when the
   event occurs. An Event instance will be passed as the argument.
   (Functions deployed this way are commonly known as *callbacks*.)

add
   is optional, either "''" or "'+'".  Passing an empty string denotes
   that this binding is to replace any other bindings that this event
   is associated with.  Passing a "'+'" means that this function is to
   be added to the list of functions bound to this event type.

Por exemplo:

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

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

Notice how the widget field of the event is being accessed in the
"turn_red()" callback.  This field contains the widget that caught the
X event.  The following table lists the other event fields you can
access, and how they are denoted in Tk, which can be useful when
referring to the Tk man pages.

+------+-----------------------+------+-----------------------+
| Tk   | Tkinter Event Field   | Tk   | Tkinter Event Field   |
|======|=======================|======|=======================|
| %f   | focus                 | %A   | char                  |
+------+-----------------------+------+-----------------------+
| %h   | height                | %E   | send_event            |
+------+-----------------------+------+-----------------------+
| %k   | keycode               | %K   | keysym                |
+------+-----------------------+------+-----------------------+
| %s   | state                 | %N   | keysym_num            |
+------+-----------------------+------+-----------------------+
| %t   | time                  | %T   | type                  |
+------+-----------------------+------+-----------------------+
| %w   | width                 | %W   | widget                |
+------+-----------------------+------+-----------------------+
| %x   | x                     | %X   | x_root                |
+------+-----------------------+------+-----------------------+
| %y   | y                     | %Y   | y_root                |
+------+-----------------------+------+-----------------------+


25.1.6.8. The index Parameter
-----------------------------

A number of widgets require "index" parameters to be passed.  These
are used to point at a specific place in a Text widget, or to
particular characters in an Entry widget, or to particular menu items
in a Menu widget.

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.)
   Some options and methods for menus manipulate specific menu
   entries. Anytime a menu index is needed for an option or a
   parameter, you may pass in:

   * an integer which refers to the numeric position of the entry in
     the widget, counted from the top, starting with 0;

   * the string ""active"", which refers to the menu position that is
     currently under the cursor;

   * the string ""last"" which refers to the last menu item;

   * An integer preceded by "@", as in "@6", where the integer is
     interpreted as a y pixel coordinate in the menu's coordinate
     system;

   * the string ""none"", which indicates no menu entry at all, most
     often used with menu.activate() to deactivate all entries, and
     finally,

   * a text string that is pattern matched against the label of the
     menu entry, as scanned from the top of the menu to the bottom.
     Note that this index type is considered after all the others,
     which means that matches for menu items labelled "last",
     "active", or "none" may be interpreted as the above literals,
     instead.


25.1.6.9. Images
----------------

Images of different formats can be created through the corresponding
subclass of "tkinter.Image":

* "BitmapImage" for images in XBM format.

* "PhotoImage" for images in PGM, PPM, GIF and PNG formats. The latter
  is supported starting with Tk 8.6.

Either type of image is created through either the "file" or the
"data" option (other options are available as well).

The image object can then be used wherever an "image" option is
supported by some widget (e.g. labels, buttons, menus). In these
cases, Tk will not keep a reference to the image. When the last Python
reference to the image object is deleted, the image data is deleted as
well, and Tk will display an empty box wherever the image was used.

Ver também:

  The Pillow package adds support for formats such as BMP, JPEG, TIFF,
  and WebP, among others.


25.1.7. File Handlers
=====================

Tk allows you to register and unregister a callback function which
will be called from the Tk mainloop when I/O is possible on a file
descriptor. Only one handler may be registered per file descriptor.
Example code:

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

This feature is not available on Windows.

Since you don't know how many bytes are available for reading, you may
not want to use the "BufferedIOBase" or "TextIOBase" "read()" or
"readline()" methods, since these will insist on reading a predefined
number of bytes. For sockets, the "recv()" or "recvfrom()" methods
will work fine; for other files, use raw reads or
"os.read(file.fileno(), maxbytecount)".

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

   Registers the file handler callback function *func*. The *file*
   argument may either be an object with a "fileno()" method (such as
   a file or socket object), or an integer file descriptor. The *mask*
   argument is an ORed combination of any of the three constants
   below. The callback is called as follows:

      callback(file, mask)

Widget.tk.deletefilehandler(file)

   Unregisters a file handler.

tkinter.READABLE
tkinter.WRITABLE
tkinter.EXCEPTION

   Constants used in the *mask* arguments.
