diff --git a/documentation/src/api_navigation.rst b/documentation/src/api_navigation.rst index 86e586d..55b512e 100644 --- a/documentation/src/api_navigation.rst +++ b/documentation/src/api_navigation.rst @@ -1,12 +1,42 @@ Navigation ---------- + +The cairo library can both move the origin and the current point from +which the next line is going to start. Boxes.py hides this by using +Turtle Graphics commands that also move the origin to the end of the +last line. Other drawing commands restore the current position after +they are finished. + +Moving the origin like this allows ignoring the absolute coordinates +and do all movement and drawing to be relative to the current +position. The current positions does not only consist of a point on +the drawing canvas but also a direction. + +To move the origin to a different location there are these to methods: + .. automethod:: boxes.Boxes.moveTo .. automethod:: boxes.Boxes.moveArc -**Boxes.ctx.save()** allows to save (among other things) the current position. -**Boxes.ctx.restore()** restores the previously saved state. Always make sure -to have balanced calls to those two functions. - -XXX +Often it is necessary to return to a position e.g. after placing a +row of parts. This can be done with the following context manager: .. automethod:: boxes.Boxes.saved_context() + +It can be used with the following code pattern: + +.. code-block:: python + + with self.saved_context: + self.rectangularWall(x, h, move="right") + self.rectangularWall(y, h, move="right") + self.rectangularWall(y, h, move="right") + self.rectangularWall(x, h, move="right") + self.rectangularWall(x, h, move="up only") + + # continue above the row + +Parts of the code still directly use the cairo primitives **Boxes.ctx.save()** +and **Boxes.ctx.restore()**. But this has several disadvantages and is +discouraged. For one it requires matchiung calls. It also does not +reset the starting point of the next line. This is "healed" by a +follow up **.moveTo()**. Use **.moveTo(0, 0)** if in doubt.