









	========================
        tclXess Reference Manual
	========================

	tclXess 1.0.0 Beta

	Copyright (C) 1994 Applied Information Systems
	100 Europa Drive, Suite 555, Chapel Hill, NC 27514

	Permission is granted to make verbatim copies of this
	reference manual, but permission is not granted to
	sell copies or to distribute changes without explicit
	written permission from Applied Information Systems, Inc.

	All rights reserved, Applied Information Systems.

	($Revision: 1.16 $)

INTRODUCTION
============

tclXess is an application which maps the Xess
Connections API to a tcl interface.  Using it requires
some knowledge of the tcl language, and optionally the
tk widget set, which is included in the tclXess binary.
Both are documented in the book _Tcl_and_the_Tk_
Toolkit_, by John Ousterhout, the creator of Tcl and
Tk. They are also documented in the Tcl and Tk
reference documentation, which comes with the Tcl and
Tk source distributions in the form of standard manual
pages.  Tcl and Tk source distributions are available
via ftp from harbor.ecn.purdue.edu in the /pub/tcl
directory.

The Xess Connections API is documented in the Xess
API User's Guide, which is available from AIS.  The
reference section of this manual tells which API
functions are called by each tclXess command, and
the Xess API User's Guide may be useful if you
need more information about a command than is given here.


There are two types of commands in tclXess.  The first
type of command is the imperative `xess' command, and
always follows the format
	xess <subcommand> ?arguments?
and the second is an `object' command, which follows the format
	<object> <action> ?arguments?

Tcl objects are created by other tcl commands.  For
example, a "connection object", which will be referred
to as a <connection>, is created with the
	xess connect <connection> ...
command.  Once that command has completed successfully,
<connection> becomes a legal tcl command, which has
many subcommands, for example,
	<connection> get_location
which returns the location of the cursor in the Xess
instance connected to the object specified by
<connection>.  This design is very much like the design
of Tk, and is well documented in _Tcl_and_the_Tk_
Toolkit_, so if it is difficult to understand, get and
read that book, which (naturally) goes into more detail
on the subject.  The only real difference from Tk objects
is that there is no inherent hierarchy of objects, although
you are encouraged to create a hierarchy in your object names
if you intend to manage more than one simultaneous
connection, and this philosophy will be borne out in the
examples.

This manual is a work in progress, and is missing many
examples.  It may also not be perfectly complete.
Please send any corrections and/or suggested changes to
me as michael@ais.com, or by snail mail to

	Michael K. Johnson
	Applied Information Systems
	100 Europa Drive, Suite 555
	Chapel Hill, NC 27514

or by phone at 919-942-7801, or by fax at 919-493-7563.

COPYRIGHT
=========

The tclXess interpreter code is held under the following copyright:

    Copyright (c) 1994 Applied Information Systems.  All rights reserved.
    Copyright (c) 1992 General Electric.  All rights reserved.
 
    Permission to use, copy, modify, and distribute this
    software and its documentation for any purpose and without
    fee is hereby granted, provided that the above copyright
    notice appear in all copies and that both that copyright
    notice and this permission notice appear in supporting
    documentation, and that the name of General Electric not be used in
    advertising or publicity pertaining to distribution of the
    software without specific, written prior permission.
    General Electric makes no representations about the suitability of
    this software for any purpose.  It is provided "as is"
    without express or implied warranty.

    This work was supported by the DARPA Initiative in Concurrent
    Engineering (DICE) through DARPA Contract MDA972-88-C-0047.

This copyright does not apply to this reference manual.  See
the copyright notice on the title page for the copyright to this
manual.

CELL REFERENCES
===============

Cell references in tclXess are written just as in Xess: C11 refers
to the same cell in Xess and in tclXess.  Ranges also are
done the same way: B12..C34 refers to the same range in
Xess and in tclXess.

However, note that a literal `$', used to denote "absolute
references", needs to either be escaped with a `\' character
or be enclosed in {}'s to keep the tcl interpreter from
attempting to interpret the name as a variable.
Otherwise, tcl will give an error like
	can't read "C10": no such variable
unless you also have a variable named C10, in which case
you have an even worse problem; your code may execute,
possibly without errors, but produce incorrect results.

You may want to consider a policy of always enclosing
literal column, row, cell, and range references in {}'s
to avoid any possibility of encountering this problem.

STANDARD RETURNS AND ERRORS
===========================

In this manual, return values for commands that do not
explicitly return a value are often referred to as
"Standard".  This means that if the command succeeded,
it returns a null string and does not "throw an error".

All functions may return some subset of this list of
standard errors.  If a function can return errors other
than ones in this list, those errors are noted in the
command reference.

"connection closed unexpectedly"
	The Xess Connections API Library has reported that a
	connection which tclXess expects to be open has closed.

"<function> returned unexpected status <status>"
	The Xess Connections API Library has returned a status
	that tclXess has not been explicitly programmed to
	understand.  There is probably a problem, but tclXess
	is not sure what it is.

"unable to connect to display"
	tclXess has failed to connect to the display.  Fix
	this as you would for any X program.

"wrong # args, should be ???"
	Standard error message.  Note that it can occasionally
	be issued when you have the right number of arguments,
	but are using an unrecognized option name. This is
	a bug and should be reported.

STANDARD METAVARIABLES
======================

There are several standard "metavariables" which are used
in the command reference section.  These are to be
replaced with various values when you use the commands.

<cell>

Stands for a cell value, which is in the same format as a
cell value given to Xess: A letter or letters indicating
the column and a number indicating the row.  Each of
these components may be prefixed with a `$' character to
indicate that it is to be absolute reference which never
changes, even when the spreadsheet shifts or a cell
containing the cell value is moved.

<row>

A valid Xess row specification; a digit or digits between
1 and 32767, optionally prefixed by a `$' character to
indicate an absolute reference that does not change, even
when the context of evaluation changes.  See <cell>.

<column>

A valid Xess column specification; a letter or letters
"between" A and FAN (case insensitive), optionally
prefixed by a `$' character to indicate an absolute
reference that does not change, even when the context of
evaluation changes.  See <cell>.

<range>

A valid Xess range specification, in the form <cell>..<cell>

<connection>

This is a "connection object".  Connections to instances
of Xess are created by procedures which take a name for
the "connection object".  This name is bound to a tcl
command which takes many arguments which act on that
connection.  Connection objects are created with the
"xess connect" command.

<menu>

This is a "menu object".  Menus are created with the name
for the corresponding "menu object", which is then used
to manipulate the object, just like the <connection> does
for the whole instance of Xess.  Menu objects are created
with the "<connection> menu" command.

<button>

This is a "button object".  Buttons are created with the
name for the corresponding "button object", which is then
used to manipulate the object.  Button objects are created
with the "<menu> button" command.

<display>

An X DISPLAY specification, like unix:0 or foo.edu:0 or
my.machine.in.my.domain:1.5

<window>

An integer window ID.

<command>

A <command> is a string of valid tcl code; a tcl command.

A <command> may take "standard %-substitutions" in the
spirit of Tk %-substitutions.  Where this is true, here
is a table of substitutions:

	%% - (ALWAYS ACCEPTED) - A literal percent sign.
	%B - The name of a button that was pressed.
	%C - The name of the connection object
	%D - The name of the display on which the Xess instance is running
	%M - The name of a menu from which a button was selected.
	%N - Xess's symbolic name for the connection.
	%P - The connection's port number.
	%W - The X window ID of the Xess instance.
	%m - The message received from another Xess client

<proc>

A <proc> is the *name* of a tcl procedure (not a tcl script).
The arguments that the procedure takes are defined wherever
<proc> is used.

<value>

A value defined in the explanation; usually an integer.

<int>

An integer expression

<text>

Some string.

<list>

A tcl list, the format of which is specified where it is used.

<expr>

A valid Xess expression.

<filename>

A valid filename on the system on which the instance of
Xess being referred to is running.

<filetype>

When referring to printfiles, "ascii" or "ps".  When
referring to import or export files, one of "wks", "wk1",
"csv", "tsv", "tex", or "text".

EXAMPLES
========

The examples are shown as if you are typing them directly to the
tclXess interpreter: they are preceded by the tclXess prompt, "%",
and responses from the interpreter are clearly marked with "==>",
so interaction that looks like this:

	% xess connect foo
==>	foo

means that tclXess presented the "%" prompt, the user typed
"xess connect foo", and the interpreter responded "foo".

COMMAND REFERENCE
=================

Xess Connection Functions
*************************

<connection> close

Returns: standard

Errors: Standard

Closes the connection specified by <connection>.

Library: xess_close_connection()



xess connect <connection> ?options?

Options:
	-name <connection name> (default: "Tk")
		Name of connection, as shown in the Xess "Connections List".

		Equivalent to name argument to xess_establish_connections().

	-timeout <int> (default: 30)
		Sets timeout to <int> seconds.  If the instance of Xess
		does not respond in that time, the connection attempt
		fails and connect returns an error.

		Equivalent to the timeout argument to
		xess_establish_connections().

	-display <display> (default: current Tk default display; $DISPLAY)
		Connect to the Xess instance currently accepting connections
		on display <display>.

	-closecommand <command>
		Records <command> to be a command to execute when the
		connection is closed unexpectedly.  <command> may contain
		any of the standard substitution keys %C, %D, %N, %P, or
		%W, described under STANDARD METAVARIABLES.

		This tcl command is not called when an explicit
		<connection> close command is issued, only when
		an asynchronous close is initiated by the Xess
		instance that it is connected to.

		Default is no callback; this behavior may be selected
		explicitly by presenting an empty string as the
		<command> parameter.

		Established with xess_set_close_notify().

	-messagecommand <command>
		Records <command> to be a command to execute when a
		message is received from another client connected to the
		same Xess instance.  The default is no callback;
		this behavior may be selected explicitly by presenting an
		empty string as the <command> parameter.

		<command> may contain any of the standard substitution
		keys %C, %D, %N, %P, %W, or %m, described under
		STANDARD METAVARIABLES

The <connection> parameter is bound as a tcl command to be
used for "object commands", which are documented below.
This overrides and erases any tcl commands which already
have this name.  For instance, if you call your object
"if", if will become a command name, and the normal
behavior of "if" will no longer exist, which will mess up
tcl, tk, and most likely your script.

Returns: The <connection> parameter is returned.

Errors: Standard
	"xess connection library refused to register display"
	"xess connection library has lost registration for display"
	"connection refused or timed out"

Examples:
	% xess connect con -name myname \
	-closecommand {
	  puts stderr "Xess connection on display %D closed unexpectedly."
	}
==>	con
	% xess connect con2 -name myname -display remotemachine:0.0 \
	-closecommand {
	  puts stderr "Xess connection on display %D closed unexpectedly."
	}
==>	con2


Library: xess_establish_connection(), xess_set_close_notify()




xess scan ?-display <display>?

Returns a list of connection window ID's for all
instances of Xess found on the specified display.

Errors: Standard
	"unable to connect to display"
	"xess connection library refused to register display"
	"xess_scan_display failed for display"

Library: xess_new_display(), xess_scan_display()

Xess Utility Functions
**********************

xess decode_cell <cell>

Takes an Xess cell specification (e.g. B11), and returns
a three element list, comprising a row number, a column
number, and a string of two binary digits, which
represent the absolute addressing flags, row first.

Errors: Standard

Examples:
	% xess decode_cell B11
==>	11 1 00
	% xess decode_cell {$C10}
==>	10 2 01




xess encode_cell <list>

Takes a three element list, comprising a row number, a
column number, and a string of two binary digits,
equivalent to the returned value from decode_cell, and
returns an Xess cell specification.

Errors: Standard

Examples:
	% xess encode_cell 11 1 00
==>	B11
	% xess encode_cell 10 2 01
==>	$C10



xess decode_column <column>

Takes an Xess column specification (e.g. $AY) and returns
a two element list comprising its column number and a
binary digit that is 1 if the column is addressed
absolutely (with $) and 0 otherwise.

Errors: Standard

Examples:
	% xess decode_column B
==>	1 0
	% xess decode_column {$B}
==>	1 1




xess encode_column <list>

Takes a two element list, comprising a column number
and a binary digit, and returns an Xess column
specification.

Errors: Standard

Examples:
	% xess encode_column 1 0
==>	B
	% xess encode_column 1 1
==>	$B




xess decode_range <range>

Takes an Xess range specification (e.g. AY$10..$BB13),
and returns a two-element list comprising the cell
specifications of the two ends of the range, in the form
returned by decode_cell.

Errors: Standard

Examples:
	% xess decode_range {B$12..$G34}
==>	{12 1 10} {34 6 01}




xess encode_range <list>

Takes a list comprising two three-element lists, and
returns the equivalent Xess range specification.

Errors: Standard

Examples:
	% xess encode_range {12 1 10} {34 6 01}
==>	B$12..$G34




xess decode_row <row>

Takes an xess row specification (e.g., $17), and returns
a two element list comprising a row number and a binary
digit that is 1 if the row is addressed absolutely (with
a $) and 0 otherwise.

Errors: Standard

Examples:
	% xess decode_row {17}
==>	17 0
	% xess decode_row {$17}
==>	17 1




xess encode_row <list>

Takes a two-element list, and returns a valid xess row
specification.

Errors: Standard

Examples:
	% xess encode_row 17 0
==>	17
	% xess encode_row 17 1
==>	$17




xess flush

Flushes all Xess connection ports.  Using `<connection> flush' is
the preferred way to flush connections, but in case there is a good
reason to flush all ports, this command is also provided.

Returns: Standard

Errors: Standard

Library: xess_flush()

Cursor Functions
****************

<connection> get_location

Returns: current position of the Xess cursor of the
connection named <connection> as a string; e.g. "A1".

Errors: Standard

Examples:
	% con get_location
==>	A1
	% con moveto G11
	% con get_location
==>	G11
	% con goto I14
	% con get_location
==>	I14

Library: xess_get_location()




<connection> goto <cell>

Moves the Xess cursor of the connection named <connection> to
the specified cell (e.g. "A1") and scrolls the sheet to put
the specified cell in the upper-left-most of the view.

Returns: Standard

Errors: Standard

Examples:
	*see get_location above*

Library: xess_goto()




<connection> moveto <cell>

Moves the Xess cursor of the connection named <connection> to
the specified cell (e.g. "A1") but does not scroll the
sheet so that the current cell is at the upper-left-most
of the view.  This is more analogous to ordinary movement
with the mouse, scrollbar, or arrow keys than is goto.

Returns: Standard

Errors: Standard

Examples:
	*see get_location above*

Library: xess_moveto()

Event Handling
**************

<connection> user_lock <value>

Locks out or allows direct manipulation of the Xess
spreadsheet by a user.  If <value> is 1, the <connection>
connection is locked, and if it is 0, the conection is
unlocked.

Returns: Standard

Errors: Standard

Library: xess_user_lock()




<connection> flush

Causes the <connection> connection to flush all remaining
events from the event queue.

Returns: Standard

Errors: Standard

Library: xess_flush_port()

Get Functions
*************

<connection> get_value <cell>

Returns the value in the cell specified by <cell> in the
Xess instance specified by <connection>.

Errors: Standard
	"empty cell <cell>"

Examples:
	% con get_value A1
==>	empty cell A1
	% con get_value B2
==>	211.000
	% con get_value C3
==>	this is a string
	% con get_value D4
==>	3.00000

Library: xess_get_value()




<connection> get_string <cell>

Returns the value in the cell specified by <cell> in the
Xess instance specified by <connection>, formatted as a
string, which means formatted as it would be displayed by
Xess on the screen.

Errors: Standard
	"empty cell <cell>"

Examples:
	% con get_string A1
==>	empty cell A1
	% con get_string B2
==>	211
	% con get_string C3
==>	this is a string
	% con get_string D4
==>	3

Library: xess_get_string()




<connection> get_number <cell>

Returns the numeric value of the contents of the cell
<cell> in the Xess instance specified by <connection>.

Errors: Standard
	"empty or non-numeric cell <cell>"

Examples:
	% con get_number A1
==>	empty or non-numeric cell A1
	% con get_number B2
==>	211
	% con get_number C3
==>	this is a string
	% con get_number D4
==>	3.00000

Library: xess_get_number()




<connection> get_formula <cell>

Returns the formula value of the cell.  The result includes
the equal sign, double quote, or caret that flags the
type of formula.

Errors: Standard
	"empty cell"

Examples:
	% con get_formula A1
==>	empty cell A1
	% con get_formula B2
==>	=211
	% con get_formula C3
==>	this is a string
	% con get_formula D4
==>	=@SUM(1,2)

Library: xess_get_formula()

Store Functions
***************

<connection> store <cell> <value>

Stores the value <value> in the cell <cell> of the Xess
instance specified by <connection>.

Errors: Standard

Examples:
	% con store B2 211.000
	% con store C3 "this is a string"
	% con store D4 =@SUM(1,2)

Library: xess_store_number(), xess_store_formula(),
	xess_store_label()




<connection> store_formatted_number <cell> <value> ?options?

Stores <value> in cell <cell> in the Xess instance
specified by <connection> in the format specified by
?options?.

Options:
	-places <n> (Default: 8)
		Number of decimal places
	-font <fontstyle>
		Valid values for <fontstyle> are "default",
		"normal", "bold", and "bolditalic"
	-format <char>
		<char> is a character which determines the format
		to use:
		*	Xess default format (default for tclXess, too)
		e	Scientific notation
		f	Fixed point
		g	General
		$	Dollar amount
		,	Comma-delimited
		h	Hex
		l	Logical
		a	dd-mmm-yy
		b	dd-mmm
		c	mmm-yy
		d	mm/dd/yy
		i	Hidden
		t	hh:mm:ss
		%	Percentage
		x	Text

Returns: Standard

Errors: Standard

Examples:
	% con store_formatted_number A1 2.111 -places 2 -format e
	% con get_string A1
==>	2.11e+00
	% con store_formatted_number A2 234 -format h  
	% con get_string A2
==>	0xEA

Library: xess_store_formatted_number()




<connection> store_formula <cell> <formula>

Stores the formula <formula> in the cell <cell> in the
Xess instance specified by <connection>.  The formula
will need to be recalculated with <connection> recalculate
to recalculate the function.  This is an optimization to
speed storing many formulas at once; only one recalculation
needs to be done after storing a large block of functions.

Returns: Standard

Errors: Standard

Examples:
	% con store_formula B3 =@SUM(1,2)
	% con get_string B3
==>	0
	% con recalculate B3
	% con get_string B3
==>	3

Library: xess_store_formula()




<connection> store_label <cell> <label>

Stores the label <label> in the cell <cell> in the Xess
instance specified by <connection>.  Labels are stored as
strings, even if they resemble something else, such as
a formula.

Returns: Standard

Errors: Standard

Examples:
	% con store_label B4 "This is a string"
	% con get_value B4
==>	This is a string
	% con store_formula B5 =@SUM(1,2)
	% con get_value B5
==>	3.00000
	% con store_label B6 =@SUM(1,2)
	% con get_value B6
==>	=@SUM(1,2)

Library: xess_store_label()




<connection> store_number <cell> <number>

Stores the number <number> in the cell <cell> in the Xess
instance specified by <connection>.

Returns: Standard

Errors: Standard
	"expected floating-point number but got..."

Examples:
	% con store_number B7 1.23456789
	% con get_number B7
==>	1.23457
(internal rounding)
	% con get_string B7
==>	1.2345679
(as displayed in view)
	% con get_formula B7
==>	=1.23456789
(as stored)

Library: xess_store_number()




<connection> store_tagged_number <cell> <number>

Stores the number <number> in the cell <cell> in the Xess
instance specified by <connection>, with a tag identifying
the cell as depending on the cell currently being calculated.
This function can only be called from within an external
function; it has no meaning otherwise.  See also install_function
below.

Returns: Standard

Errors: Standard
	"expected floating-point number but got..."

Library: xess_store_tagged_number()

Miscellaneous Functions
***********************

<connection> test

Tests the xess connection.

Returns: Null string and successful return on success,
throws an error if an error occurs.

Errors: Standard
	Throws "conection closed" *and deletes the <connection> object*
	if the xess connection library reports an error.

Library: xess_test_connection()




<connection> message <text>

Cause the Xess instance specified by <connection> to display
<text> in the status area at the bottom of the screen.

Returns: Standard

Errors: Standard

Library: xess_display_message()




<connection> version

Returns: a string containing the version number of the
Xess instance specified by <connection>.

Errors: Standard

Library: xess_version()




<connection> install_function <name> <proc>

Installs a tcl procedure as an external Xess function.
The install_function command makes a tcl procedure be
available as an @-function in a spreadsheet.  When such a
function is evaluated during recalculation, the tcl
procedure is called, with a tcl representation of the
parameters.  Each parameter may be:
- a number, expressed in %#g format,
- a cell, expressed like a <cell>,
- a range of cells, expressed as a <range>,
- a string,
- an error message from a previous calculation
The function returns the expected value of the cell.  If
it throws an error, the error message is returned as an
error message to Xess.


During the execution of the function, the following
global variables are set:
	$xess_connection
		Set to the connection ID that initiated
		the function call
	$xess_current_cell
		Set to the current cell in the spreadsheet
	$xess_flags
		This variable is an array, with the
		following members:
		RECALC
			Set to 1 if a recalculation is in
			progress, and 0 otherwise.
		FORCE_RECALC
			Set to 1 if a forced recalculation
			is in progress, and 0 otherwise.
		FULL_RECALC
			Set to 1 if a full recalculation
			is in progress, and 0 otherwise.
		MANUAL_MODE
			Set to 1 if automatic recalculation
			is disabled, and 0 otherwise.
		CONSTRAINT_MODE
			Set to 1 if constraint checks are
			*off*, and 0 otherwise.
		CONSTRAINT
			Set to 1 if a function was invoked
			from a constraint expression, and
			0 otherwise.
		CONV_WARN
			Set to 1 if a floating point conversion
			error has occurred in parameter transmission.

Returns: Standard

Errors: Standard

Library: xess_install_function()




<connection> find_label <text> ?-in <range>?

Find a label <label> in the spreadsheet, or in the range
<range> if <range> is specified.

Returns: the cell position of the first occurrence of the
label as a <cell>.

Errors: Standard
	"label not found"

Library: xess_find_label(), xess_find_label_in_range()

Constraint Functions
********************

<connection> evaluate_constraint <cell>

Test the constraint in cell <cell>.

Returns: empty string if the constraint is satisfied

Errors: Standard
	"constraint violation" if the constraint is not satisfied.

Library: xess_evaluate_constraint()




<connection> recalculate_constraints

Tests all the constraints in the entire spreadsheet.

Returns: empty string if all constraints are satisfied.
If some constraints are violated, an error is thrown
and the number of failed constraints is returned.

Errors: Standard
	"<int> constraints violated"

Library: xess_recalc_constraints()

Dialog Functions
****************

<connection> dialogue ?options?

Options:
	-prompt <text>
		Specifies the <text> with which to prompt the user.  The
		default is `Input requested from application', which
		is not terribly informative.
	-default <text>
		Specifies the data with which to pre-initialize the entry
		area of the dialog box.  The default is the empty string.
	-busycommand <command>
		Specifies a tcl command to be executed if the dialog
		fails because Xess had another dialog in progress.
		The default is the null string, which does nothing.
	-cancelcommand <command>
		Specifies a tcl command to be executed if the dialog
		fails because the user presses the `cancel' button.  The
		default is the null string, which does nothing.
	-command <command>
		Specifies the tcl command to execute if the dialog
		succeeds.  The default is the null string, which does
		nothing

All the <command>s take the standard %C, %D, %N, %P,
%W, and %m substitutions.  The %m substitutions gives
the user's input to the dialog.

Returns: Standard

Errors: Standard
	"another dialog is active"

Library: xess_dialog()

Evaluation Functions
********************

<connection> recalculate ?-force? ?<range>?

Recalculate a range of cells indicated by the range
<range>.  If the -force option is specified, the recalc
is processed even if the current recalculation mode is
manual.  If no range is specified, the entire spreadsheet
is recalculated.

Returns: Standard

Errors: Standard
	"recursive user of recalculate is forbidden"

Library: xess_recalc()




<connection> evaluate_cell <cell>

Evaluate the cell specified by the cell <cell>.

Returns: the value of the cell after evaluation in
"%#g" format if it is a number, and as a string if it
is a string.

Errors: Standard
	"cell <cell> is empty"

Library: xess_evaluate_cell()




<connection> evaluate_expression <expr>

Evaluates the Xess expression <expr> in the context of
the Xess instance specified by <connection>.

Returns: the result of the evaluation in "%#g" format
if it is a number, and as a string if it is a string.

Errors: Standard
	"error in evaluation"

Library: xess_evaluate_expr()

File and Printing Functions
***************************

<connection> read_file <filename>

Causes the instance of Xess connected to <connection> to
read the Xess file <filename>.

Returns: Standard

Errors: Standard
	"couldn't read <filename>"

Library: xess_read_file()




<connection> write_file <filename>

Causes the instance of Xess connected to <connection> to
write the current spreadsheet to the file <filename>

Returns: Standard

Errors: Standard
	"couldn't write <filename>"

Library: xess_write_file()




<connection> print <range> ?options?

Options:
	-into <filename>
		Specifies the name of the file to receive the print data.
		Default is to use the printer specified in the current
		Printer Characteristics.
	-type <filetype>
		Specifies the type of printing: "ascii" for ascii output
		or "ps" for PostScript output.  The default is "ascii".

Returns: Standard

Errors: Standard
	"couldn't print"

Library: xess_print()




<connection> import -at <cell> -from <filename> ?-type <filetype>?

Imports the file <filename> into the spreadsheet
starting at cell <cell>.  <filetype> may be one of
"text" (text format; default), "csv" (comma seperated
values), "tsv" (tab seperated values), "xsc" (xess cell
format), "xc3" (xess3 cell format), "wks" (lotus), or
"wk1" (newer lotus).  The default is to get the type of
file from the extension of <filename>.  If the file
type cannot be determined, text is assumed.

Returns: Standard

Errors: Standard
	"-at option must be supplied"
	"-from option must be supplied"
	"unknown file type"
	"couldn't import"

Library: xess_import()




<connection> export -from <range> -to <filename> ?-type <filetype>

Exports the range <range> of the spreadsheet into the
file <filename>.  <filetype> may be one of "text" (text
format; default), "csv" (comma seperated values), "tsv"
(tab seperated values), "xsc" (xess cell format), "xc3"
(xess3 cell format), "wks" (lotus), "wk1" (newer
lotus), or "tex" (latex table format).  The default is
to get the type of file from the extension of
<filename>.  If the file type cannot be determined,
text is assumed.

Returns: Standard

Errors: Standard
	"-at option must be supplied"
	"-from option must be supplied"
	"couldn't export"

Library: xess_export()

Menu Functions
**************

<connection> menu <menu> ?options?

Options:
	-name <text>
		Name under which the menu <menu> appears on the Xess menu
		bar.  The default is "Tk".  <text> should be no more
		than 10 characters long.

Creates the menu object <menu> needed for the other menu
commands.

Returns: Standard

Errors: Standard
	"-name requires argument of length 10 or less"

Examples:
	% foo menu foo.menu -name foo
==>	foo.menu
	% foo menu foo.long -name thisnameistoolong
==>	-name requires argument of length 10 or less

Library: xess_create_menu()




<connection> menus

Returns: a list of current menu object names for this
instance of tclXess.

Errors: Standard

Library: none




<menu> button <button> ?options?

Options:
	-name <text>
		Specifies the name under which the button should appear
		in the Xess menu.  The default is "NoName".
	-command <command>
		Specifies a tcl command to be executed when the button is
		pressed.  The default is the null string, which does nothing.

Creates a button in the menu specified by <menu>.

Returns: the name of the button object.

Errors: Standard
	"-name requires argument of length 15 or less"

Examples:
	% foo.menu button foo.menu.button -name "Bar" -command {
	  # Do some tcl stuff
	}
==>	foo.menu.button
	% foo.menu button foo.menu.button2 -name thisiswaytoolongforabutton
==>	-name requires argument of length 15 or less

Library: xess_create_button()




<menu> buttons

Returns: a list of the <button>'s associated with the
<menu>.

Errors: Standard

Library: none



<menu> configure -name <text>

Configure the menu <menu>.  <text> specifies the new name of
the label for the menu.

Returns: Standard

Errors: Standard

Library: xess_menu_label()




<menu> connection

Returns: the connection name (a <connection>) associated
with <menu>.

Errors: Standard

Library: none




<menu> delete

Deletes the menu and all associated resources, including
menu buttons.

Returns: Standard

Errors: Standard

Library: xess_delete_menu(), xess_delete_button()




<button> configure ?options?

Options:
	-name <text>
		<text> specifies the new name of the button as it appears
		in the <menu> associated with it.

	-command <command>
		New tcl command to be executed when the button is
		invoked.

Configures the button <button> with new values.

Returns: Standard

Errors: Standard

Library: xess_button_label()




<button> menu

Returns the <menu> object associated with the button
<button>.

Errors: Standard

Library: none




<button> delete

Deletes the button <button> from its parent menu

Returns Standard

Errors: Standard

Library: xess_delete_button()




<button> invoke

Invokes the tcl command associated with button <button>.

Returns: Standard

Errors: Standard

Library: none

Range Functions
***************

<connection> define_name <text> <range>

Make range <range> be a named range called <text> 

Returns: Standard

Errors: Standard
	"range not defined"

Examples:
	% con define_name foo A1..B6

Library: xess_define_name()




<connection> resolve_name <text>

Returns the range corresponding to the name <text> if one
exists.

Errors: Standard
	"range not resolved"

Examples:
	% con resolve_name foo
==>	A1..B6

Library: xess_resolve_name()




<connection> delete_name <text>

Deletes the named range <text>.

Returns: Standard

Errors: Standard

Examples:
	% con delete_name foo
	% con resolve_name foo
==>	range not resolved

Library: xess_delete_name()




<connection> get_range

Blocks and waits for the Xess user to specify a range.
For non-blocking input, use get_selected in connection
with user prompts.

Returns the range in standard Xess <range> form.

Errors: Standard

Library: xess_get_range()




<connection> get_selected

Returns the currently selected range for the spreadsheet.

Errors: Standard
	"no range selected"

Library: xess_get_selected()




<connection> get_extent

Returns the range that defines the bounding box of the
non-empty cells in the spreadsheet.

Errors: Standard
	"empty sheet"

Library: xess_get_extent()




<connection> scroll_range <range> <direction>

	<direction> is one of "-up", "-down", "-left", "-right"

Scrolls the range <range> one column or row in direction <direction>.

Returns: Standard

Errors: Standard
	"scroll direction not specified"

Library: xess_scroll_range()




<connection> copy_range -from <from-range> -to <to-range> -<type>

Copies the range <from-range> to the range <to-range>.
If -<type> is -values, the values are copied, and if
-<type> is -formulas, formulas are copied.  The default
type is formulas.

Returns: Standard

Errors: Standard
	"-to argument must be specified"
	"-from argument must be specified"
	"couldn't copy range"

Library: xess_copy_range()




<connection> erase_range <range>

Erases contents of the range specified by <range>.

Returns: Standard

Errors: Standard
	"range not erased"

Library: xess_erase_range()




<connection> move_range -from <range> -to <cell>

Move the contents of the range <range> to the range whose
upper-left corner is specified by <cell>.

Returns: Standard

Errors: Standard
	"-to argument must be specified"
	"-from argument must be specified"
	"range not moved"

Library: xess_move_range()




<connection> insert_rows -count <int> -at <row>

Insert <int> empty rows into the spreadsheet directly
above row <row>.

Returns: Standard

Errors: Standard
	"-at option must be supplied"
	"row(s) not inserted"

Library: xess_insert_rows()




<connection> insert_columns -count <int> -at <column>

Insert <int> empty columns into the spreadsheet directly
to the left of column <column>.

Returns: Standard

Errors: Standard
	"-at option must be supplied"
	"column(s) not inserted"

Library: xess_insert_cols()




<connection> delete_rows <from-row> <to-row>

Delete all the rows between <from-row> and <to-row>, inclusive.

Returns: Standard

Errors: Standard
	"row(s) not deleted"
	"rows out of sequence" (<from-row> must be less than <to-row>)


Library: xess_delete_rows()




<connection> delete_columns <from-column> <to-column>

Delete all the columns between <from-column> and
<to-column>,
inclusive.

Returns: Standard

Errors: Standard
	"column(s) not deleted"
	"columns out of sequence" (<from-column> must be less than <to-column>)

Library: xess_delete_cols()




<connection> clear_sheet

Clears the spreadsheet.

Returns: Standard

Errors: Standard
	"sheet not cleared"

Library: xess_clear_sheet()
