Events

Is the editor ready? Has a document been loaded, or has the user changed a field, a tracked change or the input position? The events of the Document Editor's JavaScript API tell your code, each with its own arguments, and the event lists show which event to listen for.

The events belong to the TXTextControl object; JavaScript API explains the object and where it is available in each frontend.

Attach and Remove Event Handlers

addEventListener attaches a function to an event. The function receives an event argument object, or nothing, depending on the event:

TXTextControl.addEventListener("documentLoaded", function (e) {
  console.log("Document loaded: " + e.fileName);
});

removeEventListener removes a handler again. Pass the same function that you attached, so give a handler that you want to remove a name instead of writing it inline:

function logInputPosition(e) {
  console.log("Page " + e.page + ", line " + e.line + ", column " + e.column);
}

TXTextControl.addEventListener("inputPositionChanged", logInputPosition);

// Later, when the information is no longer needed
TXTextControl.removeEventListener("inputPositionChanged", logInputPosition);

The event names are strings. Write them exactly as the tables below list them.

Events During Initialization

When a page with the editor opens, the editor raises these events. The blog article Document Editor: Initialization Events, written for version 32.0, shows them in this order for a document that the view loads:

1. textControlLoaded: the editor is ready, and your code can use the JavaScript API.
2. documentLoaded: the document that the view passed to the editor has been loaded.
3. ribbonTabLoaded: once for each tab of the ribbon.
4. ribbonTabsLoaded: the complete ribbon has been loaded.

In version 32.0, the editor loads the content of the ribbon over a second WebSocket connection while it loads its other resources, so don't rely on this order: change the content only after textControlLoaded, change a document loaded at startup only after documentLoaded, and change the ribbon's HTML elements only after ribbonTabsLoaded.

In Angular and React, the TXTextControl object itself becomes available later, so attach the handlers where the frontend signals it; When the Object Is Available lists the place for each frontend.

Example

The following script logs the events of the initialization and the connection to the browser console. Add it below the editor in Views/Home/Index.cshtml of the ASP.NET Core tutorial, or after the call of TXTextControl.init in a plain JavaScript page:

<input type="button" onclick="stopLogging()" value="Stop Logging" />

<script>
    // A named function, so that it can be removed again
    function logInputPosition(e) {
        console.log("Page " + e.page + ", line " + e.line + ", column " + e.column);
    }

    TXTextControl.addEventListener("textControlLoaded", function () {
        console.log("Text Control loaded");
        TXTextControl.addEventListener("inputPositionChanged", logInputPosition);
    });

    TXTextControl.addEventListener("documentLoaded", function (e) {
        console.log("Document loaded: " + e.fileName);
    });

    TXTextControl.addEventListener("ribbonTabLoaded", function (e) {
        console.log("Ribbon tab loaded: " + e.tabName);
    });

    TXTextControl.addEventListener("ribbonTabsLoaded", function () {
        console.log("Ribbon tabs loaded");
    });

    TXTextControl.addEventListener("webSocketClosed", function (e) {
        console.log("Connection closed: " + e.code + " " + e.reason);
    });

    function stopLogging() {
        TXTextControl.removeEventListener("inputPositionChanged", logInputPosition);
    }
</script>

Open the browser's developer tools and reload the page. The console shows the loading events, one line for each ribbon tab and a line for every move of the cursor until you click Stop Logging.

Event Reference

The tables list the events by subject. The last column links the object that the handler receives. "None" means that the handler receives no arguments.

Initialization and Loading

Document, Formatting and Input Position

Clipboard, Pasting and Dropping

The argument objects of textPasted, textDropped and fileDropped have a cancel property.

Images, Frames, Tables and Shapes

Fields, Links and Regions

Track Changes and Comments

When a tracked change has been deleted, only some properties of its event data are still valid: the kind of change, the user name, the highlight color and mode and the time of the change.

Footnotes and Signature Fields

Proofing

Connection and Errors

Architecture explains what happens when the connection is lost and how the editor reconnects.

Related Pages

• JavaScript API: the object model and the callbacks of the API.
• Loading and Saving Documents: load documents and react to documentLoaded.
• Context Menus: change the context menu in contextMenuOpening.
• Track Changes and Comments: the review events in use.