Accessing Libraries from Basic
Library Container Properties in Basic
Currently, the library system is implemented using UNO interfaces, not as a UNO service. Therefore, the library system cannot be accessed by instantiating an UNO service. The library system has to be accessed directly from Basic using the built-in properties
BasicLibraries property refers to the Basic library container that belongs to the library container that the
BasicLibraries property is accessed. In an application-wide Basic module, the property
BasicLibraries accesses the application Basic library container and in a document Basic module, the property
BasicLibraries contains the document Basic library container. The same applies to the
Initially, most Basic libraries are not loaded. All the libraries in the application library container are known after starting OpenOffice.org, and all the library elements in a document are known when it is loaded, most of them are disabled until they are loaded explicitly. This mechanism saves time during the Basic initialization. When a Basic library is initialized, the source code modules are inserted into the Basic engine and compiled. If there are many libraries with big modules, it is tim consuming, especially if the libraries are not required.
The exception to this is that every library container contains a library named "Standard" that is always loaded. This library is used as a standard location for Basic programs and dialogs that do not need a complex structure. All other libraries have to be loaded explicitly. For example:
When Library1, Module1 looks like
Sub doSomething MsgBox "doSomething" End Sub
the following code in library Standard, Module1
Sub Main doSomething() End Sub
fails, unless the user loaded Library1 before using the Tools - Macro dialog. A runtime error "Property or method not found" occurs. To avoid this, load library Library1 before calling
Sub Main BasicLibraries.loadLibrary( "Library1" ) doSomething() End Sub
Accordingly in the dialog container, all the libraries besides the Standard library have to be loaded before the dialogs inside the library can be accessed. For example:
Sub Main ' If this line was missing the following code would fail DialogLibraries.loadLibrary( "Library1" ) ' Code to instantiate and display a dialog ' Details will be explained in a later chapter oDlg = createUnoDialog( DialogLibraries.Library1.Dialog1 ) oDlg.execute() End Sub
The code to instantiate and display the dialog is described in Programming Dialogs and Dialog Controls. The library representing
DialogLibraries.Library1.Dialog1 is only valid once
Library1 has been loaded.
DialogLibraries refer to the container that includes the Basic source accessing these properties. Therefore in a document module Basic the properties
DialogLibraries refer to the Basic and Dialog library container of the document. In most cases, libraries in the document have to be loaded. In other cases it might be necessary to access application-wide libraries from document Basic. This can be done using the GlobalScope property. The
GlobalScope property represents the root scope of the application Basic, therefore the application library containers can be accessed as properties of
Example module in a Document Basic in library Standard:
Sub Main ' This code loads Library1 of the ...' Document Basic library container BasicLibraries.loadLibrary( "Library1" ) ' This code loads Library1 of the ...' Document dialog library container DialogLibraries.loadLibrary( "Library1" ) ' This code loads Library1 of the ...' Application Basic library container GlobalScope.BasicLibraries.loadLibrary( "Library1" ) ' This code loads Library1 of the ...' Application dialog library container GlobalScope.DialogLibraries.loadLibrary( "Library1" ) ' This code displays the source code of the ...' Application Basic module Library1/Module1 MsgBox GlobalScope.BasicLibraries.Library1.Module1 End Sub
|Application library containers can be accessed from document-embedded Basic libraries using the GlobalScope property, for example, GlobalScope.BasicLibraries.Library1.|
Library Container API
DialogLibraries support com.sun.star.script.XLibraryContainer2 that inherits from com.sun.star.script.XLibraryContainer, which is a com.sun.star.container.XNameContainer. Basic developers do not require the location of the interface to use a method, but a basic understanding is helpful when looking up the methods in the API reference.
XLibraryContainer2 handles existing library links and the write protection for libraries. It is also used to rename libraries:
boolean isLibraryLink( [in] string Name) string getLibraryLinkURL( [in] string Name) boolean isLibraryReadOnly( [in] string Name) void setLibraryReadOnly( [in] string Name, [in] boolean bReadOnly) void renameLibrary( [in] string Name, [in] string NewName)
XLibraryContainer creates and removes libraries and library links. Furthermore, it can test if a library has been loaded or, if necessary, load it.
com::sun::star::script::XNameContainer createLibrary( [in] string Name) com::sun::star::script::XNameAccess createLibraryLink( [in] string Name, [in] string StorageURL, [in] boolean ReadOnly) void removeLibrary( [in] string Name) boolean isLibraryLoaded( [in] string Name) void loadLibrary( [in] string Name)
The methods of
XNameContainer access and manage the libraries in the container:
void insertByName( [in] string name, [in] any element) void removeByName( [in] string name) any getByName( [in] string name) void replaceByName( [in] string name, [in] any element) sequence < string > getElementNames() boolean hasByName( [in] string name) type getElementType() boolean hasElements()
These methods are accessed using the UNO API as described in OpenOffice.org Basic. Note however, these interfaces can only be used from OpenOffice.org Basic, not from other environments.
Libraries can be added to library containers in two different ways:
Creating a New Library
- Creating a new library is done using the
createLibrary()method. A library created with this method belongs to the library container where
createLibrary()has been called. The implementation of the library container is responsible for saving and loading this library. This functionality is not currently covered by the interfaces, therefore the implementation determines how and where this is done. The method
createLibrary()returns a standard com.sun.star.container.XNameContainer interface to access the library elements and modify the library.
- Initially, such a library is empty and new library elements are inserted. It is also possible to protect a library from changes using the
setLibraryReadOnly()method. In a read-only library, no elements can be inserted or removed, and the modules or dialogs inside cannot be modified in the BasicIDE. For additional information, see OpenOffice.org Basic IDE. Currently, the read-only status can only be changed through API.
Creating a Link to an Existing Library
- Creating a link to an existing library is accomplished using the method
StorageURLparameter describes the location where the library .xlb file is stored. For additional information about this topic, see the section on Library File Structure). A library link is only referenced by the library container and is not owned, therefore the library container is not responsible for the location to store the library. This is only described by the
ReadOnlyparameter sets the read-only status of the library link. This status is independent of the read-only status of the linked library. A linked library is only modified when the library and link to the library are not read only. For example, this mechanism provides read-only access to a library located on a network drive without forcing the library to be read-only, thus the library can be modified easily by an authorized person without changing its read-only status.
The following tables provides a brief overview about other methods supported by the library containers:
|Selected Methods of com.sun.star.script.XLibraryContainer2|
|renameLibrary()||Assigns a new name to a library. If the library was added to the library container as a link, only the link is renamed.|
|Selected Methods of com.sun.star.script.XLibraryContainer|
|Content on this page is licensed under the Public Documentation License (PDL).|