The API

We can send messages to a vwRtx instance using a consistant API in order to change text styling, cut and paste, etc.

All about the API

The information provided by the config object sets up the initial properties of the vwRtx instance, and the API is used to change those properties after creation. We generally have one set of code working on the config, then many others that use the API to send commands and parameters into the API. Typically, most of the buttons on a text editing UI toolbar - think bold, italic, underline, font name selection, size, color, etc - will be wired up to send an API command.

API commands are generally simple and follow a straightforward pattern. The rtx instance is expecting to be told what it has to change, maybe with a further parameter to provide more specificity, then the new value to apply.

For example, to set the current text bold we would send this message:

rtx.send({
    name: 'font',
    attr: 'fontWeight',
    value: 'bold'
})

The content we are sending via the rtx.send command is a plain JavaScript object containing values for name, attr and value. This is the most common for of the command object. Here name informs the vwRtx of the target, attr specifies the parameter, and the value gives the new value.

The value is usually a string, number of boolean value. Occaisionally it is a plain JS object.

Multiple API commands

We can send multiple API commands in one message using an array notation.

rtx.send(
  [
    {
    name: 'font',
    attr: 'fontWeight',
    value: 'bold'
    },
    {
    name: 'font',
    attr: 'fill',
    value: 'red'
    }
  ]
)

Here we have the same message structure, repeated for each change that is required to be applied.

The messages are validated inside the vwRtx instance to ensure they are correctly configured and appropriate.

All of the configuration-affecting API messages for activities such as changing font styles, are described in the full configuration section. The remainder of this section covers the few cases that are not covered there, or bear a quick view to grow familiarity.

Undo and Redo

Each vwRtx instance keeps its own undo-redo list and that might be enough for simple cases with a single instance in use. However, in more real-word cases you will want to integrate your app's undo-redo process with the multiple vwRtx instances on the canvas. See undo-redo for more information on this topic.

For clarity, the undo and redo API messages are shown below, but do read the information in that link.

// send the undo message
rtx.send({
  name: "change",
  value: "undo"
})

// send the redo message
rtx.send({
  name: "change",
  value: "redo"
})

Note: there is no attr attribute in the change API messages.

Cut and Paste

The clipboard-focussed cut, copy and paste commands use the same message construction:

rtx.send({
  name: "clipboard",
  value: "<cut | copy | paste>"
})

The vwRtx instance will deal direct with the clipboard object - there is no requirement for additional code. The one caveat is that to use the clipboard API you must be on either a local network or be using HTTPS. This is a requirement of the clipboard API.

The cut, copy and paste commands are all undo-redo friendly. The cut and copy commands place plain text into the clipboard.

Paste arbitrary text

To paste text that your app loads without using the clipboard, use the pasteText message:

// paste arbitrary text
rtx.send({
  name: "pasteText", 
  value: "\u{1F47D}"  // pastes a green alien head
})

The pasted text is inserted over the selection, or inserted at the caret position if there is no selection.

Replace the text

To replace all of the text with a single string use the config.text message:

// paste arbitrary text
rtx.send({
  name: "config", 
  attr: "text",
  value: "Ground Control to Major Tom\rGround Control to Major Tom\rTake your protein pills and put your helmet on"
})

The value can be a plain string, a template literal or any string variable.

Font API messages

The configurable font options are described in detail in the config.font section here. Again for clarity the form is shown below. See the link for the full options.

// set the font size
rtx.send({
  name: "font",
  attr: "fontSize",
  value: "32px"
})

// set the font weight
rtx.send({
  name: "font",
  attr: "fontWeight",
  value: 400
})