svx/README.md

   1 # Graphics Related Helper Code
   2
   3 Contains graphics related helper code. Lots of the draw and impress code is in this shared library.
   4
   5 - `xoutdev`
   6
   7     this is where a lot of wht work would happen to move to the canvas. (what does that mean?)
   8
   9 - `svdraw`
  10
  11     transparent gradient stuff. [seriously? surely much more, too]
  12
  13 ## SdrObject
  14
  15 The shapes you can see in LibreOffice (like rectangle, etc.) are SdrObjects.
  16 They are declared as a hierarchy:
  17
  18     SdrObject <- SdrAttrObj <- E3dObject <- E3dCompoundObject <- E3dCubeObj
  19         ^ ^ ^             ^            ^              | | ^ ^
  20         | | |             |            |              | | | +--- E3dExtrudeObj
  21         | | |             |            |              | | +----- E3dLatheObj
  22         | | |             |            |              | +------- E3dPolygonObj
  23         | | |             |            |              +--------- E3dSphereObj
  24         | | |             |            +--- E3dScene...
  25         | | |             |
  26         | | |             +--- SdrTextObj <- SdrObjCustomShape...
  27         | | |                   ^ ^ ^ ^ ^
  28         | | |                   | | | | +--- SdrEdgeObj...
  29         | | |                   | | | +----- SdrMeasureObj...
  30         | | |                   | | +------- SdrPathObj...
  31         | | |                   | +--------- SdrRectObj...
  32         | | |                   +----------- SdrTableObj...
  33         | | +--- SdrObjGroup...
  34         | + ---- SdrPageObj...
  35         +------- SdrVirtObj...
  36
  37 The above is incomplete of course.
  38
  39 ## SdrModel / SdrView
  40
  41 Copied from `svdview.hxx`:
  42
  43   First of all the app creates a `SdrModel`.
  44   Then it opens a Win and creates a `SdrView`.
  45   `ShowSdrPage()` announces a page at `SdrView`.
  46   It's possible to show `SdrView` in any Wins at once.
  47
  48   `SdrView` can show as many Wins as it wants at once. Pages are announced
  49   or checked out with the help of `ShowSdrPage()`/`HideSdrPage()`. For every announced
  50   page there is a `SdrPageView` instance in container aPages. If more than one page
  51   is showed, you have to pay attention that the offset parameter of `ShowSdrPage()`
  52   is conformed to the size of the page (to prevent overlapping of two pages).
  53
  54 `SdrView` itself is inherited from many objects in a chain of inheritance (all
  55 that starts with `SdrPaintView` - that is itself inherited from few classes
  56 too):
  57
  58     SdrPaintView <- SdrSnapView <- SdrMarkView <- SdrEditView <- SdrPolyEditView
  59                                                                      ^
  60     +----------------------------------------------------------------+
  61     |
  62     SdrGlueEditView <- SdrObjEditView <- SdrExchangeView <- SdrDragView
  63                                                                      ^
  64     +----------------------------------------------------------------+
  65     |
  66     SdrCreateView <- SdrView
  67
  68 From `SdrView` on, it is not flat, but a real hierarchy again.
  69
  70 ## Drawing Layer / SdrObject(s)
  71
  72 See `drawinglayer/README.md` for general information about drawinglayer.
  73
  74 Below is the class diagram that comes from
  75 <https://web.archive.org/web/20160827020830if_/http://www.openoffice.org:80/marketing/ooocon2006/presentations/wednesday_g11.odp>
  76 slide number 6.
  77
  78     .------- Model --------------.      .------- View -----------------------------------------.
  79     | SdrObject - ViewContact    | 1..* | ViewObjectContact                                    |
  80     |              getChild()    |------|    getPrimitiveList()  -----> Object(s) ---> SdrView |
  81     |              getVOC()      |      |    getRecPrimitiveList()      Contact                |
  82     |              getViewInd... |      |________|_____________________________________________|
  83     | ...ependentPrimitiveList() |               |
  84     |____________________________|            generates
  85                                                  |           ______
  86                                                  V          /      |
  87                                        .----------------------.    |
  88                                        | basePrimitive        |    |
  89                                        |   getRange()         |<---'
  90                                        |   getDecomposition() |
  91                                        |______________________|
  92
  93 For `SdrObjects`, there are own `DrawingLayer` primitives in
  94 `svx/source/sdr/primitive2d`
  95
  96 The `ViewContact` / `ViewObject` / `ViewObjectContact` are in `svx/source/sdr/contact`
  97 Decomposes the `SdrObjects`, and does all sort of operations on them.
  98
  99 If the number of visualizable objects (e.g. `SdrObjects`) is `X`, and the number of
 100 `SdrViews` is `Y`, then:
 101
 102 - there are `X` `ViewContact` instances (1:1 relation with a visualizable object)
 103 - there are `Y` `ObjectContact` instances (1:1 relation with an `SdrView`)
 104 - there are `X*Y` `ViewObjectContact` instances (1:N relation to both
 105   visualizable objects and `SdrView`s)