Home Forums General XMetaL Discussion APIs that work in plain text view Reply To: APIs that work in plain text view

Derek Read

Reply to: APIs that work in plain text view

[quote=XMetaL Developer docs]It is good practice to check at the beginning of the macro which document view (Plain Text, Normal, Tags On) the document is displayed in. Many macros do not work the same in all views. Macros that use containers or DOM nodes do not work in Plain Text view. You can test the view type using Document.ViewType.

What the italicized portion of this quote basically means is any APIs that are expected to return a DOM value or interact with the DOM (Selection.ContainerNode.NodeName) or element information (Selection.ContainerName) will fail (they should probably all return null).

APIs that work with the UI should function. By UI I mean everything that surrounds the main document editing window as well as the context menu that appears inside the main document editing window.

Inside the main document editing window (essentially inside the document itself) APIs that mimic simple user interactions with the document such as Selection.MoveLeft(), Selection.TypeText(), etc, should work — things that the user can do with the keyboard to directly affect the current document.

In most cases I believe it is probably best to not allow scripts that interact with the document to run at all when in PlainText view. Perhaps it is better to put it this way: in most cases, scripts that make changes or need to interact with a document will only function fully when run in TagsOn or Normal view, so, at the start of such a script it is best to check the ViewType and either do nothing or display a warning to the user if that ViewType is not 0 (sqViewNormal) or 1 (sqViewTagsOn). It is no good to simply check that the ViewType is not 2 (sqViewPlainText) because such scripts will also not function correctly if the ViewType is 3 (sqViewBrowse), which is essentially Internet Explorer so none of the APIs we provide for interacting with a document function there at all. If you do wish to craft a script that runs in PlainText view it is also likely best to not allow that same script to run in TagsOn or Normal view. It might not be impossible to craft a script to function in all three views (using a bunch of if…then to check ViewType), however, it is probably a lot easier to create different scripts and test them separately.

All of the above applies equally to XMetaL Author and XMAX, provided you have a recent version of XMAX that includes PlainText view and that PlainText view is enabled (it is disabled in XMAX by default with a special setting being provided to enable it). Of course, APIs that work on the XMetaL Author UI will not function on the container application you are hosting XMAX within.