diff options
Diffstat (limited to 'vcl')
| -rw-r--r-- | vcl/README.md | 89 |
1 files changed, 46 insertions, 43 deletions
diff --git a/vcl/README.md b/vcl/README.md index e0944688f2f3..25498991e4fb 100644 --- a/vcl/README.md +++ b/vcl/README.md @@ -1,58 +1,61 @@ -Visual Class Library is responsible for the widgets (windowing, buttons, controls, file-pickers etc.), operating system abstraction, including basic rendering (e.g. the output device). +# Visual Class Library (VCL) + +Visual Class Library (VCL) is responsible for the widgets (windowing, buttons, controls, +file-pickers etc.), operating system abstraction, including basic rendering (e.g. the output device). It should not be confused with Borland's Visual Component Library, which is entirely unrelated. VCL provides a graphical toolkit similar to gtk+, Qt, SWING etc. -source/ ++ source/ + the main cross-platform chunk of source -inc/ ++ inc/ + cross-platform abstraction headers -headless/ ++ headless/ + a backend renderer that draws to bitmaps -android/ ++ android/ + Android backend -osx/ ++ osx/ + macOS backend -ios/ ++ ios/ + iOS backend -quartz/ ++ quartz/ + code common to macOS and iOS -win/ ++ win/ + Windows backend -qt5/ ++ qt5/ + Qt5 (under construction) -unx/ ++ unx/ + X11 backend and its sub-platforms - gtk3/ - + GTK3 support - kf5/ - + KF5 support (based on qt5 VCL plugin mentioned above) - gtk3_kde5/ - + GTK3 support with KDE5 file pickers (alternative to native kf5 one) - generic/ - + raw X11 support - - plugadapt/ + + gtk3/ + + GTK3 support + + kf5/ + + KF5 support (based on qt5 VCL plugin mentioned above) + + gtk3_kde5/ + + GTK3 support with KDE5 file pickers (alternative to native kf5 one) + + generic/ + + raw X11 support + + + plugadapt/ + pluggable framework to select correct unx backend - dtrans/ + + dtrans/ + "data transfer" - clipboard handling + http://stackoverflow.com/questions/3261379/getting-html-source-or-rich-text-from-the-x-clipboard for tips how to show the current content of the clipboard -How the platform abstraction works ++ How the platform abstraction works + InitVCL calls 'CreateSalInstance' + this is implemented by the compiled-in platform backend @@ -72,24 +75,24 @@ LibreOffice (and OpenOffice). "svp" stands for "StarView Plugin". -== COM threading == +## COM Threading The way COM is used in LO generally: - vcl puts main thread into Single-threaded Apartment (STA) -- oslWorkerWrapperFunction() puts every thread spawned via oslCreateThread() +- oslWorkerWrapperFunction() puts every thread spawned via `oslCreateThread()` into MTA (free-threaded) -== GDIMetafile == +# GDIMetafile GDIMetafile is a vector drawing representation that corresponds directly to the SVM (StarView Metafile) format; it is extremely important as an intermediate format in all sorts of drawing and printing operations. -There is a class MetafileXmlDump in include/vcl/mtfxmldump.hxx that +There is a class `MetafileXmlDump` in `include/vcl/mtfxmldump.hxx` that can store a GDIMetafile as XML, which makes debugging much easier since you can just use "diff" to see changes. -== EMF+ == +## EMF+ emf+ is vector file format used by MSO and is successor of wmf and emf formats. see @@ -104,7 +107,7 @@ because GDIMetafile is missing features we need (mostly related to transparency, argb colors, etc.) emf/wmf is translated to GDIMetafile in import filter -vcl/source/filter/wmf and so special handling ends here +`vcl/source/filter/wmf` and so special handling ends here emf+ is encapsulated into GDIMetafile inside comment records and parsed/rendered later, when it reaches cppcanvas. It is parsed and @@ -113,9 +116,9 @@ emf+-only and emf+-dual files. dual files contains both types of records (emf and emf+) for rendering the images. these can used also in applications which don't know emf+. in that case we must ignore emf records and use emf+ for rendering. for more details see -documentation +the documentation. -parsing: +## Parsing wmf/emf filter --> GDI metafile with emf+ in comments --> cppcanvas metafile renderer @@ -141,7 +144,7 @@ yet. but there were already few cases where we first though that the problem might be because of broken emf+ part. so far it always turned out to be another problem. -rendering: +## Rendering before @@ -157,16 +160,16 @@ using that bitmap later in code using vcl API. EMF+ implementation has some extensive logging, best if you do a dbgutil build, and then -export SAL_LOG=+INFO.cppcanvas.emf+INFO.vcl.emf + export SAL_LOG=+INFO.cppcanvas.emf+INFO.vcl.emf before running LibreOffice; it will give you lots of useful hints. You can also fallback to EMF (from EMF+) rendering via -export EMF_PLUS_DISABLE=1 + export EMF_PLUS_DISABLE=1 -== Printing/PDF export == +## Printing/PDF Export Printing from Writer works like this: @@ -174,7 +177,7 @@ Printing from Writer works like this: 2) in drawinglayer, a VclMetafileProcessor2D is used to record everything on the page (because the OutputDevice has been set up to record a GDIMetaFile) 3) the pages' GDIMetaFiles are converted to PDF by the vcl::PDFWriter - in vcl/source/gdi/pdfwriter* + in `vcl/source/gdi/pdfwriter*` Creating the ODF thumbnail for the first page works as above except step 3 is: @@ -183,10 +186,10 @@ Creating the ODF thumbnail for the first page works as above except step 3 is: On-screen display differs in step 1 and 2: 1) the VCL Window gets invalidated somehow and paints itself -2) in drawinglayer, a VclPixelProcessor2D is used to display the content +2) in drawinglayer, a `VclPixelProcessor2D` is used to display the content -=== Debugging PDF export === +### Debugging PDF export Debugging the PDF export becomes much easier when compression is disabled (so the PDF file is directly readable) and @@ -195,14 +198,14 @@ generated the following PDF content. The compression can be disabled even using an env. var: -export VCL_DEBUG_DISABLE_PDFCOMPRESSION=1 + export VCL_DEBUG_DISABLE_PDFCOMPRESSION=1 To de-compress the contents of a PDF file written by a release build or other programs, use the "pdfunzip" tool: -bin/run pdfunzip input.pdf output.pdf + bin/run pdfunzip input.pdf output.pdf -=== SolarMutexGuard === +### SolarMutexGuard The solar mutex is the "big kernel lock" of LibreOffice, a global one. It's a recursive mutex, so it's allowed to take the lock on the same thread multiple @@ -223,10 +226,10 @@ This way you ensure that code (not prepared for multithreading) is still executed only on a single thread. In case you expect that your caller takes the solar mutex, then you can use -the DBG_TESTSOLARMUTEX() macro to assert that in dbgutil builds. +the `DBG_TESTSOLARMUTEX()` macro to assert that in dbgutil builds. Event listeners are a special (but frequent) case of the "never call out with -a mutex (SolarMutex or other) locked" fundamental rule: +a mutex (`SolarMutex` or other) locked" fundamental rule: - UNO methods can be called from multiple threads, so most implementations take the solar mutex as their first action when necessary. |