Class ::tycho::Edit


Inherits: ::tycho::File - Source File - Contents: itk_options - public methods - protected methods - protected variables
This widget contains arbitrary text and allows editing of this text using emacs-like key bindings plus mouse movements. It interfaces to find/change and spell check dialog boxes, and supports filling of text, with an optional prefix added on each line. It has an undo mechanism and supports filling text. It also provides an infrastructure, exploited in derived classes, for parsing text in order to color it, control the font, etc.

This widget is designed to be placed within a Displayer window, although it can also be used on its own. To use within a Displayer, the following commands will work:

catch {destroy .d}
::tycho::Displayer .d
::tycho::Edit .d.e
.d centerOnScreen

Note that sometime in the future, many of the public methods in this class may become private or protected. Currently they are public to permit access from key bindings. The "code" directive in Itcl only makes private procedures accessible, not private methods. But this may change in the future.


Itk_options

-scrollbar 1
Specify whether the widget should have a scrollbar (0 or 1).
-text
Change the text in the edit window.
-selectcolor white
The color of selected text.

Public constructs

Public Methods

capitalize
Capitalize words in the selection, or the current word if there is no selection.
center
Center the insertion point in the window.
clear
Clear the text.
closeParen closeParen
Insert a close parenthesis, bracket, or brace. Highlight the region between the corresponding open parenthesis and this close parenthesis if the open parenthesis is visible in the window. The single argument represents one of the close parenthesis characters using a string that causes fewer problems when passed around in Tcl than the parentheses themselves, "paren", "brace", or "bracket".
copy
Save the selection to the clipboard.
cut
Remove the selection and save it to the clipboard.
currentPoint
Return the current insertion point in a form usable by seeFragment.
debugUndo
Print the status of the undo information (for debugging).
del type
If there is a selection, delete it and return. Otherwise, delete a single character or word and record for undo. The type argument should be "char" or "word" for backwards deletion or "fchar" or "fword" for forwards deletion.
deleteRange first last
Delete the specified range and record the deletion for undoing. If either the beginning or the end of the range align with the contents of the previous deletion or insertion, then the deleted range is appended to undo buffer rather than replacing it. The deleted string is copied to the clipboard. The arguments are indices in any form understood by the Tk text widget.
deleteSelection
If the selection is owned by this window and is visible, delete it and return 1. Otherwise return 0. It is not deleted if it is not visible because this was found to cause erroneous editing of files.
evaluate
In this base class, just issue an error message.
execProcess command {waitForOk 1}
Exec a subprocess. The optional arg `waitForOk' determines whether the process is started immediately, or if we wait for the user to hit ok.
fillSelection
Fill the set of lines identified by the selection so that they are roughly the same length. If there is no selection, then the fill region is a paragraph. A paragraph is delimited by either a blank line or a line with only the fillPrefix on it. In the future, there may be a more flexible mechanism for identifying a paragraph. Note that the implementation here is too slow, and needs to be improved.
findAll tag case regexp wholeword pattern start end tags
Find and tag all occurrences of the given pattern in a range of the text. The arguments are as a follows:
   tag       the tag to attach to matching text
   case      if 0, ignore case
   regexp    if 0, return only exact matches
   wholeword if 0, ignore word boundaries
   pattern   the pattern or string to search for
   start     the start index
   end       the end index
   tags      the list of tags to restrict the search to
The method uses specific arguments rather than options because it is frequently invoked and the overhead needs to be minimized. If the "regexp" option is 1, then the pattern is interpreted as a regular expression. If "wholeword" is 1, then match only whole words. In this case, "regexp" is ignored because we have to use a regexp search to identify word boundaries. A whole word is any string bounded by characters that are not alphabetic, numeric, or an underscore.

When restricting the search to certain tagged text (i.e. when the last argument is not a null list), then if one or more characters in the match are tagged with one the tags in the given list, the match is accepted.

findOne case backwards regexp wholeword pattern start end tags
Search for a pattern, word, or character sequence in the text. Return a two-element list containing the position and length of the match. If there is no match, return an empty string. This is amazingly complicated primarily because of wanting to support searches for whole words, but also because of the desire to search only certain tagged text. The arguments are as a follows:
   case      if 0, ignore case
   backwards if 0, search forwards from the start position
   regexp    if 0, return only exact matches
   wholeword if 0, ignore word boundaries
   pattern   the pattern or string to search for
   start     the start index
   end       the end index
   tags      the list of tags to restrict the search to
The method uses specific arguments rather than options because it is frequently invoked and the overhead needs to be minimized. If the "regexp" option is 1, then the pattern is interpreted as a regular expression. If "wholeword" is 1, then match only whole words. In this case, "regexp" is ignored because we have to use a regexp search to identify word boundaries. A whole word is any string bounded by characters that are not alphabetic, numeric, or an underscore.

When restricting the search to certain tagged text (i.e. when the last argument is not a null list), then if one or more characters in the match are tagged with one the tags in the given list, the match is accepted.

focusin
Grab the focus.
get args
Get text from the text widget (thin wrapper for the text widget get).
getSelection
If the selection is owned by this window, return the text in it. Otherwise return a null string.
gotoLine
Query the user for line number, then goto it.
help
Open a help window. This should be redefined in derived classes.
indicateReadOnly bool
Indicate in the status bar and in the menus whether modifications are allowed on the buffer.
insertData data
Insert the given data at the insertion cursor.
insertString index str
Insert the specified string at the specified index. If there is a selection, delete it first. This command sets up the undo and starts a parsing operation (which may not complete before this returns).
killToEndOfLine
Delete characters from the insertion mark to the end of the line. If the line is blank (no characters), then delete the line.
lowerCase
Convert the selection or the current word to lower case.
mouseStuff xpos ypos
Insert text from the selection if the mouse has not moved since it was first pushed. We take "not moved" to mean "not moved more than three pixels".
openLine
Open a blank line of text above the insertion cursor.
parseNow start stop
Many derived classes tag the text in various ways, such as to color comments. The methods that do the work are called "parseNow." In this base class, nothing is done here.
parseRegion start stop
Many derived classes tag the text in various ways, such as to color comments. The methods that do the work, called "parseNow" are accessed through this parseRegion method. This method breaks up large regions to be parsed into chunks, parses the first chunk, and then schedules the parsing of the remaining chunks to occur in the future. The amount of text processed in one chunk and the duration of the delay for the rest are determined by the value of the protected variables maxNumLinesToParse and delayBeforeDeferredParsing.
paste
Paste the selection from the clipboard.
print
Print the selection or, if there is no selection, the entire contents. Query the user for the print command to use. A temporary file is created and then deleted to do the printing. The name of that file will be appended to the end of the command specified by the user before it is invoked.
queryFillColumn
Query the user for a new right column for text fill.
queryFillPrefix
Query the user for a new fill prefix.
recordCharForUndo char
Record a single character entry for undo. If the file is read-only, do nothing and return 1. Otherwise, return 0.
recordMousePos xpos ypos
Record the mouse position.
replaceAll tag str
Replace all the text intervals tagged by the given tag with the specified string.
scroll direction
Scroll forward (or backwards) by one page. If direction is +1, scroll forward one page. If it is -1, scroll backward one page. Two lines of overlap are left between the old and new pages. The insertion point is placed at the top of the new page. As a side effect, the selection (if there is one) is cleared.
search
If a search window already exists, raise it and shift the focus to it. Otherwise, create one.
searchQuery backwards nochange
If a search window already exists, raise it and shift the focus to it. Otherwise, create one. The direction should be 1 for backwards and zero for forwards. The nochange should be 1 for windows where changes will not be allowed and 0 otherwise.
seeFragment point
Go to the specified point in the text, moving the insertion cursor to that point, and adjusting the view so that the point is in view. The point can be specified in any of three ways:
   {line linenumber}
   {range startindex endindex}
   regexp
In the first two forms, the point is a list beginning with the keyword "line" or "range". If the point has neither of these forms, then it is interpreted as a regular expression, and the first match of the regular expression is taken to be the specified point. In all cases, the background color of the matching text is changed temporarily. Notice that this will not be visible if the "range" form is used and the two indices are equal. As a side effect, the selection (if there is one) is cleared.
selectRange start stop
Select everything in the specified range. Place the insertion cursor at the beginning of the selected range, break the undo sequence, and move the view to see the beginning of the selected range.
spellCheck
If a spell check window already exists, raise it and shift the focus to it. Otherwise, create one.
spellCheckTags
Return a list of tags to restrict the spelling check.
textWinName
Return the full path name of the text widget. Note that this path name is defined as a command at the global scope. This is intended only to be used for interfacing to legacy Tcl/Tk code that interacts directly with a Tk text widget. A null string is returned if for some reason the text window name does not exist (due to an error in construction).
stuff
Insert text from the selection.
undo
Undo the last deletion and insertion. As a side effect, this unselects any selected text.
undoBoundary
Break a sequence of character entries for the purposes of the undo command. I.e., if a sequence of characters is entered, then this is called, then another sequence of characters is entered, only the second sequence of characters will be undone by the undo command.

This method also clears the status bar: any changes that affect the undo must also clear the status.

unselectRange start stop
Unselect everything in the specified range.
upperCase
Convert the selection or the current word to upper case.
writeSpellText filename
Write to the specified file any text that should be spell checked, which is that text tagged with any one of the tags returned by the method spellCheckTags. If spellCheckTags returns an empty string, then the entire file is written.

Protected constructs

Protected Methods

getTaggedText tag
Return the region of text tagged with the given tag within which the "current" mark sits. If there is no such tagged text, return the empty string.
preference mode args
Access the preferences associated with this widget. This method overrides the default method in ::tycho::TWidget to access the "edittext" preferences.
resetUndo
Reset the undo buffer.
saveText
Return the text to save.

Protected Variables

fillPrefix
The prefix to use on each line when filling text.
fillStart
After a fill, this variable will indicate the index where the fill began.
maxNumLinesToParse 200
Specify how much parsing is done (how many lines of text) before the rest is deferred. This number may need to be tuned to work well on a wide range of platforms. It determines the responsivity of the system when a large file is being opened. If on opening the file the screen fails to be mapped before all parsing is done, then this number should be decreased.
delayBeforeDeferredParsing 200
Specify the time delay is between parsing chunks of text. This number may need to be tuned to work well on a wide range of platforms. It determines the responsivity of the system when a large file is being opened. If the system is not sufficiently responsive to mouse or keyboard actions, try increasing this number.

Index of classes



Author: Edward A. Lee
Contributor: Shuvra Bhattacharyya, Joel King
Version: @(#)Edit.itcl 1.96 12/15/96
Copyright: (c) 1995-1996 The Regents of the University of California.