Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Prima::Edit(3)	      User Contributed Perl Documentation	Prima::Edit(3)

NAME
       Prima::Edit - standard text editing widget

SYNOPSIS
	       use Prima::Edit;
	       my $e = Prima::Edit-> create(
		       text	    => 'Hello $world',
		       syntaxHilite => 1,
	       );
	       $e-> selection( 1, 1, 1,	2);

DESCRIPTION
       The class provides text editing capabilities, three types of selection,
       text wrapping, syntax highlighting, auto	indenting, undo	and redo
       function, search	and replace methods.

       The module declares "bt::" package, that	contains integer constants for
       selection block type, used by blockType property.

USAGE
       The class addresses the text space by (X,Y)-coordinates,	where X	is
       visual character	offset and Y is	line number. The addressing can	be
       'visual'	and 'logical', - in logical case Y is number of	line of	text.
       The difference can be observed if wordWrap property is set to 1,	when a
       single text string can be shown as several sub-strings, called chunks.

       The text	is stored line-wise in "{lines}" array;	to access it use
       get_line	method.	 To access the text chunk-wise,	use get_chunk method.

       All keyboard events, except the character input and tab key handling,
       are processed by	the accelerator	table (	see Prima::Menu	). The default
       "accelItems" table defines names, keyboard combinations,	and the
       corresponding actions to	the class functions. The class does not
       provide functionality to	change these mappings. To do so, consult
       "Prima::AccelTable" in Prima::Menu.

API
   Events
       ParseSyntax TEXT, RESULT_ARRAY_REF
	   Called when syntax highlighting is requires - TEXT is a string to
	   be parsed, and the parsing results to be stored in
	   RESULT_ARRAY_REF, which is a	reference to an	array of integer
	   pairs, each representing a single-colored text chunk.  The first
	   integer in the pairs	is the length of a chunk, the second - color
	   value ( "cl::XXX" constants ).

   Properties
       autoIndent BOOLEAN
	   Selects if the auto indenting feature is on.

	   Default value: 1

       blockType INTEGER
	   Defines type	of selection block. Can	be one of the following
	   constants:

	   bt::CUA
	       Normal block, where the first and the last line of the
	       selection can be	partial, and the lines between occupy the
	       whole line. CUA stands for 'common user access'.

	       Default keys: Shift + arrow keys

	       See also: cursor_shift_key

	   bt::Vertical
	       Rectangular block, where	all selected lines are of same offsets
	       and lengths.

	       Default key: Alt+B

	       See also: mark_vertical

	   bt::Horizontal
	       Rectangular block, where	the selection occupies the whole line.

	       Default key: Alt+L

	       See also: mark_horizontal

       cursor X, Y
	   Selects visual position of the cursor

       cursorX X
	   Selects visual horizontal position of the cursor

       cursorY Y
	   Selects visual vertical position of the cursor

       cursorWrap BOOLEAN
	   Selects cursor behavior when	moved horizontally outside the line.
	   If 0, the cursor is not moved. If 1,	the cursor moved to the
	   adjacent line.

	   See also: cursor_left, cursor_right,	word_left, word_right.

       insertMode BOOLEAN
	   Governs the typing mode - if	1, the typed text is inserted, if 0,
	   the text overwrites the old text. When "insertMode" is 0, the
	   cursor shape	is thick and covers the	whole character; when 1, it is
	   of default width.

	   Default toggle key: Insert

       hiliteNumbers COLOR
	   Selects the color for number	highlighting

       hiliteQStrings COLOR
	   Selects the color for highlighting the single-quoted	strings

       hiliteQQStrings COLOR
	   Selects the color for highlighting the double-quoted	strings

       hiliteIDs ARRAY
	   Array of scalar pairs, that define words to be highlighted.	The
	   first item in the pair is an	array of words;	the second item	is a
	   color value.

       hiliteChars ARRAY
	   Array of scalar pairs, that define characters to be highlighted.
	   The first item in the pair is a string of characters; the second
	   item	is a color value.

       hiliteREs ARRAY
	   Array of scalar pairs, that define character	patterns to be
	   highlighted.	 The first item	in the pair is a perl regular
	   expression; the second item is a color value.

       mark MARK [ BLOCK_TYPE ]
	   Selects block marking state.	If MARK	is 1, starts the block
	   marking, if 0 - stops the block marking. When MARK is 1, BLOCK_TYPE
	   can be used to set the selection type ( "bt::XXX" constants ). If
	   BLOCK_TYPE is unset the value of blockType is used.

       markers ARRAY
	   Array of arrays with	integer	pairs, X and Y,	where each represents
	   a visual coordinates	in text. Used as anchor	storage	for fast
	   navigation.

	   See also: add_marker, delete_marker

       modified	BOOLEAN
	   A boolean flag that shows if	the text was modified. Can be used
	   externally, to check	if the text is to be saved to a	file, for
	   example.

       offset INTEGER
	   Horizontal offset of	text lines in pixels.

       persistentBlock BOOLEAN
	   Selects whether the selection is cancelled as soon as the cursor is
	   moved ( 0 ) or it persists until the	selection is explicitly
	   changed ( 1 ).

	   Default value: 0

       readOnly	BOOLEAN
	   If 1, no user input is accepted. Manipulation with text are allowed
	   though.

       selection X1, Y1, X2, Y2
	   Accepts two pair of coordinates, ( X1,Y1) the beginning and (
	   X2,Y2) the end of new selection, and	sets the block according to
	   blockType property.

	   The selection is null if X1 equals to X2 and	Y1 equals to Y2.
	   has_selection method	returns	1 if the selection is non-null.

       selStart	X, Y
	   Manages the selection start.	See selection, X1 and Y1.

       selEnd X, Y
	   Manages the selection end. See selection, X2	and Y2.

       syntaxHilite BOOLEAN
	   Governs the syntax highlighting. Is not implemented for word
	   wrapping mode.

       tabIndent INTEGER
	   Maps	tab ( \t ) key to "tabIndent" amount of	space characters.

       text TEXT
	   Provides access to all the text data. The lines are separated by
	   the new line	( \n ) character.

	   See also: textRef.

       textRef TEXT_PTR
	   Provides access to all the text data. The lines are separated by
	   the new line	( \n ) character. TEXT_PTR is a	pointer	to text
	   string.

	   The property	is more	efficient than text with the large text,
	   because the copying of the text scalar to the stack stage is
	   eliminated.

	   See also: text.

       topLine INTEGER
	   Selects the first line of the text drawn.

       undoLimit INTEGER
	   Sets	limit on number	of stored atomic undo operations. If 0,	undo
	   is disabled.

	   Default value: 1000

       wantTabs	BOOLEAN
	   Selects the way the tab ( \t	) character is recognized in the user
	   input.  If 1, it is recognized by the Tab key; however, this
	   disallows the toolkit widget	tab-driven navigation. If 0, the tab
	   character can be entered by pressing	Ctrl+Tab key combination.

	   Default value: 0

       wantReturns BOOLEAN
	   Selects the way the new line	( \n ) character is recognized in the
	   user	input.	If 1, it is recognized by the Enter key; however, this
	   disallows the toolkit default button	activation. If 0, the new line
	   character can be entered by pressing	Ctrl+Enter key combination.

	   Default value: 1

       wordDelimiters STRING
	   Contains string of character	that are used for locating a word
	   break.  Default STRING value	consists of punctuation	marks, space
	   and tab characters, and "\xff" character.

	   See also: word_left,	word_right

       wordWrap	BOOLEAN
	   Selects whether the long lines are wrapped, or can be positioned
	   outside the horizontal widget inferior borders. If 1, syntaxHilite
	   is not used.	A line of text can be represented by more than one
	   line	of screen text ( chunk ) . To access the text chunk-wise, use
	   get_chunk method.

   Methods
       add_marker X, Y
	   Adds	visual coordinated X,Y to markers property.

       back_char [ REPEAT = 1 ]
	   Removes REPEAT times	a character left to the	cursor.	If the cursor
	   is on 0 x-position, removes the new-line character and concatenates
	   the lines.

	   Default key:	Backspace

       cancel_block
	   Removes the selection block

	   Default key:	Alt+U

       change_locked
	   Returns 1 if	the logical locking is on, 0 if	it is off.

	   See also lock_change.

       copy
	   Copies the selected text, if	any, to	the clipboard.

	   Default key:	Ctrl+Insert

       copy_block
	   Copies the selected text and	inserts	it into	the cursor position,
	   according to	the blockType value.

	   Default key:	Alt+C

       cursor_cend
	   Moves cursor	to the bottom line

	   Default key:	Ctrl+End

       cursor_chome
	   Moves cursor	to the top line

	   Default key:	Ctrl+Home

       cursor_cpgdn
	   Default key:	Ctrl+PageDown

	   Moves cursor	to the end of text.

       cursor_cpgup
	   Moves cursor	to the beginning of text.

	   Default key:	Ctrl+PageUp

       cursor_down [ REPEAT = 1	]
	   Moves cursor	REPEAT times down

	   Default key:	Down

       cursor_end
	   Moves cursor	to the end of the line

	   Default key:	End

       cursor_home
	   Moves cursor	to the beginning of the	line

	   Default key:	Home

       cursor_left [ REPEAT = 1	]
	   Moves cursor	REPEAT times left

	   Default key:	Left

       cursor_right [ REPEAT = 1 ]
	   Moves cursor	REPEAT times right

	   Default key:	Right

       cursor_up [ REPEAT = 1 ]
	   Moves cursor	REPEAT times up

	   Default key:	Up

       cursor_pgdn [ REPEAT = 1	]
	   Moves cursor	REPEAT pages down

	   Default key:	PageDown

       cursor_pgup [ REPEAT = 1	]
	   Moves cursor	REPEAT pages up

	   Default key:	PageUp

       cursor_shift_key	[ ACCEL_TABLE_ITEM ]
	   Performs action of the cursor movement, bound to ACCEL_TABLE_ITEM
	   action ( defined in "accelTable" or "accelItems" property ),	and
	   extends the selection block along the cursor	movement. Not called
	   directly.

       cut Cuts	the selected text into the clipboard.

	   Default key:	Shift+Delete

       delete_block
	   Removes the selected	text.

	   Default key:	Alt+D

       delete_char [ REPEAT = 1	]
	   Delete REPEAT characters from the cursor position

	   Default key:	Delete

       delete_line LINE_ID, [ LINES = 1	]
	   Removes LINES of text at LINE_ID.

       delete_current_chunk
	   Removes the chunk ( or line,	if wordWrap is 0 ) at the cursor.

	   Default key:	Ctrl+Y

       delete_chunk CHUNK_ID, [	CHUNKS = 1 ]
	   Removes CHUNKS ( or lines, if wordWrap is 0 ) of text at CHUNK_ID

       delete_marker INDEX
	   Removes marker INDEX	in markers list.

       delete_to_end
	   Removes text	to the end of the chunk.

	   Default key:	Ctrl+E

       delete_text X, Y, TEXT_LENGTH
	   Removes TEXT_LENGTH characters at X,Y visual	coordinates

       draw_colorchunk CANVAS, TEXT, LINE_ID, X, Y, COLOR
	   Paints the syntax-highlighted chunk of TEXT,	taken from LINE_ID
	   line	index, at X, Y.	COLOR is used if the syntax highlighting
	   information contains	"cl::Fore" as color reference.

       end_block
	   Stops the block selection session.

       find SEARCH_STRING, [ X = 0, Y =	0, REPLACE_LINE	= '', OPTIONS ]
	   Tries to find ( and,	if REPLACE_LINE	is defined, to replace with it
	   ) SEARCH_STRING from	(X,Y) visual coordinates. OPTIONS is an
	   integer that	consists of the	"fdo::"	constants; the same constants
	   are used in Prima::EditDialog, which	provides graphic interface to
	   the find and	replace	facilities of Prima::Edit.

	   Returns X1, Y, X2, NEW_STRING where X1.Y-X2.Y are visual
	   coordinates of the found string, and	NEW_STRING is the replaced
	   version (if any)

	   fdo::MatchCase
	       If set, the search is case-sensitive.

	   fdo::WordsOnly
	       If set, SEARCH_STRING must constitute the whole word.

	   fdo::RegularExpression
	       If set, SEARCH_STRING is	a regular expression.

	   fdo::BackwardSearch
	       If set, the search direction is backwards.

	   fdo::ReplacePrompt
	       Not used	in the class, however, used in Prima::EditDialog.

       get_chunk CHUNK_ID
	   Returns chunk of text, located at CHUNK_ID.	Returns	empty string
	   if chunk is nonexistent.

       get_chunk_end CHUNK_ID
	   Returns the index of	chunk at CHUNK_ID, corresponding to the	last
	   chunk of same line.

       get_chunk_org CHUNK_ID
	   Returns the index of	chunk at CHUNK_ID, corresponding to the	first
	   chunk of same line.

       get_chunk_width TEXT, FROM, LENGTH, [ RETURN_TEXT_PTR ]
	   Returns the width in	pixels of "substr( TEXT, FROM, LENGTH)".  If
	   FROM	is larger than length of TEXT, TEXT is padded with space
	   characters. Tab character in	TEXT replaced to tabIndent times space
	   character. If RETURN_TEXT_PTR pointer is specified, the converted
	   TEXT	is stored there.

       get_line	INDEX
	   Returns line	of text, located at INDEX.  Returns empty string if
	   line	is nonexistent.

       get_line_dimension INDEX
	   Returns two integers, representing the line at INDEX	in wordWrap
	   mode: the first value is the	corresponding chunk index, the second
	   is how many chunks represent	the line.

	   See also: physical_to_logical.

       get_line_ext CHUNK_ID
	   Returns the line, corresponding to the chunk	index.

       get_selected_text
	   Return the text currently selected.

       has_selection
	   Returns boolean value, indicating if	the selection block is active.

       insert_empty_line LINE_ID, [ REPEAT = 1 ]
	   Inserts REPEAT empty	lines at LINE_ID.

       insert_line LINE_ID, @TEXT
	   Inserts @TEXT strings at LINE_ID

       insert_text TEXT, [ HIGHLIGHT = 0 ]
	   Inserts TEXT	at the cursor position.	If HIGHLIGHT is	set to 1, the
	   selection block is cancelled	and the	newly inserted text is
	   selected.

       lock_change BOOLEAN
	   Increments (	1 ) or decrements ( 0 )	lock count. Used to defer
	   change notification in multi-change calls. When internal lock count
	   hits	zero, "Change" notification is called.

       physical_to_logical X, Y
	   Maps	visual X,Y coordinates to the logical and returns the integer
	   pair.  Returns same values when wordWrap is 0.

       logical_to_visual X, Y
	   Maps	logical	X,Y coordinates	to the visual and returns the integer
	   pair.

	   Returns same	values when wordWrap is	0.

       visual_to_physical X, Y
	   Maps	visual X,Y coordinates to the physical text offset relative to
	   the Y line

	   Returns same	X when the line	does not contain any right-to-left
	   characters or bi-directional	input/output is	disabled.

       physical_to_visual X, Y
	   Maps	test offset X from line	Y to the visual	X coordinate.

	   Returns same	X when the line	does not contain any right-to-left
	   characters or bi-directional	input/output is	disabled.

       mark_horizontal
	   Starts block	marking	session	with "bt::Horizontal" block type.

	   Default key:	Alt+L

       mark_vertical
	   Starts block	marking	session	with "bt::Vertical" block type.

	   Default key:	Alt+B

       overtype_block
	   Copies the selected text and	overwrites the text next to the	cursor
	   position, according to the blockType	value.

	   Default key:	Alt+O

       paste
	   Copies text from the	clipboard and inserts it in the	cursor
	   position.

	   Default key:	Shift+Insert

       realize_panning
	   Performs deferred widget panning, activated by setting
	   "{delayPanning}" to 1.  The deferred	operations are those performed
	   by offset and topLine.

       set_line	LINE_ID, TEXT, [ OPERATION, FROM, LENGTH ]
	   Changes line	at LINE_ID to new TEXT.	Hint scalars OPERATION,	FROM
	   and LENGTH used to maintain selection and marking data. OPERATION
	   is an arbitrary string, the ones that are recognized	are
	   'overtype', 'add', and 'delete'.  FROM and LENGTH define the	range
	   of the change; FROM is a character offset and LENGTH	is a length of
	   changed text.

       split_line
	   Splits a line in two	at the cursor position.

	   Default key:	Enter (	or Ctrl+Enter if wantReturns is	0 )

       select_all
	   Selects all text

       start_block [ BLOCK_TYPE	]
	   Begins the block selection session. The block type if BLOCK_TYPE,
	   if it is specified, or blockType property value otherwise.

       update_block
	   Adjusts the selection inside	the block session, extending of
	   shrinking it	to the current cursor position.

       word_left [ REPEAT = 1 ]
	   Moves cursor	REPEAT words to	the left.

       word_right [ REPEAT = 1 ]
	   Moves cursor	REPEAT words to	the right.

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO
       Prima, Prima::Widget, Prima::EditDialog,	Prima::IntUtils,
       examples/editor.pl

perl v5.24.1			  2017-02-28			Prima::Edit(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | API | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::Edit&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help