Introduction

PAGE is a tool which helps to create Tkinter GUI interfaces for use within Python programs. It is a rework or extension of the program Visual Tcl (Vtcl) which now produces Python code. Faced with the problem of building a single GUI window for an application, PAGE will facilitate designing that GUI window and building a working skeletal Python program utilizing the Tk/ttk widget set. As other windows are required, they are designed with PAGE and incorporated into the application by importing the generated python modules. See Applications with Multiple Top-Level Windows. Also, PAGE supports design rework to a limited extent.

It is aimed at a user who wants to rapidly construct a GUI and is willing to compromise generality for ease and speed of construction. It is a helper tool. It does not build an entire application but rather is aimed at building a single GUI window. It is not a Python Interactive Design Environment(IDE). Stated in other words, PAGE generates a Python class which implements a single GUI window and also supplies all of the boiler-plate code for execution or instantiation of the GUI object. If, like me, you have difficulty remembering all the little tricks of getting a GUI to show up on the screen, PAGE can show you code that will work.

When I first set about building programs that exploited Tkinter, I could not find nearly enough examples. Another way of looking at PAGE is to consider it to be a Tkinter example builder which can build the examples you need to see.

The author is Donald Rozenberg and project page for PAGE is http://page.sourceforge.net/. My email address is Don dot Rozenberg at gmail dot com.

Change History

The 3.0 release was a major revision of PAGE initiated because of the following events:

  • The release of Tcl/Tk 8.5 which includes the ttk widget set. This is a themed widget set containing new core widgets such as notebook, combobox, treeview and progressbar widgets. Further, the themed feature allows the same design look natural on Linux, Windows, and OS X.
  • The advent of a new version of Visual Tcl upon which PAGE is built. The new version provides an improved user interface.
  • I have realized that some of the bells and whistles that I included before are superfluous or perhaps error prone.
  • Although relative placement was incorporated in the previous version, it added to the desirability of making a major revision because some Tix widgets had some problems when stretched. I want to thank George Tellalov for his suggestions and encouragement regarding this feature.
  • The Pyttk package by Guilherme Polo showed me how to create scrolled versions of text boxes and list boxes in a very transparent manner.

Thus, a fairly complete set of widgets is now supported without recourse to the Tix package or other packages, resulting in a great simplification of the installation process, particularly installation on Windows.

The 4.0 release contains sufficient advances including:

  • Significant improvements in the specification and clarity of Preferences.
  • Significant work with color and associated connections with styles. Emphasis on readability of generated style code. Unfortunately, this seems to work better with Linux/Unix systems than with Windows or OS X.
  • Better support for OS X.
  • Better support for the Scale and TScale widgets.
  • Better support for Toplevel widgets. You can now change attributes; background and cursor, for example.
  • Corrected problems with the TMenubutton.
  • Shifted emphasis to Python 2.7 from 2.6.
  • Added the ttk::sizegrip widget.
  • Fixed numerous bugs.

The 4.0.1 release incorporates bug fixes to font handling.

The 4.1 release contains several changes including:

  • Modified the GUI fonts preferences window to allow the user to specify Tk default fonts by name.
  • Changed the header of the generated Python to remove the python coding comment that seems to have caused some problems.
  • Changed the import statement in the boiler plate code of the Python GUI to look a bit more elegant.
  • When Python GUI code is generated, several existing versions are saved with the added extension ”.bak”. Five existing versions will be saved.

The 4.2 release has new function which aids Rework. This is a fairly extensive departure from the previous workings of PAGE. Additional examples were added to illustrate some aspects of the rework scheme.

The 4.2.2. release adds a Help menu to the main menu and can open the html documentation in the default browser. Also, some window titles have been cleaned up.

The 4.2.3 release corrects the bugs with saving files and makes that process more regular.

The 4.2.4 release corrects a bug in the generation of the support module and the winpage.bat file.

The 4.2.5 release adds the Scrolledentry and the Scrolledcombo widgets and corrects some problems with the generation of bindings for scrolled widgets.

The 4.3 release includes code to update an existing support module with Tk variables and skeleton functions newly required as a result of Rework.

The 4.3.1 release contains bug fixes; corrections to the generation of relative addresses for images and to the set variable and similar windows.

The 4.3.2 release replaced the color picker with tk_chooseColor. The former color picker had internationalization issues.

The 4.4 release supports popup or context menus. Also, support for ttk menubuttons has been removed pending more debugging. Finally, support for function definition has been removed; however, PAGE still defines skeleton functions as before.

Review of X Window Concepts

Let me review some X window definitions and concepts in order to avoid confusion with the terms used here, including top-level window. Some of this information is taken from “Tcl and the Tk Toolkit” by John K. Ousterhout. “The X Window System provides facilities for manipulating windows on displays. ... Each screen displays a hierarchical collection of rectangular windows, starting with a ‘root window’ that covers the entire area of the screen. The root window may have any number of child windows, each of which is called a ‘top-level window’. An X application typically manages several top-level windows, one for each of the application’s major panels and dialogs.” One can also speak of an application’s ‘root’ top-level window. This is the terminology from Grayson’s book. John Grayson’s “Python and Tkinter Programming”, Manning, 2000

In building a multi top-level window example, I recommend that one use PAGE to build the ‘root’ top-level window and then use the corresponding generated Python module as the basis for the main module of the application. When one needs additional top-level windows, use PAGE to specify them and use that code as additional modules for the application which can be imported as needed. They will contain automatically generated functions for creating and destroying them within the modules.

When one feels confident in using PAGE, he looks at the code patterns generated by PAGE and modifies the code for effects not anticipated in PAGE. The thought behind PAGE is that there is a large and intimidating body of information needed to start building a GUI and getting it to actually appear on the screen. PAGE encapsulates that information and produces working code. At that point the user can see and understand the code patterns and can easily customize and extend the code.

Visual Tcl

PAGE is based on Stewart Allen’s Visual Tcl program. In fact, it is vTcl, with modifications and two additional modules that generates Python code. And yes, it is written in Tcl! Why not? Tcl is a great language to have available on your machine. It has features which I would like to see in Python. There are many great programs written in that language. Further, it leaves the door open to use the same techniques for GUI builders in other languages which support Tk. The disadvantage of using a Tcl implementation is that one is restricted to widget sets which are available to both Tcl and Python. In previous versions of PAGE, I supported Tix widgets to provide a comprehensive widget set. With the arrival of ttk widgets in Tcl/Tk 8.5, I felt that the ttk widget set was sufficient and dropped Tix.

PAGE is a modified version of Visual Tcl. Visual Tcl is a interactive program for generating whole projects based on Tcl/Tk. Building PAGE, I added the feature of also generating a Python program which realizes the same GUI. My changes were primarily to:

  • Add the modules which generate Python code.
  • Add support to Visual Tcl for the ttk widget set as well as scrolled versions of several widgets like listbox, textbox, and treeview.
  • Aim the program to handle only one top level window. I ditched the whole window project orientation.
  • Simplify the interface to only support the needs of one building Python interfaces.
  • Write some documentation and comments for the program. Documentation of Virtual Tcl is virtually nonexistent and that is truly sad but all too common with open source programming.

My changes have become so numerous that it is perhaps wrong to call it merely a modification of Virtual Tcl. I rather have begun thinking of it as a fork which will probably be of little interest to the maintainers of Vtcl nor should they be saddled with any responsibility for the state of my version. Since I have diverged so much from Visual Tcl, I have decided to drop the Visual Tcl splash screen.

When one does a save in PAGE, it saves the constructed design as a tcl file which then can be used as an argument to PAGE allowing one to modify or augment the GUI. Even more important, if PAGE screws up it can be used to restart the process at the point where the GUI was saved. So, save often. The tcl GUI design file is not an executable stand-alone script. It contains tcl/tk code and is used as the argument of the tcl source command.

I was looking at different GUI generators for Tcl/Tk with a view of converting the output of one to Python when I came across Visual Tcl and the work of Constantin Teodorescu in generating Java from Visual Tcl. I thought if one could automatically generate Java, it should be even easier and much better to generate Python.

I believe that Stewart Allen wrote Visual Tcl in the 1996-1998 time period to aid in the development of Tcl/Tk applications. Constantin Teodorescu modified vTcl to generate Java code using SWING as the widget set. Looking at the Java generator convinced me to try doing PAGE. I was able to discern its behavior in spite of the nearly total lack of documentation, usually finding an existing procedure when needed.

Basically, I support only the placer geometry manager. In the past, I worked with Visual Basic and the placer geometry manager seemed comfortable and got me useful results. As further justification, Constantin Teodorescu also limited the Java generation to the placer geometry manager. It seems really natural with the drag and drop paradigm. One disadvantage is that some of the sizes could be wrong if fonts change. This is because several Tk widgets have sizing based on font parameters. This has implications if the GUI is generated with different fonts or resolution than are active during execution. There may also be similar problems if the generated GUI is moved to other platforms or environments.

A Very Short Description of using PAGE

There are three generated files associated with a PAGE GUI. They are a GUI design file, a Python GUI module which contains generated Python code for instantiating a class which displays the defined GUI and a Python support module which is a skeleton for the code written outside of PAGE which realizes the function of the GUI. The GUI module and the support can be executed from within PAGE to demonstrate the GUI. Using a drag-and-drop paradigm similar to that of Visual Basic, one constructs or designs the GUI window from Tk widgets within a top level window and modifies the attributes appropriately, when satisfied the user then issues commands to create the GUI module and the support module. Those modules are displayed and may be executed to verify the appearance of the GUI. The remaining step to write the necessary code in the support module to realize the function or application behavior of the GUI. The rest of this document will expand and exemplify the first two steps of this process.

PAGE generates two Python files from a GUI specification. The first file is the code to create the GUI and is named <name>.py. All the code in this file is generated by PAGE. The other file named <name>_support.py contains the code that is necessary to complete the function of the GUI. It contains skeleton code for the callback functions named in the course of laying out the GUI, the definitions of required Tkinter Variable classes refereed to in the GUI, and finally the necessary linkage between the two modules. The GUI design specification is captured and saved for later use in reworking or modifying the design in the file named <name>.tcl.

A user begins by invoking PAGE using a script, ‘page’ in linux. You get a new toplevel widget by selecting Toplevel in the Widget Toolbar with Button-1. This toplevel widget is the GUI window. (In this manual, I use the terms Button-1 and Button-3 rather than left button and right button because a user may be using a left handed mouse. This is consistent with Tcl documentation. Button-1 is under the index finger.)

  1. Using Button-1 on the mouse, drag the toplevel window to where you want it and resize it appropriately. Change attributes such as title as desired using the attribute editor.
  2. Select a desired widget from the Widget Toolbar with Button-1 and place it within its parent by clicking Button-1 within the parent. One can then use the mouse to move and resize the widget (For some of the complex widgets, one has to press the control key along with Button-1 to select the entire widget.) Using the Attribute Editor then change any of the attributes of the widget including the names of callback functions. It is probably a good idea to provide an alias which will make the generated code easier to read.
  3. Repeat the above step (2) until the GUI is complete.
  4. The remaining step is to generate the Python code in new python files with the same root name based on the root name the “tcl” file. This is done by selecting commands ‘Gen_Python’ in the submenu in the menu bar of the main window and generating the Python code. Two Python files are required the Python file for the GUI and the Python support module containing callback functions, etc.. You will see a new window, the Python console, where the code can be expected to appear. Save the code. Execute the code, if you have generated both the GUI module and the related support module, to preview the GUI. It only shows the GUI, it is not the complete application; you have to write that.
  5. Create the necessary Python functions to realize the function of the application. PAGE will facilitate this by generating skeleton functions for any functions named as callback functions in command attributes. The second python file with the same rootname with “_support” appended is also generated from the “Gen_Python” item in the main menu. It will contain skeleton functions named as callbacks in the GUI and definitions for Tkinter variables also referenced in the GUI.

With some Tk widgets, variables can be used with most entry widgets to track changes to the entered value. The Checkbutton and Radiobutton widgets require variables to work properly. Variables can also be used to validate the contents of an entry widget, and to change the text in label widgets. When using those widgets in Python-Tkinker programs it is necessary to use “Tk Variable Classes” - BooleanVar, DoubleVar, IntVar, and StringVar - which create variable wrappers that can be used wherever Tk can use a traced Tcl variable. In this document I refer to these classes as “Tk variables”. PAGE assists by creating the definitions for the Tk variables as well as instantiating the classes. See effbot website for additional information. PAGE attempts to help by supplying boiler plate to define and instantiate the required classes.

When the code is saved or the File->Save is invoked, a Tcl design file is saved so that one can come back and modify the GUI. As of version 4.2 with its emphasis on rework, PAGE creates a supporting function containing the skeleton functions, required Tkinter variables, and the required linkages. See Rework for details.

Status of PAGE

PAGE supports many of the Tk widgets and many of the ttk widgets, other widgets seem to be of lower priority to me; creating scrollbars and linking them with text boxes and the like seemed to be confusing so I skipped them in favor of auto-scrolled widgets like scrolled list box, scrolled text box, and scrolled tree. Though not directly implemented in the ttk widget set, Guilherme Polo in his Pyttk samples shows how to easily implement them; therefore, they are included.

The supported widgets:

  • Tk Widgets

    • Toplevel
    • Frame
    • Message
    • Canvas
    • Entry
    • Listbox
    • Text
    • Checkbox
    • Radiobutton
    • Scale
    • Spinbox
  • Themed Widgets

    • TButton
    • TCombobox
    • TEntry
    • TLabel
    • TLabel
    • TLabelframe
    • TMenubutton
    • TNotebook
    • TPanedwindow
    • TProgressbar
    • TRadiobutton
    • TScale
    • TSizegrip
  • Scrolled widgets.

    • Scrolledlistbox
    • Scrolledtext
    • Scrolledtreeview
    • Scrolledentry
    • Scrolledcombo

I have included Canvas in the above lists; however, I have never used the canvas widget and do not fully understand its use or programming. I am concerned that its programming is so general that I cannot usefully help with PAGE. It is there and Page will place a canvas widget into your GUI.

One of the important features of the ttk widgets is the ability to generate and modify themes. Unfortunately, PAGE provides only rudimentary facilities for manipulating themes. See a later section on Styles and Themes.

As conceived Visual Tcl will save executable Tcl files which can be opened from the file menu or specified as arguments. PAGE is trying to generate Python code so the resulting Tcl/Tk design files are not executable but they definitely can be saved and loaded into PAGE for backtracking to a previous state.

Knowing that I should have tested more, written more, and included more widgets and more examples, I apologize. If you come across bugs or have comments please let me know and I will fix it if I can. I can be reached at [don {dot} rozenberg {at} gmail {dot} com]. Please report problems and suggestions to me, it is the best way to help PAGE to be as good as it can be. I have mainly developed PAGE on linux but I have done some testing of PAGE on Windows XP and on a Mac using Snow Leopard.

While it seems prudent to advise users to keep it simple, take a look at examples/complex.py where I have paned windows nested inside pane windows and a notebook nested inside a nested paned window.

For release 4.0, I spent about two months working with the “Theme” part of Ttk and have had only partial success. I now believe that the “Theme” part of Ttk is really a very poor piece of software at all levels - concept, implementation, and especially documentation. My guess is if it had been well documented it would have been recognized by even the author as junk. I find it hard to believe that the people who control Tcl/Tk allowed it in the code base. I continue to support ttk because of the paned window, notebook and treeview widgets.

With release 4.2, I have addressed the problem of rework, hopefully, allowing easy tweaking of the GUI without jeopardizing custom coded support functionality. See Rework.

I am not happy with the menubutton support, I will revisit it in a future release. So far I have not found it to be a useful widget in any of the GUI’s that I have created; I would appreciate comments about that.

Installation

The required packages for PAGE are:

  • PAGE 3.5 or greater - This is the GUI generator. Actually one should be using 4.3 or greater.
  • Tcl/Tk 8.5 or greater. - The is first version of Tcl/Tk to contain the ttk widgets. I am using Tcl/Tk 8.6.1. Tcl/Tk is required for executing PAGE. Tcl/Tk is required because PAGE is written in Tcl/Tk. Actually one should be using 8.6 or greater.

The package required for executing the python code generated by PAGE is:

  • Python 2.7 or greater. This version of Python includes the ttk widget set.

One does not have to install Tcl/Tk or PAGE to execute programs containing GUI’s generated by PAGE. All that is necessary is Python 2.7 which includes the ttk widgets.

Since Python 2.6 had its last release scheduled for October 2013, I am now only supporting Python 2.7.3 which includes Pyttk. I am also recommending the ActiveTcl 8.6.1 package. I would recommend that anyone using a package you generate with PAGE be instructed to use Python 2.7 of 3.2.

The installations that I am using place the directory containing PAGE, named “page” into the users home directory. This directory contains the script “page”, which is executed to invoke PAGE. The script “page” is altered to reflect the locations of “wish” the Tk interpreter, and the location of the PAGE directory. This alteration can be performed manually or by execution the “configure” script in the PAGE directory.

The package contains the file “configure” which when executed will create “page” a script for executing PAGE. It is executed in the page directory and its function is to:

  1. Determine the full path for wish (first trying for wish8.6 and then wish8.5) and embedding that path as a variable in the page script.
  2. Setting the full path of the page directory as a variable in the page script.

If it completes setting up both one can then copy the page script anywhere in the file system and execute it. It looks in just a few places for wish and so may not find where you have installed it. It does look in the default location for ActiveTcl-8.6 (/opt/ActiveTcl-8.6/bin). If it fails to find a version of wish that has been installed on your system, then manually edit the page script.

With the release of PAGE 4.0, it is necessary to remove any ”.pagerc” which you may have because the new preference code may not work with a ”.pagerc” created with an older version. Also, existing ”.tcl” file created with an older version of PAGE may not work. At this point, the release of version 4.0, I will only entertain bug reports which can be recreated using Python 2.7, Tcl/Tk version 8.6, and PAGE 4.0+.

Installation on Linux

I am now running Mint 13 which including Python 2.7.3 and for Tcl/Tk 8.6.1. I am using the ActiveTcl distribution for Tcl/Tk. This is what I recommend. Current Linux distributions like Ubuntu and Mint include Python 2.7 and Tcl/Tk 8.5. So I have installed ActiveTcl-8.6.1 on my system.

In the past I have found that building and installing both Tcl and Python from source was quick and straight forward. Just install Tcl/Tk before building Python.

If you want Tcl/Tk 8.6.1, a good possibility is the ActiveState binaries for Tcl, which is what I am using.

The steps for installing PAGE are:

  1. Untar the distribution file in your home directory. You can probably use ‘tar zxvf pageXXX.tgz. This will put all the distribution in /page.
  2. Run “configure” in the installation directory, it generates the script “page” which can invoke PAGE. You may want to insure that the script “page” is in your execution path. If the script fails, manually edit the version of the page script from the installation, see configure command.
  3. Remove any ”.pagerc” file.

Installation on Win32

Installing PAGE under Win32 is considerably easier than with early versions.

  1. Obtain and install the most recent version of ActiveTcl; use the 8.6 version.
  2. Obtain from http://www.python.org the windows installer for the most recent version of Python and install it. If you install 2.7 or later, or 3.1 or later you will be fine.
  3. Download page-4.x.x.exe and execute it.

winpage.bat is the analog to the “page” script mentioned above. winpage.bat is a one line file containing:

wish.exe page.tcl %1

With Version 4.2.2, it is now feasible to install PAGE in any directory and have the icon start the program. This has been tested on a very old machine running XP. The default directory for installation is C:\page.

Installation on OS X

I have not done much with PAGE on OS X. However, several users, including Kent Fox, have tried PAGE on OS X and have convinced me that I should try to support PAGE on that system. However, the implementation of ttk with respect to color on OS X doesn’t seem very satisfactory to me so I recommend sticking with default colors.

  1. Obtain and install the prerequisites, the most recent versions of ActiveTcl and Python.
  2. Download page-4.x.x.tgz
  3. Double click on it to expand the zip file.
  4. Move the page folder to your home directory.
  5. Execute the configure file in the page folder.