Prima::Edit(3)

User Contributed Perl Documentation

Prima::Edit(3)

NAME¶

Prima::Edit - standard text editor

SYNOPSIS¶

        use Prima qw(Edit Application);
        my $e = Prima::Edit->new(
                text         => 'Hello $world',
                syntaxHilite => 1,
        );
        run Prima;

DESCRIPTION¶

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

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

USAGE¶

The text is stored line-wise in the "{lines}" array; to access it use the get_line method.

All keyboard events except the character input and tab keys 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.

Coordinates¶

The class addresses the text space by (X,Y)-coordinates, where X is the visual cluster offset and Y is the line number. The addressing coordinate system can be visual, physical, or logical. See below.

Cluster shaping and word wrapping can play a role here. Consider f.ex. a text string "offset is zero", that for the sake of the example can wrapped by width and displayed as two lines, "offset" and "is zero". Here, the font substitutes "ff" text with a single ligature glyph. Here, for example, coord("f") will be (0,1) in all coordinates, but coord("z") is not:

Physical

The X coordinate is a character offset from character line number Y. These coordinates are identical with and without the "wordWrap" flag. This coordinate is used for direct text manipulation.

Example: coord("z") is (0,10);

Visual

The X coordinate is a glyph cluster offset from the character line number Y. These coordinates are identical with and without the "wordWrap" flag. This coordinate is used for cursor and selection API.

Example: coord("z") is (0,9);

Logical

The Y coordinate is the wrapped line index. The "chunkMap" internal array contains addresses in the logical coordinates. The X coordinate is a glyph cluster offset from the line start. This coordinate is used mostly internally.

To access the text chunk-wise, use the get_chunk method.

Example: coord("z") is (1,3);

API¶

Events¶

ParseSyntax TEXT, RESULT_ARRAY_REF: Called when syntax highlighting is required - 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: Turns the auto indenting on or off
Default value: 1
blockType INTEGER: Defines the 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: mark_horizontal

cursor X, Y

Selects the visual position of the cursor

cursorX X

Selects the visual horizontal position of the cursor

cursorY Y

Selects the visual 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

Set the typing mode - if 1, the typed text is inserted, if 0, the new text overwrites the old text. When "insertMode" is 0, the cursor shape is thick and covers the whole character; when 1, it is of the default cursor 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

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

hiliteChars ARRAY

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

hiliteREs ARRAY

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

Note: these are tricky. Generally, these assume that whatever is captured in "()", is highlighted, and that capturing parentheses match from the first character onwards. So for simple matches like " (\d+) " (digits) or " (#.*) " this works fine. Things become more interesting if you need to check text after, or especially before the capture. For this, you need to make sure that whatever text is matched by a regexp, it must not move the "pos" pointer as the regexes are internally concatenated with the "\G" anchor before the actual matching takes place (i.e. starting each time from the position the previous regex left off), and use "/gc" flags (advancing "pos" to the match length). Advancing the "pos" will nullify color highlighting on the text after the capture but before the end of the match - so you'll need look-ahead assertions for this type of match, "(?=pattern) " and "(?!pattern)" (see "Lookaround Assertions" in perlre ).

For example, we have a string "ABC123abc", and we want to match 123 followed by abc. This won't work:

        hiliteREs => [
                '(123)abc',cl::LightRed,
                '(abc)', cl::LightGreen
        ]

while this will:

        hiliteREs => [
                '(123)(?=abc)',cl::LightRed,
                '(abc)', cl::LightGreen 
        ]

If you need to look behind, the corresponding assertions " (?<=pattern) " and " (?<!pattern) " could be used, but these are even more restrictive in that they only support fixed-width looks-behinds (NB: " \K " won't work because of " \G " either). That way, if we want to match 123 that follows ABC, this won't work:

        hiliteREs =>  [
                '(ABC)',cl::LightBlue,
                '(?<=[ABC]+)(123)',cl::LightRed,
        ]

while this will:

        hiliteREs =>  [
                '(ABC)',cl::LightBlue,
                '(?<=[ABC]{3})(123)',cl::LightRed,
        ]

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

An array of arrays with integer pairs, X and Y, where each represents visual coordinates in text. Used as anchor storage for fast navigation.

Methods¶

add_marker X, Y: Adds visual coordinates X,Y to the 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 two lines.
Default key: Backspace
cancel_block: Removes the selection block
Default key: Alt+U
change_locked: Returns 1 if the logical locking is on, and 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 last line
Default key: Ctrl+End
cursor_chome: Moves cursor to the first 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 ]: Deletes 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 the markers list.
delete_to_end: Removes the 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, LINE_ID, X, Y, COLOR: Paints the syntax-highlighted chunk taken from LINE_ID line index, at X, Y. COLOR is used if the syntax highlighting information contains "cl::Fore" as a color reference.
end_block: Stops the block selection session.
find SEARCH_STRING, [ X = 0, Y = 0, REPLACE_LINE = '', OPTIONS ]: Tries to find ( and, if REPLACE_LINE is defined, to replace with ) SEARCH_STRING starting from (X,Y) physical coordinates. OPTIONS is an integer that is a combination of the "fdo::" constants; the same constants are used in Prima::Dialog::FindDialog, which provides a graphic interface to the find and replace facilities of this class.
Returns X1, Y, X2, NEW_STRING where X1.Y-X2.Y are physical coordinates of the string found, and NEW_STRING is the replaced version (if any)

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 backward.
fdo::ReplacePrompt: Not used in the class, however, used in Prima::Dialog::FindDialog.

AUTHOR¶

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

Source file:	Prima::Edit.3pm.en.gz (from perl-Prima 1.72000-1.1)
Source last updated:	2024-03-08T20:56:16Z
Converted to HTML:	2024-05-01T01:42:07Z