Examples
=========================
Examples are the main way that I learned about Tkinter and how to
write code for building GUI's . Unfortunately, it is hard to find
examples. Grayson's book has been an immense help over the years and
more recently the pyttk-samples distributed by Guilherme Polo have
helped greatly. The official Tcl documentation is pretty much limited
to man pages which are of minor assistance in getting started with
Tkinter. The `tutorial on the Tcl Developers site
<http://www.tkdocs.com/tutorial/index.html>`_ only recently included
Python code. Much experimentation was required before I was able to
see a paned window on my screen or a scrolled directory. I have
gathered a number of interesting examples in the examples
subdirectory to help users get going with PAGE.
One may experiment with the examples changing sizes, colors, fonts,
etc. in the GUI modules and they should still work if he does not
regenerate support modules. At least, one can see some of the
possibilities. Of course, I have created some of them like menus in
poor taste just to illustrate some of the possibilities. You may
encounter some difficulties which may be due to the absence or miss
match of fonts, etc. between my system and yours.
Some of the prior examples have not yet been rewritten for
version 7. I will weed out some of the examples that I no longer think
teach much. The examples can be found in <page installation
directory>/examples. The examples that have multiple toplevels, are
collected in page/examples/multi-toplevel-examples and the ones with
custom widgets are in page/examples/custom.
The easiest way to try the examples is to go to one page/examples
subdirectories and (1) run page against the a '.tcl' file in
that directory and (2) execute the generated GUI module.
If you try saving the examples by executing PAGE on the Tcl files be
aware that generating and saving support files will replace the
included support files which will become backup versions and the
functioning of the applications will be lost unless the respective
files are restored.
.. Directory Browser
.. -----------------
..
.. This example contains a scrolled treeview widget that displays ones
.. UNIX directory tree. The source for this example is in
.. examples/directory-tree.py It is a rework of Polo's example to include
.. folder icons which open and close. Polo's example is Based on
.. `bitwalk's directory browser
.. <http://bitwalk.blogspot.com/2008/01/ttktreeview.html>`_.
.. This example, though interesting, was not built using page.
..
..
.. .. image:: dir-tree.png
.. _vrex:
Vrex
----
Vrex is the most important example because it is a useful tool for
composing and testing Python regular expressions. It is located in
<install dir>/examples/multi-toplevel-examples.
In the past I have used a number of regular expressions in Python and
used to great advantage `Visual Regexp
<http://laurent.riesterer.free.fr/regexp/>`__ in composing and testing
those regular expressions and thought that rewriting the program in
Python would be interesting because
* It would illustrate important capabilities of PAGE.
* It would be a useful program in its own right. Indeed, I use it all
the time.
* The original version was written in Tcl/Tk and so uses the regular
expression processing of Tcl which is bound to be slightly different
from that in Python. So an all Python version using the Python
regular expression processing would be true to Python.
* The original program had ZERO documentation. I never could figure
out all of the facilities present. (The most recent version has one
page of documentation.) I wanted a version that I could document.
* Vrex uses two Toplevel Widgets; the main GUI shown below and a
separate window for the help facility.
* This example illustrates several points about PAGE support: Building
menus, using paned windows, text colorization, synchronization
between two scrolled text windows.
.. image:: Vrex_for_Python.png
The main portion of the GUI is a three pane window for entering the
regular expression and sample in the first two and the third pane
presents match results based on the selection of buttons at the
bottom.
Some of the features of PAGE illustrated in this useful program are:
* Scrolled text widgets nested inside of label frames.
* Use of two separate GUI's, one for the main function of the program
and one for a help window.
* Colorizing the text within the scrolled text windows.
Vrex Operation
``````````````
Briefly, Vrex works as follows:
One enters the regular expression under test into the top text box,
and the sample which is the subject of the regular expression match
into the middle text box. One may use the File menu to load files
into the text boxes, one may directly type entries or use the normal
cut and paste facilities of the operating system. The user can also
save the regular expression and sample using the File menu.
* Pressing the Go button causes the match to be attempted. Also,
colorization is applied to both the regular expression and to the
sample. The regular expression is colorized to show the portions of
the regular expression are to extracted individually. And if the
match is successful the corresponding portions of the sample are
displayed in the same colors.
* By selecting one of the row of buttons marked match, 1, 2, ..., 9,
the portions of the sample corresponding to extracted subpatterns are
displayed in the match window.
* You can use the File menu to load to save both the regular expression
and the sample.
* The Quit Button terminates the program.
* The File menu also has a Quit entry that terminates the program.
* The Help menu opens a second GUI containing a ScrolledText widget
which has help information.
The regular expression should be colorized showing the portions to be
extracted in different colors and as well as the matching portion of
the sample.
If you then Select Match, that matching portion of the sample will be
shown in the Match text box. Select 1, and the portion matching the
sub expression will be shown, etc..
You can also load a file into the sample window and thus run the
regular expression against many strings.
.. _widgetdemo:
Widgetdemo
----------
.. image:: widgetdemo.png
This example displays all of the supported widgets and demonstrates
some programming tips and tricks. There is a very helpful readme
file. I highly recommend executing the file widgetdemo.py.
.. _progress:
Progress Bar
------------
The directory, <install
dir>/examples/multi-toplevel-examples/progress_bar, contains two
examples which exemplify progress bars. The first, new, has the
progress bar in a separate toplevel widget, while the other, one,
incorporates the progress bar in the main toplevel. To run the first
use the command "python3 new.py". To run the other use the command
"python3 one.py"
This example shows the usage of the progress bar widget but is included
mainly for illustrating an application with two toplevel windows. It
shows how the main window is able to interact with variables and
procedures in the imported module which actually displays the progress
bar. It also shows how to hide and restore a widget.
Important features illustrated include the creation and destruction of
the secondary top level window and the fact that the main GUI support
code requires access to Tkinter variables defined and manipulated in
the support module of the other, progress bar, window.
Complex
-------
This really isn't much of an example doing nothing but does show
nesting of a paned window inside of a paned window and a notebook
widget nested inside of a paned window. By the way, one can enlarge
the top level window and copy and paste the whole paned window to a
new location.
.. _menus:
Menus
-----
There are two directories page/examples/menu and page/examples/popup
which demonstrate menus.
Menu Directory
``````````````
The menu directory contains a fairly extreme menu bar example. Note, I do not
advocate this as a style to be used; it merely suggests some of the
things that can be done.
While this example works as expected within Linux, Windows does not
preserve the specified fonts, and OS X drops the fonts and the colors; see
:ref:`images from the three OS,s <menu-example>`.
.. _popup:
Popup Directory
```````````````
The popup directory contains a primary example, 'popup' which merely
activates a popup menu which then activates callback functions passing
no arguments to the callback functions. The example has a top level
window with two buttons and a different context menu attached to each.
To see the popup menus click with Button-3 on the buttons. You will
note that the two menus have different colors.
standard.tcl
------------
This is just a top level window with each of the standard Tk widgets
that I support. It just shows that I can generate working Python code
for each. The lowercase 's' emphasizes that it doesn't do much.
themed.tcl
----------
As above for the themed widgets.
Canvas
------
Paul Krieger donated a canvas example which can be found in the
<install_dir>/examples/canvas directory. I am very thankful since I have
no facility with the canvas widget.
.. image:: p-canvas.png
.. .. _wcpe:
..
.. WCPE
.. ----
..
.. See the WCPE directory in the examples directory. This is a program
.. that displays the program of WCPE which is one of my favorite
.. classical music stations. In this example all of the functional code
.. is located in WCPE_support.py and the GUI is defined in WCPE.py which
.. is the main module. I found it very tricky to deal with time zones
.. and did not want to loose any of that code and have to redo it or to
.. deal with diff's; at the same time, I was constantly tweaking the
.. GUI. I generated the import module once and proceeded fill out the
.. "init" function and the callback functions in WCPE_support.py while
.. tweaking the GUI, i.e., changing its location, color, the size of the
.. display fields, and change of some display fields from entry boxes to
.. labels.
..
.. This example requires the Python time zone package pytz which is
.. available from `Python Package Index <http://pypi.python.org/pypi/pytz/>`_.
..
.. .. image:: WCPE.png
..
.. This example utilizes:
..
.. * Labels linked to Tkinter variables to display information like times,
.. composer, artist, etc.
..
.. * A Scrolled text box which displays the whole play schedule for the
.. day and colorizes the current piece and makes sure it is displayed
.. within the window.
..
.. * Busy cursor to alert the user that the application is awaiting
.. playlist information from the web.
..
.. In addition I fuss around with reading and parsing web pages and time
.. zone calculations.
..
.. _double:
Clone
-----
This is a somewhat kooky example located in <install
dir>/examples/multi-toplevel-examples/clone, in which clone.py creates
a GUI which presents a button "Make Two" which cause the creation of
two instances of the "called" widget but with differing
characteristics of location and background colors. The called widget
is then able to create incidences of clones with different locations
and background colors.
There may be a problem executing this example on Windows if fonts
selected in the tcl are not available on the Windows machine. In that
case the font will default to TkDefaultFont.
Note that the command specified in the attribute editor for the Close button
is "self.top.destroy".
Calendar
--------
Small example of building a calendar display . It is located in
examples/calendar subdirectory.
.. image:: calendar.png
CPU Info
--------
Another small example which displays the output of lscpu on a Linux
system. This does not execute properly on Windows machine because it
utilizes a Linux command.
.. image:: cpu-info.png
.. _bind_example:
Bind
----
This subdirectory contains a bind example where the button
responds to selection with <Button-1> via the command attribute
set in the Attribute Editor and to <Button-2> and <Button-3> via
bind commands created using the Binding Window.
The function named in the command attribute is different from that
in the bind statement because in the latter case an event object is
passed as a parameter to the event handler so the handler must have an
argument to accommodate the event object.
.. _custom_example:
Custom Widgets
--------------
.. _lib_demo:
Lib Demo
````````
.. _scrolledlistbox:
ScrolledCheckedListBox
``````````````````````
.. image:: scrolledchecklistbox.png
This annotated example written by Greg Walters is the best example of
the definition and use of a Custom Widget that I have seen. Included
is an extensive write up on usage.
Dual
````
.. image:: dual.png
This directory contains an exeample of a GUI with two different custom
widgets, ScrolledCheckedListBox and ScrolledFrame, which were written
externally from PAGE. The variants are "_d" and "_g" which give rise
to class names "Custom_d" and "Custom_g" in the GUI module and which
are renamed ScrolledFrame and ScrolledCheckedListBox in the support
module.
The ScrolledCheckedListBox was written by Greg Walters and is
borrowed from his ScrolledCheckedListBox example picked up and stuffed
into a new "dual" toplevel widget along with a rehash of my lib_demo custom
widget. My original ScrolledFrame proved to have some problem with the
scroll bars, so I modified it along lines which I borrowed from the
ScrolledCheckedListBox widget. The toplevel also has a menubar
borrowed from lib_demo so the entries apply to the ScrolledFrame.
There is a Tsizegrip widget to facilitate resizing the GUI. The event
'<ButtonRelease-1>' is bound to the Tsizegrip so that when Button1 as
released at the end of a resize, the Custom widget on the right is
refreshed.
You may notice that there is a bunch of special code in
ScrolledCheckedListBox.py to make that custom widget work with both
Windows and Linux.
Tksheet_1
`````````
This example, written by Bill Roberts, employs the tksheet widget as a
custom widget. While tksheet is quite complex, almost 1 MB
in the install directory, very little code was required in the support
module to build this example . The tksheet was created by ragardner
and can be found at
https://github.com/ragardner/tksheet. Unfortunately, the tksheet
package was released with incomplete documentation.
.. image:: tksheets.png
.. _auto_combo:
Tksheet_2
`````````
This is another example using Tksheet_2. This one
is written by Greg Walters.
The tksheet_2 subdirectory also contains an article discussing this
example that Greg has written for FullCircle magazine to which Greg
contributes to on a monthly basis. The article references an earlier
article for FullCircle magazine issue 155 of a more introductory
nature. That article is included in the docs/tutorial subdirectory of
the installation directory.
.. image:: tksheetGUI.png
Autocomplete combobox
`````````````````````
This is another custom widget example written by Bill Roberts
employing the AutocompleteCombobox widget from ttkwidgets. ttkwidgets
can be found at https://github.com/TkinterEP/ttkwidgets. The ttkwidgets package
is documented. See :ref:`ttkwidgets`. This example can be found in
<install_dir>/examples/custom/combobox.
.. image:: autocomplete-combobox.png
.. _cal2:
Calendar2
`````````
This example uses the Calendar widget from the ttkwidgets package.
.. image:: cal2.png
I used the following code in the support module:
.. sourcecode:: python
from ttkwidgets import Calendar
class Cal(Calendar):
def __init__(self, master,):
super().__init__(master,
selectforeground='white', selectbackground='red')
Custom = Cal
To execute this example, you must install the ttkwidgets package.
Two
---
This is an example of a project which contains two simple windows w1
and w2. It issustrates how the support module for window 1 creates
window 2 and passing it a parameter which is used to set a label. It
also has another example of the TProgressbar widget.
Three
-----
This example has three GUI's where The main GUI invokes a second which
invokes the third which sports popup menus bound to the buttons.
.. _rplay:
.. Rplay
.. -----
..
.. .. image:: rplay.png
..
.. This example was written as a music server for my Raspberry Pi which
.. drives my audio system from CD images stored on a Linux box. I use this
.. program daily. In this example I have a number of different bindings
.. and utilize a number of text widget tricks that I discovered by
.. experimentation as well as using multiple threads to run the mp3
.. player while keeping the GUI fairly responsive.
..
.. Labelframe
.. ----------
..
.. Greg Walters contributed this example to help debug the recent fixes
.. to the handling of labelframe widgets.
..
.. .. image:: labelframe.png
..
.. .. _sfimage:
Scrolledwindow
--------------
This examples can be found in the examples/scrolledwindow subdirectory.
This exemplifies the creation of a Scrolledwindow and populates it with
a column of Button widgets.
.. image:: lib_sframe.png
In this example the scrolled window is a tk canvas which I populate
with an array of button, each of which contains an image and each of
which is bound to the same popup menu.
Tip
---
.. image:: tooltip.png
This example has three button widgets one of which, the Dest button
has a tool tip.
When the Change button is selected, The tooltip message is changed and
a tooltip is added to the Quit button.
The addition of the tooltip to the quit button requires access to the
definition of the Tooltip class. The code definition of the ToolTip
class was added to the GUI module because I had specified a tooltip
for the Change button. If Iad not set up a tooltip in the GUI module I
would have had to add that code manually to the support module.
ToolTip Hack
------------
.. image:: TooltipHack.png
This example by Greg Walters shows one how to change tooltip
configuration from inside the support module. Included is very useful
documentation. It is located in the examples/popup directory.
Full Screen
-----------
.. image:: fullscreen.png
This example has a simple GUI. When the generated Python is executed
the toplevel window expands to fill the entire screen. F11 and Escape
keys control whether the GUI occupies the full screen or not as does
the Screen submenu.
Because the GUI is in Relative mode, the size of the text widget and
the widget placement also change correspondingly.
Scrolledlistbox
---------------
.. image:: scrolledlistbox.png
This is another example by Greg Walters.
Plotext
-------
.. image:: plotext.png
This is an example written by Greg Walters demonstrating the plotext
library package which was written to plot data directly on a terminal. This
example shows the use of plotext to plot data in a Scrolledtextbox
widget. This example requires the installation of the plotext package
which can be done with the command "pip install plotext". For more
inforation visit https://github.com/piccolomo/plotext.
This is a replacement of the earlier Plotext example. It illustrates
utilizes new features of the of the Plotext package upgrade.
Show color
----------
.. image:: show-color.png
This example is a tool which I used extensively when make the color
changes since version 7.4. It is located in the color_chart
subdirectory of the installation rather than in the examples
subdirectory.
As a useful tool it is interesing for three reasons:
1. Given a color it shows the hex value of the color, a swatch of the
color, and whether the color is deemed a light or dark color using the
page algorithm. t now also shows the complementary color. the input
parameter is the color name or the six hex digits of the X11 color.
2. I have thought of GUI's primarily as the primary controller of the
program, i.e.,the program throws up a GUI and waits until the user
acts on the GUI such as entering a value in an entry widget, selects a
button, selects a menu command, etc.. In this case, the program is
entered from the command line and a color is given as an argument. For
example, "python3 color_show.py dark green". Then the program does its
thing and the GUI appears with the answer. There are no callback
functions in the support module. I think that this is the only time I
wrote a PAGE program in this way without using callbacks.
3. There is a "Quit" button the GUI that terminates the program and
the associated command is "sys.exit". But sys.exit does not require a
function definition in the support module and so there is no callback
function.
BusyCursor
----------
This example creates a toplevel widget with a Run button. The run
button initiates the callback function run which turns on a busy
cursor, runs for 5 seconds, and finally restores the original cursor.
Treeview
--------
.. image:: treeview.png
This demo shows how to use a ttk::Treeview to present a hierarchical
structure. In this case, it is used to show a folder or directory
hierarchy. This example was written by Greg Walters based on an
example by Guilherme Polo.
PAGE8.0Demo
-----------
This demo by Greg Walters demonstrates some of the new features of
Version 8.0 and discusses some of the tricks that can be used.