[mcclim-cvs] CVS mcclim/Doc

[rstrandh]

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

Modified Files:
	manual.tex 
Added Files:
	views.lisp 
Log Message:
Added a new part (User manual) to the manual, and a first chapter 
(Using views) to that part. 


--- /project/mcclim/cvsroot/mcclim/Doc/manual.tex	2005/08/22 02:49:05	1.31
+++ /project/mcclim/cvsroot/mcclim/Doc/manual.tex	2006/10/30 06:26:53	1.32
@@ -607,6 +607,78 @@
 What is finally displayed (in the interactor pane, which is the
 standard input of the frame), is ``the 15 of The third month''.
 
+\part{User Manual}
+
+\chapter{Using views}
+
+The CLIM specification mentions a concept called a \emph{view}, and
+also lists a number of predefined views to be used in various
+different contexts.  
+
+In this chapter we show how the \emph{view} concept can be used in
+some concrete programming examples.  In particular, we show how to use
+a single pane to show different views of the application data
+structure at different times.  To switch between the different views,
+we supply a set of commands that alter the
+\texttt{stream-default-view} feature of all CLIM extended output
+streams.
+
+The example shown here has been stripped to a bare minimum in order to
+illustrate the important concepts.  A more complete version can be
+found in \texttt{Examples/views.lisp} in the McCLIM source tree. 
+
+Here is the example:
+
+\verbatimtabinput{views.lisp}
+
+The example shows a stripped-down example of a simple database of
+members of some organization.
+
+The main trick used in this example is the \texttt{display-main-pane}
+function that is declared to be the display function of the main pane
+in the application frame.  The \texttt{display-main-pane} function
+trampolines to a generic function called
+\texttt{display-pane-with-view}, and which takes an additional
+argument compared to the display functions of CLIM panes.  This
+additional argument is of type \texttt{view} which allows us to
+dispatch not only on the type of frame and the type of pane, but also
+on the type of the current default view.  In this example the view
+argument is simply taken from the default view of the pane.
+
+A possibility that is not obvious from reading the CLIM specification
+is to have views that contain additional slots.  Our example defines
+two subclasses of the CLIM \texttt{view} class, namely
+\texttt{members-view} and \texttt{person-view}.  
+
+The first one of these does not contain any additional slots, and is
+used when a global view of the members of our organization is wanted.
+Since no instance-specific data is required in this view, we follow
+the idea of the examples of the CLIM specification to instantiate a
+singleton of this class and store that singleton in the
+\texttt{stream-default-view} of our main pane whenever a global view
+of our organization is required.
+
+The \texttt{person-view} class, on the other hand, is used when we
+want a closer view of a single member of the organization.  This class
+therefore contains an additional slot which holds the particular
+person instance we are interested in.  The method on
+\texttt{display-pane-with-view} that specializes on
+\texttt{person-view} displays the data of the particular person that
+is contained in the view.  
+
+To switch between the views, we provide two commands.  The command
+\texttt{com-show-all} simply changes the default view of the main pane
+to be the singleton instance of the \texttt{members-view} class.  The
+command \texttt{com-show-person} is more complicated.  It takes an
+argument of type person, creates an instance of the
+\texttt{person-view} class initialized with the person that was passed
+as an argument, and stores the instance as the default view of the
+main pane. 
+
+\chapter{Using command tables}
+
+(to be filled in)
+
 \part{Reference Manual}
 
 \chapter{Concepts}

--- /project/mcclim/cvsroot/mcclim/Doc/views.lisp	2006/10/30 06:26:53	NONE
+++ /project/mcclim/cvsroot/mcclim/Doc/views.lisp	2006/10/30 06:26:53	1.1
;;; part of application "business logic"
(defclass person ()
  ((%last-name :initarg :last-name :accessor last-name)
   (%first-name :initarg :first-name :accessor first-name)
   (%address :initarg :address :accessor address)
   (%membership-number :initarg :membership-number :reader membership-number)))

;;; constructor for the PERSON class.  Not strictly necessary. 
(defun make-person (last-name first-name address membership-number)
  (make-instance 'person 
                 :last-name last-name 
                 :first-name first-name
                 :address address
                 :membership-number membership-number))

;;; initial list of members of the organization we imagine for this example
(defparameter *members*
  (list (make-person "Doe" "Jane" "123, Glencoe Terrace" 12345)
        (make-person "Dupont" "Jean" "111, Rue de la Republique" 54321)
        (make-person "Smith" "Eliza" "22, Trafalgar Square" 121212)
        (make-person "Nilsson" "Sven" "Uppsalagatan 33" 98765)))

;;; the CLIM view class that corresponds to a list of members, one member
;;; per line of text in a CLIM application pane. 
(defclass members-view (view) ())

;;; since this view does not take any parameters in our simple example,
;;; we need only a single instance of it. 
(defparameter *members-view* (make-instance 'members-view))

;;; the application frame.  It contains instance-specific data
;;; such as the members of our organization. 
(define-application-frame views ()
  ((%members :initform *members* :accessor members))
  (:panes
   (main-pane :application :height 500 :width 500
              :display-function 'display-main-pane
              ;; notice the initialization of the default view of
              ;; the application pane. 
              :default-view *members-view*)
   (interactor :interactor :height 100 :width 500))
  (:layouts
   (default (vertically ()
              main-pane
              interactor))))

;;; the trick here is to define a generic display function
;;; that is called on the frame, the pane AND the view, 
;;; whereas the standard CLIM display functions are called 
;;; only on the frame and the pane.
(defgeneric display-pane-with-view (frame pane view))

;;; this is the display function that is called in each iteration
;;; of the CLIM command loop.  We simply call our own, more elaborate
;;; display function with the default view of the pane. 
(defun display-main-pane (frame pane)
  (display-pane-with-view frame pane (stream-default-view pane)))

;;; now we can start writing methods on our own display function
;;; for different views.  This one displays the data each member
;;; on a line of its own.
(defmethod display-pane-with-view (frame pane (view members-view))
  (loop for member in (members frame)
        do (with-output-as-presentation 
               (pane member 'person)
             (format pane "~a, ~a, ~a, ~a~%"
                     (membership-number member)
                     (last-name member)
                     (first-name member)
                     (address member)))))

;;; this CLIM view is used to display the information about
;;; a single person.  It has a slot that indicates what person
;;; we want to view. 
(defclass person-view (view)
  ((%person :initarg :person :reader person)))

;;; this method on our own display function shows the detailed 
;;; information of a single member. 
(defmethod display-pane-with-view (frame pane (view person-view))
  (let ((person (person view)))
    (format pane "Last name: ~a~%First Name: ~a~%Address: ~a~%Membership Number: ~a~%"
            (last-name person)
            (first-name person)
            (address person)
            (membership-number person))))

;;; entry point to start our applciation
(defun views-example ()
  (run-frame-top-level (make-application-frame 'views)))

;;; command to quit the application 
(define-views-command (com-quit :name t) ()
  (frame-exit *application-frame*))

;;; command to switch the default view of the application pane
;;; (which is the value of *standard-output*) to the one that
;;; shows a member per line. 
(define-views-command (com-show-all :name t) ()
  (setf (stream-default-view *standard-output*) *members-view*))
    
;;; command to switch to a view that displays a single member. 
;;; this command takes as an argument the person to display.  
;;; In this application, the only way to satisfy the demand for
;;; the argument is to click on a line of the members view.  In 
;;; more elaborate application, you might be able to type a
;;; textual representation (using completion) of the person. 
(define-views-command (com-show-person :name t) ((person 'person))
  (setf (stream-default-view *standard-output*)
        (make-instance 'person-view :person person)))