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 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 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 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
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 Properties
52 autoIndent BOOLEAN
53 Selects if the auto indenting feature is on.
54 Default value: 1
56 blockType INTEGER
58 Defines type of selection block. Can be one of the following
59 constants:
60 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 Default keys: Shift + arrow keys
67 See also: cursor_shift_key
69 bt::Vertical
71 Rectangular block, where all selected lines are of same offsets
72 and lengths.
73 Default key: Alt+B
75 See also: mark_vertical
77 bt::Horizontal
79 Rectangular block, where the selection occupies the whole line.
80 Default key: Alt+L
82 See also: mark_horizontal
84 cursor X, Y
86 Selects visual position of the cursor
87 cursorX X
89 Selects visual horizontal position of the cursor
90 cursorY Y
92 Selects visual vertical position of the cursor
93 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 See also: cursor_left, cursor_right, word_left, word_right.
100 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 Default toggle key: Insert
108 hiliteNumbers COLOR
110 Selects the color for number highlighting
111 hiliteQStrings COLOR
113 Selects the color for highlighting the single-quoted strings
114 hiliteQQStrings COLOR
116 Selects the color for highlighting the double-quoted strings
117 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 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 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 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 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 See also: add_marker, delete_marker
145 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 offset INTEGER
152 Horizontal offset of text lines in pixels.
153 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 Default value: 0
160 readOnly BOOLEAN
162 If 1, no user input is accepted. Manipulation with text are allowed
163 though.
164 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 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 selStart X, Y
174 Manages the selection start. See selection, X1 and Y1.
175 selEnd X, Y
177 Manages the selection end. See selection, X2 and Y2.
178 syntaxHilite BOOLEAN
180 Governs the syntax highlighting. Is not implemented for word
181 wrapping mode.
182 tabIndent INTEGER
184 Maps tab ( \t ) key to "tabIndent" amount of space characters.
185 text TEXT
187 Provides access to all the text data. The lines are separated by
188 the new line ( \n ) character.
189 See also: textRef.
191 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 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 See also: text.
202 topLine INTEGER
204 Selects the first line of the text drawn.
205 undoLimit INTEGER
207 Sets limit on number of stored atomic undo operations. If 0, undo
208 is disabled.
209 Default value: 1000
211 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 Default value: 0
219 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 Default value: 1
227 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 See also: word_left, word_right
234 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 Methods
243 add_marker X, Y
244 Adds visual coordinated X,Y to markers property.
245 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 Default key: Backspace
252 cancel_block
254 Removes the selection block
255 Default key: Alt+U
257 change_locked
259 Returns 1 if the logical locking is on, 0 if it is off.
260 See also lock_change.
262 copy
264 Copies the selected text, if any, to the clipboard.
265 Default key: Ctrl+Insert
267 copy_block
269 Copies the selected text and inserts it into the cursor position,
270 according to the blockType value.
271 Default key: Alt+C
273 cursor_cend
275 Moves cursor to the bottom line
276 Default key: Ctrl+End
278 cursor_chome
280 Moves cursor to the top line
281 Default key: Ctrl+Home
283 cursor_cpgdn
285 Default key: Ctrl+PageDown
286 Moves cursor to the end of text.
288 cursor_cpgup
290 Moves cursor to the beginning of text.
291 Default key: Ctrl+PageUp
293 cursor_down [ REPEAT = 1 ]
295 Moves cursor REPEAT times down
296 Default key: Down
298 cursor_end
300 Moves cursor to the end of the line
301 Default key: End
303 cursor_home
305 Moves cursor to the beginning of the line
306 Default key: Home
308 cursor_left [ REPEAT = 1 ]
310 Moves cursor REPEAT times left
311 Default key: Left
313 cursor_right [ REPEAT = 1 ]
315 Moves cursor REPEAT times right
316 Default key: Right
318 cursor_up [ REPEAT = 1 ]
320 Moves cursor REPEAT times up
321 Default key: Up
323 cursor_pgdn [ REPEAT = 1 ]
325 Moves cursor REPEAT pages down
326 Default key: PageDown
328 cursor_pgup [ REPEAT = 1 ]
330 Moves cursor REPEAT pages up
331 Default key: PageUp
333 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 cut Cuts the selected text into the clipboard.
341 Default key: Shift+Delete
343 delete_block
345 Removes the selected text.
346 Default key: Alt+D
348 delete_char [ REPEAT = 1 ]
350 Delete REPEAT characters from the cursor position
351 Default key: Delete
353 delete_line LINE_ID, [ LINES = 1 ]
355 Removes LINES of text at LINE_ID.
356 delete_current_chunk
358 Removes the chunk ( or line, if wordWrap is 0 ) at the cursor.
359 Default key: Ctrl+Y
361 delete_chunk CHUNK_ID, [ CHUNKS = 1 ]
363 Removes CHUNKS ( or lines, if wordWrap is 0 ) of text at CHUNK_ID
364 delete_marker INDEX
366 Removes marker INDEX in markers list.
367 delete_to_end
369 Removes text to the end of the chunk.
370 Default key: Ctrl+E
372 delete_text X, Y, TEXT_LENGTH
374 Removes TEXT_LENGTH characters at X,Y visual coordinates
375 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 end_block
382 Stops the block selection session.
383 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 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 fdo::MatchCase
396 If set, the search is case-sensitive.
397 fdo::WordsOnly
399 If set, SEARCH_STRING must constitute the whole word.
400 fdo::RegularExpression
402 If set, SEARCH_STRING is a regular expression.
403 fdo::BackwardSearch
405 If set, the search direction is backwards.
406 fdo::ReplacePrompt
408 Not used in the class, however, used in Prima::EditDialog.
409 get_chunk CHUNK_ID
411 Returns chunk of text, located at CHUNK_ID. Returns empty string
412 if chunk is nonexistent.
413 get_chunk_end CHUNK_ID
415 Returns the index of chunk at CHUNK_ID, corresponding to the last
416 chunk of same line.
417 get_chunk_org CHUNK_ID
419 Returns the index of chunk at CHUNK_ID, corresponding to the first
420 chunk of same line.
421 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 get_line INDEX
430 Returns line of text, located at INDEX. Returns empty string if
431 line is nonexistent.
432 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 See also: physical_to_logical.
439 get_line_ext CHUNK_ID
441 Returns the line, corresponding to the chunk index.
442 get_selected_text
444 Return the text currently selected.
445 has_selection
447 Returns boolean value, indicating if the selection block is active.
448 insert_empty_line LINE_ID, [ REPEAT = 1 ]
450 Inserts REPEAT empty lines at LINE_ID.
451 insert_line LINE_ID, @TEXT
453 Inserts @TEXT strings at LINE_ID
454 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 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 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 logical_to_visual X, Y
470 Maps logical X,Y coordinates to the visual and returns the integer
471 pair.
472 Returns same values when wordWrap is 0.
474 visual_to_physical X, Y
476 Maps visual X,Y coordinates to the physical text offset relative to
477 the Y line
478 Returns same X when the line does not contain any right-to-left
480 characters or bi-directional input/output is disabled.
481 physical_to_visual X, Y
483 Maps test offset X from line Y to the visual X coordinate.
484 Returns same X when the line does not contain any right-to-left
486 characters or bi-directional input/output is disabled.
487 mark_horizontal
489 Starts block marking session with "bt::Horizontal" block type.
490 Default key: Alt+L
492 mark_vertical
494 Starts block marking session with "bt::Vertical" block type.
495 Default key: Alt+B
497 overtype_block
499 Copies the selected text and overwrites the text next to the cursor
500 position, according to the blockType value.
501 Default key: Alt+O
503 paste
505 Copies text from the clipboard and inserts it in the cursor
506 position.
507 Default key: Shift+Insert
509 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 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 split_line
524 Splits a line in two at the cursor position.
525 Default key: Enter ( or Ctrl+Enter if wantReturns is 0 )
527 select_all
529 Selects all text
530 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 update_block
536 Adjusts the selection inside the block session, extending of
537 shrinking it to the current cursor position.
538 word_left [ REPEAT = 1 ]
540 Moves cursor REPEAT words to the left.
541 word_right [ REPEAT = 1 ]
543 Moves cursor REPEAT words to the right.
544
546 Dmitry Karasik, <dmitry@karasik.eu.org>.
547
549 Prima, Prima::Widget, Prima::EditDialog, Prima::IntUtils,
550 examples/editor.pl
551perl v5.28.1 2019-02-02 Prima::Edit(3)