	About Us	Search	Products
	Support	Download	Store

tclNExS Reference Manual

tclNExS 1.1

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 GreyTrout Software, Inc.

Introduction
Copyright
Cell References
Standard Returns and Errors
Standard Metavariables
Examples
Invoking tclNExS
Command Reference

Introduction

tclNExS is an application which maps the NExS 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 tclNExS 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 from the Tcl/Tk Developer Xchange, http://www.tcl.tk.

Prior releases of tclNExS were built as stand-alone binaries. This necessitated version-specific builds and limited the ability to conveniently use other extensions in conjunction with tclNExS. The current release eliminates the stand-alone binary and uses instead a dynamic load library implemented as a Tcl package. The tclNExS extensions are now loaded into the running "wish" executable by the command:

package require tclNExS

This is the only new feature in tclNExS 1.1. The NExS API Library is documented in the NExS API Guide, which is available from GreyTrout Software. The reference section of this manual tells which API functions are called by each tclNExS command, and the NExS API Guide may be useful if you need more information about a command than is given here.

There are two types of commands in tclNExS. The first type of command is the imperative `nexs' command, and always follows the format

	nexs <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

	nexs 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 NExS 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.

Copyright

The tclNExS interpreter code is held under the following copyrights:

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 tclNExS are written just as in NExS: C11 refers to the same cell in NExS and in tclNExS. Ranges also are done the same way: B12..C34 refers to the same range in NExS and in tclNExS.

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 NExS Connections API Library has reported that a connection which tclNExS expects to be open has closed.

"<function> returned unexpected status <status>"

The NExS Connections API Library has returned a status that tclNExS has not been explicitly programmed to understand. There is probably a problem, but tclNExS is not sure what it is.

"unable to connect to display"

tclNExS 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 NExS: 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 NExS 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 NExS 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 NExS range specification, in the form <cell>..<cell>

<connection>

This is a "connection object". Connections to instances of NExS 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 "nexs 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 NExS. 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 NExS instance is running.
	%M - The name of a menu from which a button was selected.
	%N - NExS's symbolic name for the connection.
	%P - The connection's port number.
	%W - The X window ID of the NExS instance.
	%m - The message received from another NExS 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 NExS expression.

<filename>

A valid filename on the system on which the instance of NExS 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", "text", "xsc", or "html".

Examples

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

	% nexs connect foo
==>	foo

means that tclNExS presented the "%" prompt, the user typed "nexs connect foo", and the interpreter responded "foo".

Invoking tclNExS

TclNExS is invoked by executing "wish" and dynamically loading the tclNExS shared library extensions using the "package require" command:

	$ wish
	% package require tclNExS
==>	1.1

A "wish" script for a tclNExS application would typically start like this:

	#!/bin/sh
	# the next line restarts using wish \
	exec /usr/bin/wish "$0" "$@"

	package require tclNExS

Command Reference

NExS Connection Functions

<connection> close

Returns: standard

Errors: Standard

Closes the connection specified by <connection>.

Library: nexs_close_connection()

nexs connect <connection> ?options?

Options:

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

		Equivalent to name argument to nexs_establish_connections().

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

		Equivalent to the timeout argument to
		nexs_establish_connections().

	-display <display> (default: current Tk default display; $DISPLAY)
		Connect to the NExS 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 NExS
		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 nexs_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 NExS 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

	"nexs connection library refused to register display"
	"nexs connection library has lost registration for display"
	"connection refused or timed out"

Examples:

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

Library: nexs_establish_connection(), nexs_set_close_notify()

nexs scan ?-display <display>?

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

Errors: Standard

	"unable to connect to display"
	"nexs connection library refused to register display"
	"nexs_scan_display failed for display"

Library: nexs_new_display(), nexs_scan_display()

NExS Utility Functions

nexs decode_cell <cell>

Takes an NExS 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:

	% nexs decode_cell B11
==>	11 1 00
	% nexs decode_cell {$C10}
==>	10 2 01

nexs 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 NExS cell specification.

Errors: Standard

Examples:

	% nexs encode_cell 11 1 00
==>	B11
	% nexs encode_cell 10 2 01
==>	$C10

nexs decode_column <column>

Takes an NExS 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:

	% nexs decode_column B
==>	1 0
	% nexs decode_column {$B}
==>	1 1

nexs encode_column <list>

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

Errors: Standard

Examples:

	% nexs encode_column 1 0
==>	B
	% nexs encode_column 1 1
==>	$B

nexs decode_range <range>

Takes an NExS 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:

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

nexs encode_range <list>

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

Errors: Standard

Examples:

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

nexs decode_row <row>

Takes an nexs 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:

	% nexs decode_row {17}
==>	17 0
	% nexs decode_row {$17}
==>	17 1

nexs encode_row <list>

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

Errors: Standard

Examples:

	% nexs encode_row 17 0
==>	17
	% nexs encode_row 17 1
==>	$17

nexs flush

Flushes all NExS 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: nexs_flush()

Cursor Functions

<connection> get_location

Returns: current position of the NExS 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: nexs_get_location()

<connection> goto <cell>

Moves the NExS 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: nexs_goto()

<connection> moveto <cell>

Moves the NExS 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: nexs_moveto()

Event Handling

<connection> user_lock <value>

Locks out or allows direct manipulation of the NExS 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: nexs_user_lock()

<connection> flush

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

Returns: Standard

Errors: Standard

Library: nexs_flush_port()

Get Functions

<connection> get_value <cell>

Returns the value in the cell specified by <cell> in the NExS 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: nexs_get_value()

<connection> get_string <cell>

Returns the value in the cell specified by <cell> in the NExS instance specified by <connection>, formatted as a string, which means formatted as it would be displayed by NExS 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: nexs_get_string()

<connection> get_number <cell>

Returns the numeric value of the contents of the cell <cell> in the NExS 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: nexs_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: nexs_get_formula()

Store Functions

<connection> store <cell> <value>

Stores the value <value> in the cell <cell> of the NExS 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: nexs_store_number(), nexs_store_formula(), nexs_store_label()

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

Stores <value> in cell <cell> in the NExS 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:
		*	NExS default format (default for tclNExS, 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: nexs_store_formatted_number()

<connection> store_formula <cell> <formula>

Stores the formula <formula> in the cell <cell> in the NExS 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: nexs_store_formula()

<connection> store_label <cell> <label>

Stores the label <label> in the cell <cell> in the NExS 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: nexs_store_label()

<connection> store_number <cell> <number>

Stores the number <number> in the cell <cell> in the NExS 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: nexs_store_number()

<connection> store_tagged_number <cell> <number>

Stores the number <number> in the cell <cell> in the NExS 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: nexs_store_tagged_number()

Miscellaneous Functions

<connection> test

Tests the nexs 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 nexs connection library reports an error.

Library: nexs_test_connection()

<connection> message <text>

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

Returns: Standard

Errors: Standard

Library: nexs_display_message()

<connection> version

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

Errors: Standard

Library: nexs_version()

<connection> install_function <name> <proc>

Installs a tcl procedure as an external NExS 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 NExS.

During the execution of the function, the following global variables are set:

$nexs_connection

Set to the connection ID that initiated the function call

$nexs_current_cell

Set to the current cell in the spreadsheet

$nexs_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: nexs_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: nexs_find_label(), nexs_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: nexs_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: nexs_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 NExS 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: nexs_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: nexs_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: nexs_evaluate_cell()

<connection> evaluate_expression <expr>

Evaluates the NExS expression <expr> in the context of the NExS 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: nexs_evaluate_expr()

File and Printing Functions

<connection> read_file <filename>

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

Returns: Standard

Errors: Standard

	"couldn't read <filename>"

Library: nexs_read_file()

<connection> write_file <filename>

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

Returns: Standard

Errors: Standard

	"couldn't write <filename>"

Library: nexs_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: nexs_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" (nexs cell format), "xc3" (nexs 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: nexs_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" (nexs cell format), "xc3" (nexs 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: nexs_export()

Menu Functions

<connection> menu <menu> ?options?

Options:

	-name <text>
		Name under which the menu <menu> appears on the NExS 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: nexs_create_menu()

<connection> menus

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

Errors: Standard

Library: none

<menu> button <button> ?options?

Options:

	-name <text>
		Specifies the name under which the button should appear
		in the NExS 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: nexs_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: nexs_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: nexs_delete_menu(), nexs_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: nexs_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: nexs_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: nexs_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: nexs_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: nexs_delete_name()

<connection> get_range

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

Returns the range in standard NExS <range> form.

Errors: Standard

Library: nexs_get_range()

<connection> get_selected

Returns the currently selected range for the spreadsheet.

Errors: Standard

	"no range selected"

Library: nexs_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: nexs_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: nexs_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: nexs_copy_range()

<connection> erase_range <range>

Erases contents of the range specified by <range>.

Returns: Standard

Errors: Standard

	"range not erased"

Library: nexs_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: nexs_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: nexs_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: nexs_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: nexs_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: nexs_delete_cols()

<connection> clear_sheet

Clears the spreadsheet.

Returns: Standard

Errors: Standard

	"sheet not cleared"

Library: nexs_clear_sheet()

tclNExS Reference Manual

tclNExS 1.1

Contents