libreofficekit/README.md

   1 # LibreOfficeKit
   2
   3 LibreOfficeKit can be used for accessing LibreOffice functionality
   4 through C/C++, without any need to use UNO.
   5
   6 For now it only offers document conversion (in addition to an experimental
   7 tiled rendering API).
   8
   9 ## Integrating LOK Into Other Software
  10
  11 LOK functionality can be accessed by including `LibreOfficeKit.h[xx]` in your
  12 program.
  13
  14 LOK initialisation (`lok_init`) requires the inclusion of `LibreOfficeKitInit.h` in
  15 your program. If you use the C++ `LibreOfficeKit.hxx` header, it already includes
  16 `LibreOfficeKitInit.h` for you.
  17
  18 (`LibreOfficeKit.hxx` is a simple and fully inlined C++ wrapper for the same
  19 functionality as in `LibreOfficeKit.h`.)
  20
  21 An example program can be seen on:
  22 <https://gitlab.com/ojwb/lloconv>
  23
  24 ## Tiled Rendering
  25
  26 To use LOK Tiled Rendering you will need the following before the LOK includes:
  27
  28     #define LOK_USE_UNSTABLE_API
  29
  30 (This must be define before ANY LOK header, i.e. including the Init header.)
  31
  32 Currently only bitmap-buffer rendering is supported, with a 32-bit BGRA
  33 colorspace (further alternatives could feasibly be implemented as needed).
  34 Scanlines are ordered top-down (whereas LibreOffice will internally default
  35 to bottom-up).
  36
  37 ## Tiled Editing
  38
  39 On top of the tiled rendering API, a set of new methods have been added to the
  40 `lok::Document` class to allow basic editing, too. Communication between the LOK
  41 client and LibreOffice is a two-way channel. The client can initiate an action
  42 by calling the above mentioned methods. The most important methods for the
  43 client -> LibreOffice communication are:
  44
  45 - `initializeForRendering()`, expected to be called right after
  46   `lok::Office::documentLoad()` returned a `lok::Document*`.
  47 - `postKeyEvent()`, expected to be called when the user provides input on the
  48   (soft-)keyboard.
  49 - `postMouseEvent()`, expected to be called when the user generated a touch or
  50   mouse event.
  51
  52 In general, all coordinates are always in absolute twips (20th of a point, or:
  53 1" = 1440 twips). See `lok::Document` in `LibreOfficeKit.hxx` for a full list of
  54 methods and their documentation.
  55
  56 The other way around (LibreOffice -> LOK client) is implemented using a
  57 callback. A LOK client can register a callback using the registerCallback()
  58 method. Whenever editing requires some action on the client side, a callback
  59 event is emitted. The callback types are described using the
  60 `LibreOfficeKitCallbackType` enumeration in `LibreOfficeKitEnums.h`, the callback
  61 function signature itself is provided by the LibreOfficeKitCallback typedef in
  62 `LibreOfficeKitTypes.h`. The most important callback types:
  63
  64 - `LOK_CALLBACK_INVALIDATE_TILES`: drop all tiles cached on client-side that
  65   intersect with the provided rectangle
  66 - `LOK_CALLBACK_INVALIDATE_VISIBLE_CURSOR`: need to set the position and/or the
  67   size of the cursor
  68 - `LOK_CALLBACK_TEXT_SELECTION`: need to adjust the selection overlay provided
  69   by the client as the set of rectangles describing the selection overlay
  70   changed
  71
  72 There are currently two known LOK clients supporting tiled editing:
  73
  74 - `gtktiledviewer` (see below), which allows testing the LOK core implementation
  75   on (desktop) Linux
  76 - (LibreOffice on) Android
  77
  78 Core has next to no idea what is the LOK client, so for effective development,
  79 it's recommended that the core part is developed against `gtktiledviewer`, and
  80 once a feature works there, then implement the Android part, with its slower
  81 development iteration (slow uploading to the device, the need to link all
  82 object files into a single `.so`, etc).
  83
  84 * Debugging with gdb and `gtktiledviewer`
  85
  86 To run `gtktiledviewer`:
  87
  88     bin/run gtktiledviewer --lo-path=$PWD/instdir/program path/to/test.odt
  89
  90 To receive all incoming events from core use `G_MESSAGES_DEBUG=all`
  91
  92     G_MESSAGES_DEBUG=all bin/run gtktiledviewer --lo-path=$PWD/instdir/program ../test.odt
  93
  94 To debug with `gdb`:
  95
  96     export LO_TRACE='gdb --tui --args'
  97
  98 before `bin/run`, this will run gtktiledviewer in the debugger instead.
  99
 100 ### Building and running gtktiledviewer on Windows
 101
 102 A pre-requisite is pre-built GTK3 libraries. See [official GTK documentation](https://www.gtk.org/docs/installations/windows/).
 103 Building of gtktiledviewer on Windows is enabled by passing
 104
 105     --with-gtk3-build=<path/to/GTK3/build/directory>
 106
 107 to configure.
 108
 109 Running the compiled executable requires GTK's bin in PATH:
 110
 111     PATH=${PATH}:/cygdrive/c/gtk-build/gtk/x64/release/bin bin/run gtktiledviewer --lo-path=$(cygpath -am $PWD/instdir/program) ../test.odt
 112
 113 ## LibreOfficeKitGtk
 114
 115 Currently consists of only a very basic GTK document viewer widget.
 116
 117 The widget uses `g_info()` instead of `SAL_INFO()`, use the `G_MESSAGES_DEBUG=all`
 118 environment variable to display those messages.