diff options
Diffstat (limited to 'itcl/itk/doc')
| -rw-r--r-- | itcl/itk/doc/Archetype.n | 353 | ||||
| -rw-r--r-- | itcl/itk/doc/Toplevel.n | 133 | ||||
| -rw-r--r-- | itcl/itk/doc/Widget.n | 123 | ||||
| -rw-r--r-- | itcl/itk/doc/itk.n | 96 | ||||
| -rw-r--r-- | itcl/itk/doc/itkvars.n | 43 | ||||
| -rw-r--r-- | itcl/itk/doc/itkwish.1 | 55 | ||||
| -rw-r--r-- | itcl/itk/doc/license.terms | 27 | ||||
| -rw-r--r-- | itcl/itk/doc/man.macros | 236 | ||||
| -rw-r--r-- | itcl/itk/doc/usual.n | 76 |
9 files changed, 1142 insertions, 0 deletions
diff --git a/itcl/itk/doc/Archetype.n b/itcl/itk/doc/Archetype.n new file mode 100644 index 00000000000..5389d32d19f --- /dev/null +++ b/itcl/itk/doc/Archetype.n @@ -0,0 +1,353 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id$ +'\" +.so man.macros +.TH Archetype n 3.0 itk "[incr\ Tk]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Archetype \- base class for all [incr\ Tk] mega-widgets +.SH "INHERITANCE" +none +.ta 4c 8c 12c +.SH "WIDGET-SPECIFIC OPTIONS" +.LP +.nf +Name: \fBclientData\fR +Class: \fBClientData\fR +Command-Line Switch: \fB-clientdata\fR +.fi +.IP +This does not affect the widget operation in any way. It is +simply a hook that clients can use to store a bit of data with +each widget. This can come in handy when using widgets to +build applications. +.BE + +.SH DESCRIPTION +.PP +The \fBArchetype\fR class is the basis for all \fB[incr\ Tk]\fR +mega-widgets. It keeps track of component widgets and provides +methods like "configure" and "cget" that are used to access +the composite configuration options. Each component widget +must be registered with the \fBArchetype\fR base class using +the "\fBitk_component add\fR" method. When the component +is registered, its configuration options are integrated into +the composite option list. Configuring a composite option +like "-background" causes all of the internal components +to change their background color. +.PP +It is not used as a widget by itself, but is used as a base +class for more specialized widgets. The \fBWidget\fR base class +inherits from \fBArchetype\fR, and adds a Tk frame which acts as +the "hull" for the mega-widget. The \fBToplevel\fR base class +inherits from \fBArchetype\fR, but adds a Tk toplevel which acts +as the "hull". +.PP +\fIEach derived class must invoke the \fBitk_initialize\fP method +within its constructor\fR, so that all options are properly +integrated and initialized in the composite list. + + +.SH "PUBLIC METHODS" +.PP +The following methods are provided to support the public +interface of the mega-widget. +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +.sp +In this case, \fIoption\fR refers to a composite configuration +option for the mega-widget. Individual components integrate +their own configuration options onto the composite list when +they are registered by the "\fBitk_component add\fR" method. +.TP +\fIpathName\fR \fBcomponent\fR ?\fIname\fR? ?\fIcommand arg arg ...\fR? +Used to query or access component widgets within a mega-widget. +With no arguments, this returns a list of symbolic names for +component widgets that are accessible in the current scope. +The symbolic name for a component is established when it is +registered by the "\fBitk_component add\fR" method. Note that +component widgets obey any public/protected/private access +restriction that is in force when the component is created. +.sp +If a symbolic \fIname\fR is specified, this method returns the +window path name for that component. +.sp +Otherwise, the \fIcommand\fR and any remaining \fIarg\fR arguments +are invoked as a method on the component with the symbolic +name \fIname\fR. This provides a well-defined way of accessing +internal components without relying on specific window path +names, which are really details of the implementation. +.TP +\fIpathName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). If +one or more \fIoption\-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +.sp +In this case, the \fIoptions\fR refer to composite configuration +options for the mega-widget. Individual components integrate their +own configuration options onto the composite list when they are +registered by the "\fBitk_component add\fR" method. + +.SH "PROTECTED METHODS" +.PP +The following methods are used in derived classes as part of +the implementation for a mega-widget. +.TP +\fBitk_component add\fR ?\fB-protected\fR? ?\fB-private\fR? ?\fB--\fR? \fIname createCmds\fR ?\fIoptionCmds\fR? +Creates a component widget by executing the \fIcreateCmds\fR +argument and registers the new component with the symbolic +name \fIname\fR. The \fB-protected\fR and \fB-private\fR options +can be used to keep the component hidden from the outside world. +These options have a similar effect on component visibility as +they have on class members. +.sp +The \fIcreateCmds\fR code can contain any +number of commands, but it must return the window path name +for the new component widget. +.sp +The \fIoptionCmds\fR script contains commands that describe +how the configuration options for the new component should +be integrated into the composite list for the mega-widget. +It can contain any of the following commands: +.RS +.TP +\fBignore \fIoption\fR ?\fIoption option ...\fR? +Removes one or more configuration \fIoptions\fR from the +composite list. All options are ignored by default, +so the \fBignore\fR command is only used to negate the +effect of a previous \fBkeep\fR or \fBrename\fR command. +This is useful, for example, when the some of the options +added by the \fBusual\fR command should not apply to +a particular component, and need to be ignored. +.TP +\fBkeep \fIoption\fR ?\fIoption option ...\fR? +Integrates one or more configuration \fIoptions\fR into the +composite list, keeping the name the same. Whenever the +mega-widget option is configured, the new value is also +applied to the current component. Options like "-background" +and "-cursor" are commonly found on the \fBkeep\fR list. +.TP +\fBrename \fIoption switchName resourceName resourceClass\fR +Integrates the configuration \fIoption\fR into the composite +list with a different name. The option will be called +\fIswitchName\fR on the composite list. It will also be +modified by setting values for \fIresourceName\fR and \fIresourceClass\fR +in the X11 resource database. The "-highlightbackground" +option is commonly renamed to "-background", so that when +the mega-widget background changes, the background of the +focus ring will change as well. +.TP +\fBusual ?\fItag\fR? +Finds the usual option-handling commands for the specified +\fItag\fR name and executes them. If the \fItag\fR is +not specified, then the widget class name is used as the +\fItag\fR name. The "usual" option-handling commands +are registered via the \fBusual\fR command. +.RE +.sp +If the \fIoptionCmds\fR script is not specified, the usual +option-handling commands associated with the class of the +component widget are used by default. + +.TP +\fBitk_component delete\fR \fIname\fR ?\fIname name ...\fR? +Removes the component widget with the symbolic name \fIname\fR +from the mega-widget. The component widget will still exist, +but it will no longer be accessible as a component of the +mega-widget. Also, any options associated with the component +are removed from the composite option list. +.sp +Note that you can destroy a component using the \fBdestroy\fR +command, just as you would destroy any Tk widget. Components +automatically detach themselves from their mega-widget parent +when destroyed, so "\fBitk_component delete\fR" is rarely used. + +.TP +\fBitk_initialize ?\fIoption value option value...\fR? +\fIThis method must be invoked within the constructor for +each class in a mega-widget hierarchy.\fR It makes sure +that all options are properly integrated into the composite +option list, and synchronizes all components to the initial +option values. It is usually invoked near the bottom of +the constructor, after all component widgets have been +added. +.sp +If any \fIoption\fR/\fIvalue\fR pairs are specified, they +override settings determined from the X11 resource database. +The arguments to the constructor are usually passed along +to this method as follows: +.CS +class MyWidget { + inherit Widget + + constructor {args} { + . + . + . + eval itk_initialize $args + } +} +.CE + +.TP +\fBitk_option add\fR \fIoptName\fR ?\fIoptName optName ...\fR? +Adds one or more options to the composite option list for +a mega-widget. Here, \fIoptName\fR can have one of the +following forms: +.RS +.TP +\fIcomponent\fR.\fIoption\fR +Accesses an \fIoption\fR belonging to a component with the +symbolic name \fIcomponent\fR. The \fIoption\fR name is +specified without a leading "\fB-\fR" sign. +.TP +\fIclassName\fR::\fIoption\fR +Accesses an \fIoption\fR defined by the "\fBitk_option define\fR" +command in class \fIclassName\fR. The \fIoption\fR name is +specified without a leading "\fB-\fR" sign. +.RE +.PP +Options are normally integrated into the composite option list +when a component widget is first created. This method can be +used to add options at a later time. For example, the \fBWidget\fR +and \fBToplevel\fR base classes keep only the bare minimum options +for their "hull" component: -background and -cursor. A derived +class can override this decision, and add options that control +the border of the "hull" component as well: +.CS +class MyWidget { + inherit Widget + + constructor {args} { + itk_option add hull.borderwidth hull.relief + + itk_component add label { + label $itk_interior.l1 -text "Hello World!" + } + pack $itk_component(label) + + eval itk_initialize $args + } +} +.CE + +.TP +\fBitk_option define\fR \fIswitchName resourceName resourceClass init\fR ?\fIconfig\fR? +This command is used at the level of the class definition to +define a synthetic mega-widget option. Within the \fBconfigure\fR +and \fBcget\fR methods, this option is referenced by \fIswitchName\fR, +which must start with a "\fB-\fR" sign. It can also be +modified by setting values for \fIresourceName\fR and \fIresourceClass\fR +in the X11 resource database. The \fIinit\fR value string is used +as a last resort to initialize the option if no other value can +be used from an existing option, or queried from the X11 resource +database. If any \fIconfig\fR code is specified, it is executed +whenever the option is modified via the \fBconfigure\fR method. +The \fIconfig\fR code can also be specified outside of the class +definition via the \fBconfigbody\fR command. +.sp +In the following example, a synthetic "-background" option is +added to the class, so that whenever the background changes, the +new value is reported to standard output. Note that this synthetic +option is integrated with the rest of the "-background" options +that have been kept from component widgets: +.CS +class MyWidget { + inherit Widget + constructor {args} { + itk_component add label { + label $itk_interior.l1 -text "Hello World!" + } + pack $itk_component(label) + + eval itk_initialize $args + } + itk_option define -background background Background #d9d9d9 { + puts "new background: $itk_option(-background)" + } +} +.CE + +.TP +\fBitk_option remove\fR \fIoptName\fR ?\fIoptName optName ...\fR? +Removes one or more options from the composite option list for +a mega-widget. Here, \fIoptName\fR can have one of the forms +described above for the "\fBitk_option add\fR" command. +.sp +Options are normally integrated into the composite option list +when a component widget is first created. This method can be +used to remove options at a later time. For example, a derived +class can override an option defined in a base class by removing +and redefining the option: +.CS +class Base { + inherit Widget + constructor {args} { + eval itk_initialize $args + } + + itk_option define -foo foo Foo "" { + puts "Base: $itk_option(-foo)" + } +} + +class Derived { + inherit Base + + constructor {args} { + itk_option remove Base::foo + eval itk_initialize $args + } + itk_option define -foo foo Foo "" { + puts "Derived: $itk_option(-foo)" + } +} +.CE +Without the "\fBitk_option remove\fR" command, the code fragments +for both of the "-foo" options would be executed each time the +composite "-foo" option is configured. In the example above, +the \fCBase::foo\fR option is suppressed in all Derived class +widgets, so only the \fCDerived::foo\fR option remains. + +.SH "PROTECTED VARIABLES" +Derived classes can find useful information in the following +protected variables. +.TP +itk_component(\fIname\fR) +The "itk_component" array returns the real window path name +for a component widget with the symbolic name \fIname\fR. +The same information can be queried using the \fBcomponent\fR +method, but accessing this array is faster and more convenient. +.TP +itk_interior +This variable contains the name of the window that acts as +a parent for internal components. It is initialized to the +name of the "hull" component provided by the \fBWidget\fR +and \fBToplevel\fR classes. Derived classes can override +the initial setting to point to another interior window +to be used for further-derived classes. +.TP +itk_option(\fIoption\fR) +The "itk_option" array returns the current option value +for the composite widget option named \fIoption\fR. Here, +the \fIoption\fR name should include a leading "\fB-\fR" sign. +The same information can be queried using the \fBcget\fR +method, but accessing this array is faster and more convenient. + +.SH KEYWORDS +itk, Widget, Toplevel, mega-widget diff --git a/itcl/itk/doc/Toplevel.n b/itcl/itk/doc/Toplevel.n new file mode 100644 index 00000000000..b11c4b2d029 --- /dev/null +++ b/itcl/itk/doc/Toplevel.n @@ -0,0 +1,133 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id$ +'\" +.so man.macros +.TH Toplevel n 3.0 itk "[incr\ Tk]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Toplevel \- base class for mega-widgets in a top-level window +.SH "INHERITANCE" +itk::Archetype <- itk::Toplevel +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +\fBbackground\fR \fBcursor\fR +.fi +.LP +See the "options" manual entry for details on the standard options. +.SH "WIDGET-SPECIFIC OPTIONS" +.LP +.nf +Name: \fBtitle\fR +Class: \fBTitle\fR +Command-Line Switch: \fB-title\fR +.fi +.IP +Sets the title that the window manager displays in the title bar +above the window. The default title is the null string. +.BE + +.SH DESCRIPTION +.PP +The \fBToplevel\fR class inherits everything from the \fBArchetype\fR +class, and adds a Tk toplevel called the "hull" component to represent +the body of the mega-widget. The window class name for the hull +is set to the most-specific class name for the mega-widget. +The protected variable \fBitk_interior\fR contains the window +path name for the "hull" component. Derived classes specialize +this widget by packing other widget components into the hull. +.PP +Since the hull for the \fBToplevel\fR class is implemented with +a Tk toplevel, mega-widgets in the \fBToplevel\fR class have +their own toplevel window. This class is used to create dialog +boxes and other pop-up windows. + +.SH "COMPONENTS" +.LP +.nf +Name: \fBhull\fR +Class: \fBToplevel\fR +.fi +.IP +The "hull" component acts as the body for the entire mega-widget. +Other components are packed into the hull to further specialize +the widget. + +.SH EXAMPLE +.PP +The following example implements a \fBMessageInfo\fR +mega-widget. It creates a pop-up message that the +user can dismiss by pushing the "Dismiss" button. +.CS +option add *MessageInfo.title "Notice" widgetDefault + +class MessageInfo { + inherit itk::Toplevel + + constructor {args} { + itk_component add dismiss { + button $itk_interior.dismiss -text "Dismiss" \ + -command "destroy $itk_component(hull)" + } + pack $itk_component(dismiss) -side bottom -pady 4 + + itk_component add separator { + frame $itk_interior.sep -height 2 -borderwidth 1 -relief sunken + } + pack $itk_component(separator) -side bottom -fill x -padx 4 + + itk_component add icon { + label $itk_interior.icon -bitmap info + } + pack $itk_component(icon) -side left -padx 8 -pady 8 + + itk_component add infoFrame { + frame $itk_interior.info + } + pack $itk_component(infoFrame) -side left -expand yes \ + -fill both -padx 4 -pady 4 + + itk_component add message { + label $itk_interior.mesg -width 20 + } { + usual + rename -text -message message Text + } + pack $itk_component(message) -expand yes -fill both + + eval itk_initialize $args + + after idle [code $this centerOnScreen] + } + + protected method centerOnScreen {} { + update idletasks + set wd [winfo reqwidth $itk_component(hull)] + set ht [winfo reqheight $itk_component(hull)] + set x [expr ([winfo screenwidth $itk_component(hull)]-$wd)/2] + set y [expr ([winfo screenheight $itk_component(hull)]-$ht)/2] + wm geometry $itk_component(hull) +$x+$y + } +} + +usual MessageInfo { + keep -background -cursor -foreground -font + keep -activebackground -activeforeground -disabledforeground + keep -highlightcolor -highlightthickness +} + +# +# EXAMPLE: Create a notice window: +# +MessageInfo .m -message "File not found:\\n/usr/local/bin/foo" +.CE + +.SH KEYWORDS +itk, Archetype, Widget, mega-widget diff --git a/itcl/itk/doc/Widget.n b/itcl/itk/doc/Widget.n new file mode 100644 index 00000000000..0c74fd92ebe --- /dev/null +++ b/itcl/itk/doc/Widget.n @@ -0,0 +1,123 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id$ +'\" +.so man.macros +.TH Widget n 3.0 itk "[incr\ Tk]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Widget \- base class for mega-widgets within a frame +.SH "INHERITANCE" +itk::Archetype <- itk::Widget +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +\fBbackground\fR \fBcursor\fR +.fi +.LP +See the "options" manual entry for details on the standard options. +.BE + +.SH DESCRIPTION +.PP +The \fBWidget\fR class inherits everything from the \fBArchetype\fR +class, and adds a Tk frame called the "hull" component to represent +the body of the mega-widget. The window class name for the hull +is set to the most-specific class name for the mega-widget. +The protected variable \fBitk_interior\fR contains the window +path name for the "hull" component. Derived classes specialize +this widget by packing other widget components into the hull. +.PP +Since the hull for the \fBWidget\fR class is implemented with a +Tk frame, mega-widgets in the \fBWidget\fR class can be packed +into other frames and toplevels. + +.SH "COMPONENTS" +.LP +.nf +Name: \fBhull\fR +Class: \fBFrame\fR +.fi +.IP +The "hull" component acts as the body for the entire mega-widget. +Other components are packed into the hull to further specialize +the widget. + +.SH EXAMPLE +.PP +The following example implements a simple \fBTextDisplay\fR +mega-widget. It creates a read-only display of text with +a text widget and a scrollbar. +.CS +option add *TextDisplay.wrap none widgetDefault +option add *TextDisplay.textBackground ivory widgetDefault +option add *TextDisplay.width 40 widgetDefault +option add *TextDisplay.height 10 widgetDefault + +class TextDisplay { + inherit itk::Widget + + constructor {args} { + itk_component add text { + text $itk_interior.info -state disabled \ + -yscrollcommand [code $itk_interior.sbar set] + } { + usual + keep -tabs -wrap -width -height + rename -background -textbackground textBackground Background + } + pack $itk_component(text) -side left -expand yes -fill both + + itk_component add scrollbar { + scrollbar $itk_interior.sbar \ + -command [code $itk_interior.info yview] + } + pack $itk_component(scrollbar) -side right -fill y + + eval itk_initialize $args + } + + public method display {info} + public method append {info} +} + +body TextDisplay::display {info} { + $itk_component(text) configure -state normal + $itk_component(text) delete 1.0 end + $itk_component(text) insert 1.0 $info + $itk_component(text) configure -state disabled +} + +body TextDisplay::append {info} { + $itk_component(text) configure -state normal + $itk_component(text) insert end $info + $itk_component(text) configure -state disabled +} + +usual TextDisplay { + keep -background -cursor -foreground -font + keep -activebackground -activerelief + keep -highlightcolor -highlightthickness + keep -insertbackground -insertborderwidth -insertwidth + keep -insertontime -insertofftime + keep -selectbackground -selectborderwidth -selectforeground + keep -textbackground -troughcolor +} + +# +# EXAMPLE: Display the /etc/passwd file +# +TextDisplay .file -background red +pack .file + +\&.file display [exec cat /etc/passwd] +.CE + +.SH KEYWORDS +itk, Archetype, Widget, mega-widget diff --git a/itcl/itk/doc/itk.n b/itcl/itk/doc/itk.n new file mode 100644 index 00000000000..6a58bb19948 --- /dev/null +++ b/itcl/itk/doc/itk.n @@ -0,0 +1,96 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id$ +'\" +.so man.macros +.TH itk n 3.0 itk "[incr\ Tk]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +itk \- framework for building mega-widgets in Tcl/Tk +.BE + +.SH DESCRIPTION +.PP +Mega-widgets are high-level widgets that are constructed using +Tk widgets as component parts, usually without any C code. A +fileselectionbox, for example, may have a few listboxes, some +entry widgets and some control buttons. These individual widgets +are put together in a way that makes them act like one big +widget. A fileselectionbox mega-widget can be created with a +command like: +.CS +fileselectionbox .fsb -background blue -foreground white +.CE +Once it has been created, it can be reconfigured with a command +like: +.CS +\&.fsb configure -background green -foreground black +.CE +and all of its internal components will change color. Each +mega-widget has a set of methods that can be used to manipulate +it. For example, the current selection can be queried from a +fileselectionbox like this: +.CS +set fileName [.fsb get] +.CE +In effect, a mega-widget looks and acts exactly like a Tk widget, +but is considerably easier to implement. +.PP +\fB[incr\ Tk]\fR is a framework for building mega-widgets. It +uses \fB[incr\ Tcl]\fR to support the object paradigm, and adds +base classes which provide default widget behaviors. +.PP +All \fB[incr\ Tk]\fR widgets are derived from the \fBArchetype\fR +base class. This class manages internal component widgets, +and provides methods like "configure" and "cget" to access +configuration options. +.PP +The \fBWidget\fR base class inherits everything from \fBArchetype\fR, +and adds a Tk frame which acts as a container for the mega-widget. +It is used to build mega-widgets that sit inside of other frames +and toplevels. Derived classes create other internal components +and pack them into the "hull" frame created by the \fBWidget\fR +base class. +.PP +The \fBToplevel\fR base class inherits everything from \fBArchetype\fR, +but adds a Tk toplevel which acts as a container for the mega-widget. +It is used to build mega-widgets, such as dialog boxes, that have +their own toplevel window. Derived classes create other internal +components and pack them into the "hull" toplevel created by the +\fBToplevel\fR base class. + +.SH [incr Widgets] LIBRARY +.PP +\fB[incr\ Widgets]\fR is a mega-widget library built using +\fB[incr\ Tk]\fR. It can be used right out of the box, and +contains more than 30 different widget classes, including: +.IP - +fileselectiondialog +.IP - +tabnotebook +.IP - +panedwindow +.IP - +combobox +.IP - +optionmenu +.IP - +scrolledlistbox +.IP - +scrolledframe +.IP - +messagedialog +.IP - +and many others... +.LP +The \fBcatalog\fR demo in the "iwidgets/demos" directory +shows all of the available widgets in action. Each widget +class has its own man page describing the features available. + +.SH KEYWORDS +class, object, object-oriented, mega-widget diff --git a/itcl/itk/doc/itkvars.n b/itcl/itk/doc/itkvars.n new file mode 100644 index 00000000000..6271ae9821b --- /dev/null +++ b/itcl/itk/doc/itkvars.n @@ -0,0 +1,43 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id$ +'\" +.so man.macros +.TH itkvars n 3.0 itk "[incr\ Tk]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +itkvars \- variables used by [incr\ Tk] +.BE + +.SH DESCRIPTION +.PP +The following global variables are created and managed automatically +by the \fB[incr\ Tk]\fR library. Except where noted below, these +variables should normally be treated as read-only by application-specific +code and by users. +.TP +\fBitk::library\fR +When an interpreter is created, \fB[incr\ Tk]\fR initializes this +variable to hold the name of a directory containing the system library +of \fB[incr\ Tk]\fR scripts. The initial value of \fBitk::library\fR +is set from the ITK_LIBRARY environment variable if it exists, +or from a compiled-in value otherwise. +.sp +When \fB[incr\ Tk]\fR is added to an interpreter, it executes +the script "\fCinit.itk\fR" in this directory. This script, +in turn, looks for other script files with the name "\fCinit.\fIxxx\fR". +Mega-widget libraries will be automatically initialized if they +install a script named "\fCinit.\fIxxx\fR" in this directory, +where "\fIxxx\fR" is the name of the mega-widget library. +For example, the \fB[incr\ Widgets]\fR library installs +the script "\fCinit.iwidgets\fR" in this directory. +This script establishes the "iwidgets" namespace, and sets +up autoloading for all \fB[incr\ Widgets]\fR commands. + +.SH KEYWORDS +itcl, itk, variables diff --git a/itcl/itk/doc/itkwish.1 b/itcl/itk/doc/itkwish.1 new file mode 100644 index 00000000000..b6a12194b81 --- /dev/null +++ b/itcl/itk/doc/itkwish.1 @@ -0,0 +1,55 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id$ +'\" +.so man.macros +.TH itkwish 1 3.0 itk "[incr\ Tk]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +itkwish \- Simple windowing shell for [incr\ Tcl] / [incr\ Tk] +.SH SYNOPSIS +\fBitkwish\fR ?\fIfileName arg arg ...\fR? +.SH OPTIONS +.IP "\fB\-display \fIdisplay\fR" 20 +Display (and screen) on which to display window. +.IP "\fB\-geometry \fIgeometry\fR" 20 +Initial geometry to use for window. If this option is specified, its +value is stored in the \fBgeometry\fR global variable of the application's +Tcl interpreter. +.IP "\fB\-name \fIname\fR" 20 +Use \fIname\fR as the title to be displayed in the window, and +as the name of the interpreter for \fBsend\fR commands. +.IP "\fB\-sync\fR" 20 +Execute all X server commands synchronously, so that errors +are reported immediately. This will result in much slower +execution, but it is useful for debugging. +.IP "\fB\-\|\-\fR" 20 +Pass all remaining arguments through to the script's \fBargv\fR +variable without interpreting them. +This provides a mechanism for passing arguments such as \fB\-name\fR +to a script instead of having \fBitkwish\fR interpret them. +.BE + +.SH DESCRIPTION +.PP +\fBitkwish\fR is a simple program consisting of the Tcl command +language, the Tk toolkit, the \fB[incr\ Tcl]\fR extension for +object-oriented programming, and the \fB[incr\ Tk]\fR extension +for building mega-widgets. The main program creates an +interpreter, creates a main window, and then processes Tcl +commands from standard input or from a file. +.PP +\fBitkwish\fR is just like \fBwish\fR, but includes the +\fB[incr\ Tcl]\fR / \fB[incr\ Tk]\fR extensions. +.PP +See the \fBwish\fR man page for details concerning usage. See +the \fBitcl\fR and \fBitk\fR man pages for an overview of +\fB[incr\ Tcl]\fR / \fB[incr\ Tk]\fR. + +.SH KEYWORDS +Tcl, Tk, itcl, itk, interpreter, shell, toolkit diff --git a/itcl/itk/doc/license.terms b/itcl/itk/doc/license.terms new file mode 100644 index 00000000000..5ad564315d8 --- /dev/null +++ b/itcl/itk/doc/license.terms @@ -0,0 +1,27 @@ +------------------------------------------------------------------------ +>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> [incr Tcl] <<<<<<<<<<<<<<<<<<<<<<<<<<<<<< + + AUTHOR: Michael J. McLennan + Bell Labs Innovations for Lucent Technologies + mmclennan@lucent.com + http://www.tcltk.com/itcl +======================================================================== + Copyright (c) 1993-1996 Lucent Technologies +======================================================================== +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that the copyright notice and warranty disclaimer appear in +supporting documentation, and that the names of Lucent Technologies +any of their entities not be used in advertising or publicity +pertaining to distribution of the software without specific, written +prior permission. + +Lucent Technologies disclaims all warranties with regard to this +software, including all implied warranties of merchantability and +fitness. In no event shall Lucent be liable for any special, indirect +or consequential damages or any damages whatsoever resulting from loss +of use, data or profits, whether in an action of contract, negligence +or other tortuous action, arising out of or in connection with the use +or performance of this software. +======================================================================== diff --git a/itcl/itk/doc/man.macros b/itcl/itk/doc/man.macros new file mode 100644 index 00000000000..3af2da92934 --- /dev/null +++ b/itcl/itk/doc/man.macros @@ -0,0 +1,236 @@ +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59 +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ie !"\\$3"" \{\ +.ta \\n()Au \\n()Bu +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. diff --git a/itcl/itk/doc/usual.n b/itcl/itk/doc/usual.n new file mode 100644 index 00000000000..0e2c4646c6c --- /dev/null +++ b/itcl/itk/doc/usual.n @@ -0,0 +1,76 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id$ +'\" +.so man.macros +.TH usual n 3.0 itk "[incr\ Tk]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +usual \- access default option-handling commands +.br + for a mega-widget component +.SH SYNOPSIS +\fBusual ?\fItag\fR? ?\fIcommands\fR? +.BE + +.SH DESCRIPTION +.PP +The \fBusual\fR command is used outside of an \fB[incr\ Tcl]\fR +class definition to define the usual set of option-handling +commands for a component widget. Option-handling commands +are used when a component is registered with the \fBArchetype\fR +base class via the "\fBitk_component add\fR" method. They +specify how the component's configuration options should be +integrated into the composite option list for the mega-widget. +Options can be kept, renamed, or ignored, as described in the +\fBArchetype\fR man page. +.PP +It is tedious to include the same declarations again and again +whenever components are added. The \fBusual\fR command allows +a standard code fragment to be registered for each widget class, +which is used by default to handle the options. All of the +standard Tk widgets have \fBusual\fR declarations defined in +the \fB[incr\ Tk]\fR library. Similar \fBusual\fR declarations +should be created whenever a new mega-widget class is conceived. +Only the most-generic options should be included in the \fBusual\fR +declaration. +.PP +The \fItag\fR name is usually the name of a widget class, +which starts with a capital letter; however, any string registered +here can be used later with the \fBusual\fR command described +on the \fBArchetype\fR man page. +.PP +If the \fIcommands\fR argument is specified, it is associated +with the \fItag\fR string, and can be accessed later via +\fBitk_component add\fR. +.PP +If only the \fItag\fR argument is specified, this command looks for +an existing \fItag\fR name and returns the commands associated +with it. If there are no commands associated with \fItag\fR, +this command returns the null string. +.PP +If no arguments are specified, this command returns a list of +all \fItag\fR names previously registered. + +.SH EXAMPLE +Following is the \fBusual\fR declaration for the standard +Tk button widget: +.CS +usual Button { + keep -background -cursor -foreground -font + keep -activebackground -activeforeground -disabledforeground + keep -highlightcolor -highlightthickness + rename -highlightbackground -background background Background +} +.CE +Only the options that would be common to all buttons in a +single mega-widget are kept or renamed. Options like "-text" +that would be unique to a particular button are ignored. + +.SH KEYWORDS +itk, Archetype, component, mega-widget |