Draft document-rendering tiling API to be called from viewer apps

[Tor Lillqvist]

OK, so I did some design of how an API to render (tiles of) pages
would look like that could be used both on Android and iOS apps.

My first idea was to do it based on UNO. On Android the Java code
would then call the implementation in the "normal" nice way one from
Java code calls UNO services. For iOS, the iOS-specific code would
either also use the UNO as from C++ (i.e. from Objective-C++), or one
would write a thing layer in between, perhaps even with ObjC proxy
objects if one would want to get fancy.

Now I am having second thoughts, though, but still, a first, in
progress, draft API is in UNOIDL form is in touch/idl.

See those .idl files for plenty of comments. (Sorry, comments not yet
in the meta-syntax that our documentation-generating tools would
understand.) To see the corresponding Java API that is automatically
generated from that, one needs to run javap on the class files.

The command "javap -classpath
workdir/unxandr.pro/CustomTarget/touch/class
org.libreoffice.touch.Document org.libreoffice.touch.XDocument
org.libreoffice.touch.DocumentRenderCallback
org.libreoffice.touch.XDocumentRenderCallback" outputs:


public final class org.libreoffice.touch.Document extends java.lang.Object{
    public static org.libreoffice.touch.XDocument
create(com.sun.star.uno.XComponentContext, java.lang.String);
}

public interface org.libreoffice.touch.XDocument extends
com.sun.star.uno.XInterface{
    public static final com.sun.star.lib.uno.typeinfo.TypeInfo[] UNOTYPEINFO;
    public abstract int getnumberOfPages();
    public abstract void render(long, int,
org.libreoffice.touch.XDocumentRenderCallback, int, int, int, int)
  throws com.sun.star.lang.IllegalArgumentException;
}

public final class org.libreoffice.touch.DocumentRenderCallback
extends java.lang.Object{
    public static org.libreoffice.touch.XDocumentRenderCallback
create(com.sun.star.uno.XComponentContext);
}

public interface org.libreoffice.touch.XDocumentRenderCallback extends
com.sun.star.uno.XInterface{
    public static final com.sun.star.lib.uno.typeinfo.TypeInfo[] UNOTYPEINFO;
    public abstract boolean start(int, int);
    public abstract boolean progress(float);
}

But I'll move on to those second thoughts....

I already thought I was starting to like UNO! That was after having
seen how nice (relatively speaking) it is to use UNO from Java code
(as in the DocumentLoader test Android app).

Java's garbage collection inter-operates fully with the life-cycles of
underlying UNO objects written in C++, these get destructed when there
are no more references to them on the Java side (or on the C++ side),
when the proxy Java object is finalized prior to being garbage
collected. Or something like that.

Using UNO services is even nicer if the services are of the "new
style" as described by Stephan Bergmann in his "Shiny Happy" OOoCon
talk from 2004 http://www.openoffice.org/marketing/ooocon2004/presentations/friday/shinyhappyuno.pdf
, which ideas are right now (after 8 years) actually being implemented
more widely in the codebase.

Using UNO APIs from C++ is also (relatively) nice. And specifying APIs
in IDL *is* nice.

But, that's the *specification* and *use*. *Implementing* UNO services
in C++, especially if you don't want to just copy-paste existing code
as a start, and then modify,  without understanding what the parts you
don't touch is exactly doing, is still nightmarish with loads of
boilerplate-ish rubbish.

So now I am not so sure any more. Maybe after all I will just do a
JNI-friendly "C" API. That then internally of course uses UNO to
*call* the existing services in LO, and poke directly into their
implementations as needed. I don't feel like extending existing,
already "published" and thus fixed, APIs like XDevice, XRenderable
etc.

This means the life-cycle of objects accessed though this will
probably not be automated for Java clients, hmm.

Anyway, the end result will be an API for (your) Android Java GUI code
to call that will still be something fairly close to the above. So now
is the time to speak up if you see something obviously stupid, or have
lots of other ideas (which would be *good*, don't be modest!)

Cheers,
--tml