vcl/README

   1 Visual Components Library is responsible for the widgets (windowing, buttons, controls, file-pickers etc.) operating system abstraction, including basic rendering (e.g. the output device).
   2
   3 VCL provides a graphical toolkit similar to gtk+, Qt, SWING etc.
   4
   5 source/
   6         + the main cross-platform chunk of source
   7
   8 inc/
   9         + cross-platform abstraction headers
  10         vcl/
  11                 + public headers ("public" to the rest of LibreOffice, that is)
  12
  13 generic/
  14         + shared helper code for *some* of the backends, actually built into vcl.
  15
  16 headless/
  17         + a backend renderer that draws to bitmaps
  18
  19 android/
  20         + Android backend (work in progress, does work to some extent)
  21
  22 aqua/
  23         + OS X backend
  24
  25 ios/
  26         + iOS backend (work in progres, does not work, needs re-think
  27         and re-write)
  28
  29 win/
  30         + Windows backend
  31
  32 unx/
  33         + X11 backend and its sub-platforms
  34
  35         plugadapt/
  36                 + pluggable framework to select correct unx backend
  37         gtk/
  38                 + GTK2 support
  39         gtk3/
  40                 + GTK3.2+ support
  41         kde/
  42                 + KDE3 support
  43         kde4/
  44                 + KDE4 support
  45         generic/
  46                 + raw X11 support
  47
  48
  49 How the platform abstraction works
  50
  51         + InitVCL calls 'CreateSalInstance'
  52                 + ths is implemented by the compiled-in platform backend
  53                 + it stores various bits of global state in the
  54                   'SalData' (inc/saldatabasic.hxx) structure but:
  55         + the SalInstance vtable is the primary outward facing gateway
  56           API for platform backends
  57                 + It is a factory for:
  58                   SalFrames, SalVirtualDevices, SalPrinters,
  59                   Timers, the SolarMutexe, Drag&Drop and other
  60                   objects, as well as the primary event loop wrapper.
  61
  62 Note: references to "SV" in the code mean StarView, which was a
  63 portable C++ class library for GUIs, with very old roots, that was
  64 developed by StarDivision. Nowadays it is not used by anything except
  65 LibreOffice (and OpenOffice).
  66
  67 == EMF+ ==
  68
  69 emf+ is vector file format used by MSO and is successor of wmf and
  70 emf formats. see
  71 http://msdn.microsoft.com/en-us/library/cc230724.aspx for
  72 documentation. note that we didn't have this documentation from
  73 start, so part of the code predates to the time when we had guessed
  74 some parts and can be enhanced today. there also still many thing not
  75 complete
  76
  77 emf+ is handled a bit differently compared to original emf/wmf files,
  78 because GDIMetafile is missing features we need (mostly related to
  79 transparency, argb colors, etc.)
  80
  81 emf/wmf is translated to GDIMetafile in import filter
  82 vcl/source/filter/wmf and so special handling ends here
  83
  84 emf+ is encapsulated into GDIMetafile inside comment records and
  85 parsed/rendered later, when it reaches cppcanvas. it is parsed and
  86 rendered in cppcanvas/source/mtfrenderer. also note that there are
  87 emf+-only and emf+-dual files. dual files contains both types of
  88 records (emf and emf+) for rendering the images. these can used also
  89 in applications which don't know emf+. in that case we must ignore
  90 emf records and use emf+ for rendering. for more details see
  91 documentation
  92
  93 parsing:
  94
  95  wmf/emf filter --> GDI metafile with emf+ in commments --> cppcanvas metafile renderer
  96
  97 lately the GDIMetafile rendering path changed which also influenced
  98 emf+ rendering. now many things happen in drawing layer, where
  99 GDIMetafile is translated into drawing layer primitives. for
 100 metafiles with emf+ we let the mtfrenderer render them into bitmap
 101 (with transparency) and use this bitmap in drawinlayer. cleaner
 102 solution for current state would be to extend the drawing layer for
 103 missing features and move parsing into drawing layer (might be quite
 104 a lot of work). intemediary enhancement would be to know better the
 105 needed size/resolution of the bitmap, before we render emf+ into
 106 bitmap in drawing layer. Thorsten is working on the same problem with
 107 svg rendering, so hopefully his approach could be extended for emf+ as
 108 well. the places in drawing layer where we use canvas mtfrenderer to
 109 render into bitmaps can be found when you grep for GetUseCanvas. also
 110 look at vcl/source/gdi/gdimetafile.cxx where you can look for
 111 UseCanvas again. moving the parsing into drawinglayer might also have
 112 nice side effect for emf+-dual metafiles. in case the emf+ records
 113 are broken, it would be easier to use the duplicit emf
 114 rendering. fortunatelly we didn't run into such a broken emf+ file
 115 yet. but there were already few cases where we first though that the
 116 problem might be because of broken emf+ part. so far it always turned
 117 out to be another problem.
 118
 119 rendering:
 120
 121  before
 122
 123  vcl --> cppcanvas metafile renderer --> vcl
 124
 125  now
 126
 127  drawing layer --> vcl --> cppcanvas metafile renderer --> vcl --> drawing layer
 128
 129 another interesting part is actual rendering into canvas bitmap and
 130 using that bitmap later in code using vcl API.