OpenOffice.org Forum at OOoForum.orgThe OpenOffice.org Forum
 
 [Home]   [FAQ]   [Search]   [Memberlist]   [Usergroups]   [Register
 [Profile]   [Log in to check your private messages]   [Log in

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

 
Post new topic   Reply to topic    OOoForum.org Forum Index -> OpenOffice.org Macros and API
View previous topic :: View next topic  
Author Message
JulianBuss
General User
General User


Joined: 20 Jul 2003
Posts: 8

PostPosted: Sun Jul 20, 2003 1:29 pm    Post subject: looking for an *understable* API reference... *sigh* Reply with quote

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 Smile

So, did I miss anything?
Back to top
View user's profile Send private message
DannyB
Moderator
Moderator


Joined: 02 Apr 2003
Posts: 3991
Location: Lawrence, Kansas, USA

PostPosted: Mon Jul 21, 2003 10:22 am    Post subject: Reply with quote

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?
Back to top
View user's profile Send private message
Guest






PostPosted: Thu Jul 24, 2003 1:51 am    Post subject: Reply with quote

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.

Quote:
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?


that's exactly the point. With my new knowledge, I understand much more of the reference, but it's fairly impractical.
Due to the fact that the reference is being created automatically. why not improve the generating script so that it lists all inherited properties and methods directly for every service? Perhaps marked in some way so that the user see's that these methods/properties are inherited.
That would make live much easier Smile

So slowly I think I can dive into the concepts and understand them and may be able to perform my trivial goal. But when I think about "standard programmers" who just have knowledge about VBA, I fear that the api reference alone is a insuperable hurdle...

Thanks again for your answer. Perhaps you can lead me the right way for my problem:
I have a OOo text document with some user fields in it. Via script I want to set these fields to certain values.

So I just need something like

myField = document.getFieldByName("companyname")
myField.value = "Acme Inc."

I've got the current document, but I cannot get an object for the field and donnow how to set the field to some value.
Back to top
bernardM
Guest





PostPosted: Fri Jul 25, 2003 3:17 am    Post subject: Reply with quote

Quote:
So I just need something like
myField = document.getFieldByName("companyname")
myField.value = "Acme Inc."
I've got the current document, but I cannot get an object for the field and donnow how to set the field to some value

Hi,
Look at API doc, following these links
first page (star) > document > DocumentInfo > XDocumentInfo

In each of these pages you have a wealth of links. In the final page you'll find several methods to read and set User fields.
If you are in a hurry :
http://api.openoffice.org/common/ref/com/sun/star/document/XDocumentInfo.html

Have fun...
Back to top
danad
Guest





PostPosted: Wed Aug 06, 2003 6:52 pm    Post subject: Reply with quote

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
Back to top
Display posts from previous:   
Post new topic   Reply to topic    OOoForum.org Forum Index -> OpenOffice.org Macros and API All times are GMT - 8 Hours
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001, 2005 phpBB Group