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
  11 headless/
  12         + a backend renderer that draws to bitmaps
  13
  14 android/
  15         + Android backend
  16
  17 osx/
  18         + OS X backend
  19
  20 ios/
  21         + iOS backend
  22
  23 quartz/
  24         + code common to OS X and iOS
  25
  26 win/
  27         + Windows backend
  28
  29 unx/
  30         + X11 backend and its sub-platforms
  31
  32         plugadapt/
  33                 + pluggable framework to select correct unx backend
  34         gtk/
  35                 + GTK2 support
  36         gtk3/
  37                 + GTK3.2+ support
  38         kde/
  39                 + KDE3 support
  40         kde4/
  41                 + KDE4 support
  42         generic/
  43                 + raw X11 support
  44
  45                 dtrans/
  46                         + "data transfer" - clipboard handling
  47                         + http://stackoverflow.com/questions/3261379/getting-html-source-or-rich-text-from-the-x-clipboard
  48                           for tips how to show the current content of the
  49                           clipboard
  50
  51
  52 How the platform abstraction works
  53
  54         + InitVCL calls 'CreateSalInstance'
  55                 + this is implemented by the compiled-in platform backend
  56                 + it stores various bits of global state in the
  57                   'SalData' (inc/saldatabasic.hxx) structure but:
  58         + the SalInstance vtable is the primary outward facing gateway
  59           API for platform backends
  60                 + It is a factory for:
  61                   SalFrames, SalVirtualDevices, SalPrinters,
  62                   Timers, the SolarMutexe, Drag&Drop and other
  63                   objects, as well as the primary event loop wrapper.
  64
  65 Note: references to "SV" in the code mean StarView, which was a
  66 portable C++ class library for GUIs, with very old roots, that was
  67 developed by StarDivision. Nowadays it is not used by anything except
  68 LibreOffice (and OpenOffice).
  69
  70 "svp" stands for "StarView Plugin".
  71
  72 == COM threading ==
  73
  74 The way COM is used in LO generally:
  75 - vcl InitSalData() puts main thread into Single-threaded Apartment (STA)
  76 - oslWorkerWrapperFunction() puts every thread spawned via oslCreateThread()
  77   into MTA (free-threaded)
  78
  79 == GDIMetafile ==
  80
  81 GDIMetafile is a vector drawing representation that corresponds directly
  82 to the SVM (StarView Metafile) format; it is extremely important as
  83 an intermediate format in all sorts of drawing and printing operations.
  84
  85 There is a class MetafileXmlDump in include/test/mtfxmldump.hxx that
  86 can store a GDIMetafile as XML, which makes debugging much easier
  87 since you can just use "diff" to see changes.
  88
  89 To use it you need to link against "test" library and then (because
  90 "test" is not part of the installation) run with:
  91 LD_LIBRARY_PATH=workdir/LinkTarget/Library:workdir/UnpackedTarball/cppunit/src/cppunit/.libs instdir/program/soffice
  92
  93 == EMF+ ==
  94
  95 emf+ is vector file format used by MSO and is successor of wmf and
  96 emf formats. see
  97 http://msdn.microsoft.com/en-us/library/cc230724.aspx for
  98 documentation. note that we didn't have this documentation from
  99 start, so part of the code predates to the time when we had guessed
 100 some parts and can be enhanced today. there also still many thing not
 101 complete
 102
 103 emf+ is handled a bit differently compared to original emf/wmf files,
 104 because GDIMetafile is missing features we need (mostly related to
 105 transparency, argb colors, etc.)
 106
 107 emf/wmf is translated to GDIMetafile in import filter
 108 vcl/source/filter/wmf and so special handling ends here
 109
 110 emf+ is encapsulated into GDIMetafile inside comment records and
 111 parsed/rendered later, when it reaches cppcanvas. it is parsed and
 112 rendered in cppcanvas/source/mtfrenderer. also note that there are
 113 emf+-only and emf+-dual files. dual files contains both types of
 114 records (emf and emf+) for rendering the images. these can used also
 115 in applications which don't know emf+. in that case we must ignore
 116 emf records and use emf+ for rendering. for more details see
 117 documentation
 118
 119 parsing:
 120
 121  wmf/emf filter --> GDI metafile with emf+ in comments --> cppcanvas metafile renderer
 122
 123 lately the GDIMetafile rendering path changed which also influenced
 124 emf+ rendering. now many things happen in drawing layer, where
 125 GDIMetafile is translated into drawing layer primitives. for
 126 metafiles with emf+ we let the mtfrenderer render them into bitmap
 127 (with transparency) and use this bitmap in drawinlayer. cleaner
 128 solution for current state would be to extend the drawing layer for
 129 missing features and move parsing into drawing layer (might be quite
 130 a lot of work). intermediary enhancement would be to know better the
 131 needed size/resolution of the bitmap, before we render emf+ into
 132 bitmap in drawing layer. Thorsten is working on the same problem with
 133 svg rendering, so hopefully his approach could be extended for emf+ as
 134 well. the places in drawing layer where we use canvas mtfrenderer to
 135 render into bitmaps can be found when you grep for GetUseCanvas. also
 136 look at vcl/source/gdi/gdimetafile.cxx where you can look for
 137 UseCanvas again. moving the parsing into drawinglayer might also have
 138 nice side effect for emf+-dual metafiles. in case the emf+ records
 139 are broken, it would be easier to use the duplicit emf
 140 rendering. fortunately we didn't run into such a broken emf+ file
 141 yet. but there were already few cases where we first though that the
 142 problem might be because of broken emf+ part. so far it always turned
 143 out to be another problem.
 144
 145 rendering:
 146
 147  before
 148
 149  vcl --> cppcanvas metafile renderer --> vcl
 150
 151  now
 152
 153  drawing layer --> vcl --> cppcanvas metafile renderer --> vcl --> drawing layer
 154
 155 another interesting part is actual rendering into canvas bitmap and
 156 using that bitmap later in code using vcl API.
 157
 158 EMF+ implementation has some extensive logging, best if you do a dbgutil
 159 build, and then
 160
 161 export SAL_LOG=+INFO.cppcanvas.emf+INFO.vcl.emf
 162
 163 before running LibreOffice; it will give you lots of useful hints.
 164
 165 You can also fallback to EMF (from EMF+) rendering via
 166
 167 export EMF_PLUS_DISABLE=1
 168
 169
 170 == Printing/PDF export ==
 171
 172 Printing from Writer works like this:
 173
 174 1) individual pages print by passing an appropriate OutputDevice to XRenderable
 175 2) in drawinglayer, a VclMetafileProcessor2D is used to record everything on
 176    the page (because the OutputDevice has been set up to record a GDIMetaFile)
 177 3) the pages' GDIMetaFiles are converted to PDF by the vcl::PDFWriter
 178    in vcl/source/gdi/pdfwriter*
 179
 180 Creating the ODF thumbnail for the first page works as above except step 3 is:
 181
 182 3) the GDIMetaFile is replayed to create the thumbnail
 183
 184 On-screen display differs in step 1 and 2:
 185
 186 1) the VCL Window gets invalidated somehow and paints itself
 187 2) in drawinglayer, a VclPixelProcessor2D is used to display the content
 188
 189
 190 === Debugging PDF export ===
 191
 192 Debugging the PDF export becomes much easier in higher debug-levels, where
 193 compression is disabled (so the PDF file is directly readable) and
 194 the MARK function puts comments into the PDF file about which method
 195 generated the following PDF content.
 196
 197 touch vcl/source/gdi/pdfwriter* && make vcl dbglevel=3
 198
 199 To de-compress the contents of a PDF file written by a release build or
 200 other programs, use the "pdfunzip" tool:
 201
 202 bin/run pdfunzip input.pdf output.pdf