Introduction¶

PAGE is a tool which helps in the creation of 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 Python installed and the generated Python code requires only Python to execute.

Faced with the problem of building a GUI for an application, users will find that PAGE facilitates designing that GUI and building a working skeletal Python program utilizing the Tk/ttk widget set. As of version 7, PAGE supports the design and construction of GUI’s with multiple toplevel windows. See Applications with Multiple Toplevel Windows. Also, PAGE supports design rework to a limited extent. Version 7 is much simpler while supporting expanded functionality compared to earlier versions.

PAGE is aimed at a use who wants to rapidly construct a GUI and is willing to accept the limitations of Tk and the Place Geometry Manager. It is a helper tool. It does not build an entire application but rather is aimed at designing and implementing GUI windows. It is not a Python Interactive Design Environment (IDE). Stated in other words, PAGE generates Python classes which implement GUI windows and also supplies all of the boiler-plate code for execution or instantiation of the GUI objects. If, like me, you have difficulty remembering all the little tricks of getting a GUI to actually appear on the screen, PAGE can show you code that will work.

The author is Donald Rozenberg and the 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 8.0 is a major release providing:

A first attempt to support ttk themes, but with my tweaks. See Version 8 Additions.
Several themes coordinated with PAGE theme support.
Support for copy-paste of menubars from lender project to current project.
Improved support popup menus including copy-and-paste.
Ability to change locations of notebook tabs.

There are known issues with menu editing that will be addressed in a future release.

The 7.6 release:

Adds support for vertical progress bars.
Improves behavior Attribute Editor resizing.
Changes popup (context) menus from root widgets to toplevel widgets.
Extends Tooltip support to allow user specify attribute changes from within the support module.
Corrects some issues with Menu Editor.
Corrects an issue with the borrow facility.

The 7.5 release:

Moves some boiler plate code from the toplevel class definitions to the module level.
Adds function to Widget Tree allowing collapse and expansion of container widgets. See Widget Tree Pruning.
Changes the code generation for GUI images so that generated GUI modules can be executed from arbitrary directories. See Using Images.
Corrects problems with paned window widget.
Improves menu processing.
Makes minor corrections to color handling.
Changes skeletal callback functions to make the output more readable.
Adds a couple of color utilities to help with choosing colors. See Standalone Color Utilities.

The 7.4 release:

Cleans up color handling and can lead to a “Dark” mode for PAGE. See “Dark” mode.
Supports the location of rc files to be in any writable directory. See Initializing and Executing PAGE.
Added some capability to modify global colors when reopening existing projects. See Loading a Saved Project File.
Includes a new example which shows all of the supported widgets and shows some useful tips. See Widgetdemo.

The 7.3 release consists mostly of bug fixes.

The 7.2 release:

Corrects bugs related to the textvariable option with ttk widgets. Requires the user to disregard “::” artifact in Attribute Editor.
Disallows the closing of the Widget Tree by the user.
Now supports a variety of graphical formats including JPEG for most architectures and OS’s.
Uses tk widgets, in place of ttk widgets for dialogues.
Corrects bugs in the update functions.
Corrects bug with selecting TLabel widgets.
Supports selection with Double-Button-1 in Widget Tree. See Double Click with Button1.
Implements a search function in Widget Tree. See Widget Tree Search.

The 7.1 release:

Improves behavior of Attribute Editor.
Corrects bug that prevented creation of popup menus.

The 7.0 release is a major release:

Utilizes new formats for the generated GUI module and the support module which are simpler particulary for multiple toplevel GUI’s. See Module Structure, Applications with Multiple Toplevel Windows, and Automatically Updating the Support Module. However the new formats present some backward compatibility questions with existing support modules; see Major Compatibility Issues.
Changes code for the skeletal callback functions.
Drops Python 2 support.
Updates examples to version 7.
Updates and substantially enlarges the tutorials.
Includes a discussion on migrating projects created in earlier versions of PAGE.
Improves presentation of attribute errors.
Allows user defined names for context menu function names.
Corrects code for using images.
Corrects code in notebook editor.
Improves the handling of text and textvariable interactions. See Strangeness with Text and Variables, and Attribute Editor.
Adds support for the ttk::spinbox widget.
Modifies the copy-paste to behave more naturally when borrowing toplevel windows. See Borrowing Widgets from Existing Projects.
Corrects problems with copy-paste of toplevel menubars and context menus.
Modifies the Widget Tree to behave more naturally when borrowing.
Relegates backup files to the “backups” subdirectoy of project directory.
Adds a preference to add custom sizes to the font selection dialog.
Provides support for the labelanchor attribute with labelframe widgets.
Provides support for inclusion of the post command for the ttk::combobox.
Fixes miscellaneous bugs.

The 6.2 release fixes some bugs.

The 6.1 release:

Implements an auto-save feature. See Autosave.
Invocation accepts a nonexistent project name. See preferred invocation.
Expands the documentation to discuss setting command preferences.
Better handles specification of validation attributes.
Better handles remembering of PAGE window geometry.
Fixes some bugs.

The 6.0 release:

employs a Python wrapper which leads to a much simpler installation process,
improves the error handling and display of PAGE errors,
puts install directory in users PATH for Windows users,
sets working directory of Windows icon to the users Desktop.

The 5.6 release:

fixes a problem with code generation with respect to notebook widgets.
fixes a problem with the Attribute Editor in Windows.

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.

Installation¶

With PAGE 6.0, the way PAGE is installed and invoked has changed. Installation is much simpler than before and avoids the need to separately install Tcl/Tk. In essence, PAGE uses a Python wrapper, that is a minimal Python module which invokes PAGE which remains a Tcl script. The advantage of the new approach is simplicity of installation. There is no longer a need to install Tcl/Tk. The primary disadvantage I see is that the Tcl/Tk included with Tkinter does not support jpeg images. See Using Images. While that support can easily be added to Linux installations, I have not found a way to added additional image support to Windows.

With PAGE 7.0 PAGE ceases to cater to Python 2.

The required packages for executing PAGE are:

PAGE 7 or greater - This is the GUI generator. Actually one should be using the latest version.
I recommend Python 3.6 or greater. The latest version is a good idea.

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

The generated Python modules will execute under Python 3.

One does not require PAGE to execute programs containing GUI’s generated by PAGE. All that is necessary is a Python version which includes the ttk widgets.

The default installation directory is “page” in 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 default PAGE installation directory is C:\page. The installation directory contains “page.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”. Run the configure script.

./configure

Installation on Windows¶

Download page-x.x.x.exe and execute it. This will install PAGE in C:page. As part of the installation “page.bat” is installed in that directory, page.bat is the analog to the “page” script mentioned above. page.bat is a one line file containing:

@start /min   python3 c:\page\page.py %1 %2 %3

This starts PAGE execution from a terminal window. However, problems have been experienced with the command “python3”. Sometimes the command needs to be replaced with python. In my case I installed Python 3.10.8 in my Windows 10 system found that python3 would not work but python3.10 would. Unfortunately, there were no error messages. I have no explanation.

One can install PAGE in any directory and have the icon start the program. The default directory for installation is C:\page.

The installation directory is automatically added to the Path environmental variable at installation. Thus “page” will invoke the program from any directory. The Shortcut icon will use the users Desktop folder as the working directory.

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.

Download page-7.x.x.tgz
Double click on it to expand the zip file.
Move the page folder to your home directory.

Initializing and Executing PAGE¶

It is important that the current directory is the development directory for the application when PAGE is started. A number of users have experienced difficulties because they started PAGE without being in the development directory. Please visit the directory “How To Start PAGE” in page/docs for Greg Walters discussion of our recommended startup procedure.

One executes PAGE in Unix-like systems, Linux, OS X, SunOS, etc., by issuing the “python3 page.py” command in the installation directory.

Running “./configure” in the installation directory creates an executable file “page” in the installation directory. One can then create a shell alias like:

alias page="~/page/page"

Without running configure, you can create a shell alias such as:

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

Either way, 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.

Initialization rc Files¶

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 file is by default the file “.pagerc” located in the user’s home directory. With Linux and UNIX like systems, PAGE determines the home directory from the HOME environmental variable. With Windows, PAGE tries to get the home directory from the HOME environmental variable. If there is no HOME environmental variable, PAGE uses the HOMEDRIVE and HOMEPATH variables.

There are times when one wishes to have multiple initial configurations which are facilitated by having multiple rc files. With version 7.4, rc files are not restricted to the users home directory. For instance, if one wish to have a particular color scheme for a particular PAGE product, he/she may create a custom rc file in the associated project directory. You create a custom rc file by opening PAGE, selecting Preferences from the main menu, and saving the modified preferences wherever you like. The name of the new rc file may be any legal file name, but if you forgo the character “.” and end with “rc”, the -s argument below will work more satisfactorily.

The command for executing PAGE 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 or
    a project file to be created.

The page command will accept a project file name even if the file does not exist as when starting a new project. The project file is of the form “<project_name>.tcl”. Acceptable forms of the project file in the page command are “<project_name>.tcl”, “<project_name>.”, and <project_name>”. It is recommended that the <project_file> be specified because this facilitates the auto-save function.

If you omit the “-p <rc_file>”, it uses HOME/.pagerc as the rc file. Specifying “-p gregrc” has the same effect as “-p ~/gregrc” as does providing the full path of the rc file. If you want to use an rc file in the project data base you may specify “-p ./gregrc”

Consider the following examples:

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

or on Windows

page -p F:\darkrc newGui.tcl

You may 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. By convention rc files usually start with a ‘.’ but that is not necessary; maybe not even good.

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

creates a project directory to contain them all
makes that directory the current working directory before initiating
PAGE. This will also facilitate distributing the application.

Remember, the Windows PAGE installer sets the working directory of the PAGE icon to be the user’s Desktop.

I have just experienced a nasty problem running PAGE in Windows 10. The installation process creates a batch file, page.bat, for the execution of PAGE, the file contains only one line of code:

@start /min python3 "%~dp0page.py" %1 %2 %3

However, I installed a new version of Python, namely 3.10.4, and could no longer execute python3. Assured by knowledgeable friends that this is a well known Microsoftism, I am flummoxed; I don’t know how change the install procedure to discover the version of Python in use and incorporate it into the process. I did discover that the installation did install the file, python3.10.exe, which does execute. So, I manually modified page.bat to be:

@start /min python3.10 "%~dp0page.py" %1 %2 %3

Of course, I will need to do that every time I reinstall PAGE. So I copied page.bat to pg.bat and I can execute PAGE with the command “pg”. I hope that will take care of execution until I install a 3.11 version of Python.

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. In this document, I use the terms “root window” as well as “toplevel” in place of “top-level”.

Visual Tcl¶

PAGE is based on Stewart Allen’s Visual Tcl program. In fact, it is vTcl, with modifications and 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.

An additional disadvantage is that Tcl/Tk only support a limited range of image file formats which does not include JPEG or TIFF.

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.
Facilities for testing Tcl programs, for defining functions, 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 Visual Tcl is virtually nonexistent and that is truly sad but all too common with open source programming.
Fix bugs.
Added new function. As time went on I added more and more new function.

My changes have become so numerous that it is wrong to call it merely a modification of Visual 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.

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 for specifying widget geometry. 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 GUI windows using PAGE to automate the construction of a GUI realized in a GUI module and to put all of the supporting application dependent code in a separate 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 manual coding job should be restricted to getting the application right and not to following the conventions of Tkinter. In other words, reworking the GUI appearance should have only a minimum impact on the application code. The GUI design is preserved in the project file.

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. However, it is a requirement that PAGE be executed in the same subdirectory as any image files allowing the use of use relative file names for image files.

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, skeleton callback functions, and code for instantiating toplevel classes, i.e. making them appear on the screen. PAGE also can update the support module to the extent of adding skeletons for new callback functions required by rework. This update function is described later.

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. With Python 7, PAGE allows one to have multiple toplevel windows in a project module.

The GUI module contains code in the form of Python classes which describes the toplevel widgets while the support module invokes the toplevel classes to actually create the GUI on the screen. By interacting with the GUI, the application 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, although written in Tcl, is not an executable stand-alone script.

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

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 PAGE user 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 import statements.

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. This allows one to verify the appearance of the GUI.

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

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¶

Official support for Python 2 has ended. I have stopped thinking about or accommodating Python 2.

With version 6.0 of PAGE, PAGE is packaged as a thin Python wrapper that invokes the PAGE program which is written in Tcl/Tk. Thus there is the question of which version of Python to use to execute PAGE. I only recommend 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.

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

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 utilizes the GUI and realizes the application. The GUI module and the support module 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 windows from Tk widgets within a top level windows 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, code for creating the toplevel widgets, 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 project file named <name>.tcl.

A user begins by invoking PAGE using the command ‘page’. A new toplevel widget is automatically generated. This toplevel widget is the root window of the GUI. With version 7 a GUI may contain multiple toplevel windows. (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.)

Using Button-1 on the mouse, drag a 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.

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.

Repeat the above step (2) until the GUI is complete.

Add addition desired toplevel windows by selecting the Toplevel entry in Widget Toolbar. It will appear on the screen and one can repeat the above steps to complete the GUI design.

The remaining step is to generate the Python code in new python modules with the 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 complete that.

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.

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

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.

PAGE periodically saves the project file that you are building; this is called auto-saving. Auto-saving prevents you from losing more than a limited amount of work if PAGE or the system crashes. By default, auto-saves happen around every 10 seconds.

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
- TNotebook
- TPanedwindow
- TProgressbar
- TRadiobutton
- TScale
- TSeparator
- TSizegrip
- TSpinbox
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 can be used as 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. It has been replaced with the Scrolledwindow. Other have found Custom widgets useful and have contributed them as examples.

So for users who have a tkinter widget that they want to use, 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. Of course, configuration properties are not available within PAGE but may be user-manipulated in the support module. 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 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, see Reporting Problems. 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 the users hand code. See Rework.

PAGE allows one to build an application with multiple GUI windows; 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. That includes toplevel windows. See Borrowing Widgets from Existing Projects.