Starting XOTclIDE

Change in your working directory and start XOTclIDE.tcl from it. Command line to start XOTclIDE its depending on your installation here an example for Linux RPM installation. By Windows system you can just click on XOTclIDE.tcl.

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

Component Browser is divided visually into 4 areas (panes) : Component, Classes/Object/Tcl Procs Groups, Categories, Methods and Text Editor. Each area have its corresponding menu. The four upper list-views correspond to source code structure in XOTclIDE. The main structure is component. A Component has specific name and is a container for Classes, Objects and Tcl-Procedures-Groups. Every Class can have instance- or class methods. These methods can be group together in categories. Also standard not object oriented Tcl procedures can be a part of component. They are grouped in so called Tcl-Procedures-Groups. Tcl-Procedures can not belong to categories. In this way you can structure in 3 level system your whole code and it can be used to practice component oriented programming (More Information the Section called Building an Application in the chapter called Programming with XOTclIDE).

Exercise

Select component IDECore in Components list view. In Class/Objects list view all classes contained in this component will be listed. Select class IDE::Component in Class/Objects list view. Select category _all_categories in Categories list view. Select method getObjectDefineList in Methods list view. In the editor area appear the body (source code) of this method. You should see the browser as on screen-shoot Figure 1. The blue background of the right lower button Source indicate that this method have programmer comment. Press it to see this comment. The editor changes to comment view. Press it again to change back to source view. Press button Classes in the Class/Objects list view to see another elements of this component.

Creating new Components

Programming in XOTclIDE is component oriented. Assuming that you want to write simple program as follow.

# 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

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

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
}

package require PlatformLogDumper
generateTclPlatformProtocol tclPlatform.log

XOTclIDE Components act for Tcl as normal packages. They contains additional XOTclIDE special meta informations that are handled by XOTclIDE.

Adding Tcl procedures

Your new created component appear in the Components list view. Select it. Now create new Tcl-Procedures-Group with menu Class->Tcl Procs Group->New Group. Type in the dialog the name of the group.

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

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

If you want to set comment for this procedure press the button Source in the right lower edge of edit area. The editor change the view to comment view. You can type the command and apply it with Edit->Save/Apply (Control-s)

Interactive work with procedures

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

Saving Component in File System

To save a component in file system you can use menu in Component Browser Component->Save Components. In the dialog box select your component and check the button create pkgIndex (see Figure 4).

# 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
}

proc @ args {}

# 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]]

Using Components without XOTclIDE

For Tcl 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 auto_path global variable and if you do not use XOTcl to define dummy procedure to ignore @ lines. Here a sample usage from 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

Loading Component from File System

To load a component into XOTclIDE use menu. Component->Load Package If you do not see the your component in package list than you must assure that Tcl can find the package. The list is generated by using package names command. XOTclIDE add current working directory to auto_path at start time. Also if you want to load the your package change into the directory with your packages before starting XOTclIDE.

In normal case you do not need to worry about how the components are save or load in file-system and also how is the text representation of whole component (component as script). You can install you component in Tcl distribution subdirectory. Read Tcl package command manual to get more about package mechanism in Tcl.

It can be quite tricky to force Tcl to find and load package you need. Some people say even about "Package Hell". The package list are also build only once and can not be rebuild if you change package dynamic. You need to restart XOTclIDE to load packages you have just created. You would not have this problems if you use Version Control.

Creating Configuration Map and distribute program

The components in XOTclIDE have a characteristic of function- or class libraries in another system. You can build your application as one or set of components. To specify a application you need not only definition scripts but also the application starting script also a line like this

generateTclPlatformProtocol out.log

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

• Components to load (the order to load and how they should be loaded from file-system or version control system)

• preStartScript - a script that will be evaluated before loading component

• startScript - a script that start the application

In another IDEs "configuration map" correspond to project or "solution map".

You can set this configmap file as 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

Evaluating Short Tcl Scripts

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

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

You can load and manage your scripts be using so called Workspaces. To open a Workspace use menu System->Workspace It is simply text area (simple Editor) that can be used to type scripts save or load them from 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.

Advanced Usage: Overview

The tutorial above describes how to get first result with XOTclIDE. But the main advantages of this system can be seen by using advanced techniques of XOTclIDE. That are: