libreofficekit/README

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