Hello Jürgen,
Juergen Schmidt escribió:
Hi Ariel,
thanks for your detailed report about the SDK examples. The problem is
that these examples are not really maintained and it seems that you are
one of the first users who really had taken a closer look into the
examples.
Anyway your infos are helpful to improve the examples and later on the
DevGuide. The DevGuide will be moved into the Wiki not the SDK. But
my idea is to provide all or most of the examples as NetBeans and Eclipse
projects as well. You have already started to convert some of the
examples into NetBeans projects. Are you interested to contribute your
examples back
I send to your personal mail a copy of this one with a zipped folder
containing:
NB Projects for $SDK_HOME/examples/DevelopersGuide
* the examples in FirstSteps
OOo_SDK_EXAMPLES/DevelopersGuide_examples/FirstSteps/FirstLoadComponent
OOo_SDK_EXAMPLES/DevelopersGuide_examples/FirstSteps/FirstUnoContact
OOo_SDK_EXAMPLES/DevelopersGuide_examples/FirstSteps/HelloTextTableShape
* the only example in $SDK_HOME/examples/DevelopersGuide/Text
OOo_SDK_EXAMPLES/DevelopersGuide_examples/Text
NB Projects for $SDK_HOME/examples/java=
* the only drawing example
OOo_SDK_EXAMPLES/Java_examples/Drawing_Documents/SDraw
* all the text document examples
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/BookmarkInsertion
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/GraphicsInserter
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/HardFormatting
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/StyleCreation
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/StyleInitialization
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/SWriter
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/TextDocumentStructure
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/TextReplace
OOo_SDK_EXAMPLES/Java_examples/Text_Documents/WriterSelectionDetector
* the embedded object example
OOo_SDK_EXAMPLES/Java_examples/UNO_Components/EmbeddedObject
Some examples have only little style changes, other were (completely)
re-written. Explaining the criteria I followed will be too long to
explain here, more logical would have been to send you a diff patch, but
my NB Projects were already created and full of notes, so that doing
it all over again would have taken me more time than it took me to clean
up me own notes (by the way, that's the reason of my [too] late answer).
A few examples:
* the purpose of the StyleInitialization was not very clear for me, it
has a text enumeration example that is not very clear, my guessing is
that it was intended to show how applying styles creates text portions,
so I stressed this.
* in most cases I tried to use OOo API instead of Java's one (for
example getting the temp dir is very simple in java but I used OOo API;
also converting a system path into an URL; even for checking if a file
exists I used OOo API instead of Java's).
* removed all what I thought that was wrong or not proper (but this was
only my opinion, and so debatable - herea diff patch would have been
more proper)
Nevertheless, I didn't change everything I disliked in the examples...
In only one case I changed completely the example:
examples/java/Text/WriterSelector.java uses getCurrentComponent(), and
quoting Andreas Schlüns once again: "Using of any API related to the
focus (getActiveFrame(), getCurrentComponent() etc) should be
suppressed", so I suppressed this and created a new example named
WriterSelectionDetector.
I send you this example although it is not completely finished, because
some things seen not to work as desired, not knowing if I'm missing
something or things simply do not work. For example: I insert different
objects to show every possible selection type, and when inserting an OOo
Math formula the shape does not resize, crashing in two times OOo while
a message "Adapt Objects..." was on the status bar. As this didn't work,
I insert a Java applet. In this case, the applet gets sometimes
activated, but sometimes not (maybe here I'm missing something: I
learned all this by my self - the embedding API "documentation" (sic.
"specification") is rather cryptic, and in the Dev's Guide there is
nothing said about it...).
and maybe provide a wiki page to explain it in more detail
+ references to the appropriate DevGuide articles.
here what do you have in mind? is there some kind of template to follow?
how deep should the explanation go? I mean, trying to explain the only
text example in $SDK_HOME/examples/DevelopersGuide/Text with its ca.
2000 lines of code, would be like writing the Text documents chap. in
the Dev's Guide once again ;-)
Concerning this last one, I changed the text view cursor example, which
is one of the introductory examples of the Text Documents chap. in the
Dev's Guide
http://api.openoffice.org/docs/DevelopersGuide/Text/Text.xhtml#1_1_2_Example_3A_Visible_Cursor_Position
Because when I created all the NB projects I didn't have in mind that
they may be committed, I did my changes without taking care of how would
they affect the code quoted in the text of the Dev's Guide; I mean, if
my changes are accepted and committed, they should reflect on the Dev's
Guide text (so that the reader can read the text, and then go to the
example and find the same). So should I take care in the future when
changing some code that is quoted in the Dev's Guide? should I send my
changes as a patch?
One last point concerning the Dev's Guide examples: now, before every
example there is a link to the source code in the SDK. How will it be
when the Dev's Guide is on the Wiki?
Just as an idea: it would be nice if the link points to a page where the
reader could get the "same" example in all language binding available
(as long as this is possible).
From my own experience and the questions I've received, this will be
very useful: although Java is one of the most popular programming
languages, it is not completely accessible for a beginner, and most
people using OOo Basic find the OOo Basic Guide (now on the Wiki) rather
"primitive" in some points, and have to jump in the Dev's Guide, which
may be rather "cryptic" from a beginner point of view. Here OOo Basic
version of the Dev's Guide examples may help.
Well, quite long mail, that's all for now.
Regards
Ariel
Ariel Constenla-Haile wrote:
Hello Marco, * ,
I took the above code from the TextDocuments.java example that comes
with the OO SDK
well, if you are starting studying OOo API, you must take care both of
the SDK and its examples, because they have some errors, some of them
quite serious and may make you waste a whole day thinking what you're
doing wrong, when it's the SDK that's wrong and not you.
All this will sure be fixed when the SDK is on the Wiki.
Concerning the TextDocuments.java, as I started (for my own
training/studying) to translate the SDK Java examples into C++, I
realize that it has some issues:
* the TextSectionExample() is supposed to show how to create
child-parent sections, and a linked one, but due to errors moving the
text cursor and selecting text ranges, the example ends up creating two
simple sections and a linked one
* the DrawPageExample() is quite old, so at the end it does not group
shapes (and by the way the commented code is wrong)
* the viewCursorExample() is, IMHO, a serious case:
starting with its ACTHUNG!:
viewCursorExample(); // makes changes to the current document,
// use with *care*
and all the rest, the example is a way to propagate a bad programming
practice.
This assertion is justified because of the way it access the document:
XDesktop.getCurrentComponent(), by reading a very hidden comment in
Dev's Guide 20. GUI
http://api.openoffice.org/docs/DevelopersGuide/GUI/GUI.xhtml#1_5_3_The_Toolkit_Service
"There are several ways to retrieve a frame. The easiest way to retrieve
a frame is to query the frame that has the focus: [...]
XDesktop.getCurrentFrame() [...] This should only be used for debugging
purposes. The method getCurrentFrame is based on the implementation of
the window handler of the operating system and you cannot be sure that
the returned frame is always the desired one on all supported platforms,
or that a valid frame is returned at all."
and as@ comment in
http://www.openoffice.org/issues/show_bug.cgi?id=84767
"Using of any API related to the focus (getActiveFrame(),
getCurrentComponent() etc) should be supressed. It works sometimes ...
but not always and even not on all platforms in the same way. Its always
better to make thinks more explicit. You can travel the frames
hierarchie .. analyzing controlls/models to find the right (in your
example forms) component - and it will work always."
So getting any reference using getCurrentComponent(), getCurrentFrame(),
getActiveFrame() is completely discouraged, and every example should
avoid to use this.
[Side comment: some hidden place in the Dev's Guide or an issue comments
is not the right place to state this warning to the developers, it
should at least be in the corresponding chapter in the Developer's
Guide:
http://api.openoffice.org/docs/DevelopersGuide/OfficeDev/OfficeDev.xhtml
seems to be the right place, because there is explained the use of
getActiveFrame(), getCurrentFrame() and getCurrentComponent() *BUT*
there is no explanation at all concerning the possible problems of using
the current implementation. Again: this will sure be fixed when the SDK
is on the Wiki]
Said so, you can find my version of TextDocuments.java as a NetBeans
Project in
http://www.ArielConstenlaHaile.com.ar/ooo/temp/TextDocuments_java.zip
I have corrected the text sections example (now there is a parent and a
child section), the view cursor example is completely re-writen, and in
the draw page example added two ways to group shapes.
--
Ariel Constenla-Haile
La Plata, Argentina
[EMAIL PROTECTED]
[EMAIL PROTECTED]
http://www.ArielConstenlaHaile.com.ar/ooo/
"Aus der Kriegsschule des Lebens
- Was mich nicht umbringt,
macht mich härter."
Nietzsche Götzendämmerung, Sprüche und Pfeile, 8.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
