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 :ref:`Applications with Multiple
Top-Level 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.

..  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 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 
~~~~~~~~~~~~~~
.. include:: <isotech.txt>

The 8.0 is a major release providing:

+ A first attempt to support ttk themes, but with my tweaks. See
  :ref:`v8`.
+ 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 :ref:`compress`.
+ Changes the code generation for GUI images so that generated GUI
  modules can be executed from arbitrary directories. See :ref:`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 :ref:`color_utilities`.
			 
The 7.4 release:

+ Cleans up color handling and can lead to a "Dark" mode for PAGE. See
  :ref:`dark`. 
+ Supports the location of rc files to be in any writable
  directory. See :ref:`rc`.
+ Added some capability to modify global colors when reopening existing
  projects. See :ref:`reopen_colors`.
+ Includes a new example which shows all of the supported widgets and
  shows some useful tips.  See :ref:`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 :ref:`wt_double`.
+ Implements a search function in Widget Tree.
  See :ref:`wt_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 :ref:`mod_struct`,  :ref:`Applications with Multiple
  Top-Level Windows`, and :ref:`auto_update`.
  However the new formats present some backward compatibility
  questions with existing support modules; see :ref:`compat7`.
+ 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 :ref:`interact`, and :ref:`ae`.
+ Adds support for the ttk::spinbox widget.
+ Modifies the copy-paste to behave more naturally when borrowing
  toplevel windows. See :ref:`borrow`.
+ 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 :ref:`auto_save`.
+ Invocation accepts a nonexistent project name. See 
  :ref:`preferred invocation <fullcmd>`.
+ Expands the documentation to discuss 
  :ref:`setting command preferences<py_cmd>`.
+ 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 :ref:`newmenu`,
+ 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 :ref:`menu`.		 
+ 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 :ref:`section on
  command linkage<cmd>`.
+ 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 :ref:`balloon`,
+ expands again the functions available in multiple selection. See
  :ref:`multiselection`,
+ improves undo.  See :ref:`undo`.	   


The 5.1 release:

+ extends function available in multiple selection. See
  :ref:`multiselection`, 
+ changes the key commands for removing multiple selection
  designation,
+ provides an experimental undo capability for certain operations.
  See :ref:`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
  :ref:`multiselection`,
+ adds the Scrolledwindow widget based on the canvas widget. See
  :ref:`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 :ref:`relative`,
+ corrects some problems with Pane window widgets,
+ changes the way values are specified for Ttk Combobox widgets. See
  :ref:`combo`,
+ 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 "|minus|\ s" to "|minus|\ |minus|\ s",
  and removes the "|minus|\ h" option. Also add new option "|minus|\
  |minus|\ s". See :ref:`rc`.
+ changes validation specification and code. See :ref:`Validation commands
  <entrycmd>`.
+ corrects problem with color of widget handles.
+ corrects problem with resizing notebook widgets.
  See :ref:`Resizing Notebook Widgets <nbresize>`.
+ improves Attribute Editor by not displaying attributes that are not
  changeable.
+ tentively explores the ttkwidgets package. See :ref:`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 :ref:`rc`.

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 -
  :ref:`see the Attribute Editor <propagate>`,

+ 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 :ref:`naming`),

+ adds line numbering to the Python consoles,

+ adds Top button to several PAGE windows,  ...

.. + enables the context menu for Attribute Editor,
  
  
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 :ref:`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.

.. sourcecode:: python

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

.. sourcecode:: python

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

.. It was suggested by Pär Smårs that the generation of winpage.bat with
.. the correct installation directory should be done magically at
.. installation.  With version 4.8.7, I managed to do this.  Since I have
.. a deficient understanding of the Windows world, I decline trying to
.. update the PATH environmental variable.

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.


.. _rc:   
   

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:

.. sourcecode:: python

    alias page="~/page/page"				

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

.. sourcecode:: python

	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:

.. sourcecode:: python


	usage: page [<option>] project_file
      
.. sourcecode:: python

    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.

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

.. sourcecode:: python

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

or on Windows

.. sourcecode:: python

   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:

.. sourcecode:: python

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

.. sourcecode:: python

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

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.

.. image:: paradigm.png
     :align: center		   

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 :ref:`rework` for more discussion of this world view.

.. _projdir:

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:

.. sourcecode:: python

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

.. sourcecode:: python


    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.



.. I have recently received a bug report and example with the claim that
.. it would not execute in 32 bit Windows. Extensive testing revealed
.. that the real problem was faulty specification of a non-ACSII
.. character and when that was repaired the example would run with Python
.. 3 but not with Python 2. SO, if you require non-ASCII characters use
.. Python 3. Reserve Python 2 for legacy programs.

.. Application Distribution and Additional Files
.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. When an application is ready for distribution, there are more files
.. to distribute than the Python files described above.
   
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.

.. image:: overview.png
     :align: center

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

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

..
   
2. Select a desired widget from the Widget Toolbar with Button-1 and
   place it within its parent by clicking Button-1 within the
   parent. One can then use the mouse to move and resize the widget
   (For some of the complex widgets, one has to press the control key
   along with Button-1 to select the entire widget.) Using the
   Attribute Editor, then change any of the attributes of the widget
   including the names of callback functions. It is probably a good
   idea to provide an alias which will make the generated code easier
   to read.


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

..

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

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


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


..
   
7. 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
   :ref:`execute`. 

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
:ref:`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
:ref:`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 :ref:`custom_example`. 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 :ref:`styles`.

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 :ref:`report`.  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.

.. I now believe that the
.. "Theme" part of ttk is really a very poor piece of software at all
.. levels - concept, implementation, and especially documentation. My
.. guess is if it had been well documented it would have been recognized
.. by even the author as junk. I find it hard to believe that the people
.. who control Tcl/Tk allowed it in the code base.


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 :ref:`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
:ref:`borrow`.