# The Editor Context object

Orion 4.0 introduces ''Object References'', which enable two-way communication between a service provider and the host Orion page. An Object Reference exposes functions that a service provider can call to help it fulfill a service contract. Like everything in Orion's service framework, Object References work asynchronously: all functions return Promises and the caller must wait for them to fulfill to an actual value. An Object Reference is valid only during the lifetime of its parent service call. Once the provider has fulfilled the service call, any Object References created for that call are unregistered by the framework, and cannot be used thereafter.

Many of the service APIs documented on this page now provide a special Object Reference, called the Editor Context object, as the first parameter in their function signatures. The Editor Context object contains various functions to query the state of the Orion editor, and to cause side effects. For example, if a provider needs the text from the editor buffer to fulfill its service contract, it can invoke the Editor Context's `getText()` method:

    editorContextObject.getText().then(function(text) {
        // Use text to fulfill the provider's service contract
    });

Any plugin that uses Object References must load Orion's `Deferred.js` in addition to the usual `plugin.js` script. Failure to do this will cause runtime errors when the plugin attempts to use an Object Reference.

## API versions

The older API signatures are labelled as "Orion 3.0" in the documentation. These are still supported, but date from Orion releases when Object References were not available. It is preferable to use the "Orion 4.0" version of an API whenever available, as these provide greater consistency, are somewhat more efficient, and can be more easily evolved in future releases without changing method signatures.

## Editor Context methods

The Editor Context object provides the following methods:

  getCaretOffset()
    Resolves to `Number`. Returns the offset of the editing caret.
  getSelection()
    Resolves to `Selection`. Returns the editor's current selection.
  getText(start?, end?)
    Resolves to `String`. Returns the text in the given range.
  setCaretOffset(offset, show?)
    Resolves to `undefined`. Sets the caret offset. If `show` is true, the editor will scroll to the new caret position.
  setSelection(selection)
    Resolves to `undefined`. Sets the editor's selection.
  setText(text, start?, end?)
    Resolves to `undefined`. Sets the text in the given range.