The [$editorToken] command.

Introduction

This page documents the syntax of the Tcl command associated with TextView views created with the [view create TextView] command. The actual name of the command is the view's token (designated by $editorToken in the rest of this document).

Synopsis

The formal syntax of the $editorToken command is:

$editorToken subcommand ?options?

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

The [color] subcommand

This subcommand lets you set or remove a color on a range of text. The complete syntax is:

$editorToken color colorToken ?range?

The range argument is a two-element list containing the start and end positions of the region. If range is not specified, the command applies to the entire text.
The colorToken argument is a color token (typically obtained with the [colorRef create] command). Specifying an empty string restores the default black color.

The [delete] subcommand

This subcommand deletes the chunk of text between two positions. The complete syntax is:

$editorToken delete pos1 pos2

If one of the specified positions pos1 or pos2 is out of range, an error occurs.

The [exec] subcommand

This subcommand lets you execute simple actions. The complete syntax is:

$editorToken exec action

The action argument is the name of a standard command to perform on the currently selected region. It is the name of a Cocoa method that is defined in the NSTextView class (or inherited from a parent class) and takes a unique nullable argument. The main methods available are given in the following table:

Alignment	alignCenter, alignJustified, alignLeft, alignRight
Case changes	capitalizeWord, lowercaseWord, uppercaseWord
Deletions	delete, deleteBackward, deleteForward, deleteToBeginningOfLine, deleteToBeginningOfParagraph, deleteToEndOfLine, deleteToEndOfParagraph, deleteWordBackward, deleteWordForward
Insertions	insertBacktab, insertContainerBreak, insertLineBreak, insertNewline, insertParagraphSeparator, insertTab, insertTabIgnoringFieldEditor
Marks	deleteToMark, selectToMark, setMark, swapWithMark
Miscellaneous	print, showGuessPanel, startSpeaking, stopSpeaking
Movement	moveBackward, moveDown, moveForward, moveLeft, moveRight, moveToBeginningOfDocument, moveToBeginningOfLine, moveToBeginningOfParagraph, moveToEndOfDocument, moveToEndOfLine, moveToEndOfParagraph, moveToLeftEndOfLine, moveToRightEndOfLine, moveUp, moveWordBackward, moveWordForward, moveWordLeft, moveWordRight, pageDown, pageUp
Movement and selection	moveBackwardAndModifySelection, moveDownAndModifySelection, moveForwardAndModifySelection, moveLeftAndModifySelection, moveParagraphBackwardAndModifySelection, moveParagraphForwardAndModifySelection, moveRightAndModifySelection, moveToBeginningOfDocumentAndModifySelection, moveToBeginningOfLineAndModifySelection, moveToBeginningOfParagraphAndModifySelection, moveToEndOfDocumentAndModifySelection, moveToEndOfLineAndModifySelection, moveToEndOfParagraphAndModifySelection, moveToLeftEndOfLineAndModifySelection, moveToRightEndOfLineAndModifySelection, moveUpAndModifySelection, moveWordBackwardAndModifySelection, moveWordForwardAndModifySelection, moveWordLeftAndModifySelection, moveWordRightAndModifySelection, pageDownAndModifySelection, pageUpAndModifySelection
Pasteboard	copy, cut, paste, pasteAsPlainText, pasteAsRichText, yank
Scrolling	scrollLineDown, scrollLineUp, scrollPageDown, scrollPageUp, scrollToBeginningOfDocument, scrollToEndOfDocument
Selection	centerSelectionInVisibleArea, selectAll, selectLine, selectParagraph, selectWord
Style	outline, subscript, superscript, underline, unscript

The list above is not exhaustive. Technically, any method inherited by the NSTextView class and whose signature has a unique nullabe argument sender can be used.

The [get] subcommand

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

$editorToken get pos1 pos2

If one of the specified positions pos1 or pos2 is out of range, an error occurs.

The [hyper] subcommand

This subcommand lets you install or remove a hyperlink on a range of text. The complete syntax is:

$editorToken hyper (proc|URL) ?range?

The range argument is a two-element list containing the start and end positions of the region. If range is not specified, the command applies to the entire text.
The (proc|URL) argument attaches either a script to execute or an URL to open when the user clicks on the specified range of text. This option causes the corresponding region to be colored in blue and underlined. Specifying an empty string removes the hyperlink.

The [insert] subcommand

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

$editorToken insert ?-pos num? ?--? text

The -pos option specifies the position where the text is to be inserted. If this option is not specified, the text is inserted at the current position. The command clears any existing selection before the text is inserted.
The -- argument indicates the end of the options.

The [maxPos] subcommand

This subcommand returns the total length of the text contained in the text view. The complete syntax is:

$editorToken maxPos

The [pos] subcommand

This subcommand lets you get or set the current insertion position in the text view. The complete syntax is:

$editorToken pos ?num?

If there is no num argument, the command returns the current position of the insertion cursor. Otherwise it sets the position to num: if num is out of range, it raises an error. To know the length of the text, see the maxPos subcommand.

The [register] subcommand

This subcommand lets you register a Tcl callback to invoke for some action. The complete syntax is:

$editorToken register action callback

The callback argument is the name of a Tcl proc that will be invoked when the action is executed. Setting the callback argument to an empty string unregisters a previously declared callback for the given action (if there is no such callback, nothing happens). There are two kinds of actions explained in the next sections.

Standard bindable actions

The action argument can be the name of a Cocoa method defined in the NSTextView class that takes a unique nullable argument (as with the [$editorToken exec] command). It corresponds to a simple user action (like pressing the arrow keys for instance). See the available names in this table.
In that case, the callback proc takes a single argument which is the text view's token. For example, you can declare a callback for the moveRight action like this:

$editorToken register moveRight myProc

and the proc myProc should have the following prototype:

proc myProc {token} {
    # instructions here
}

If myProc raises an error, then the default implementation of action is executed.

The willChangeSelection action

If the action argument is willChangeSelection, then the callback proc is invoked each time the user attempts to modify the selection. It takes three arguments:

the text view's token
the old selected char range
the new proposed char range

Each range is represented by a two-element list containing the start and end positions of the range. The proc is expected to return the wanted range: this is an opportunity for the Tcl script to modify or adjust the proposed selection. For example, you can declare a callback for the willChangeSelection action like this:

$editorToken register willChangeSelection mySelectionProc

and the proc mySelectionProc should have the following prototype:

proc mySelectionProc {token old new} {
    # instructions here to compute actual selection's start and end
	return [list $start $end]
}

The [search] subcommand

This subcommand lets you search for a string or pattern in the text view. The complete syntax is:

$editorToken search ?options? pattern pos

It supports the exact same options as the search command for document windows (with the exception of the -w option, which is not relevant here). For more information, see the [search] page.

The [select] subcommand

This subcommand lets you set the selection. The complete syntax is:

$editorToken select start end

The start and end arguments are the starting and ending positions respectively of the region to hilite. If the positions are out of range, an error occurs. The command clears the current selection before installing the new one.

The [selEnd] subcommand

This subcommand lets you get the end of the hilited selection. The complete syntax is:

$editorToken selEnd

It returns the end position of the hilited selection, or the current insertion position if no text is selected. In the case of a multiple selection, the returned value is the end of the first selected range.

The [style] subcommand

This subcommand lets you set or remove a style on a range of text. The complete syntax is:

$editorToken style num ?range?

The range argument is a two-element list containing the start and end positions of the region. If range is not specified, the command applies to the entire text.
The num argument specifies a font style. Its value is a combination of the following additive flags:

normal	0
italic	1
bold	2

Specify a null value to remove any italic or bold style.

Examples

Here are a few basic examples which can be executed one by one in the Tcl Shell (⌘Y).
Let's create a root window containing a TextView view:

set root [view root Document -frame {220 250 440 360}]
set edToken [view create TextView -frame {10 10 420 340} -parent $root]
view show $root

The variable $edToken contains the token of the TextView which is also the name of the command associated with this view. All the following instructions use this $edToken command.
First add some text to the view:

$edToken insert "Optimus pretosius rures corrumperet ossifragi, et catelli\
		imputat umbraculi. Fragilis zothecas plane neglegenter iocari\
		utilitas ossifragi."

Move cursor to start of text:

$edToken pos 0

Search for the word ossifragi and hilite it:

set res [$edToken search ossifragi 0]
$edToken select {*}$res

Colorize ossifragi in red:

$edToken color [colors::named red] $res

Convert the word at current position to uppercase:

$edToken exec uppercaseWord

Find all occurrences of ossifragi in a case-insensitive manner:

$edToken search -i 1 -all ossifragi 0

Select the entire text and put it in the pasteboard:

$edToken exec selectAll
$edToken exec copy

Last updated 2020-07-09 19:39:58