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