Liren Large Software Subsidy 9

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 9 / 09.iso / l / l044 / 4.ddi / ONLINE.ZIP / EDITORS.DOC < prev next >

Wrap

Text File | 1990-10-23 | 24.1 KB | 774 lines

EDITORS ------- TEditor implements a small, fast 64K editor for use in Turbo Vision applications. It features mouse support, undo, clipboard cut, copy and paste, autoindent and overwrite modes, WordStar key bindings, and search and replace. This editor can be used not only for editing files, but as a multi-line memo field in dialogs or forms. The use of TEditor is demonstrated in TVEDIT.PAS for editing files and TVFORM.PAS as a memo field. Both of these file can be found in the \T6\TVDEMOS directory. Object summary -------------- TEditor ------- TEditor is the base object for all editors. It implements most of the editor's functionality. If a TEditor object is created, it will allocate its buffer out of the heap with the given size. The buffer will initially be empty. TMemo ----- TMemo is a descendant of TEditor that is intended to go into a dialog or form. It supports GetData and SetData and allows the Tab key to be processed by TDialog. It also has a different palette than TEditor. GetData/SetData expect a record like the following, TMemoRec = record TextLen: Word; TextData: array[1..MaxMemoLen] of Char; end; where MaxMemoLen is the BufSize value passed to TMemo. TMemo allocates its buffer from the heap. TFileEditor ----------- TFileEditor edits the contents of a file, which it stores in memory allocated from the Buffers unit. This allows several editors to share the same memory pool. Instead of allocating 64k for each editor, you can allocate, say, 128k for all your editors. If the first editor only takes up 16k, it will leave 112k for other editors. The editor takes only the memory it needs at the time out of the pool. An editor will grow by 4k at a time whenever the "gap" shrinks to 0, and will shrink by 4k at a time if the gap grows larger than 4K. See below for a description of the "gap." See BUFFERS.DOC for further information on dynamic buffers. TEditWindow ----------- TEditWindow is a window designed to hold a TFileEditor or the clipboard. It will change its title to display the file name being edited and will initialize scroll bars and an indicator for the editor. If the name passed to TEditWindow is blank, it assumes that you are initializing the clipboard. TIndicator ---------- TIndicator is the line and column counter in the lower left corner of the edit window. It is initialized by TEditWindow and passed as the fourth parameter to a TEditor. Key Bindings ------------ Keys are bound to many of the the familiar WordStar key bindings used in the IDE. The only exceptions are the block commands. Since TEditor does not use persistent blocks, the block commands are simulated by copying the information to and from the clipboard. For example, ^K^B will begin selecting text. ^K^K will copy the text to the clipboard. ^K^C will paste the contents from the clipboard to the editor. This simulates, quite closely, the keystrokes to do the same thing using WordStar bindings. The selection can be started by holding down the shift key with any of the cursor movement commands instead of using the ^K bindings. These key bindings can be changed by overriding the ConvertEvent method which translates the given key event to a command event. Internals --------- Buffer structure ---------------- TEditor implements a "buffer gap" editor. It stores the text in two pieces. Any text before the cursor is stored at the beginning of the buffer, and text after the cursor is stored at the end of the buffer. The space between the text is called the "gap." When a character is inserted into the editor it is inserted into the gap. The editor supports undo by recording deleted text in the gap and maintaining the the number of characters inserted and deleted. When asked to perform an undo, the characters that were inserted are deleted, the deleted characters are copied to the beginning of the gap, and the cursor is positioned after the formerly-deleted text. To illustrate how the buffer operates, consider the following diagram of an editor buffer after the characters "abcdefghijkxxxopqrstuvwxyz" are inserted, CurPtr | v<-- GapLen --> ===========================................ |abcdefghijkxxxopqrstuvwxyz | ===========================................ <-------- BufLen --------> <---------------- BufSize --------------> Buffer after text inserted CurPtr records the position of the cursor, GapLen is the length of the gap, and BufLen is the total number of characters in the buffer. BufSize is the size of the buffer which is always the sum of GapLen and BufLen. If the cursor is then moved to just after the "xxx" characters, the buffer would look like, CurPtr | v<-- GapLen --> ===============...............============= |abcdefghijkxxx opqrstuvwxyz| ===============...............============= BufLen = <------------> + <-----------> <--------------- BufSize ---------------> Buffer after cursor movement Note that the gap is kept in front of the cursor. This allow for quick insertion of characters without moving any text. If "xxx" is deleted using the backspace key the characters are copied to the bottom of the gap and the cursor is moved backwards. The DelCount field records the number of characters deleted. CurPtr | v<--- GapLen ----> ============..................============= |abcdefghijk xxxopqrstuvwxyz| ============..................============= <-> DelCount BufLen = <------------> + <-----------> <--------------- BufSize ---------------> Buffer after "xxx" is deleted When characters are inserted, the insertion count, InsCount, is incremented to record how to many characters to delete with an undo. If "lmn" are now typed, the buffer would look like this: CurPtr | v<-- GapLen --> ===============...............============= |abcdefghijklmn xxxopqrstuvwxyz| ===============...............============= <-> InsCount <-> DelCount BufLen = <------------> + <-----------> <--------------- BufSize ---------------> Buffer after "lmn" is inserted InsCount records the number of characters inserted. If an undo is now requested "lmn" are deleted and "xxx" are copied on top of them, restoring the buffer to what it was before the edits. CurPtr | v<-- GapLen --> ===============...............============= |abcdefghijkxxx opqrstuvwxyz| ===============...............============= BufLen = <------------> + <-----------> <--------------- BufSize ---------------> Buffer after undo If the cursor is moved before the undo is performed, all undo information is lost because the gap moves. Undo will only undo operations done between cursor movements. As soon as the cursor moves, the edits performed are considered "accepted." Note also that undo takes space inside the buffer which could prevent the user from inserting text. The space can be recovered by moving the cursor. Selection or block ------------------ The Selection or block mark is always either before or after the cursor. If text is inserted into the editor, either through a key press, or through InsertText, the contents of the selection are replaced by the inserted text. If there is no selection, the text is just inserted. The selection is marked by the fields SelStart and SelEnd. The selection can be set by the call SetSelection, which will also move the cursor. Options ------- TEditor provides several options, the state of which are stored in Boolean fields. CanUndo indicates whether the editor records undo information. Since undo takes space temporarily from inserts, you might find it advantageous to disable undo. This is done automatically for the clipboard. Overwrite indicates whether the editor is in overwrite or insert mode. AutoIndent records whether the editor will, when the Enter key is pressed, indent the cursor to the column of the first non-space character of the previous line. This is convenient if the editor is used to edit source code. Objects ------- TEditor ----------------------------------------------------------------- Fields ------ HScrollBar: PScrollBar; Pointer to the horizontal scroll bar, nil if the scroll bar does not exist. VScrollBar: PScrollBar; Pointer to the vertical scroll bar, nil if the scroll bar does not exist. Indicator: PIndicator; Pointer to the indicator, nil if the indicator does not exist. Buffer: PEditBuffer; Pointer to the buffer used to hold the text. BufSize: Word; Size of Buffer. BufLen: Word; The amount of text currently in buffer. GapLen: Word; The size of the "gap" between the text before the cursor and the text after the cursor. See above description of the "gap." SelStart: Word; Starting offset of the selection. SelEnd: Word; Ending offset of the selection. CurPtr: Word; Offset of the cursor. CurPos: TPoint; Line/Column location of the cursor in the file. Delta: TPoint; The top line and left most column shown in the view. Limit: TPoint; The maximum number of columns to display, and the number of lines in the file. Records the limits of the scroll bars. DelCount: Word; Number of characters in the end of the gap that were deleted from the text. Used to implement undo. InsCount: Word; Number of characters inserted into the text since the last cursor movement. Used to implement undo. IsValid: Boolean; True if the view is valid. Used by the Valid method. CanUndo: Boolean; True if the editor is to support undo. Modified: Boolean; True if the buffer has been modified. Selecting: Boolean; True if the editor is in selecting mode (i.e., ^K^B has been pressed). Overwrite: Boolean; True if in overwrite mode, otherwise the editor is in insert mode. AutoIndent: Boolean; True if the editor is in autoindent mode. Methods ------- constructor Init(var Bounds: TRect; AHScrollBar, AVScrollBar: PScrollBar; AIndicator: PIndicator; ABufSize: Word); Creates a TEditor object with the given scroll bars and indicator, and with a buffer of size ABufSize. Options are set to sfSelectable and the EventMask additionally allows handling of broadcast events. Any of AHScrollBar, AVScrollBar or AIndicator can be nil if you do not want to use them. constructor Load(var S: TStream); Creates and initializes a TEditor object off the given stream. It does not load the previous contents of the buffer, but instead initializes the buffer to empty. function BufChar(P: Word): Char; Returns the P'th character in the file, factoring in the gap. function BufPtr(P: Word): Word; Returns the offset into Buffer of the P'th character in the file, factoring in the gap. procedure ChangeBounds(var Bounds: TRect); virtual; Overridden to ensure the file stays within view if the parent size changes. procedure ConvertEvent(var Event: TEvent); virtual; Converts key events into command events. Used to implement the WordStar key-bindings. Override if you wish to change or extend the default key-bindings. function CursorVisible: Boolean; Returns true if the cursor (or insertion point) is visible within the view. procedure DeleteSelect; Deletes selection if one exists. procedure DoneBuffer; virtual; Called whenever the buffer should be disposed. By default it calls FreeMem with Buffer and BufSize. It should be overridden if you wish not to use the heap to store the buffer. This is done in TFileEditor. procedure Draw; virtual; Overridden to draw the editor. This should not be overridden by descendants of TEditor. function GetPalette: PPalette; virtual; Returns the Editor palette, CEditor. Override if you wish to change the palette of the editor. procedure HandleEvent(var Event: TEvent); virtual; Provides the event handling for the editor. Override if you wish to extend the commands the editor handles. procedure InitBuffer; virtual; Called whenever the buffer should be allocated. By default, an editor will call GetMem with Buffer and BufSize. You should override this method if you do not want the editor to allocate the buffer from the heap. function InsertBuffer(var P: PEditBuffer; Offset, Length: Word; AllowUndo, SelectText: Boolean): Boolean; This is the lowest-level text insertion method. It will insert Length bytes of text from the given pointer to text into the buffer from the given offset into the buffer, P. It will optionally record undo information and select the text inserted. This method need never be called directly, since it is called from InsertFrom and InsertText. This method should be used if the buffer to be copied from could move (e.g., P was allocated using the Buffers unit). function InsertFrom(Editor: PEditor): Boolean; virtual; Insert the selection from the given editor into this editor. This method is used to implement Cut, Copy, and Paste. It need never be overridden by the user. function InsertText(Text: Pointer; Length: Word; SelectText: Boolean): Boolean; Insert the given text of length Length into the buffer, optionally selecting the text. This is an easier-to-use version of InsertBuffer. procedure ScrollTo(X, Y: Integer); Move column X and line Y to the upper-left corner of the editor. function Search(FindStr: String; Opts: Word): Boolean; Search for the given string in the editor with the given options. The options words are, efCaseSensitive Case sensitive search efWholeWordsOnly Find whole words only function SetBufSize(NewSize: Word): Boolean; virtual; Called whenever the buffer can be grown or shrunk to the given value. It should return true if the the buffer can be of the given size. By default, it returns true if NewSize is less than or equal to the new size. procedure SetCmdState(Command: Word; Enable: Boolean); Disables or enables the given command. The command is always disabled if the editor is not the selected view. Used as a convenient way to enable and disable command instead of using EnableCommands and DisableCommands. procedure SetSelect(NewStart, NewEnd: Word; CurStart: Boolean); Set the selection to the given offsets into the file. This method will either place the cursor in front of behind the selection pending on the value of CurStart. procedure SetState(AState: Word; Enable: Boolean); virtual; SetState is overridden to hide and show scroll bars and the indicator and to enable and disable commands. If you wish to enable and disable additional commands, override UpdateCommands instead. This is called whenever the command states should be updated. procedure Store(var S: TStream); Stores the editor on the given stream. procedure TrackCursor(Center: Boolean); Forces the cursor to be visible. If Center is True, the cursor is forced to be in the center of the screen in the Y access. The X, or column, is not changed. procedure Undo; Undo the changes since the last cursor movement. procedure UpdateCommands; virtual; Called whenever the commands should be updated. This is used to enable and disable commands such as cmUndo, cmClip, cmCopy, etc. function Valid(Command: Word): Boolean; virtual; Returns whether the view is valid given Command. By default it returns the value of IsValid which is True if Buffer is non-nil. TMemo ----------------------------------------------------------------- Methods ------- constructor Load(var S: TStream); Creates and initializes a TMemo object off the given stream. function DataSize: Word; virtual; Returns the size of the data written by GetData and read by SetData. By default it return SizeOf(Word) + BufSize. procedure GetData(var Rec); virtual; Writes the contents of the buffer into the given Rec. function GetPalette: PPalette; virtual; Returns a palette, CMemo, suitable for TMemo's use in a TDialog. procedure HandleEvent(var Event: TEvent); virtual; Prevents TMemo from handling kbTab, otherwise handles events the same as a TEditor. procedure SetData(var Rec); virtual; Read the contents of the buffer from the given Rec. procedure Store(var S: TStream); Store the TMemo to the given stream. TFileEditor ----------------------------------------------------------------- Fields ------ FileName: FNameStr; Name of the file being edited. Methods ------- constructor Init(var Bounds: TRect; AHScrollBar, AVScrollBar: PScrollBar; AIndicator: PIndicator; AFileName: FNameStr); Creates a TFileEditor object with the given scroll bars and indicator and loads the contents of the given file. If the file is not found or invalid an error message will be displayed and the object's Valid method will return false. Options are set to sfSelectable and the EventMask additionally allows handling of broadcast events. Any of AHScrollBar, AVScrollBar or AIndicator can be nil if you do not want them. constructor Load(var S: TStream); Creates and initializes a TFileEditor object off the given stream. The file is reloaded into the editor and the cursor is positioned back to the location it was when the Store was performed. It is ideal for use with a "Desktop save" option. procedure DoneBuffer; virtual; Disposes of the buffer allocated from the Buffers unit. procedure HandleEvent(var Event: TEvent); virtual; Overridden to implement the cmSave and cmSaveAs commands. procedure InitBuffer; virtual; Allocates memory from the Buffers unit to use for the editor buffer. function LoadFile: Boolean; Read the file from disk and check for errors. Sets IsValid to False if the file was not loaded into the buffer. function Save: Boolean; Saves the file to disk. Returns false if the save failed or was canceled. If EditorFlags has the efBackupFiles bit set, a .BAK file is created. Will call SaveAs if the editor is "Untitled." function SaveAs: Boolean; Saves the editor with a different name. The name is derived from a dialog brought up using the EditorDialogs function pointer. Returns True if the editor was saved, False otherwise (i.e., the operation was canceled). function SaveFile: Boolean; Saves the file to disk. Returns False if the save failed. If EditorFlags has the efBackupFiles bit set, a .BAK file is created. function SetBufSize(NewSize: Word): Boolean; virtual; Overridden to grow and shrink the buffer with calls to the Buffers unit. Will grow and shrink the buffer in 4k increments. procedure Store(var S: TStream); Store the TFileEditor object on the given stream. The file name, not the file contents, are stored on the stream. procedure UpdateCommands; virtual; Overridden to enable and disable the cmSave and cmSaveAs commands. They are only valid if the selected view is an editor, otherwise they should be disabled. function Valid(Command: Word): Boolean; virtual; Overridden to make sure the file is saved before the program exits. Returns False if the user cancels the save. TEditWindow ----------------------------------------------------------------- Fields ------ Editor: PFileEditor; Pointer to the editor object in the edit window. constructor Init(var Bounds: TRect; FileName: FNameStr; ANumber: Integer); Creates a TEditWindow object that will edit the given file name with window number ANumber. This method initializes a TFileEditor with scroll bars and an indicator. If the file name is a null string, it is assumed to be an untitled file. If Editor is equal to the Clipboard variable, the editor is assumed to be the clipboard. constructor Load(var S: TStream); Creates and initializes a TEditWindow off the given stream. procedure Close; virtual; Overridden to hide, instead of close, the window if the editor is a clipboard. function GetTitle(MaxSize: Integer): TTitleStr; virtual; Returns the name of the file being edited by the editor or 'Clipboard' if the editor is the clipboard. procedure HandleEvent(var Event: TEvent); virtual; Handles cmUpdateTitle to redraw the frame of the window. Used in SaveAs to change the title of the window if the file being edited changes names. procedure Store(var S: TStream); Saves the TEditWindow object to the given stream. TIndicator ----------------------------------------------------------------- Fields ------ Location: TPoint; Stores the location to display. Updated by a TEditor. Modified: Boolean; True if the associated TEditor has been modified. Displays a special character if true. Methods ------- constructor Init(var Bounds: TRect); Creates a TIndicator object. procedure Draw; virtual; Draws the indicator. function GetPalette: PPalette; virtual; Return the a pointer to CIndicator, the TIndicator default palette. procedure SetState(AState: Word; Enable: Boolean); virtual; Draws the indicator in the frame dragging color if dragging. procedure SetValue(ALocation: TPoint; AModified: Boolean); Method called by TEditor to update the values to the fields of a TIndicator. Globals ------- Variables --------- WordChars: set of Char; Set of characters that define a word. Used when handling the cmWordLeft and cmWordRight commands. The default value is ['0'..'9', 'A'..'Z', '_', 'a'..'z']. EditorDialog: TEditorDialog; EditorDialog is a procedure variable that is used by TEditor objects to display various dialogs. Since dialogs are very application-dependent, EDITORS cannot display its own dialogs. Instead it calls this function variable instead. For an example of an EditorDialog function, see TVEDIT.PAS. The various dialog values are edOutOfMemory edReadError edWriteError edCreateError edSaveModify edSaveUntitled edSaveAs edFind edSearchFailed edReplace edReplacePrompt EditorFlags: Word; EditorFlags contains various flags for use in the editor. The value of which are efCaseSensitive Default to case sensitive search efWholeWordsOnly Default to whole words only search efPromptOnReplace Prompt on replace efReplaceAll Replace all occurrences. efDoReplace Do replace. efBackupFiles Create .BAK files on saves. The default value is efBackupFiles + efPromptOnReplace. FindStr: String[80]; Stores the last value used for a find. ReplaceStr: String[80]; Stores the last value of a replace. Clipboard: PEditor = nil; Pointer to the clipboard. Any TEditor can be the clipboard, it just needs be assigned to this variable. The clipboard should not support undo (i.e., its CanUndo should be false). Procedures ---------- procedure RegisterEditors; Register all object types in EDITORS.