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_width TEXT, FROM, LENGTH, [ RETURN_TEXT_PTR ]
505 Returns the width in pixels of "substr( TEXT, FROM, LENGTH)". If
506 FROM is larger than length of TEXT, TEXT is padded with space
507 characters. Tab character in TEXT replaced to tabIndent times space
508 character. If RETURN_TEXT_PTR pointer is specified, the converted
509 TEXT is stored there.
510 get_line INDEX
512 Returns line of text, located at INDEX. Returns empty string if
513 line is nonexistent.
514 get_line_dimension INDEX
516 Returns two integers, representing the line at INDEX in wordWrap
517 mode: the first value is the corresponding chunk index, the second
518 is how many chunks represent the line.
519 See also: physical_to_logical.
521 get_selected_text
523 Return the text currently selected.
524 has_selection
526 Returns boolean value, indicating if the selection block is active.
527 insert_empty_line LINE_ID, [ REPEAT = 1 ]
529 Inserts REPEAT empty lines at LINE_ID.
530 insert_line LINE_ID, @TEXT
532 Inserts @TEXT strings at LINE_ID
533 insert_text TEXT, [ HIGHLIGHT = 0 ]
535 Inserts TEXT at the cursor position. If HIGHLIGHT is set to 1, the
536 selection block is cancelled and the newly inserted text is
537 selected.
538 lock_change BOOLEAN
540 Increments ( 1 ) or decrements ( 0 ) lock count. Used to defer
541 change notification in multi-change calls. When internal lock count
542 hits zero, "Change" notification is called.
543 physical_to_logical X, Y
545 Maps visual X,Y coordinates to the logical and returns the integer
546 pair. Returns same values when wordWrap is 0.
547 logical_to_visual X, Y
549 Maps logical X,Y coordinates to the visual and returns the integer
550 pair.
551 Returns same values when wordWrap is 0.
553 visual_to_physical X, Y
555 Maps visual X,Y coordinates to the physical text offset relative to
556 the Y line
557 Returns same X when the line does not contain any right-to-left
559 characters or complex glyphs.
560 physical_to_visual X, Y
562 Maps test offset X from line Y to the visual X coordinate.
563 Returns same X when the line does not contain any right-to-left
565 characters or complex glyphs.
566 mark_horizontal
568 Starts block marking session with "bt::Horizontal" block type.
569 Default key: Alt+L
571 mark_vertical
573 Starts block marking session with "bt::Vertical" block type.
574 Default key: Alt+B
576 overtype_block
578 Copies the selected text and overwrites the text next to the cursor
579 position, according to the blockType value.
580 Default key: Alt+O
582 paste
584 Copies text from the clipboard and inserts it in the cursor
585 position.
586 Default key: Shift+Insert
588 realize_panning
590 Performs deferred widget panning, activated by setting
591 "{delayPanning}" to 1. The deferred operations are those performed
592 by offset and topLine.
593 set_line LINE_ID, TEXT, [ OPERATION, FROM, LENGTH ]
595 Changes line at LINE_ID to new TEXT. Hint scalars OPERATION, FROM
596 and LENGTH used to maintain selection and marking data. OPERATION
597 is an arbitrary string, the ones that are recognized are
598 'overtype', 'add', and 'delete'. FROM and LENGTH define the range
599 of the change; FROM is a cluster offset and LENGTH is a length of
600 changed text.
601 split_line
603 Splits a line in two at the cursor position.
604 Default key: Enter ( or Ctrl+Enter if wantReturns is 0 )
606 select_all
608 Selects all text
609 start_block [ BLOCK_TYPE ]
611 Begins the block selection session. The block type if BLOCK_TYPE,
612 if it is specified, or blockType property value otherwise.
613 update_block
615 Adjusts the selection inside the block session, extending of
616 shrinking it to the current cursor position.
617 word_left [ REPEAT = 1 ]
619 Moves cursor REPEAT words to the left.
620 word_right [ REPEAT = 1 ]
622 Moves cursor REPEAT words to the right.
623
625 Dmitry Karasik, <dmitry@karasik.eu.org>.
626
628 Prima, Prima::Widget, Prima::Dialog::FindDialog, Prima::IntUtils,
629 examples/editor.pl
630perl v5.32.1 2021-01-27 Prima::Edit(3)