#54 fikset test rundt posisjonering av modul & la til forklaring

forklaringen vil nok ikke holde vann når SOI etterhvert skal støtte landscape / porttrait + header plassert sidelengs

soitool/soi.py

@@ -123,11 +123,67 @@ class SOI:
 
     Holds all info about an SOI necessary to view and edit it.
 
+    ## Note about rectpack
+
     This class relies heavily on the rectpack library for optimal placement of
     modules when placement_strategy is 'auto'. Refer to the rectpack
     documentation for details beyond what is provided in this class:
     https://github.com/secnot/rectpack
 
+    ## Anatomy of an SOI
+
+    Below is an illustration of how an SOI with two pages is represented using
+    the class variables.
+
+    ```text
+     SOI.PADDING
+     |  SOI.CONTENT_WIDTH
+     |  |        SOI.PADDING
+     |  |        |
+     v  v        v
+    +-------------+
+    |             | <- SOI.PADDING
+    | +---------+ |
+    | | HEADER  | | <- SOI.HEADER_HEIGHT
+    | +---------+ |
+    | | MODULES | | <- SOI.CONTENT_HEIGHT
+    | +---------+ |
+    |             | <- SOI.PADDING
+    +-------------+
+                    <- SOI.PADDING
+    +-------------+
+    |             | <- SOI.PADDING
+    | +---------+ |
+    | | HEADER  | | <- SOI.HEADER_HEIGHT
+    | +---------+ |
+    | | MODULES | | <- SOI.CONTENT_HEIGHT
+    | +---------+ |
+    |             | <- SOI.PADDING
+    +-------------+
+    ```
+
+    `MODULES` is where all the modules of the page will show up. Each module
+    has two positions stored, one through it's `module["meta"]["x"]` and
+    `module["meta"]["y"]` values, and one through the position of it's
+    widget representation `module["widget"].pos()`. The "meta" position is
+    relative to the page indicated by `meta["meta"]["page"]`, whereas the
+    widget position is absolute and takes into consideration that the SOI is in
+    practice painted onto one continious surface. They are defined as follows:
+
+    * `module["meta"]["x"]` is a value between `0` and `SOI.CONTENT_WIDTH`.
+        This value is determined by the placement strategy.
+    * `module["meta"]["y"]` is a value between `0` and `SOI.CONTENT_HEIGHT`.
+        This value is determined by the placement strategy.
+    * `module["widget"].pos().x()` is calculated from `module["meta"]["x"]`
+        as follows: `module["meta"]["x"] + SOI.PADDING`
+    * `module["widget"].pos().y()` is calculated from `module["meta"]["y"]`
+        as follows: `module["meta"]["y"] + SOI.PADDING + SOI.HEADER_HEIGHT +
+        (SOI.PADDING + SOI.HEIGHT) * (module["meta"]["page"] - 1)`
+
+    The function `SOI.update_module_widget_position` is responsible for
+    updating the widget positions based on the "meta" positions, using the
+    formulas above.
+
     Parameters
     ----------
     title : string
@@ -269,7 +325,8 @@ class SOI:
     def update_module_widget_position(self, module):
         """Update position of module widget based on meta position.
 
-        This function is very much WIP..
+        For reasoning on the calculations done in this function see the class
+        docstring.
 
         Parameters
         ----------

test/test_soi.py

@@ -276,10 +276,14 @@ class TestSOI(unittest.TestCase):
 
         self.soi.update_module_widget_position(self.soi.modules[0])
 
-        # calculate expected widget positions
+        # calculate expected widget positions. See SOI class docstring for an
+        # explanation of the calculation neededfor y
         expected_x = page_2_module["meta"]["x"] + self.soi.PADDING
         expected_y = (
-            page_2_module["meta"]["y"] + self.soi.PADDING * 3 + self.soi.HEIGHT
+            page_2_module["meta"]["y"]
+            + self.soi.PADDING * 2
+            + self.soi.HEIGHT
+            + self.soi.HEADER_HEIGHT
         )
 
         self.assertEqual(