Besides collections and objects for most document elements, the new JavaScript API implements asynchronous methods with callback functions. As all methods are asynchronous, it is important to wait for the return value which is solved using callbacks.

A callback is essentially a function that is executed after another function has finished executing.

The JavaScript method getStart of the Selection object has the following syntax:

<void> Selection.getStart(<RequestNumberCallback> callback, [<ErrorCallback> errorCallback])

It returns a RequestNumberCallback when successfully executed and an ErrorCallback when failed. The call of this method should look like this:

TXTextControl.selection.getStart(
        function (curSelStart) {
                // success
                console.log(curSelStart);
        },
        function (errArg) {
                // error
                console.log(errArg);
        },
);

The above code returns safely the selection start index of the current input position. Now, what if we need to check the selection length value in the same function? JavaScript is an event driven language. That implies that Javascript is not waiting for a response before moving on. In the following function, we cannot be 100% certain that the value of the first function is returned first.

function GetValues()
{
        TXTextControl.selection.getStart(
                function (curSelStart) {
                        // success
                        console.log(curSelStart);
                }
        );

        TXTextControl.selection.getLength(
                function (curSelLength) {
                        // success
                        console.log(curSelLength);
                }
        );
}

In order to achieve this, the second function should be called in the callback function of the first function:

function GetValues()
{
        TXTextControl.selection.getStart(
                function (curSelStart) {
                        console.log(curSelStart);
                        
                        TXTextControl.selection.getLength(
                                function (curSelLength) {
                                        // success
                                        console.log(curSelLength);
                                }
                        );
                }
        );
}

In case, you need the return values of these two functions in the function itself to do something else, you would have to create a lot of nested functions. That would result in complex structures which makes it the hard to read the code.

Therefore, Promises and async functions can be used. The following function returns a range object with the start and end index of the current selection. The return value itself is a Promise that can be resolved and rejected.

function getSelectionRange() {
    return new Promise(resolve => {
        TXTextControl.selection.getStart(function (curSelStart) {
            TXTextControl.selection.getLength(function (curSelLength) {

                var range = {
                    start: curSelStart,
                    end: curSelStart + curSelLength,
                };

                resolve(range);
            });
        });
    });
}

The calling function must be async in order to wait for Promises:

async function GetValues()
{
        var range = await getSelectionRange();
        console.log(range.start);
        console.log(range.end);
}

The keyword await marks the function to wait for a returned Promise, so that the return value can be used in further code in the same function.