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

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:

  * Modern Tkinter for Busy Python Developers
       By Mark Roseman. (ISBN 978-1999149567)

  * Python and Tkinter Programming
       By Alan Moore. (ISBN 978-1788835886)

  * Programming Python
       By Mark Lutz; has excellent coverage of Tkinter. (ISBN
       978-0596158101)

  * Tcl and the Tk Toolkit (2nd edition)
       By John Ousterhout, inventor of Tcl/Tk, and Ken Jones; does not
       cover Tkinter. (ISBN 978-0321336330)


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
===========================

Esta seção não foi projetada para ser um tutorial completo sobre Tk ou
Tkinter. Em vez disso, pretende ser uma ajuda inicial, 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.


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.


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


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.


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

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

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

O mestre de um objeto está implícito no novo nome dado a ele no
momento da criação. No Tkinter, os masters são especificados
explicitamente.

   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 Definiçã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")


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.


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


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   | Tk   | Campo de Eventos do   |
|      | Tkinter               |      | 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.

Índices de widget de entrada (índice, índice de visualização, etc.)
   Os widgets de entrada têm opções que se referem às posições dos
   caracteres no texto exibido. Você pode acessar esses pontos
   especiais em um widget de texto usando as seguintes funções
   "tkinter":

Índice de widget de texto
   A notação de índice do widget de texto é muito rica e é melhor
   detalhada nas páginas do manual Tk.

Índices de menu (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*.
