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