[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    branches/kolourpaint/control/devel-doc/code-walk-thru/views
From:       Clarence Dang <dang () kde ! org>
Date:       2007-10-22 9:44:53
Message-ID: 1193046293.671943.11826.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 728070 by dang:

Clean up


 M  +118 -25   README.txt  


--- branches/kolourpaint/control/devel-doc/code-walk-thru/views/README.txt #728069:728070
@@ -1,39 +1,132 @@
 
-Views
-~~~~~
+views/ Package.
 
-The source code is stored in the views/ folder.  There can be 1 or more
-views per kpDocument document.
 
-ACTION: These classes are badly designed because subclasses limit
-functionality instead of increasing it.  We need to tip the inheritance
-hierarchy upside-down.
+Widgets for visualizing kpDocument.
 
-TODO: class diagram
 
+1. Inheritance Hierarchy
+2. views/
+3. views/manager/
 
 
+1. Inheritance Hierarchy
+~~~~~~~~~~~~~~~~~~~~~~~~
 
+                  kpView
+                  ^    ^
+                 /      \
+               /          \
+             /              \
+    kpZoomedView         kpThumbnailView
+                             ^    ^
+                            /      \
+                          /          \
+                        /              \
+      kpUnzoomedThumbnailView    kpZoomedThumbnailView
 
-View depends on existence of document - for simplicty.
-For instance, views pass on mouse events to tools which assume existence.
-If you destroy document, you must kill view first.
-setDocument() kills view and doc and creates doc and view.
 
-Exception is kpView::deleteLater():
-r385274 | dang | 2005-02-02 22:08:27 +1100 (Wed, 02 Feb 2005) | 21 lines
 
-* kpView: fix crash on access to deleted kpDocument in paintEvent()
-          due to kpMainWindow::setDocument(0) calling
-          "kpThumbnailView->deleteLater()" - thumbnailView was alive
-          even after document had died.  Used QGuardedPtr.
-          Crash can be reproduced by
-          opening a document, switching to brush tool, opening thumbnail,
-          zooming to 800%, then CTRL+W (close).
-          This only goes to show that deleteLater(),
-QTimer::singleShot(0,...)
-          and other event loop tricks only cause trouble.
+2. views/
+~~~~~~~~~
 
-which is why kpView uses a guardded pointer to document.
+[>>>] kpView
 
+Abstract base class for all views.
 
+A view is a widget that renders a possibly zoomed onscreen representation
+of a kpDocument.
+
+1 view corresponds to 1 document.
+1 document corresponds to 0 or more views.
+
+Views are created by kpMainWindow.  kpViewManager signals each view to
+update.  External classes generally use the interface provided by kpView
+and rarely need to use subclass-specific interfaces.
+
+kpView can also:
+
+1. Display contents offset by an origin
+2. Display a grid
+3. Display a "thumbnail rectangle"
+4. Transform to-and-from document coordinates
+
+View events (e.g. mouse press) are forwarded to the currently selected
+kpTool.
+
+All the painting code is located in the kpView base, not the subclasses.
+
+Each view depends on the existence of the document -- for simplicity.  If
+you want to destroy the kpDocument it's observing, you must destroy the
+view first.  Due to deleteLater() being used on kpView, this deletion
+order is briefly violated -- hence the need for QPointer in kpView.
+
+
+[>>>] kpZoomedView
+
+Concrete zoomed view of a document, used as the main view in KolourPaint.
+
+It resizes according to the size of the document and the zoom level.
+
+Derived from kpView.  Created by kpMainWindow::setDocument().
+
+
+[>>>] kpThumbnailView
+
+Abstract base class for all thumbnail views.  Derived from kpView.
+
+Created by kpMainWindow and placed into a kpThumbnail window.
+
+
+[>>>] kpUnzoomedThumbnailView
+
+Concrete unzoomed thumbnail view of a document, dervied from
+kpThumbnailView.  Unlike kpZoomedThumbnailView, it never changes the zoom
+level.  And unlike kpZoomedView, it never resizes itself.  Instead, it
+changes its origin according to the main view's scrollable container so
+that the top-left most document pixel displayed in the kpMainWindow's
+kpViewScrollableContainer will be visible.
+
+
+[>>>] kpZoomedThumbnailView
+
+Concrete zoomed thumbnail view of a document, derived from
+kpThumbnailView.  Unlike kpZoomedView, it never resizes itself.  Instead,
+it changes its zoom level to accommodate the display of entire document
+in the view, while maintaining aspect.
+
+
+3. views/manager/
+~~~~~~~~~~~~~~~~~
+
+[>>>] kpViewManager
+
+1 kpViewManager is created by each kpMainWindow and stores pointers to
+kpView's, each created by that kpMainWindow.
+
+Functionality includes:
+
+1. Determining which view the mouse cursor is under.
+
+2. Setting the mouse cursor shape for all views.
+
+3. Keeping track of the current kpTempImage, as set by kpTool's and
+   queried by the kpView painting code.
+
+4. If a kpSelection is active, keeping track of the appearance of
+   the selection border, as set by kpTool's and queried by kpView
+   painting code.  Only a maximum of 1 of kpSelection and kpTempImage
+   are allowed to exist simultaneously.
+
+5. If a kpTextSelection is active, keeping track of the artificial text
+   cursor and periodically asking the views to update it.
+
+6. Controls the timing and speed of updates.  See setQueueUpdates() and
+   setFastUpdates().
+
+7. Updates arbitrary regions in all of the views.
+   kpMainWindow::setDocument() connects kpDocument's contentsChanged()
+   signal to kpViewManager's updateViews(), so that all document changes
+   are automatically reflected in the view.  Consecutive
+   document modifications should be wrapped with a
+   setQueueUpdates()/restoreQueueUpdates() block for efficiency.
[prev in list] [next in list] [prev in thread] [next in thread]