added documentation about redraw cycle

README.md

@@ -11,14 +11,20 @@ daign-2d-graphics lets you define 2d-graphics that can be modified through contr
 The final graphics can be output to interactive web applications with technologies like SVG or Canvas,
 but other output formats like [Ti*k*Z][tikz-url] code can also be defined.
 
+## Packages ##
+
+daign-2d-graphics is the main package of several npm packages that work together to build this project.
+[Learn more about the packages.](./docs/packages.md)
+
 ## Demo ##
 
 Here is a repository with [demo applications][demo-url].
 
 ## Documentation ##
 
-daign-2d-graphics is the main package of several npm packages that work together to build this project.
-[Learn more about the packages.](./docs/packages.md)
++ [Layers](./docs/layers.md)
++ [Control objects](./docs/control-objects.md)
++ [Redraw cycle](./docs/redraw-cycle.md)
 
 ## Installation
 

docs/control-objects.md

@@ -0,0 +1,38 @@
+# Control objects - daign-2d-graphics
+
+Control objects are the core element of a daign-2d-graphics application
+and the template for all graphical elements that the user can interact with.
+
+## Control points
+
+A control object consists of an array of control point coordinates
+and a set of instructions how to draw the desired shape based on the coordinates.
+
+A line control object for example will typically contain two control points
+for the endpoints.
+
+However not every point in the resulting shape has to be a control point.
+A rectangle control for example can also be defined by two control points for opposite corners.
+The remaining two points for the resulting shape will be calculated from those.
+
+And similarly a control point does not necessarily translate
+into a point of the resulting shape.
+For example it is possible to use a control point
+whose position will translate into the hue of the object.
+
+## Control point changes
+
+When dragging a control point the redraw is automatically executed.
+However multiple actions are executed beforehand which give you the possibility
+to react to or modify control point changes.
+
+The coordinate changes on the control point are channeled
+through the control modifiers of the control object.
+Coordinates can be adjusted at this point, even of control points which 
+were not directly targeted by the drag.
+
+After the coordinates have been channeled through the control modifiers,
+they are written back to the control object.
+This will then trigger a redraw of the control object.
+
+Afterwards the [redraw of the application](./redraw-cycle.md) is automatically executed.

docs/layers.md

@@ -0,0 +1,39 @@
+# Layers - daign-2d-graphics
+
+A daign-2d-graphics application typically consists of two layers:
+the drawing layer and the control layer.
+Unless the application is non-interactive,
+in which case there is no control layer.
+
+## Drawing layer
+
+The drawing layer contains the graphic or document that you want to draw.
+The top most object of the drawing layer is the viewport,
+which is just a group object with transformations
+that facilitate zooming and panning of the application.
+
+## Control layer
+
+The control layer shows the controls that help manipulating the graphic.
+There are three categories of elements on the control layer:
+
++ **Control points** are handles that allow manipulating the graphic.
+For example a line [control object](./control-objects.md)
+will display two handle points to manipulate the end points of the line.
++ **Button controls** are buttons and can handle click events.
++ **Control guides** for non-interactive graphical helper elements.
+
+Objects on the control layer are not affected by zooming.
+They will adjust their position according to the graphic elements below,
+but will always stay the same size.
+The main reason for this is, that handles should always be easily clickable,
+so should not scale with the zooming.
+
+## Custom layers
+
+It is possible to add further layers to the application.
+This can be useful for adding user interface objects
+that should not scale with the zooming of the graphic.
+
+However for organizing the main graphic into layers
+one should use group objects inside of the drawing layer.

docs/redraw-cycle.md

@@ -0,0 +1,56 @@
+# Redraw cycle - daign-2d-graphics
+
+In a daign-2d-graphics application some components
+will automatically keep track of changes and update themselves, and some won't.
+Here is what you need to know about bringing changes from the document to the screen.
+
+## Internal update mechanisms
+
+When adding or removing nodes to the document tree
+or when changing transformations on nodes,
+then the projection matrices are updated automatically.
+See [daign-2d-pipeline documentation](https://github.com/daign/daign-2d-pipeline/blob/master/docs/change-notifications.md).
+
+Assigning or changing class names on a StyledGraphicNode will build the style selector,
+which will be evaluated during the rendering process.
+
+## The redraw cycle
+
+A redraw of the application consists of the following steps:
+1. The redraw is requested by calling application.redraw().
+2. A redraw event is send to custom components that have subscribed to the event,
+to get informed before a redraw is executed.
+3. The control layer is redrawn.
+4. The callback to your custom render function is called.
+
+For some predefined user actions a redraw is executed automatically.
+But for most functions that you add to the application
+you will have to call the redraw yourself.
+This way you can execute multiple changes to the document
+and render the application only once when you are finished.
+
+### Automatic redraws
+
+Automatic redraws happen on the following predefined user actions:
+1. Selecting a control object.
+2. Selecting a control point.
+3. [Dragging a control point](./control-objects.md#control-point-changes).
+4. Panning or zooming the view.
+5. Clicking in an empty area to deselect.
+
+### Manual redraws
+
+In the following cases you have to call the redraw manually if needed:
+1. In the callback of a button object.
+2. When changing the selection programmatically.
+3. When changing the view programmatically, for example when calling fitToContent().
+4. After making changes to the document, e.g. appending or removing nodes from the document tree,
+changing transformations, changing style selectors.
+
+## Reacting to selection changes
+
+Normally you don't act on selection changes specifically.
+If your components should react to actions that they are not directly affected by,
+they should subscribe to the redraw event with the updateMananger.subscribeToRedrawEvent() method.
+
+However it is also possible to subscribe to the selection manager if needed.