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}