Update of /project/mcclim/cvsroot/mcclim/Doc
In directory clnet:/tmp/cvs-serv22828
Modified Files:
mcclim.texi
Log Message:
Added a section on how CLIM applications produce output.
--- /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi 2007/01/06 05:00:17 1.5
+++ /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi 2007/01/06 05:27:53 1.6
@@ -418,6 +418,7 @@
@cindex writing an application
@menu
+* How CLIM applications produce output::
* Panes and Gadgets::
* Defining Application Frames::
* A First Attempt::
@@ -427,6 +428,84 @@
* Incremental redisplay::
@end menu
+@node How CLIM applications produce output
+@section How CLIM applications produce output
+
+CLIM stream panes use output recording. This means that such a pane
+maintains a display list, consisting of a sequence of output records,
+ordered chronologically, from the first output record to be drawn to
+the last.
+
+This display list is used to fill in damaged areas of the pane, for
+instance as a result of the pane being partially or totally covered by
+other panes, and then having some or all of its area again becoming
+visible. The output records of the display list that have some parts
+in common with the exposed area are partially or totally replayed (in
+chronological order) to redraw the contents of the area.
+
+An application can have a pane establish this display list in several
+fundamentally different ways.
+
+Very simple applications have no internal data structure to keep track
+of application objects, and simply produce output to the pane from
+time to time as a result of running commands, occasionally perhaps
+erasing the pane and starting over. Such applications typically use
+text or graphics output as a result of running commands. CLIM
+maintains the display list for the pane, and adds to the end of it,
+each time also producing the pixels that result from drawing the new
+output record. If the pane uses scrolling (which it typically does),
+then CLIM must determine the extent of the pane so as to update the
+scroll bar after each new output.
+
+More complicated applications use a display function. Before the
+display function is run, the existing display list is typically
+deleted, so that the purpose of the display function becomes to
+establish an entirely new display list. The display function might
+for instance produce some kind of form to be filled in, and
+application commands can use text or graphics operations to fill in
+the form. A game of tic-tac-toe could work this way, where the
+display function draws the board and commands draw shapes into the
+squares.
+
+Even more complicated applications might have some internal data
+structure that has a direct mapping to output, and commands simply
+modify this internal data structure. In this case, the display
+function is run after each time around the command loop, because a
+command can have modified the internal data structure in some
+arbitrary ways. Some such applications might simply want to delete
+the existing display list and produce a new one each time (to minimize
+flicker, double buffering could be used). This is a very simple way
+of structuring an application, and entirely acceptable in many cases.
+Consider, for instance, a board game where pieces can be moved (as
+opposed to just added). A very simple way of structuring such an
+application is to have an internal representation of the board, and to
+make the display function traverse this data structure and produce the
+complete output each time in the command loop.
+
+Some applications have very large internal data structures to be
+displayed, and it would cause a serious performance problem if the
+display list had to be computer from scratch each time around the
+command loop. To solve this problem, CLIM contains a feature called
+incremental redisplay. It allows many of the output records to be
+kept from one iteration of the command loop to the next. This can be
+done in two different ways. The simplest way is for the application
+to keep the simple structure which consists of traversing the entire
+data structure each time, but at various points indicate to CLIM that
+the output has not changed since last time, so as to avoid actually
+invoking the application code for computing it. This is accomplished
+by the use of @t{updating-output}. The advantage of
+@t{updating-output} is that the application logic remains
+straightforward, and it is up to CLIM to do the hard work of recycling
+output records. The disadvantage is that for some very demanding
+applications, this method might not be fast enough.
+
+The other way is more complicated and requires the programmer to
+structure the application differently. Essentially, the application
+has to keep track of the output records in the display list, and
+inform CLIM about modifications to it. The main disadvantage of this
+method is that the programmer must now write the application to keep
+track of the output records itself, as opposed to leaving it to CLIM.
+
@node Panes and Gadgets
@section Panes and Gadgets