1Prima::Edit(3) User Contributed Perl Documentation Prima::Edit(3)
2
6 Prima::Edit - standard text editing widget
7
9 use Prima qw(Edit Application);
10 my $e = Prima::Edit->new(
11 text => 'Hello $world',
12 syntaxHilite => 1,
13 );
14 run Prima;
15
17 The class provides text editing capabilities, three types of selection,
18 text wrapping, syntax highlighting, auto indenting, undo and redo
19 function, search and replace methods.
20 The module declares "bt::" package, that contains integer constants for
22 selection block type, used by blockType property.
23
25 The text is stored line-wise in "{lines}" array; to access it use
26 get_line method. To access the text chunk-wise, use get_chunk method.
27 All keyboard events, except the character input and tab key handling,
29 are processed by the accelerator table ( see Prima::Menu ). The default
30 "accelItems" table defines names, keyboard combinations, and the
31 corresponding actions to the class functions. The class does not
32 provide functionality to change these mappings. To do so, consult
33 "Prima::AccelTable" in Prima::Menu.
34 Coordinates
36 The class addresses the text space by (X,Y)-coordinates, where X is
37 visual cluster offset and Y is line number. The addressing can be
38 'visual' and 'logical', - in logical case Y is number of line of text.
39 The difference can be observed if wordWrap property is set to 1, when a
40 single text string can be shown as several sub-strings, called chunks.
41 Cluster shaping and word wrapping can play a role here. Consider f.ex.
43 text "offset is zero", that for the sake of the example can wrapped by
44 width and displayed as two lines, "offset" and "is zero". Here, the
45 font substitutes "ff" text with a single ligature glyph. Here, for
46 example, coord("f") will be (0,1) in all coordinates, but coord("z") is
47 different:
48 Physical
50 X coordinate is a character offset from character line number Y.
51 These coordinates are identical with and without "wordWrap" flag.
52 This coordinate is used for direct text manipulation.
53 Example: coord("z") is (0,10);
55 Visual
57 X coordinate is a glyph cluster offset from character line number
58 Y. These coordinates are identical with and without "wordWrap"
59 flag. This coordinate is used for cursor and selection API.
60 Example: coord("z") is (0,9);
62 Logical
64 Y coordinates is a wrapped line index. "chunkMap" internal array is
65 addresses in logical coordinates. X coordinate is a glyph cluster
66 offset from the line start. This coordinate is used mostly
67 internally.
68 Example: coord("z") is (1,3);
70
72 Events
73 ParseSyntax TEXT, RESULT_ARRAY_REF
74 Called when syntax highlighting is requires - TEXT is a string to
75 be parsed, and the parsing results to be stored in
76 RESULT_ARRAY_REF, which is a reference to an array of integer
77 pairs, each representing a single-colored text chunk. The first
78 integer in the pairs is the length of a chunk, the second - color
79 value ( "cl::XXX" constants ).
80 Properties
82 autoIndent BOOLEAN
83 Selects if the auto indenting feature is on.
84 Default value: 1
86 blockType INTEGER
88 Defines type of selection block. Can be one of the following
89 constants:
90 bt::CUA
92 Normal block, where the first and the last line of the
93 selection can be partial, and the lines between occupy the
94 whole line. CUA stands for 'common user access'.
95 Default keys: Shift + arrow keys
97 See also: cursor_shift_key
99 bt::Vertical
101 Rectangular block, where all selected lines are of same offsets
102 and lengths.
103 Default key: Alt+B
105 See also: mark_vertical
107 bt::Horizontal
109 Rectangular block, where the selection occupies the whole line.
110 Default key: Alt+L
112 See also: mark_horizontal
114 cursor X, Y
116 Selects visual position of the cursor
117 cursorX X
119 Selects visual horizontal position of the cursor
120 cursorY Y
122 Selects visual vertical position of the cursor
123 cursorWrap BOOLEAN
125 Selects cursor behavior when moved horizontally outside the line.
126 If 0, the cursor is not moved. If 1, the cursor moved to the
127 adjacent line.
128 See also: cursor_left, cursor_right, word_left, word_right.
130 insertMode BOOLEAN
132 Governs the typing mode - if 1, the typed text is inserted, if 0,
133 the text overwrites the old text. When "insertMode" is 0, the
134 cursor shape is thick and covers the whole character; when 1, it is
135 of default width.
136 Default toggle key: Insert
138 hiliteNumbers COLOR
140 Selects the color for number highlighting
141 hiliteQStrings COLOR
143 Selects the color for highlighting the single-quoted strings
144 hiliteQQStrings COLOR
146 Selects the color for highlighting the double-quoted strings
147 hiliteIDs ARRAY
149 Array of scalar pairs, that define words to be highlighted. The
150 first item in the pair is an array of words; the second item is a
151 color value.
152 hiliteChars ARRAY
154 Array of scalar pairs, that define characters to be highlighted.
155 The first item in the pair is a string of characters; the second
156 item is a color value.
157 hiliteREs ARRAY
159 Array of scalar pairs, that define character patterns to be
160 highlighted. The first item in the pair is a perl regular
161 expression; the second item is a color value.
162 Note: these are tricky. Generally, they assume that whatever is
164 captured in (), is highlighted, and that capturing parentheses
165 match from the first character onwards. So for simple matches like
166 " (\d+) " (digits) or " (#.*) " this works fine. Things become more
167 interesting if you need to check text after, or especially before
168 the capture. For this you need to make sure that whatever text is
169 matched by a regexp, need not move "pos" pointer as the regexes are
170 looped over with "\G" anchor prepended (i.e. starting each time
171 from the position the previous regex left off), and with "/gc"
172 flags (advancing " pos " to the match length). Advancing the "pos"
173 will skip color highlighting on text after the capture but before
174 end of the match - so you'll need look-ahead assertions, "
175 (?=pattern) " and " (?!pattern) " (see "Lookaround Assertions" in
176 perlre ).
177 For example, we have a string " ABC123abc ", and we want to match
179 123 followed by abc. This won't work
180 hiliteREs => [
182 '(123)abc',cl::LightRed,
183 '(abc)', cl::LightGreen
184 ]
185 while this will:
187 hiliteREs => [
189 '(123)(?=abc)',cl::LightRed,
190 '(abc)', cl::LightGreen
191 ]
192 If you need to look behind, the corresponding assertions "
194 (?<=pattern) " and " (?<!pattern) " could be used, but these are
195 even more restrictive in that they only support fixed-width looks-
196 behinds (NB: " \K " won't work because of " \G " either). That way,
197 if we want to match 123 that follow ABC, this won't work:
198 hiliteREs => [
200 '(ABC)',cl::LightBlue,
201 '(?<=[ABC]+)(123)',cl::LightRed,
202 ]
203 while this will:
205 hiliteREs => [
207 '(ABC)',cl::LightBlue,
208 '(?<=[ABC]{3})(123)',cl::LightRed,
209 ]
210 mark MARK [ BLOCK_TYPE ]
212 Selects block marking state. If MARK is 1, starts the block
213 marking, if 0 - stops the block marking. When MARK is 1, BLOCK_TYPE
214 can be used to set the selection type ( "bt::XXX" constants ). If
215 BLOCK_TYPE is unset the value of blockType is used.
216 markers ARRAY
218 Array of arrays with integer pairs, X and Y, where each represents
219 a visual coordinates in text. Used as anchor storage for fast
220 navigation.
221 See also: add_marker, delete_marker
223 modified BOOLEAN
225 A boolean flag that shows if the text was modified. Can be used
226 externally, to check if the text is to be saved to a file, for
227 example.
228 offset INTEGER
230 Horizontal offset of text lines in pixels.
231 persistentBlock BOOLEAN
233 Selects whether the selection is cancelled as soon as the cursor is
234 moved ( 0 ) or it persists until the selection is explicitly
235 changed ( 1 ).
236 Default value: 0
238 readOnly BOOLEAN
240 If 1, no user input is accepted. Manipulations with text are
241 allowed though.
242 selection X1, Y1, X2, Y2
244 Accepts two pair of visual coordinates, (X1,Y1) the beginning and
245 (X2,Y2) the end of new selection, and sets the block according to
246 blockType property.
247 The selection is null if X1 equals to X2 and Y1 equals to Y2.
249 has_selection method returns 1 if the selection is non-null.
250 selStart X, Y
252 Manages the selection start. See selection, X1 and Y1.
253 selEnd X, Y
255 Manages the selection end. See selection, X2 and Y2.
256 syntaxHilite BOOLEAN
258 Governs the syntax highlighting. Is not implemented for word
259 wrapping mode.
260 tabIndent INTEGER
262 Maps tab ( \t ) key to "tabIndent" amount of space characters.
263 text TEXT
265 Provides access to all the text data. The lines are separated by
266 the new line ( \n ) character.
267 See also: textRef.
269 textDirection BOOLEAN
271 If set, indicates RTL text input.
272 textLigation BOOLEAN
274 If set, text may be rendered at better quality with ligation and
275 kerning, however that comes with a price that some ligatures may be
276 indivisible and form clusters (f.ex. ff or ffi ligatures). Cursor
277 cannot go inside of such clusters, and thus one can only select
278 them, delete as whole, or press Del/Backspace on the cluster's
279 edge.
280 textRef TEXT_PTR
282 Provides access to all the text data. The lines are separated by
283 the new line ( \n ) character. TEXT_PTR is a pointer to text
284 string.
285 The property is more efficient than text with the large text,
287 because the copying of the text scalar to the stack stage is
288 eliminated.
289 See also: text.
291 topLine INTEGER
293 Selects the first line of the text drawn.
294 undoLimit INTEGER
296 Sets limit on number of stored atomic undo operations. If 0, undo
297 is disabled.
298 Default value: 1000
300 wantTabs BOOLEAN
302 Selects the way the tab ( \t ) character is recognized in the user
303 input. If 1, it is recognized by the Tab key; however, this
304 disallows the toolkit widget tab-driven navigation. If 0, the tab
305 character can be entered by pressing Ctrl+Tab key combination.
306 Default value: 0
308 wantReturns BOOLEAN
310 Selects the way the new line ( \n ) character is recognized in the
311 user input. If 1, it is recognized by the Enter key; however, this
312 disallows the toolkit default button activation. If 0, the new line
313 character can be entered by pressing Ctrl+Enter key combination.
314 Default value: 1
316 wordDelimiters STRING
318 Contains string of character that are used for locating a word
319 break. Default STRING value consists of punctuation marks, space
320 and tab characters, and "\xff" character.
321 See also: word_left, word_right
323 wordWrap BOOLEAN
325 Selects whether the long lines are wrapped, or can be positioned
326 outside the horizontal widget inferior borders. If 1, syntaxHilite
327 is not used. A line of text can be represented by more than one
328 line of screen text ( chunk ) . To access the text chunk-wise, use
329 get_chunk method.
330 Methods
332 add_marker X, Y
333 Adds visual coordinated X,Y to markers property.
334 back_char [ REPEAT = 1 ]
336 Removes REPEAT times a character left to the cursor. If the cursor
337 is on 0 x-position, removes the new-line character and concatenates
338 the lines.
339 Default key: Backspace
341 cancel_block
343 Removes the selection block
344 Default key: Alt+U
346 change_locked
348 Returns 1 if the logical locking is on, 0 if it is off.
349 See also lock_change.
351 copy
353 Copies the selected text, if any, to the clipboard.
354 Default key: Ctrl+Insert
356 copy_block
358 Copies the selected text and inserts it into the cursor position,
359 according to the blockType value.
360 Default key: Alt+C
362 cursor_cend
364 Moves cursor to the bottom line
365 Default key: Ctrl+End
367 cursor_chome
369 Moves cursor to the top line
370 Default key: Ctrl+Home
372 cursor_cpgdn
374 Default key: Ctrl+PageDown
375 Moves cursor to the end of text.
377 cursor_cpgup
379 Moves cursor to the beginning of text.
380 Default key: Ctrl+PageUp
382 cursor_down [ REPEAT = 1 ]
384 Moves cursor REPEAT times down
385 Default key: Down
387 cursor_end
389 Moves cursor to the end of the line
390 Default key: End
392 cursor_home
394 Moves cursor to the beginning of the line
395 Default key: Home
397 cursor_left [ REPEAT = 1 ]
399 Moves cursor REPEAT times left
400 Default key: Left
402 cursor_right [ REPEAT = 1 ]
404 Moves cursor REPEAT times right
405 Default key: Right
407 cursor_up [ REPEAT = 1 ]
409 Moves cursor REPEAT times up
410 Default key: Up
412 cursor_pgdn [ REPEAT = 1 ]
414 Moves cursor REPEAT pages down
415 Default key: PageDown
417 cursor_pgup [ REPEAT = 1 ]
419 Moves cursor REPEAT pages up
420 Default key: PageUp
422 cursor_shift_key [ ACCEL_TABLE_ITEM ]
424 Performs action of the cursor movement, bound to ACCEL_TABLE_ITEM
425 action ( defined in "accelTable" or "accelItems" property ), and
426 extends the selection block along the cursor movement. Not called
427 directly.
428 cut Cuts the selected text into the clipboard.
430 Default key: Shift+Delete
432 delete_block
434 Removes the selected text.
435 Default key: Alt+D
437 delete_char [ REPEAT = 1 ]
439 Delete REPEAT characters from the cursor position
440 Default key: Delete
442 delete_line LINE_ID, [ LINES = 1 ]
444 Removes LINES of text at LINE_ID.
445 delete_current_chunk
447 Removes the chunk ( or line, if wordWrap is 0 ) at the cursor.
448 Default key: Ctrl+Y
450 delete_chunk CHUNK_ID, [ CHUNKS = 1 ]
452 Removes CHUNKS ( or lines, if wordWrap is 0 ) of text at CHUNK_ID
453 delete_marker INDEX
455 Removes marker INDEX in markers list.
456 delete_to_end
458 Removes text to the end of the chunk.
459 Default key: Ctrl+E
461 delete_text X, Y, TEXT_LENGTH
463 Removes TEXT_LENGTH characters at X,Y physical coordinates
464 draw_colorchunk CANVAS, LINE_ID, X, Y, COLOR
466 Paints the syntax-highlighted chunk taken from LINE_ID line index,
467 at X, Y. COLOR is used if the syntax highlighting information
468 contains "cl::Fore" as color reference.
469 end_block
471 Stops the block selection session.
472 find SEARCH_STRING, [ X = 0, Y = 0, REPLACE_LINE = '', OPTIONS ]
474 Tries to find ( and, if REPLACE_LINE is defined, to replace with it
475 ) SEARCH_STRING from (X,Y) visual coordinates. OPTIONS is an
476 integer that consists of the "fdo::" constants; the same constants
477 are used in Prima::Dialog::FindDialog, which provides graphic
478 interface to the find and replace facilities of Prima::Edit.
479 Returns X1, Y, X2, NEW_STRING where X1.Y-X2.Y are visual
481 coordinates of the found string, and NEW_STRING is the replaced
482 version (if any)
483 fdo::MatchCase
485 If set, the search is case-sensitive.
486 fdo::WordsOnly
488 If set, SEARCH_STRING must constitute the whole word.
489 fdo::RegularExpression
491 If set, SEARCH_STRING is a regular expression.
492 fdo::BackwardSearch
494 If set, the search direction is backwards.
495 fdo::ReplacePrompt
497 Not used in the class, however, used in
498 Prima::Dialog::FindDialog.
499 get_chunk CHUNK_ID
501 Returns chunk of text, located at CHUNK_ID. Returns empty string
502 if chunk is nonexistent.
503 get_chunk_cluster_length CHUNK_ID
505 Return length of a chunk in clusters
506 get_chunk_dimension CHUNK_ID
508 Finds the line number the CHUNK_ID belongs to, return first chunk
509 of that line and how many chunks the line occupies.
510 get_chunk_width TEXT, FROM, LENGTH, [ RETURN_TEXT_PTR ]
512 Returns the width in pixels of "substr( TEXT, FROM, LENGTH)". If
513 FROM is larger than length of TEXT, TEXT is padded with space
514 characters. Tab character in TEXT replaced to tabIndent times space
515 character. If RETURN_TEXT_PTR pointer is specified, the converted
516 TEXT is stored there.
517 get_line INDEX
519 Returns line of text, located at INDEX. Returns empty string if
520 line is nonexistent.
521 get_line_cluster_length LINE_ID
523 Return length of a line in clusters
524 get_line_dimension INDEX
526 Returns two integers, representing the line at INDEX in wordWrap
527 mode: the first value is the corresponding chunk index, the second
528 is how many chunks represent the line.
529 See also: physical_to_logical.
531 get_selected_text
533 Return the text currently selected.
534 has_selection
536 Returns boolean value, indicating if the selection block is active.
537 insert_empty_line LINE_ID, [ REPEAT = 1 ]
539 Inserts REPEAT empty lines at LINE_ID.
540 insert_line LINE_ID, @TEXT
542 Inserts @TEXT strings at LINE_ID
543 insert_text TEXT, [ HIGHLIGHT = 0 ]
545 Inserts TEXT at the cursor position. If HIGHLIGHT is set to 1, the
546 selection block is cancelled and the newly inserted text is
547 selected.
548 lock_change BOOLEAN
550 Increments ( 1 ) or decrements ( 0 ) lock count. Used to defer
551 change notification in multi-change calls. When internal lock count
552 hits zero, "Change" notification is called.
553 physical_to_logical X, Y
555 Maps visual X,Y coordinates to the logical and returns the integer
556 pair. Returns same values when wordWrap is 0.
557 logical_to_visual X, Y
559 Maps logical X,Y coordinates to the visual and returns the integer
560 pair.
561 Returns same values when wordWrap is 0.
563 visual_to_physical X, Y
565 Maps visual X,Y coordinates to the physical text offset relative to
566 the Y line
567 Returns same X when the line does not contain any right-to-left
569 characters or complex glyphs.
570 physical_to_visual X, Y
572 Maps test offset X from line Y to the visual X coordinate.
573 Returns same X when the line does not contain any right-to-left
575 characters or complex glyphs.
576 mark_horizontal
578 Starts block marking session with "bt::Horizontal" block type.
579 Default key: Alt+L
581 mark_vertical
583 Starts block marking session with "bt::Vertical" block type.
584 Default key: Alt+B
586 overtype_block
588 Copies the selected text and overwrites the text next to the cursor
589 position, according to the blockType value.
590 Default key: Alt+O
592 paste
594 Copies text from the clipboard and inserts it in the cursor
595 position.
596 Default key: Shift+Insert
598 realize_panning
600 Performs deferred widget panning, activated by setting
601 "{delayPanning}" to 1. The deferred operations are those performed
602 by offset and topLine.
603 set_line LINE_ID, TEXT, [ OPERATION, FROM, LENGTH ]
605 Changes line at LINE_ID to new TEXT. Hint scalars OPERATION, FROM
606 and LENGTH used to maintain selection and marking data. OPERATION
607 is an arbitrary string, the ones that are recognized are
608 'overtype', 'add', and 'delete'. FROM and LENGTH define the range
609 of the change; FROM is a cluster offset and LENGTH is a length of
610 changed text.
611 split_line
613 Splits a line in two at the cursor position.
614 Default key: Enter ( or Ctrl+Enter if wantReturns is 0 )
616 select_all
618 Selects all text
619 start_block [ BLOCK_TYPE ]
621 Begins the block selection session. The block type if BLOCK_TYPE,
622 if it is specified, or blockType property value otherwise.
623 update_block
625 Adjusts the selection inside the block session, extending of
626 shrinking it to the current cursor position.
627 word_left [ REPEAT = 1 ]
629 Moves cursor REPEAT words to the left.
630 word_right [ REPEAT = 1 ]
632 Moves cursor REPEAT words to the right.
633
635 Dmitry Karasik, <dmitry@karasik.eu.org>.
636
638 Prima, Prima::Widget, Prima::Dialog::FindDialog, Prima::IntUtils,
639 examples/editor.pl
640perl v5.36.0 2022-07-22 Prima::Edit(3)