[mcclim-cvs] CVS update: mcclim/Doc/ex2c.lisp mcclim/Doc/manual.tex

[Robert Strandh]

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

Modified Files:
	manual.tex 
Added Files:
	ex2c.lisp 
Log Message:
Added example using incremental redisplay.

Date: Sun Aug 14 08:20:13 2005
Author: rstrandh



Index: mcclim/Doc/manual.tex
diff -u mcclim/Doc/manual.tex:1.29 mcclim/Doc/manual.tex:1.30
--- mcclim/Doc/manual.tex:1.29	Sun Aug 14 06:32:38 2005
+++ mcclim/Doc/manual.tex	Sun Aug 14 08:20:12 2005
@@ -403,6 +403,25 @@
 must have an option of \texttt{:name t}.  The reason is that some
 commands will be available only from menus or by some other mechanism. 
 
+You may notice that if the output of the application is hidden (say by
+the window of some other application) and then re-exposed, the output
+reappears normally, without any intervention necessary on the part of
+the programmer.  This effect is accomplished by a CLIM mechanism
+called \emph{output recording}.  Essentially, every piece of output is
+not only displayed in the pane, but also captured in an \emph{output
+  record} associated with the pane.  When a pane is re-exposed, its
+output records are consulted and if any of them overlap the
+re-exposed region, they are redisplayed.  In fact, some others may be
+redisplayed as well, because CLIM guarantees that the effect will be
+the same as when the initial output was created.  It does that by
+making sure that the order between (partially) overlapping output
+records is respected.  
+
+Not all panes support output recording, but certainly application
+panes do, so it is good to use some subclass of
+\texttt{application-pane} to display application-specific object,
+because output recording is then automatic. 
+
 \section{An application displaying a data structure}
 
 Many applications use a central data structure that is to be on
@@ -448,6 +467,73 @@
 the value of a single number (or \texttt{NIL}), but you could think of
 this as displaying all the objects that have been drawn in some figure
 drawing program or displaying all the entries in an address book. 
+
+\section{Incremental redisplay}
+
+While the example in the previous section is a very simple way of
+structuring an application (let commands arbitrarily modify the data
+structure, and simply erase the pane and redisplay the structure after
+each iteration of the command loop), the visual result is not so great
+when many objects are to be displayed.  There is most often a
+noticeable flicker between the moment when the pane is cleared and the
+objects are drawn.  Sometimes this is inevitable (as when nearly all
+objects change), but most of the time, only an incremental
+modification has been made, and most of the objects are still in the
+same place as before. 
+
+In simple toolkits, the application programmer would have to figure
+out what has changed since the previous display, and only display the
+differences.  CLIM offers a mechanism called \emph{incremental
+  redisplay} that automates a large part of this task.  As we
+mentioned earlier, CLIM captures output in the form of \emph{output
+  records}.  The same mechanism is used to obtain incremental
+redisplay.
+
+To use incremental redisplay, Client code remains structured in the
+simple way that was mention above: after each iteration of the command
+loop, the display function output the entire data structure as usual,
+except that it helps the incremental redisplay mechanism by telling
+CLIM which piece of output corresponds to which piece of output during
+the previous iteration of the command loop.  It does this by giving
+some kind of \emph{unique identity} to some piece of output, and some
+means of indicating whether the contents of this output is \emph{the
+  same} as it was last time.  With this information, the CLIM
+incremental redisplay mechanism can figure out whether some output is
+new, has disappeared, or has been moved, compared to the previous
+iteration of the command loop.  As with re-exposure, CLIM guarantees
+that the result is identical to that which would have been obtained,
+had all the output records been output in order to a blank pane. 
+
+The next example illustrates this idea.  It is a simple application
+that displays a fixed number (here 20) of lines, each line being a
+number.  Here is the code: 
+
+\verbatimtabinput{ex2c.lisp}
+
+We store the numbers in a slot called \texttt{numbers} of the
+application frame.  However, we store each number in its own list.
+This is a simple way to provide a unique identity for each number.  We
+could not use the number itself, because two numbers could be the same
+and the identities would not be unique.  Instead, we use the cons cell
+that store the number as the unique identity.  By using
+\texttt{:id-test \#'eq} we inform CLIM that it can figure out whether
+an output record is the same as one that was issued previous time by
+using the function \texttt{eq} to compare them.  But there is a second
+test that has to be verified, namely whether an output record that was
+issued last time has to be redisplayed or not.  That is the purpose of
+the cache-value.  Here we use the number itself as the cache value and
+\texttt{eql} as the test to determine whether the output is going to
+be the same as last time. 
+
+For convenience, we display a \texttt{*} at the beginning of the
+current line, and we provide two commands \texttt{next} and
+\texttt{previous} to navigate between the lines.  
+
+Notice that in the declaration of the pane in the application frame,
+we have given the option \texttt{:incremental-redisplay t}.  This
+informs CLIM not to clear the pane after each command-loop iteration,
+but to keep the output records around and compare them to the new ones
+that are produced during the new iteration. 
 
 \chapter{Using presentation types}