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