looking for an *understable* API reference... *sigh*

[JulianBuss]

Hi,

I try to code something trivial in OOo for some days now, I've looked in the Developer tutorial, in api.openoffice.org, in this forum, in a german forum and several other sites. I am a developer with long year experience in java, c, pascal, basic and whatever languages. And yes, I know what OOP is. I use OOP methods in my everyday work.

So: I just want to have a *readable* API reference. Just to answer questions like "I have an object from class X, what properties and methods are avaible" or "I want to create an instance of class Y, how to?"

I really like OOo, and I really appreciate the possiblity to program it in basic, java, python and so on... but I think, the lack of a simple-to-use reference is a really problem for every new developer.

And for the "refrence" on api.openoffice.org ... I simply do not understand it

So, did I miss anything?

[DannyB]

Please see a previous post I made here...

http://www.oooforum.org/forum/viewtopic.php?t=1114

The key concept, which my previous post discusses at more length, is this. The properties and methods of any given object (i.e. "service") are the UNION of the methods and properties of the services, the inherited services, the included services, and the inherited and included services of each included service. Got that?

Suppose service E inherits from A, and includes B and C. Service B includes J and K, and B inherits from L. Service C includes M and N, and inherits from O. Oh, and A inherits from D. (At this point, draw a diagram. It's not quite like the OO you are accustomed to.) So the entire set of properties and methods available at E are....
* Everything in A
* Everything in D (A inherits from D)
* Everything in B
* Everything in L (B inherits from L)
* Everything in J and K (B includes J and K)
* Everything in C
* Everything in O (C inherits from O)
* Everything in M and N (C includes M and N)
Now if service N included some other services, R and S, then every property and method of those would be available in E as well.

What makes it seem difficult to follow is that many services have an extremely trivial interface, often consisting of one or two methods or properties. For instance there is an interface for simply indexing through a collection. Now a collection, say an array, might offer random access, index access, enumeration access, name access, etc. But each of these types of access to the array might be through a different interface. You would see the docs for this hypothetical collection object, but no properties or methods defined for it. Just some services or interfaces that are inherited from and/or included.

This makes reading the auto-generated html api docs difficult. It's not like reading the javadocs for a java api. Instead of listing all the methods and properties directly, it only lists the direct methods and properties. Usually there are NO direct methods and properties. (In my example above, service E would have no direct methods, only those methods offered by the many services directly or indirectly offered by E.)

I would love to see a hyperlinked api document that was more direct. This service offers XIndexAccess interface, so why not show those methods directly in the docs for this service?

From a service, you always have to get to an interface to find methods. So finding methods on something is always at least one level of indirection away (an interface) or two levels away (another service that leads to an interface). But you can have to go through multiple levels of service to reach a usable interface.

It sure would be nice to have a single doc that says, for a Spreadsheet document, or a Drawing document, here are the many methods and properties available. But it is not. Once you have an object, you go on a scavenger hunt for the useful interfaces of that object. Once you find a method, that probably returns another object, you go to that object's definition and then repeat the scavenger hunt for something useful on that object.




Other useful info here....

http://www.pitonyak.org/AndrewMacro.sxw

And finally, see my sig. Not only Danny's Draw Power Tools, but Turtle Graphics tutorial. Also BouncingBalls in my Examples folder.
_________________
Want to make OOo Drawings like the colored flower design to the left?

[Guest]

Danny,

thanks for the comprehensive answer. In the meanwhile I've found a good tutorial from Sun, with which I understood much more of the concepts. You are right, it's different from the OO concepts I worked with yet.

[bernardM]

[danad]

Hi,

Get the lib DevGuide in EDV – Systeme Kienlein http://kienlein.com/pages/oo.html. It has a module Inspect with a Sub ObjInit.

It's a great tool for your questions about services, interfaces and properties.

Sorry my english!

danad