Update of /project/climacs/cvsroot/climacs/Doc In directory common-lisp.net:/tmp/cvs-serv27428

Modified Files: climacs-internals.texi Log Message: Separated syntax from redisplay.

Date: Fri Jan 21 21:15:52 2005 Author: rstrandh

Index: climacs/Doc/climacs-internals.texi diff -u climacs/Doc/climacs-internals.texi:1.8 climacs/Doc/climacs-internals.texi:1.9 --- climacs/Doc/climacs-internals.texi:1.8 Tue Jan 18 10:59:54 2005 +++ climacs/Doc/climacs-internals.texi Fri Jan 21 21:15:50 2005 @@ -558,77 +558,77 @@ implementations may implement it fairly efficiently, say O(log n) where n is the number of lines in the buffer.

-@chapter Redisplay and the syntax protocol +@chapter The syntax protocol

@section General

-A buffer can be on display in several panes. The redisplay -algorithm is invoked on each such pane. Each pane is associated -with a distinguished mark called the `point' of the pane. The point -is a right-sticky mark independently of whether you are typing -left-to-right or right-to-left. - -The redisplay function works by dispatching on an object of type -syntax, which determines exactly how the buffer contents is going to -be rendered in this particular pane. +A buffer may have a syntax module associated with it. The syntax +module usually consists of an incremental parser that analyzes the +contents of the buffer and creates some kind of parse tree or other +representation of the contents in order that it can be exploited by +the redisplay module and by user commands.

@deftp {Protocol Class} syntax

The base class for all syntaxes. - -A syntax object is a placeholder for many kinds of information -depending on the exact syntax, but in particular, it holds information -(in the form of two marks) about what part of the buffer was on -display after the previous invocation of the redisplay algorithm. @end deftp

-@deftp {:initarg} :pane -Indicates the pane where rendering is to take place. -@end deftp +The redisplay module exploits the syntax module for several things: + +@itemize @bullet +@item highlighting of various syntactic entities of the buffer +@item highlighting of matching parenthesis, +@item turning syntactic entities into clickable presentations, +@item marking lines with inconsistent indentation, +@item etc. +@end itemize

-All subclasses of the syntax class must support the :pane initarg. -The pane that is passed as an initarg must have a valid buffer -associated with it. +User commands can use the syntax module for:

-@deffn {Function} {redisplay-pane} pane +@itemize @bullet +@item moving point by units that are specific to a particular buffer +syntax, such as expressions, statements, or paragraphs, +@item transposing syntactic units, +@item sending the text of a syntactic unit to a language processor, +@item indenting lines according to the syntax, +@item etc. +@end itemize

-This function is called by the command loop on every pane that is on -display. It simply calls redisplay-with-syntax with the pane and the -syntax of the pane. -@end deffn +The view that the syntax module has of the buffer is updated only when +needed, and then only for the parts of the buffer that are needed. +Most syntax modules (such as for programming languages) need to +compute their representations from the beginning of the buffer up to a +particular point beyond which the structure of the buffer does not +need to be known. + +There are two situations where updating might be needed:

-@deffn {Generic Function} {redisplay-with-syntax} pane syntax +@itemize @bullet +@item before redisplay is about to show the contents of part of the +buffer in a pane. +@item as a result of a command that exploits the syntactic entities of +the buffer contents. +@end itemize + +The first case is handled by the redisplay invoking the following +generic function before proceeding to display the buffer contents in a +pane:

-Redisplay a pane using a given syntax. +@deffn {Generic Function} {update-syntax} buffer syntax mark + +Inform the syntax module that it must update its view of the buffer +contents up to the point indicated by the mark. It is acceptable to +pass an offset instead of the mark. @end deffn

-This function can behave radically differently for different syntaxes. -In all cases, however, it starts by determining the current dimensions -of the pane, and compare that to the size of the region of the buffer -that is currently on display. Adjustments are made as necessary. It -then determines whether the point of the pane is within the region on -display. If not, a new region is computed in a way that the point is -as close to the middle of the pane as possible. It is important to -maintain the region on display as much as possible, so as to avoid -unnecessary scrolling. +The second case is handled by the syntax module itself when needed in +order to correctly compute the effects of a command.

-The final step of this function is to render the region of the buffer -that is to be displayed. Some syntaxes can use simple algorithms that -simply draw everything in the region. Others can optimize so that -only the portions of the pane that have actually changed are redrawn. - -The redisplay-with-syntax function also implements parsing of the -buffer text. - -Simple parsers may be restricted to dividing the text into words, -possibly recognizing special words like URLs or email addresses, and -then using `present' to render these words. - -More complicated parsers may use incremental parsing techniques to -maintain sophisticated information of the buffer contents. Such a -parser needs to use the low-mark and high-mark to determine which -parts of the buffer have changed, and recompute parsing information as -necessary. +It is important to realize that the syntax module is not directly +involved in displaying buffer contents in a pane. In fact, the syntax +module should work even if there is no graphic user interface +present, and it should be exploitable by several, potentially totally +different, display units.

@section Common Lisp syntax

@@ -1404,6 +1404,58 @@ top element, increment the expression count of the new top entry, and perform a count check again. @end deffn + +@chapter Redisplay + +A buffer can be on display in several panes. The redisplay +algorithm is invoked on each such pane. Each pane is associated +with a distinguished mark called the `point' of the pane. The point +is a right-sticky mark independently of whether you are typing +left-to-right or right-to-left. + +@deffn {Generic Function} {redisplay-pane} pane view current-p + +This function is invoked on all panes at the end of each iteration of +the command loop. The current-p argument is a boolean that indicates +whether the pane is the one that currently has the input focus +@end deffn + +For maximum flexibility, the redisplay-pane function dispatches off of +two objects, a pane and a CLIM view. The reason for this is that the +same type of pane, such as a simple CLIM application pane, can be used +to show the buffer contents in slightly different ways: + +@itemize @bullet +@item highlighted or not, +@item highlighting tabulation characters (for makefiles) +@item showing control characters in a special font +@item etc. +@end itemize + +These minor variations are obtained by creating a special view type +and a method that dispatches on that type. + +Major differences such as the need to have pane-specific output +recording are best handled by creating a different pane type. + +The redisplay-pane function may use the current-p argument to slightly +alter the presentation such as drawing the cursor in a different +color. + +The redisplay-pane function starts by determining the current +dimensions of the pane, and compare that to the size of the region of +the buffer that is currently on display. Adjustments are made as +necessary. It then determines whether the point of the pane is within +the region on display. If not, a new region is computed in a way that +the point is as close to the middle of the pane as possible. It is +important to maintain the region on display as much as possible, so as +to avoid unnecessary scrolling. + +The final step of this function is to render the region of the buffer +that is to be displayed. Some pane types can use simple algorithms +that simply draw everything in the region. Others can optimize so +that only the portions of the pane that have actually changed are +redrawn.

@chapter The undo protocol