The PAGE Interface ~~~~~~~~~~~~~~~~~~ This section discusses the menus and several of the windows in the PAGE interface. Again, the PAGE interface is a modified version of the Visual Tcl interface. It was modified because some of the original facilities and features of Visual Tcl are inappropriate for PAGE or because the Visual Tcl documentation is in such a sad state that I do not understand them. Many PAGE parameters are are saved from one invocation of PAGE to the next in the file "HOME/.pagerc". Included are the preferences and the geometry (size and location) of the various windows in the page interface. Start PAGE by executing 'page' on Linux, winpage.bat in a DOS window, or activating the PAGE icon on the Windows desktop. The page and winpage.bat scripts may specify a filename. If the filename includes an extension, it must be ".tcl"; in the case of no extension or a final ".", the extension ".tcl" will be appended to the filename. The user is then greeted with a number PAGE windows and the main menu. The default interface for PAGE presents small font sizes and the Tk default scheme of black on gray. So for my personal use I made the fonts larger and wanted the background color Wheat. See the section on Preferences. Menus ````` The main menu of PAGE contains some of the usual stuff and there is nothing too surprising in the File, Edit, and Window menu. The Window menu does invoke a command console; I have never used it. There are several PAGE windows which popup for various functions and the user can relocate them and change their sizes with the mouse. The Save Window Locations item in the Window menu saves the current locations for future invocations of PAGE. The Option menu has the item "Hide" which "Withdraws a widget from display". Again, I have never used it. The other items are self explanatory. The Widget menu is dynamic depending on the widget selected. Commonly, it allows the invocation of things like the Menu editor, or Page editor for the TNotebook widget. Finally, the Gen_Python menu creates the Python code for the GUI. Let me emphasize that PAGE will contain bugs. So be sure to save often. That is the purpose of the save commands in the File menu. When PAGE starts for the first time, it throws up upon the screen a jumble of windows to be discussed below. You should move them around to better locations, resize them, and then invoke Window->Save Window Location and quit. The next time you start PAGE, they will be where you put them. Of course this can be done anytime. Also, when you Quit PAGE, the current window locations and geometries are saved as default locations. Many of interface elements like the Widget Toolbar, the Attribute Editor, and the Widget Tree can be turned on from the Window item of the main toolbar. Others are invoked from the widget menu after a widget is selected. Widget Toolbar `````````````` The Widget Toolbar is where one obtains widgets for inclusion in the GUI. One begins building a GUI by selecting Toplevel with Button-1 and a blank toplevel window appears on the screen. For other widgets, click on the widget in the toolbar and then click in the parent. The upper left hand corner of the widget appears at the spot where the user clicked. The Widget Toolbar appears below: .. image:: widget.jpg Clicking on the gray bands causes the corresponding section to collapse or expand. Attribute Editor ```````````````` When one selects a widget the Attribute Editor dislays all attributes of that widget. The plum colored fields are not writable the others are. For instance, the Attribute Editor shown below allows one to change the title from "New Toplevel 1" to something more meaningful. That field is used to generate the Python class name for the GUI. .. image:: attribute.jpg There is the Alias field which is writable by the user. The user can provide an alias to improve the readability of the generated code. Widget Tree ``````````` The Widget Tree shows all of widgets created by PAGE and how they are nested within their parent widgets, see below. .. image:: widget-tree.jpg The above tree shows that the selected widget is a Treeview subwidget in the TScrolledtreeview, that it is nested inside the toplevel titled Example. Remember that the Attribute Editor window displays the current attributes of the Quit button. The Widget Tree is a very good place to select a widget with Button-1. If you change an attribute like the text in a button, the Widget tree will not be updated until you hit the update button in the upper left of the Widget Tree. I frequently use this window to select the widget I want to modify and occasionally it fails to select the widget, particularly when doing copy and paste operations. For unknown reasons,if I go and select another widget and then reselect the widget I want it usually works. As described below the Widget Tree is very important when trying to move or select some of the more complex widgets like paned windows or scrolled windows. Bindings Window ``````````````` This window which appears when Bindings is selected from the Widget menu allows one to add one of the possible bindings shown for the widget and to specify the action. In the image below the event has been added for a Button widget and "quit" is specified for the action. .. image:: binding.jpg Menu Editor ``````````` This window easily builds a menu. You can see below an example of its use. .. image:: menu.jpg It is called forth from the Widget menus or from the Attribute editor. I made this menu with weird colors and fonts to confirm that such is possible. There is one thing that is a little strange in the menu editor is that colors like the background color is displayed on the button rather than on the entry field. I may try to run that down in a future release. Function Editor ``````````````` Here is a list of the functions that have been defined for the program. Obviously, the intended function in the original Visual Tcl was to build Tcl functions. Such functions have no meaning for Python. The best place to define your Python function is in the Python IDE that you are using. However, this facility does serve a purpose. It allows you to easily build a skeleton function that are called when you try a test run of the GUI. More on that later. .. image:: function-list.jpg If one selects the left button in the function list, the Function Editor appears. .. image:: function-editor.jpg This is already set up with a skeleton python function named py:xxx. If you then go into the editor and change xxx to the name of the function that you may have specified in a menu, binding, or command attribute, you get the dummy Python function that will be needed to test the GUI. When you have your GUI window and are back in the Python IDE fleshing out your application, then complete the skeleton functions. Class methods are distinguished by having the "self" as the first parameter. The more I use PAGE the less that I use the function editor. The IDE that I use to create the python functions id emacs. Preferences Window `````````````````` The Preferences Window allows one to set some PAGE preferences. I considered removing the Preferences Window completely, but on further thought I realized that the this is indeed a complex subject involving preferences for both PAGE and the GUI generated by page. Please see the section on Preferences. The Colors tab of the Preferences Window is shown below. .. image:: colors.png Python Console `````````````` When the user generates the python module as described above the Python console window appears with the generated code inside the upper text box. It has the following appearance: .. image:: console.jpg The upper text box contains the generated text with a bit of colorization applied. The lower text box contains any generated output from running the source program. The Python Console is a ttk::panedwindow which allows one to move the sash between the two text boxes. To execute the generated Python module, just click on the Run button of the 'Python console'. Unless you have written the necessary functions not much will happen other than providing a preview of the GUI. In version 3.5, I have modified the skeletal function that are generated automatically for callbacks to print the function name in the Execution Output window using the Print function. On Linux or OS X the function name will appear immediately; on Windows, when execution is terminated. The Print function works fine for Python 2.7 or 3.x. See the penultimate paragraph of this section which discusses this more. There are several buttons along the bottom of the window. They behave as follows: + Save - Saves the contents of the upper text box into a file. It also saves the tcl files. + Run - Attempts to execute the source module in the upper text box. It also saves the Python and the tcl files. + Close - Closes the Python console. The upper text box can be modified (edited) by selecting a character position with the mouse and typing. Such changes will be saved with either the Save or Run buttons. As you can imagine the colorization is not fancy. Keywords, comments, and strings are set to distinct colors. The defaults are set to reasonable colors for light backgrounds. One place you may have trouble is with quotes that bracketed by ''' or """. You should start a line with one of these delimiters and end a following line with one. The Run Button attempts a trial run on your GUI. If you have enough skeleton functions and there are no errors in the generated code, you should see the python code executed and the GUI window will appear. From there you close the Python window go back to PAGE and refine the GUI by moving widgets around, adding additional widgets, or changing attributes. A problem was reported when users attempt to resize the window. Changes made in PAGE 3.1 allow the window to gracefully resize. This can be necessary if the screen resolution will not allow the entire window to be displayed. When the window is made smaller, it may appear to loose the Execution pane. However, it can be recovered by moving up the sash of the paned window. When one quits and restarts PAGE after resizing the Python console, the new size will have been saved in ~/.pagerc and used when subsequently invoking the Python console including the placement of the sash. So invoke the Python console, resize it, reposition the sash quit PAGE, and restart PAGE to use the new Python console. Also, scroll wheel support in the Python console has been updated in PAGE 3.1. To use the scroll wheel in Windows one must focus on the desired pane first. In earlier versions, the output from the execution was written to a file and then displayed in the bottom pane when execution terminated. With version 3.5, the Python execution on Linux now communicates with the console through pipes; thus output from the execution now appears immediately in the Execution Output pane. Coupled with a recent change which embeds a print statement in the generated dummy functions, if a user specifies a command for a button, for example, and generates the python and runs it from the Python Console, and selects the button, the name of the command will appear in the Execution Console. See the section "Defining Functions" in Using PAGE. This is useful because no output from selecting the widget means that you have not defined a callback function. Unfortunately, on Windows the name of the command does not appear until the execution terminates. Note also that the print function is not supported in Python 2.6, if you want to run the generated code with the print function in Python 2.6, then it is necessary to have the following statement at the beginning of the file. .. sourcecode:: python from __future__ import print_function Again, I think you should be using a version of Python which is newer than 2.6. Python 2.6 is no longer mentioned on the download page of Python Org or ActiveState; clearly it is time to move on. If you expect the code might be run under Python 2.6 then perhaps the automatically generated print functions should be modified or removed. Color Dialog ```````````` There are many cases where when setting preferences in the Preferences window or attributes for a widget in the Attribute Editor one selects a little button with an elipsis and the invokes a color dialog window: .. image:: colorpicker.png When this window pops up you are given several different ways of selecting a color: + Pick a color in the multicolored window with your mouse. + Enter values in the Red, Green, and Blue entry fields. + Enter values in the Hue, Saturation, and Value entry fields. + Enter an Hex color value such as #f5deb3 in the Color entry field. That is the color wheat. + Enter a color name such as wheat in the Color entry field. I found the color dialog on the web at `Le site de Jack `_. It was very easy to use and allowed me to enter color names, a feature not allowed by the other color picker I found. Colors `````` Since PAGE is aimed at using ttk widgets which will obey the canned themes which are basically black on gray, I want the background of created windows to be gray. Unless you are prepared to work with themes, I recommend that you stay with the tk default colors.