TkVSform-1.0b1 ============== (Dec. 8, 1995) TkVSform version 1.0, beta release 1 With apologies to the many people that have contacted me over the months since I alluded to this package, I'm finally making a prerelease version available for your experimentation. TkVSform is a facility for developing Tk-based forms without worrying too much about such things as widget path names, widget arguments, key bindings, geometry management, and other annoying Tk issues. As a result, a forms-based GUI tends to be put together much more quickly and consistently over its Tk equivalent. TkVSform works well with the other TclVS toolkit components, TclVSdb (a database facility) and TclVSrpt (a report / document generation facility), but can be used independently. [see dbForm.tcl for TclVSdb integration]. As much as I hate the term "widget", I find no good alternative to the term for this document. In context of TclVSform, a "widget" is a GUI item on the form that presents or obtains information. Decorative or control elements are not "widgets". Features: ========= o A "form" is a data abstraction that is associated with a Tcl associative array variable. This associative array contains all state information and the configuration of the form. o A "group" is continuous region of the form of consisting of "lines" and has a border drawn around it. o A "line" is a horizontal band of "widgets". o An "widget" is a graphical user-interface element. Supported widgets include: formLABEL a prompt string and / or string obtained from a variable formCHECK a checkbutton with prompt that sets a boolean variable formRADIO a radiobutton that sets a variable to its prompt value formBUTTON a push button that launches a Tcl command or procedure formENTRY a text entry line with two-way association to a variable and optional Tcl verification procedure formPASSWORD a formENTRY which echos "*" instead of typed input formMESSAGE a multi-line text display formTEXT a scrollable multi-line text entry area or text display area, with two-way association to a variable formLIST a scrollable selection list (select single entry) with three possible input sources: * list of fixed entries via literal list * list of entries pulled from a variable * list of entries returned from a Tcl command or procedure two possible output destinations: * a variable * a Tcl procedure o Each "widget" may have a state name (a mnemonic string) associated with it, (independent of its line or group membership). All items with same state name may be enabled or disabled atomically. o All selectable widgets support keyboard traversal via and activation via . o Two way association exists between all widgets and their source variable, meaning that invoking or changing the widget via the form instantly maps the values to the variable, and changing the variable's value immediately updates the form. o Forms are not mapped to the screen until all construction and geometry management is completed. o Form composition is simple; following a basic outline structure working from the top of the form, down line by line, and from the left to the right adding widgets to a line: formBEGIN formGROUP formNEWLINE widget widget widget formNEWLINE widget widget formGROUP formNEWLINE widget widget formEND Drawbacks: ========== o Not all Tk widgets or features are supported o Placement of widgets is on from left to right on a line, to add spacing between widgets, insert a formLABEL widget with an empty string. No centering on a line or placement controls are given Procedures: =========== NOTE: The widget creation procedures return the Tk widget path of the widget. In most situations, this value can be simply ignored as TkVSform tracks all of this information internally. formBEGIN fvar title pos wtoposto [MAIN] Start definition of a form. Associate form with global array named "fvar". Put "title" in the window decoration. Position the upper-left corner of the form to "pos" (i.e. "+100+100"). Ignore "wtoposto" for now as relative positioning of forms hasn't been implemented yet. If "MAIN" is added, the main "wish" window is used for the form, otherwise, a new toplevel form is created. formGROUP fvar Close definition of any previous lines or groups and start definition of a new group on the form associated with the "fvar" global array variable. formNEWLINE fvar Close definition of the previous line and start definition of a new line in the form associated with the "fvar" global array variable. A "line" is a horizontal band of widgets which are added from left to right. The height of the current line is determined by the height of the tallest widget on the line. Widgets are centered vertically within their line. formCHECK fvar statetag prompt var [elem] [tkopts] Create a checkbutton widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. "prompt" is the string to label the checkbutton with (placed to the right of the checkbutton). "var" is a global variable to take the boolean value (1=selected, 0=not selected) of the checkbutton. If "var" is a global array variable, "elem" is the element name to associate with the checkbutton (or either omit or set to "" if not needed). "tkopts" is a string containing any additional Tk options that you might want to optionally set for the checkbutton widget. formRADIO fvar statetag prompt var [elem] [tkopts] Create a radiobutton widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. "prompt" is the string to label the radiobutton with and is also the value returned if the radiobutton is selected (placed to the right of the radio). "var" is a global variable to receive the value of the radiobutton. If "var" is a global array variable, "elem" is the element name to associate with the radiobutton (or either omit or set to "" if not needed). "tkopts" is a string containing any additional Tk options that you might want to optionally set for the radiobutton widget. formBUTTON fvar statetag prompt cmd [cmdargs] [width] [tkopts] Create a button widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. "prompt" is the string to display on the button. "cmd" is the Tcl command or procedure name to invoke when the button is activated. "cmdargs" is a string containing any arguments that you might wish to provide the "cmd" argument, or omit or set to "" if not needed. "width" is the desired width of the button in characters, which, if omitted or set to "" will default to the width of "prompt". "tkopts" is a string containing any additional Tk options that you might want to optionally set for the button widget. formLABEL fvar statetag prompt [var] [elem] [width] [tkopts] Create a label widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. "prompt" is a bolded string to display prior to the label widget (or set to "" if not desired). "var" is an optional global variable to display a non-bolded string from after the "prompt" string (and is updateable at run time by simply assigning to "var"; either omit or set to "" if not needed). If "var" is a global array variable, "elem" is the element name to associate with the label widget (or either omit or set to "" if not needed). "tkopts" is a string containing any additional Tk options that you might want to optionally set for the label widget. formENTRY fvar statetag var [elem] [width] [cmd] [cmdargs] [tkopts] Create an entry (type-in) widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. Associate the global variable "var" with the entry widget. If "var" is a global array, "elem" is used to specify which array element to associate with the entry widget (omit or set to "" if not needed). "width" is the optional width of the entry widget in characters (defaults to 25). Validation of the entry is achieved with the "cmd" Tcl procedure name and its optional argument list, "cmdargs". The "cmd" procedure, if given will be called as: procname $fvar $pathofentry $var $elem $cmdargs when a is entered in the entry widget. "tkopts" is a string containing any additional Tk options that you might want to optionally set for the entry widget. formPASSWORD fvar statetag var [elem] [width] [cmd] [cmdargs] [tkopts] formPASSWORD is identical in every way to formENTRY execept all typed-in input is echoed as a sequence of "*" characters. See the "formENTRY" entry above for usage. formMESSAGE fvar statetag var [elem] [tkopts] Create a multi-line textual message widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. The argument "var" may be either the string to display in the message widget or the global variable name containing the text to display in the message widget. The message widget determines its width by the width of the longest line of text to be displayed, and will only break displayed lines when a newline is found in the text. If "var" is a global variable array, "elem" is the element name for the message widget to associate with in the array. "tkopts" is a string containing any additional Tk options that you might want to optionally set for the message widget. formTEXT fvar statetag var [elem] [width] [height] [tkopts] Create a multi-line scrollable text input / output region widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. "var" is the global variable to associate with the scrollable text region ("var" for this widget acts as if a Tk text widget had a "-textvariable" option [which it doesn't]). If "var" is a global array variable, "elem" specifies the element in the array to associate with the widget. "width" specifies the width of this widget is characters (defaults to 45) and "height" specifies the height of the widget in lines of text (defaults to 8). "tkopts" is a string containing any additional Tk options that you might want to optionally set for the text widget. Should you wish to not allow input into this widget, but make it read-only, specify the "tkopts" string "-state disabled". formLIST fvar statetag var elem ovar [oelem] [width] [height] [tkopts] Create a multi-line scrollable, single selection, list widget on the current line of the form associated with the "fvar" global array variable. "statetag" can be an arbitrary string (no white space) for managing enabling or disabling of this widget, or "" if not important. "var" is the data source of the list of strings to display in the list widget, one per line, and may be given as one of three forms: (1) a quoted literal list of items for the list ("elem" must be set to ""), (2) "var" is the name of a global variable from which the list of items to display are obtained ("elem" specifies the element name for the list if "var" is a global array), and (3) "var" is the name of a Tcl command or procedure which will return the list of items to display ("elem" is the arguments to the command or procedure, or ""). "ovar" is the destination of of the list item text selected. "ovar" may take on one of two forms: (1) "ovar" is the name of a global variable to receive the selected list item string ("oelem" is the element name for the assignment if "ovar" is a global array), or (2) "ovar" is the name of a Tcl procedure to receive the selected item string ("oelem" becomes an list of additional arguments to the procedure. The argument list to "ovar" when used in this manner is: procname $fvar $selectedindex $selecteditem ["olem" arguments] The various input and output options to the formLIST widget makes it very flexible. "width" is the width of the list in characters (defaults to 15). "height" is the height of the list in lines displayed (defaults to 5). "tkopts" is a string containing any additional Tk options that you might want to optionally set for the list widget. formEND fvar [showit] [focuseditem] [focustype] Signals completion of the form defintion associated with the global array variable "fvar". "showit" may have the value of "on" (the default) or "off", governing whether the form should be displayed on the screen immediately. The "formSHOW" command may be used to display a form whose "showit" value has been set to "off". "focuseditem" is the widget path the on the form that receives the initial highlighted input focus (defaults to the first form widget defined). "focustype" may be set to the value of "lockedinput" which will exclude any transfer for focus outside of the form when it is visible on the screen [use this option only after exhaustive testing of the form without it, and then, with caution]. formDIE fvar Removes a form from the screen, destroys it, frees all resources associated with the form, and destroys the "fvar" global array variable. formSHOW fvar [showit] Displays a finished form (formEND has been previously issued) associated with the global array variable "fvar", or removes the form non-destructively from the screen. "showit" may take the value "on" to display a form (the default), or "off" to remove the form from the screen. formPATHS fvar [pattern] Returns a list of the Tk widget paths for all widgets in the form associated with the global array variable "fvar". If "pattern" is omitted, all widget paths are returned. "pattern" is a glob-style pattern to restrict the returned paths. For instance, a pattern of "*.txt" will return all text area widgets, and a pattern of "*.g3.*" will return all widgets in the third group defined for the form. formSTATE fvar statetag [onoff] Activates or deactives all widgets in the form associated with the global array variable "fvar" whose "statetag" matches the string provided with this command. "onoff" may take the value of "on" (the default) to activate the widgets, or "off" will deactivate the widgets. When a widget is deactivated, it becomes a light gray in color and is neither selectable with the mouse or keyboard traversal. formCURSOR fvar [type] [altcursorname] Set the cursor shown when the mouse pointer is over the form for the form associated with the global array variable "fvar". "type" may take on the values of "normal" (the default), "busy" (an hourglass), or "alt". If "type" is set to "alt", then "altcursorname" must contain the name of the cursor to use. formTEXTTRACE fvar opcode Activates or deactivates the two-way association between the text widgets in the form associated with the global array variable "fvar", and their data source variables. "opcode" may be set to "on" (the default) to activate the two-way association, or "off" to break the association. formTEXTREFRESH fvar Updates the text widgets for the form associated with the global array variable "fvar" from their data source variables. This would be desirable if "formTEXTTRACE" was used to break two-way association with these variables. formLISTCLEAR fvar [path] Clears the contents of a scrollable single item selection list widget in the form associated with the global array variable "fvar". if "path" is omitted, all list widgets in the form are cleared. Otherwise, "path" is the Tk widget path returned by the "formLIST" command to the widget to be cleared. formLISTUPDATE fvar path var [elem] Replaces the contents of a scrollable single item selection list widget in the form associated with the global array variable "fvar". "path" is the Tk widget path (as returned by "formLIST") for the widget to be updated. "var" is a list of strings to display in the list widget, one per line, and may be given as one of three forms: (1) a quoted literal list of items for the list widget ("elem" must be set to ""), (2) "var" is the name of a global variable from which the list of items to display are obtained ("elem" specifies the element name for the list if "var" is a global array), and (3) "var" is the name of a Tcl command or procedure which will return the list of items to display ("elem" is the arguments to the command or procedure, or ""). Missing features desired for actual release of TkVSform: ======================================================== o Multi, discontinuous, list selection o Menu bars and menu lists o Bitmap and image support (without using "tkopts") o Library of stock forms (e.g. file selection, font selection, email form, error popup, confirmation popup, etc.) o Sample application integrating TkVSform with TclVSdb and TclVSrpt to provide database definition, selection, editing, and report generation. o Possible other sample applications (bug tracking? rolodex?) Feedback, comments, bugs, enhancement requests: =============================================== Please send all feedback, comments, bugs, enhancement requests, war stories, success stories, etc. to: steven@cirque.com Steve Wahl Cirque Labs, Inc. 268 W. Third St. / P. O. Box 1774 Nederland, CO 80466 (303) 258-0100 (303) 258-7255 (FAX) url: http://www.cirque.com/ Announcements will be made to comp.lang.tcl, perhaps comp.lang.tcl.announce (if it happens anytime soon). TclVS archives are found at: ftp://ftp.cirque.com/pub/TclVS http://www.cirque.com/tclvs.html