Installation and Usage

Installation requirements and usage instructions

DESCRIPTION

System Requirements

The current version of the TWAPI extension supports Windows 2000 and later.

TWAPI also requires Tcl 8.4 or higher. It will not load on older versions of Tcl.

Distribution formats

Each TWAPI package comes in multiple forms. The main twapi package distribution comes in three forms: a ZIP archive ("twapi-VERSION.zip"), a single file Tcl module ("twapi-VERSION.tm") for Tcl 8.5 and above, and a Starkit ("twapi-VERSION.kit").

The subset packages twapi_desktop and twapi_server are only distributed as single file Tcl modules and Starkits.

To install the ZIP distribution, unzip it into a directory and add the location of the twapi distribution directory to your Tcl auto_path variable.

The Tcl module distributions can be used with Tcl 8.5 or later. To install, copy the file into one of the directories returned by Tcl's ::tcl::tm::path list command.

The Starkit distributions are self-contained except for the documentation. To use one of these distributions, simply use the Tcl source command to read it into your Tcl interpreters.

Some factors to consider in choosing the distribution:

• The ZIP distribution is the most complete, including a test suite for testing the installation using Tcl's tcltest command. It also makes it easy to look through or adapt the Tcl script level code if required.
• The Starkit is the most compact on-disk if distribution size is a factor.
• The Tcl module distribution loads the fastest. However, it can only be used with Tcl 8.5 or later.
• Both the Starkit and Tcl module distributions write the TWAPI DLL component to a temporary directory before calling the OS loader. They therefore cannot be used in read-only disk environments. However, this writing is done only the first time a specific TWAPI build is loaded. The written DLL is identified by a GUID that is specific to every TWAPI build and not rewritten if it already exists.

Loading TWAPI

Once installed, TWAPI can be loaded using the command package require PACKAGENAME where PACKAGENAME is one of twapi, twapi_desktop or twapi_server. Note that with the Starkit distribution, you still need to source the file before invoking this command.

Commands

All commands installed by this extension fall under the twapi:: namespace even if you load the twapi_server or twapi_desktop packages.

The commands are not exported from the namespace by default. To import the commands, they must first be exported by calling ::twapi::export_public_commands. Alternatively, you can call ::twapi::import_commands to import all TWAPI commands.

COPYRIGHT

Copyright © 2003-2009 Ashok P. Nadkarni