---
name: "Prima::Edit"
section: "3"
platform: "linux"
package: "libprima-perl"
version: "1.28-1.3+b3"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/Prima::Edit"
---

# Prima::Edit(3)

standard text editing widget

## NAME

Prima::Edit - standard text editing widget

## SYNOPSIS

```
        use Prima::Edit;
        my $e = Prima::Edit-> create(
                text         => 'Hello $world',
                syntaxHilite => 1,
        );
        $e-> selection( 1, 1, 1, 2);
```

## DESCRIPTION

The class provides text editing capabilities, three types of selection, text wrapping, syntax highlighting, auto indenting, undo and redo function, search and replace methods.

The module declares `"bt::"` package, that contains integer constants for selection block type, used by blockType property.

## USAGE

The class addresses the text space by (X,Y)-coordinates, where X is character offset and Y is line number. The addressing can be 'physical' and 'logical', - in logical case Y is number of line of text. The difference can be observed if wordWrap property is set to 1, when a single  text string can be shown as several sub-strings, called *chunks*.

The text is stored line-wise in `"{lines}"` array; to access it use get\_line method. To access the text chunk-wise, use get\_chunk method.

All keyboard events, except the character input and tab key handling, are  processed by the accelerator table ( see Prima::Menu ). The default `"accelItems"` table defines names, keyboard combinations, and the corresponding actions to the class functions. The class does not provide functionality to change these mappings. To do so, consult "Prima::AccelTable" in Prima::Menu.

## API

### Events

- ParseSyntax TEXT, RESULT\_ARRAY\_REF

  Called when syntax highlighting is requires - TEXT is a string to be parsed, and the parsing results to be stored in RESULT\_ARRAY\_REF, which is a reference to an array of integer pairs, each representing a single-colored text chunk. The first integer in the pairs is the length of a chunk, the second - color value ( `"cl::XXX"` constants ).

### Properties

- autoIndent BOOLEAN

  Selects if the auto indenting feature is on.

  Default value: 1

- blockType INTEGER

  Defines type of selection block. Can be one of the following constants:

  - bt::CUA

    Normal block, where the first and the last line of the selection can be partial, and the lines between occupy the whole line. CUA stands for 'common user access'.

    Default keys: Shift + arrow keys

    See also: cursor\_shift\_key

  - bt::Vertical

    Rectangular block, where all selected lines are of same offsets and lengths.

    Default key: Alt+B

    See also: mark\_vertical

  - bt::Horizontal

    Rectangular block, where the selection occupies the whole line.

    Default key: Alt+L

    See also: mark\_horizontal

- cursor X, Y

  Selects physical position of the cursor

- cursorX X

  Selects physical horizontal position of the cursor

- cursorY Y

  Selects physical vertical position of the cursor

- cursorWrap BOOLEAN

  Selects cursor behavior when moved horizontally outside the line. If 0, the cursor is not moved. If 1, the cursor moved to the adjacent line.

  See also: cursor\_left, cursor\_right, word\_left, word\_right.

- insertMode BOOLEAN

  Governs the typing mode - if 1, the typed text is inserted, if 0, the text overwrites the old text. When `"insertMode"` is 0, the cursor shape is thick and covers the whole character; when 1, it is of default width.

  Default toggle key: Insert

- hiliteNumbers COLOR

  Selects the color for number highlighting

- hiliteQStrings COLOR

  Selects the color for highlighting the single-quoted strings

- hiliteQQStrings COLOR

  Selects the color for highlighting the double-quoted strings

- hiliteIDs ARRAY

  Array of scalar pairs, that define words to be highlighted. The first item in the pair is an array of words; the second item is a color value.

- hiliteChars ARRAY

  Array of scalar pairs, that define characters to be highlighted. The first item in the pair is a string of characters; the second item is a color value.

- hiliteREs ARRAY

  Array of scalar pairs, that define character patterns to be highlighted. The first item in the pair is a perl regular expression; the second item is a color value.

- mark MARK \[ BLOCK\_TYPE \]

  Selects block marking state. If MARK is 1, starts the block marking, if 0 - stops the block marking. When MARK is 1, BLOCK\_TYPE can be used to set the selection type ( `"bt::XXX"` constants ). If BLOCK\_TYPE is  unset the value of blockType is used.

- markers ARRAY

  Array of arrays with integer pairs, X and Y, where each represents a physical coordinates in text. Used as anchor storage for fast navigation.

  See also: add\_marker, delete\_marker

- modified BOOLEAN

  A boolean flag that shows if the text was modified. Can be used externally, to check if the text is to be saved to a file, for example.

- offset INTEGER

  Horizontal offset of text lines in pixels.

- persistentBlock BOOLEAN

  Selects whether the selection is cancelled as soon as the cursor is moved ( 0 ) or it persists until the selection is explicitly changed ( 1 ).

  Default value: 0

- readOnly BOOLEAN

  If 1, no user input is accepted.

- selection X1, Y1, X2, Y2

  Accepts two pair of coordinates, ( X1,Y1) the beginning and ( X2,Y2) the end of new selection, and sets the block according to blockType property.

  The selection is null if X1 equals to X2 and Y1 equals to Y2.  has\_selection method returns 1 if the selection is non-null.

- selStart X, Y

  Manages the selection start. See selection, X1 and Y1.

- selEnd X, Y

  Manages the selection end. See selection, X2 and Y2.

- syntaxHilite BOOLEAN

  Governs the syntax highlighting. Is not implemented for word wrapping mode.

- tabIndent INTEGER

  Maps tab ( \\t ) key to `"tabIndent"` amount of space characters.

- text TEXT

  Provides access to all the text data. The lines are separated by  the new line ( \\n ) character.

  See also: textRef.

- textRef TEXT\_PTR

  Provides access to all the text data. The lines are separated by  the new line ( \\n ) character. TEXT\_PTR is a pointer to text string.

  The property is more efficient than text with the large text, because the copying of the text scalar to the stack stage is eliminated.

  See also: text.

- topLine INTEGER

  Selects the first line of the text drawn.

- undoLimit INTEGER

  Sets limit on number of stored atomic undo operations. If 0, undo is disabled.

  Default value: 1000

- wantTabs BOOLEAN

  Selects the way the tab ( \\t ) character is recognized in the user input. If 1, it is recognized by the Tab key; however, this disallows the toolkit  widget tab-driven navigation. If 0, the tab character can be entered by pressing Ctrl+Tab key combination.

  Default value: 0

- wantReturns BOOLEAN

  Selects the way the new line ( \\n ) character is recognized in the user input. If 1, it is recognized by the Enter key; however, this disallows the toolkit  default button activation. If 0, the new line character can be entered by pressing Ctrl+Enter key combination.

  Default value: 1

- wordDelimiters STRING

  Contains string of character that are used for locating a word break.  Default STRING value consists of punctuation marks, space and tab characters, and `"\xff"` character.

  See also: word\_left, word\_right

- wordWrap BOOLEAN

  Selects whether the long lines are wrapped, or can be positioned outside the horizontal widget inferior borders. If 1, syntaxHilite is not used. A line of text can be represented by more than one line of screen text ( chunk ) . To access the text chunk-wise, use get\_chunk method.

### Methods

- add\_marker X, Y

  Adds physical coordinated X,Y to markers property.

- back\_char \[ REPEAT = 1 \]

  Removes REPEAT times a character left to the cursor. If the cursor is on 0 x-position, removes the new-line character and concatenates the lines.

  Default key: Backspace

- begin\_undo\_group

  Opens bracket for group of actions, undone as single operation.  The bracket is closed by calling `"end_undo_group"`.

- cancel\_block

  Removes the selection block

  Default key: Alt+U

- change\_locked

  Returns 1 if the logical locking is on, 0 if it is off.

  See also lock\_change.

- copy

  Copies the selected text, if any, to the clipboard.

  Default key: Ctrl+Insert

- copy\_block

  Copies the selected text and inserts it into the cursor position, according to the blockType value.

  Default key: Alt+C

- cursor\_cend

  Moves cursor to the bottom line

  Default key: Ctrl+End

- cursor\_chome

  Moves cursor to the top line

  Default key: Ctrl+Home

- cursor\_cpgdn

  Default key: Ctrl+PageDown

  Moves cursor to the end of text.

- cursor\_cpgup

  Moves cursor to the beginning of text.

  Default key: Ctrl+PageUp

- cursor\_down \[ REPEAT = 1 \]

  Moves cursor REPEAT times down

  Default key: Down

- cursor\_end

  Moves cursor to the end of the line

  Default key: End

- cursor\_home

  Moves cursor to the beginning of the line

  Default key: Home

- cursor\_left \[ REPEAT = 1 \]

  Moves cursor REPEAT times left

  Default key: Left

- cursor\_right \[ REPEAT = 1 \]

  Moves cursor REPEAT times right

  Default key: Right

- cursor\_up \[ REPEAT = 1 \]

  Moves cursor REPEAT times up

  Default key: Up

- cursor\_pgdn \[ REPEAT = 1 \]

  Moves cursor REPEAT pages down

  Default key: PageDown

- cursor\_pgup \[ REPEAT = 1 \]

  Moves cursor REPEAT pages up

  Default key: PageUp

- cursor\_shift\_key \[ ACCEL\_TABLE\_ITEM \]

  Performs action of the cursor movement, bound to ACCEL\_TABLE\_ITEM action ( defined in `"accelTable"` or `"accelItems"` property ), and extends the selection block along the cursor movement. Not called directly.

- cut

  Cuts the selected text into the clipboard.

  Default key: Shift+Delete

- delete\_block

  Removes the selected text.

  Default key: Alt+D

- delete\_char \[ REPEAT = 1 \]

  Delete REPEAT characters from the cursor position

  Default key: Delete

- delete\_line LINE\_ID, \[ LINES = 1 \]

  Removes LINES of text at LINE\_ID.

- delete\_current\_chunk

  Removes the chunk ( or line, if wordWrap is 0 ) at the cursor.

  Default key: Ctrl+Y

- delete\_chunk CHUNK\_ID, \[ CHUNKS = 1 \]

  Removes CHUNKS ( or lines, if wordWrap is 0 ) of text at CHUNK\_ID

- delete\_marker INDEX

  Removes marker INDEX in markers list.

- delete\_to\_end

  Removes text to the end of the chunk.

  Default key: Ctrl+E

- delete\_text X, Y, TEXT\_LENGTH

  Removes TEXT\_LENGTH characters at X,Y physical coordinates

- draw\_colorchunk CANVAS, TEXT, LINE\_ID, X, Y, COLOR

  Paints the syntax-highlighted chunk of TEXT, taken from LINE\_ID line index, at X, Y. COLOR is used if the syntax highlighting information contains `"cl::Fore"` as color reference.

- end\_block

  Stops the block selection session.

- end\_undo\_group

  Closes bracket for group of actions, opened by `"begin_undo_group"`.

- find SEARCH\_STRING, \[ X = 0, Y = 0, REPLACE\_LINE = '', OPTIONS \]

  Tries to find ( and, if REPLACE\_LINE is defined, to replace with it )  SEARCH\_STRING from (X,Y) physical coordinates. OPTIONS is an integer that consists of the `"fdo::"` constants; the same constants are used in Prima::EditDialog, which provides graphic interface to the find and replace facilities of Prima::Edit.

  - fdo::MatchCase

    If set, the search is case-sensitive.

  - fdo::WordsOnly

    If set, SEARCH\_STRING must constitute the whole word.

  - fdo::RegularExpression

    If set, SEARCH\_STRING is a regular expression.

  - fdo::BackwardSearch

    If set, the search direction is backwards.

  - fdo::ReplacePrompt

    Not used in the class, however, used in Prima::EditDialog.

- get\_chunk CHUNK\_ID

  Returns chunk of text, located at CHUNK\_ID.  Returns empty string if chunk is nonexistent.

- get\_chunk\_end CHUNK\_ID

  Returns the index of chunk at CHUNK\_ID, corresponding to the last chunk  of same line.

- get\_chunk\_org CHUNK\_ID

  Returns the index of chunk at CHUNK\_ID, corresponding to the first chunk  of same line.

- get\_chunk\_width TEXT, FROM, LENGTH, \[ RETURN\_TEXT\_PTR \]

  Returns the width in pixels of `"substr( TEXT, FROM, LENGTH)"`. If FROM is larger than length of TEXT, TEXT is padded with space characters. Tab character in TEXT replaced to tabIndent times space character. If RETURN\_TEXT\_PTR pointer is specified, the converted TEXT is stored there.

- get\_line INDEX

  Returns line of text, located at INDEX.  Returns empty string if line is nonexistent.

- get\_line\_dimension INDEX

  Returns two integers, representing the line at INDEX in wordWrap mode: the first value is the corresponding chunk index, the second is how many chunks represent the line.

  See also: make\_logical.

- get\_line\_ext CHUNK\_ID

  Returns the line, corresponding to the chunk index.

- has\_selection

  Returns boolean value, indicating if the selection block is active.

- insert\_empty\_line LINE\_ID, \[ REPEAT = 1 \]

  Inserts REPEAT empty lines at LINE\_ID.

- insert\_line LINE\_ID, @TEXT

  Inserts `@TEXT` strings at LINE\_ID

- insert\_text TEXT, \[ HIGHLIGHT = 0 \]

  Inserts TEXT at the cursor position. If HIGHLIGHT is set to 1, the selection block is cancelled and the newly inserted text is selected.

- lock\_change BOOLEAN

  Increments ( 1 ) or decrements ( 0 ) lock count. Used to defer change notification in multi-change calls. When internal lock count hits zero, `"Change"` notification is called.

- make\_logical X, Y

  Maps logical X,Y coordinates to the physical and returns the integer pair. Returns same values when wordWrap is 0.

- make\_physical X, Y

  Maps physical X,Y coordinates to the logical and returns the integer pair.

  Returns same values when wordWrap is 0.

- mark\_horizontal

  Starts block marking session with `"bt::Horizontal"` block type.

  Default key: Alt+L

- mark\_vertical

  Starts block marking session with `"bt::Vertical"` block type.

  Default key: Alt+B

- overtype\_block

  Copies the selected text and overwrites the text next to the cursor position, according to the blockType value.

  Default key: Alt+O

- paste

  Copies text from the clipboard and inserts it in the cursor position.

  Default key: Shift+Insert

- realize\_panning

  Performs deferred widget panning, activated by setting `"{delayPanning}"` to 1. The deferred operations are those performed by offset and topLine.

- redo

  Re-applies changes, formerly rolled back by `"undo"`.

- set\_line LINE\_ID, TEXT, \[ OPERATION, FROM, LENGTH \]

  Changes line at LINE\_ID to new TEXT. Hint scalars OPERATION, FROM and LENGTH used to maintain selection and marking data. OPERATION is an arbitrary string, the ones that are recognized are `'overtype'`, `'add'`, and `'delete'`. FROM and LENGTH define the range of the change; FROM is a character offset and LENGTH is a length of changed text.

- split\_line

  Splits a line in two at the cursor position.

  Default key: Enter ( or Ctrl+Enter if wantReturns is 0 )

- select\_all

  Selects all text

- start\_block \[ BLOCK\_TYPE \]

  Begins the block selection session. The block type if BLOCK\_TYPE, if it is specified, or blockType property value otherwise.

- undo

  Rolls back changes into internal array, which size cannot extend `"undoLimit"` value. In case `"undoLimit"` is 0, no undo actions can be made.

- update\_block

  Adjusts the selection inside the block session, extending of shrinking it to  the current cursor position.

- word\_left \[ REPEAT = 1 \]

  Moves cursor REPEAT words to the left.

- word\_right \[ REPEAT = 1 \]

  Moves cursor REPEAT words to the right.

## AUTHOR

Dmitry Karasik, \<dmitry@karasik.eu.org\>.

## SEE ALSO

Prima, Prima::Widget, Prima::EditDialog, Prima::IntUtils, *examples/editor.pl*