vcl/README.md

   1 # Visual Class Library (VCL)
   2
   3 Visual Class Library (VCL) is responsible for the widgets (windowing, buttons, controls,
   4 file-pickers etc.), operating system abstraction, including basic rendering (e.g. the output device).
   5
   6 It should not be confused with Borland's Visual Component Library, which is entirely unrelated.
   7
   8 VCL provides a graphical toolkit similar to gtk+, Qt, SWING etc.
   9
  10 + source/
  11         + the main cross-platform chunk of source
  12
  13 + inc/
  14         + cross-platform abstraction headers
  15
  16 + headless/
  17         + a backend renderer that draws to bitmaps
  18
  19 + android/
  20         + Android backend
  21
  22 + osx/
  23         + macOS backend
  24
  25 + ios/
  26         + iOS backend
  27
  28 + quartz/
  29         + code common to macOS and iOS
  30
  31 + win/
  32         + Windows backend
  33
  34 + qt5/
  35         + Qt5 (under construction)
  36
  37 + unx/
  38         + X11 backend and its sub-platforms
  39                 + gtk3/
  40                         + GTK3 support
  41                 + kf5/
  42                         + KF5 support (based on qt5 VCL plugin mentioned above)
  43                 + gtk3_kde5/
  44                         + GTK3 support with KDE5 file pickers (alternative to native kf5 one)
  45                 + generic/
  46                         + raw X11 support
  47
  48                 + plugadapt/
  49                         + pluggable framework to select correct unx backend
  50
  51                 + dtrans/
  52                         + "data transfer" - clipboard handling
  53                         + http://stackoverflow.com/questions/3261379/getting-html-source-or-rich-text-from-the-x-clipboard
  54                           for tips how to show the current content of the
  55                           clipboard
  56
  57
  58 + How the platform abstraction works
  59
  60         + InitVCL calls 'CreateSalInstance'
  61                 + this is implemented by the compiled-in platform backend
  62                 + it stores various bits of global state in the
  63                   'SalData' (inc/saldatabasic.hxx) structure but:
  64         + the SalInstance vtable is the primary outward facing gateway
  65           API for platform backends
  66                 + It is a factory for:
  67                   SalFrames, SalVirtualDevices, SalPrinters,
  68                   Timers, the SolarMutex, Drag&Drop and other
  69                   objects, as well as the primary event loop wrapper.
  70
  71 Note: references to "SV" in the code mean StarView, which was a
  72 portable C++ class library for GUIs, with very old roots, that was
  73 developed by StarDivision. Nowadays it is not used by anything except
  74 LibreOffice (and OpenOffice).
  75
  76 "svp" stands for "StarView Plugin".
  77
  78 ## COM Threading
  79
  80 The way COM is used in LO generally:
  81 - vcl puts main thread into Single-threaded Apartment (STA)
  82 - oslWorkerWrapperFunction() puts every thread spawned via `oslCreateThread()`
  83   into MTA (free-threaded)
  84
  85 ## GDIMetafile
  86
  87 GDIMetafile is a vector drawing representation that corresponds directly
  88 to the SVM (StarView Metafile) format; it is extremely important as
  89 an intermediate format in all sorts of drawing and printing operations.
  90
  91 There is a class `MetafileXmlDump` in `include/vcl/mtfxmldump.hxx` that
  92 can store a GDIMetafile as XML, which makes debugging much easier
  93 since you can just use "diff" to see changes.
  94
  95 ## EMF+
  96
  97 emf+ is vector file format used by MSO and is successor of wmf and
  98 emf formats. see
  99 http://msdn.microsoft.com/en-us/library/cc230724.aspx for
 100 documentation. note that we didn't have this documentation from
 101 start, so part of the code predates to the time when we had guessed
 102 some parts and can be enhanced today. there also still many thing not
 103 complete
 104
 105 emf+ is handled a bit differently compared to original emf/wmf files,
 106 because GDIMetafile is missing features we need (mostly related to
 107 transparency, argb colors, etc.)
 108
 109 emf/wmf is translated to GDIMetafile in import filter
 110 `vcl/source/filter/wmf` and so special handling ends here
 111
 112 emf+ is encapsulated into GDIMetafile inside comment records and
 113 parsed/rendered later, when it reaches cppcanvas. It is parsed and
 114 rendered in cppcanvas/source/mtfrenderer. also note that there are
 115 emf+-only and emf+-dual files. dual files contains both types of
 116 records (emf and emf+) for rendering the images. these can used also
 117 in applications which don't know emf+. in that case we must ignore
 118 emf records and use emf+ for rendering. for more details see
 119 the documentation.
 120
 121 ## Parsing
 122
 123  wmf/emf filter --> GDI metafile with emf+ in comments --> cppcanvas metafile renderer
 124
 125 lately the GDIMetafile rendering path changed which also influenced
 126 emf+ rendering. now many things happen in drawing layer, where
 127 GDIMetafile is translated into drawing layer primitives. for
 128 metafiles with emf+ we let the mtfrenderer render them into bitmap
 129 (with transparency) and use this bitmap in drawinlayer. cleaner
 130 solution for current state would be to extend the drawing layer for
 131 missing features and move parsing into drawing layer (might be quite
 132 a lot of work). intermediary enhancement would be to know better the
 133 needed size/resolution of the bitmap, before we render emf+ into
 134 bitmap in drawing layer. Thorsten is working on the same problem with
 135 svg rendering, so hopefully his approach could be extended for emf+ as
 136 well. the places in drawing layer where we use canvas mtfrenderer to
 137 render into bitmaps can be found when you grep for GetUseCanvas. also
 138 look at vcl/source/gdi/gdimetafile.cxx where you can look for
 139 UseCanvas again. moving the parsing into drawinglayer might also have
 140 nice side effect for emf+-dual metafiles. in case the emf+ records
 141 are broken, it would be easier to use the duplicit emf
 142 rendering. fortunately we didn't run into such a broken emf+ file
 143 yet. but there were already few cases where we first though that the
 144 problem might be because of broken emf+ part. so far it always turned
 145 out to be another problem.
 146
 147 ## Rendering
 148
 149  before
 150
 151  vcl --> cppcanvas metafile renderer --> vcl
 152
 153  now
 154
 155  drawing layer --> vcl --> cppcanvas metafile renderer --> vcl --> drawing layer
 156
 157 another interesting part is actual rendering into canvas bitmap and
 158 using that bitmap later in code using vcl API.
 159
 160 EMF+ implementation has some extensive logging, best if you do a dbgutil
 161 build, and then
 162
 163     export SAL_LOG=+INFO.cppcanvas.emf+INFO.vcl.emf
 164
 165 before running LibreOffice; it will give you lots of useful hints.
 166
 167 You can also fallback to EMF (from EMF+) rendering via
 168
 169     export EMF_PLUS_DISABLE=1
 170
 171
 172 ## Printing/PDF Export
 173
 174 Printing from Writer works like this:
 175
 176 1) individual pages print by passing an appropriate OutputDevice to XRenderable
 177 2) in drawinglayer, a VclMetafileProcessor2D is used to record everything on
 178    the page (because the OutputDevice has been set up to record a GDIMetaFile)
 179 3) the pages' GDIMetaFiles are converted to PDF by the vcl::PDFWriter
 180    in `vcl/source/gdi/pdfwriter*`
 181
 182 Creating the ODF thumbnail for the first page works as above except step 3 is:
 183
 184 3) the GDIMetaFile is replayed to create the thumbnail
 185
 186 On-screen display differs in step 1 and 2:
 187
 188 1) the VCL Window gets invalidated somehow and paints itself
 189 2) in drawinglayer, a `VclPixelProcessor2D` is used to display the content
 190
 191
 192 ### Debugging PDF export
 193
 194 Debugging the PDF export becomes much easier when
 195 compression is disabled (so the PDF file is directly readable) and
 196 the MARK function puts comments into the PDF file about which method
 197 generated the following PDF content.
 198
 199 The compression can be disabled even using an env. var:
 200
 201     export VCL_DEBUG_DISABLE_PDFCOMPRESSION=1
 202
 203 To de-compress the contents of a PDF file written by a release build or
 204 other programs, use the "pdfunzip" tool:
 205
 206     bin/run pdfunzip input.pdf output.pdf
 207
 208 ### SolarMutexGuard
 209
 210 The solar mutex is the "big kernel lock" of LibreOffice, a global one. It's a
 211 recursive mutex, so it's allowed to take the lock on the same thread multiple
 212 times, and only the last unlock will actually release the mutex.
 213
 214 UNO methods on components can be called from multiple threads, while the
 215 majority of the codebase is not prepared for multi-threading. One way to get
 216 around this mismatch is to create a SolarMutexGuard instance at the start of
 217 each & every UNO method implementation, but only when it is necessary:
 218
 219 - Only acquire the SolarMutex if you actually need it (e.g., not in functions
 220   that return static information).
 221
 222 - Only around the code that actually needs it (i.e., never call out with it
 223   locked).
 224
 225 This way you ensure that code (not prepared for multithreading) is still
 226 executed only on a single thread.
 227
 228 In case you expect that your caller takes the solar mutex, then you can use
 229 the `DBG_TESTSOLARMUTEX()` macro to assert that in dbgutil builds.
 230
 231 Event listeners are a special (but frequent) case of the "never call out with
 232 a mutex (`SolarMutex` or other) locked" fundamental rule:
 233
 234 - UNO methods can be called from multiple threads, so most implementations
 235   take the solar mutex as their first action when necessary.
 236
 237 - This can be problematic if later calling out (an event handler is called),
 238   where the called function may be an UNO method implementation as well and
 239   may be invoked on a different thread.
 240
 241 - So we try to not own the solar mutex, whenever we call out (invoke event
 242   listeners).
 243
 244 In short, never hold any mutex unless necessary, especially not when calling
 245 out.
 246
 247 ## Read More
 248 * [Environment variables in VCL](README.vars.md)
 249 * [GDIMetaFile class](README.GDIMetaFile.md)
 250 * [Understanding transitional VCL lifecycle](README.lifecycle.md)
 251 * [VCL scheduler](README.scheduler.md)