[texworks] SCRIPTS: TW.ui

[Stefan Löffler]

Hi,

Am 2010-05-26 02:01, schrieb Paul A Norman:
> I went through the TW.(tree) And could only find Qstring and was not
> sure whether it was xml or a file name for ui stuff
>   

There are both variants. createUiFromString takes an xml string,
createUi takes the filename of a .ui file (from which an xml string is
loaded; the rest is identical to createUiFromString).

> Some of this is obvious but I just want to clarifiy / confirmn it to
> keep my head clear please.
>
> May be as I get this straight in my mind I should  write it up for others too.
>   

That'd be really great. We do need some good documentation of the
scripting API, and Jonathan has started one on the wiki. However, with
all the changes to scripting, that documentation is out of date already
and is missing many new features.

> Can we safely (at all times) use null as a parent as in the other dialogues?
> Or should I pass somet reference to the current TW.target...?
>   

This depends ;). For dialogs (and other top-level windows) it should
always be safe to use null. For normal widgets (like a text-box) this
should be theoretically possible (check the Qt docs for the specific
widget if necessary), but usually will result in some unintended
behavior (e.g., the widget gets the wrong size and/or position).

Note that if you specify a parent (typically TW.target), the Ui you
create is tied to that. This means, e.g., that the Ui will get destroyed
when Tw.target is destroyed (=closed). See the discussion of globals
below for some more info.

> TW.createUIFromString(uiSpec, parent)
> TW.createUI(filename, parent)
>
> The two function calls with out requiring parent(s) are for internal
> use only then?
>
>       createUI(QString)
>       createUIFromString(QString)
>   

No, you can use them. They are identical to passing null as parent to
the other two.

> Do the dialogues automatically pass from scope and memory when the
> script stops, or should I free them in some way? Or is that where the
> parnet comes in?
>   

Dialogs should not be destroyed automatically when the script ends. In
fact, I think that at the moment, they are never destroyed (until the
application terminates or the parent (if any) is destroyed). This is
something Jonathan should fix - hopefully together with the fact that
dialogs are shown automatically. Could you post an issue for these two
issues on GC?

In general, the dialogs should be destroyed when the script is
destroyed, or when the script calls for their destruction. So the best
way probably is for the script to call dlg.deleteLater() when the dialog
is no longer needed.



> Before script finishes, can the handle of an already created dialogue
> be passed to one of the new global objects for later re-use intact?
>   

It should generally be possible, yes. Whether it's safe to do so depends
on the situation. If your dialog has a parent, I would discourage that
behavior, though, as in that case the dialog is not guaranteed to stay
alive (i.e., it may be destroyed at any time when the parent is
destroyed). The globals should handle this case, but I haven't tested
this extensively yet.
If your dialog has no parent, I think it should be safe, but I'd
encourage some testing here, first :).

> If that is possible would I need to have created the dialogue with the
> application as the parent (TW.app ...), or null?
>   

Use null. TW.app is not a widget, and as such not a valid parent. How
this is handled depends on the scripting implementation. Lua & Python
raise an error at the moment, but this should change with my patch from
issue 369 so that null is used in case of an invalid parent. How
QtScript behaves I don't know off hand.

>>> Both functions show the widget they create, and return a handle to it.
>>>       
> Do they open modal and suspend script?
>   

No, they open the dialog and return to the script immediately. IMO, this
should be changed to not opening the dialog at all by default, leaving
that task to the script entirely. See my two issue requests above.

> Or can I use the handle, discover widgets -
> findChildWidget(QWidget*,QString) and
> PRESET certain curent values/script processed stuff, first from script
> for the user to interact with in the dialogue?
>   

Yes, you can.

> In  findChildWidget(QWidget*,QString)
>
> QWidget is the handle returmed by createUIFromString() and createUI() ?
> and the QTstring is the widget.name being looked for?
>   

Exactly.

HTH
Stefan