Preliminary Instructions on using OpTcl's Script Objects
========================================================

Farzad Pezeshkpour
University of East Anglia
email: fuzz@sys.uea.ac.uk 
Release Version: 1.0b1
Due date of next release: 1st May 97


Contents
--------

+ Introduction

+ Loading the OpTcl1 Module

+ Commands
	Core Commands
	Script Object Commands
		Methods
		Properties
		Constants
		Reference Counting

+ An example of using OpTcl with Microsoft Excel


Introduction
------------

This is a temporary working document, and in the next release will be made part of the a distributed set of help files in HTML format.

OpTcl is an extension to the popular programming language, Tcl/Tk developed and distributed by Sun Microsystems. The acronym stands for Open Tool Command Language and its purpose is to provide a component model neutral extension to Tcl, such that it can be used to script and embed components  in Tcl scripts. 

A component is some code or stand alone application, that has had its functionality exposed to prospective clients using the protocols defined by some component model. Components can range from small units of code such as a spellchecker, or image viewer, to more complex systems such spreadsheets and databases.  The important difference that exists between a component and a library (DLL) is that there exists a series of protocols (rules of communication) that enable a client to discover a component at runtime.  This is a very powerful tool as it means that once a client has been compiled with these rules, it can (in theory) communicated with _any_ component.

The protocols are often referred to as component models. There exist a variety of these models, but the primary three that I forsee as being dominant in the future are:

	Microsoft's OLE (also known as ActiveX)
	CILab's OpenDoc
	Javasoft's JavaBeans

OpTcl currently supports the first of these three, but it is a sincere aim of the author to support all three models within the next six months on the Win32, MacOs and Unix platforms. Also, the current version only supports dynamic scripting to objects - however, the next release (circa June 1997) will also full embedding of an object in the GUI of Tk, Drag and Drop, and Persistance management.

OpTcl exists as a loadable module (a DLL in Win32), and hence does not require recompilation of the Tcl/Tk binaries. The module has been tested on Tcl/Tk8.0a2.

Please make any bug reports or suggestions by email as given at the beginning of this document.


Loading the OpTcl1 Module
-------------------------

To enable the functionality of OpTcl in your script, use the command

	load [optcl path\]Optcl1 Optcl1     or alternatively



This will initialise all the necessary commands, and setup exit handlers to clean up all allocated structures on exit.

Commands
--------

  Core commands
  -----------

There are four core commands to learn: socreate, sodestroy, sodestroyall and solist.


. socreate <object name>

This is the main command for creating scriptable references to objects in the system. <object name> is a system registered name that is capable of such a connection. Whether an application complies with the connection protocols is documented in its respective manual pages/help files, as well as being registered in the systems object reference registry (in Win32 the registery). The next release of OpTcl will show all objects available in the system, hence reducing the search time for available servers.

For example, to create a connection to Microsoft Excel, <object name> would be:

	excel.application

or for Internet Explorer,

	internetexplorer.application

The return value of this function is a unique identifier for that connection, and will used to communicate with that object - so in OpTcl, it is common to store this value in some variable.



. sodestroy <unique identifier> [<unique identifier> ...]

sodestroy releases all references from Tcl to the script objects with the given unique identifiers and deallocates the internal structures associated with them. Note that this does not force the said object to terminate. This method of destroying an object is only provided for emergency purposes. Please see the reference counting section on a more civilised approach.


. sodestroyall

This is a short cut to ensure that all script objects are released.



. solist

This returns a list of all script objects.


	Script Object Commands
	----------------------

Once a script object is created, it can have a set of commands invoked to it.
Generally any object will have a set of methods, a set of properties, and another for constants. The great power of OpTcl is that it provides a component model neutral syntax for querying an object for information regarding its members. With this kind of information, a script writer can interactivley, make a connection to an object, view its members, experiment with them, and based on these experimentations write/modify the his/her script.

Methods
-------

To find the methods of an object use the following syntax:

	<object id> methods

This returns a list of available methods. Each element of this list is in the form:

	{methodName {required optional returnType <parameters>}}

where 

	required	-	The number of required parameters
	optional	-	The number of optional parameters
	returnType	- 	The return type of the method

	<parameters>-	This is a list of parameter declarations, where each
				element is of the form:
			
					{ParamterName ParameterType}

To invoke a method, use the following syntax:
	
	<object id> do <method name> [<method parameters>]

The 'do' operator is optional iff methodname is not a reserved keyword by OpTcl.
Note that the return value a method call could be another script object. For example, in Excel, we could ask the application for a reference to the collection of 'Workbooks'. This call will return a new script object, with its own set of methods, properties and constants.

Properties
----------

To discover the properties of an object use the following syntax:

	<object id> properties

This returns a list of availble properties. Each element of this list is of the form:

	{propertyName propertyType writeAccess}


To set the value of a property, use the following syntax:

	<object id> set <propertyName> <propertyValue>

And read the value of a property:

	<object id> get <propertyName>


Constants
---------

The constants used by an object are grouped in 'Constant Groups'.  To retrieve all constant groups supported by an object use:

	<object id> constantgrps

This will return a list of group names.  To view constants stored within one group use:

	<object id> constants <groupName>

This will return a list where each element is of the form:

	{<constant name> <constant value>}

[note: some components pack all of their constants into one group and when there are a large number of these, the above query can take a little while (in the order of a few seconds)]

OpTcl also allows the retrieval of the value of one constant.  This is in the form of:

	<object id> constant <groupName> <constantName>


Reference counting
------------------
Version 1.1 has the ability to maintain and manipulate a reference count on an object. The syntax is as follows:

	# to increment the reference count
	<object id> addref

	# and to decrement
	<object id> releaseref

Both addition and release of the reference returns the current reference count on the object. When the reference count reaches zero the object automatically deletes itself.


An example of using OpTcl with Microsoft Excel
----------------------------------------------

The following script starts Excel, creates a workbook, make three entries, and creates a chart from them, and allows the user to manipulate to position of the chart from Tk using the buttons. The current version of OpTcl can be improved significantly to improve the speed of the binding process to the members of the object.

# Start of Excel demo

# load the OpTcl module
load Optcl1.dll Optcl1

# create the application 
set xl [socreate excel.application]

# make it visible
$xl set visible true

# we are going to make a 3D bar chart so cache this constant first
# note that this binding takes a significant amount of time due to the lack 
# of structure in and the large number of Excels constants.  It might be
# preferable for the developer to read this at development time, and hard code
# it into the script. This of course, impacts on the advantages gained through 
# dynamic binding.
set xl3DColumn [$xl constant Constants xl3DColumn ]

# get the workbooks collection and create a new workbook
set books [$xl workbooks]
set book [$books add]
$books releaseref

# get the current worksheet and rename it
set sheet1 [$book worksheets 1]
$sheet1 set Name "OpTcl Test"

# make three entries
set cell [$sheet1 cells 1 a]
$cell set formula 1
$cell releaseref

set cell [$sheet1 cells 1 b]
$cell set formula 2
$cell releaseref

set cell [$sheet1 cells 1 c]
$cell set formula 3
$cell releaseref

set range [$sheet1 range a1 c1]
$range select
$range releaseref

# create a chart
set charts [$book charts]
set chart [$charts add]
$charts releaseref

# set the chart to xl3DColumn type
$chart set type $xl3DColumn

set rotate 20
$chart set rotation $rotate

# create a bunch of buttons to manipulate the charts orientation
# and to quit the demo

button .left -text "<" -font {Arial 12 {bold}} -command {
	incr rotate
	if {$rotate >= 360} {set rotate 0}
	$chart set rotation $rotate
}

button .right -text ">" -font {Arial 12 {bold}} -command {
	incr rotate -1
	if {$rotate <= 0} {set rotate 360}
	$chart set rotation $rotate
}

button .quit -text "Quit" -font {Arial 12 {bold}} -command {
	$book set saved True
	$xl quit
	sodestroyall
	exit
}

pack .left .right .quit -side left