[mcclim-cvs] CVS mcclim/Doc

Update of /project/mcclim/cvsroot/mcclim/Doc In directory clnet:/tmp/cvs-serv28429

Modified Files: Makefile Added Files: makeimages.sh mcclim.texi sheet-hierarchy.tex Removed Files: manual.tex Log Message: Converted McCLIM User's Guide to Texinfo format, but extracted one math-heavy (and not very user-oriented) chapter to an external LaTeX document (sheet-hierarchy.tex).

--- /project/mcclim/cvsroot/mcclim/Doc/Makefile 2003/07/16 17:49:39 1.3 +++ /project/mcclim/cvsroot/mcclim/Doc/Makefile 2006/11/11 15:33:21 1.4 @@ -1,11 +1,17 @@ -NAME=manual +NAME=mcclim +NAME2=sheet-hierarchy

-TEXFILES=$(NAME).tex $(shell ./tex-dependencies $(NAME).tex) +TEXFILES=$(NAME2).tex $(shell ./tex-dependencies $(NAME2).tex) PSTEX_T=$(shell ./strip-dependence inputfig $(TEXFILES)) VERBATIM=$(shell ./strip-dependence verbatimtabinput $(TEXFILES)) PSTEX=$(subst .pstex_t,.pstex,$(PSTEX_T)) +IMAGES=ex2.eps inspect-as-cells.eps inspect-object-1.eps \ +inspect-object-2.eps inspect-object-3.eps native.fig +IMAGETARGETTYPES=gif png eps +TARGETIMAGES=$(shell sh ./makeimages.sh -e "$(IMAGES)" "$(IMAGETARGETTYPES)") +TEXIFILES=$(NAME).texi

-all : $(NAME).ps +all : $(NAME).ps $(NAME2).ps

%.pstex: %.fig fig2dev -Lpstex -m 0.75 $< $@ @@ -13,12 +19,24 @@ %.pstex_t: %.fig %.pstex fig2dev -Lpstex_t -m 0.75 -p $(basename $<).pstex $< $@

-$(NAME).dvi: $(TEXFILES) $(PSTEX_T) $(VERBATIM) +$(NAME).dvi: $(TEXIFILES) $(TARGETIMAGES) + texi2dvi $(NAME).texi + +$(NAME2).dvi: $(NAME2).tex $(PSTEX_T) $(VERBATIM) latex $< -# makeindex $(NAME) + makeindex $(NAME) latex $<

-$(NAME).ps: $(NAME).dvi $(PSTEX) +$(TARGETIMAGES): + sh ./makeimages.sh "$(IMAGES)" "$(IMAGETARGETTYPES)" + +$(NAME).html: $(TEXIFILES) + makeinfo --html $< + +$(NAME).ps: $(NAME).dvi + dvips $< -o + +$(NAME2).ps: $(NAME2).dvi $(PSTEX) dvips $< -o

view: $(NAME).ps @@ -29,5 +47,5 @@

spotless: make clean - rm -f *.ps *.dvi *.pstex *.pstex_t *.toc *.idx *.ilg *.ind - + rm -f *.ps *.dvi *.pstex *.pstex_t *.toc *.idx *.ilg *.ind *pdf \ +*ky *pg *tmp *tp *tps *vr *fn *fns *info

--- /project/mcclim/cvsroot/mcclim/Doc/makeimages.sh 2006/11/11 15:33:21 NONE +++ /project/mcclim/cvsroot/mcclim/Doc/makeimages.sh 2006/11/11 15:33:21 1.1 #!/bin/sh

# Go through a list of image files and make sure that a version of # each image exists in every format specified by a list of file # types. Uses ImageMagick. If first argument is -e, to not convert, # but print a list of the files that are supposed to exist after the # script has run. if [ "$1" == "-e" ]; then NOCREATE="true" IMAGES="$2" IMAGETARGETTYPES="$3" else IMAGES=$1 IMAGETARGETTYPES=$2 fi

for FILE in $IMAGES; do if [ -f "$FILE" ]; then RAWFILE=${FILE%.*} for TYPE in $IMAGETARGETTYPES; do FILETOMAKE=$RAWFILE.$TYPE if [ "$NOCREATE" == "true" ]; then echo $FILETOMAKE else if [ ! -f "$FILETOMAKE" ]; then convert $FILE $FILETOMAKE fi fi done else echo The file $FILE does not exist. fi done--- /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi 2006/11/11 15:33:21 NONE +++ /project/mcclim/cvsroot/mcclim/Doc/mcclim.texi 2006/11/11 15:33:21 1.1 % @c -*- Coding: utf-8; Mode: Texinfo -*- % @c Note that Texinfo does not support UTF-8. Please do not use literal % @c UTF-8 characters in this document. \input texinfo

@setfilename mcclim @settitle McCLIM User's Manual

@set MCCLIMVERSION 0.9.3

@copying Copyright @copyright{} 2004,2005,2006 the McCLIM hackers. @end copying

@dircategory Common Lisp @direntry * McCLIM User's Manual: (mcclim). A free implementation of CLIM. @end direntry

@titlepage @title{McCLIM User's Manual}

@sp 5 @center @titlefont{The Users Guide} @sp 2 @center @titlefont{and} @sp 2 @center @titlefont{API Reference} @sp 2

@page @vskip 0pt plus 1filll @insertcopying

@end titlepage

@iftex @contents @end iftex

@macro glossentry{ENTRY} @b{\ENTRY} @cindex \ENTRY\ @end macro

@macro func{NAME} @t{\NAME} @findex \NAME\ @end macro

@macro fmacro{MACRO} @func{\MACRO} @end macro

@macro genfun{FUN} @func{\FUN} @end macro

@alias gloss = i @alias class = t @alias gadget = t @alias pane = t @alias initarg = t @alias methcomp = t @alias slot = t @alias longref = t @alias cl = t @alias initarg = t

@ifnottex @node Top @top McCLIM User's Manual @insertcopying @end ifnottex

@menu * Introduction::

Getting started * CLIM Demos and Applications:: * The First Application:: * Using presentation types::

User Manual * Using views:: * Using command tables::

Reference Manual * Concepts:: * Windowing system drawing functions:: * CLIM drawing functions:: * Panes:: * Output Protocol:: * Command Processing::

Extensions * Output Protocol Extensions:: * Output Recording Extensions:: * Drawing Two-Dimensional Images:: * File Selector Gadget:: * PostScript Backend::

Utility Programs * Listener:: * Inspector::

Auxilliary Material * Glossary:: * Development History::

Index * Concept Index:: * Function Index:: @end menu

@node Introduction @chapter Introduction @cindex Ehtoota

CLIM is a large layered software system that allows the user to customize it at each level. The most simple ways of using CLIM is to directly use its top layer, which contains application frames, panes, and gadgets, very similar to those of traditional windowing system toolkits such as GTK, Tk, and Motif.

But there is much more to using CLIM. In CLIM, the upper layer with panes and gadgets is written on top of a basic layer containing more basic functionality in the form of sheets. Objects in the upper layer are typically instances of classes derived from those of the lower layer. Thus, nothing prevents a user from adding new gadgets and panes by writing code that uses the sheet layer.

Finally, since CLIM is written in Common Lisp, essentially all parts of it can be modified, replaced, or extended.

For that reason, a user's manual for CLIM must contain not only a description of the protocols of the upper layer, but also of all protocols, classes, functions, macros, etc. that are part of the specification.

@menu * Standards:: * How CLIM Is Different:: @end menu

@node Standards @section Standards

This manual documents McCLIM @value{MCCLIMVERSION} which is a mostly complete implementation of the CLIM 2.0 specification and its revision 2.2. To our knowledge version~2.2 of the CLIM specification is only documented in the ``CLIM 2 User's Guide'' by Franz. While that document is not a formal specification, it does contain many cleanups and is often clearer than the official specification; on the other hand, the original specification is a useful reference. This manual will note where McCLIM has followed the 2.2 API. @cindex Specification

Also, some protocols mentioned in the 2.0 specification, such as parts of the incremental redisplay protocol, are clearly internal to CLIM and not well described. It will be noted here when they are partially implemented in McCLIM or not implemented at all.

@node How CLIM Is Different @section How CLIM Is Different

Many new users of CLIM have a hard time trying to understand how it works and how to use it. A large part of the problem is that many such users are used to more traditional GUI toolkits, and they try to fit CLIM into their mental model of how GUI toolkits should work.

But CLIM is much more than just a GUI toolkit, as suggested by its name, it is an @emph{interface manager}, i.e. it is a complete mediator between application ``business logic'' and the way the user interacts with objects of the application. In fact, CLIM doesn't have to be used with graphics output at all, as it contains a large collection of functionality to manage text. @cindex Interface manager

Traditional GUI toolkits have an @emph{event loop}. @cindex Event loop Events are delivered to GUI elements called @emph{gadgets} (or @emph{widgets}), and the programmer attaches @emph{event handlers} to those gadgets in order to invoke the functionality of the application logic. While this way of structuring code is sometimes presented as a virtue (``Event-driven programming''), it has an unfortunate side effect, namely that event handlers are executed in a null context, so that it becomes hard to even remember two consecutive events. The effect of event-driven programming is that applications written that way have very rudimentary interaction policies.

At the lowest level, CLIM also has an event loop, but most application programmers never have any reason to program at that level with CLIM. Instead, CLIM has a @emph{command loop} @cindex Command loop at a much higher level than the event loop. At each iteration of the command loop:

@enumerate @item A command is acquired. You might satisfy this demand by clicking on a menu item, by typing the name of a command, by hitting some kind of keystroke, by pressing a button, or by pressing some visible object with a command associated with it; @item Arguments that are required by the command are acquired. Each argument is often associated with a @emph{presentation type}, and visible objects of the right presentation type can be clicked on to satisfy this demand. You can also type a textual representation of the argument, using completion, or you can use a context menu; @item The command is called on the arguments, usually resulting in some significant modification of the data structure representing your application logic; @item A @emph{display routine} is called to update the views of the application logic. The display routine may use features such as incremental redisplay. @end enumerate

Instead of attaching event handlers to gadgets, writing a CLIM application therefore consists of:

@itemize @bullet @item writing CLIM commands that modify the application data structures independently of how those commands are invoked, and which may take application objects as arguments; @item writing display routines that turn the application data structures (and possibly some "view" object) into a collection of visible representations (having presentation types) of application objects; @item writing completion routines that allow you to type in application objects (of a certain presentation type) using completions; @item independently deciding how commands are to be invoked (menus, buttons, presentations, textual commands, etc). @end itemize

By using CLIM as a mediator of command invocation and argument acquisition, you can obtain some very modular code. Application logic is completely separate from interaction policies, and the two can evolve separately and independently.

@c @node Getting Started @c @part Getting Started

@node CLIM Demos and Applications @chapter CLIM Demos and Applications @cindex Demo applications

@menu * Running the Demos:: * McCLIM Installation and Usage Tips:: @end menu

@node Running the Demos @section Running the Demos

The McCLIM source distribution comes with a number of demos and applications. They are intended to showcase specific CLIM features, demonstrate programming techniques or provide useful tools.

These demos and applications are available in the @t{Examples} and @t{Apps} subdirectories of the source tree's root directory. Instructions for compiling, loading and running some of the demos are included in the files with the McCLIM installation instructions for your Common Lisp implementation. See for example the file @t{INSTALL} if you use Allegro CL, @t{INSTALL.CMU} for CMUCL, @t{INSTALL.OPENMCL} for OpenMCL, and so on.

Below is a complete list of the McCLIM demos and applications, sorted in alphabetical order. Each entry provides a short description of what the program does, with instructions for compiling and running it if not mentioned in the general installation instructions.

@table @t @item Apps/Listener CLIM-enabled Lisp listener. See the compilation and execution instructions in @t{Apps/Listener/README}. @item Examples/address-book.lisp Simple address book. See McCLIM's installation instructions. @item Examples/calculator.lisp Simple desk calculator. See McCLIM's installation instructions. @item Examples/clim-fig.lisp Simple paint program. You can run it by evaluating this form at the Lisp prompt: @lisp (clim-demo::clim-fig) @end lisp @item Examples/colorslider.lisp Interactive color editor. See McCLIM's installation instructions. @item Examples/demodemo.lisp Demonstrates different pane types. You can compile it by evaluating: @lisp (compile-file "Examples/demodemo.lisp") @end lisp Then load it with: @lisp (load "Examples/demodemo") @end lisp Finally, run it with: @lisp (clim-demo::demodemo) @end lisp @item Examples/goatee-test.lisp Text editor with Emacs-like key bindings. See McCLIM's installation instructions. @item Examples/menutest.lisp Displays a window with a simple menu bar. See McCLIM's installation instructions. @item Examples/postscript-test.lisp Displays text and graphics to a PostScript file. Run it with: @lisp (clim-demo::postscript-test) @end lisp The resulting file @t{ps-test.ps} is generated in the current directory and can be displayed by a PostScript viewer such as @t{gv} on Unix-like systems. @item Examples/presentation-test.lisp Displays an interactive window in which you type numbers that are successively added. When a number is expected as input, you can either type it at the keyboard, or click on a previously entered number. Run it with: @lisp (clim:run-frame-top-level (clim:make-application-frame 'clim-demo::summation)) @end lisp @item Examples/sliderdemo.lisp Apparently a calculator demo (see above). Compile with: @lisp (compile-file "Examples/sliderdemo.lisp") @end lisp Load with: @lisp (load "Examples/sliderdemo") @end lisp Run with: @lisp (clim-demo::slidertest) @end lisp @item Examples/stream-test.lisp Interactive command processor that echoes its input. Run with: @lisp (clim-demo::run-test) @end lisp @end table

The following programs are currently @b{known not to work}: @itemize @bullet @item @t{Examples/fire.lisp} @item @t{Examples/gadget-test-kr.lisp} @item @t{Examples/gadget-test.lisp} @item @t{Examples/puzzle.lisp} @item @t{Examples/traffic-lights.lisp} @item @t{Examples/transformations-test.lisp} @end itemize

@node McCLIM Installation and Usage Tips @section McCLIM Installation and Usage Tips

[1945 lines skipped] --- /project/mcclim/cvsroot/mcclim/Doc/sheet-hierarchy.tex 2006/11/11 15:33:21 NONE +++ /project/mcclim/cvsroot/mcclim/Doc/sheet-hierarchy.tex 2006/11/11 15:33:21 1.1

[2451 lines skipped]