libreofficekit: add overview of tiled editing to README

Change-Id: Ie4e28f9315c9de2062d63c5eb5e9c7481c719cef

1 files changed, 48 insertions, 0 deletions

diff --git a/libreofficekit/README b/libreofficekit/README
index eb29106341bd..22693ceeaf1d 100644
--- a/libreofficekit/README
+++ b/libreofficekit/README
@@ -38,6 +38,54 @@ colourspace (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 is slower
+development iteration (slow uploading to the device, the need to link all
+object files into a single .so, etc).
+
 LibreOfficeKitGtk
 *****************