The [text] command.

Introduction

The text command lets you interact programmatically with the text buffer of a document window.

Synopsis

The formal syntax of the [text] command is:

text subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some options may be specified.

The [bounds] subcommand

This subcommand returns the bounding rectangle enclosing the specified range of characters. The complete syntax is:

    text bounds ?-w win? start end

If the window specified by the -w option is split, it applies to the current pane. The returned rectangle is expressed in text view coordinates (the text origin is the top left corner of the text view). It is suitable for use with the -rect option of the [popover] command.

The [check] subcommand

This subcommand forces a default text checking on the entire document. The complete syntax is:

    text check ?-w win?

Depending on the features which have been enabled on the document (like link detection, spelling correction, grammar checking, etc.), the document is entirely checked.

The [composed] subcommand

This subcommand returns the range corresponding to the composed character sequences in a given range. The complete syntax is:

    text composed ?-w win? pos1 ?pos2?

The composed character sequence includes the first base character found at or before pos1, and its length includes the last base character and all non-base characters (such as combining marks) following this base character. If the pos2 argument is not specified, it is equal to pos1.

The [copy] subcommand

This subcommand copies in the pasteboard the currently selected text. The complete syntax is:

    text copy ?-w win?

It copies to the pasteboard the text selected in the current document window. It supports multiple selections and rectangular selections.

The [cut] subcommand

This subcommand cuts and sends to the pasteboard the currently selected text. The complete syntax is:

    text cut ?-w win?

It cuts the text selected in the current document window (if it is not in read-only mode) and sends a copy to the pasteboard. It supports multiple selections and rectangular selections.

The [delete] subcommand

This subcommand deletes the text block between the specified positions. The complete syntax is:

    text delete ?-w win? ?-preserve? pos1 pos2

The -preserve option tells to preserve the current selection (if any) or the current location of the cursor. By default, when some text is deleted, the current cursor position is moved to position pos1 and, if there was a selection, it is deselected. Setting this option may be useful to delete some text without jumping to a new location. Note that if the deleted range intersects the current selection, the selection is removed anyway.

The [get] subcommand

This subcommand returns the text block between the specified positions. The complete syntax is:

    text get ?-w win? pos1 pos2

The [insert] subcommand

This subcommand inserts text in the buffer. The complete syntax is:

    text insert ?-w win? ?-pos num? ?-preserve? ?--? text…

The -pos option indicates the position where the text is to be inserted. If it is not specified, the current position (of the current pane) is assumed.
The -preserve option tells to preserve the current selection (if any) or the current location of the cursor. By default, the current cursor position is moved to the end of the inserted text and, if there was a selection, it is deselected. Setting this option may be useful to insert some text without jumping to a new location. Note that if the insertion position is inside the current selection, the selection is removed anyway.
The -- argument indicates the end of the options. The remaining arguments are one or more strings which are concatenated before being inserted.

The [paste] subcommand

This subcommand inserts the contents of the pasteboard at the current position. The complete syntax is:

    text paste ?-w win?

It inserts at the current position the text contained in the pasteboard (if any). It supports multiple selections and rectangular selections.

The [replace] subcommand

This subcommand replaces a text block by another one. The complete syntax is:

    text replace ?-w win? ?-preserve? ?--? pos1 pos2 string

The text block contained between the specified positions is replaced by the string argument.
The -preserve option has the same meaning as with the [text insert] command.
The -- argument indicates the end of the options.

The [visible] subcommand

This subcommand makes a text block visible. The complete syntax is:

    text visible ?-w win? pos1 ?pos2?

It scrolls the text in the current pane in order to make the specified range visible. If the pos2 argument is not specified, it is equal to pos1.

Examples

Open the Tcl Shell (with ⌘Y). It starts with the following text:

Welcome to Alpha's AlphaTcl shell.
«»

Now enter the following commands, one by one:

«» text get 0 10
Welcome to
«» text delete 19 24
«» text insert -pos 23 super
«» text replace 0 10 "Greetings from"

In the end, the text should be:

Greetings from Alpha's Tcl supershell.

Last updated 2020-06-30 07:41:43