summaryrefslogtreecommitdiffstats
path: root/libreofficekit/README
diff options
context:
space:
mode:
Diffstat (limited to 'libreofficekit/README')
-rw-r--r--libreofficekit/README109
1 files changed, 109 insertions, 0 deletions
diff --git a/libreofficekit/README b/libreofficekit/README
new file mode 100644
index 000000000..d346770e0
--- /dev/null
+++ b/libreofficekit/README
@@ -0,0 +1,109 @@
+LibreOfficeKit
+**************
+
+LibreOfficeKit can be used for accessing LibreOffice functionality
+through C/C++, without any need to use UNO.
+
+For now it only offers document conversion (in addition to an experimental
+tiled rendering API).
+
+Integrating LOK into other software
+-----------------------------------
+
+LOK functionality can be accessed by including LibreOfficeKit.h[xx] in your
+program.
+
+LOK initialisation (lok_init) requires the inclusion of LibreOfficeKitInit.h in
+your program. If you use the C++ LibreOfficeKit.hxx header, it already includes
+LibreOfficeKitInit.h for you.
+
+(LibreOfficeKit.hxx is a simple and fully inlined C++ wrapper for the same
+functionality as in LibreOfficeKit.h.)
+
+An example program can be seen on:
+https://gitlab.com/ojwb/lloconv
+
+Tiled Rendering
+---------------
+
+To use LOK Tiled Rendering you will need the following before the LOK includes:
+#define LOK_USE_UNSTABLE_API
+
+(This must be define before ANY LOK header, i.e. including the Init header.)
+
+Currently only bitmap-buffer rendering is supported, with a 32-bit BGRA
+colorspace (further alternatives could feasibly be implemented as needed).
+Scanlines are ordered top-down (whereas LibreOffice will internally default
+to bottom-up).
+
+Tiled Editing
+-------------
+
+On top of the tiled rendering API, a set of new methods have been added to the
+lok::Document class to allow basic editing, too. Communication between the LOK
+client and LibreOffice is a two-way channel. The client can initiate an action
+by calling the above mentioned methods. The most important methods for the
+client -> LibreOffice communication are:
+
+- initializeForRendering(), expected to be called right after
+ lok::Office::documentLoad() returned a lok::Document*.
+- postKeyEvent(), expected to be called when the user provides input on the
+ (soft-)keyboard.
+- postMouseEvent(), expected to be called when the user generated a touch or
+ mouse event.
+
+In general, all coordinates are always in absolute twips (20th of a point, or:
+1" = 1440 twips). See lok::Document in LibreOfficeKit.hxx for a full list of
+methods and their documentation.
+
+The other way around (LibreOffice -> LOK client) is implemented using a
+callback. A LOK client can register a callback using the registerCallback()
+method. Whenever editing requires some action on the client side, a callback
+event is emitted. The callback types are described using the
+LibreOfficeKitCallbackType enumeration in LibreOfficeKitEnums.h, the callback
+function signature itself is provided by the LibreOfficeKitCallback typedef in
+LibreOfficeKitTypes.h. The most important callback types:
+
+- LOK_CALLBACK_INVALIDATE_TILES: drop all tiles cached on client-side that
+ intersect with the provided rectangle
+- LOK_CALLBACK_INVALIDATE_VISIBLE_CURSOR: need to set the position and/or the
+ size of the cursor
+- LOK_CALLBACK_TEXT_SELECTION: need to adjust the selection overlay provided
+ by the client as the set of rectangles describing the selection overlay
+ changed
+
+There are currently two known LOK clients supporting tiled editing:
+
+- gtktiledviewer (see below), which allows testing the LOK core implementation
+ on (desktop) Linux
+- (LibreOffice on) Android
+
+Core has next to no idea what is the LOK client, so for effective development,
+it's recommended that the core part is developed against gtktiledviewer, and
+once a feature works there, then implement the Android part, with its slower
+development iteration (slow uploading to the device, the need to link all
+object files into a single .so, etc).
+
+* Debugging with gdb and gtktiledviewer
+
+To run gtktiledviewer:
+
+ bin/run gtktiledviewer --lo-path=$PWD/instdir/program path/to/test.odt
+
+To receive all incoming events from core use G_MESSAGES_DEBUG=all
+
+ G_MESSAGES_DEBUG=all bin/run gtktiledviewer --lo-path=$PWD/instdir/program ../test.odt
+
+To debug with gdb:
+
+ export LO_TRACE='gdb --tui --args'
+
+before bin/run, this will run gtktiledviewer in the debugger instead.
+
+LibreOfficeKitGtk
+*****************
+
+Currently consists of only a very basic GTK+ document viewer widget.
+
+The widget uses g_info() instead of SAL_INFO(), use the 'G_MESSAGES_DEBUG=all'
+environment variable to display those messages.