|
|||||||
|
|
|
|||||
|
|
|||||||
tkBuilder Version 1.0.2 (Beta Release 1)
Copyright © 1999, 2000 Frank Schnekenburger
Built at Sawpit
e-mail: sawpit@yahoo.com
http: sawpit.iwarp.com
Check out tkBuilder's New Features
Join the tkBuilder Users Group
Check out Quick Tips
To Marilyn, who showed me the Perseids.
tkBuilder is a tool designed to facilitate the construction and testing of interfaces using tcl/tk. It is chiefly a tool for managing the widget hierarchy; it is not a GUI builder in the sense of products like Visual Basic. tkBuilder gives you the ability to:
tkBuilder is written in tcl/tk, and runs under tcl/tk 8.0.4 or later.
tkBuilder is distributed free of charge under the terms of GNU General Public License (see License).
tkBuilder Version 1.0.2 (Beta Release 1)
Copyright © 1999, 2000 Frank Schnekenburger
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program in the file '_GPL.txt'; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
tkBuilder is built with tcl/tk. Many thanks to those involved in its development.
The tkBuilder interface includes widgets provided in the following excellent packages:
Many thanks to following for feedback, suggestions, bug reports, and/or reviews:
We'd appreciate bug reports, comments and suggestions for improving tkBuilder and its documentation. To contact us, send e-mail to sawpit@yahoo.com.
We maintain a tkBuilder Users Group mailing list. Group members automatically receive the latest news on upgrades, bug reports, tips and faqs. To be added to the list, send a message to sawpit@yahoo.com, with the text 'subscribe tkBuilder' in the subject of the message.
tkBuilder is coded in pure tcl/tk (version 8.0.4) and is distributed as a set of tcl files zipped into the file tkBuilder1.0.2.zip (for Windows) and the file tkBuilder1.0.2.tar.gz (for UNIX). The distribution includes the tcl files for the BWidget and combobox packages. To install tkBuilder, unzip the distribution file; to run tkBuilder execute the tcl script 'tkBuilder.tcl'.
New features added to Version 1.0.2 include:
The base (root) of each widget tree is the Project. The root object of Version 1.0.1 is now called Main Window in Version 1.0.2, and is treated much as other toplevel objects (see Main Window).
Version 1.0.2 of tkBuilder can read project files created with version 1.0.1. Project properties (e.g. resources, packages, namespaces) are now part of the project (rather than options as in version 1.0.1). These will have to be entered in the project's properties forms (see Project). Projects saved using version 1.0.2 cannot be read using version 1.0.1.
Some terminology used in tkBuilder is given here by way of a sample widget hierarchy:
.frame1
.frame1.button1
.frame1.button2
.frame1.frame2
.frame1.frame2.button1
.frame3
The path name of a widget is its fully qualified tcl hierarchical description, e.g., .frame1.frame2.button1. Each widget must have a unique path name. The widget name of a widget is the last word of its path. For example, button1 is the name of widget .frame1.frame2.button1. Two or more widgets may have the same widget name as long as they all have different path names (e.g., .frame1.button1 and .frame1.frame2.button1). This distinction is important: As you build a widget hierarchy with tkBuilder, you will specify widget names, not path names. Path names are implied by the position within the hierachy in which you insert widgets.
A tree is the entire widget hierarchy. A branch refers to a widget and all its descendants. A branch can range in size from a single widget to the entire tree. A tree has as many branches as it has widgets, since each widget is the start of a branch.
All widget trees start with project as the first node (this is the '.' of the tcl widget hierarchy). The project node has only children widgets; it cannot have a parent or sibling widgets.
The display of tkBuilder is divided into two halves: the widget tree on the left and the properties forms on the right.
The widget tree displays the current hierarchy of the widgets in a tree diagram. Each node on the tree represents a widget and shows the widget name, and optionally the widget class icon, widget class name, geometry manager of the widget and set variable name. Use the View menu to toggle these items on and off.
The properties forms consist of five tabbed forms: attributes, layout, bindings, general, and special. These forms are used to enter the properties of each widget. The forms display the properties of the widget currently selected (highlighted) in the widget tree.
The display includes a Main Toolbar, Widget Toolbar, Tool Tips, and Status Bar which can be toggled on and off in the View menu.
The widget tree is managed using the widget menu. It allows you to perform operations that affect whole widgets, including the ability to insert, duplicate, copy, delete and rename widgets. Select Widget from the menu bar or right-click on a widget name in the tree.
Inserting Widgets. A widget may be inserted into the widget hierarchy as the parent, sibling or child of the current widget. Select Insert from the widget menu to display a menu of the available tk widgets. In addition, you can insert registered widgets (More), special objects (Special), and tkBuilder megawidgets (Megawidget...).
Duplicating Widgets. To create a new, identical and independant copy of the current widget or branch, select Duplicate Widget or Duplicate Branch, respectively. The new widget will be a sibling of the copied widget.
Deleting Widgets. Use Delete Widget to delete a single widget from the tree if it has 0 or 1 children; if it has 1 child, that widget takes its place in the tree. You cannot delete a single widget that has 2 or more children, as parentage becomes ambiguous. To delete the current widget and all its descendants, select Delete Branch.
Copying Widgets. To copy the properties of the current widget to other widgets of the same widget class (e.g. button), select Copy To Siblings or Copy to Descendants, to copy to siblings or descendants, respectively. All properties in the attribute, layout and binding forms of the copied-to widgets are overwritten with those of the widget being copied. Properties on the general form are not copied.
Renaming Widgets. Select Rename to change the name of a widget; changing a widget name has no affect on its properties or position in the tree.
You can move a widget or branch from one point to another. To move widget X, left-click and drag it to widget Y and select its new relationship with widget Y (sibling or child). To move widgets using default relationships, select Use default relationship when moving widgets from Tools-Options-General.
All descendants of widget X are moved with it. Moving a branch does not change the widget names, properties or widget hierarchy of the branch. However, the path names of widgets in the branch will change, reflecting their new position within the tree.
You cannot move a widget onto its own branch. You cannot move the project widget.
Widget properties are specified in the property forms:
The forms always display properties for the currently selected widget.
The attribute form allows you to set the attributes of the current widget. For attributes that take colour values, you can click on the colour box of the attribute entry to open the colour selector dialog box.
You can hide attributes that you never or rarely use; goto Tools-Options-Attributes and select those you wish to hide. Values specified for hidden attributes are remembered, and displayed again when the attributes are shown. To temporarily show all hidden attributes, select Show hidden attributes. To include the values of hidden attributes when building a branch, select Build with hidden attributes. This functionality is also available from the Properties menu.
Be careful when showing hidden attributes. If you are showing hidden attributes, but not building with them, you may make changes to attributes that seem to have no effect when you build. To avoid confusion, its generally best to work with hidden attributes not shown.
The layout form allows you to select a geometry manager and set the geometry options for the widget. During a build, tkBuilder will warn you if you try to both pack and grid siblings.
The binding form allows you to define commands that are associated with events on the widget. A command must be a single argument (e.g. "puts $myVar" and {set ::x 5} are ok, but set ::x 5 is not). A command can span any number of lines, as long as it forms a single argument.
You can add events to a widget by selecting Insert Event from the Properties menu. The event is only added to the current widget. You can delete one or more events from the current widget by highlighting them and selecting Delete Event from the Properties menu. Note that this is different than hiding attributes; once deleted, an event and any code associated with it are destroyed; you can insert the event again, but you will have to re-enter its code.
When a new widget is created, it is assigned a list of default events. You can edit this list by going to Tools-Options-Bindings. Changes made to this list do not affect existing widgets.
Bindings for canvas objects require special consideration.
The general form allows you to specify a number of other properties for the widget; all of these properties are optional:
Set Variable Name. This is the name of the variable that will be assigned the widget path when the widget is built. For example, in the code set myVar [frame .myFrame], myVar is the set variable name. This variable name is then available for use in descendants of the widget.
Use set variable name in path of descendants. If this option is selected, the path of the widget is replaced with its variable name when building descendants. This option is applicable only if a set variable name has been specified. For example, without this option, the following code results when building frame f1 and button b1:
set f [frame .toplevel.dialog.f1]
pack .toplevel.dialog.f1
button .toplevel.dialog.f1.b1
pack .toplevel.dialog.f1.b1
With this option selected for frame f1, the following code results:
set f [frame .toplevel.dialog.f1]
pack .toplevel.dialog.f1
button $f.b1
pack $f.b1
This may make your code easier to read, but should be used with caution where the set variable may go out of scope.
Note that you can also use the set variable name in the pack and binding statements of a widget by selecting Use set variable name as path in layout and binding commands at Tools-Options-Build. This results in the following code for the above example:
set f [frame .toplevel.dialog.f1]
pack $f
button $f.b1
pack $f.b1
Widget name is full path. Select this option if the name given for the widget (i.e. the name displayed in the tree) is actually the full path for this widget. tkBuilder will use this as the path name when building the widget, rather than the path implied by the tree. For example, you can specify the name for a button to be .toplevel.dialog.frame.b1, rather than b1. You must ensure that the parent widget (.toplevel.dialog.frame in this case) exists by the time the widget is built. The widget name can also be a variable that resolves to a full path (.e.g $widget; include the dollar sign). One application for this option is within procedures that build widgets and accept their names as arguments.
Specify parent name. Select this option if you want to explicitly specify the parent path name of this widget, rather than using the parent implied by the tree. Check the check box, then enter the parent name in the entry. For example, you can specify the parent name .toplevel.dialog.frame to build the button b1. tkBuilder will use this as the parent name when building the widget and ignore the widget tree. You must ensure that the parent exists by the time the widget is built. The parent name can also be a variable that resolves to a path name (.e.g $parent; include the dollar sign). This option is useful within a procedure that builds widgets within other widgets (such as a toplevel or frame) that are passed as arguments to the procedure.
For any widget, you CANNOT use both the widget name as the full path and specify the parent name. You may use one or the other or neither, but not both.
Pre-Widget Code. Enter code that you wish to execute before the widget is built. This code should not reference the widget itself, since the widget will not exist when this code is executed.
Post-Widget Code. Enter code that you wish to execute immediately after the widget is built. This code can reference the widget itself, since the widget will exist by the time this code is executed.
The special form is only activated for special objects. The format of the form is different for each object type. See Special Objects for details.
The properties menu allows you to perform operations on selected properties of the current widget. Properties of the attribute, layout and binding forms can be selected using the left mouse button, in combination with the Control and Shift keys. The properties menu is available as a context menu with a right click on a property.
Copy To Siblings. Copies the values of selected properties to siblings of the current widget.
Copy To Descendants. Copies the values of selected properties to descendants of the current widget.
If you copy an event that does not exist in sibling or descendant widgets, that event is created for those widgets.
Copy Options. Select to same widget class to have subsequent copy operations applied only to widgets that are of the same class as the current widget; select to all widget classes to have copy operations applied to all widget classes. In the later case, if the current widget has selected attributes not found in widgets that are being copied to, they are ignored (e.g., copying attributes from a button to frame widgets).
Clear. Clears values of selected properties.
Show Hidden Attributes. Select this option to show hidden attributes.
Build With Hidden Attributes. Select this option to build with hidden attributes.
Add To Hidden List. Adds the selected attributes to the hidden list. If Show Hidden Attributes is selected, you will not notice a change in the list of displayed attributes.
Remove From Hidden List. Removes the selected attributes from the hidden list.
Insert Event. Select this item to add a new event to the binding form of the current widget. You will be prompted for the event name. Include angle brackets when specifying events, e.g.
Delete Event. Deletes the selected events from the binding form of the current widget.
Building is the process of generating tcl code for the project or a branch of the widget tree. This code can be immediately executed, viewed, saved as tcl code, or saved as a megawidget, without leaving tkBuilder.
A key feature of tkBuilder is that it can build any branch of a tree, from a single widget to the entire project. tkBuilder can initiate a build from the currently selected widget. It builds the widget and all of its descendants. This allows you to construct and test small portions of the tree, rather than dealing with the whole tree all the time.
Widgets are built recursively from the currently selected widget using two rules: 1) siblings are built in the order in which they occur in the widget tree, from top to bottom; 2) descendants of a widget are built before the siblings that follow it in the tree. For example, given the following widget tree:
the order of construction will be main window (.), frame1, button1, button2, frame2, button3, button4, assuming that the main window is the current widget. If frame1 is the current widget, the order of construction will be frame1, button1, and button2. This has two implications when building branches:
The Build menu provides the following items:
Use Run Last if you are tweeking the widgets of a frame and want to continually re-run from the frame, rather than from the widgets you are tweeking.
If you make changes to a widget's properties (attributes, layout or bindings), they will be immediately reflected in the running application (check Enable run-time modification of application properties in Tools-Options-Build). However, changing the geometry manager of a widget has no affect in the running application.
When you build a run, you can Control-Shift-Left-click on a widget of the running application to go to the property forms of that widget in tkBuilder (check Enable selection of widget forms from application in Tools-Options-Build). If you build a run while a previous build is running, the previous build will be shutdown and replaced by the new one.
While an application is running, the fully resolved path name of the currently selected widget is displayed in the status bar.
A tkBuilder megawidget is a branch that you build and save to a file. Again, this can be any branch of the tree, but more likely will be a useful, reuseable group of related widgets that you have put together for a particular purpose, such as a scrolled listbox. Once saved, a megawidget can be inserted any number of times into the current tree or into other trees.
To save the current branch as a tkBuilder megawidget, select Save Branch As Megawidget... from the Build menu. You will be prompted for a megawidget file name that you can specify later when inserting the megawidget.
The file format for megawidgets is unique to tkBuilder; megawidgets are not saved in tcl/tk code; however, you can always view and/or save the tcl/tk code as specified above.
You can specify bindings for individual canvas objects (without the use of tags) in the binding form for the object. When doing so, you should also specify a set variable name for the object, as it will be used in building the binding command. If you specify bindings, but no set variable name, tkBuilder will create the local variable _tkb_canvasObject_ in your code to store the name of the object while its bindings are built.
Note that while all default events are listed in the binding form for canvas objects, only key, button, motion, enter, leave and virtual events are valid for canvas objects.
You can also specify bindings using canvas object tags, but you must write the code for those.
The following special objects can be inserted into the widget tree: Main Window, code blocks, procedures, files, namespaces, and templates. Additionally, each project has a project object. Though they appear in the tree, special objects do not become part of the widget path hierarchy, nor do they directly affect widget path names.
The first object of each widget tree is the project. The project object is automatically created with each new project. Each project has only one project object; you cannot move, insert or delete the project object. The name of the project object is the tail of the file name used to store the project. To save the current project, go to File-Save_Project or File-Save_Project_As. All other objects in the tree are descendants of the project.
Use the project object to set the following properties of the project: startup code, resources, auto_path, packages, namespaces, and registered (third party) widgets. Any time you modifiy these properties, press the Update button to ensure the changes go into effect.
Main Tcl File: Use to select the tcl file to which the properties of the project will be written (i.e. startup code, resources, auto path, packages, and namespaces). The drop down list will contain the names of the tcl file objects that are part of the project. If you do not select a main tcl file, the project properties will not be written to a tcl file; however, the properties will still be used when building runs or views of the project.
Startup: Use Startup to specify the code used to start tcl on your machine, e.g. #!/usr/local/bin/wish -f. Enter the code in the Tcl Startup Code textbox. This code will be put at the top of the main tcl file of the project. Note that tkBuilder does not use this code when building runs or views of your project. You may not need to specify startup code for your project (if, for example, your application runs on Windows, and the wish executable is associated with tcl files).
Resources: Use Resources to specify resource database entries that are added to an application during a build. Enter each database entry on a separate line of the option add textbox. Do not include the text 'option add'; simply enter the resource name and its value; for example, *Button.background red.
Auto_path: Use Auto_path to specify directory names to append to the auto_path variable. Enter each path name on a separate line of the lappend auto_path textbox or delimit with commas or semicolons. Do not include the text 'lappend auto_path'.
Packages: Use Packages to specify the packages to include in the project. Enter each package name on a separate line of the package require textbox, or delimit with commas or semicolons. Do not include the text 'package require'.
Namespaces: Use Namespaces to specify the namespaces to import into the project. Enter each namespace on a separate line of the namespace import textbox, or delimit with commas or semicolons. Do not include the text 'namespace import'.
Widgets: You can register widget classes from other packages, and then use them within tkBuilder as any other tk widget. Once registered, a widget class appears in the More sub-menu of the Widget Insert menu. In order for a widget class to be registered by tkBuilder, its package must provide a function that is the widget class name and has the following capabilities:
To register a widget class, enter the class name in the Widget Registry textbox, delimited by line, comma or semi-colon. Once all desired widgets are entered, press the Update button. To unregister a widget class, remove it from the textbox and press Update.
Do not un-register any widget classes currently used in your application. If you do, you will not be able to access the attributes of those widgets.
The Main Window is the main toplevel window (root) of the application (formerly refered to as 'root' in Version 1.0.1). A project can have only one Main Window; it can be moved and deleted, and re-inserted anywhere in the tree of the project. The position of the Main Window in the tree determines when and where it is configured. Regardless of where it occurs in the tree, the Main Window is always named '.' in tcl code.
A project does not have to have a Main Window object. In that case, the main toplevel of the application will still be created in the running application, with default toplevel properties.
You can add blocks of tcl/tk code anywhere within the widget tree. Each code block is executed as it is encountered during a build (see Order of Widget Construction). Your code can operate on any widgets that have been built by the time the code is encountered; you can even use your code to build widgets directly, rather than specifying them in the widget tree.
Procedure objects allow you to integrate tcl procs into the widget tree. The position of a procedure within the tree determines when it is defined, not when it is executed. Procedure code is not executed until the procedure is explicitly called by your code. If a procedure has descendants, they are not built until the procedure is called.
Parameters. If your procedure has parameters, specify them in the Parameters field. Specify parameters in the same way you do when coding procedures in tcl. For example:
Parameters: myParam
Parameters: { myParam1 myParam2 }
Parameters: "myParam1 myParam2"
Parameters: { myParam1 {myParam2 24} }
Parameters: args
Leave the field blank if the procedure has no parameters.
Test Arguments. When you build a run from a procedure that has parameters, you must supply test arguments in the Test Arguments field. These will be passed to the parameters of the procedure when it is called by tkBuilder. You must supply a test argument for each parameter of the procedure; optional parameters do not require test arguments. You don't need test arguments for a procedure if you won't be building a run from it.
A test argument can be a word, e.g., 2 or myArg, or a command that returns an appropriate value. For example, if a parameter to a procedure is a frame within which descendants of the procedure are packed, [frame .f -bd 3 -relief raised] would be a suitable test argument.
Test arguments are used only when you build a run starting at a procedure; otherwise they are ignored. They are only used for the procedure that starts the run and only in the initial call to the procedure by tkBuilder. Any calls that your code makes to a procedure must supply the necessary arguments.
Test arguments do not appear in built code.
Code. Enter the code of your procedure in the Code box. Do not put braces around the code, as tkBuilder will do that for you. If a procedure has descendants, the code is executed first, and then the descendants are built. If you need code in the procedure to execute after the descendants are built, add a code block as the last child of the procedure.
A file object specifies the name of a tcl file into which tcl code for descendants of the file object is saved when you use File-Save Tcl Files. The purpose of file objects is to partition the tcl code generated by the project into useful file units, as you might if coding outside of tkBuilder. To automatically save all tcl files any time the project is saved, check Save all tcl files when saving project in Tools-Options-General.
WARNING: When adding tcl file objects to a project, DO NOT select existing tcl files, as they will be overwritten when the tcl files are saved. Do not edit the contents of tcl files that are generated by tcl file objects, as any time the tcl files are saved from within tkBuilder, these files will be overwritten.
A template allows you to set values for class-attributes pairs that are then inherited by descendants of the template. For example, you can select button and background, and specify red; then all button widget descendants of the template will have a red background. In this way, you can manage the attributes common to a group of related widgets (e.g., a group of framed buttons) from a single point. A single template can be used to set values for any number of attributes, of any number of widget classes. Any number of templates can be inserted into a widget tree.
To add a class-attribute entry into the current template, select the widget class from the Class combobox and the attribute from the Attribute combobox. The class-attribute entry will be added to the template. Enter a value in the entry box.
To select an entry, click on its class or attribute name or its entry box. To delete an entry, right-click on it and select Delete Entry from the pop-up menu. You can delete the current entry by pressing delete.
The following rules apply to templates:
Remember that a build involves the current widget and its descendants, and ignores the rest of the tree, including ancestors. If you build the top frame in the above example, it will know nothing of the class-attribute values specified in the scheme1 template. For a template to have an effect, you must start the build at the template itself, or at one of its ancestors.