[texworks] Scripting: TW.result and TW.target.consoleOutput

Thu Jun 23 18:58:33 CEST 2011

Hi,

On 2011-06-23 08:34, Paul A Norman wrote:
> I have been reading through Issues, latexErrors,js and the Wiki,
> trying to glean how these operate please.
>
> var message = "<html><body><br />Progress Copy Completed: <br /><a
> href=\"texworks:" + fileDetail + "\">" +  fileDetail + "</a><br
> /></body></html>";
>
>            TW.result = message;
>
> TW.result can receive an array?

TW.result in principle can receive any supported data, including arrays,
or even objects, windows, ...
For the AfterTypeset hook, however, only strings are used (i.e.,
whatever you put in there will be converted to a string internally
(TeXDocument.cpp l.2632)). This has changed a bit over time (in some
previous versions, arrays were supported separately, but this is no
longer necessary).

> "texworks:" + filePath    ...
>
> ... as an <a href=   Causes a link to appear which when clicked opens
> the document in Tw editor.

Yes, _if_ TW.result starts with "<html>" (see TeXDocument.cpp l.2633).
In that case, the return value is interpreted as html (or a subset of
it, anyway), so "<a href..." can be used to denote a link. In addition
to "normal" html, a new virtual "texworks://" scheme is defined for
links of the form "texworks://C:/path/to/file.tex#123" (where 123 is the
line number).

>     TW.result = message;
> In a hook script this automatically opens a console panel by the name
> of the Script Title, but nothing seems to happen in stanadalones

Yes, TW.result was introduced precisely for the purpose to pass data
from a script back to Tw. Of course, this only makes sense if Tw called
the script for a particular reason of its own. This is the case for hook
scripts, but not for standalone scripts (for which Tw just passes on the
user's wish to run the script, but doesn't know what the script does or
what data it might return).

In fact, I think at the moment the AfterTypeset hook is the only one
that actually uses TW.result (if it's non-empty, a new console tab is
opened to display its contents - see TeXDocument.cpp l.2638).

> And can   TW.result = "<html><body> ..... etc";
>
>  ... be put in a function or must it be the last statement in a script?

No, you can put this anywhere you want. Alternatively, you can put the
string as last statement instead of "undefined;" to implicitly set
TW.result.

> Can TW.target.consoleOutput be assigned to from a script?

No, it is read-only (TeXDocument.h l.114). You can only open additional
tabs in the AfterTypeset hook.

HTH
Stefan