Examples — PAGE 8 documentation

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

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

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

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

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 images from the three OS,s.

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

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

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

## 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 Widgets

### ScrolledCheckedListBox

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

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.

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

### 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 ttkwidgets. This example can be found in <install_dir>/examples/custom/combobox.

### Calendar2

This example uses the Calendar widget from the ttkwidgets package.

I used the following code in the support module:

    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.

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

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

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

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

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

This is another example by Greg Walters.

## Plotext

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

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

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.

Some of the tricks that this demo shows includes

  - demonstrating use of the NotebookTabChanged virtual event

  - a (fairly) simple way to setup and fill a ScrolledTreeview widget

  - demonstrating how to set the background of each tab page in a TNotebook widget

  - demonstrating how to use the count_it class to aid in widget animation