Type  	info
Title 	New document events
Posted by 	mathias.bauer@sun.com
Affected 	,-
Effective from 	fwkfinal1


Summary


Two new document events are available now, their API names are "OnCreate" (for
new, empty documents) and "OnLoadFinished" (for documents loaded from a file or
stream). They are sent by every document, regardless if it is opened/created
with or without a view, hidden or visible.
OTOH the "old", well known events "OnNew" and "OnLoad" are sent only for visible
documents and they are sent not before the document has become visible.



Description

In OOo1.x  the "OnNew"/"OnLoad" events where sent asynchronously
(means: a user event was posted that on execution notified all listeners).

So if you open a document via API, modify it and then close it you get
the close event (because it must be sent synchronously) before the
open event (and BTW the document is already gone when you get this
event). We tried to fix this by sending the OnNew/OnLoad events
synchronously, but then they arrived at the listeners before the
document window was shown. Basic macros bound to those events now got
the wrong parent, dialogs asking for input became useless because you
can't see the underlying template etc., so we had to go back to
asychronous notification (the window manager doesn't allow to force a
window to appear on the screen immediately). The API problem can be
fixed only by introducing the new events and declaring the point in
time when the "OnNew/OnLoad" events arrive as undefined (and in case
of our API example they will not arrive at all!).

Any consumer of document events now must decide if it reacts on the
"old" events (that are sent out only for documents that are made
visible) or the "new" events (that are sent out for every created
document, even for hidden or embedded ones or for documents as data
source etc.).

As it looks no code has to be changed because the handling of the
OnNew/OnLoad events now is the same as in OOo1.1.