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