ooo-build r12624 - trunk/doc

[noelpwer svn gnome org]

Author: noelpwer
Date: Wed May 21 18:07:20 2008
New Revision: 12624
URL: http://svn.gnome.org/viewvc/ooo-build?rev=12624&view=rev

Log:
some note on how the BasicManager, document storage, Libraries and
Modules hang together


Added:
   trunk/doc/BasicLibraryModuleNotes.txt

Added: trunk/doc/BasicLibraryModuleNotes.txt
==============================================================================
--- (empty file)
+++ trunk/doc/BasicLibraryModuleNotes.txt	Wed May 21 18:07:20 2008
@@ -0,0 +1,117 @@
+
+ODF Document ( loaded ) e.g. via someone accessing the scripts from the BasicContainer
+
+sfx2/source/doc/objxtor.cxx
+  o SfxObjectShell::GetBasicContainer()
+   - where the ScriptLibraryContainer ( uno service ) is returned
+      - InitBasicManager_Impl() creates a new BasicManager ( for the document )
+  o lcl_getOrCreateLibraryContainer, does as the name says on the tin 
+basic
+    - it creates a new SfxScriptLibraryContainer service/instance via the new service uno service thingy 'DocumentScriptLibraryContainer::create( comphelper_getProcessComponentContext(), xStorageDoc )' note: passing the document as a paramater
+
+basic/source/uno/scriptcont.cxx
+  o SfxScriptLibraryContainer - is the Library container ( it's the "com.sun.star.script.ScriptLibraryContainer" service
+
+      XInitialization
+           ^
+           |
+      XStorageBasedLibraryContainer
+           ^
+           |
+      XLibraryContainerPassword
+           ^
+           |
+      XLibraryContainerExport
+           ^
+           |
+      XContainer
+           ^
+           |
+      XServiceInfo
+           ^
+           |
+LibraryContainerHelper ::utl::OEventListenerAdapter
+              ^        ^
+               \      /
+                \    /
+                 \  /
+                  \/
+         SfxLibraryContainer OldBasicPassword
+                        ^      ^
+                         \    /
+                          \  /
+                           \/
+               SfxScriptLibraryContainer
+
+basic/source/uno/namecont.cxx
+  o SfxLibraryContainer - is the common base class for dialog and script containers
+    - OMG this is a *nasty* class that involves a huge and scary initialisation stack.
+    - it has a maNameContainer member which is more or less a string -> XNameAccess map
+       + SfxLibraryContainer::initialize can call either initializeFromDocumentURL or initializeFromDocument depending on whether a string url or a XStorageBasedDocument instance is passed in. We only care about the latter.
+          + when this class is passed a document storage 'init' is called, which calls init_Impl. There is alot of generic code to deal with the library xml descriptions ( which it seems must to be the same for basic dialogs and  basic libraries ), 
+
+library information is read/parsed into a ::xmlscript::LibDescriptorArray
+
+see ( xmlscript/inc/xmlscript/xmllib_imexp.hxx )
+
+struct LibDescriptor
+{
+   ::rtl::OUString aName;
+   ::rtl::OUString aStorageURL;
+   sal_Bool bLink;
+   sal_Bool bReadOnly;
+   sal_Bool bPasswordProtected;
+   ::com::sun::star::uno::Sequence< ::rtl::OUString > aElementNames;
+   sal_Bool bPreload;
+};
+
+struct LibDescriptorArray
+{
+   LibDescriptor* mpLibs;
+   sal_Int32 mnLibCount;
+};
+
+      ignoring links ( which are presumably handled similary ) createLink is called which inturn calls script library specific processing  via the implCreateLibrary method ( basic/source/uno/scriptconf.cxx ) The dialog or script library ( XNameAccess ) implementation is returned, note: these are both derived from SfxLibrary. On load it seems actually no library is read[1], instead dummy entries are provided for each of the LibDescriptor entries. 
+
+[1] part of the init_impl method loops through the LibDescriptor entries and call( class SfxLibraryContainer::loadLibrary ) on any library required to be pre-loaded ( determined by and xml attribute ). The loadLibrary routine calls ( in the case of basic libraries )  SfxScriptLibraryContainer::importLibraryElement() ( scriptcont.cxx ) which does the xml parse of the Module file
+
+  o SfxScriptLibraryContainer::importLibraryElement
+   
+
+Quesion: Is this a good place to read/write a vba option :-/ I think it might, perhaps this is also a place to hook in some codename -> ( associated document object ) relationship without going into the document format itself. Perhaps though the basic manager itself might be better because otherwise we would be ( potentially ) supporting a vba option in the dialog _and_ library xml which doesn't make sense.
+
+
+XNameContainer XContainer cppu::BaseMutex cppu::OComponentHelper
+      |               |            |                  |
+      -------------------------------------------------
+                           |
+                       SfxLibrary ( basic/source/namecont.cxx )
+                           |
+                    SfxScriptLibrary ( basic/source/scriptcont.cxx )
+
+so once a library is loaded, it's source is stored in the maNameContainer of the SfxLibrary ( yes just to confuse things both the SfxLibrary and SfxLibraryContainer both has a same named member of the same type. To make things worse they are used al over the same source files. Of course it's not so confusing when you know what is what. Anyway the maNameContainer in both cases is NameContainer ( defined in namecont.hxx ) When you change the source in the IDE for example then replaceByName is called on the NameContainer, this in-turn fires an event to any listener(s). It just so happens that our friendly BaseMgr has such a listerer instance  for each library, and the elementReplaced/elementXXXX methods modify the core in memory classes. 
+
+
+how do the BasicManager and the ScriptLibraryContainer/ScriptLibrary classes co-operate.
+
+   On Document load
+   ================
+    If the document has Storage, normally the ScriptLibraryContainer is created first, and as we can see above initialisation of the ScriptLibraryContainer ( for a document ) reads in any basic scripts that are stored to the document. 
+
+   Post Document Load
+   ==================
+   Attempting to create a script will result in the library container getting created, if it already exists ( say for example with Libraries/Modules already loaded ) then new libraries/Modules are created in memory. The same classes ( e.g. SfxScriptLibrary ) are used to store the Library/Module relationship ( and copy of the source ) 
+
+  What are all these other classes for e.g. BasicManagerImpl, BasMgrContainerListenerImpl, BasicLibInfo, BasicLibs, BasicManager
+
+
+
+
+
+Excel/Import & Basic
+=====================
+
+svx/source/msfilter/svxmsbas.cxx ( etc. etc. ) - I might have some sketchy notes for this somewhere ( perhaps out of date though )
+
+
+