[Kst] extragear/graphics/kst/devel-docs

[George Staikos]

SVN commit 515729 by staikos:

update this document and stress things that apparently are not coming through


 M  +16 -17    viewdesign.txt  


--- trunk/extragear/graphics/kst/devel-docs/viewdesign.txt #515728:515729
@@ -3,17 +3,16 @@
 The current view is designed as a set of classes called "view objects" which
 inherit from KstViewObject and contain properties as well as pointers to their
 children.  Their properties are generally quantities relative to their parent
-objects, though ideally, and eventually entirely in practice, they do not know
-their parent(s) and may have 0, 1, or more parents.  They also do not know how
-they are displayed, or even if they are displayed.  They must only react to
-events or commands sent by others.
+objects, though ideally they do not depend on their parent's properties more
+than necessary.  They also do not know how they are displayed, or even if they
+are displayed.  They must only react to events or commands sent by others.
 
 
-
-- Referring to the parent is bad, and should be avoided in all cases
-- Assumption of a number of parents is bad
 - Events pass in a view pointer, but generally, there is no single "view"
-- Walk the tree only when necessary, and only ever walk down!
+- Painting must -only- happen in the paintSelf() function.  Anything else is
+  wrong and will break eventually.
+- Updating must only happen in update() and updateSelf().  Anything else is
+  wrong and will break eventually.
 - All KstViewObjects are KstSharedPtrs.  Again, as documented in the threading
   documentation, they must ALWAYS be referred to in KstSharedPtr<Class> form!
   If you don't do this, you will break these objects in multithreaded
@@ -21,13 +20,13 @@
   deleted memory.
 - You must use locking, though we presently only use these objects from one
   thread so locking is not used yet.
-- Properties should be relative to the parent (not all are yet, but they will
-  be)
+- Properties should be relative to the parent
 - Avoid unnecessary redraws, use a KstBackBuffer.  Eventually KstBackBuffer
   will need to be enhanced to provide multiple backends.
 - KstTopLevelView is the only object that has a pointer to the view because it
   is by definition an object that represents a view.
-- Objects must provide serialization so they can be packaged for XDND
+- Objects must provide serialization so they can be packaged for undo, drag
+  and drop, and more.  They must be self-contained.
 - Do not store widgets or pointers to widgets beyond the life of an "operation"
   They are effectively invalid after that time.  For instance, you can store
   the view pointer while waiting for a menu selection, but do not store the
@@ -40,11 +39,11 @@
   causes far too many of them.  For instance, if you want to move up-left in a
   2D plot and the moveUp() and moveLeft() functions both draw(), you get 2
   redraws where you only needed one.
+- View objects are meant to be modular and eventually will be loaded as plugins
+  to provide additional functionality on demand.  No higher-level should know
+  about a view object.  Making an object such as KstApp know about a view object
+  is completely wrong.  Do not do it.  Period.  Even KstDoc will eventually lose
+  all knowledge of specific objects, as will KstTopLevelView.  The factories
+  provide everything that is needed.
 
 
-Remember, view objects are a tree where you can only look down.  You don't see
-your siblings or your ancestors, except in terms of a given view.  You don't
-see a view until it is explicitly passed to you during an event.
-
-
-