1Prima::Edit(3)        User Contributed Perl Documentation       Prima::Edit(3)
2
3
4

NAME

6       Prima::Edit - standard text editing widget
7

SYNOPSIS

9               use Prima qw(Edit Application);
10               my $e = Prima::Edit->new(
11                       text         => 'Hello $world',
12                       syntaxHilite => 1,
13               );
14               run Prima;
15

DESCRIPTION

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
21       The module declares "bt::" package, that contains integer constants for
22       selection block type, used by blockType property.
23

USAGE

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
28       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
35   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
42       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
49       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
54           Example: coord("z") is (0,10);
55
56       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
61           Example: coord("z") is (0,9);
62
63       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
69           Example: coord("z") is (1,3);
70

API

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
81   Properties
82       autoIndent BOOLEAN
83           Selects if the auto indenting feature is on.
84
85           Default value: 1
86
87       blockType INTEGER
88           Defines type of selection block. Can be one of the following
89           constants:
90
91           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
96               Default keys: Shift + arrow keys
97
98               See also: cursor_shift_key
99
100           bt::Vertical
101               Rectangular block, where all selected lines are of same offsets
102               and lengths.
103
104               Default key: Alt+B
105
106               See also: mark_vertical
107
108           bt::Horizontal
109               Rectangular block, where the selection occupies the whole line.
110
111               Default key: Alt+L
112
113               See also: mark_horizontal
114
115       cursor X, Y
116           Selects visual position of the cursor
117
118       cursorX X
119           Selects visual horizontal position of the cursor
120
121       cursorY Y
122           Selects visual vertical position of the cursor
123
124       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
129           See also: cursor_left, cursor_right, word_left, word_right.
130
131       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
137           Default toggle key: Insert
138
139       hiliteNumbers COLOR
140           Selects the color for number highlighting
141
142       hiliteQStrings COLOR
143           Selects the color for highlighting the single-quoted strings
144
145       hiliteQQStrings COLOR
146           Selects the color for highlighting the double-quoted strings
147
148       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
153       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
158       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
163           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
178           For example, we have a string " ABC123abc ", and we want to match
179           123 followed by abc.  This won't work
180
181                   hiliteREs => [
182                           '(123)abc',cl::LightRed,
183                           '(abc)', cl::LightGreen
184                   ]
185
186           while this will:
187
188                   hiliteREs => [
189                           '(123)(?=abc)',cl::LightRed,
190                           '(abc)', cl::LightGreen
191                   ]
192
193           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
199                   hiliteREs =>  [
200                           '(ABC)',cl::LightBlue,
201                           '(?<=[ABC]+)(123)',cl::LightRed,
202                   ]
203
204           while this will:
205
206                   hiliteREs =>  [
207                           '(ABC)',cl::LightBlue,
208                           '(?<=[ABC]{3})(123)',cl::LightRed,
209                   ]
210
211       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
217       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
222           See also: add_marker, delete_marker
223
224       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
229       offset INTEGER
230           Horizontal offset of text lines in pixels.
231
232       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
237           Default value: 0
238
239       readOnly BOOLEAN
240           If 1, no user input is accepted. Manipulations with text are
241           allowed though.
242
243       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
248           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
251       selStart X, Y
252           Manages the selection start. See selection, X1 and Y1.
253
254       selEnd X, Y
255           Manages the selection end. See selection, X2 and Y2.
256
257       syntaxHilite BOOLEAN
258           Governs the syntax highlighting. Is not implemented for word
259           wrapping mode.
260
261       tabIndent INTEGER
262           Maps tab ( \t ) key to "tabIndent" amount of space characters.
263
264       text TEXT
265           Provides access to all the text data. The lines are separated by
266           the new line ( \n ) character.
267
268           See also: textRef.
269
270       textDirection BOOLEAN
271           If set, indicates RTL text input.
272
273       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
281       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
286           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
290           See also: text.
291
292       topLine INTEGER
293           Selects the first line of the text drawn.
294
295       undoLimit INTEGER
296           Sets limit on number of stored atomic undo operations. If 0, undo
297           is disabled.
298
299           Default value: 1000
300
301       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
307           Default value: 0
308
309       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
315           Default value: 1
316
317       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
322           See also: word_left, word_right
323
324       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
331   Methods
332       add_marker X, Y
333           Adds visual coordinated X,Y to markers property.
334
335       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
340           Default key: Backspace
341
342       cancel_block
343           Removes the selection block
344
345           Default key: Alt+U
346
347       change_locked
348           Returns 1 if the logical locking is on, 0 if it is off.
349
350           See also lock_change.
351
352       copy
353           Copies the selected text, if any, to the clipboard.
354
355           Default key: Ctrl+Insert
356
357       copy_block
358           Copies the selected text and inserts it into the cursor position,
359           according to the blockType value.
360
361           Default key: Alt+C
362
363       cursor_cend
364           Moves cursor to the bottom line
365
366           Default key: Ctrl+End
367
368       cursor_chome
369           Moves cursor to the top line
370
371           Default key: Ctrl+Home
372
373       cursor_cpgdn
374           Default key: Ctrl+PageDown
375
376           Moves cursor to the end of text.
377
378       cursor_cpgup
379           Moves cursor to the beginning of text.
380
381           Default key: Ctrl+PageUp
382
383       cursor_down [ REPEAT = 1 ]
384           Moves cursor REPEAT times down
385
386           Default key: Down
387
388       cursor_end
389           Moves cursor to the end of the line
390
391           Default key: End
392
393       cursor_home
394           Moves cursor to the beginning of the line
395
396           Default key: Home
397
398       cursor_left [ REPEAT = 1 ]
399           Moves cursor REPEAT times left
400
401           Default key: Left
402
403       cursor_right [ REPEAT = 1 ]
404           Moves cursor REPEAT times right
405
406           Default key: Right
407
408       cursor_up [ REPEAT = 1 ]
409           Moves cursor REPEAT times up
410
411           Default key: Up
412
413       cursor_pgdn [ REPEAT = 1 ]
414           Moves cursor REPEAT pages down
415
416           Default key: PageDown
417
418       cursor_pgup [ REPEAT = 1 ]
419           Moves cursor REPEAT pages up
420
421           Default key: PageUp
422
423       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
429       cut Cuts the selected text into the clipboard.
430
431           Default key: Shift+Delete
432
433       delete_block
434           Removes the selected text.
435
436           Default key: Alt+D
437
438       delete_char [ REPEAT = 1 ]
439           Delete REPEAT characters from the cursor position
440
441           Default key: Delete
442
443       delete_line LINE_ID, [ LINES = 1 ]
444           Removes LINES of text at LINE_ID.
445
446       delete_current_chunk
447           Removes the chunk ( or line, if wordWrap is 0 ) at the cursor.
448
449           Default key: Ctrl+Y
450
451       delete_chunk CHUNK_ID, [ CHUNKS = 1 ]
452           Removes CHUNKS ( or lines, if wordWrap is 0 ) of text at CHUNK_ID
453
454       delete_marker INDEX
455           Removes marker INDEX in markers list.
456
457       delete_to_end
458           Removes text to the end of the chunk.
459
460           Default key: Ctrl+E
461
462       delete_text X, Y, TEXT_LENGTH
463           Removes TEXT_LENGTH characters at X,Y physical coordinates
464
465       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
470       end_block
471           Stops the block selection session.
472
473       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
480           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
484           fdo::MatchCase
485               If set, the search is case-sensitive.
486
487           fdo::WordsOnly
488               If set, SEARCH_STRING must constitute the whole word.
489
490           fdo::RegularExpression
491               If set, SEARCH_STRING is a regular expression.
492
493           fdo::BackwardSearch
494               If set, the search direction is backwards.
495
496           fdo::ReplacePrompt
497               Not used in the class, however, used in
498               Prima::Dialog::FindDialog.
499
500       get_chunk CHUNK_ID
501           Returns chunk of text, located at CHUNK_ID.  Returns empty string
502           if chunk is nonexistent.
503
504       get_chunk_cluster_length CHUNK_ID
505           Return length of a chunk in clusters
506
507       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
511       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
518       get_line INDEX
519           Returns line of text, located at INDEX.  Returns empty string if
520           line is nonexistent.
521
522       get_line_cluster_length LINE_ID
523           Return length of a line in clusters
524
525       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
530           See also: physical_to_logical.
531
532       get_selected_text
533           Return the text currently selected.
534
535       has_selection
536           Returns boolean value, indicating if the selection block is active.
537
538       insert_empty_line LINE_ID, [ REPEAT = 1 ]
539           Inserts REPEAT empty lines at LINE_ID.
540
541       insert_line LINE_ID, @TEXT
542           Inserts @TEXT strings at LINE_ID
543
544       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
549       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
554       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
558       logical_to_visual X, Y
559           Maps logical X,Y coordinates to the visual and returns the integer
560           pair.
561
562           Returns same values when wordWrap is 0.
563
564       visual_to_physical X, Y
565           Maps visual X,Y coordinates to the physical text offset relative to
566           the Y line
567
568           Returns same X when the line does not contain any right-to-left
569           characters or complex glyphs.
570
571       physical_to_visual X, Y
572           Maps test offset X from line Y to the visual X coordinate.
573
574           Returns same X when the line does not contain any right-to-left
575           characters or complex glyphs.
576
577       mark_horizontal
578           Starts block marking session with "bt::Horizontal" block type.
579
580           Default key: Alt+L
581
582       mark_vertical
583           Starts block marking session with "bt::Vertical" block type.
584
585           Default key: Alt+B
586
587       overtype_block
588           Copies the selected text and overwrites the text next to the cursor
589           position, according to the blockType value.
590
591           Default key: Alt+O
592
593       paste
594           Copies text from the clipboard and inserts it in the cursor
595           position.
596
597           Default key: Shift+Insert
598
599       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
604       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
612       split_line
613           Splits a line in two at the cursor position.
614
615           Default key: Enter ( or Ctrl+Enter if wantReturns is 0 )
616
617       select_all
618           Selects all text
619
620       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
624       update_block
625           Adjusts the selection inside the block session, extending of
626           shrinking it to the current cursor position.
627
628       word_left [ REPEAT = 1 ]
629           Moves cursor REPEAT words to the left.
630
631       word_right [ REPEAT = 1 ]
632           Moves cursor REPEAT words to the right.
633

AUTHOR

635       Dmitry Karasik, <dmitry@karasik.eu.org>.
636

SEE ALSO

638       Prima, Prima::Widget, Prima::Dialog::FindDialog, Prima::IntUtils,
639       examples/editor.pl
640
641
642
643perl v5.36.0                      2022-07-22                    Prima::Edit(3)
Impressum