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::Edit;
10               my $e = Prima::Edit-> create(
11                       text         => 'Hello $world',
12                       syntaxHilite => 1,
13               );
14               $e-> selection( 1, 1, 1, 2);
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 class addresses the text space by (X,Y)-coordinates, where X is
26       visual character offset and Y is line number. The addressing can be
27       'visual' and 'logical', - in logical case Y is number of line of text.
28       The difference can be observed if wordWrap property is set to 1, when a
29       single text string can be shown as several sub-strings, called chunks.
30
31       The text is stored line-wise in "{lines}" array; to access it use
32       get_line method.  To access the text chunk-wise, use get_chunk method.
33
34       All keyboard events, except the character input and tab key handling,
35       are processed by the accelerator table ( see Prima::Menu ). The default
36       "accelItems" table defines names, keyboard combinations, and the
37       corresponding actions to the class functions. The class does not
38       provide functionality to change these mappings. To do so, consult
39       "Prima::AccelTable" in Prima::Menu.
40

API

42   Events
43       ParseSyntax TEXT, RESULT_ARRAY_REF
44           Called when syntax highlighting is requires - TEXT is a string to
45           be parsed, and the parsing results to be stored in
46           RESULT_ARRAY_REF, which is a reference to an array of integer
47           pairs, each representing a single-colored text chunk.  The first
48           integer in the pairs is the length of a chunk, the second - color
49           value ( "cl::XXX" constants ).
50
51   Properties
52       autoIndent BOOLEAN
53           Selects if the auto indenting feature is on.
54
55           Default value: 1
56
57       blockType INTEGER
58           Defines type of selection block. Can be one of the following
59           constants:
60
61           bt::CUA
62               Normal block, where the first and the last line of the
63               selection can be partial, and the lines between occupy the
64               whole line. CUA stands for 'common user access'.
65
66               Default keys: Shift + arrow keys
67
68               See also: cursor_shift_key
69
70           bt::Vertical
71               Rectangular block, where all selected lines are of same offsets
72               and lengths.
73
74               Default key: Alt+B
75
76               See also: mark_vertical
77
78           bt::Horizontal
79               Rectangular block, where the selection occupies the whole line.
80
81               Default key: Alt+L
82
83               See also: mark_horizontal
84
85       cursor X, Y
86           Selects visual position of the cursor
87
88       cursorX X
89           Selects visual horizontal position of the cursor
90
91       cursorY Y
92           Selects visual vertical position of the cursor
93
94       cursorWrap BOOLEAN
95           Selects cursor behavior when moved horizontally outside the line.
96           If 0, the cursor is not moved. If 1, the cursor moved to the
97           adjacent line.
98
99           See also: cursor_left, cursor_right, word_left, word_right.
100
101       insertMode BOOLEAN
102           Governs the typing mode - if 1, the typed text is inserted, if 0,
103           the text overwrites the old text. When "insertMode" is 0, the
104           cursor shape is thick and covers the whole character; when 1, it is
105           of default width.
106
107           Default toggle key: Insert
108
109       hiliteNumbers COLOR
110           Selects the color for number highlighting
111
112       hiliteQStrings COLOR
113           Selects the color for highlighting the single-quoted strings
114
115       hiliteQQStrings COLOR
116           Selects the color for highlighting the double-quoted strings
117
118       hiliteIDs ARRAY
119           Array of scalar pairs, that define words to be highlighted.  The
120           first item in the pair is an array of words; the second item is a
121           color value.
122
123       hiliteChars ARRAY
124           Array of scalar pairs, that define characters to be highlighted.
125           The first item in the pair is a string of characters; the second
126           item is a color value.
127
128       hiliteREs ARRAY
129           Array of scalar pairs, that define character patterns to be
130           highlighted.  The first item in the pair is a perl regular
131           expression; the second item is a color value.
132
133       mark MARK [ BLOCK_TYPE ]
134           Selects block marking state. If MARK is 1, starts the block
135           marking, if 0 - stops the block marking. When MARK is 1, BLOCK_TYPE
136           can be used to set the selection type ( "bt::XXX" constants ). If
137           BLOCK_TYPE is unset the value of blockType is used.
138
139       markers ARRAY
140           Array of arrays with integer pairs, X and Y, where each represents
141           a visual coordinates in text. Used as anchor storage for fast
142           navigation.
143
144           See also: add_marker, delete_marker
145
146       modified BOOLEAN
147           A boolean flag that shows if the text was modified. Can be used
148           externally, to check if the text is to be saved to a file, for
149           example.
150
151       offset INTEGER
152           Horizontal offset of text lines in pixels.
153
154       persistentBlock BOOLEAN
155           Selects whether the selection is cancelled as soon as the cursor is
156           moved ( 0 ) or it persists until the selection is explicitly
157           changed ( 1 ).
158
159           Default value: 0
160
161       readOnly BOOLEAN
162           If 1, no user input is accepted. Manipulation with text are allowed
163           though.
164
165       selection X1, Y1, X2, Y2
166           Accepts two pair of coordinates, ( X1,Y1) the beginning and (
167           X2,Y2) the end of new selection, and sets the block according to
168           blockType property.
169
170           The selection is null if X1 equals to X2 and Y1 equals to Y2.
171           has_selection method returns 1 if the selection is non-null.
172
173       selStart X, Y
174           Manages the selection start. See selection, X1 and Y1.
175
176       selEnd X, Y
177           Manages the selection end. See selection, X2 and Y2.
178
179       syntaxHilite BOOLEAN
180           Governs the syntax highlighting. Is not implemented for word
181           wrapping mode.
182
183       tabIndent INTEGER
184           Maps tab ( \t ) key to "tabIndent" amount of space characters.
185
186       text TEXT
187           Provides access to all the text data. The lines are separated by
188           the new line ( \n ) character.
189
190           See also: textRef.
191
192       textRef TEXT_PTR
193           Provides access to all the text data. The lines are separated by
194           the new line ( \n ) character. TEXT_PTR is a pointer to text
195           string.
196
197           The property is more efficient than text with the large text,
198           because the copying of the text scalar to the stack stage is
199           eliminated.
200
201           See also: text.
202
203       topLine INTEGER
204           Selects the first line of the text drawn.
205
206       undoLimit INTEGER
207           Sets limit on number of stored atomic undo operations. If 0, undo
208           is disabled.
209
210           Default value: 1000
211
212       wantTabs BOOLEAN
213           Selects the way the tab ( \t ) character is recognized in the user
214           input.  If 1, it is recognized by the Tab key; however, this
215           disallows the toolkit widget tab-driven navigation. If 0, the tab
216           character can be entered by pressing Ctrl+Tab key combination.
217
218           Default value: 0
219
220       wantReturns BOOLEAN
221           Selects the way the new line ( \n ) character is recognized in the
222           user input.  If 1, it is recognized by the Enter key; however, this
223           disallows the toolkit default button activation. If 0, the new line
224           character can be entered by pressing Ctrl+Enter key combination.
225
226           Default value: 1
227
228       wordDelimiters STRING
229           Contains string of character that are used for locating a word
230           break.  Default STRING value consists of punctuation marks, space
231           and tab characters, and "\xff" character.
232
233           See also: word_left, word_right
234
235       wordWrap BOOLEAN
236           Selects whether the long lines are wrapped, or can be positioned
237           outside the horizontal widget inferior borders. If 1, syntaxHilite
238           is not used. A line of text can be represented by more than one
239           line of screen text ( chunk ) . To access the text chunk-wise, use
240           get_chunk method.
241
242   Methods
243       add_marker X, Y
244           Adds visual coordinated X,Y to markers property.
245
246       back_char [ REPEAT = 1 ]
247           Removes REPEAT times a character left to the cursor. If the cursor
248           is on 0 x-position, removes the new-line character and concatenates
249           the lines.
250
251           Default key: Backspace
252
253       cancel_block
254           Removes the selection block
255
256           Default key: Alt+U
257
258       change_locked
259           Returns 1 if the logical locking is on, 0 if it is off.
260
261           See also lock_change.
262
263       copy
264           Copies the selected text, if any, to the clipboard.
265
266           Default key: Ctrl+Insert
267
268       copy_block
269           Copies the selected text and inserts it into the cursor position,
270           according to the blockType value.
271
272           Default key: Alt+C
273
274       cursor_cend
275           Moves cursor to the bottom line
276
277           Default key: Ctrl+End
278
279       cursor_chome
280           Moves cursor to the top line
281
282           Default key: Ctrl+Home
283
284       cursor_cpgdn
285           Default key: Ctrl+PageDown
286
287           Moves cursor to the end of text.
288
289       cursor_cpgup
290           Moves cursor to the beginning of text.
291
292           Default key: Ctrl+PageUp
293
294       cursor_down [ REPEAT = 1 ]
295           Moves cursor REPEAT times down
296
297           Default key: Down
298
299       cursor_end
300           Moves cursor to the end of the line
301
302           Default key: End
303
304       cursor_home
305           Moves cursor to the beginning of the line
306
307           Default key: Home
308
309       cursor_left [ REPEAT = 1 ]
310           Moves cursor REPEAT times left
311
312           Default key: Left
313
314       cursor_right [ REPEAT = 1 ]
315           Moves cursor REPEAT times right
316
317           Default key: Right
318
319       cursor_up [ REPEAT = 1 ]
320           Moves cursor REPEAT times up
321
322           Default key: Up
323
324       cursor_pgdn [ REPEAT = 1 ]
325           Moves cursor REPEAT pages down
326
327           Default key: PageDown
328
329       cursor_pgup [ REPEAT = 1 ]
330           Moves cursor REPEAT pages up
331
332           Default key: PageUp
333
334       cursor_shift_key [ ACCEL_TABLE_ITEM ]
335           Performs action of the cursor movement, bound to ACCEL_TABLE_ITEM
336           action ( defined in "accelTable" or "accelItems" property ), and
337           extends the selection block along the cursor movement. Not called
338           directly.
339
340       cut Cuts the selected text into the clipboard.
341
342           Default key: Shift+Delete
343
344       delete_block
345           Removes the selected text.
346
347           Default key: Alt+D
348
349       delete_char [ REPEAT = 1 ]
350           Delete REPEAT characters from the cursor position
351
352           Default key: Delete
353
354       delete_line LINE_ID, [ LINES = 1 ]
355           Removes LINES of text at LINE_ID.
356
357       delete_current_chunk
358           Removes the chunk ( or line, if wordWrap is 0 ) at the cursor.
359
360           Default key: Ctrl+Y
361
362       delete_chunk CHUNK_ID, [ CHUNKS = 1 ]
363           Removes CHUNKS ( or lines, if wordWrap is 0 ) of text at CHUNK_ID
364
365       delete_marker INDEX
366           Removes marker INDEX in markers list.
367
368       delete_to_end
369           Removes text to the end of the chunk.
370
371           Default key: Ctrl+E
372
373       delete_text X, Y, TEXT_LENGTH
374           Removes TEXT_LENGTH characters at X,Y visual coordinates
375
376       draw_colorchunk CANVAS, TEXT, LINE_ID, X, Y, COLOR
377           Paints the syntax-highlighted chunk of TEXT, taken from LINE_ID
378           line index, at X, Y. COLOR is used if the syntax highlighting
379           information contains "cl::Fore" as color reference.
380
381       end_block
382           Stops the block selection session.
383
384       find SEARCH_STRING, [ X = 0, Y = 0, REPLACE_LINE = '', OPTIONS ]
385           Tries to find ( and, if REPLACE_LINE is defined, to replace with it
386           ) SEARCH_STRING from (X,Y) visual coordinates. OPTIONS is an
387           integer that consists of the "fdo::" constants; the same constants
388           are used in Prima::EditDialog, which provides graphic interface to
389           the find and replace facilities of Prima::Edit.
390
391           Returns X1, Y, X2, NEW_STRING where X1.Y-X2.Y are visual
392           coordinates of the found string, and NEW_STRING is the replaced
393           version (if any)
394
395           fdo::MatchCase
396               If set, the search is case-sensitive.
397
398           fdo::WordsOnly
399               If set, SEARCH_STRING must constitute the whole word.
400
401           fdo::RegularExpression
402               If set, SEARCH_STRING is a regular expression.
403
404           fdo::BackwardSearch
405               If set, the search direction is backwards.
406
407           fdo::ReplacePrompt
408               Not used in the class, however, used in Prima::EditDialog.
409
410       get_chunk CHUNK_ID
411           Returns chunk of text, located at CHUNK_ID.  Returns empty string
412           if chunk is nonexistent.
413
414       get_chunk_end CHUNK_ID
415           Returns the index of chunk at CHUNK_ID, corresponding to the last
416           chunk of same line.
417
418       get_chunk_org CHUNK_ID
419           Returns the index of chunk at CHUNK_ID, corresponding to the first
420           chunk of same line.
421
422       get_chunk_width TEXT, FROM, LENGTH, [ RETURN_TEXT_PTR ]
423           Returns the width in pixels of "substr( TEXT, FROM, LENGTH)".  If
424           FROM is larger than length of TEXT, TEXT is padded with space
425           characters. Tab character in TEXT replaced to tabIndent times space
426           character. If RETURN_TEXT_PTR pointer is specified, the converted
427           TEXT is stored there.
428
429       get_line INDEX
430           Returns line of text, located at INDEX.  Returns empty string if
431           line is nonexistent.
432
433       get_line_dimension INDEX
434           Returns two integers, representing the line at INDEX in wordWrap
435           mode: the first value is the corresponding chunk index, the second
436           is how many chunks represent the line.
437
438           See also: physical_to_logical.
439
440       get_line_ext CHUNK_ID
441           Returns the line, corresponding to the chunk index.
442
443       get_selected_text
444           Return the text currently selected.
445
446       has_selection
447           Returns boolean value, indicating if the selection block is active.
448
449       insert_empty_line LINE_ID, [ REPEAT = 1 ]
450           Inserts REPEAT empty lines at LINE_ID.
451
452       insert_line LINE_ID, @TEXT
453           Inserts @TEXT strings at LINE_ID
454
455       insert_text TEXT, [ HIGHLIGHT = 0 ]
456           Inserts TEXT at the cursor position. If HIGHLIGHT is set to 1, the
457           selection block is cancelled and the newly inserted text is
458           selected.
459
460       lock_change BOOLEAN
461           Increments ( 1 ) or decrements ( 0 ) lock count. Used to defer
462           change notification in multi-change calls. When internal lock count
463           hits zero, "Change" notification is called.
464
465       physical_to_logical X, Y
466           Maps visual X,Y coordinates to the logical and returns the integer
467           pair.  Returns same values when wordWrap is 0.
468
469       logical_to_visual X, Y
470           Maps logical X,Y coordinates to the visual and returns the integer
471           pair.
472
473           Returns same values when wordWrap is 0.
474
475       visual_to_physical X, Y
476           Maps visual X,Y coordinates to the physical text offset relative to
477           the Y line
478
479           Returns same X when the line does not contain any right-to-left
480           characters or bi-directional input/output is disabled.
481
482       physical_to_visual X, Y
483           Maps test offset X from line Y to the visual X coordinate.
484
485           Returns same X when the line does not contain any right-to-left
486           characters or bi-directional input/output is disabled.
487
488       mark_horizontal
489           Starts block marking session with "bt::Horizontal" block type.
490
491           Default key: Alt+L
492
493       mark_vertical
494           Starts block marking session with "bt::Vertical" block type.
495
496           Default key: Alt+B
497
498       overtype_block
499           Copies the selected text and overwrites the text next to the cursor
500           position, according to the blockType value.
501
502           Default key: Alt+O
503
504       paste
505           Copies text from the clipboard and inserts it in the cursor
506           position.
507
508           Default key: Shift+Insert
509
510       realize_panning
511           Performs deferred widget panning, activated by setting
512           "{delayPanning}" to 1.  The deferred operations are those performed
513           by offset and topLine.
514
515       set_line LINE_ID, TEXT, [ OPERATION, FROM, LENGTH ]
516           Changes line at LINE_ID to new TEXT. Hint scalars OPERATION, FROM
517           and LENGTH used to maintain selection and marking data. OPERATION
518           is an arbitrary string, the ones that are recognized are
519           'overtype', 'add', and 'delete'.  FROM and LENGTH define the range
520           of the change; FROM is a character offset and LENGTH is a length of
521           changed text.
522
523       split_line
524           Splits a line in two at the cursor position.
525
526           Default key: Enter ( or Ctrl+Enter if wantReturns is 0 )
527
528       select_all
529           Selects all text
530
531       start_block [ BLOCK_TYPE ]
532           Begins the block selection session. The block type if BLOCK_TYPE,
533           if it is specified, or blockType property value otherwise.
534
535       update_block
536           Adjusts the selection inside the block session, extending of
537           shrinking it to the current cursor position.
538
539       word_left [ REPEAT = 1 ]
540           Moves cursor REPEAT words to the left.
541
542       word_right [ REPEAT = 1 ]
543           Moves cursor REPEAT words to the right.
544

AUTHOR

546       Dmitry Karasik, <dmitry@karasik.eu.org>.
547

SEE ALSO

549       Prima, Prima::Widget, Prima::EditDialog, Prima::IntUtils,
550       examples/editor.pl
551
552
553
554perl v5.28.0                      2017-02-28                    Prima::Edit(3)
Impressum