# Bespin Plugin Guide

## Editor API

## Introduction

The Bespin editor provides various functions for interaction. If you have the environment (env) variable you can access the current editor via

    var editor = env.editor;

For example, a basic command function looks like this:

    exports.upperCaseCommand = function(env, args, request) {
        // Get the editor instance from the environment variable.
        var editor = env.editor;
        // Replace the selected text with the current selected text, where
        // the current selected text is transformed to upper case.
        editor.selectedText = editor.selectedText.toUpperCase();
    };

## Setter & Getter API

get editor.focus
  returns true if the editor has the focus, false otherwise.
set editor.focus = `hasFocus`
  if `hasFocus` is true, the editor is focused, otherwise the editor loses focus.
get editor.readOnly
  returns true if the editor is readOnly, false otherwise.
set editor.readOnly = `isReadOnly`
  if `isReadOnly` is true, the editor's content can't get changed, otherwise it can.
get editor.selection
  returns the currently selected range.
set editor.selection = `newRange`
  sets the currently selected range to.
get editor.selectedText
  returns the currently selected text.
set editor.selectedText = `newText`
  replaces the current selected text with `newText` and moves the cursor at the end of `newText`. Returns true if the change was performed, otherwise false.
get editor.value
  returns the current text.
set editor.value = `newValue`
  sets the value of the current text. Returns true if the change was performed, otherwise false.
get editor.syntax
  returns the initial syntax highlighting context (i.e. the language).
set editor.syntax = `newSyntax`
  sets the initial syntax highlighting context (i.e. the language).

## Function API

editor.replace(`range`, `newText`, `keepSelection`)
  replaces the range of text with newText. If keepSelection is true, the current selection is maintained otherwise the cursor will jump to the end of `newText`. Returns true if the change was performed, otherwise false.
editor.setCursor(`newPosition`)
  moves the cursor to `newPosition`.
editor.setLineNumber(`lineNumber`)
  scrolls and moves the cursor to the given `lineNumber`.
editor.getText(`range`)
  returns the text within `range`.
editor.changeGroup(`func`)
  performs `func` within one change group. This means, that all the actions performed by `func` result in one undo/redo action. Returns true if the change was performed, otherwise false.

Example:

    editor.changeGroup(function(editor) {
       editor.value = 'Hello';
       editor.selectedText = ' World';
    });

These are two performed actions, but as they are grouped as one change and are one change in the undo/redo manager.

## Events

Listening to events work like this:

    editor.selectionChanged.add(function(newSelection) {
        console.log('selectionChanged', JSON.stringify(newSelection));
    });

editor.textChanged: (oldRange, newRange, newText)
  Fired whenever the value changed.
editor.selectionChanged: (newSelection)
  Fired whenever the selection changed.