Change to your chosen working directory and start XOTclIDE.tcl in it. The command line to start XOTclIDE depends on your installation. For example, using a Linux RPM installation:

[artur@rybnik xotclIDE]$ tclsh /usr/local/lib/xotclIDE/XotclIDE.tcl
or
[artur@rybnik xotclIDE]$ /usr/local/lib/xotclIDE/XotclIDE.tcl

On Windows systems you can just click on XOTclIDE.tcl.

After loading two windows appear. One window is the Transcript window with a welcome message. This is used to display system messages and evaluate short scripts. The second window is the Component Browser, the main browser used to explore and modify your system structure and program code.

The Component Browser is divided into five panes: Component, Classes/Object/Tcl Procs Groups, Categories, Methods and Text Editor. The four upper list-views correspond to source code structures within XOTclIDE. Each of the four has an associated menu. The highest level structure is a Component. A Component has a specific name and is a container for Classes, Objects and Tcl-Procedures-Groups. Each Class can have instance methods or class methods, corresponding respectively to XOTcl's instprocs and procs. These methods can be grouped together in Categories. Standard non object oriented Tcl procedures can be part of a Component when grouped in Tcl-Procedures-Groups. Individual Tcl procedures may not belong to Categories. The Methods pane lists the names of methods (procs and instprocs) in the selected Class and Category. The three levels (Component, Class/Object/Tcl-Procedures-Group, and Category) may be used to practice component oriented programming (More Information the section called “Building an Application”).

Exercise

Select component IDECore in the Components list view. In the Class/Objects list view all classes contained in this component will be listed. Select class IDE::Component in the Class/Objects list view. Select category _all_categories in Categories list view. Select method getObjectDefineList in the Methods list view. In the editor area the body (source code) of this method will appear. The browser will look like screen-shot Figure 2.1, “Component Browser”. The blue background of the Source button in the right lower corner indicates that this method has a programmer comment. Press it to see this comment. The editor changes to comment view. Press the button again to change back to source view. Press button Objects in the Class/Objects list view to see another type of element of this component.

Figure 2.1. Component Browser

Programming in XOTclIDE is component oriented. Assume that you want to write simple program as follows.

# This procedure dump elements of global array Tcl_platform
# to file with name specified by parameter "file"
proc generateTclPlatformProtocol {file} {
     global tcl_platform
     set fhandler [open $file w]
     foreach key [array names tcl_platform] {
         puts $fhandler "$key = $tcl_platform($key)"
     }
     close $fhandler
}
generateTclPlatformProtocol tclPlatform.log

A regular Tcl-Programmer would open his favorite editor, type the text and save it as a Tcl script. Perhaps he would not create the procedure generateTclPlatformProtocol but would program it directly in the global context as follows:

set fhandler [open  tclPlatform.log  w]
foreach key [array names tcl_platform] {
     puts $fhandler "$key = $tcl_platform($key)"
}
close $fhandler

This can be good for small scripts. To program larger systems or to create reusable code a good programmer would prefer to write a Tcl-package like this:

package provide PlatformLogDumper 0.1
# This procedure dump elements of global array tcl_platform
# to file with name specified by parameter "file"
proc generateTclPlatformProtocol {file} {
     global tcl_platform
     set fhandler [open $file w]
     foreach key [array names tcl_platform] {
         puts $fhandler "$key = $tcl_platform($key)"
     }
     close $fhandler
}

You would also need to create a file pkgIndex.tcl and add its directory to the Tcl auto_path global variable. You can use the package as follows

package require PlatformLogDumper
generateTclPlatformProtocol tclPlatform.log

The Tcl package mechanism allows the function library definition to be separated from the function call.

	Important
	XOTclIDE Components are normal Tcl packages that contain additional meta information that is handled by XOTclIDE.

Let's make make a first Component. Choose menu Component->New from Component Browser. In the dialog enter the name of the new component “PlatformLogDumper” and click the apply button. Your new component will appear in the list of components. In the next section you will learn how to add procedures to this component.

Your new created component appears in the Components list view. Select it. Now create a new Tcl-Procedures-Group using the menu Class->Tcl Procs Group->New Group. In the dialog type the name of the group.

The name of the newly created Tcl-Procedures-Group will appear in the Class/Objects list view. Select it. New you can create your procedure. Select menu Method->New Method Template In the editor window the template for a Tcl procedure will appear as follows:

proc procName {args} {
    # enter the body here
}

Type your new procedure. When you are ready you must add the procedure to the interpreter. Use menu or key accelerator Edit->Save/Apply (Control-s) Your Component Browser will appear as follows: Figure 2.2, “Create Component”

Figure 2.2. Create Component

If you want to create a comment for this procedure press the Source button in the right lower edge of the edit area. The editor pane will change to comment view. Type a comment and apply it with Edit->Save/Apply (Control-s)

The main advantage of XOTclIDE is that it is not only an editor for Tcl scripts but it “sits” directly on a Tcl-Interpreter. Tcl for XOTclIDE is the same as Lisp for Emacs. You can try (invoke, call) a procedure immediately after you define it. Select the procedure and choose the menu Method->Invoke You will be ask to specify the parameters for the procedure call. In Tcl everything is a string so it is no problem just to type the parameters in the dialog as Tcl words (e.g “2 {2 3}” are two parameters)

Figure 2.3. Invoking Procedures

The result is returned as result text. If the result is an XOTcl object or list of XOTcl objects the object inspector will be displayed. If the result is an empty string then a special message box is shown.

To save your new component in the file system use the menu Component Browser Component->Save Components. In the dialog box select your component and check the button create pkgIndex (see Figure 2.4, “Saving Components”).

Figure 2.4. Saving Components

After accepting dialog a package file PlatformLogDumper.xotcl will be saved in a filesystem directory. The file should look as follows.

# automatically generated from XOTclIDE
package provide PlatformLogDumper 0.1

@ tclproc generateTclPlatformProtocol idemeta struct \
PlatformLogDumper MyGroup
proc generateTclPlatformProtocol file {
     global tcl_platform
     set fhandler [open $file w]
     foreach key [array names tcl_platform] {
           puts $fhandler "$key = $tcl_platform($key)"
     }
     close $fhandler
}

Note that the component was saved as a “regular” Tcl package. The one difference is the line beginning with @. This is XOTcl notation for meta-data and is used in XOTclIDE to code additional structure information. To use this package from pure Tcl you can check the button no meta data @ before saving the component or define a dummy proc to ignore the meta-data as follows

proc @ args {}

The checked option create pkgIndex caused the generation of the file pkgIndex.tcl in the same directory as the package.

# Tcl package index file, version 1.1
# This file is generated by the "pkg_mkIndex -direct" command
# and sourced either when an application starts up or
# by a "package unknown" script.
It invokes the
# "package ifneeded" command to set up package-related
# information so that packages will be loaded automatically
# in response to "package require" commands.
When this
# script is sourced, the variable $dir must contain the
# full path name of this file's directory.
package ifneeded PlatformLogDumper 0.1 \
[list source [file join $dir PlatformLogDumper.xotcl]]

In this index file appear all packages from the directory with names that match the pattern *.xotcl.

As mentioned above, XOTclIDE components are normal Tcl packages. To use them from Tcl scripts you need first to register the package in Tcl package system by setting the auto_path global variable. If you do not use XOTcl, define a dummy procedure to ignore @ lines. Here is a sample usage from the tcl shell.

[artur@localhost own_oxtcl]$ tcl
tcl>proc @ args {}
tcl>lappend auto_path .
/usr/share/tcl8.3 /usr/share /usr/lib /usr/share/tclX8.3 .
tcl>package require PlatformLogDumper
0.1
tcl>generateTclPlatformProtocol out.log

To load a package or component into XOTclIDE use the menu Component->Load Package. If you do not see your component in the package list, this means Tcl is unable find the package. The package list is generated using the Tcl package names command which uses the auto_path variable as a list of directories to search for packages. XOTclIDE adds the current working directory to the auto_path list at start time. One way to load your package is to change into the directory with your packages before starting XOTclIDE.

Normally you do not need to worry about how the components are saved or loaded in the filesystem or how a component is represented in text. You can install your component in Tcl distribution subdirectory. Read the Tcl package command manual for more about the package mechanism in Tcl.

	Warning
	It can be quite tricky to force Tcl to find and load packages you need. Some people use the phrase “Package Hell”. The package list are built only once and cannot be rebuilt if you change packages dynamically. You will need to restart XOTclIDE to load packages you have just created if your components are stored as files. You would not have this problem if you use XOTclIDE's Version Control.

Components in XOTclIDE are like function- or class libraries in other systems. You can build your application as one or more components. You also need an application starting script that contains a line like this

generateTclPlatformProtocol out.log

You can of course write you own start script as follows and save it as a file

lappend auto_patch $pathToComponentFile
proc @ args {}
package require PlatformLogDumper 
generateTclPlatformProtocol out.log

Alternatively, XOTclIDE supports configuration maps that group components together and specify a start script. A configuration map specifies

Configuration maps may be also used to deploy applications.

	Tip
	“Configuration maps” correspond to project or “solution maps” in other IDEs.

To specify a configuration map you use the Configuration MapBrowser that can be started from the menu System->Configuration Map Browser.

Figure 2.5. Configurations Map Browser

Do not forget to apply the start script from the menu Edit->Save/Apply (Control-s). After defining a configuration map you can save it as a configuration map file (extension .cfmap).

You can set this configmap file as a start parameter of XOTclIDE so all components from this configuration map are loaded at starting time.

[artur@localhost own_oxtcl]$ XotclIDE.tcl -- -configmap platformLogDumper.cfmap

If you develop a big application it's a good idea to define a configuration map and use it as a start parameter. (see the section called “Configuration Management and Deploying” for more informations)

Tcl is often used to write short ad hoc programs called scripts (Scripting Language). Scripts are often sequences of simple Tcl commands that are evaluated in the global context. Often no procedures are defined in such scripts.

Every Editor Text Area in XOTclIDE has the ability to evaluate short scripts. To run (evaluate) the script just select the script text and invoke it from the pop-down menu (Right mouse-button) or the menu Editor.

You can load and manage your scripts by using Workspace windows. To open a Workspace use the menu System->Workspace A Workspace is simply a text area (simple Editor) that can be used to type scripts, save or load them from the file system. It can be also used as a temporary “scratch pad”, to enter and evaluate expressions during the process of testing new method definitions.

Figure 2.6. Workspace

The tutorial above describes how to get your first results with XOTclIDE. The main advantages of this system can be seen by using the advanced features of XOTclIDE: