Introduction

PAGE is a tool which helps to create Python GUI interfaces using Tkinter and the Tk/ttk widget set. It is a fork or extension of the program Visual Tcl (vTcl) which now produces Python code. PAGE runs on any system with Tcl installed and the generated Python code requires only Python to execute.

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.

Note that some of the screen shots in this documentation may appear with a gray or a wheat background. The reason is that the Tk default color is gray but I prefer wheat. Also, the font size is often large because I prefer nay require large fonts.

Change History

The 5.6 release:

  • fixes a problem with code generation for notebook widgets,
  • fixes a problem with the presentation of the Attribute Editor in Windows,
  • revises the command options. See Initializing and Executing PAGE.

The 5.5 release:

  • fixes a problem with aliases in copy-and-paste operations,
  • adds the capability to revert to default geometries for the principle PAGE windows, see Menu Attributes,
  • fixes problems with opening and saving projects,
  • fixes a problem the Absolute/Relative code,
  • makes minor improvement in the handling of fonts,
  • reworks some of the examples for better presentation across OS’s.

The 5.4 release:

  • changes the Menu Editor to more closely align with Tk menu capabilities. See Menus.
  • fixes a problem with font preferences.
  • adds the Scrolledspinbox widget.

The 5.3 release:

  • fixes the use of arrow keys and extends their usage to changing sashes in paned windows,
  • corrects some problems with paned windows,
  • simplifies the specification of command attributes with arguments by generating lambda functions in some simple cases, See section on command linkage.
  • includes minor changes to the menu editor.

The 5.2 release:

  • fixes the saving of font specification for scrolled widgets,
  • modifies the tooltip support to allow changes from inside the support module. See Balloon Help - Tooltips,
  • expands again the functions available in multiple selection. See Multiple Selection,
  • improves undo. See Undo.

The 5.1 release:

  • extends function available in multiple selection. See Multiple Selection,
  • changes the key commands for removing multiple selection designation,
  • provides an experimental undo capability for certain operations. See Undo.,
  • handles Windows device letters better,
  • improve the resizing of panes in paned windows.

The 5.0.3 release fixes bugs with relative placement and multiple selection.

The 5.0.2 release fixes a busy cursor bug.

The 5.0.1 release repairs a mistake in the release of 5.0 documentation.

The 5.0 release:

  • contains rewrite of the support module update code,
  • fixes problem with aliases of multiple instances of scrolled and custom widgets,
  • adds facility for removing an image from a widget,
  • provides limited functionality for multiple widget selection. See Multiple Selection,
  • adds the Scrolledwindow widget based on the canvas widget. See Scrolledwindow,
  • adds New command to File menu in main menu,
  • extends relative placement to the design phase of GUI development providing a WYSIWYG improvement. See Relative Placement,
  • corrects some problems with Pane window widgets,
  • changes the way values are specified for Ttk Combobox widgets. See Ttk Combobox,
  • improves automatic project saving upon Python generation,
  • improves support for copy-and-paste,
  • adds the busy cursor for some long running operations,
  • moves the python3 examples to the “examples” subdirectory and the previous python2 examples have been moved to the “examples-py2” subdirectory. Python2 examples are no longer being maintained.

The 4.26 release:

  • generates new code for several geometric attributes of toplevel widgets.
  • changes the invocation option “−s” to “−−s”, and removes the “−h” option. Also add new option “−−s”. See Initializing and Executing PAGE.
  • changes validation specification and code. See Validation commands.
  • corrects problem with color of widget handles.
  • corrects problem with resizing notebook widgets. See Resizing Notebook Widgets.
  • improves Attribute Editor by not displaying attributes that are not changeable.
  • tentively explores the ttkwidgets package. See ttkwidgets.
  • corrects several problems with menu generation and saving.

The 4.25.1 release fixes a bug affecting the Python generation for a number of ttk widgets when project have not been saved and reopened before generation of GUI module code.

The 4.25 release

  • makes operation on 32 bit Windows system a whole lot better.
  • enables the opening of project files on drives different from the current drive,
  • improves the “Stash and Apply” to facilitate widget alignment,
  • changes the preferences function has to allow the saving of preferences to a named file.
  • and fixes several bugs.

The 4.24 release includes further corrections for widget images, and font specification. It also facilitates the use of multiple initialization files. See Initializing and Executing PAGE.

The 4.23a release fixes error that prevents code generation.

The 4.23 release fixes several bugs, one related to the Scrolledtreeview, another to code generation in the absence of an IDE specification, and one related to changing relative size attributes in the Attribute Editor. In addition, some aspects of image use has been improved. The font support revealed errors and had to be fixed. Finally, the encoding problems and internationalization was addressed.

The 4.22 release fixes several bugs.

The 4.21 release includes Balloon Help (tooltips) for many of the supported widgets and bug fixes.

The 4.20 release fixes bugs related to the Scale widget and the Scrolledtreeview widget.

The 4.19 release:

  • provides Stash and Apply mechanism for transferring attributes from one widget to others,
  • enables context menus in the Attribute Editor for transferring attributes from one widget to others - see the Attribute Editor,
  • further enhances scrolling of PAGE windows,
  • fixes bugs, some related to color preferences,

The 4.18 release:

  • enhances the Scrolled widgets to support mousewheel scrolling over data windows in generated Python modules,
  • enhances mousewheel scrolling over PAGE data windows,
  • removed some warning messages and added other more meaningful ones,
  • improves the style of the tkinter import statements (see Naming Conventions),
  • adds line numbering to the Python consoles,
  • adds Top button to several PAGE windows, …

The 4.17 release: displays the locked state of a widget in the Attribute Editor, adds a preference for setting the indentation, expands tabs when updating the support module, fixes a subtle bug with placement within labelframe widgets, and enhances the use of geometric attributes in the Attribute Editor.

The 4.16 release fixes an important bug in the support module update feature as well as improving the “Fill Container” function.

The 4.15 release improves the use of the Binding Window, improves the display of callback functions, and the automatic saving of the project file. The ttk::separator widget is added and support of custom widgets expanded. Individual widget geometries can now be locked to prevent mouse changes.

The 4.14 release provides function to save the Widget Tree to a file and function to display callback functions. Fixes are also made for copy and paste as well as to relative placement.

The 4.13 release adds a search function to the Python Consols, fixes a syntax coloring problem, adds additional support for utf-8 encoding, and fixes some bugs.

The 4.12 release fixes several bugs related to placement, cut and paste, and borrowing.

The 4.11 release allows one to copy a menu bar from an existing project to the current project. An important addition is the inclusion of a tutorial written by Greg Walters.

The 4.10 release includes a reuse facility which allows one to copy from existing projects and paste to the current project. This release also modifies the startup to automatically create the Toplevel widget and expands support for the Canvas widget and adds some checking of identifier syntax. In addition, there is a new custom version of the TNotebook widget which incorporates an icon for closing tabs.

The 4.9 release fixes bugs related to state values of several widgets. It also improves the Widget Tree by changing the labels to display the class and the alias of the widget and automatically updating it in more cases.

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.

X 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

Visual Tcl

PAGE is based on Stewart Allen’s Visual Tcl program. In fact, it is vTcl, with modifications and several 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. Ann additional disadvantage is that Windows users probably need to install Tcl/Tk. 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, 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.
  • Fix bugs.

My changes have become so numerous that it is perhaps wrong to call it merely a modification of Virtual Tcl. I now think of PAGE 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 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. Similarly, 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. It is interesting that many people writing about Tk and Tkinter dismiss the placer geometry manager.

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.

I believe that it is a good idea to build the GUI and the support module in a separate subdirectory so the recommended procedure is to create the application subdirectory and make that your working directory.

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

The orthodox view of object oriented programming groups all of the attributes and methods of an object into a single class. I normally follow that dictum. PAGE deviates from that rule in that it places the automatically generated code in a GUI module and relegates the hand-coded event functions to a separate support module. All that PAGE does with the support module is optionally create a skeletal version of that module containing linkages between the two modules and skeleton callback functions. PAGE also can update the support module to the extent of adding skeletons for new callback functions required by rework.

The separation of the two module results from requiring a fool proof method for reworking the GUI. I have found that I am constantly changing the GUI for reasons such as improving its appearance, clarifying its behavior, adding new widgets to support new function, etc.; I call this rework. Once I have researched and written code for the support module, I don’t want to expose that code to some “smart” automation program, even my own, but I still want to use PAGE to update the GUI. Implementing rework requires that PAGE be able to distinguish between automatically generated code, which can be rewritten, and hand written code which must be left alone. The only safe way I could think to do that was to separate the code into two modules. A paramount requirement of PAGE is the preservation of manual code as the user goes around the loop of polishing the GUI design and expanding and testing the application.

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 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 to aid in 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.

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.

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 using the GUI window. The <name> may be thought of as a project name and must be a legal Python identifier because the generated Python code will use <name> in an import statement.

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.

Project Directory Configuration

When dealing with code, one should use a project based approach. It really doesn’t make a difference where you store your code in the grand scheme of things, but each project should be structured in a folder of it’s own. For example:

MyProject
   Images
   Documentation
   code
   ...

Even if you have multiple forms for a given project, all of the code should be contained within the same project folder. Any images/graphics should be kept within a folder under the main folder. Documentation (including change logs, etc) can be maintained in a separate folder within the project.

Versions can be maintained as follows…

Project
   Version 1.x
      Images
      Documentation
      code
      ...

   Version 2.x
      Images
      Documentation
      code
      ...
   ...

This way, base information can simple be copied and modified and maintained.

Python 2 or Python 3

With PAGE, the presence of Unicode characters in project names will require Python 3, because those characters will be used as identifiers in the generated Python code.

Up to this point, version 4.22, all my development and testing has been in Python 2. Since the Python developers have announced the end of support for Python 2 at the end of 2019 and the recognition of internationalization problems, I have decide to shift my focus to Python 3. Primarily that means that I will no longer generate or debug examples in Python 2 and will switch my testing of generated code to Python 3. I have reworked the existing Python 2 examples to function in Python 3. I would not recommend starting new projects in Python 2. Reserve Python 2 for legacy programs.

Python Encoding and UTF-8

I have recently received a bug report and example with the claim that it would not execute in 32 bit Windows. Testing and help from abroad revealed that the real problem was that the encoding of the supplied example was in Windows-1252 also known as cp1252 and Python requires UTF-8. This illustrated a real problem with sharing PAGE projects between countries and internationally. In release 4.23, PAGE has been modified to treat input and output as encoded in UTF-8. That means that when using the Open or Borrow function PAGE will expect the incoming project file to be encoded in UTF-8 and that output files, the Python files, will be encoded in UTF-8.

The simple reasons why everything should default to UTF-8:

  • Python requires UTF-8 and thus, PAGE should deliver UTF-8-encoded files, too.
  • Ansi is not portable at all. Neither for different countries nor for different platforms.
  • Ansi is not able to represent characters that don’t belong to the specific code page.

So, things must be consistent. UTF-8 always and everywhere. That way each character of every language is representable (no loss of data), scripts are portable between different countries and platforms, and scripts don’t cause coding errors in Python anymore.

A Very Short Description of using PAGE

As first steps in using PAGE, I recommend creating a subdirectory to contain the application and all supporting files needed and then making that subdirectory the current working directory.

_images/overview.png

There are three generated files associated with a PAGE GUI. They are a GUI design module also called the project 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 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. Starting with version 4.10, a new toplevel widget is automatically generated. 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.
  1. 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.
  1. Repeat the above step (2) until the GUI is complete.
  1. 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. 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.
  1. 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 and other boiler plate code in a second python module with the same rootname with “_support” appended. 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.
  1. 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 an 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 the 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 project file is saved so that one can come back and modify the GUI. See Rework for details.

Release 4.10 added the capability to paste widgets from existing projects into the current toplevel GUI window. This is a new additional way of selecting and including widgets into the GUI. See Reuse for details.

Status of PAGE

PAGE runs on many operating systems including Linux, Windows, OS X, and most versions of Unix. Recently, it has been running on Raspbian, the Linux derivative for the Raspberry Pi 3.

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 confusing so I skipped them in favor of auto-scrolled widgets like Scrolledlistbox, Scrolledtextbox, and Scrolledtreeview. 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
    • Checkbutton
    • Entry
    • Frame
    • Label
    • Labelframe
    • Listbox
    • Message
    • Popupmenu
    • Radiobutton
    • Scale
    • Spinbox
    • Text

  • Themed Widgets

    • TButton
    • TCombobox
    • TEntry
    • TFrame
    • TLabel
    • TLabelframe
    • TMenubutton
    • TNotebook
    • TPanedwindow
    • TProgressbar
    • TRadiobutton
    • TScale
    • TSeparator
    • TSizegrip

  • Enhanced widgets.

    • Scrolledentry
    • Scrolledlistbox
    • Scrolledspinbox
    • Scrolledtext
    • Scrolledtreeview
    • Scrolledwindow
    • Custom
    • PNotebook

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. Canvas has been extended with the inclusion of the Scrolledwindow widget which is a canvas widget in which a window item has been created at position (0,0). The Scrolledwindow widget is a container for Tk widgets.

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 Widgets. 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 limited.
  • Documentation may be wanting.

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, configuration properties are not available to within PAGE but may be user-manipulated in the support module. With version 4.15 you may have more than one custom widget type per GUI window and you can have several instances of them.

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. Styles and Themes

As conceived Visual Tcl will save executable Tcl files which evolve into the application. PAGE is trying to generate Python applications so the resulting Tcl/Tk design files need not be executable but they definitely are saved and can be loaded into PAGE for rework and backtracking to a previous state. They are the project files referred to below.

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 them 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 10 and on a Mac. It even works on the Raspberry PI.

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. The lack of documentation has left me thrashing. I continue to support ttk because of a few widgets like the paned window, notebook, and treeview widgets which are not in the standard package.

With release 4.2, I have addressed the problem of rework, hopefully, allowing easy tweaking of the GUI without jeopardizing th users hand code. 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.

PAGE allows one to build an application one GUI window at a time, with release 4.10, I have added Borrow functionality which allows one to copy widget specification from existing projects and paste them in the GUI currently under development. See Borrowing Widgets from Existing Projects.

Installation

The required packages for executing PAGE are:

  • PAGE 6 or greater - This is the GUI generator. Actually one should be using the latest version.
  • Python 3.7 or greater.

The packages required for executing the python code generated by PAGE are:

  • Python 3.7 or later. The current version of the Python tkinter package includes the ttk widget set.
  • If JPG images are used to decorate widgets, then the Python Imaging Library is needed. The installation package for PIL is named Pillow.

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 and possibly Pillow.

As of April 2019, I am recommending the use of Python 3.6 or later. This is because Python 2 support ends in 2019. 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 3.

The installations that I am using place the directory containing PAGE, named “page” into the users home directory on Unix-like systems. This directory contains the script “page.py”, which is executed to invoke PAGE on Unix-like systems.

With Windows the “page” installation directory is C:\page. It is recommended that C:\page be added to the environmental variable PATH. The installation directory contains “winpage.bat” which invokes PAGE.

Installation on Linux

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

If you wish to use JPG images then installing three additional packages using apt-get - libtk-img, python3-pil, and python3-pil.imagetk gets things working.

Installation on Windows

  1. Download page-6.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:

start /min   python c:\page\page.tcl %1 %2 %3

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 Windows 7 running under VirtualBox. The default directory for installation is C:\page. If PAGE is installed in a different directory then winpage.bat 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

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

I recommend that the PATH environmental variable be set to include the installation directory. I am not confident in my Windows skills to attempt including that in the Windows installer. If done one can then execute PAGE in any directory with the command “winpage” rather than “C:\page\winpage” or a variation containing the installation directory. Also, things will run more smoothly if there is a defined HOME environmental variable.

At the time of this writing, I do not know how to make the fuction of the Img package available to Tkinter on Windows. Thus Windows users are apparently stuck with limited image formats.

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.

ActiveTcl and Python.
  1. Download page-6.x.x.tgz
  2. Double click on it to expand the zip file.
  3. Move the page folder to your home directory.

Initializing and Executing PAGE

One executes PAGE in Unix-like systems, Linux, OS X, SunOS, etc., by issuing the “python3 page.py” command in the installation directory. If you create an alias such as:

alias page="python3 ~/page/page.py"

then you can execute PAGE in any directory. Be aware that Linux system may have a completely different command with the name “page”. If you issue the command “page” and strange things happen check to be sure you know if our page was executed.

Associated with the execution of PAGE is an initialization file sometimes called an rc file. It contains the initial configuration, i.e color schemes, font preferences, window locations, the Python command name, and many other initial values.

With PAGE the rc is by default the file “.pagerc” located in the user’s home directory. There are times when one wishes to have multiple initial configurations which may be stored by having multiple rc files in the users home directory.

The command for executing PAGE beginning with version 4.24 is:

usage: page <option> <project_file>

where option can be:
    -p <rc_file>    : specifies the rcfile to be used. If absent
                      the rc_file is ~/.pagerc
    -d              : run without using an rc_file. Use default
                      values instead.
    -s              : select the rc_file to be used.
    -h,--help       : display this message and exit.

    and the project_file is an existing project file to be opened.

If you leave out the “-p <rc_file>”, it works just like always calling forth .pagerc as the rc file. You can use any name you want for rc_file and that will be the rc file in your home directory for that run. Specifying “-p gregrc” has the same effect as “-p ~/gregrc”. Consider the following examples:

page -p ~/page-dev/themes-greg/.pagerc themed1

or on Windows

winpage -p F:\darkrc

You set any preferences you want and they will be saved in the current rc file when you quit. If the file does not exist at the start of execution, you will be granted the default values of everything usually stored in the rc file. rc files usually start with a ‘.’ but that is not necessary.

Since an application built with PAGE will involve numerous file including several files including the project file with the “.tcl” extension, the generated Python files, any needed image files, as well as other files needed by the application, it is recommended that one (1) creates a directory to contain them all and (2) makes that directory the current working directory before initiating PAGE. This will also facilitate distributing the application.

Because the Windows PAGE installer sets the working directory for the PAGE icon to the install directory, using the PAGE icon may not be the best way to initiate PAGE. Comments welcome.

In Windows, initiating PAGE by means of the PAGE icon sets the working directory to the installation directory, using the PAGE icon may not be the best way to initiate PAGE. Comments welcome.