# Class CodeArea

java.lang.Object
javafx.scene.Node
javafx.scene.Parent
javafx.scene.layout.Region
javafx.scene.control.Control
jfx.incubator.scene.control.richtext.RichTextArea
jfx.incubator.scene.control.richtext.CodeArea

All Implemented Interfaces:
  `Styleable`, `EventTarget`, `Skinnable`

public class CodeArea extends RichTextArea
CodeArea is an editable text component which supports styling (for example, syntax highlighting) of plain text.

Unlike its base class `RichTextArea`, the `CodeArea` requires a special kind of model to be used, a `CodeTextModel`.

## Creating a CodeArea

The following example creates an editable control with the default `CodeArea`:

       CodeArea codeArea = new CodeArea();
       codeArea.setWrapText(true);
       codeArea.setLineNumbersEnabled(true);
       codeArea.setText("Lorem\nIpsum");

Which results in the following visual representation:

## Usage Considerations

`CodeArea` extends the `RichTextArea` class, meaning most of the functionality works as it does in the base class. There are some differences that should be mentioned:

- Model behavior: any direct changes to the styling, such as `applyStyle()`, will be ignored
- Line numbers: the `CodeArea` sets the `RichTextArea.leftDecoratorProperty()` to support the line numbers, so applications should not set or bind that property.

Since:
  24

- ## Nested Class Summary

  ### Nested classes/interfaces declared in class jfx.incubator.scene.control.richtext.RichTextArea

  `RichTextArea.Tag`

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final ObjectProperty<Font>`
  `font`
  The font to use for text in the `CodeArea`.
  `final BooleanProperty`
  `lineNumbersEnabled`
  Determines whether to show line numbers.
  `final DoubleProperty`
  `lineSpacing`
  Defines the vertical space in pixels between lines.
  `final IntegerProperty`
  `tabSize`
  The size of a tab stop in spaces.

  ### Properties declared in class jfx.incubator.scene.control.richtext.RichTextArea

  `anchorPosition, caretBlinkPeriod, caretPosition, contentPadding, displayCaret, editable, highlightCurrentParagraph, leftDecorator, model, redoable, rightDecorator, selection, undoable, useContentHeight, useContentWidth, wrapText`

  ### Properties declared in class javafx.scene.control.Control

  `contextMenu, skin, tooltip`

  ### Properties declared in class javafx.scene.layout.Region

  `background, border, cacheShape, centerShape, height, insets, maxHeight, maxWidth, minHeight, minWidth, opaqueInsets, padding, prefHeight, prefWidth, scaleShape, shape, snapToPixel, width`

  ### Properties declared in class javafx.scene.Parent

  `needsLayout`

  ### Properties declared in class javafx.scene.Node

  `accessibleHelp, accessibleRoleDescription, accessibleRole, accessibleText, blendMode, boundsInLocal, boundsInParent, cacheHint, cache, clip, cursor, depthTest, disabled, disable, effectiveNodeOrientation, effect, eventDispatcher, focused, focusTraversable, focusVisible, focusWithin, hover, id, inputMethodRequests, layoutBounds, layoutX, layoutY, localToParentTransform, localToSceneTransform, managed, mouseTransparent, nodeOrientation, onContextMenuRequested, onDragDetected, onDragDone, onDragDropped, onDragEntered, onDragExited, onDragOver, onInputMethodTextChanged, onKeyPressed, onKeyReleased, onKeyTyped, onMouseClicked, onMouseDragEntered, onMouseDragExited, onMouseDragged, onMouseDragOver, onMouseDragReleased, onMouseEntered, onMouseExited, onMouseMoved, onMousePressed, onMouseReleased, onRotate, onRotationFinished, onRotationStarted, onScrollFinished, onScroll, onScrollStarted, onSwipeDown, onSwipeLeft, onSwipeRight, onSwipeUp, onTouchMoved, onTouchPressed, onTouchReleased, onTouchStationary, onZoomFinished, onZoom, onZoomStarted, opacity, parent, pickOnBounds, pressed, rotate, rotationAxis, scaleX, scaleY, scaleZ, scene, style, translateX, translateY, translateZ, viewOrder, visible`

- ## Field Summary

  ### Fields declared in class jfx.incubator.scene.control.richtext.RichTextArea

  `styleHandlerRegistry`

  ### Fields declared in class javafx.scene.layout.Region

  `USE_COMPUTED_SIZE, USE_PREF_SIZE`

  ### Fields declared in class javafx.scene.Node

  `BASELINE_OFFSET_SAME_AS_HEIGHT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CodeArea()`
  This constructor creates the CodeArea with the default `CodeTextModel`.
  `CodeArea(CodeTextModel model)`
  This constructor creates the CodeArea with the specified `CodeTextModel`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final ObjectProperty<Font>`
  `fontProperty()`
  The font to use for text in the `CodeArea`.
  `static List<CssMetaData<? extends Styleable, ?>>`
  `getClassCssMetaData()`
  Gets the `CssMetaData` associated with this class, which may include the `CssMetaData` of its superclasses.
  `final Font`
  `getFont()`
  Gets the value of the `font` property.
  `final double`
  `getLineSpacing()`
  Gets the value of the `lineSpacing` property.
  `final SyntaxDecorator`
  `getSyntaxDecorator()`
  This convenience method returns the syntax decorator value in the `CodeTextModel`, or null if the model is null.
  `final int`
  `getTabSize()`
  Gets the value of the `tabSize` property.
  `final String`
  `getText()`
  Returns plain text.
  `final boolean`
  `isLineNumbersEnabled()`
  Gets the value of the `lineNumbersEnabled` property.
  `final BooleanProperty`
  `lineNumbersEnabledProperty()`
  Determines whether to show line numbers.
  `final DoubleProperty`
  `lineSpacingProperty()`
  Defines the vertical space in pixels between lines.
  `final void`
  `setFont(Font value)`
  Sets the value of the `font` property.
  `final void`
  `setLineNumbersEnabled(boolean on)`
  Sets the value of the `lineNumbersEnabled` property.
  `final void`
  `setLineSpacing(double spacing)`
  Sets the value of the `lineSpacing` property.
  `final void`
  `setSyntaxDecorator(SyntaxDecorator d)`
  This convenience method sets the decorator property in the `CodeTextModel`.
  `final void`
  `setTabSize(int spaces)`
  Sets the value of the `tabSize` property.
  `final void`
  `setText(String text)`
  Replaces text in this CodeArea.
  `final IntegerProperty`
  `tabSizeProperty()`
  The size of a tab stop in spaces.

  ### Methods declared in class jfx.incubator.scene.control.richtext.RichTextArea

  `anchorPositionProperty, appendText, appendText, appendText, applyStyle, backspace, caretBlinkPeriodProperty, caretPositionProperty, clear, clearSelection, clearUndoRedo, contentPaddingProperty, copy, copy, createDefaultSkin, cut, delete, deleteParagraph, deleteParagraphStart, deleteWordNextEnd, deleteWordNextStart, deleteWordPrevious, deselect, displayCaretProperty, editableProperty, errorFeedback, execute, executeDefault, extendSelection, getActiveStyleAttributeMap, getAnchorPosition, getCaretBlinkPeriod, getCaretPosition, getContentPadding, getControlCssMetaData, getDocumentEnd, getInputMap, getLeftDecorator, getModel, getParagraphCount, getParagraphEnd, getPlainText, getRightDecorator, getSelection, getStyleHandlerRegistry, getTextPosition, hasNonEmptySelection, highlightCurrentParagraphProperty, insertLineBreak, insertTab, insertText, insertText, isDisplayCaret, isEditable, isHighlightCurrentParagraph, isRedoable, isUndoable, isUseContentHeight, isUseContentWidth, isWrapText, leftDecoratorProperty, modelProperty, moveDocumentEnd, moveDocumentStart, moveDown, moveLeft, moveLineEnd, moveLineStart, moveParagraphDown, moveParagraphEnd, moveParagraphStart, moveParagraphUp, moveRight, moveUp, moveWordLeft, moveWordNextEnd, moveWordNextStart, moveWordPrevious, moveWordRight, pageDown, pageUp, paste, paste, pastePlainText, read, read, redo, redoableProperty, replaceText, replaceText, rightDecoratorProperty, select, select, selectAll, selectDown, selectionProperty, selectLeft, selectPageDown, selectPageUp, selectParagraph, selectParagraphDown, selectParagraphEnd, selectParagraphStart, selectParagraphUp, selectRight, selectToDocumentEnd, selectToDocumentStart, selectToLineEnd, selectToLineStart, selectUp, selectWord, selectWordLeft, selectWordNextEnd, selectWordNextStart, selectWordPrevious, selectWordRight, setCaretBlinkPeriod, setContentPadding, setDisplayCaret, setEditable, setHighlightCurrentParagraph, setLeftDecorator, setModel, setRightDecorator, setStyle, setUseContentHeight, setUseContentWidth, setWrapText, undo, undoableProperty, useContentHeightProperty, useContentWidthProperty, validateModel, wrapTextProperty, write, write`

  ### Methods declared in class javafx.scene.control.Control

  `computeMaxHeight, computeMaxWidth, computeMinHeight, computeMinWidth, contextMenuProperty, getContextMenu, getCssMetaData, getInitialFocusTraversable, getSkin, getTooltip, isResizable, setContextMenu, setSkin, setTooltip, skinProperty, tooltipProperty`

  ### Methods declared in class javafx.scene.layout.Region

  `backgroundProperty, borderProperty, cacheShapeProperty, centerShapeProperty, computePrefHeight, computePrefWidth, getBackground, getBorder, getHeight, getInsets, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpaqueInsets, getPadding, getPrefHeight, getPrefWidth, getShape, getUserAgentStylesheet, getWidth, heightProperty, insetsProperty, isCacheShape, isCenterShape, isScaleShape, isSnapToPixel, layoutInArea, layoutInArea, layoutInArea, layoutInArea, maxHeight, maxHeightProperty, maxWidth, maxWidthProperty, minHeight, minHeightProperty, minWidth, minWidthProperty, opaqueInsetsProperty, paddingProperty, positionInArea, positionInArea, prefHeight, prefHeightProperty, prefWidth, prefWidthProperty, resize, scaleShapeProperty, setBackground, setBorder, setCacheShape, setCenterShape, setHeight, setMaxHeight, setMaxSize, setMaxWidth, setMinHeight, setMinSize, setMinWidth, setOpaqueInsets, setPadding, setPrefHeight, setPrefSize, setPrefWidth, setScaleShape, setShape, setSnapToPixel, setWidth, shapeProperty, snappedBottomInset, snappedLeftInset, snappedRightInset, snappedTopInset, snapPosition, snapPositionX, snapPositionY, snapSize, snapSizeX, snapSizeY, snapSpace, snapSpaceX, snapSpaceY, snapToPixelProperty, widthProperty`

  ### Methods declared in class javafx.scene.Parent

  `getBaselineOffset, getChildren, getChildrenUnmodifiable, getManagedChildren, getStylesheets, isNeedsLayout, layout, layoutChildren, needsLayoutProperty, requestLayout, requestParentLayout, setNeedsLayout, updateBounds`

  ### Methods declared in class javafx.scene.Node

  `accessibleHelpProperty, accessibleRoleDescriptionProperty, accessibleRoleProperty, accessibleTextProperty, addEventFilter, addEventHandler, applyCss, autosize, blendModeProperty, boundsInLocalProperty, boundsInParentProperty, buildEventDispatchChain, cacheHintProperty, cacheProperty, clipProperty, computeAreaInScreen, contains, contains, cursorProperty, depthTestProperty, disabledProperty, disableProperty, effectiveNodeOrientationProperty, effectProperty, eventDispatcherProperty, executeAccessibleAction, fireEvent, focusedProperty, focusTraversableProperty, focusVisibleProperty, focusWithinProperty, getAccessibleHelp, getAccessibleRole, getAccessibleRoleDescription, getAccessibleText, getBlendMode, getBoundsInLocal, getBoundsInParent, getCacheHint, getClip, getContentBias, getCursor, getDepthTest, getEffect, getEffectiveNodeOrientation, getEventDispatcher, getId, getInitialCursor, getInputMethodRequests, getLayoutBounds, getLayoutX, getLayoutY, getLocalToParentTransform, getLocalToSceneTransform, getNodeOrientation, getOnContextMenuRequested, getOnDragDetected, getOnDragDone, getOnDragDropped, getOnDragEntered, getOnDragExited, getOnDragOver, getOnInputMethodTextChanged, getOnKeyPressed, getOnKeyReleased, getOnKeyTyped, getOnMouseClicked, getOnMouseDragEntered, getOnMouseDragExited, getOnMouseDragged, getOnMouseDragOver, getOnMouseDragReleased, getOnMouseEntered, getOnMouseExited, getOnMouseMoved, getOnMousePressed, getOnMouseReleased, getOnRotate, getOnRotationFinished, getOnRotationStarted, getOnScroll, getOnScrollFinished, getOnScrollStarted, getOnSwipeDown, getOnSwipeLeft, getOnSwipeRight, getOnSwipeUp, getOnTouchMoved, getOnTouchPressed, getOnTouchReleased, getOnTouchStationary, getOnZoom, getOnZoomFinished, getOnZoomStarted, getOpacity, getParent, getProperties, getPseudoClassStates, getRotate, getRotationAxis, getScaleX, getScaleY, getScaleZ, getScene, getStyle, getStyleableParent, getStyleClass, getTransforms, getTranslateX, getTranslateY, getTranslateZ, getTypeSelector, getUserData, getViewOrder, hasProperties, hoverProperty, idProperty, inputMethodRequestsProperty, intersects, intersects, isCache, isDisable, isDisabled, isFocused, isFocusTraversable, isFocusVisible, isFocusWithin, isHover, isManaged, isMouseTransparent, isPickOnBounds, isPressed, isVisible, layoutBoundsProperty, layoutXProperty, layoutYProperty, localToParent, localToParent, localToParent, localToParent, localToParent, localToParentTransformProperty, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToScene, localToSceneTransformProperty, localToScreen, localToScreen, localToScreen, localToScreen, localToScreen, lookup, lookupAll, managedProperty, mouseTransparentProperty, nodeOrientationProperty, notifyAccessibleAttributeChanged, onContextMenuRequestedProperty, onDragDetectedProperty, onDragDoneProperty, onDragDroppedProperty, onDragEnteredProperty, onDragExitedProperty, onDragOverProperty, onInputMethodTextChangedProperty, onKeyPressedProperty, onKeyReleasedProperty, onKeyTypedProperty, onMouseClickedProperty, onMouseDragEnteredProperty, onMouseDragExitedProperty, onMouseDraggedProperty, onMouseDragOverProperty, onMouseDragReleasedProperty, onMouseEnteredProperty, onMouseExitedProperty, onMouseMovedProperty, onMousePressedProperty, onMouseReleasedProperty, onRotateProperty, onRotationFinishedProperty, onRotationStartedProperty, onScrollFinishedProperty, onScrollProperty, onScrollStartedProperty, onSwipeDownProperty, onSwipeLeftProperty, onSwipeRightProperty, onSwipeUpProperty, onTouchMovedProperty, onTouchPressedProperty, onTouchReleasedProperty, onTouchStationaryProperty, onZoomFinishedProperty, onZoomProperty, onZoomStartedProperty, opacityProperty, parentProperty, parentToLocal, parentToLocal, parentToLocal, parentToLocal, parentToLocal, pickOnBoundsProperty, pressedProperty, pseudoClassStateChanged, queryAccessibleAttribute, relocate, removeEventFilter, removeEventHandler, requestFocus, requestFocusTraversal, resizeRelocate, rotateProperty, rotationAxisProperty, scaleXProperty, scaleYProperty, scaleZProperty, sceneProperty, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, sceneToLocal, screenToLocal, screenToLocal, screenToLocal, setAccessibleHelp, setAccessibleRole, setAccessibleRoleDescription, setAccessibleText, setBlendMode, setCache, setCacheHint, setClip, setCursor, setDepthTest, setDisable, setDisabled, setEffect, setEventDispatcher, setEventHandler, setFocused, setFocusTraversable, setHover, setId, setInputMethodRequests, setLayoutX, setLayoutY, setManaged, setMouseTransparent, setNodeOrientation, setOnContextMenuRequested, setOnDragDetected, setOnDragDone, setOnDragDropped, setOnDragEntered, setOnDragExited, setOnDragOver, setOnInputMethodTextChanged, setOnKeyPressed, setOnKeyReleased, setOnKeyTyped, setOnMouseClicked, setOnMouseDragEntered, setOnMouseDragExited, setOnMouseDragged, setOnMouseDragOver, setOnMouseDragReleased, setOnMouseEntered, setOnMouseExited, setOnMouseMoved, setOnMousePressed, setOnMouseReleased, setOnRotate, setOnRotationFinished, setOnRotationStarted, setOnScroll, setOnScrollFinished, setOnScrollStarted, setOnSwipeDown, setOnSwipeLeft, setOnSwipeRight, setOnSwipeUp, setOnTouchMoved, setOnTouchPressed, setOnTouchReleased, setOnTouchStationary, setOnZoom, setOnZoomFinished, setOnZoomStarted, setOpacity, setPickOnBounds, setPressed, setRotate, setRotationAxis, setScaleX, setScaleY, setScaleZ, setStyle, setTranslateX, setTranslateY, setTranslateZ, setUserData, setViewOrder, setVisible, snapshot, snapshot, startDragAndDrop, startFullDrag, styleProperty, toBack, toFront, toString, translateXProperty, translateYProperty, translateZProperty, usesMirroring, viewOrderProperty, visibleProperty`

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods declared in interface javafx.css.Styleable

  `getStyleableNode`

- ## Property Details

  - ### lineNumbersEnabled

    public final BooleanProperty lineNumbersEnabledProperty
    Determines whether to show line numbers. Toggling this property results in changes made to the `leftDecorator` property, so the application code should not bind or modify that property.
    Default value:
      false
    See Also:
      - `isLineNumbersEnabled()`
      - `setLineNumbersEnabled(boolean)`
      - `lineNumbersEnabledProperty()`

  - ### tabSize

    public final IntegerProperty tabSizeProperty
    The size of a tab stop in spaces. Values less than 1 are treated as 1.
    Default value:
      8
    See Also:
      - `getTabSize()`
      - `setTabSize(int)`
      - `tabSizeProperty()`

  - ### font

    public final ObjectProperty<Font> fontProperty
    The font to use for text in the `CodeArea`.
    Default value:
      the Monospaced font with the default size
    See Also:
      - `getFont()`
      - `setFont(Font)`
      - `fontProperty()`

  - ### lineSpacing

    public final DoubleProperty lineSpacingProperty
    Defines the vertical space in pixels between lines.
    Default value:
      0
    See Also:
      - `getLineSpacing()`
      - `setLineSpacing(double)`
      - `lineSpacingProperty()`

- ## Constructor Details

  - ### CodeArea

    public CodeArea(CodeTextModel model)
    This constructor creates the CodeArea with the specified `CodeTextModel`.
    Parameters:
      `model` - the instance of `CodeTextModel` to use

  - ### CodeArea

    public CodeArea()
    This constructor creates the CodeArea with the default `CodeTextModel`.

- ## Method Details

  - ### setSyntaxDecorator

    public final void setSyntaxDecorator(SyntaxDecorator d)
    This convenience method sets the decorator property in the `CodeTextModel`. Nothing is done if the model is null.
    Parameters:
      `d` - the syntax decorator
    See Also:
      - `CodeTextModel.setDecorator(SyntaxDecorator)`

  - ### getSyntaxDecorator

    public final SyntaxDecorator getSyntaxDecorator()
    This convenience method returns the syntax decorator value in the `CodeTextModel`, or null if the model is null.
    Returns:
      the syntax decorator value, or null

  - ### lineNumbersEnabledProperty

    public final BooleanProperty lineNumbersEnabledProperty()
    Determines whether to show line numbers. Toggling this property results in changes made to the `leftDecorator` property, so the application code should not bind or modify that property.
    Default value:
      false
    Returns:
      the line numbers enabled property
    See Also:
      - `isLineNumbersEnabled()`
      - `setLineNumbersEnabled(boolean)`

  - ### isLineNumbersEnabled

    public final boolean isLineNumbersEnabled()
    Gets the value of the `lineNumbersEnabled` property.
    Property description:
      Determines whether to show line numbers. Toggling this property results in changes made to the `leftDecorator` property, so the application code should not bind or modify that property.
    Default value:
      false
    Returns:
      the value of the `lineNumbersEnabled` property
    See Also:
      - `setLineNumbersEnabled(boolean)`
      - `lineNumbersEnabledProperty()`

  - ### setLineNumbersEnabled

    public final void setLineNumbersEnabled(boolean on)
    Sets the value of the `lineNumbersEnabled` property.
    Property description:
      Determines whether to show line numbers. Toggling this property results in changes made to the `leftDecorator` property, so the application code should not bind or modify that property.
    Default value:
      false
    Parameters:
      `on` - the value for the `lineNumbersEnabled` property
    See Also:
      - `isLineNumbersEnabled()`
      - `lineNumbersEnabledProperty()`

  - ### tabSizeProperty

    public final IntegerProperty tabSizeProperty()
    The size of a tab stop in spaces. Values less than 1 are treated as 1.
    Default value:
      8
    Returns:
      the tab size property
    See Also:
      - `getTabSize()`
      - `setTabSize(int)`

  - ### getTabSize

    public final int getTabSize()
    Gets the value of the `tabSize` property.
    Property description:
      The size of a tab stop in spaces. Values less than 1 are treated as 1.
    Default value:
      8
    Returns:
      the value of the `tabSize` property
    See Also:
      - `setTabSize(int)`
      - `tabSizeProperty()`

  - ### setTabSize

    public final void setTabSize(int spaces)
    Sets the value of the `tabSize` property.
    Property description:
      The size of a tab stop in spaces. Values less than 1 are treated as 1.
    Default value:
      8
    Parameters:
      `spaces` - the value for the `tabSize` property
    See Also:
      - `getTabSize()`
      - `tabSizeProperty()`

  - ### fontProperty

    public final ObjectProperty<Font> fontProperty()
    The font to use for text in the `CodeArea`.
    Default value:
      the Monospaced font with the default size
    Returns:
      the font property
    See Also:
      - `getFont()`
      - `setFont(Font)`

  - ### setFont

    public final void setFont(Font value)
    Sets the value of the `font` property.
    Property description:
      The font to use for text in the `CodeArea`.
    Default value:
      the Monospaced font with the default size
    Parameters:
      `value` - the value for the `font` property
    See Also:
      - `getFont()`
      - `fontProperty()`

  - ### getFont

    public final Font getFont()
    Gets the value of the `font` property.
    Property description:
      The font to use for text in the `CodeArea`.
    Default value:
      the Monospaced font with the default size
    Returns:
      the value of the `font` property
    See Also:
      - `setFont(Font)`
      - `fontProperty()`

  - ### lineSpacingProperty

    public final DoubleProperty lineSpacingProperty()
    Defines the vertical space in pixels between lines.
    Default value:
      0
    Returns:
      the property instance
    See Also:
      - `getLineSpacing()`
      - `setLineSpacing(double)`

  - ### setLineSpacing

    public final void setLineSpacing(double spacing)
    Sets the value of the `lineSpacing` property.
    Property description:
      Defines the vertical space in pixels between lines.
    Default value:
      0
    Parameters:
      `spacing` - the value for the `lineSpacing` property
    See Also:
      - `getLineSpacing()`
      - `lineSpacingProperty()`

  - ### getLineSpacing

    public final double getLineSpacing()
    Gets the value of the `lineSpacing` property.
    Property description:
      Defines the vertical space in pixels between lines.
    Default value:
      0
    Returns:
      the value of the `lineSpacing` property
    See Also:
      - `setLineSpacing(double)`
      - `lineSpacingProperty()`

  - ### getClassCssMetaData

    public static List<CssMetaData<? extends Styleable, ?>> getClassCssMetaData()
    Gets the `CssMetaData` associated with this class, which may include the `CssMetaData` of its superclasses.
    Returns:
      the `CssMetaData`

  - ### getText

    public final String getText()
    Returns plain text. This method returns an empty string when the model is `null`.
    Returns:
      plain text

  - ### setText

    public final void setText(String text)
    Replaces text in this CodeArea.

    The caret gets reset to the start of the document, selection gets cleared, and an undo event gets created.

    Parameters:
      `text` - the text string