Introduction

PAGE is a tool which helps to create Python GUI interfaces using Tkinter and the Tk/ttk widget set. 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.

PAGE 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. It is a good place to start when starting with Tkinter.

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 4.8.x releases fixes bugs and updates the documentation.

The 4.8 release includes support for Custom widgets which are widgets for which the Python implementation is left to the user. Python 3 versions of the examples are included. The widgets handles have been enlarged and colored to facilitate selection. Bugs related to the changing of aliases have been corrected. Finally, a function which expands a widget to fill its container has been added to some widgets I have fixed some bug within the font handling code and that may require that fonts in existing PAGE projects be re-specified.

The 4.7 release includes support for binding events to top level windows and reorganizes the generated code for greater clarity and provides variable parameter lists for the init function in the support module using the Python convention of *vargs, **kwargs. Important fixes for Cut, Copy, and Paste and for the TCombobox widget.

The 4.6 release includes new function. a) Shows generated code in separate console windows. b) Allows loading of consol windows without generating code. c) Allows the opening of user’s favorite IDE with saved versions of the generated code. d) Corresponding changes in the Gen_Python menu.

The 4.5 release incorporates new flexibility for the location of the toplevel widget in the generated GUI using the default location determined by the window manager.

The 4.4.x releases contain bug fixes.

The 4.4 releases supported popup or context menus. Also, support for ttk menubuttons was removed pending more debugging and the Labelframe widget was added. Finally, support for function definition was; however, PAGE still defined skeleton functions as before. The 4.3 release includes code to update an existing support module with Tkinter variables and skeleton functions newly required as a result of Rework.

The 4.2 releases 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. They also provided additional Help and additional scrolled widgets.

The 4.1 releases contains several changes dealing with preferences dealing with font preferences and function to backup versions of the generated GUI.

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

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

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 Tcl/Tk program for generating whole projects in 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. Facilities for testing Tcl programs, for defining functions, and support for multiple toplevel windows, and support for geometry managers other than the placer geometry manager were among those deleted.
  • 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 replace the Visual Tcl splash screen.

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.

PAGE supports 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.

Design Paradigm using PAGE

The PAGE view of the application development process is to build the program one GUI window at a time using PAGE to automate the construction of the GUI window realized in the GUI module and to put all of the supporting application dependent code in a support module. I expect to change the GUI often as I polish its appearance and add widgets, but ideally would only automatically generate the support module once. The difficult coding job should be restricted to getting the application right and not to realizing the conventions of Tkinter. In other words, reworking the GUI appearance should have only a minimum impact on the application code.

PAGE generates a single Toplevel window for use in an application, that is, PAGE generates two Python modules, the GUI module and the support module while preserving the design in the project file.

When building a multiple top-level window application, 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. Generated GUI modules will contain automatically generated functions for creating and destroying them within the modules.

The GUI module contains code to actually cause the GUI to appear on the screen. By interacting with the GUI, the user causes events, such as selecting a button or adding text to an entry, to occur which really invoke callback functions which are implemented as functions found in the support module. Thus, there is a separation between PAGE generated code in the GUI module and developer generated code in the support module. The former is the GUI module and the latter is in the support module. The exception to a complete separation is that PAGE will generate a template for support module containing the linkage between the two modules.

A design goal of PAGE is to allow the user to actually execute and see the GUI before the application is completed. To that end, generation of the support module will provide skeletal functions for the callback functions.

The manual code to support the GUI and realize the application will be written in the support module. A paramount goal of PAGE is that preservation of manual code as the user goes around the loop of polishing the GUI design and testing the application.

If the application requires more than one Toplevel window each is generated by PAGE and linked by import and call statements. This is discussed in later sections.

When one does a save in PAGE, it saves the 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.

The following diagram shows the design/implementation loop supported by PAGE.

_images/paradigm.png

PAGE generates the three files shown above. The two modules on the left are required to realize the GUI window as a Python program. The GUI module as conceived by the author is completely generated by PAGE while the support module will contain all of the hand coded Python required by the application to use the GUI window.

The project file records the GUI window description in the form of a Tcl/Tk module. It serves as input to PAGE for subsequent rework iterations. It is not an executable program.

Every time you make a set of modifications to the GUI design, you will want to generate and test a new GUI module. However, the support module needs to be changed only when GUI modifications refer to new callback functions. There are a couple of additional but infrequent cases as well. (They include the addition of Tkinter variables used by widgets such as Label and a definition of a custom widget.)

The dashed line is meant to convey the idea that you will not want to change the support module each time the GUI design is modified. For that reason PAGE has separate commands for generating the GUI module and the support module. Also, the generation of the GUI module has two variations, complete generation and updating the support module.

The first time that a GUI is designed, one wants to generate both Python modules. The support module will have all the necessary boiler plate necessary to work with the GUI module; i.e., the GUI module and the support module should be an executable program even with no manual code added to the skeletal callback functions.

With subsequent modifications of the GUI, the support module may need to be updated by PAGE only to add skeletal functions for newly referenced callbacks, etc. in the GUI. No code is deleted. Further, backup versions of all generated files are saved.

Please see Rework for more discussion of this world view.

A Very Short Description of using PAGE

_images/page-simple.png

There are three generated files associated with a PAGE GUI. They are a GUI design module, 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 module can be executed from within PAGE to demonstrate the GUI.

Using a drag-and-drop paradigm inspired by 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 saved and executed to verify the appearance of the GUI. The remaining step of writing the necessary code in the support module to realize the function or application behavior of the GUI is left to the user. The rest of this document will expand and exemplify the first two steps of this process.

PAGE generates two Python modules from a GUI specification. The first module, called the GUI module, is the code to create the GUI and is named <name>.py. All the code in this module is generated by PAGE. The other module, termed the support module, named <name>_support.py contains the code that is necessary to complete the function of the GUI. As generated it contains skeleton code for the callback functions named in the course of laying out the GUI, the definitions of required Tkinter Variable classes referred to in the GUI, a default definition of a custom widget, 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. If the “default origin” is YES then the generated window will be placed at the default location as determined by the system window manager, otherwise it will use the coordinates of the current toplevel location.

  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 modules 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 modules are required the Python module for the Python GUI and the Python support module containing callback functions, etc.. First generate the GUI module, you will see a new window, the Python console, where the code can be expected to appear. After saving the GUI module, generate the support module; generation is dependent on the save GUI module. Another Python console will appear containing the support module. Again save the module. Execute the code, 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 module 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.

    As of version 4.6, PAGE can directly open an IDE such as idleX with two windows containing the stored version of the GUI and support module respectively. I want to avoid building an IDE.

  6. Test the GUI, this can be done by selecting the “Run” button in either of the PAGE consoles. This will show the resulting GUI.

With some Tk widgets, variables can be used 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 “Tkinter variables”. PAGE assists by creating the definitions for the Tkinter 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 GUI 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 module 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; they seem great, therefore, they are included.

The supported widgets:

  • Tk Widgets

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

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

    • Scrolledentry
    • Scrolledlistbox
    • Scrolledtext
    • Scrolledtreeview
    • Custom

I have included Canvas in the above lists; however, I have rarely used the canvas widget directly 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 manipulate a canvas widget into your GUI.

With version 4.8, I have include the Custom widget, which allows the user to include his own special widget, provided that he has a Python/Tkinter implementation. See Custom Widget. I added this feature because I want to use PAGE to build a photo album application where I need a scrolling window for displaying photo thumbnail images. I was able to find several such tkinter classes but none that I felt comfortable including as PAGE widgets for any of several reasons such as:

  • I don’t fully understand the code.
  • There is not a corresponding tk implementation which would allow me to incorporate it into Virtual Tcl functions like the Attribute Editor.
  • The one I actually use successfully is alleged to contain bugs.
  • The generality of the widgets may be lacking.

So for users who have a tkinter widget that they want to use, I have implemented the Custom widget which can be placed, sized, saved in the generated tcl file, etc., while the tkinter implementation is added by the user to the support module. Again, any configuration properties are not available to within PAGE but may be user-manipulated in the support module. Further you can use only one custom widget type per GUI window but you can have several instances of it.

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 rework and 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 executing PAGE are:

  • PAGE 3.5 or greater - This is the GUI generator. Actually one should be using 4.6 or greater.
  • Tcl/Tk 8.6 or greater. - 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.

Even though Python will run the tkinter interface to Tcl/Tk, a full installation of Tcl/Tk is required to run PAGE.

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 a Python version 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 which includes Pyttk. I am also recommending the most up-to-date ActiveTcl package. I would recommend that anyone using a package you generate with PAGE be instructed to use Python 2.7 or 3.2 or later.

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 17 which including Python 2.7.6 and for Tcl/Tk 8.6.2. 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 need to install Tcl/Tk 8.6, a good source 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 the subdirectory “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 Windows

Installing PAGE under Windows 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 c:\page\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. If PAGE is installed in a different directory then winpage will have to be changed to reflect the that fact. For instance if it is installed in C:\x\y then the winpage.bat should look like

wish.exe C:\x\y\page.tcl %1

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.