Objects

The manipulation of objects in OpTcl is performed with commands defined in the optcl namespace. The following is the synopsis of this namespace.

optcl::new ?-start? ?-window windowname? CLSID_ProgID_DocumentURL_HTML
optcl::lock objid
optcl::unlock objid ?objid ...?
optcl::isobject objid
optcl::interface objid ?new_interface_name?
optcl::class objid
optcl::bind objid eventname tcl_procedure
objid ?-with subobj? methodname ?arg ...?
objid ?-with subobj? : propname ?new_value?
objid ?-with subobj? : propname(index?, index ...?) ?new_value?

Description

optcl::new

The optcl::new command creates or attaches to existing COM objects, returning a unique object identifier, if successful. The -start flag is used to indicate that the call should always create a new instance of the object. The -window option creates with the COM object, a Tk widget that will attempt to in-place activate the user interface of the object. Not all COM objects provide a user interface, and not all objects with user-interfaces will in-place activate.

The final parameter of the command is an identifier for the COM class of the object. This can take four different forms: CLSID, ProgID, document path or raw HTML. Currently, the latter two only work with the -window option. A CLSID is a string representation of a COM Globally Unique IDentifer (GUID for short). CLSIDs uniquely identify the location of a COM class server through the system registry. To successfully create an instance of the COM class, the server must be correctly registered with the system registery. An example of a CLSID is {8E27C92B-1264-101C-8A2F-040224009C02} (the CLSID for the Calendar Control). In order to pass a CLSID correctly to the optcl::new command, the CLSID must be wrapped in an extra pair of braces. This will ensure that the bracing surrounding the CLSID is not stripped by the Tcl interpreter. For example, {{8E27C92B-1264-101C-8A2F-040224009C02}}. A ProgID (programmatic identifier) is a human readable name that performs the same job as a CLSID. For example, MSCAL.Calendar.7.

Additionally, the command can take two further forms of identifer. A URL to a document with a correctly registered document server, or an inline HTML. Both these options are only available currently with in-place activation only (-window option) and require the installation of Internet Explorer 4.0 or above. To use inline HTML, the source string must begin with the characters "mshtml:".

Reference Management

At the time of writing, OpTcl cannot provide a robust automatic handling of object lifetimes. So for now, the optcl::lock and optcl::unlock commands provide explicit means for respectively incrementing or decrementing the reference count on an object. On creation, the reference count of an object is one. If, the reference count of an object becomes zero, the object is destroyed, together with its Tk container window, if one exists. Furthermore, the destruction of a container window, will immediately destroy its related object.

optcl::isobject

The optcl::isobject command returns true if and only if its only parameter is an OpTcl object.

optcl::interface

The optcl::interface command performs the role of querying the current interface name of an OpTcl object, or setting it to a new interface type. COM objects are polymorphic, in that they can (and often do) support multiple interfaces. In OpTcl an interface name is a properly formed type, and hence can be browsed with the Type Library Access functionality of OpTcl. One can discover the supported interfaces of an object by finding and viewing details of its COM class. The initial interface of an object, is its default interface.

optcl::class

The optcl::class command returns the class name of the object. If no class name information is provided, the command returns '???'.

optcl::bind

The optcl::bind command binds an event from an object to a Tcl procedure name. The event can either be the name of an event on the default interface, or the name of an event on another event interface. The latter must take the form lib.eventinterface.event. The Tcl procedure will be called with the first parameter being the object identifier of the OpTcl object raising the event, followed by the parameters of the event itself.

Object Command

The object identifer returned from optcl::new, is also a Tcl command for the lifetime of the object. Using the command, we can invoke the object's methods, and properties. As a means to improving efficiency, both forms of member access can be applied to a sub-object of the invoked OpTcl object. Methods can be invoked on an object, by appending to the object command (with a possible sub-object), the method name and its parameters.

Access to properties of an OpTcl object are differentiated from method invocations by the placement of a : prior the property name, with white space seperating it from the name. For example to set the visible property of an object to true, we would use the following syntax:

	$myobj : visible 1

And to retrieve it:

	$myobj : visible
	==> 1

If the property is indexed, then its index can be specified within matching braces as a comma-seperated list. For example:

	$myobj : grid(3,4) "foo"

Sub-Objects

COM objects often have deep hierarchies of objects, reachable from the created object. In many cases it may be inefficient to represent several of these objects within the hierarchy as OpTcl objects, in order to access a single object. For this purpose, the object command can take the -with option. This is a dot seperated list of sub-objects that it has to traverse before invoking the method or property. For example:

	$app -with documents(1) save
	$xl -with workbooks(1).worksheets(sheet1).range(a1,b2) : value 15

Copyright (c) 1999, Farzad Pezeshkpour