If there are creation arguments given for a tot, then the first argument specifies the name of a destination window.  A tot object created without arguments, or with a dot put in place of the first argument, interfaces its containing window.  Thus, any tot object has its destination window specified (although it does not matter if that window actually exists, as long as it is not referenced in a scriptlet).

Apart from a literal name of a destination window, and the single-dot symbol, the first argument might also take the value of one of the following reserved symbols:  .parent (parent window of the containing subpatch),  .root (root window of the containing document), .owner (parent of the root), .top (top-level patch window). 

The creation of a destination window is reported through the rightmost outlet of a tot object.

An optional second argument to a tot object specifies a scriptlet file to be read during object's creation.  The read and write messages enable scriptlets to be loaded and saved on the fly.

When a tot object is clicked at, an editor window opens for a scriptlet currently held by a tot.  Editing is not supported yet;  instead, a scriptlet saved to a file (using the write message) may be edited externally, and then loaded back into a tot.

A scriptlet held by a tot is the persistent scriptlet.  An object triggers the transfer of its persistent scriptlet after receiving a push or a qpush message (the difference between the two is explained below).

Another possibility is passing a transient scriptlet for immediate transfer, using tot and query messages.

The transferring messages, push and qpush, accept up to nine arguments, which are substituted for the corresponding dot-parameters in the scriptlet's body.

Scriptlets may be transfered in two modes: command and query.  If a Tcl command (or, in case of a multi-command scriptlet, last Tcl command) being executed for a query-transfered scriptlet, returns a value, then this value is transfered back, and sent through the tot's left outlet.  In case of a command-transfered scriptlet, there is no feedback, other than by using callback sequences.

A persistent scriptlet is command-transfered, after a tot receives a push message.  Or it is query-transfered, after receiving a qpush message.

A transient scriptlet specified in a tot message is command-transfered.  A scriptlet specified in a query message is query-transfered.

It is possible to build persistent scriptlets incrementally, using reset, add, and addnext messages.  This feature makes bulky transfers easier and more robust.  Sometimes, it is also more convenient to build and push a multi-command persistent scriptlet using several addnext messages, instead of putting several .: separators in a transient scriptlet.

The tot does not impose any limit on the length of a scriptlet, persistent or transient.  Each tot object maintains two separate, resizable buffers for that purpose -- if these buffers are not large enough, they grow automatically (and synchronously).  Successive scriptlets reuse them, or stretch even more.  However, the buffers never shrink automatically.  Instead, their size in bytes, smaller or bigger than the current, might be specified explicitly with a prealloc message.  The obligatory numeric argument to this message is <persistent-size> (transient scriptlet's buffer is adjusted automatically).

However, only scriptlets of limited size (20kb) may be pushed.  This constraint is likely to be lifted some day, but not very soon...

Since the tot does no syntax checking, it is easy to corrupt things, by omitting a closing bracket, etc.  Exceptions are not handled by the tot, although it is always possible to put a catch clause into a scriptlet.

The tot's third outlet optionally captures a stream of Pd gui messages dealing with user control over a destination canvas.  This is a tricky and unreliable feature -- use with care.

In order to enable capturing, a tot should receive a capture message with a nonzero float argument.  If this message contains a second, symbol argument, then the output stream is preformatted and time-stamped, ready to be recorded in a qlist.  The symbol argument defines the target atom of qlist messages.  The first argument equal zero stops capturing.

The presentation playback could easily be spoiled by interleaving gui messages streamed out from a qlist, with gui messages generated interactively.  Therefore, in order to suspend processing of interactive messages, a tot targeting the same destination canvas which is used for a presentation, should detach its canvas before playback, and attach it afterwards.

The lastmotion message copies the destination window's current mouse position to another window specified by a message argument.  This is a criptic message needed in certain cases of capturing.  It works only for a capturing tot.

complaints to this address