Prima::Edit - standard text editing widget 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 the blockType manpage property. use Prima::Edit; my $e = Prima::Edit-> create( text => 'Hello $world', syntaxHilite => 1, ); $e-> selection( 1, 1, 1, 2); 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 the wordWrap manpage 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 the get_line manpage method. To access the text chunk-wise, use the get_chunk manpage method. All keyboard events, except the character input and tab key handling, are processed by the accelerator table ( see the Prima::Menu manpage ). 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 the Prima::AccelTable entry in the Prima::Menu manpage.

Events
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
Selects if the auto indenting feature is on. Default value: 1 Defines type of selection block. Can be one of the following constants: 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: the cursor_shift_key manpage Rectangular block, where all selected lines are of same offsets and lengths. Default key: Alt+B See also: the mark_vertical manpage Rectangular block, where the selection occupies the whole line. Default key: Alt+L See also: the mark_horizontal manpage Selects physical position of the cursor Selects physical horizontal position of the cursor Selects physical vertical position of the cursor 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: the cursor_left manpage, the cursor_right manpage, the word_left manpage, the word_right manpage. 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 Selects the color for number highlighting Selects the color for highlighting the single-quoted strings Selects the color for highlighting the double-quoted strings 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. 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. 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. 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 the blockType manpage is used. 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: the add_marker manpage, the delete_marker manpage 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. Horizontal offset of text lines in pixels. 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 If 1, no user input is accepted. Accepts two pair of coordinates, ( X1,Y1) the beginning and ( X2,Y2) the end of new selection, and sets the block according to the blockType manpage property. The selection is null if X1 equals to X2 and Y1 equals to Y2. the has_selection manpage method returns 1 if the selection is non-null. Manages the selection start. See the selection manpage, X1 and Y1. Manages the selection end. See the selection manpage, X2 and Y2. Governs the syntax highlighting. Is not implemented for word wrapping mode. Maps tab ( \t ) key to tabIndent amount of space characters. Provides access to all the text data. The lines are separated by the new line ( \n ) character. See also: the textRef manpage. 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 the text manpage with the large text, because the copying of the text scalar to the stack stage is eliminated. See also: the text manpage. Selects the first line of the text drawn. Sets limit on number of stored atomic undo operations. If 0, undo is disabled. Default value: 1000 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 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 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: the word_left manpage, the word_right manpage Selects whether the long lines are wrapped, or can be positioned outside the horizontal widget inferior borders. If 1, the syntaxHilite manpage 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 the get_chunk manpage method.

Methods
Adds physical coordinated X,Y to the markers manpage property. 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 Opens bracket for group of actions, undone as single operation. The bracket is closed by calling end_undo_group. Removes the selection block Default key: Alt+U Returns 1 if the logical locking is on, 0 if it is off. See also the lock_change manpage. Copies the selected text, if any, to the clipboard. Default key: Ctrl+Insert Copies the selected text and inserts it into the cursor position, according to the the blockType manpage value. Default key: Alt+C Moves cursor to the bottom line Default key: Ctrl+End Moves cursor to the top line Default key: Ctrl+Home Default key: Ctrl+PageDown Moves cursor to the end of text. Moves cursor to the beginning of text. Default key: Ctrl+PageUp Moves cursor REPEAT times down Default key: Down Moves cursor to the end of the line Default key: End Moves cursor to the beginning of the line Default key: Home Moves cursor REPEAT times left Default key: Left Moves cursor REPEAT times right Default key: Right Moves cursor REPEAT times up Default key: Up Moves cursor REPEAT pages down Default key: PageDown Moves cursor REPEAT pages up Default key: PageUp 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. Cuts the selected text into the clipboard. Default key: Shift+Delete Removes the selected text. Default key: Alt+D Delete REPEAT characters from the cursor position Default key: Delete Removes LINES of text at LINE_ID. Removes the chunk ( or line, if the wordWrap manpage is 0 ) at the cursor. Default key: Ctrl+Y Removes CHUNKS ( or lines, if the wordWrap manpage is 0 ) of text at CHUNK_ID Removes marker INDEX in the markers manpage list. Removes text to the end of the chunk. Default key: Ctrl+E Removes TEXT_LENGTH characters at X,Y physical coordinates 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. Stops the block selection session. Closes bracket for group of actions, opened by begin_undo_group. 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 the Prima::EditDialog manpage, which provides graphic interface to the find and replace facilities of the Prima::Edit manpage. If set, the search is case-sensitive. If set, SEARCH_STRING must constitute the whole word. If set, SEARCH_STRING is a regular expression. If set, the search direction is backwards. Not used in the class, however, used in the Prima::EditDialog manpage. Returns chunk of text, located at CHUNK_ID. Returns empty string if chunk is nonexistent. Returns the index of chunk at CHUNK_ID, corresponding to the last chunk of same line. Returns the index of chunk at CHUNK_ID, corresponding to the first chunk of same line. 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 the tabIndent manpage times space character. If RETURN_TEXT_PTR pointer is specified, the converted TEXT is stored there. Returns line of text, located at INDEX. Returns empty string if line is nonexistent. Returns two integers, representing the line at INDEX in the wordWrap manpage mode: the first value is the corresponding chunk index, the second is how many chunks represent the line. See also: the make_logical manpage. Returns the line, corresponding to the chunk index. Returns boolean value, indicating if the selection block is active. Inserts REPEAT empty lines at LINE_ID. Inserts @TEXT strings at LINE_ID Inserts TEXT at the cursor position. If HIGHLIGHT is set to 1, the selection block is cancelled and the newly inserted text is selected. 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. Maps logical X,Y coordinates to the physical and returns the integer pair. Returns same values when the wordWrap manpage is 0. Maps physical X,Y coordinates to the logical and returns the integer pair. Returns same values when the wordWrap manpage is 0. Starts block marking session with bt::Horizontal block type. Default key: Alt+L Starts block marking session with bt::Vertical block type. Default key: Alt+B Copies the selected text and overwrites the text next to the cursor position, according to the the blockType manpage value. Default key: Alt+O Copies text from the clipboard and inserts it in the cursor position. Default key: Shift+Insert Performs deferred widget panning, activated by setting {delayPanning} to 1. The deferred operations are those performed by the offset manpage and the topLine manpage. Re-applies changes, formerly rolled back by undo. 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. Splits a line in two at the cursor position. Default key: Enter ( or Ctrl+Enter if the wantReturns manpage is 0 ) Selects all text Begins the block selection session. The block type if BLOCK_TYPE, if it is specified, or the blockType manpage property value otherwise. Rolls back changes into internal array, which size cannot extend undoLimit value. In case undoLimit is 0, no undo actions can be made. Adjusts the selection inside the block session, extending of shrinking it to the current cursor position. Moves cursor REPEAT words to the left. Moves cursor REPEAT words to the right. Dmitry Karasik, <dmitry@karasik.eu.org>. the Prima manpage, the Prima::Widget manpage, the Prima::EditDialog manpage, the Prima::IntUtils manpage, examples/editor.pl